line.rst

Line

Table of Contents

Creating a Line object

An Xsuite Line can be created by providing beam line element objects and the corresponding names, as illustrated in the following example:

generated_code_snippets/toy_ring.py

Importing a line from MAD-X

An Xsuite Line object can be imported from an existing MAD-X model, through the cpymad interface of MAD-X, using the method xtrack.Line.from_madx_sequence. The import of certain features of the MAD-X model (dererred expressions, apertures, thick elements, alignment errors, field errors, etc.) can be controlled by the user. This is illustrated in the following example:

generated_code_snippets/madx_import_psb.py

Define a line through a sequence

A line can also be defined through a "sequence", providing the element s positions instead of explicit drifts, as show in the example below:

generated_code_snippets/sequence.py

Line inspection, Line.get_table(), Line.attr[...] ========================================================

The following example illustrates how to inspect the properties of a line and its elements:

generated_code_snippets/line_inspect.py

References and deferred expressions

Accelerators and beam lines have complex control paterns. For example, a single high-level parameter can be used to control groups of accelerator components (e.g., sets of magnets in series, groups of RF cavities, etc.) following complex dependency relations. Xsuite allows including these dependencies in the simulation model so that changes in the high-level parameters are automatically propagated down to the line elements properties. Furthermore, the dependency relations can be created, inspected and modified at run time, as illustrated in the following example:

generated_code_snippets/expressions_basics.py

When importing a MAD-X model, the dependency relations from MAD-X deferred expressions are automatically imported as well. The following example illustrates how to inspect the dependency relations in a line imported from MAD-X:

generated_code_snippets/expressions_madx.py

Save and reload lines

An Xtrack Line object can be transformed into a dictionary or saved to a json file, as illustrated in the following example:

generated_code_snippets/tojson.py

Element insertion

generated_code_snippets/insert_element.py

Element slicing

It is possible to slice thick element with thin or thick slices, using the Uniform or the Teapot scheme. This is illustrated in the following example:

generated_code_snippets/slicing.py

Simulation of small rings: drifts, bends, fringe fields

The modeling of the body of bending magnets in automatically adapted depending on the bending radius, hence no special setting is required for this purpose when simulating small rings with large bending angles.

However, the modeling of the fringe fields and the drifts is not automatically adapted and appropriate settings need to be provided by the user.

The following example illustrates how to switch to the full model for the fringe fields and the drifts and compares the effect of different models on the optics functions and the chromatic properties of the CERN ELENA ring:

generated_code_snippets/elena_chromatic_functions.py

Comparison of the simplified and full model for the CERN ELENA ring (the six bends of the ring are highlighted in blue). While the linear optics is well reproduced by the simplified model, the chromatic properties differ significantly (in particular, note the effect of the dipole edges).

Extraction of second order transfer maps

The method xtrack.Line.get_line_with_second_order_maps allows modeling portions of a beam line with second order transfer maps. This is illustrated in the following example.

See also xtrack.SecondOrderTaylorMap.from_line.

generated_code_snippets/line_with_maps.py

Apply transformations (tilt, shift) to elements

Tilt and shifts transformations can be applied to beam elements, as illustrated in the following example:

generated_code_snippets/compound_transform.py

Tranfromations are propagated when the elements are sliced and can be updated also after the slicing by acting on the parent element. This is illustrated in the following example:

generated_code_snippets/compound_transform_sliced.py

Add multipolar components to elements

Multipolar components can be added to thick beam elements, as illustrated in the following example:

generated_code_snippets/multipolar_components.py

Multipolar components are propagated when the elements are sliced and can be updated also after the slicing by acting on the parent element. This is illustrated in the following example:

generated_code_snippets/multipolar_components_sliced.py

Cut line elements at given s positions

The method xtrack.Line.cut_at_s allows for cutting the line elements at the specified s positions. In the example before we take the same toy ring introduced in the earlier example<createline> and we cut it into 100 equal length slices:

generated_code_snippets/cut_at_s.py