15  Beam Lines

The accelerator to be studied is represented as a sequence of physical elements called a beam line. A beam line is built from simpler beam lines whose definitions can be nested to any level. A LINE command provides the formal definition:

label: LINE = (member, ..., member);

Each member may be:

• an element label,
• a beamline label,
• a sub-line enclosed in parentheses.

15.1 Simple Beam Lines

The simplest beam line is a list of elements:

label: LINE = (member, ..., member);

Example:

L: LINE = (A, B, C, D, A, D);

Line attributes:

ORIGIN

position vector of the origin of the line. Elements placed using ELEMEDGE use this as reference.

ORIENTATION

orientation vector of Tait-Bryan angles at the line origin.

15.2 Sub-lines

Instead of referring directly to an element, a beamline member can refer to another named beam line. This provides shorthand notation for repeated lattice segments. Lines and sub-lines can be entered in any order, but when a line is used, all of its sub-lines must already be known to the parser.

Example:

L: LINE = (A, B, S, B, A, S, A, B);
S: LINE = (C, D, E);

The source manual expands this in two steps.

1. Replace S by its definition:

(A, B, (C, D, E), B, A, (C, D, E), A, B)

2. Omit parentheses:

A, B, C, D, E, B, A, C, D, E, A, B

15.3 Ring geometry and fringe fields

RING declares a beam sequence, not a lattice element:

R: RING = (B1, D1, Q1, D2, B2, ...);

Specify each physical occurrence with its own explicit 6D entrance pose (X, Y, Z, THETA, PHI, PSI); use no ELEMEDGE in new inputs. Repetition and reflection modifiers are not supported by RING, and a RING cannot be nested inside a LINE or another RING. A RING may contain named LINE segments; the expanded physical occurrences are tagged with the enclosing ring name. The sequence does not automatically place or geometrically close the elements.

The design circumference is calculated from the nominal element arc lengths and drift lengths. There is no CIRCUMFERENCE input option. Explicit drifts must account for the intended gaps once. A fringe extending into a drift does not add length or require moving that drift. For RBEND, the stored chord length is converted to the corresponding design arc length.

With numerical maps enabled, an element’s map covers its nominal body interval and includes neighbouring fields. A drift with a fringe field is therefore not a field-free drift map. Field-support boundaries remain integration boundaries, not additional pieces of lattice geometry.

Ring threading measures the reference’s return to the starting transverse plane and reports both the design circumference and the travelled return length, together with position and momentum closure residuals. A return is not a closed-orbit solve. The path-index lookup uses the measured return length; explicit TURNS stopping uses directed return-plane crossings. When no explicit turn-count or energy stop is active, ring progress remains based on design length. The reference search is bounded and reports an error if no one-circuit return is found.

TRACK,LINE=<ring> supports directed-return tracking for RING runs. The separate named COF command also requires LINE to name a RING, because it builds a fixed-energy return problem from the ring’s ordered static magnetic elements.

See geometry, fringe support and ring return for the equations, search limits and comparison with MAD-X, Bmad and MaryLie.