Beams

The beam object is the root object of beams that store information relative to particles and particle beams. It also provides a simple interface to the particles and nuclei database.

The beam module extends the typeid module with the is_beam function, which returns true if its argument is a beam object, false otherwise.

Attributes

The beam object provides the following attributes:

particle

A string specifying the name of the particle. (default: "positron").

mass

A number specifying the energy-mass of the particle [GeV]. (default: emass).

charge

A number specifying the charge of the particle in [q] unit of qelect. [1] (default: 1).

spin

A number specifying the spin of the particle. (default: 0).

emrad

A lambda returning the electromagnetic radius of the particle [m],

\(\mathrm{emrad} = \mathrm{krad_GeV}\times\mathrm{charge}^2/\mathrm{mass}\) where \(\mathrm{krad_GeV} = 10^{-9} (4 \pi\varepsilon_0)^{-1} q\).

aphot

A lambda returning the average number of photon emitted per bending unit,

\(\mathrm{aphot} = \mathrm{kpht_GeV}\times\mathrm{charge}^2\times\mathrm{betgam}\) where \(\mathrm{kpht_GeV}\) \(= \frac{5}{2\sqrt{3}}\) \(\mathrm{krad_GeV}\) \((\hbar c)^{-1}\).

energy

A number specifying the particle energy [GeV]. (default: 1).

pc

A lambda returning the particle momentum times the speed of light [GeV],

\(\mathrm{pc} = (\mathrm{energy}^2 - \mathrm{mass}^2)^{\frac{1}{2}}\).

beta

A lambda returning the particle relativistic \(\beta=\frac{v}{c}\),

\(\mathrm{beta} = (1 - (\mathrm{mass}/\mathrm{energy})^2)^{\frac{1}{2}}\).

gamma

A lambda returning the particle Lorentz factor \(\gamma=(1-\beta^2)^{-\frac{1}{2}}\),

\(\mathrm{gamma} = \mathrm{energy}/\mathrm{mass}\).

betgam

A lambda returning the product \(\beta\gamma\),

\(\mathrm{betgam} = (\mathrm{gamma}^2 - 1)^\frac{1}{2}\).

pc2

A lambda returning \(\mathrm{pc}^2\), avoiding the square root.

beta2

A lambda returning \(\mathrm{beta}^2\), avoiding the square root.

betgam2

A lambda returning \(\mathrm{betgam}^2\), avoiding the square root.

brho

A lambda returning the magnetic rigidity [T.m],

brho = GeV_c * pc/|charge| where GeV_c = \(10^{9}/c\)

ex

A number specifying the horizontal emittance \(\epsilon_x\) [m]. (default: 1).

ey

A number specifying the vertical emittance \(\epsilon_y\) [m]. (default: 1).

et

A number specifying the longitudinal emittance \(\epsilon_t\) [m]. (default: 1e-3).

exn

A lambda returning the normalized horizontal emittance [m],

exn = ex * betgam.

eyn

A lambda returning the normalized vertical emittance [m],

eyn = ey * betgam.

etn

A lambda returning the normalized longitudinal emittance [m],

etn = et * betgam.

nbunch

A number specifying the number of particle bunches in the machine. (default: 0).

npart

A number specifying the number of particles per bunch. (default: 0).

sigt

A number specifying the bunch length in \(c \sigma_t\). (default: 1).

sige

A number specifying the relative energy spread in \(\sigma_E/E\) [GeV]. (default: 1e-3).

The beam object also implements a special protect-and-update mechanism for its attributes to ensure consistency and precedence between the physical quantities stored internally:

The following attributes are read-only, i.e. writing to them triggers an error:

mass, charge, spin, emrad, aphot
The following attributes are read-write, i.e. hold values, with their accepted numerical ranges:

particle, energy \(>\) mass, ex \(>0\), ey \(>0\), et \(>0\), nbunch \(>0\), npart \(>0\), sigt \(>0\), sige \(>0\).
The following attributes are read-update, i.e. setting these attributes update the energy, with their accepted numerical ranges:

pc \(>0\), \(0.9>\) beta \(>0\), gamma \(>1\), betgam \(>0.1\), brho \(>0\), pc2, beta2, betgam2.
The following attributes are read-update, i.e. setting these attributes update the emittances ex, ey, and et repectively, with their accepted numerical ranges:

exn \(>0\), eyn \(>0\), etn \(>0\).

Methods

The beam object provides the following methods:

new_particle: A method (particle, mass, charge, [spin]) creating new particles or nuclei and store them in the particles database. The arguments specify in order the new particle’s name, energy-mass [GeV], charge [q], and spin (default: 0). These arguments can also be grouped into a table with same attribute names as the argument names and passed as the solely argument.
set_variables: A method (set) returning self with the attributes set to the pairs (key, value) contained in set. This method overrides the original one to implement the special protect-and-update mechanism, but the order of the updates is undefined. It also creates new particle on-the-fly if the mass and the charge are defined, and then select it. Shortcut setvar.
showdb: A method ([file]) displaying the content of the particles database to file (default: io.stdout).

Metamethods

The beam object provides the following metamethods:

__init: A metamethod () returning self after having processed the attributes with the special protect-and-update mechanism, where the order of the updates is undefined. It also creates new particle on-the-fly if the mass and the charge are defined, and then select it.
__newindex: A metamethod (key, val) called by the assignment operator [key]=val to create new attributes for the pairs (key, value) or to update the underlying physical quantity of the beam objects.

The following attribute is stored with metamethods in the metatable, but has different purpose:

__beam: A unique private reference that characterizes beams.

Particles database

The beam object manages the particles database, which is shared by all beam instances. The default set of supported particles is:

electron, positron, proton, antiproton, neutron, antineutron, ion, muon, antimuon, deuteron, antideuteron, negmuon (=muon), posmuon (=antimuon).

New particles can be added to the database, either explicitly using the new_particle method, or by creating or updating a beam object and specifying all the attributes of a particle, i.e. particle’s name, charge, mass, and (optional) spin:

local beam in MAD
local nmass, pmass, mumass in MAD.constant

-- create a new particle
beam:new_particle{ particle='mymuon', mass=mumass, charge=-1, spin=1/2 }

-- create a new beam and a new nucleus
local pbbeam = beam { particle='pb208', mass=82*pmass+126*nmass, charge=82 }

The particles database can be displayed with the showdb method at any time from any beam:

beam:showdb()  -- check that both, mymuon and pb208 are in the database.

Particle charges

The physics of MAD-NG is aware of particle charges. To enable the compatibility with codes like MAD-X that ignores the particle charges, the global option nocharge can be used to control the behavior of created beams as shown by the following example:

local beam, option in MAD
local beam1 = beam { particle="electron" } -- beam with negative charge
print(beam1.charge, option.nocharge)       -- display: -1  false

option.nocharge = true                     -- disable particle charges
local beam2 = beam { particle="electron" } -- beam with negative charge
print(beam2.charge, option.nocharge)       -- display:  1  true

-- beam1 was created before nocharge activation...
print(beam1.charge, option.nocharge)       -- display: -1  true

This approach ensures consistency of beams behavior during their entire lifetime. [2]

Examples

The following code snippet creates the LHC lead beams made of bare nuclei \(^{208}\mathrm{Pb}^{82+}\)

local beam in MAD
local lhcb1, lhcb2 in MADX
local nmass, pmass, amass in MAD.constant
local pbmass = 82*pmass+126*nmass

-- attach a new beam with a new particle to lhcb1 and lhcb2.
lhc1.beam = beam 'Pb208' { particle='pb208', mass=pbmass, charge=82 }
lhc2.beam = lhc1.beam -- let sequences share the same beam...

-- print Pb208 nuclei energy-mass in GeV and unified atomic mass.
print(lhcb1.beam.mass, lhcb1.beam.mass/amass)

Footnotes