Input Syntax

BDSIM is controlled by input text (ASCII) files that define the model, physics and options in its own GMAD syntax.

GMAD Syntax

GMAD is a language specifically for BDSIM that is made to be human readable. The name comes from the design intention of MAD-X syntax and extensions for Geant4. While GMAD is very similar to MAD-X, not all MAD-X commands are supported.

  • S.I. units are used except where explicitly specified

  • Variables can be defined using name = value; syntax

  • Arithmetic expressions can be defined

  • Binary operators +, -, *, /, ^, are valid

  • Unary operators +, -, are valid

  • Boolean operators <, >, <=, >=, <> (not equal), ==, are valid

  • Every expression must end with a semi-colon;

  • No variable name can begin with a number

  • !Comments start with an exclamation mark “!”

  • A variable may inherit values (via copy) from another variable using newvariable : existingvariable;

Extending Objects

If an object (or beam line element) is already defined, a parameter can be updated in it. We call this ‘extending’ the object. Examples can be found in bdsim/parser/test/extend*. E.g.

d1: drift, l=1*m;
print, d1;
! now we update the d1 definition
d1: aper1=5*cm;

Note

Beam line elements can only effectively be updated before the use command is called as this command will copy the current definitions to a new place in memory.

Warning

When extending an object the parameter “type” must not be used first after the semi-colon. This is a limitation of the parser that understands the input syntax. Any other parameter can be updated first then (if appropriate) “type” can be set.

Mathematical Functions

The following mathematical functions are provided:

  • sqrt

  • cos

  • sin

  • tan

  • exp

  • log

  • acos

  • asin

  • atan

  • abs

Other Commands

  • print; Prints all elements

  • print, line; Prints all elements that are in the beam line defined by use. See also use - Defining which Line to Use.

  • print, option; Prints the value of some options

  • print, variable; Prints the value of a numerical variable, which could be your own defined variable

  • length = d1["l"]; A way to access properties of elements, in this case, length of element d1.

  • stop; or return; Exists parser

  • if () {}; ‘if’ construct

  • if () {} else {}; ‘if-else’ construct

  • include ../some/other/file.gmad; Includes another file to be parsed. Note that the path provided must be relative, not absolute.

Examples

Examples:

x = 1;
y = 2.5-x;
z = sin(x) + log(y) - 8e5;
mat = "copper";

Floating Point and Integer Numbers

The result of a calculation may be a floating point number. If assigned to what should be an integer value, such as the number of bins in a scoring mesh, the number is rounded to the nearest integer.

Common Pitfalls

The following is an example of a common mistake that’s not easy to spot:

beam, particle="e-",
      energy=3*TeV;
      E0=1*TeV;

With this syntax we expect to create a design beam of 3 TeV electrons but the central energy of 1 TeV for the bunch. 3 TeV is used to calculate the magnet strengths and it’s expected to fire a 1 TeV electron. However, the E0 parameter here just defines a variable called E0 that isn’t used. The indentation (white-space) is ignored. The error is the semi-colon at the end of the second line. This is the correct version:

beam, particle="e-",
      energy=3*TeV,
      E0=1*TeV;

Coordinates & Units

In Geant4, global Euclidean coordinates are used for tracking purposes. However, in describing a lattice with BDSIM, curvilinear coordinates are used, as is common with accelerators (X,Y,S).

GMAD uses SI units

Name

Units

length

[m] (metres)

time

[s] (seconds)

angle

[rad] (radians)

quadrupole coefficient

[m \(^{-2}\) ]

multipole coefficient 2n poles

[m \(^{-n}\) ]

electric voltage

[V] (Volts)

electric field strength

[V/m]

particle energy

[GeV]

particle mass

[GeV/c \(^2\) ]

particle momentum

[GeV/c \(^2\) ]

beam current

[A] (Amperes)

particle charge

[e] (elementary charges)

emittance

[pi m mrad]

density

[g/cm \(^{3}\) ]

temperature

[K] (Kelvin)

pressure

[atm] (atmosphere)

frequency

[Hz] (Hertz)

mass number

[g/mol]

Some useful predefined values / units are:

Name

Value

pi

3.14159265358979

twopi

2 * pi

halfpi

0.5 * pi

degrees

\(\pi\) / 180

GeV

1

eV

\(10^{-9}\)

keV

\(10^{-6}\)

MeV

\(10^{-3}\)

TeV

\(10^{3}\)

PeV

\(10^{6}\)

J

1

PJ

\(10^{12}\)

GJ

\(10^{9}\)

MJ

\(10^{6}\)

kJ

\(10^{3}\)

mJ

\(10^{-3}\)

uJ

\(10^{-6}\)

nJ

\(10^{-9}\)

pJ

\(10^{-12}\)

V

1

mV

\(10^{-3}\)

kV

\(10^{3}\)

MV

\(10^{6}\)

GV

\(10^{9}\)

Tesla

1

T

1

rad

1

mrad

\(10^{-3}\)

urad

\(10^{-6}\)

nrad

\(10^{-9}\)

clight

\(2.99792458 \times 10^{8}\)

km

\(10^{3}\)

m

1

cm

\(10^{-2}\)

mm

\(10^{-3}\)

um

\(10^{-6}\)

mum

\(10^{-6}\)

nm

\(10^{-9}\)

ang

\(10^{-10}\)

pm

\(10^{-12}\)

s

1

ms

\(10^{-3}\)

us

\(10^{-6}\)

ns

\(10^{-9}\)

ps

\(10^{-12}\)

Hz

1

kHz

\(10^{3}\)

MHz

\(10^{6}\)

GHz

\(10^{9}\)

THz

\(10^{12}\)

As an example, one can write either 100*eV or 0.1*keV to specify an energy value in GMAD. Both are equivalent.