14  Distribution Command

14.1.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.

14.2.1 Universal Attributes

These attributes apply to all distribution types:

14.2.2 Injected Distribution Attributes

14.2.3 Emitted Distribution Attributes

14.3.1 FROMFILE

FROMFILE reads coordinates from an external text file.

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

The type-specific attribute is:

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.

14.3.2 GAUSS

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

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.

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}). \]

14.3.3 FLATTOP

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

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;

14.3.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 [8].

The key shape parameters are:

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;

14.3.5 GAUSSMATCHED

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

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

14.3.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 [9].

Key attributes are:

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

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;

14.4.1 NONE

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

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

14.4.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].

14.4.3 NONEQUIL

NONEQUIL is a more physical photoemission model for metal cathodes and materials such as CsTe [10], [11], [12].

Its additional parameters are:

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;