Particle Enums: Use Consistently and Rename (#351)

* Particle Enums: Use Consistently and Rename

- rename: `m_qm` to `qm` because it is charge over mass, not its inverse
- rename AoS to use s-based description by default: `z`->`t`
- Rename `AddNParticles` parameter, since we add particles for fixed `s`
- Use enums consistently whe we access `.pos` arguments, instead of `0-2`

* Change pt, too

Co-authored-by: Chad Mitchell <[email protected]>

* Transforms: Clarify In and Out

* Fancy Alias for Fixed t

* Spaces

* ToFixedT: Use Name f-suffix as in ToFixedS

* More Spaces

* Docs: Mention s-based first

Mention s-based interpretation first, because its the most commonly
used throughout the code base.

* Comments

* Use New Alias Once More

* Coord Trafo: Use Aliases for Final Values

---------

Co-authored-by: Chad Mitchell <[email protected]>

Author: ax3l

docs/source/usage/python.rst

@@ -167,9 +167,9 @@ Particles
 
    This class stores particles, distributed over MPI ranks.
 
-   .. py:method:: add_n_particles(lev, x, y, z, px, py, pyz, qm, bchchg)
+   .. py:method:: add_n_particles(lev, x, y, t, px, py, pt, qm, bchchg)
 
-      Add new particles to the container
+      Add new particles to the container for fixed s.
 
       Note: This can only be used *after* the initialization (grids) have
             been created, meaning after the call to :py:meth:`ImpactX.init_grids`
@@ -178,10 +178,10 @@ Particles
       :param lev: mesh-refinement level
       :param x: positions in x
       :param y: positions in y
-      :param z: positions in z
+      :param t: positions as time-of-flight in c*t
       :param px: momentum in x
       :param py: momentum in y
-      :param pz: momentum in z
+      :param pt: momentum in t
       :param qm: charge over mass in 1/eV
       :param bchchg: total charge within a bunch in C
 

examples/cfchannel/analysis_cfchannel.py

@@ -23,7 +23,7 @@ def get_moments(beam):
     sigpx = moment(beam["momentum_x"], moment=2) ** 0.5
     sigy = moment(beam["position_y"], moment=2) ** 0.5
     sigpy = moment(beam["momentum_y"], moment=2) ** 0.5
-    sigt = moment(beam["position_ct"], moment=2) ** 0.5
+    sigt = moment(beam["position_t"], moment=2) ** 0.5
     sigpt = moment(beam["momentum_t"], moment=2) ** 0.5
 
     epstrms = beam.cov(ddof=0)
@@ -34,7 +34,7 @@ def get_moments(beam):
         sigy**2 * sigpy**2 - epstrms["position_y"]["momentum_y"] ** 2
     ) ** 0.5
     emittance_t = (
-        sigt**2 * sigpt**2 - epstrms["position_ct"]["momentum_t"] ** 2
+        sigt**2 * sigpt**2 - epstrms["position_t"]["momentum_t"] ** 2
     ) ** 0.5
 
     return (sigx, sigy, sigt, emittance_x, emittance_y, emittance_t)

examples/cfchannel/analysis_cfchannel_10nC.py

@@ -22,7 +22,7 @@ def get_moments(beam):
     sigpx = moment(beam["momentum_x"], moment=2) ** 0.5
     sigy = moment(beam["position_y"], moment=2) ** 0.5
     sigpy = moment(beam["momentum_y"], moment=2) ** 0.5
-    sigt = moment(beam["position_ct"], moment=2) ** 0.5
+    sigt = moment(beam["position_t"], moment=2) ** 0.5
     sigpt = moment(beam["momentum_t"], moment=2) ** 0.5
 
     epstrms = beam.cov(ddof=0)
@@ -33,7 +33,7 @@ def get_moments(beam):
         sigy**2 * sigpy**2 - epstrms["position_y"]["momentum_y"] ** 2
     ) ** 0.5
     emittance_t = (
-        sigt**2 * sigpt**2 - epstrms["position_ct"]["momentum_t"] ** 2
+        sigt**2 * sigpt**2 - epstrms["position_t"]["momentum_t"] ** 2
     ) ** 0.5
 
     return (sigx, sigy, sigt, emittance_x, emittance_y, emittance_t)

examples/chicane/analysis_chicane.py

@@ -22,7 +22,7 @@ def get_moments(beam):
     sigpx = moment(beam["momentum_x"], moment=2) ** 0.5
     sigy = moment(beam["position_y"], moment=2) ** 0.5
     sigpy = moment(beam["momentum_y"], moment=2) ** 0.5
-    sigt = moment(beam["position_ct"], moment=2) ** 0.5
+    sigt = moment(beam["position_t"], moment=2) ** 0.5
     sigpt = moment(beam["momentum_t"], moment=2) ** 0.5
 
     epstrms = beam.cov(ddof=0)
@@ -33,7 +33,7 @@ def get_moments(beam):
         sigy**2 * sigpy**2 - epstrms["position_y"]["momentum_y"] ** 2
     ) ** 0.5
     emittance_t = (
-        sigt**2 * sigpt**2 - epstrms["position_ct"]["momentum_t"] ** 2
+        sigt**2 * sigpt**2 - epstrms["position_t"]["momentum_t"] ** 2
     ) ** 0.5
 
     return (sigx, sigy, sigt, emittance_x, emittance_y, emittance_t)

examples/chicane/plot_chicane.py

@@ -28,7 +28,7 @@ def get_moments(beam):
     sigpx = moment(beam["momentum_x"], moment=2) ** 0.5
     sigy = moment(beam["position_y"], moment=2) ** 0.5
     sigpy = moment(beam["momentum_y"], moment=2) ** 0.5
-    sigt = moment(beam["position_ct"], moment=2) ** 0.5
+    sigt = moment(beam["position_t"], moment=2) ** 0.5
     sigpt = moment(beam["momentum_t"], moment=2) ** 0.5
 
     epstrms = beam.cov(ddof=0)
@@ -39,7 +39,7 @@ def get_moments(beam):
         sigy**2 * sigpy**2 - epstrms["position_y"]["momentum_y"] ** 2
     ) ** 0.5
     emittance_t = (
-        sigt**2 * sigpt**2 - epstrms["position_ct"]["momentum_t"] ** 2
+        sigt**2 * sigpt**2 - epstrms["position_t"]["momentum_t"] ** 2
     ) ** 0.5
 
     return (sigx, sigy, sigt, emittance_x, emittance_y, emittance_t)
@@ -178,7 +178,7 @@ def read_time_series(file_pattern):
     ax = axs[(0, ncol_ax)]
     beam_at_step = series.iterations[step].particles["beam"].to_df()
     ax.scatter(
-        beam_at_step.position_ct.multiply(millimeter),
+        beam_at_step.position_t.multiply(millimeter),
         beam_at_step.momentum_t.multiply(mrad),
         s=0.01,
     )
@@ -202,7 +202,7 @@ def read_time_series(file_pattern):
     ax = axs[(2, ncol_ax)]
     beam_at_step = series.iterations[step].particles["beam"].to_df()
     ax.scatter(
-        beam_at_step.position_ct.multiply(millimeter),
+        beam_at_step.position_t.multiply(millimeter),
         beam_at_step.position_x.multiply(millimeter),
         s=0.01,
     )
@@ -212,7 +212,7 @@ def read_time_series(file_pattern):
     ax = axs[(3, ncol_ax)]
     beam_at_step = series.iterations[step].particles["beam"].to_df()
     ax.scatter(
-        beam_at_step.position_ct.multiply(millimeter),
+        beam_at_step.position_t.multiply(millimeter),
         beam_at_step.momentum_x.multiply(mrad),
         s=0.01,
     )

examples/distgen/analysis_gaussian.py

@@ -22,7 +22,7 @@ def get_moments(beam):
     sigpx = moment(beam["momentum_x"], moment=2) ** 0.5
     sigy = moment(beam["position_y"], moment=2) ** 0.5
     sigpy = moment(beam["momentum_y"], moment=2) ** 0.5
-    sigt = moment(beam["position_ct"], moment=2) ** 0.5
+    sigt = moment(beam["position_t"], moment=2) ** 0.5
     sigpt = moment(beam["momentum_t"], moment=2) ** 0.5
 
     epstrms = beam.cov(ddof=0)
@@ -33,7 +33,7 @@ def get_moments(beam):
         sigy**2 * sigpy**2 - epstrms["position_y"]["momentum_y"] ** 2
     ) ** 0.5
     emittance_t = (
-        sigt**2 * sigpt**2 - epstrms["position_ct"]["momentum_t"] ** 2
+        sigt**2 * sigpt**2 - epstrms["position_t"]["momentum_t"] ** 2
     ) ** 0.5
 
     return (sigx, sigy, sigt, emittance_x, emittance_y, emittance_t)

examples/distgen/analysis_kurth4d.py

@@ -22,7 +22,7 @@ def get_moments(beam):
     sigpx = moment(beam["momentum_x"], moment=2) ** 0.5
     sigy = moment(beam["position_y"], moment=2) ** 0.5
     sigpy = moment(beam["momentum_y"], moment=2) ** 0.5
-    sigt = moment(beam["position_ct"], moment=2) ** 0.5
+    sigt = moment(beam["position_t"], moment=2) ** 0.5
     sigpt = moment(beam["momentum_t"], moment=2) ** 0.5
 
     epstrms = beam.cov(ddof=0)
@@ -33,7 +33,7 @@ def get_moments(beam):
         sigy**2 * sigpy**2 - epstrms["position_y"]["momentum_y"] ** 2
     ) ** 0.5
     emittance_t = (
-        sigt**2 * sigpt**2 - epstrms["position_ct"]["momentum_t"] ** 2
+        sigt**2 * sigpt**2 - epstrms["position_t"]["momentum_t"] ** 2
     ) ** 0.5
 
     return (sigx, sigy, sigt, emittance_x, emittance_y, emittance_t)

examples/distgen/analysis_kvdist.py

@@ -22,7 +22,7 @@ def get_moments(beam):
     sigpx = moment(beam["momentum_x"], moment=2) ** 0.5
     sigy = moment(beam["position_y"], moment=2) ** 0.5
     sigpy = moment(beam["momentum_y"], moment=2) ** 0.5
-    sigt = moment(beam["position_ct"], moment=2) ** 0.5
+    sigt = moment(beam["position_t"], moment=2) ** 0.5
     sigpt = moment(beam["momentum_t"], moment=2) ** 0.5
 
     epstrms = beam.cov(ddof=0)
@@ -33,7 +33,7 @@ def get_moments(beam):
         sigy**2 * sigpy**2 - epstrms["position_y"]["momentum_y"] ** 2
     ) ** 0.5
     emittance_t = (
-        sigt**2 * sigpt**2 - epstrms["position_ct"]["momentum_t"] ** 2
+        sigt**2 * sigpt**2 - epstrms["position_t"]["momentum_t"] ** 2
     ) ** 0.5
 
     return (sigx, sigy, sigt, emittance_x, emittance_y, emittance_t)

examples/distgen/analysis_semigaussian.py

@@ -22,7 +22,7 @@ def get_moments(beam):
     sigpx = moment(beam["momentum_x"], moment=2) ** 0.5
     sigy = moment(beam["position_y"], moment=2) ** 0.5
     sigpy = moment(beam["momentum_y"], moment=2) ** 0.5
-    sigt = moment(beam["position_ct"], moment=2) ** 0.5
+    sigt = moment(beam["position_t"], moment=2) ** 0.5
     sigpt = moment(beam["momentum_t"], moment=2) ** 0.5
 
     epstrms = beam.cov(ddof=0)
@@ -33,7 +33,7 @@ def get_moments(beam):
         sigy**2 * sigpy**2 - epstrms["position_y"]["momentum_y"] ** 2
     ) ** 0.5
     emittance_t = (
-        sigt**2 * sigpt**2 - epstrms["position_ct"]["momentum_t"] ** 2
+        sigt**2 * sigpt**2 - epstrms["position_t"]["momentum_t"] ** 2
     ) ** 0.5
 
     return (sigx, sigy, sigt, emittance_x, emittance_y, emittance_t)

examples/expanding_beam/analysis_expanding.py

@@ -22,7 +22,7 @@ def get_moments(beam):
     sigpx = moment(beam["momentum_x"], moment=2) ** 0.5
     sigy = moment(beam["position_y"], moment=2) ** 0.5
     sigpy = moment(beam["momentum_y"], moment=2) ** 0.5
-    sigt = moment(beam["position_ct"], moment=2) ** 0.5
+    sigt = moment(beam["position_t"], moment=2) ** 0.5
     sigpt = moment(beam["momentum_t"], moment=2) ** 0.5
 
     epstrms = beam.cov(ddof=0)
@@ -33,7 +33,7 @@ def get_moments(beam):
         sigy**2 * sigpy**2 - epstrms["position_y"]["momentum_y"] ** 2
     ) ** 0.5
     emittance_t = (
-        sigt**2 * sigpt**2 - epstrms["position_ct"]["momentum_t"] ** 2
+        sigt**2 * sigpt**2 - epstrms["position_t"]["momentum_t"] ** 2
     ) ** 0.5
 
     return (sigx, sigy, sigt, emittance_x, emittance_y, emittance_t)