Merge pull request #1 from reichherzerp/doc_observer

Update observer documentation & code

doc/pages/Cpp-projects.md

@@ -23,7 +23,7 @@ int main(void) {
         sim.add(new MinimumEnergy(1*EeV));
 
         ref_ptr<Observer> obs = new Observer();
-        obs->add(new ObserverPoint());
+        obs->add(new Observer1D());
         obs->onDetection(new TextOutput("events.txt", Output::Event1D));
         obs->onDetection(new TextOutput());
         sim.add(obs);

doc/pages/Simulation-Modules.md

@@ -53,24 +53,22 @@ Periodic- and ReflectiveBox implement boundary conditions for the particles. The
 * **CylindricalBoundary** - Cylindric simulation volume
 * **PeriodicBox** - Periodic boundary conditions for the particle: If a particle leaves the box it will enter from the opposite side and the initial position will be changed as if it had come from that side.
 * **ReflectiveBox** - Reflective boundary conditions for the particle: If a particle leaves the box it will be reflected (mirrored) and the initial position will be changed as if it had come from that side.
-* **DetectionLength** - Detects the candidate at a given trajectory length. 
+* **DetectionLength** - Detects the candidate at a given trajectory length.
 
 ### Observers
 Observers can be defined using a collection of ObserverFeatures.
 The names of ObserverFeatures all start with "Observer" so you can discover the available options from an interactive python session by typing "Observer" and pressing "tab". The list includes
-* **ObserverSurface** - Detects particles crossing the boundaries of a surface defined (see, e.g., `Geometry` module)
-* **ObserverSmallSphere** - Detects particle when they enter the sphere
-* **ObserverLargeSphere** - Detects particles when they leave the sphere
-* **ObserverTracking** - For recording the tracks of particles inside a small observer sphere
-* **ObserverPoint** - Observer for 1D simulations
+* **ObserverSurface** - Detects particles crossing the boundaries of a defined surface (see, e.g., `Geometry` module)
+* **ObserverTracking** - For recording the tracks of particles inside an observer sphere
+* **Observer1D** - Observer for 1D simulations that detects particles when reaching x = 0
 * **ObserverDetectAll** - Detects all particles
-* **ObserverRedshiftWindow** - Detect particles within a given redshift interval around z=0
+* **ObserverRedshiftWindow** - Detect particles within a given redshift interval
 * **ObserverInactiveVeto** - Veto for inactive particles
 * **ObserverPhotonVeto** - Veto for photons
 * **ObserverElectronVeto** - Veto for electrons/positrons
 * **ObserverNeutrinoVeto** - Veto for neutrinos
 * **ObserverNucleusVeto** - Veto for protons/neutrons and nuclei
-* **ObserverTimeEvolution** - Records all candidates at a series of equidistant trajectory length intervals.
+* **ObserverTimeEvolution** - Records all candidates along their trajectory using linear or logarithmic steps
 
 ### Output modules
 Main output modules

doc/pages/example_notebooks/extragalactic_fields/MHD_models.v4.ipynb

@@ -285,7 +285,7 @@
     "\n",
     "## initialize observer that registers particles that enter into sphere of given size around its position\n",
     "obs = Observer()\n",
-    "obs.add( ObserverSmallSphere( obsPosition, obsSize ) )\n",
+    "obs.add( ObserverSurface( Sphere( obsPosition, obsSize ) ) )\n",
     "## write registered particles to output file\n",
     "obs.onDetection( TextOutput( filename_output ) )\n",
     "## choose to not further follow particles paths once detected\n",

include/crpropa/module/Observer.h

@@ -50,22 +50,22 @@ class Observer: public Module {
 	bool clone;
 	bool makeInactive;
 public:
-	/** Default observer constructor.
+	/** Default observer constructor
 	 */
 	Observer();
-	/** Add a feature to the observer.
-	 @param feature		observer feature to be add to the Observer object
+	/** Add a feature to the observer
+	 @param feature		observer feature to be added to the Observer object
 	 */
 	void add(ObserverFeature *feature);
 	/** Perform some specific actions upon detection of candidate
 	 @param action		module that performs a given action when candidate is detected
-	 @param clone		if true, clone candidate 
+	 @param clone		if true, clone candidate
 	 */
 	void onDetection(Module *action, bool clone = false);
 	void process(Candidate *candidate) const;
 	std::string getDescription() const;
 	void setFlag(std::string key, std::string value);
-	/** Determine whether candidate should be deactivated on detection.
+	/** Determine whether candidate should be deactivated on detection
 	 @param deactivate	if true, deactivate detected particles; if false, continue tracking them
 	 */
 	void setDeactivateOnDetection(bool deactivate);
@@ -85,7 +85,7 @@ class ObserverDetectAll: public ObserverFeature {
 
 /**
  @class ObserverSurface
- @brief Detects particles crossing a given surface
+ @brief Detects particles crossing the boundaries of a defined surface (see, e.g., `Geometry` module)
  */
 class ObserverSurface: public ObserverFeature {
 private:
@@ -100,27 +100,6 @@ class ObserverSurface: public ObserverFeature {
 };
 
 
-/**
- @class ObserverSmallSphere
- @brief Detects particles that enter a sphere from the outside to the inside
- */
-class ObserverSmallSphere: public ObserverFeature {
-private:
-	Vector3d center;
-	double radius;
-public:
-	/** Constructor
-	 @param center		vector containing the coordinates of the center of the sphere
-	 @param radius		radius of the sphere
-	 */
-	ObserverSmallSphere(Vector3d center = Vector3d(0.), double radius = 0);
-	DetectionState checkDetection(Candidate *candidate) const;
-	void setCenter(const Vector3d &center);
-	void setRadius(float radius);
-	std::string getDescription() const;
-};
-
-
 /**
  @class ObserverTracking
  @brief Tracks particles inside a sphere
@@ -143,32 +122,25 @@ class ObserverTracking: public ObserverFeature {
 
 
 /**
- @class ObserverLargeSphere
- @brief Detects particles that exit a sphere from the inside to the outside
+ @class ObserverPoint
+ @brief Detects particles when reaching x = 0
+
+Should be removed and replaced by Observer1D
  */
-class ObserverLargeSphere: public ObserverFeature {
-private:
-	Vector3d center;
-	double radius;
+class ObserverPoint: public ObserverFeature {
 public:
-	/** Constructor
-	 @param center		vector containing the coordinates of the center of the sphere
-	 @param radius		radius of the sphere
-	 */
-	ObserverLargeSphere(Vector3d center = Vector3d(0.), double radius = 0);
 	DetectionState checkDetection(Candidate *candidate) const;
 	std::string getDescription() const;
 };
 
 
 /**
- @class ObserverPoint
+ @class Observer1D
  @brief Detects particles when reaching x = 0
 
- This module limits the next step size to prevent candidates from overshooting.
- Should be renamed to Observer1D, once old observer-scheme is removed.
+ This module detects particles when reaching x = 0 and also limits the next step size to prevent candidates from overshooting.
  */
-class ObserverPoint: public ObserverFeature {
+class Observer1D: public ObserverFeature {
 public:
 	DetectionState checkDetection(Candidate *candidate) const;
 	std::string getDescription() const;
@@ -180,7 +152,7 @@ class ObserverPoint: public ObserverFeature {
  @brief Detects particles in a given redshift window
 
  When added to an observer, this feature generalizes it to four dimensions.
- The fourth dimension is the redshift, a proxy for time. This is particularly 
+ The fourth dimension is the redshift, a proxy for time. This is particularly
  useful in "4D" studies, including either time-dependence (e.g. flaring objects),
  or in 3D studies including cosmological evolution.
  Note that redshifts should be assigned to sources when using this feature.
@@ -258,7 +230,7 @@ class ObserverElectronVeto: public ObserverFeature {
 
 /**
  @class ObserverParticleIdVeto
- @brief Custom veto for user-defined particle types.
+ @brief Custom veto for user-defined particle types
  Vetoes for more than one type of particle can be added by calling this
  feature multiple times.
  */
@@ -299,12 +271,12 @@ class ObserverTimeEvolution: public ObserverFeature {
 	 @param max	    maximum time
 	 @param numb	number of time intervals
 	 @param log     log (input: true) or lin (input: false) scaling between min and max with numb steps
-	 @param 
+	 @param
 	 */
 	ObserverTimeEvolution(double min, double max, double numb, bool log);
-	// add a new time step to the detection time list of the observer
+	// Add a new time step to the detection time list of the observer
 	void addTime(const double &position);
-	// using log or lin spacing of times in the range between min and
+	// Using log or lin spacing of times in the range between min and
 	// max for observing particles
 	void addTimeRange(double min, double max, double numb, bool log = false);
 	const std::vector<double>& getTimes() const;

src/module/Observer.cpp

@@ -98,50 +98,6 @@ std::string ObserverDetectAll::getDescription() const {
 	return description;
 }
 
-// ObserverSmallSphere --------------------------------------------------------
-ObserverSmallSphere::ObserverSmallSphere(Vector3d center, double radius) :
-		center(center), radius(radius) {
-			KISS_LOG_WARNING << "ObserverSmallSphere deprecated and will be removed in the future. Replace with ObserverSurface( Sphere(center, radius)).";
-}
-
-DetectionState ObserverSmallSphere::checkDetection(Candidate *candidate) const {
-	// current distance to observer sphere center
-	double d = (candidate->current.getPosition() - center).getR();
-
-	// conservatively limit next step to prevent overshooting
-	candidate->limitNextStep(sqrt(fabs(d*d - radius*radius)));
-
-	// no detection if outside of observer sphere
-	if (d > radius)
-		return NOTHING;
-
-	// previous distance to observer sphere center
-	double dprev = (candidate->previous.getPosition() - center).getR();
-
-	// if particle was inside of sphere in previous step it has already been detected
-	if (dprev <= radius)
-		return NOTHING;
-
-	// else detection
-	return DETECTED;
-}
-
-void ObserverSmallSphere::setCenter(const Vector3d &center) {
-	this->center = center;
-}
-
-void ObserverSmallSphere::setRadius(float radius) {
-	this->radius = radius;
-}
-
-std::string ObserverSmallSphere::getDescription() const {
-	std::stringstream ss;
-	ss << "ObserverSmallSphere: ";
-	ss << "center = " << center / Mpc << " Mpc, ";
-	ss << "radius = " << radius / Mpc << " Mpc";
-	return ss.str();
-}
-
 // ObserverTracking --------------------------------------------------------
 ObserverTracking::ObserverTracking(Vector3d center, double radius, double stepSize) :
 		center(center), radius(radius), stepSize(stepSize) {
@@ -177,54 +133,37 @@ std::string ObserverTracking::getDescription() const {
 	return ss.str();
 }
 
-// ObserverLargeSphere --------------------------------------------------------
-ObserverLargeSphere::ObserverLargeSphere(Vector3d center, double radius) :
-		center(center), radius(radius) {
-		KISS_LOG_WARNING << "ObserverLargeSphere deprecated and will be removed in the future. Replace with ObserverSurface( Sphere(center, radius) ).";
-}
-
-DetectionState ObserverLargeSphere::checkDetection(Candidate *candidate) const {
-	// current distance to observer sphere center
-	double d = (candidate->current.getPosition() - center).getR();
-
-	// conservatively limit next step size to prevent overshooting
-	candidate->limitNextStep(fabs(radius - d));
-
-	// no detection if inside observer sphere
-	if (d < radius)
-		return NOTHING;
-
-	// previous distance to observer sphere center
-	double dprev = (candidate->previous.getPosition() - center).getR();
-
-	// if particle was outside of sphere in previous step it has already been detected
-	if (dprev >= radius)
+// ObserverPoint --------------------------------------------------------------
+DetectionState ObserverPoint::checkDetection(Candidate *candidate) const {
+	KISS_LOG_WARNING << "ObserverPoint is deprecated and is no longer supported. Please use Observer1D instead.\n";
+	double x = candidate->current.getPosition().x;
+	if (x > 0) {
+		// Limits the next step size to prevent candidates from overshooting in case of non-detection
+		candidate->limitNextStep(x);
 		return NOTHING;
-
-	// else: detection
+	}
+	// Detects particles when reaching x = 0
 	return DETECTED;
 }
 
-std::string ObserverLargeSphere::getDescription() const {
-	std::stringstream ss;
-	ss << "ObserverLargeSphere: ";
-	ss << "center = " << center / Mpc << " Mpc, ";
-	ss << "radius = " << radius / Mpc << " Mpc";
-	return ss.str();
+std::string ObserverPoint::getDescription() const {
+	return "ObserverPoint: observer at x = 0";
 }
 
-// ObserverPoint --------------------------------------------------------------
-DetectionState ObserverPoint::checkDetection(Candidate *candidate) const {
+// Observer1D --------------------------------------------------------------
+DetectionState Observer1D::checkDetection(Candidate *candidate) const {
 	double x = candidate->current.getPosition().x;
 	if (x > 0) {
+		// Limits the next step size to prevent candidates from overshooting in case of non-detection
 		candidate->limitNextStep(x);
 		return NOTHING;
 	}
+	// Detects particles when reaching x = 0
 	return DETECTED;
 }
 
-std::string ObserverPoint::getDescription() const {
-	return "ObserverPoint: observer at x = 0";
+std::string Observer1D::getDescription() const {
+	return "Observer1D: observer at x = 0";
 }
 
 // ObserverRedshiftWindow -----------------------------------------------------
@@ -358,7 +297,7 @@ DetectionState ObserverTimeEvolution::checkDetection(Candidate *c) const {
 		// Calculate the distance to next detection
 		double distance = length - detList[index];
 
-		// Limit next Step and detect candidate
+		// Limit next step and detect candidate.
 		// Increase the index by one in case of detection
 		if (distance < 0.) {
 			c->limitNextStep(-distance);

test/testBreakCondition.cpp

@@ -205,7 +205,7 @@ TEST(ObserverFeature, LargeSphere) {
 
 TEST(ObserverFeature, Point) {
 	Observer obs;
-	obs.add(new ObserverPoint());
+	obs.add(new Observer1D());
 	Candidate c;
 	c.setNextStep(10);
 

test/testOutput.cpp

@@ -229,7 +229,7 @@ TEST(ParticleCollector, getTrajectory) {
 	sim->add(new SimplePropagation(1, 1));
 
 	ref_ptr<Observer> obs = new Observer();
-	obs->add(new ObserverPoint());
+	obs->add(new Observer1D());
 	obs->onDetection(output);
 	sim->add(obs);
 

test/testSimulationExecution.py

@@ -42,7 +42,7 @@ def runTest(self):
 
         # observer
         obs = crp.Observer()
-        obs.add(crp.ObserverPoint())
+        obs.add(crp.Observer1D())
         sim.add(obs)
 
         # output