at.load.xsuite#

Using Xsuite .json files with PyAT.#

PyAT can read and write lattice descriptions in Xsuite .json files. If both PyAT and Xsuite are installed, in-memory direct conversion is also possible in both directions.

However, because of intrinsic differences between PyAT and Xsuite, some incompatibilities must be taken into account.

1. Differences between PyAT and Xsuite#

Magnet models#

Xsuite separates the definition of the magnet modelling method (model) and the definition of the integrator (integrator). It offers a large choice for both. PyAT combines both in the PassMethod associated with the element. The conversion in both directions is described below.

Magnet transformations#

PyAT uses a coherent definition of rotations: the positive sign corresponds to a cork-screw rotation, or in other words an anti-clockwise rotation when facing the axis. Xsuite has a special definition for the x-axis rotation, opposite to the standard. As a consequence, the signs of the pitch in AT and rot-x-rad in Xsuite are opposite. The conversion takes care of that.

Rectangular bending magnets#

A Xsuite RBend magnet corresponds to a standard Dipole if its rbend_model is set to curved-body. When converted to AT, its PassMethod will then be set to BndMPoleSymplectic4Pass or ExactSectorBendPass depending on its model.

It corresponds to a real rectangular magnet if its rbend_model is set to straight-body. When converted to AT, its PassMethod will then be set to ExactRectangularBendPass, the only one for rectangular bends.

2. Reading Xsuite files#

PyAT can read both Environment and Line file descriptions. For Environment files, a use keyword selects the desired Line.

Xsuite elements converted to PyAT have an additional origin string attribute giving the class of the original Xsuite element. Xsuite element without equivalent in PyAT are converted to Marker or Drift depending on their length.

Model and integrator#

Xsuite models equivalent to PyAT “exact” methods are converted to the equivalent PassMethod:

Xsuite element

Xsuite model

AT PassMethod

Drift

“exact”

“ExactDriftPass”

Straight magnets

“drift-kick-drift-exact”

“ExactMultipolePass”

Bend, Rbend in “curved-body”

“bend-kick-bend”

“ExactSectorBendPass”

Rbend in “straight-body”

“drift-kick-drift-exact”

“ExactRectangularBendPass”

All other models are converted to the default element PassMethod.

Longitudinal motion#

The generated AT lattice has longitudinal motion turned off: RF cavities are inactive and synchrotron radiation is turned off.

3. Writing Xsuite files#

Rectangular bending magnets#

An AT Dipole will be converted to a RBend with rbend_model set to straight-body if its PassMethod is ExactRectangularBendPass. In all other cases, it will be converted to a Bend.

Model and integrator#

PyAT exact passmethods are converted to the equivalent Xsuite model. Other methods are converting according to a match_model keyword:

  • match_model is False (the default): model, integrator, num_multipole_kicks are set to their default value. This way, the default behaviour in AT is turned into the default behaviour in Xsuite,

  • match_model is True: a model matching at best the AT model is selected, the integrator is set to yoshida4 and num_multipole_kicks is set equal to NumIntSteps.

This is summarised in this table:

AT element

AT PassMethod

Xsuite model, match_model=

False

True

Drift

ExactDriftPass

“exact”

default

“adaptive”

“expanded”

Straight magnet

ExactMultipolePass

“drift-kick-drift-exact”

default

“adaptive”

“drift-kick-drift-expanded”

Dipole

ExactSectorBendPass

“bend-kick-bend”

ExactRectangularBendPass

“drift-kick-drift-exact”

default

“adaptive”

“rot-kick-rot”

Longitudinal motion#

Whatever the 6D status of the AT lattice, the Xsuite lattice will have synchrotron radiation turned off and active RF cavities.

Ignored attributes#

The following AT attributes are ignored in writing Xsuite .json files:

  • RApertures

  • EApertures

  • X0ref. This parameter defines the distance between the magnetic axis of a rectangular bend and the reference trajectory. It only matters for rectangular bends with focusing or higher order multipoles. Xsuite has a similar attribute rbend_shift but there is no analytical conversion possible between both.

  • RefDZ. This defines the correction of path lengthening for rectangular bends.

Functions

lattice_from_line(line[, use])

Create a Lattice object from a Xsuite Line or Environment.

line_from_lattice(ring[, match_model])

Create a Xsuite Line from an AT lattice.

load_xsuite(filename[, use])

Create a Lattice from a Xsuite JSON file.

save_xsuite(lattice[, filename, ...])

Save a Lattice as a Xsuite JSON file.

Classes

XsElement(name, *args, **kwargs)

Base class for Xsuite elements.

XsLine(elements, **root)

Line object simulation a Xsuite Line.
class XsElement(name, *args, **kwargs)[source]#

Bases: dict

Base class for Xsuite elements.

classmethod from_at(match_model=False, **atparams)[source]#

Build a XsElement element from an AT element.

Parameters:

  • match_model (bool) – If True, set the Xsuite model and integrator matching at best the AT PassMethod. Otherwise, use Xsuite defaults,

  • atparams – dictionary representation of the AT element.

Returns:

xselement – new XsElement object

classmethod from_dict(xsparams, name='?', warn=<function XsElement.<lambda>>)[source]#

Build a XsElement from its dictionary representation.

Parameters:

  • xsparams (dict[str, Any]) – dictionary representation of the XsElement

  • name (str) – Optional name of the element

  • warn (Callable[[str], bool]) – warning trigger function

Returns:

xselement – new XsElement object

static static_from_at(atelem, match_model=False)[source]#

Build a XsElement from an AT element.

Parameters:

  • atelem (Element) – AT Element

  • match_model (bool) – If True, set the Xsuite model and integrator matching at best the AT PassMethod. By default, the Xsuite default model and integrator will be used.

Returns:

xselement – new XsElement object

static static_from_dict(elem_dict, name='?', warn=<function XsElement.<lambda>>)[source]#

Build a XsElement from its dictionary representation.

Parameters:

  • elem_dict (dict[str, Any]) – dictionary representation of the XsElement

  • name (str) – Optional name of the element

  • warn (Callable[[str], bool]) – warning trigger function

Returns:

xselement – new XsElement object

to_at()[source]#

Generate the AT element.

Returns:

elem – new Element object

to_dict()[source]#

Build a dictionary representation of the XsElement.

Returns:

elem_dict – dictionary representation of the XsElement

name: str#

Element name

origin: str#

Xsuite class of the source element

class XsLine(elements, **root)[source]#

Bases: object

Line object simulation a Xsuite Line.

classmethod from_at(ring, match_model=False, **kwargs)[source]#

Create a XsLine from an AT Lattice.

Parameters:

  • ring (Lattice) – AT lattice

  • match_model (bool) – If True, set the Xsuite model and integrator matching at best the AT PassMethod. By default, the Xsuite default model and integrator will be used.

Returns:

xsline – New XsLine

classmethod from_dict(root, use=None, **kwargs)[source]#

Create an XsLine from a dictionary.

Parameters:

  • root (dict[str, Any]) – Dictionary representation of the line or environment,

  • use (str | None) – For environment, name of the sequence or line containing the desired lattice. Default: ring.

Returns:

xsline – New XsLine

classmethod from_json(filename, use=None, **kwargs)[source]#

Create a XsLine from a JSON file.

Parameters:

  • filename (str | Path) – Name or path of the JSON file.

  • use (str | None) – For environment, name of the sequence or line containing the desired lattice. Default: ring

Returns:

xsline – New XsLine

classmethod from_xsuite(line, use=None)[source]#

Create a XsLine from a Xsuite Line or Environment.

Parameters:

  • line – Xsuite Line or Environment

  • use (str | None) – For environment, name of the sequence or line containing the desired lattice. Default: ring

Returns:

xsline – New XsLine

lattice(**kwargs)#

Create an AT lattice from the XsLine.

Keyword Arguments:

  • name (str) – Name of the lattice. Default: Xsuite line name.

  • particle (Particle) – Circulating particle. Default: Xsuite reference particle

  • energy (float) – Energy of the lattice [eV]. Default: from Xsuite reference particle

  • periodicity (int) – Number of periods. Default: 1

  • * – All other keywords will be set as Lattice attributes

Returns:

lattice – New Lattice.

to_at(**kwargs)[source]#

Create an AT lattice from the XsLine.

Keyword Arguments:

  • name (str) – Name of the lattice. Default: Xsuite line name.

  • particle (Particle) – Circulating particle. Default: Xsuite reference particle

  • energy (float) – Energy of the lattice [eV]. Default: from Xsuite reference particle

  • periodicity (int) – Number of periods. Default: 1

  • * – All other keywords will be set as Lattice attributes

Returns:

lattice – New Lattice.

to_dict()[source]#

Create a Xsuite-compatible dictionary representation of the XsLine.

Returns:

dict[str, Any] – Dictionary representation of the XsLine.

to_json(filename=None, compact=False)[source]#

Save the XsLine into a JSON file.

Parameters:

  • filename (str | Path | None) – Name of the JSON file. Default: outputs on sys.stdout

  • compact (bool) – If False (default), the JSON file is pretty-printed with line feeds and indentation. Otherwise, the output is a single line.

element_names: list[str] = []#
in_file: str = ''#
name: str = 'test'#
particle_ref: dict[str, Any] = {'beta0': [0.9999998694400277], 'gamma0': [1956.9511809167193], 'mass0': 510998.95069, 'q0': -1}#
lattice_from_line(line, use=None, **kwargs)[source]#

Create a Lattice object from a Xsuite Line or Environment.

Parameters:

  • line (Line) – Xsuite line or environment

  • use (str) – Name of the line containing the desired lattice. Default: ring.

Keyword Arguments:

  • name (str) – Name of the lattice. Default: Xsuite line name.

  • particle (Particle) – Circulating particle. Default: Xsuite reference particle

  • energy (float) – Energy of the lattice [eV]. Default: from Xsuite reference particle

  • periodicity (int) – Number of periods. Default: 1

  • * – All other keywords will be set as Lattice attributes

Returns:

lattice – New Lattice object.

line_from_lattice(ring, match_model=False)[source]#

Create a Xsuite Line from an AT lattice.

Parameters:

  • ring (Lattice) – AT lattice

  • match_model (bool) – if True, set the Xsuite model and integrator matching at best the AT PassMethod. Otherwise, use Xsuite defaults.

Returns:

line – new Line object.

load_xsuite(filename, use=None, **kwargs)[source]#

Create a Lattice from a Xsuite JSON file.

Parameters:

  • filename (str | Path) – Name or path of the JSON file

  • use (str | None) – Name of the Xsuite line containing the desired lattice. Default: ring

Keyword Arguments:

  • name (str) – Name of the lattice. Default: Xsuite line name.

  • particle (Particle) – Circulating particle. Default: Xsuite reference particle

  • energy (float) – Energy of the lattice [eV]. Default: from Xsuite reference particle

  • periodicity (int) – Number of periods. Default: 1

  • * – All other keywords will be set as Lattice attributes

Returns:

lattice (Lattice) – New Lattice object

See also

load_json(), which reads both AT and Xsuite .json files,

load_lattice() for a generic lattice-loading function,

Lattice.load() for a generic lattice factory method.

save_xsuite(lattice, filename=None, match_model=False, compact=False)[source]#

Save a Lattice as a Xsuite JSON file.

Parameters:

  • lattice (Lattice) – Lattice description

  • filename (str | Path | None) – Name of the JSON file. Default: outputs on sys.stdout

  • match_model (bool) – If True, set the Xsuite model matching at best the AT PassMethod. By default, the Xsuite default model will be used.

  • compact (bool) – If False (default), the JSON file is pretty-printed with line feeds and indentation. Otherwise, the output is a single line.