Clarify that ReducedBeamCharacteristics are relative to reference particle (#585)

* Clarify the coordinates in the RBC

Make clear how the ReducedBeamCharacteristics quantities are in reference to
the reference particle.

* Apply suggestions from code review

Co-authored-by: Chad Mitchell <46825199+cemitch99@users.noreply.github.com>

* Apply suggestions from code review

Co-authored-by: SchroederSa <134732256+SchroederSa@users.noreply.github.com>

* Apply suggestions from code review

Co-authored-by: Chad Mitchell <46825199+cemitch99@users.noreply.github.com>

* Comment on beam monitor

---------

Co-authored-by: Chad Mitchell <46825199+cemitch99@users.noreply.github.com>
Co-authored-by: SchroederSa <134732256+SchroederSa@users.noreply.github.com>
Co-authored-by: Axel Huebl <axel.huebl@plasma.ninja>

Author: 4 people

docs/source/dataanalysis/dataanalysis.rst

@@ -58,8 +58,12 @@ Example to print the integrated orbit path length ``s`` at each beam monitor pos
 Reduced Beam Characteristics
 ----------------------------
 
-ImpactX calculates reduced beam characteristics like averaged positions, momenta, beam emittances and Courant-Snyder (Twiss) parameters during runtime.
-These quantities are calculated before, after, and during each step of the simulation.
+ImpactX calculates reduced beam characteristics based on the beam moments during runtime.
+These include averaged positions, momenta, beam emittances and Courant-Snyder (Twiss) parameters.
+For computing beam moments (as elsewhere), positions and momenta are given as deviations with respect to the reference particle (see :ref:`Coordinates and Units <theory-coordinates-and-units>`).
+
+The reduced beam characteristics are stored with the output of the beam monitor element.
+They are also calculated before, after, and during each step of the simulation.
 If ``diag.slice_step_diagnostics`` is enabled, they will also be calculated during each slice of each beamline element.
 
 The code writes out the values in an ASCII file prefixed ``reduced_beam_characteristics`` containing the follow columns:
@@ -69,13 +73,13 @@ The code writes out the values in an ASCII file prefixed ``reduced_beam_characte
 * ``s``, ``ref_beta_gamma``
     Reference particle coordinate ``s`` (unit: meter) and relativistic momentum normalized by the particle mass and the speed of light (unit: dimensionless)
 * ``x_mean/min/max``, ``y_mean/min/max``, ``t_mean/min/max``
-    Average / minimum / maximum beam particle position in the dimensions of ``x``, ``y`` (transverse coordinates, unit: meter), and ``t`` (normalized time difference :math:`ct`, unit: meter)
+    Average / minimum / maximum particle displacement with respect to the reference particle in the dimensions of ``x``, ``y`` (transverse coordinates, unit: meter), and ``t`` (normalized time difference :math:`ct`, unit: meter)
 * ``sig_x``, ``sig_y``, ``sig_t``
     RMS of the average beam particle positions (unit: meter)
 * ``px_mean/min/max``, ``py_mean/min/max``, ``pt_mean/min/max``
-    Average / minimum / maximum beam momenta normalized by reference particle momentum (unit: dimensionless, radians for transverse momenta)
+    Average / minimum / maximum particle momentum deviation from the reference particle momentum, divided by the magnitude of the reference particle momentum (unit: dimensionless, radians for transverse momenta)
 * ``sig_px``, ``sig_py``, ``sig_pt``
-    RMS of the average beam momenta (energy difference for ``pt``) (unit: dimensionless)
+    Standard deviation of the particle momentum deviations (energy difference for ``pt``) normalized by the magnitude of the reference particle momentum (unit: dimensionless)
 * ``emittance_x``, ``emittance_y``, ``emittance_t``
     Normalized beam emittance (unit: meter)
 * ``alpha_x``, ``alpha_y``, ``alpha_t``

docs/source/theory/intro.rst

@@ -38,6 +38,7 @@ One can set the number of slice steps through each lattice element for the appli
    Currently, space charge kicks are calculated in 3D.
    A 2D space-charge solver for purely transversal effects will be added in the future.
 
+.. _theory-coordinates-and-units:
 
 Coordinates and Units
 ---------------------