EUROPEAN ORGANIZATION FOR NUCLEAR RESEARCH
Beam Line Sequences
MAD-X accepts two forms of an accelerator definition: sequences and
lines. However, the sequence definition is the
only one used internally; lines are converted into sequences when they
are USEd. Consequently, only sequences can be saved (written onto a file)
by MAD-X.
The corresponding sequence of statements defining a sequence is
name: SEQUENCE, L=real, REFER=keyword, REFPOS=name,
ADD_PASS=integer, NEXT_SEQU='seq_name';
...
label: class, AT=real, FROM=name {,attributes};
class, AT=real, FROM=name;
sequ_name, AT=real, FROM=name;
...
ENDSEQUENCE;
where "real" means a real number, variable, or expression.
The first line declares a sequence with the given name and provides key parameters:
- L=real: specifies the total length of the sequence in meters.
(Default: 0 m)
- REFER=keyword from {ENTRY,CENTRE,EXIT}:
specifies which part of the element is taken as the reference point
at which the position along the beamline is given.
(default: CENTRE)
- REFPOS=name: specifies the name of an element in this sequence
to be used as the reference point for the insertion of this sequence
in another sequence.
- ADD_PASS=integer: specifies a number of additionnal passes (maximum 5)
through the structure; in case of an RBEND the angle will be overwritten in
SURVEY using the i-th component ( where 1 <= i <= add_pass <= 5)
of its array_of_angles (see RBEND).
- NEXT_SEQU=name: specifies the name of a sequence to be concatenated
to the end of this sequence.
Inside the SEQUENCE ... ENDSEQUENCE bracketing keywords, three types of commands
may appear:
- an element declaration as usual, with an additional "AT" attribute
giving the element position relative to the start of the sequence;
CAUTION: an existing definition for an element with the same name will
be replaced, however, defining the same element twice inside the same
sequence results in a fatal error, since a unique object (this element)
would be placed at two different positions.
- a class name with a position; this causes an instance of the class
to be placed at the position given. For use in ranges, instances
of the same class can be accessed with an occurrence count.
- a sequence name with a position; this causes the sequence with that
name (inserted sequence) to be placed at the position indicated relative
to the start of the current containing sequence.
Depending upon the REFER= attribute of the current (containing) sequence,
the entry, centre, or exit of the inserted sequence is placed at the
position specified.
HOWEVER, if the inserted sequence has a "REFPOS" attribute containing the
name of an element in the inserted sequence, the inserted sequence is placed
such that the element pointed to by REFPOS is at the location specified in the
current sequence.
The additional arguments that can be given in the declaration of sequence
elements or sub-sequences are:
- AT=real: specifies the location at which the reference point
(entry, centre or exit) of the element is to be placed on the beamline.
The value is absolute with reference to the start of the sequence, unless
a FROM= argument is specified.
- FROM=name: specifies the name of an element of the same sequence.
The location given for the current element or sequence in the AT= argument
is then taken as RELATVE to the position of the center of the element given
by the FROM= argument.
Only simple elements should be used in FROM; specifying a sequence
as the FROM reference can lead to erroneous sequence expansion at best.
When the sequence is expanded in a
USE command,
MAD-X generates the missing drift spaces according to the following rules:
- When the distance between the exit of the previous element and the entrance
of the next element is positive and greater than a threshold of one micrometer
an explicit drit is generated with its own name, unless an already existing
drift space with the same length (within 10**(-12)m tolerance) can be
re-used.
- When the absolute value of the distance between the exit of the previous
element and the entrance of the next element is less than a given tolerance
of one micrometer, no drift space is created and the elements are considered
as contiguous.
Note that in very specific cases this can cause very small errors to
accumulate and the actual length of the sequence can vary slightly
from the declared length. (see second example below)
- When the distance between the exit of the previous element and the entrance
of the next element is negative and less than minus one micrometer, the elements
are considered to be overlapping and MAD-X terminates with a ``negative drift
length'' fatal error.
Note that a bug in the expansion of sub-sequences within a sequence was reported
in July 2013 and fixed from version 5.01.03 onwards.
Details are explained here.
For efficiency reasons MAD-X imposes an important restriction
on element lengths and positions: once a sequence is expanded, the element
positions and lengths are considered as fixed; in order to vary a position
or element length, a re-expansion of the sequence becomes necessary.
The MATCH command contains a special flag "vlength" to
match element lengths.
Example:
! define a default beam (otherwise fatal error)
beam;
! Define element classes for a simple cell:
b: sbend,l=35.09, angle = 0.011306116;
qf: quadrupole,l=1.6,k1=-0.02268553;
qd: quadrupole,l=1.6,k1=0.022683642;
sf: sextupole,l=0.4,k2=-0.13129;
sd: sextupole,l=0.76,k2=0.26328;
! define the cell as a sequence:
sequ: sequence,l=79;
b1: b, at=19.115;
sf1: sf, at=37.42;
qf1: qf, at=38.70;
b2: b, at=58.255,angle=b1->angle;
sd1: sd, at=76.74;
qd1: qd, at=78.20;
endm: marker, at=79.0;
endsequence;
Example of very small drift space being ignored during sequence
expansion:
QTEST: QUADRUPOLE, L=1.000001;
TEST: SEQUENCE, REFER=centre, L=2.;
QTEST, AT=1.5;
ENDSEQUENCE;
USE, SEQUENCE=TEST;
SURVEY, FILE='test';
The above sequence will expand to a total length of 2.0000005 m, half
a micron longer than the claimed length of 2 m, but will not fail.
hansg, June 17, 2002
Last updated: Ghislain Roy, 18 March 2014