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.CORRaffects correlations; CUTOFFX,CUTOFFY,CUTOFFPX,CUTOFFPY, andCUTOFFPZapply toGAUSSonly;CUTOFFLONGalso controls the flat-top pulse edges and the optional legacy emitted-file window.MULTIVARIATEGAUSSuses internally fixed three-sigma bounds;FTOSCAMPLITUDEandFTOSCPERIODSaffect onlyOPALFLATTOP;ASTRAis supported only by the generated flat-top distribution and- file distributions take momentum from their files, not from
BEAMenergy.
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. |
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,CORRZR51,R52R61,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].
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.
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
EMITTEDor injected mode - the total number of particles is still controlled by the
BEAMcommand - 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.