7  Conventions

OPALX uses metres, seconds, and SI electromagnetic-field units, while energy, mass, and normalized momentum follow the conventions below.

7.1 Physical units

Quantity Input convention
Length \(\mathrm{m}\)
Angle \(\mathrm{rad}\)
Time \(\mathrm{s}\) unless an attribute states otherwise
QUADRUPOLE.K1, K1S, DK1, DK1S \(\mathrm{m^{-2}}\)
Normalized MULTIPOLE.KN and KS coefficient, \(2n\) poles \(\mathrm{m^{-n}}\)
Physical MULTIPOLET.TP coefficient, \(2n\) poles \(\mathrm{T\,m^{-n+1}}\)
Electric voltage \(\mathrm{MV}\)
Electric field strength \(\mathrm{MV\,m^{-1}}\)
Magnetic field strength \(\mathrm{T}\) in current OPALX field output
Frequency \(\mathrm{MHz}\)
Charged-particle BEAM.ENERGY \(\mathrm{GeV}\)
Photon BEAM.ENERGY \(\mathrm{GeV}\); photon transport is unavailable
Particle mass \(\mathrm{GeV\,c^{-2}}\) in BEAM.MASS
Normalized momentum \(\widetilde p=p/(mc)=\beta\gamma\), dimensionless
Beam current \(\mathrm{A}\)
Particle charge elementary-charge units
Normalized and geometric emittance \(\mathrm{m\,rad}\)

The analytic LASER definition uses WAVELENGTH, WAISTX, and WAISTY in meters, PULSEENERGY in joules, and PULSELENGTH in seconds. DIR and STOKES are dimensionless three-vectors.

7.2 Symbols

Symbol Definition
\(X\), \(Y\) Ellipse axes in the transverse plane; \(X=Y=R\) for a circular beam.
\(R\) Circular beam radius.
\(R^*\) Effective elliptical radius, \((X+Y)/2\).
\(\sigma_x\), \(\sigma_y\), \(\sigma_z\) RMS beam sizes in the respective coordinates.
\(\sigma_r\) Circular-beam RMS radius, \(\langle r^2\rangle^{1/2}\).
\(\beta\), \(\gamma\) Relativistic velocity and Lorentz factors.
\(p_0\) Reference momentum. Input files commonly expose it as P0.
\(I\) Beam current.
\(I_0\) Species-dependent Alfvén current.
\(k_p\) Generalized beam perveance.
\(q\), \(m\) Particle charge and mass.

Coordinate frames and transformations are defined in the Physics coordinate-system chapter.

7.3 Bunch moments and RMS emittance

The definitions below apply to the main bunch-statistics (.stat) output. Statistics are calculated separately for each particle container, using the particles currently in that container across all MPI ranks. Each macroparticle contributes equally: the averages do not use particle charge or weight. Particles already removed from the container do not contribute.

7.3.1 Coordinates and normalized momentum

Write the stored phase-space vector as

\[ \mathbf w=(x,\widetilde p_x,y,\widetilde p_y,z,\widetilde p_z), \qquad \widetilde{\mathbf p}=\frac{\mathbf p}{mc}=\gamma\boldsymbol\beta, \qquad \gamma=\sqrt{1+|\widetilde{\mathbf p}|^2}. \]

Here \(\mathbf p=\gamma m\mathbf v\) is mechanical (kinetic) momentum. Throughout the OPALX documentation, normalized momentum means the dimensionless quantity \(\widetilde{\mathbf p}=\mathbf p/(mc)\) defined above.

Canonical momentum is a different quantity. In SI units,

\[ \mathbf p_{\mathrm{can}}=\mathbf p+q\mathbf A, \]

where \(q\) is the physical particle charge in coulombs and \(\mathbf A\) is the magnetic vector potential. OPALX’s PX, PY, and PZ correspond to \(\widetilde p_x=\gamma\beta_x\), \(\widetilde p_y=\gamma\beta_y\), and \(\widetilde p_z=\gamma\beta_z\), without a vector-potential term.

Positions are in metres and normalized momentum components are dimensionless. In particular, \(\widetilde p_x\) and \(\widetilde p_y\) are momentum components; the corresponding trajectory slopes are \(\widetilde p_x/\widetilde p_z\) and \(\widetilde p_y/\widetilde p_z\) when \(\widetilde p_z\ne0\).

Bunch moments use the container’s moving reference coordinate system at the output time. Its longitudinal axis follows the reference-particle momentum. The transformation translates positions and rotates momenta; it does not Lorentz-boost the particles into their rest frame. For a rigid transformation \(\mathbf r'=Q(\mathbf r-\mathbf a)\), \(\widetilde{\mathbf p}'=Q\widetilde{\mathbf p}\), the centered vectors obey \(\Delta\mathbf r'=Q\Delta\mathbf r\) and \(\Delta\widetilde{\mathbf p}'=Q\Delta\widetilde{\mathbf p}\). Thus the covariance transforms as \(C'=TCT^{\mathsf T}\), where \(T\) applies \(Q\) to the position and momentum components in the ordering above. Projected emittances can change when the axes mix different planes.

The suffix s in mean_s, rms_s, rms_ps, and emit_s denotes the local longitudinal coordinate \(z\). The separate .stat column s is the accumulated reference path length, not a particle coordinate.

7.3.2 Averages, spreads, and correlations

For a nonempty container with \(N\) macroparticles, define

\[ \langle a\rangle=\frac{1}{N}\sum_{k=1}^{N}a_k, \qquad \Delta a_k=a_k-\langle a\rangle, \qquad C_{ab}=\frac{1}{N}\sum_{k=1}^{N}\Delta a_k\Delta b_k. \]

These are population moments with denominator \(N\), without an \(N-1\) sample correction. The reported RMS sizes and momentum spreads are centered standard deviations,

\[ \sigma_{r_i}=\sqrt{C_{r_ir_i}}, \qquad \sigma_{\widetilde p_i}=\sqrt{C_{\widetilde p_i\widetilde p_i}}. \]

For example, rms_px is the spread about \(\langle \widetilde p_x\rangle\), rather than \(\sqrt{\langle \widetilde p_x^2\rangle}\). The correlation columns contain

\[ \rho_i=\frac{C_{r_i\widetilde p_i}}{\sigma_{r_i}\sigma_{\widetilde p_i}}. \]

The correlation is undefined if either spread is zero; the current output calculation does not guard this division, so such entries can be non-finite. For an empty container, the writer outputs zero for the means, RMS spreads, correlations, and emittances listed below.

7.3.3 Projected normalized and geometric emittance

The reported RMS emittances are calculated from positions and the normalized mechanical momentum components \(\widetilde p_i=p_i/(mc)\) defined above. For \(i\in\{x,y,z\}\), the projected normalized RMS emittance is

\[ \varepsilon_{n,i}=\sqrt{\max\!\left( C_{r_ir_i}C_{\widetilde p_i\widetilde p_i}-C_{r_i\widetilde p_i}^{\,2},\,0\right)}. \]

The nonnegative clamp prevents a negative square-root argument from roundoff. This is an RMS emittance with no additional factor of \(\pi\). It includes the full distribution in the container, without a dispersion subtraction or a percentile cut. It is a two-dimensional projection; it does not measure the coupled eigenemittances of the full six-dimensional covariance matrix. The longitudinal value uses \((z,\widetilde p_z)\), rather than a time–energy pair.

The internal geometric-emittance conversion is

\[ \overline\gamma=\frac1N\sum_{k=1}^{N}\sqrt{1+|\widetilde{\mathbf p}_k|^2}, \qquad \varepsilon_{g,i}=\frac{\varepsilon_{n,i}}{\sqrt{\overline\gamma^2-1}}. \]

The same denominator is used for all three planes. It is obtained from the mean particle Lorentz factor, not the reference particle or the magnitude of the mean momentum. This conversion requires \(\sqrt{\overline\gamma^2-1}>0\); it is not a direct covariance calculation using particle slopes. For broad momentum distributions, distinguish this convention from an emittance calculated directly from \((x,\widetilde p_x/\widetilde p_z)\) or \((y,\widetilde p_y/\widetilde p_z)\). The main .stat file writes the normalized emittances, not these geometric values.

Both are conventionally quoted in \(\mathrm{m\,rad}\), with radians dimensionless; the .stat header labels emit_* with unit m. Multiply a value in metres by \(10^6\) to express it in \(\mathrm{mm\,mrad}\).

7.3.4 Rest-frame temperatures

The temperature columns are the only .stat quantities evaluated in the rest frame of the bunch. OPALX Lorentz-boosts every macroparticle momentum into the centre-of-momentum frame of the container, in which the mean momentum vanishes:

\[ \boldsymbol\beta_c=\frac{\langle\widetilde{\mathbf p}\rangle}{\langle\gamma\rangle}, \qquad \gamma_c=\frac{1}{\sqrt{1-|\boldsymbol\beta_c|^2}}, \]

\[ \widetilde{\mathbf p}'_k=\Delta\widetilde{\mathbf p}_k +\left[\frac{\gamma_c^2}{\gamma_c+1}\,\boldsymbol\beta_c\cdot\Delta\widetilde{\mathbf p}_k -\gamma_c\,\Delta\gamma_k\right]\boldsymbol\beta_c, \qquad \gamma'_k=\sqrt{1+|\widetilde{\mathbf p}'_k|^2}, \]

with \(\Delta\gamma_k=\gamma_k-\langle\gamma\rangle\). This is the exact transformation, not an expansion in the momentum spread. The temperature along each axis is

\[ k_BT_i=mc^2\left\langle\frac{\widetilde p_{k,i}'^{\,2}}{\gamma'_k}\right\rangle, \qquad i=x,y,z, \]

written in kelvin as temperature_x, temperature_y, and temperature_s. The mass \(m\) is the rest mass of the container’s particle species, not the macroparticle mass, and the axes are the reference axes described above.

\(k_BT_i\) is the diagonal of the kinetic pressure tensor per particle in the rest frame. For a relativistic Maxwell-Jüttner distribution it equals \(k_BT\) along every axis, and for a non-relativistic bunch it reduces to \(mc^2\sigma_{\widetilde p_i}^2\). The exact transformation matters for relativistic beams: at equal \(\widetilde p_z\), a particle with a larger transverse momentum has a smaller longitudinal velocity. For a beam with a large transverse spread, this term dominates \(T_z\), and \(mc^2(\sigma_{\widetilde p_z}/\gamma_c)^2\) underestimates it by orders of magnitude.

All particles are taken at the same laboratory time, which in the rest frame is not a single time. This differs from a rest-frame snapshot only through the forces acting during the corresponding time offset. The DebyeLength, plasmaParameter, and rmsDensity columns are currently written as zero.

7.3.5 Statistics columns

The main statistics file is SDDS ASCII. A single container uses <basename>.stat; multiple containers use <basename>_c0.stat, <basename>_c1.stat, and so on. Read column names and units from the file header. The following subset maps the moments above to the output:

Columns Definition Units
mean_x, mean_y, mean_s \(\langle x\rangle\), \(\langle y\rangle\), \(\langle z\rangle\) m
rms_x, rms_y, rms_s \(\sigma_x\), \(\sigma_y\), \(\sigma_z\) m
rms_px, rms_py, rms_ps \(\sigma_{\widetilde p_x}\), \(\sigma_{\widetilde p_y}\), \(\sigma_{\widetilde p_z}\) dimensionless
xpx, ypy, zpz \(\rho_x\), \(\rho_y\), \(\rho_z\) dimensionless
emit_x, emit_y, emit_s \(\varepsilon_{n,x}\), \(\varepsilon_{n,y}\), \(\varepsilon_{n,z}\) m
temperature_x, temperature_y, temperature_s Rest-frame \(T_x\), \(T_y\), \(T_z\) K

These definitions concern the bunch snapshot at an output time. Sampling and frames for MONITOR and PROBE records must be considered separately.

7.4 Multipole conversion

QUADRUPOLE.K1 and the quadrupole entry of MULTIPOLE.KN already take a normalized strength \(k_1\) in \(\mathrm{m^{-2}}\). When importing it from another code, retain that normalization and set the global reference momentum P0 in \(\mathrm{GeV}/c\). OPALX converts the normalized coefficient to a physical field coefficient using P0; do not first convert \(k_1\) to a gradient for these attributes. See QUADRUPOLE and MULTIPOLE.

For a physical field-gradient interface, the conversion is \(G=(B\rho)k_1\), using the reference magnetic rigidity. Use momentum rather than total or kinetic energy to determine the rigidity; replacing momentum with energy is an ultrarelativistic approximation. Check the coordinate and charge conventions and verify the sign with a single-particle trajectory before using an imported lattice.