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 for PARTICLE=MUON and PARTICLE=PION.
  • DAUGHTERBEAM is optional. Without it, decayed particles are only removed.
  • DAUGHTERBEAM must name another beam selected by the same TRACK command. 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=MUON daughter beam, and a muon beam a PARTICLE=ELECTRON daughter beam.
  • A decay keeps the charge: the daughter beam must have the same CHARGE as its parent. The default charges are \(+1\) for PION and \(-1\) for MUON and ELECTRON, so set CHARGE where needed. For \(\mu^+\to e^+\), use PARTICLE=ELECTRON, CHARGE=1; PARTICLE=POSITRON is rejected as a daughter.
  • A beam selected as a DAUGHTERBEAM must omit GAMMA, ENERGY, PC, and SOURCES. It inherits the reference particle and frame of the first source beam in its decay chain. The first entry of TRACK.BEAMS must 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:

  • MASS in GeV
  • CHARGE in elementary-charge units

16.7 Beam Energy

There are three standard energy attributes, with the usual priority:

  • GAMMA
  • ENERGY
  • PC

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.