16 Beam Definitions
BEAM defines the physical species and reference state for one particle container. A typical generated distribution uses:
Beam1: BEAM, PARTICLE=ELECTRON, PC=0.1,
NALLOC=100000, BCHARGE=1e-9, SOURCES=Sources1;
BCHARGE is normally given as a positive charge magnitude. OPALX obtains the macroparticle sign from CHARGE, which defaults to the selected particle’s charge. The named emission-source list must exist when RUN resolves the beam.
16.1 Parameters
| Parameter | Default | Unit | Current behavior |
|---|---|---|---|
PARTICLE |
none | - | Selects a predefined species. If omitted, both MASS and CHARGE are required. |
MASS |
species value | GeV/\(c^2\) | Overrides the predefined rest mass, or defines a custom species with CHARGE. |
CHARGE |
species value | \(e\) | Charge in proton-charge units. It also determines the macroparticle charge sign. |
ENERGY |
unset | GeV | Total charged-particle energy; must exceed MASS. |
PC |
unset | GeV/\(c\) | Reference momentum; must be positive. |
GAMMA |
unset | - | Reference Lorentz factor; must be greater than one. |
BCHARGE |
0 |
C | Bunch-charge magnitude used with NALLOC to calculate macroparticle charge. |
NALLOC |
required | particles | Positive allocation and macroparticle-weight baseline. Real input is converted to an integer size. |
SOURCES |
required | name | EMISSIONSOURCELIST used by a source beam; forbidden on a beam selected as another beam’s DAUGHTERBEAM. |
GLOBALPROCESSES |
empty | names | Uppercase array of global processes. Only DECAY is currently accepted. |
DAUGHTERBEAM |
empty | name | Beam/container that receives daughter particles from a configured decay. |
POLARIZATION |
unset | - | Muon-only vector {Px, Py, Pz} with \(|\mathbf P|\leq1\); requires PARTICLE. Setting it, including to zero, enables spin tracking. Every particle starts with this vector, given along the same axes as the distribution momenta. |
BCURRENT, BFREQ |
unset | - | Legacy attributes explicitly rejected by OPALX; use BCHARGE. |
The additional TUNEINITIAL array supplies repeated triples {kinetic_energy_GeV, radius_m, radial_momentum_mc, ...} to the experimental RUN,SPECTRALTUNES=TRUE diagnostic. It does not replace the ordinary source distribution. See Tune Calculation.
The predefined PARTICLE values are PHOTON, ELECTRON, POSITRON, MUON, PION, PROTON, ANTIPROTON, DEUTERON, HMINUS, H2P, ALPHA, CARBON, XENON, and URANIUM.
16.2 Reference energy
For generated distributions, set one of GAMMA, ENERGY, or PC. If more than one is supplied, the implementation currently uses GAMMA before ENERGY, and ENERGY before PC; relying on that precedence is discouraged.
FROMFILE and EMITTEDFROMFILE carry absolute particle momenta. A beam using either type must omit all three reference-energy attributes. See Beam and Distributions for their file conventions.
16.3 Allocation and sources
NALLOC is required and must be positive. It remains the denominator used to derive macroparticle charge even when the sum of NPARTDIST over all sources sets a different runtime allocation. For a source beam with N generated particles, the total charge magnitude is N * BCHARGE / NALLOC; set NALLOC=N when the generated bunch should carry BCHARGE. Keep allocation and particle counts consistent unless a different weighting is intentional.
Each tracked source beam requires a non-empty SOURCES name. The target list must contain at least one EMISSIONSOURCE; it is resolved during RUN. A decay daughter beam receives particles only from its parent decay and must omit SOURCES.
16.4 Multiple species, decay, and spin
Use TRACK.BEAMS to select several beam definitions in a fixed order. OPALX creates one particle container per entry. For decay calculations:
GLOBALPROCESSES={DECAY}is implemented forPARTICLE=MUONandPARTICLE=PION.DAUGHTERBEAMis optional. Without it, decayed particles are only removed.DAUGHTERBEAMmust name another beam selected by the sameTRACKcommand. A beam can be the daughter beam of only one beam, and the settings must not form a loop. Chains such as pion to muon to electron are allowed.- The daughter species is fixed: a pion beam needs a
PARTICLE=MUONdaughter beam, and a muon beam aPARTICLE=ELECTRONdaughter beam. - A decay keeps the charge: the daughter beam must have the same
CHARGEas its parent. The default charges are \(+1\) forPIONand \(-1\) forMUONandELECTRON, so setCHARGEwhere needed. For \(\mu^+\to e^+\), usePARTICLE=ELECTRON, CHARGE=1;PARTICLE=POSITRONis rejected as a daughter. - A beam selected as a
DAUGHTERBEAMmust omitGAMMA,ENERGY,PC, andSOURCES. It inherits the reference particle and frame of the first source beam in its decay chain. The first entry ofTRACK.BEAMSmust be a source beam, not a decay daughter. - Parent and daughter beams must represent one physical particle per macroparticle:
BCHARGE = NALLOC * |CHARGE| * q_e. - Muon decay requires
POLARIZATION. A daughter muon beam also needs it so the container stores spin; the decay sets each daughter’s value.
The Decay Processes chapter gives the physics model and validation.
16.5 Photon definitions
Not yet implemented Photon beams require positive ENERGY and NALLOC, and reject MASS, CHARGE, PC, GAMMA, and SOURCES. BEAM.ENERGY uses GeV. Photon transport is not yet available.
The BEAM command defines the particle species, reference energy or momentum, and global beam properties used by tracking and diagnostics.
label: BEAM, PARTICLE=name, MASS=real, CHARGE=real,
ENERGY=real, PC=real, GAMMA=real, BCURRENT=real,
NPART=real, BFREQ=real;
The label is optional and defaults to UNNAMED_BEAM.
16.6 Particle Definition
PARTICLE selects one of the predefined species such as ELECTRON, POSITRON, MUON, PROTON, DEUTERON, HMINUS, H2P, ALPHA, CARBON, XENON, or URANIUM.
For custom species, the user can provide:
MASSinGeVCHARGEin elementary-charge units
16.7 Beam Energy
There are three standard energy attributes, with the usual priority:
GAMMAENERGYPC
16.8 Other Attributes
The other important beam attributes are:
BFREQ-
bunch frequency in
MHz. BCURRENT-
bunch current in
A. NPART- number of macro particles used in the simulation.
NSLICE- number of slices per bunch.
MOMENTUMTOLERANCE- tolerance used when checking consistency between the distribution and the reference momentum.