17  Beam and Distributions

OPALX separates the sampled phase space from its placement in the simulation:

Dist: DISTRIBUTION, TYPE=GAUSS, NPARTDIST=10000,
      SIGMAX=1e-3, SIGMAY=1e-3, SIGMAZ=2e-3,
      SIGMAPX=1e-4, SIGMAPY=1e-4, SIGMAPZ=1e-4;
Source: EMISSIONSOURCE, DISTRIBUTION=Dist;
Sources: EMISSIONSOURCELIST=(Source);
Beam: BEAM, PARTICLE=ELECTRON, PC=0.1, NALLOC=10000,
      BCHARGE=1e-9, SOURCES=Sources;

The DISTRIBUTION defines the particle sample, EMISSIONSOURCE adds source offsets and timing, EMISSIONSOURCELIST groups sources, and BEAM.SOURCES selects the group. See Beam Definitions for the complete BEAM attribute table and its reference-energy rules.

17.1 EMISSIONSOURCE

name: EMISSIONSOURCE, DISTRIBUTION=distribution_name, ...;

Offsets are applied after sampling. Position uses metres, momentum uses dimensionless normalized momentum \(\boldsymbol{p}/mc=\boldsymbol{\beta}\gamma\), and time uses seconds.

Parameter Default Meaning and constraints
DISTRIBUTION required Previously defined DISTRIBUTION name.
R0X, R0Y, R0Z 0 m Position offset added to every sampled particle.
P0X, P0Y, P0Z 0 Normalized-momentum offset added after sampling.
T0 0 s Source start time. For one-shot types, T0 > 0 delays injection.
EMISSIONMODEL NONE NONE or ASTRA; availability depends on distribution type.
EKIN 0 eV Thermal kinetic energy for generated emitted particles; OPALX uses its absolute value.
ZEROFACE_R0Z FALSE Apply explicit image-charge Dirichlet correction at \(z=\mathrm{R0Z}\).
SHIFTED_GREENS_FUNCTION FALSE Alternative shifted-Green correction; requires TYPE=OPEN, or TYPE=P3M with all BCFFT*=OPEN.
ZEROFACEPLANEDUMP 0 Non-negative integer dump frequency; requires ZEROFACE_R0Z=TRUE.
ZEROFACE_MAXSTEPS 0 Non-negative correction-step limit; 0 means unlimited.

ZEROFACE_R0Z and SHIFTED_GREENS_FUNCTION are mutually exclusive. A run can activate at most one source plane by either method.

For generated emission, NONE adds the momentum corresponding to EKIN in \(+z\). ASTRA samples the forward half-sphere with magnitude

\[ p_{\mathrm{th}}=\sqrt{\left(1+\frac{E_{\mathrm{kin}}}{mc^2}\right)^2-1}, \qquad p_z\geq 0, \]

before adding P0X, P0Y, and P0Z.

17.2 EMISSIONSOURCELIST

Sources: EMISSIONSOURCELIST=(Source1, Source2);

The list is ordered and must contain at least one previously defined EMISSIONSOURCE. Attach it with SOURCES=Sources on BEAM. Several sources may use the same distribution, each with independent offsets and start time.

17.3 DISTRIBUTION

name: DISTRIBUTION, TYPE=distribution_type, ...;

OPALX accepts exactly UNIFORM, GAUSS, MULTIVARIATEGAUSS, FLATTOP, OPALFLATTOP, FROMFILE, and EMITTEDFROMFILE.

The legacy OPAL types BINOMIAL, GAUSSMATCHED, MULTIGAUSS, GUNGAUSSFLATTOPTH, and ASTRAFLATTOPTH are unavailable in the current OPALX version. The legacy NONEQUIL emission model and laser-image distribution attributes are also unavailable.

Available input parameters

Parameter Default / unit Used by Runtime effect
TYPE required all Selects one of the seven types above.
NPARTDIST 0, particles all Requested macroparticle count. Use a positive integer except where EMITTEDFROMFILE explicitly selects all file records.
FNAME empty, path file types Input particle file. A relative name is first checked in the working directory; if absent, it is checked relative to the OPALX input file directory.
SIGMAX, SIGMAY, SIGMAZ 0 m UNIFORM; Gaussian types; transverse flat-top types Ellipsoid semi-axes for UNIFORM, Gaussian widths, or transverse flat-top semi-axes.
SIGMAPX, SIGMAPY, SIGMAPZ 0, \(\beta\gamma\) Gaussian types RMS normalized-momentum widths.
CORR empty array MULTIVARIATEGAUSS Fifteen off-diagonal correlation coefficients.
SIGMAT 0 s flat-top types; optional emitted-file window Default RMS width for both pulse edges.
TPULSEFWHM 0 s flat-top types; optional emitted-file window Full pulse width at half maximum.
TRISE, TFALL 0 s flat-top types; optional emitted-file window Edge times; a positive value overrides the corresponding SIGMAT.
CUTOFFLONG 3, \(\sigma\) GAUSS; flat-top types; optional emitted-file window Truncates the longitudinal position of GAUSS at \(\pm\,\)CUTOFFLONG\(\,\sigma_z\) and both Gaussian pulse edges of the flat-top types. Must be positive.
FTOSCAMPLITUDE 0 % OPALFLATTOP Sinusoidal modulation amplitude, clamped to 100%.
FTOSCPERIODS 0 OPALFLATTOP Number of modulation periods across the flat interval.
EMITTED FALSE flat-top types; optional emitted-file window Enables generated time-dependent emission.
EMISSIONSTEPS 100 OPALFLATTOP, EMITTEDFROMFILE Defines the number of emission steps.
CUTOFFX, CUTOFFY 3, \(\sigma\) GAUSS Semi-axes of the elliptical cut on \((x,y)\) in units of \(\sigma_x\), \(\sigma_y\). 0 disables the cut. Ignored by MULTIVARIATEGAUSS.
CUTOFFPX, CUTOFFPY, CUTOFFPZ 3, \(\sigma\) GAUSS Semi-axes of the elliptical cut on \((p_x,p_y)\) and the per-axis cut on \(p_z\), in units of the momentum widths. 0 disables the cut. Ignored by MULTIVARIATEGAUSS.
CORRX, CORRY, CORRZ, CORRT 0 none currently Accepted but currently ignored; use CORR with MULTIVARIATEGAUSS.

Non-file distributions require PC, ENERGY, or GAMMA on BEAM. FROMFILE and EMITTEDFROMFILE contain absolute normalized momenta and reject those three beam-energy attributes.

17.3.1 UNIFORM

UNIFORM samples positions uniformly by volume inside an ellipsoid with semi-axes \(a=\mathrm{SIGMAX}\), \(b=\mathrm{SIGMAY}\), and \(c=\mathrm{SIGMAZ}\):

\[ \frac{x^2}{a^2}+\frac{y^2}{b^2}+\frac{z^2}{c^2}\leq 1. \]

All three semi-axes must be positive. Every particle receives the same normalized momentum \((0,0,\bar p_z)\) from the beam reference momentum, so the sample has no momentum spread. Source R0* and P0* offsets are added after sampling.

U: DISTRIBUTION, TYPE=UNIFORM, NPARTDIST=10000,
   SIGMAX=1e-3, SIGMAY=2e-3, SIGMAZ=3e-3;

Use EMISSIONMODEL=NONE and T0=0. Other emission models are not yet supported.

17.3.2 GAUSS

GAUSS samples independent normal coordinates and truncates them with the same cuts as OPAL. Each candidate \((x,y,z,p_x,p_y,p_z)\) is drawn in units of its width and accepted only if

\[ \left(\frac{x}{C_x}\right)^2+\left(\frac{y}{C_y}\right)^2\le 1,\qquad \left(\frac{p_x}{C_{p_x}}\right)^2+\left(\frac{p_y}{C_{p_y}}\right)^2\le 1,\qquad |z|\le C_z,\qquad |p_z|\le C_{p_z}, \]

where \(C_x\), \(C_y\), \(C_z\) are CUTOFFX, CUTOFFY, CUTOFFLONG and \(C_{p_x}\), \(C_{p_y}\), \(C_{p_z}\) are CUTOFFPX, CUTOFFPY, CUTOFFPZ, all in units of the corresponding SIGMA*. The transverse cuts are ellipses, not boxes, so the accepted sample excludes the corners that an independent per-axis truncation would keep. Accepted samples are scaled by the widths:

\[ R_i\sim\mathcal{N}(0,\sigma_{R_i}^2),\qquad P_i\sim\mathcal{N}(\bar P_i,\sigma_{P_i}^2), \]

with \(\bar P=(0,0,\bar p_z)\) taken from the BEAM reference momentum.

A cutoff of 0 for CUTOFFX, CUTOFFY, CUTOFFPX, CUTOFFPY, or CUTOFFPZ disables that cut. CUTOFFLONG must be positive; 0 is rejected with an error. Negative values are used by magnitude.

After sampling, the phase space is adjusted as in OPAL: \(x\), \(y\), \(z\), \(p_x\), and \(p_y\) are shifted so that their sampled means are exactly zero, and \(p_z\) is shifted by a common offset so that the mean of \(p_z+(p_x^2+p_y^2)/(2p_z)\) equals \(\bar p_z\). The source offsets R0* and P0* are added afterwards and are not affected by this adjustment.

Because of the truncation, the sampled RMS widths lie below the requested SIGMA* values. With the default cutoff of \(3\), the transverse RMS widths are \(0.974\,\sigma\) and the longitudinal ones \(0.987\,\sigma\). A zero SIGMA* collapses that coordinate to an exact point. An omitted spatial width defaults to zero; no artificial spread is introduced, and momentum spreads remain as specified. Older builds may produce non-finite samples for zero spatial widths (see issue #617).

Use Parameters
Count NPARTDIST (positive integer)
Position SIGMAX, SIGMAY, SIGMAZ
Momentum SIGMAPX, SIGMAPY, SIGMAPZ
Cutoffs CUTOFFX, CUTOFFY, CUTOFFLONG, CUTOFFPX, CUTOFFPY, CUTOFFPZ
Source R0*, P0*, T0; EMISSIONMODEL=NONE only
G: DISTRIBUTION, TYPE=GAUSS, NPARTDIST=10000,
   SIGMAX=1e-3, SIGMAY=1e-3, SIGMAZ=2e-3,
   SIGMAPX=1e-4, SIGMAPY=1e-4, SIGMAPZ=2e-4,
   CUTOFFX=3, CUTOFFY=3, CUTOFFLONG=3,
   CUTOFFPX=3, CUTOFFPY=3, CUTOFFPZ=0;   // no cut on pz

With T0 > 0, the complete sample is injected once when a tracker step crosses T0. The named correlations CORRX, CORRY, CORRZ, CORRT do not affect this sampler; use MULTIVARIATEGAUSS for correlated phase space.

17.3.3 MULTIVARIATEGAUSS

Let

\[ q=(x,p_x,y,p_y,z,p_z)^T,\qquad D=\operatorname{diag}(\sigma_x,\sigma_{p_x},\sigma_y,\sigma_{p_y}, \sigma_z,\sigma_{p_z}). \]

CORR defines a correlation matrix \(C\) and the sampler forms \(\Sigma=DCD=LL^T\), then applies the Cholesky factor \(L\) to independent normal samples. \(C\) must be symmetric positive definite.

Use Parameters
Count and widths NPARTDIST, all six SIGMA* values
Coupling CORR with exactly 15 values
Source R0*, P0*, T0; EMISSIONMODEL=NONE only

The array is the upper triangle in this order:

(x,px), (x,y), (x,py), (x,z), (x,pz),
(px,y), (px,py), (px,z), (px,pz),
(y,py), (y,z), (y,pz), (py,z), (py,pz), (z,pz)
MG: DISTRIBUTION, TYPE=MULTIVARIATEGAUSS, NPARTDIST=10000,
    SIGMAX=1e-3, SIGMAPX=1e-4,
    SIGMAY=1e-3, SIGMAPY=1e-4,
    SIGMAZ=2e-3, SIGMAPZ=2e-4,
    CORR={0.2,0,0,0,0, 0,0,0,0, 0,0,0, 0,0,0};

Sampling truncates each coordinate independently at internally fixed three-sigma bounds; the CUTOFF* attributes are ignored, and no phase-space adjustment is applied. T0 > 0 produces one delayed injection, as for GAUSS.

17.3.4 FLATTOP

FLATTOP is a time-dependent emitter. Transverse positions are uniform on an ellipse with semi-axes \(a=\mathrm{SIGMAX}\) and \(b=\mathrm{SIGMAY}\):

\[ x=a\sqrt{u}\cos(2\pi v),\qquad y=b\sqrt{u}\sin(2\pi v),\qquad u,v\sim U(0,1). \]

Use Parameters
Required NPARTDIST>0, EMITTED=TRUE, SIGMAX, SIGMAY
Pulse SIGMAT or TRISE/TFALL, TPULSEFWHM, CUTOFFLONG
Source T0, R0*, P0*, EKIN; EMISSIONMODEL=NONE or ASTRA

For a positive TRISE or TFALL, OPALX converts the corresponding input edge time to an RMS width using

\[ \sigma=\frac{T_{\mathrm{edge}}} {\sqrt{2\ln 10}-\sqrt{2\ln(10/9)}}. \]

With edge widths \(\sigma_r\), \(\sigma_f\) and cutoff \(C\), the flat interval and total emission duration are

\[ T_{\mathrm{flat}}=\max\!\left(0,T_{\mathrm{FWHM}} -\sqrt{2\ln2}(\sigma_r+\sigma_f)\right),\qquad T_{\mathrm{emit}}=C(\sigma_r+\sigma_f)+T_{\mathrm{flat}}. \]

The rate consists of truncated Gaussian rise and fall edges around a constant flat interval. Each tracker step integrates that profile and gives newborn particles a random fractional timestep.

FT: DISTRIBUTION, TYPE=FLATTOP, NPARTDIST=10000, EMITTED=TRUE,
    SIGMAX=1e-3, SIGMAY=1e-3,
    TRISE=0.5e-12, TFALL=0.5e-12,
    TPULSEFWHM=10e-12, CUTOFFLONG=3;

17.3.5 OPALFLATTOP

OPALFLATTOP uses the same transverse and pulse mathematics as FLATTOP, but precomputes a globally sorted inventory of particle birth times. This gives an exact requested inventory and OPAL-compatible pulse centering.

Use Parameters
Required All FLATTOP parameters; NPARTDIST>0 and EMITTED=TRUE are enforced
Resolution EMISSIONSTEPS
Modulation FTOSCAMPLITUDE, FTOSCPERIODS
Source T0, R0*, P0*, EKIN; EMISSIONMODEL=NONE or ASTRA

On the flat interval, birth-time density is proportional to

\[ 1+a\sin\!\left(2\pi n\frac{t}{T_{\mathrm{flat}}}\right),\qquad a=\min\!\left(1,\frac{|\mathrm{FTOSCAMPLITUDE}|}{100}\right), \]

where \(n=|\mathrm{FTOSCPERIODS}|\).

OFT: DISTRIBUTION, TYPE=OPALFLATTOP, NPARTDIST=10000, EMITTED=TRUE,
     SIGMAX=1e-3, SIGMAY=1e-3,
     TRISE=0.5e-12, TFALL=0.5e-12,
     TPULSEFWHM=10e-12, CUTOFFLONG=3,
     EMISSIONSTEPS=100, FTOSCAMPLITUDE=5, FTOSCPERIODS=3;

17.3.6 FROMFILE

FROMFILE reads an injected 6D sample. Set a positive NPARTDIST; OPALX uses at most that many records from the beginning of the file.

Use Parameters
Required FNAME, positive NPARTDIST
Source R0*, P0*, T0; EMISSIONMODEL=NONE only
Beam Omit PC, ENERGY, and GAMMA

The first non-comment line is the declared count, the second is a header, and exactly that many data rows must follow. Header order is arbitrary but must contain x, y, z, px, py, and pz (case-insensitive). Blank lines and lines beginning with # are ignored.

3
x px y py z pz
0.0 0.001 0.0 0.000 0.0 1.2
0.1 0.002 0.0 0.001 0.0 1.2
-0.1 0.000 0.0 -0.001 0.0 1.2
FF: DISTRIBUTION, TYPE=FROMFILE, FNAME="particles.txt", NPARTDIST=3;

Positions are metres and file momenta are absolute \(\beta\gamma\) values. Source offsets are added after reading. T0 > 0 delays the complete file sample to one tracker step.

With several MPI ranks, each rank reads and stores only its own records. The ranks split the data part of the file into equal byte ranges, count the data lines in their range, and exchange the counts. Each rank then parses only its contiguous block of the selected records. No rank holds the whole file, so host and device memory per rank scale with that rank’s share of the particles, and the file is read about twice in total, split over the ranks. Every rank opens FNAME, so the file must be on a file system that all ranks can read.

17.3.7 EMITTEDFROMFILE

EMITTEDFROMFILE reads either legacy old-OPAL emitted records or explicit spacetime records and releases them at per-record birth times.

Use Parameters
Required FNAME; NPARTDIST=0 selects all records, otherwise it selects a prefix
Resolution EMISSIONSTEPS
Optional window EMITTED=TRUE plus flat-top pulse parameters
Source R0*, P0*, T0; EMISSIONMODEL=NONE only
Beam Omit PC, ENERGY, and GAMMA

Legacy rows are positional: x px y py t pz [bin]. The positive-integer bin column is optional. A legacy file may use a leading count and header, or a comment header.

3
x px y py t pz bin
0.0 0.001 0.0 0.000 -2e-12 1.2 1
0.1 0.002 0.0 0.001 -1e-12 1.2 2
-0.1 0.000 0.0 -0.001 0.0 1.2 3
EFF: DISTRIBUTION, TYPE=EMITTEDFROMFILE,
     FNAME="emitted.txt", NPARTDIST=0, EMISSIONSTEPS=100;

Without bins or a configured window, OPALX negates the old-OPAL file times, centres their span, and uses

\[ t_{\mathrm{birth}}=\mathrm{T0}-t_{\mathrm{file}}-t_{\mathrm{centre}}. \]

An enabled flat-top window may replace the inferred span, but it must cover the latest selected file time. Positions and momenta receive the source offsets; the file momenta remain absolute.

For event-generator input, use an explicit named header containing x y z px py pz birth_time:

2
x y z px py pz birth_time
1e-6 2e-6 -3e-4 0.1 -0.2 0.3 -4e-12
-1e-6 1e-6 2e-4 -0.1 0.2 -0.3 3e-12

Columns in this format are mapped by name. Positions are metre offsets from the emission source R0, momenta are absolute normalized values \(p/(mc)\) plus any source P0 offset, and birth_time is a time offset in seconds from the source T0:

\[ t_{\mathrm{birth}}=\mathrm{T0}+t_{\mathrm{file}},\qquad \mathbf R_{\mathrm{birth}}=\mathbf R_0+(x,y,z). \]

For compatibility with early prototype files, t is accepted as an alias for birth_time only when the named header also contains z. Explicit records are not negated or recentered, and flat-top window parameters do not override their birth times. EMISSIONSTEPS controls only the preferred tracker step during the span; a particle born inside a step receives the remaining fractional step.

17.4 Reproducibility and current limitations

Record the OPALX version, random seed, NPARTDIST, BEAM.NALLOC, bunch charge, source list, and every referenced file. Keep NALLOC at least as large as the sum of the source distributions’ particle counts.

Current limitations are:

  • only MULTIVARIATEGAUSS.CORR affects correlations;
  • CUTOFFX, CUTOFFY, CUTOFFPX, CUTOFFPY, and CUTOFFPZ apply to GAUSS only; CUTOFFLONG also controls the flat-top pulse edges and the optional legacy emitted-file window. MULTIVARIATEGAUSS uses internally fixed three-sigma bounds;
  • FTOSCAMPLITUDE and FTOSCPERIODS affect only OPALFLATTOP;
  • ASTRA is supported only by the generated flat-top distribution and
  • file distributions take momentum from their files, not from BEAM energy.

The DISTRIBUTION command defines how particles are introduced into a simulation. A distribution has a name, a type, and a set of attributes that control its geometry, momentum spread, emission behavior, and optional correlations.

Name: DISTRIBUTION, TYPE = DISTRIBUTION_TYPE,
      ATTRIBUTE1 = ...,
      ATTRIBUTE2 = ...;

The following distribution types belong to the retained legacy OPAL interface. The current OPALX types are listed in the OPALX view.

Type Description
FROMFILE Read initial particle coordinates from a user-provided text file.
GAUSS Gaussian distribution in one or more dimensions.
FLATTOP Hard-edge transverse distribution with flat-top time structure.
BINOMIAL Binomial family controlled by one shape parameter per axis.
GAUSSMATCHED Matched Gaussian distribution for cyclotron-style matching.
MULTIGAUSS Train of Gaussian pulses along the longitudinal direction.
GUNGAUSSFLATTOPTH Legacy shorthand for emitted FLATTOP with ASTRA.
ASTRAFLATTOPTH Legacy emitted flat-top photoinjector distribution.

17.5 Units

Lengths are given in meters and times in seconds. Momentum input units depend on INPUTMOUNITS.

Attribute Value Meaning
INPUTMOUNITS NONE Use normalized momentum components beta_x gamma, beta_y gamma, beta_z gamma. This is the OPAL-T default.
INPUTMOUNITS EVOVERC Use momenta in eV/c. This is the OPAL-cycl default.

17.5.1 Momentum unit conversion

To convert from normalized momentum to transverse angle in mrad, use \[ (\beta\gamma)_{\mathrm{ref}} = \frac{P}{m_0 c} = \frac{Pc}{m_0 c^2}, \] and \[ P_x[\mathrm{mrad}] = 1000 \times \frac{\beta_x\gamma}{(\beta\gamma)_{\mathrm{ref}}}. \]

To convert from eV/c to dimensionless normalized momentum, \[ \beta_x \gamma = \frac{P_x[\mathrm{eV}/c]}{m_0 c} = \frac{P_x[\mathrm{eV}/c]\,c}{m_0 c^2}. \]

The same relations apply to the y and z components.

17.6 General Distribution Attributes

The first major distinction is whether the distribution is injected at the start of the simulation or emitted over time.

Attribute Value Meaning
EMITTED FALSE Inject the full distribution at the start of the simulation. This is the default.
EMITTED TRUE Emit the particles over time. This is currently an OPAL-T mode.

For injected distributions, the longitudinal coordinate is z in meters. For emitted distributions, the longitudinal coordinate is t in seconds.

17.6.1 Universal Attributes

These attributes apply to all distribution types:

Attribute Default Meaning
WRITETOFILE FALSE Write the generated initial distribution to a text file.
SCALABLE FALSE Make generation scalable with the number of MPI ranks.
WEIGHT 1.0 Relative weight when used in a distribution list.
NBIN 0 Number of energy bins.
SBIN 100 Sample bins per energy bin.
XMULT, YMULT 1.0 Scale transverse positions after generation.
PXMULT, PYMULT, PZMULT 1.0 Scale momentum components after generation.
OFFSETX, OFFSETY 0.0 Shift average transverse position.
OFFSETPX, OFFSETPY, OFFSETPZ 0.0 Shift average momentum.
ID1, ID2 zero 6-vector Tracer particles written to track_orbit.dat in OPAL-cycl.

17.6.2 Injected Distribution Attributes

Attribute Default Meaning
ZMULT 1.0 Scale longitudinal position after generation.
OFFSETZ 0.0 Shift average longitudinal position.

17.6.3 Emitted Distribution Attributes

Attribute Default Meaning
TMULT 1.0 Scale emission time after generation.
OFFSETT 0.0 Delay emission relative to the reference particle.
EMISSIONSTEPS 1 Number of timesteps used during emission.
EMISSIONMODEL NONE Emission model applied at the cathode.

17.7 Distribution Types

17.7.1 FROMFILE

FROMFILE reads coordinates from an external text file.

Name: DISTRIBUTION, TYPE=FROMFILE,
      FNAME="text file name";

The type-specific attribute is:

Attribute Meaning
FNAME File name containing the particle coordinates.

For an injected FROMFILE distribution, the file format is:

N
x1 px1 y1 py1 z1 pz1
x2 px2 y2 py2 z2 pz2
...
xN pxN yN pyN zN pzN

For an emitted FROMFILE distribution, z is replaced by t:

N
x1 px1 y1 py1 t1 pz1
x2 px2 y2 py2 t2 pz2
...
xN pxN yN pyN tN pzN

The emitted case is internally shifted so that emission starts from negative time and particles appear as the simulation clock advances.

When using FROMFILE, the particle count must match the BEAM NPART expectation, and the mean momentum in the file must be consistent with the beam energy settings.

17.7.2 GAUSS

GAUSS creates a six-dimensional Gaussian bunch. The core attributes are:

Attribute Meaning
SIGMAX, SIGMAY RMS transverse widths.
SIGMAR RMS radial width; overrides SIGMAX and SIGMAY if nonzero.
SIGMAZ, SIGMAT RMS bunch length in z or t. SIGMAZ overrides SIGMAT.
SIGMAPX, SIGMAPY, SIGMAPZ RMS momentum spreads.
CUTOFFX, CUTOFFY, CUTOFFR, CUTOFFLONG, CUTOFFPX, CUTOFFPY, CUTOFFPZ Cutoffs expressed in units of the corresponding sigma.

Example:

Name: DISTRIBUTION, TYPE       = GAUSS,
      SIGMAX     = 0.001,
      SIGMAY     = 0.003,
      SIGMAZ     = 0.002,
      SIGMAPX    = 0.0,
      SIGMAPY    = 0.0,
      SIGMAPZ    = 0.0,
      CUTOFFX    = 2.0,
      CUTOFFY    = 2.0,
      CUTOFFLONG = 4.0,
      OFFSETX    = 0.001,
      OFFSETY    = -0.002,
      OFFSETZ    = 0.01,
      OFFSETPZ   = 1200.0;

GAUSS for photoinjectors

For emitted beams, GAUSS can also produce a half-Gaussian rise, flat-top, half-Gaussian fall time profile. The key extra attributes are:

Attribute Meaning
TPULSEFWHM Full-width-at-half-maximum pulse length.
TRISE Rise time. Overrides SIGMAT.
TFALL Fall time. Overrides SIGMAT.
FTOSCAMPLITUDE Oscillation amplitude on the flat top, in percent.
FTOSCPERIODS Number of oscillation periods across the flat top.
Figure 17.1: Emitted GAUSS and FLATTOP time profile with half-Gaussian edges and optional flat-top oscillations.

The rise and fall parameters correspond to \[ \mathrm{TRISE} = 1.6869\,\sigma_R, \qquad \mathrm{TFALL} = 1.6869\,\sigma_F, \] and the pulse FWHM is \[ \mathrm{TPULSEFWHM} = t_{\mathrm{flattop}} + \sqrt{2\ln 2}(\sigma_R + \sigma_F). \]

The total emission time depends on CUTOFFLONG: \[ t_E = \mathrm{TPULSEFWHM} + \frac{\mathrm{CUTOFFLONG} - \sqrt{2 \ln 2}}{1.6869} (\mathrm{TRISE} + \mathrm{TFALL}). \]

Correlations for GAUSS

The Gaussian generator also supports experimental correlations. They can be given either as a compact array R or through named coefficients such as:

  • CORRX, CORRY, CORRZ
  • R51, R52
  • R61, R62

In the four-dimensional (x, p_x, z, p_z) subspace, the correlation matrix is \[ \sigma = \begin{bmatrix} 1 & c_x & R_{51} & R_{61} \\ c_x & 1 & R_{52} & R_{62} \\ R_{51} & R_{52} & 1 & c_t \\ R_{61} & R_{62} & c_t & 1 \end{bmatrix}. \]

The implementation constructs correlated samples from the Cholesky factorization of this matrix. This feature is experimental and only documented for Gaussian distributions.

17.7.3 FLATTOP

FLATTOP defines hard-edge distributions and is commonly used to model laser profiles in photoinjectors.

Injected FLATTOP

For injected beams, the distribution is a uniformly filled ellipse transversely and uniform in z.

Attribute Meaning
SIGMAX, SIGMAY Hard-edge widths.
SIGMAR Radial hard-edge width; overrides SIGMAX and SIGMAY.
SIGMAZ Hard-edge bunch length.

Emitted FLATTOP

For emitted beams, FLATTOP uses the same longitudinal pulse-shape parameters as the photoinjector-style GAUSS case.

Additional attributes include:

Attribute Meaning
SIGMAX, SIGMAY, SIGMAR Hard-edge transverse beam size.
SIGMAT, TPULSEFWHM, TRISE, TFALL Time-profile parameters.
FTOSCAMPLITUDE, FTOSCPERIODS Oscillations on the flat top.
LASERPROFFN, IMAGENAME, INTENSITYCUT Laser-profile image input.
FLIPX, FLIPY, ROTATE90, ROTATE180, ROTATE270 Laser-image transforms.

Example:

Dist: DISTRIBUTION, TYPE = FLATTOP,
      SIGMAX = 0.001,
      SIGMAY = 0.002,
      TRISE = 0.5e-12,
      TFALL = 0.5e-12,
      TPULSEFWHM = 10.0e-12,
      CUTOFFLONG = 4.0,
      NBIN = 5,
      EMISSIONSTEPS = 100,
      EMISSIONMODEL = ASTRA,
      EKIN = 0.5,
      EMITTED = TRUE;

The legacy manual also describes a laser-image driven transverse sampling path through LASERPROFFN, but explicitly marks it as under development.

GUNGAUSSFLATTOPTH and ASTRAFLATTOPTH

These are legacy shorthands for emitted flat-top photoinjector distributions. Both correspond to FLATTOP-style emission. GUNGAUSSFLATTOPTH automatically enables EMITTED=TRUE and EMISSIONMODEL=ASTRA, while ASTRAFLATTOPTH follows the same idea with a slightly different legacy longitudinal profile generator.

17.7.4 BINOMIAL

BINOMIAL generates a family of distributions governed by one parameter m per axis. Changing m moves continuously from hollow-shell and flat-profile shapes toward Gaussian-like limits [1].

Figure 17.2: Representative transverse properties of binomial phase-space distributions.

The key shape parameters are:

Attribute Meaning
MX Binomial parameter in x.
MY Binomial parameter in y.
MT, MZ Binomial parameter in the longitudinal direction. MZ is the same as MT.

The phase-space widths are still set through the usual SIGMAX, SIGMAPX, CORRX, and corresponding y and z/t variants.

For one plane, \[ \epsilon_x = \sigma_x \sigma_{x'} \cos\!\left(\arcsin(\sigma_{12})\right), \] with the corresponding Twiss relations \[ \beta_x = \frac{\sigma_x^2}{\epsilon_x}, \qquad \gamma_x = \frac{\sigma_{x'}^2}{\epsilon_x}, \qquad \alpha_x = -\sigma_{12}\sqrt{\beta_x \gamma_x}. \]

Example:

Dist: DISTRIBUTION, TYPE    = BINOMIAL,
      SIGMAX  = 2.15e-03,
      SIGMAPX = 1E-6,
      CORRX   = 0.0,
      MX      = 0.01,
      SIGMAY  = 0.50*23.e-03,
      SIGMAPY = 28.0,
      CORRY   = 0.5,
      MY      = 990.0,
      SIGMAT  = 1.0e-1,
      SIGMAPT = 11.96,
      CORRT   = -0.5,
      MT      = 2.0;

17.7.5 GAUSSMATCHED

GAUSSMATCHED constructs a matched Gaussian distribution, intended for cyclotron-style matched injection. The main control parameters are:

Attribute Meaning
DENERGY Energy step size for the closed-orbit finder.
EX, EY, ET Projected normalized emittances.
NSTEPS, NSECTORS Closed-orbit integration controls.
SECTOR Match using one sector or the full ring.
ORDERMAPS Order used in the field expansion.
RGUESS Initial radius guess.
RESIDUUM Convergence target.
MAXSTEPSCO, MAXSTEPSSI Iteration limits for the closed-orbit and matching loops.

The legacy manual explicitly notes one limitation: trim-coil field maps are not included in this matched-distribution construction.

17.7.6 MULTIGAUSS

MULTIGAUSS models a train of Gaussian pulses. Transversely it uses a uniform elliptical profile, while longitudinally it generates NPEAKS equally spaced Gaussian peaks [2].

Key attributes are:

Attribute Meaning
SIGMAX, SIGMAY, SIGMAR Transverse size.
SIGMAZ, SIGMAT RMS length of each Gaussian pulse.
SEPPEAKS Peak-to-peak separation.
NPEAKS Number of Gaussian pulses.
CUTOFFLONG Longitudinal cutoff relative to the first and last pulse.
SIGMAPX, SIGMAPY, SIGMAPZ Momentum spread for injected beams.
CUTOFFPX, CUTOFFPY, CUTOFFPZ Momentum cutoffs for injected beams.

When emitted, the momentum is assigned by the selected emission model. When injected, the momentum components are sampled from normal distributions.

Figure 17.3: Example of an injected MULTIGAUSS bunch with several separated longitudinal peaks.

Example:

Dist: DISTRIBUTION, TYPE = MULTIGAUSS,
      SIGMAPX = 1e-2, SIGMAPY = 1e-2, SIGMAPZ = 1e-2,
      CUTOFFPX = 4.0, CUTOFFPY = 4.0, CUTOFFPZ = 4.0,
      SIGMAR = 340e-6,
      SIGMAZ = 90e-6 / 2.355,
      CUTOFFLONG = 4.0,
      SEPPEAKS = 126e-6,
      NPEAKS = 4,
      EMITTED = FALSE;

17.8 Emission Models

Emission models apply only to emitted distributions and determine how thermal energy and cathode physics are translated into initial particle momentum.

17.8.1 NONE

NONE is the default OPAL-T emission model. It adds a user-specified kinetic energy EKIN to the longitudinal momentum only.

Attribute Default Meaning
EKIN 1.0 eV Thermal energy added during emission.

This model is useful for transversely cold emitted beams. If EKIN=0, emitted particles may fail to drift off the cathode cleanly.

17.8.2 ASTRA

ASTRA uses the same EKIN parameter but distributes the momentum three-dimensionally: \[ p_{\mathrm{total}} = \sqrt{\left(\frac{\mathrm{EKIN}}{mc^2}+1\right)^2 - 1}, \] \[ p_x = p_{\mathrm{total}}\sin(\theta)\cos(\phi),\quad p_y = p_{\mathrm{total}}\sin(\theta)\sin(\phi),\quad p_z = p_{\mathrm{total}}|\cos(\theta)|. \]

Here theta is random on [0, pi], and \[ \phi = 2 \arccos\!\left(\sqrt{x}\right), \] with x a uniform random number on [0, 1].

17.8.3 NONEQUIL

NONEQUIL is a more physical photoemission model for metal cathodes and materials such as CsTe [3], [4], [5].

Its additional parameters are:

Attribute Default Meaning
ELASER 4.86 eV Drive-laser photon energy.
W 4.31 eV Cathode work function.
FE 7.0 eV Fermi energy.
CATHTEMP 300 K Cathode temperature.

Example:

Dist: DISTRIBUTION, TYPE = GAUSS,
      SIGMAX = 0.001,
      SIGMAY = 0.002,
      TRISE = 1.0e-12,
      TFALL = 1.0e-12,
      TPULSEFWHM = 15.0e-12,
      CUTOFFLONG = 3.0,
      NBIN = 10,
      EMISSIONSTEPS = 100,
      EMISSIONMODEL = NONEQUIL,
      ELASER = 6.48,
      W = 4.1,
      FE = 7.0,
      CATHTEMP = 325,
      EMITTED = TRUE;

17.9 Distribution List

The RUN command can accept either a single distribution or a list:

RUN, METHOD = "PARALLEL-T",
     BEAM = beam_name,
     FIELDSOLVER = field_solver_name,
     DISTRIBUTION = DIST1;

or

RUN, METHOD = "PARALLEL-T",
     BEAM = beam_name,
     FIELDSOLVER = field_solver_name,
     DISTRIBUTION = {DIST1, DIST2, DIST3};

In a distribution list:

  • the first entry is the master distribution
  • all other distributions inherit its EMITTED or injected mode
  • the total number of particles is still controlled by the BEAM command
  • per-distribution particle counts are apportioned through WEIGHT

FROMFILE is the special case: its particle count comes from the file rather than from BEAM and WEIGHT.