Skip to content

GitLab

  • Projects
  • Groups
  • Snippets
  • Help
    • Loading...
  • Help
    • Help
    • Support
    • Community forum
    • Submit feedback
  • Sign in
O OPALManualWiki
  • Project overview
    • Project overview
    • Details
    • Activity
    • Releases
  • Repository
    • Repository
    • Files
    • Commits
    • Branches
    • Tags
    • Contributors
    • Graph
    • Compare
    • Locked Files
  • Issues 0
    • Issues 0
    • List
    • Boards
    • Labels
    • Service Desk
    • Milestones
    • Iterations
  • Merge requests 0
    • Merge requests 0
  • CI/CD
    • CI/CD
    • Pipelines
    • Jobs
    • Schedules
  • Operations
    • Operations
    • Incidents
    • Environments
  • Analytics
    • Analytics
    • CI/CD
    • Code Review
    • Issue
    • Repository
    • Value Stream
  • Wiki
    • Wiki
  • Snippets
    • Snippets
  • Members
    • Members
  • Activity
  • Graph
  • Create a new issue
  • Jobs
  • Commits
  • Issue Boards
Collapse sidebar
  • snuverink_j
  • OPALManualWiki
  • Wiki
  • distribution

Last edited by Jochem Snuverink Sep 12, 2017
Page history

distribution

Table of Contents
  • 1. Distribution Command
    • 1.1. Units
    • 1.2. General Distribution Attributes
    • 1.3. FROMFILE Distribution Type
    • 1.4. GAUSS Distribution Type
    • 1.5. FLATTOP Distribution Type
    • 1.6. BINOMIAL Distribution Type
    • 1.7. Emission Models
    • 1.8. Distribution List

1. Distribution Command

Table 1. Possible distribution types. Note that the SURFACEEMISSION and SURFACERANDCREATE distribution types will not be discussed in this chapter. Instead, refer to Chapter [femiss] on field emission for using these types.
Distribution Type Description

FROMFILE

Initial distribution read in from text file provided by user see Section [fromfiledisttype].

GAUSS

Initial distribution generated using Gaussian distribution(s) see Section [gaussdisttype].

FLATTOP

Initial distribution generated using flattop distribution(s) see Section [flattopdisttype].

BINOMIAL

Initial distribution generated using binomial distribution(s) see Section [binomialdisttype].

SURFACEEMISSION

For dark current and multipacting simulations. This type of distribution will not be covered in this chapter, see instead Chapter [femiss].

SURFACERANDCREATE

For dark current and multipacting simulations. This type of distribution will not be covered in this chapter, see instead Chapter [femiss].

GUNGAUSSFLATTOPTH

Legacy. Special case of FLATTOP distribution see Section [gungaussflattopthdisttype].

ASTRAFLATTOPTH

Legacy. Special case of FLATTOP distribution see Section [astraflattopthdisttype].

The distribution command is used to introduce particles into an OPAL simulation. Like other OPAL commands see Chapter [format], the distribution command is of the form:

Name:DISTRIBUTION, TYPE = DISTRIBUTION_TYPE,
                   ATTRIBUTE #1 =,
                   ATTRIBUTE #2 =,
                   .
                   .
                   .
                   ATTRIBUTE #N =;

The distribution is given a name (which is used to reference the distribution in the OPAL input file), a distribution type, and a list of attributes. The types of distributions that are supported are listed in Table [disttypes]. The attributes that follow the distribution type further define the particle distribution. Some attributes are universal, while others are specific to the distribution type. In the following sections we will define the distribution attributes, starting with the general, or universal attributes. (Note that, in general, if a distribution type does not support a particular attribute, defining a value for it does no harm. That attribute just gets ignored.)

1.1. Units

The internal units used by OPAL-t and OPAL-cycl are described in Section [variablesopalt,variablesopalcycl]. When defining a distribution, both OPAL-t and OPAL-cycl use meters for length and seconds for time. However, there are different options for the units used to input the momentum. This is controlled with the INPUTMOUNITS attribute, defined in Table [distattrinputmounits].

Table 2. Definition of INPUTMOUNITS attribute.
Attribute Name Value Description

INPUTMOUNITS

NONE (default for OPAL-t)

Use no units for the input momentum (e.g. p_{x}, p_{y}, p_{z}). Momentum is given as \beta_{x} \gamma, \beta_{y} \gamma and \beta_{z} \gamma, as in Section [variablesopalt].

INPUTMOUNITS

EV (default for OPAL-cycl)

Use the units eV for the input momentum (e.g. p_{x}, p_{y}, p_{z}).

1.2. General Distribution Attributes

Once the distribution type is chosen, the next attribute to specify is the EMITTED attribute, which is defined in Table [distattremitted]. The EMITTED attribute controls whether a distribution is injected or emitted. An injected distribution is placed in its entirety into the simulation space at the start of the simulation. An emitted beam is emitted into the simulation over time as the simulation progresses (e.g. from a cathode in a photoinjector simulation). Currently, only OPAL-t supports emitted distributions. The default is an injected distribution.

Table 3. Definition of EMITTED attribute.
Attribute Name Value Description

EMITTED

FALSE (default)

The distribution is injected into the simulation in its entirety at the start of the simulation. The particle coordinates for an injected distribution are defined as in Section [variablesopalt,variablesopalcycl]. Note that in OPAL-t the entire distribution will automatically be shifted to ensure that the z coordinate will be greater than zero for all particles.

EMITTED

TRUE

The distribution is emitted into the simulation over time as the simulation progresses. Currently only OPAL-t supports this type of distribution. In this case, the longitudinal coordinate, as defined by Section [variablesopalt], is given in seconds instead of meters. Early times are emitted first.

Depending on the EMITTED attribute, we can specify several other attributes that do not depend on the distribution type. These are defined in Section [universaldistattributes,injecteddistattributes,emitteddistattributes] in Table [distattruniversal,distattrinjected,distattrsemitted].

1.2.1. Universal Attributes

Table 4. Definition of universal distribution attributes. Any distribution type can use these and they are the same whether the beam is injected or emitted.
Attribute Name Default Value Units Description

WRITETOFILE

FALSE

None

Echo initial distribution to text file data/<basename > DIST.dat_.

SCALABLE

FALSE

None

Makes the generation scalable with respect of number of particles. The result depends on the number of cores used.

WEIGHT

1.0

None

Weight of distribution when used in a distribution list see Section [distlist].

NBIN

0

None

The distribution (beam) will be broken up into NBIN energy bins. This has consequences for the space charge solver see Section [FSENBINS].

XMULT

1.0

None

Value used to scale the x positions of the distribution particles. Applied after the distribution is generated (or read in).

YMULT

1.0

None

Value used to scale the y positions of the distribution particles. Applied after the distribution is generated (or read in).

PXMULT

1.0

None

Value used to scale the x momentum, p_{x}, of the distribution particles. Applied after the distribution is generated (or read in).

PYMULT

1.0

None

Value used to scale the y momentum, p_{y}, of the distribution particles. Applied after the distribution is generated (or read in).

PZMULT

1.0

None

Value use to scale the z momentum, p_{z}, of the distribution particles. Applied after the distribution is generated (or read in).

OFFSETX

0.0

m

Distribution is shifted in x by this amount after the distribution is generated (or read in). Same as the average x position, \bar{x}.

OFFSETY

0.0

m

Distribution is shifted in y by this amount after the distribution is generated (or read in). Same as the average y position, \bar{y}.

OFFSETPX

0.0

Section [unitsdistattributes]

Distribution is shifted in p_{x} by this amount after the distribution is generated (or read in). Same as the average p_{x} value, \bar{p}_{x}.

OFFSETPY

0.0

Section [unitsdistattributes]

Distribution is shifted in p_{y} by this amount after the distribution is generated (or read in). Same as the average p_{y} value, \bar{p}_{y}.

OFFSETPZ

0.0

Section [unitsdistattributes]

Distribution is shifted in p_{z} by this amount after the distribution is generated (or read in). Same as the average p_{z} value, \bar{p}_{z}.

ID1

0.0

Section [unitsdistattributes]

Tracer particle which is written also into data/track_orbit.dat

ID2

0.0

Section [unitsdistattributes]

Tracer particle which is written also into data/track_orbit.dat

1.2.2. Injected Distribution Attributes

Table 5. Definition of distribution attributes that only affect injected beams.
Attribute Name Default Value Units Description

ZMULT

1.0

None

Value used to scale the z positions of the distribution particles. Applied after the distribution is generated (or read in).

OFFSETZ

0.0

m

Distribution is shifted in z by this amount relative to the reference particle. Same as the average z position, \bar{z}.

1.2.3. Emitted Distribution Attributes

Table 6. Definition of distribution attributes that only affect emitted beams.
Attribute Name Default Value Units Description

TMULT

1.0

None

Value used to scale the t values of the distribution particles. Applied after the distribution is generated (or read in).

OFFSETT

0.0

s

Distribution is emitted later by this amount relative to the reference particle.

EMISSIONSTEPS

1

None

Number of time steps to take during emission. The simulation time step will be adjusted during emission to ensure that this many time steps will be required to emit the entire distribution.

EMISSIONMODEL

None

None

Emission model to use when emitting particles from cathode see Section [emissionmodel].

1.3. FROMFILE Distribution Type

The most versatile distribution type is to use a user generated text file as input to OPAL. This allows the user to generate their own distribution, if the built in options in OPAL are insufficient, and have it either injected or emitted into the simulation. In Table [distattrfromfile] we list the single attribute specific to this type of distribution type.

Table 7. Definition of distribution attributes for a FROMFILE distribution type.
Attribute Name Default Value Units Description

FNAME

None

None

File name for text file containing distribution particle coordinates.

An example of an injected FROMFILE distribution definition is:

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

an example of an emitted FROMFILE distribution definition is:

Name:DISTRIBUTION, TYPE = FROMFILE,
                   FNAME = "text file name",
                   EMITTED = TRUE,
                   EMISSIONMODEL = None;

The text input file for the FROMFILE distribution type has slightly a slightly different format, depending on whether the distribution is to be injected or emitted. The injected file format is defined in Table [fromfileinjfileformat]. The emitted file format is defined in Table [fromfileemitfileformat].

Table 8. File format for injected FROMFILE distribution type. N is the number of particles in the file. The particle coordinates are defined in Section [variablesopalt,variablesopalcycl].
N

x_{1}

p_{x1}

y_{1}

p_{y1}

z_{1}

p_{z1}

x_{2}

p_{x2}

y_{2}

p_{y2}

z_{2}

p_{z2}

.

.

x_{N}

p_{xN}

y_{N}

p_{yN}

z_{N}

p_{zN}

Table 9. File format for emitted FROMFILE distribution type. N is the number of particles in the file. The particle coordinates are defined in Section [variablesopalt] except that z, in meters, is replaced by t in seconds.
N

x_{1}

p_{x1}

y_{1}

p_{y1}

t_{1}

p_{z1}

x_{2}

p_{x2}

y_{2}

p_{y2}

t_{2}

p_{z2}

.

.

x_{N}

p_{xN}

y_{N}

p_{yN}

t_{N}

p_{zN}

Note that for an emitted FROMFILE distribution, all of the particle’s time, t, coordinates will be shifted to negative time (if they are not there already). The simulation clock will then start at t = 0 and distribution particles will be emitted into the simulation as the simulation progresses. Also note that, as the particles are emitted, they will be modified according to the type of emission model used. This is defined by the attribute EMISSIONMODEL, which is described in Section [emissionmodel]. A choice of NONE for the EMISSIONMODEL (which is the default) can be defined so as not to affect the distribution coordinates at all.

To maintain consistency N and NPART from the BEAM command in Chapter [beam] must be equal.

1.4. GAUSS Distribution Type

As the name implies, the GAUSS distribution type can generate distributions with a general Gaussian shape (here we show a one-dimensional example):

f(x) = \frac{1}{\sqrt{2 \pi}} e^{-\frac{(x - \bar{x})^{2}}{2 \sigma_{x}^{2}}}

where \bar{x} is the average value of x. However, the GAUSS distribution can also be used to generate an emitted beam with a flat top time profile. We will go over the various options for the GAUSS distribution type in this section.

1.4.1. Simple GAUSS Distribution Type

We will begin by describing how to create a simple GAUSS distribution type. That is, a simple 6-dimensional distribution with a Gaussian distribution in all dimensions.

Table 10. Definition of the basic distribution attributes for a GAUSS distribution type.
Attribute Name Default Value Units Description

SIGMAX

0.0

m

RMS width, \sigma_{x}, in transverse x direction.

SIGMAY

0.0

m

RMS width, \sigma_{y}, in transverse y direction.

SIGMAR

0.0

m

RMS radius, \sigma_{r}, in radial direction. If nonzero SIGMAR overrides SIGMAX and SIGMAY.

SIGMAZ

0.0

m

RMS length, \sigma_{z}, in longitudinal (z) direction. SIGMAZ is used for an injected distribution.

SIGMAT

0.0

s

RMS width, \sigma_{t}, in time (t). SIGMAT is used for an emitted distribution.

SIGMAPX

0.0

Section [unitsdistattributes]

Parameter \sigma_{px} for defining distribution.

SIGMAPY

0.0

Section [unitsdistattributes]

Parameter \sigma_{py} for defining distribution.

SIGMAPZ

0.0

Section [unitsdistattributes]

Parameter \sigma_{pz} for defining distribution.

CUTOFFX

3.0

None

Defines transverse distribution cutoff in the x direction in units of \sigma_{x}. If CUTOFFX = 0 then actual cutoff in x is set to infinity.

CUTOFFY

3.0

None

Defines transverse distribution cutoff in the y direction in units of \sigma_{y}. If CUTOFFY = 0 then actual cutoff in y is set to infinity.

CUTOFFR

3.0

None

Defines transverse distribution cutoff in the r direction in units of \sigma_{r}. If CUTOFFR = 0 then actual cutoff in r is set to infinity. CUTOFFR is only used if SIGMAR >0.

CUTOFFLONG

3.0

None

Defines longitudinal distribution cutoff in the z or t direction (injected or emitted) in units of \sigma_{z} or \sigma_{t}. CUTOFFLONG is different from other dimensions in that a value of 0.0 does not imply a cutoff value of infinity.

CUTOFFPX

3.0

None

Defines cutoff in p_{x} dimension in units of \sigma_{px}. If CUTOFFPX = 0 then actual cutoff in p_{x} is set to infinity.

CUTOFFPY

3.0

None

Defines cutoff in p_{y} dimension in units of \sigma_{py}. If CUTOFFPY = 0 then actual cutoff in p_{y} is set to infinity.

CUTOFFPZ

3.0

None

Defines cutoff in p_{z} dimension in units of \sigma_{pz}. If CUTOFFPZ = 0 then actual cutoff is p_{z} is set to infinity.

In Table [distattrgauss] we list the basic attributes available for a GAUSS distribution. We can use these to create a very simple GAUSS distribution:

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
                   USEEV = TRUE;

This creates a Gaussian shaped distribution with zero transverse emittance, zero energy spread, \sigma_{x} = {1.0}\mathrm{mm}, \sigma_{y} = {3.0}\mathrm{mm}, \sigma_{z} = {2.0}\mathrm{mm} and an average energy of:

W = {1.2}{MeV}

In the x direction, the Gaussian distribution is cutoff at x = 2.0 \times \sigma_{x} = {2.0}\mathrm{mm}. In the y direction it is cutoff at y = 2.0 \times \sigma_{y} = {6.0}\mathrm{mm}. This distribution is injected into the simulation at an average position of (\bar{x},\bar{y},\bar{z})=({1.0}\mathrm{mm}, {-2.0}\mathrm{mm}, {10.0}\mathrm{mm}).

1.4.2. GAUSS Distribution for Photoinjector

Table 11. Definition of additional distribution attributes for an emitted GAUSS distribution type. These are used to generate a distribution with a time profile as illustrated in Figure [flattop].
Attribute Name Default Value Units Description

TPULSEFWHM

0.0

s

Flat top time see Figure [flattop].

TRISE

0.0

s

Rise time see Figure [flattop]. If defined will override SIGMAT.

TFALL

0.0

s

Fall time see Figure [flattop]. If defined will override SIGMAT.

FTOSCAMPLITUDE

0

None

Sinusoidal oscillations can imposed on the flat top in Figure [flattop]. This defines the amplitude of those oscillations in percent of the average flat top amplitude.

FTOSCPERIODS

0

None

Defines the number of oscillation periods imposed on the flat top, t_\mathrm{flattop}, in Figure [flattop].

Figure 1: OPAL emitted GAUSS distribution with flat top.

flattop

A useful feature of the GAUSS distribution type is the ability to mimic the initial distribution from a photoinjector. For this purpose we have the distribution attributes listed in Table [distattremittedgauss]. Using them, we can create a distribution with the time structure shown in Figure [flattop]. This is a half Gaussian rise plus a uniform flat-top plus a half Gaussian fall. To make it more convenient to mimic measured laser profiles, TRISE and TFALL from Table [distattremittedgauss] do not define RMS quantities, but instead are given by (See also Figure [flattop]):

\begin{aligned}
  \mathrm{TRISE} = t_{R} &= \left(\sqrt{2 \ln(10)} - \sqrt{2 \ln \left(\frac{10}{9} \right)} \right) \sigma_{R}\\
  & = 1.6869 \sigma_{R} \\
  \mathrm{TFALL} = t_{F} &= \left(\sqrt{2 \ln(10)} - \sqrt{2 \ln \left(\frac{10}{9} \right)} \right) \sigma_{F}\\
  & = 1.6869 \sigma_{F}\end{aligned}

where \sigma_{R} and \sigma_{F} are the Gaussian, RMS rise and fall times respectively. The flat-top portion of the profile, TPULSEFWHM, is defined as (See also Figure [flattop]):

\mathrm{TPULSEFWHM} = \mathrm{FWHM}_{P} = t_\mathrm{flattop} + \sqrt{2 \ln 2} \left( \sigma_{R} + \sigma_{F} \right)

Total emission time, t_{E}, of this distribution, is a function of the longitudinal cutoff, CUTOFFLONG see Table [distattrgauss], and is given by:

\begin{aligned}
  t_{E}(\mathrm{CUTOFFLONG}) &= \mathrm{FWHM}_{P} - \frac{1}{2} (\mathrm{FWHM}_{R} + \mathrm{FWHM}_{F})
  + \mathrm{CUTOFFLONG} (\sigma_{R} + \sigma_{F}) \\
  &= \mathrm{FWHM}_{P} + \frac{\mathrm{CUTOFFLONG} - \sqrt{2 \ln 2}}{1.6869} (\mathrm{TRISE} + \mathrm{TFALL})\end{aligned}

Finally, we can also impose oscillations over the flat-top portion of the laser pulse in Figure [flattop], t_\mathrm{flattop}. This is defined by the attributes FTOSCAMPLITUDE and FTOSCPERIODS from Table [distattremittedgauss]. FTOSCPERIODS defines how many oscillation periods will be present during the t_\mathrm{flattop} portion of the pulse. FTOSCAMPLITUDE defines the amplitude of those oscillations in percentage of the average profile amplitude during t_\mathrm{flattop}. So, for example, if we set \mathrm{FTOSCAMPLITUDE} = 5, and the amplitude of the profile is equal to 1.0 during t_\mathrm{flattop}, the amplitude of the oscillation will be 0.05.

1.4.3. Correlations for GAUSS Distribution (Experimental)

Table 12. Definition of additional distribution attributes for a GAUSS distribution type for generating correlations in the beam.
Attribute Name Default Value Units Description

CORRX

0.0

Section [unitsdistattributes]

x, p_x correlation. (R_{12} in transport notation.)

CORRY

0.0

Section [unitsdistattributes]

y, p_y correlation. (R_{34} in transport notation.)

CORRZ

0.0

Section [unitsdistattributes]

z, p_z correlation. (R_{56} in transport notation.)

R51

0.0

Section [unitsdistattributes]

x, z correlation. (R_{51} in transport notation.)

R52

0.0

Section [unitsdistattributes]

p_x, z correlation. (R_{52} in transport notation.)

R61

0.0

Section [unitsdistattributes]

x, p_z correlation. (R_{61} in transport notation.)

R62

0.0

Section [unitsdistattributes]

p_x, p_z correlation. (R_{62} in transport notation.)

To generate Gaussian initial distribution with dispersion, first we generate the uncorrelated Gaussian inputs matrix R=(R1,...,R_n). The mean of R_i is 0 and the standard deviation squared is 1. Then we correlate R. The correlation coefficient matrix \sigma in x, p_x, z, p_z phase space reads:

\sigma= \left[
\begin{array}{cccc}
1    &c_x  &r51    &r61\\
c_x  &1    &r52    &r62\\
r51  &r52  &1      &c_t\\
r61  &r62  &c_t    &1
\end{array}
\right]

The Cholesky decomposition of the symmetric positive-definite matrix \sigma is \sigma=C^{\mathbf{T}}C, then the correlated distribution is C^{\mathbf{T}}R.

Note: Correlations work for the moment only with the Gaussian distribution and are experimental, so there are no guarantees as to its efficacy or accuracy. Also, these correlations will work, in principle, for an emitted beam. However, recall that in this case, z in meters is replaced by t in seconds, so take care.

As an example of defining a correlated beam, let the initial correlation coefficient matrix be:

\sigma= \left[
\begin{array}{cccc}
1      &0.756  &0.023    &0.496\\
0.756  &1      &0.385    &-0.042\\
0.023  &0.385  &1        &-0.834\\
0.496  &-0.042 &-0.834   &1
\end{array}
\right]

then the corresponding distribution command will read:

Dist:DISTRIBUTION, TYPE = GAUSS,
                   SIGMAX = 4.796e-03,
                   SIGMAPX = 231.0585,
                   CORRX = 0.756,
                   SIGMAY = 23.821e-03,
                   SIGMAPY = 1.6592e+03,
                   CORRY = -0.999,
                   SIGMAZ = 0.466e-02,
                   SIGMAPZ = 74.7,
                   CORRZ = -0.834,
                   OFFSETZ = 0.466e-02,
                   OFFSETPZ = 72e6,
                   R61 = 0.496,
                   R62 = -0.042,
                   R51 = 0.023,
                   R52 = 0.385;

1.5. FLATTOP Distribution Type

The FLATTOP distribution type is used to define hard edge beam distributions. Hard edge, in this case, means a more or less uniformly filled cylinder of charge, although as we will see this is not always the case. The main purpose of the FLATTOP is to mimic laser pulses in photoinjectors, and so we usually will make this an emitted distribution. However it can be injected as well.

1.5.1. Injected FLATTOP

The attributes for an injected FLATTOP distribution are defined in Table [distattrflattopinj,distattruniversal]. At the moment, we cannot define a spread in the beam momentum, so an injected FLATTOP distribution will currently have zero emittance. An injected FLATTOP will be a uniformly filled ellipse transversely with a uniform distribution in z. (Basically a cylinder with an elliptical cross section.)

Table 13. Definition of the basic distribution attributes for an injected FLATTOP distribution type.
Attribute Name Default Value Units Description

SIGMAX

0.0

m

Hard edge width in x direction.

SIGMAY

0.0

m

Hard edge width in y direction.

SIGMAR

0.0

m

Hard edge radius. If nonzero SIGMAR overrides SIGMAX and SIGMAY.

SIGMAZ

0.0

m

Hard edge length in z direction.

1.5.2. Emitted FLATTOP

Table 14. Definition of the basic distribution attributes for an emitted FLATTOP distribution type.
Attribute Name Default Value Units Description

SIGMAX

0.0

m

Hard edge width in x direction.

SIGMAY

0.0

m

Hard edge width in y direction.

SIGMAR

0.0

m

Hard edge radius. If nonzero SIGMAR overrides SIGMAX and SIGMAY.

SIGMAT

0.0

s

RMS rise and fall of half Gaussian in flat top defined in in Figure [flattop].

TPULSEFWHM

0.0

s

Flat top time. See Figure [flattop].

TRISE

0.0

s

Rise time. See Figure [flattop]. If defined will override SIGMAT.

TFALL

0.0

s

Fall time. See Figure [flattop]. If defined will override SIGMAT.

FTOSCAMPLITUDE

0

None

Sinusoidal oscillations can imposed on the flat top in Figure [flattop]. This defines the amplitude of those oscillations in percent of the average flat top amplitude.

FTOSCPERIODS

0

None

Defines the number of oscillation periods imposed on the flat top, t_\mathrm{flattop}, in Figure [flattop].

LASERPROFFN

None

File name containing measured laser image.

IMAGENAME

None

Name of the file containing the laser image.

INTENSITYCUT

0.0

None

Parameter defining floor of the background to be subtracted from the laser image in percent of the maximum intensity.

FLIPX

FALSE

Flip the laser profile in horizontal direction.

FLIPY

FALSE

Flip the laser profile in vertical direction.

ROTATE90

FALSE

Rotate the laser profile 90^{\circ} in counterclockwise direction.

ROTATE180

FALSE

Rotate the laser profile 180^{\circ}.

ROTATE270

FALSE

Rotate the laser profile 270^{\circ} in counterclockwise direction.

The attributes of an emitted FLATTOP distribution are defined in Table [distattrflattopemit,distattruniversal]. The FLATTOP distribution was really intended for this mode of operation in order to mimic common laser pulses in photoinjectors. The basic characteristic of a FLATTOP is a uniform, elliptical transverse distribution and a longitudinal (time) distribution with a Gaussian rise and fall time as described in Section [gaussdisttypephotoinjector]. Below we show an example of a FLATTOP distribution command with an elliptical cross section of 1mm by 2mm and a flat top, in time, 10ps long with a 0.5ps rise and fall time as defined in Figure [flattop].

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;

1.5.3. Transverse Distribution from Laser Profile (Under Development)

An alternative to using a uniform, elliptical transverse profile is to define the LASERPROFFN, IMAGENAME and INTENSITYCUT attributes from Table [distattrflattopemit]. Then, OPAL-t will use the laser image as the basis to sample the transverse distribution.

This distribution option is not yet available.

1.5.4. GUNGAUSSFLATTOPTH Distribution Type

This is a legacy distribution type. A GUNGAUSSFLATTOPTH is the equivalent of a FLATTOP distribution, except that the EMITTED attribute will set to TRUE automatically and the EMISSIONMODEL will be automatically set to ASTRA.

1.5.5. ASTRAFLATTOPTH Distribution Type

This is a legacy distribution type. A ASTRAFLATTOPTH is the equivalent of a FLATTOP distribution, except that the EMITTED attribute will set to TRUE automatically and the EMISSIONMODEL will be automatically set to ASTRA. There are a few other differences with how the longitudinal time profile of the distribution is generated.

1.6. BINOMIAL Distribution Type

The BINOMIAL type of distribution is based on [JohoDist]. The shape of the binomial distribution is governed by one parameter m. By varying this single parameter one obtains the most commonly used distributions for our type of simulations, as listed in Table [binomdist].

Table 15. Different distributions specified by a single parameter m
m Distribution Density Profile

0.0

Hollow shell

\frac{1}{\pi}\delta(1-r^2)

\frac{1}{\pi}(1-r^2)^{-0.5}

0.5

Flat profile

\frac{1}{2\pi}(1-r^2)^{-0.5}

\frac{1}{2}

1.0

Uniform

\frac{1}{\pi}

\frac{2}{\pi}(1-x^2)^{0.5}

1.5

Elliptical

\frac{3}{2\pi}(1-r^2)^{0.5}

\frac{1}{4}(1-x^2)

2.0

Parabolic

\frac{2}{\pi}(1-r^2)

\frac{3}{8\pi}(1-x^2)^{1.5}

\rightarrow \infty

Gaussian

\frac{1}{2\pi\sigma_x\sigma_y}exp(-\frac{x^2}{2\sigma_x^2} -\frac{y^2}{2\sigma_y^2})

\frac{1}{\sqrt{2\pi}*\sigma_x}exp(-\frac{x^2}{2\sigma_x^2})

1.7. Emission Models

When emitting a distribution from a cathode, there are several ways in which we can model the emission process in order to calculate the thermal emittance of the beam. In this section we discuss the various options available.

1.7.1. Emission Model: NONE (default)

The emission model NONE is the default emission model used in OPAL-t. It has a single attribute, listed in Table [distattremitmodelnoneastra]. The NONE emission model is very simplistic. It merely adds the amount of energy defined by the attribute EKIN to the longitudinal momentum, p_{z}, for each particle in the distribution as it leaves the cathode.

Table 16. Attributes for the NONE and ASTRA emission models.
Attribute Name Default Value Units Description

EKIN

1.0

eV

Thermal energy added to beam during emission.

An example of using the NONE emission model is given below. This option allows us to emit transversely cold (zero x and y emittance) beams into our simulation. We must add some z momentum to ensure that the particles drift into the simulation space. If in this example one were to specify EKIN = 0, then you would likely get strange results as the particles would not move off the cathode, causing all of the emitted charge to pile up at z = 0 in the first half time step before the beam space charge is calculated.

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 = NONE,
                   EKIN = 0.5,
                   EMITTED = TRUE;

One thing to note, it may be that if you are emitting your own distribution using the TYPE = FROMFILE option, you may want to set EKIN = 0 if you have already added some amount of momentum, p_{z}, to the particles.

1.7.2. Emission Model: ASTRA

The ASTRA emittance model uses the same single parameter as the NONE option as listed in Table [distattremitmodelnoneastra]. However, in this case, the energy defined by the EKIN attribute is added to each emitted particle’s momentum in a random way:

\begin{aligned}
    p_{total} &= \sqrt{\left(\frac{\mathrm{EKIN}}{mc^{2}} + 1\right)^{2} - 1} \\
    p_{x} &= p_{total} \sin(\phi) \cos(\theta)) \\
    p_{y} &= p_{total} \sin(\phi) \sin(\theta)) \\
    p_{z} &= p_{total} |{\cos(\theta)}|
  \end{aligned}

where \theta is a random angle between 0 and \pi, and \phi is given by

\phi = 2.0 \arccos \left( \sqrt{x} \right)

with x a random number between 0 and 1.

1.7.3. Emission Model: NONEQUIL

The NONEQUIL emission model is based on an actual physical model of particle emission as described in [flo:97, clen:2000, dowe:2009]. The attributes needed by this emission model are listed in Table [distattremitmodelnonequil].

Table 17. Attributes for the NONE and ASTRA emission models.
Attribute Name Default Value Units Description

ELASER

4.86

eV

Photoinjector drive laser energy. (Default is 255nm light.)

W

4.31

eV

Photocathode work function. (Default is atomically clean copper.)

FE

7.0

eV

Fermi energy of photocathode. (Default is atomically clean copper.)

CATHTEMP

300.0

K

Operating temperature of photocathode.

An example of using the NONEQUIL emission model is given below. This model is relevant for metal cathodes and cathodes such as CsTe.

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;

1.8. Distribution List

It is possible to use multiple distributions in the same simulation. We do this be using a distribution list in the RUN command see Chapter [track]. Assume we have defined several distributions: DIST1, DIST2 and DIST3. If we want to use just one of these distributions in a simulation, we would use the following RUN command to start the simulation:

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

If we want to use all the distributions at the same time, then the command would instead be:

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

In this second case, the first distribution (DIST1) is the master distribution. The main consequence of this is that all distributions in the list will be forced to the same EMITTED condition as DIST1. So, if DIST1 is to be emitted, then all other distributions in the list will be forced to this same condition. If DIST1 is to be injected, then all other distribution is the list will also be injected.

The number of particles in the simulation is defined in the BEAM command see Chapter [beam]. The number of particles in each distribution in a distribution list is determined by this number and the WEIGHT attribute of each distribution (Table [distattruniversal]). If all distributions have the same WEIGHT value, then the number of particles will be divided up evenly among them. If, however we have a distribution list consisting of two distributions, and one has twice the WEIGHT of the other, then it will have twice the particles as its partner. The exception here is any FROMFILE distribution type. In this case, the WEIGHT attribute and the number of particles in the BEAM command are ignored. The number of particles in any FROMFILE distribution type is defined by the text file containing the distribution particle coordinates. (Section [fromfiledisttype]).

Clone repository
  • autophase
  • beam command
  • benchmarks
  • control
  • conventions
  • distribution
  • elements
  • fieldmaps
  • fieldsolvers
  • format
  • geometry
  • Home
  • introduction
  • lines
  • opal madx
View All Pages