Members - short description

Editing, Inspection, Variables and Configuration
Member	Description
eval(…)	Get the value of an expression
extend_knl_ksl(…)	Extend the order of the knl and ksl attributes of the elements.
extend_knl_rel_ksl_rel(…)	Extend the order of the rel_knl and rel_ksl attributes of the elements.
get(…)	Get an element or the value of a variable.
get_expr(…)	Get expression associated to a variable
import_line(…)	Import a line into this environment.
info(…)	Get information about an element or a variable.
new(…)	Create a new element or line.
new_expr(…)	Create a new expression
new_line(…)	Create a new line.
place(…)	Create a place object.
remove(…)	Remove an element, particle, line, or variable by name.
replace_replica(…)	Replace a replica element with a clone of its parent element. Expressions on element attributes are preserved.
set(…)	Set the values or expressions of variables or element properties. A single call can set one or multiple variables or elements.
element_dict	Dictionary-like container of elements in the environment.
element_refs	Dictionary-like container of xdeps element references.
elements	Container of environment elements; item access returns `View` objects.
functions	xdeps function container used in expressions.
line_names	List of names of all lines currently in the environment.
lines	Container of named lines registered in this environment.
metadata	User metadata associated with the environment.
ref	xdeps reference container for variables, elements and particles.
ref_manager	xdeps dependency manager for variables, element references, and expressions.
vars	Variables container associated with the environment.
xcoll	Xcoll-specific helpers associated with this environment.
xfields	Xfields-specific helpers associated with this environment.

Reference Particle and Particle Generation
Member	Description
new_particle(…)	Associate a particle type to a name. The particle is stored in Environment.particles, its properties can be controlled with deferred expressions and it can be used as reference particle for lines.
set_particle_ref(…)	Set the environment reference particle and optionally propagate it to lines.
particle_ref	Reference particle accessor, or `None` if not configured.
particles	Container of named particles; item access returns `View` objects.

Analysis and Matching
Member	Description
match(…)	Change a set of knobs in the beam lines in order to match assigned targets.
match_knob(…)	Match a new knob in the beam line such that the specified targets are matched when the knob is set to the value knob_value_end and the state of the line before tha matching is recovered when the knob is set to the value knob_value_start.
twiss(…)	Compute the twiss parameters for the lines.

Tracker Setup
Member	Description
build_trackers(…)	Build the trackers for the lines.
discard_trackers(…)	Discard all trackers in all lines of the environment.

Constructors and Serialization
Member	Description
call(…)	Call a file with xtrack commands.
copy(…)	Create a deep copy of the environment.
from_dict(…)	Rebuild an environment from a serialized dictionary.
from_json(…)	Constructs an environment from a JSON file.
to_dict(…)	Serialize the environment to a JSON-compatible dictionary.
to_json(…)	Save the environment to a json file.

Deprecated
Member	Description
from_madx(…)	Load a multiline from a MAD-X file.
new_builder(…)	Deprecated. Create a new composer.
set_multipolar_errors(…)	Deprecated: set multipolar errors for specified elements of the environment.
varval	Convenience accessor to variable values.
vv	Short alias for variable values.

Upcoming deprecations
Member	Description
apply_filling_pattern(…)	Deprecated alias for `env.xfields.apply_filling_pattern(...)`.
configure_beambeam_interactions(…)	Deprecated alias for `env.xfields.configure_beambeam_interactions(...)`.
install_beambeam_interactions(…)	Deprecated alias for `env.xfields.install_beambeam_interactions(...)`.

Members - full description

Editing, Inspection, Variables and Configuration

Go to Summary table

Environment.eval(expr)

Get the value of an expression

Parameters:: expr (str) – Expression to evaluate.
Returns:: value – Value of the expression.
Return type:: float

Environment.extend_knl_ksl(order, element_names=None)

Extend the order of the knl and ksl attributes of the elements.

Parameters:

order (int) – New order of the knl and ksl attributes.
element_names (list of str) – Names of the elements to extend. If None, all elements having knl and ksl attributes are extended.

Environment.extend_knl_rel_ksl_rel(order, element_names=None)

Extend the order of the rel_knl and rel_ksl attributes of the elements.

Parameters:

order (int) – New order of the rel_knl and rel_ksl attributes.
element_names (list of str) – Names of the elements to extend. If None, all elements having knl and ksl attributes are extended.

Environment.get(key)

Get an element or the value of a variable.

Parameters:: key (str) – Name of the element or variable.
Returns:: element – Element or value of the variable.
Return type:: Element or float

Environment.get_expr(var)

Get expression associated to a variable

Parameters:: var (str) – Name of the variable
Returns:: expr – Expression associated to the variable
Return type:: Expression

Environment.import_line(line, suffix_for_common_elements=None, rename_elements={}, line_name=None, overwrite_vars=False)

Import a line into this environment.

Parameters:

suffix_for_common_elements (str, optional) – Suffix to be added to the names of the elements that are common to the imported line and the line in this environment. If None, ‘_{source_line_name}’ is used.
rename_elements (dict, optional) – Dictionary with the elements to be renamed. The keys are the names of the elements in line, and the values are the new names.
line_name (str, optional) – Name of the new line. If None, the name of the imported line is used.
overwrite_vars (bool, optional) – If True, the variables in the imported line will overwrite the variables with the same name in this environment. Default is False.

Environment.info(key, limit=30)

Get information about an element or a variable.

Parameters:

key (str) – Name of the element or variable.
limit (int, optional) – Maximum number of expression terms shown for variable info.

Returns:

This method displays information and does not return a value.

Return type:

None

Environment.new(name, parent, mode=None, at=None, from_=None, anchor=None, from_anchor=None, extra=None, mirror=False, force=False, import_from=None, **kwargs)

Create a new element or line.

Parameters:

name (str) – Name of the new element or line
parent (str or class) – Parent class or name of the parent element
mode (str, optional) –
- clone: clone the parent element or line. The parent element or line is copied, together with the associated expressions.
- replica: replicate the parent elements or lines are made.
- import: clone from a different environment. import_from must be provided.
at (float or str, optional) – Position of the created object.
from (str, optional) – Name of the element from which the position is calculated (its center is used as reference).
mirror (bool, optional) – Can only be used when cloning lines. If True, the order of the elements is reversed.
import_from (Environment, optional. Only to be used when mode is 'import'.) –

Returns:

Name of the created element or line or a Place object if at or from_ is provided.

Return type:

str or Place

Environment.new_expr(expr)

Create a new expression

Parameters:: expr (str) – Expression to create.
Returns:: expr – New expression.
Return type:: Expression

Environment.new_line(components=None, name=None, refer: Literal['start', 'center', 'centre', 'end'] = 'center', length=None, mirror=False, s_tol=1e-06, compose=False) → Line

Create a new line.

Parameters:

components (list, optional) – List of components to be added to the line. It can include strings, place objects, and lines.
name (str, optional) – Name of the new line.
refer (str, optional) – Specifies which part of the component the at position will refer to. Allowed values are start, center (default; also allowed is centre`), and end.
length (float | str, optional) – Length of the line to be built by the composer. Can be an expression. If not specified, the length will be the minimum length that can fit all the components.
mirror (bool, optional) – Whether the line should be mirrored after creation.
compose (bool, optional) – Whether to instantiate the line in compose mode, which allows the components to be added to the line after creation.
s_tol (float, optional) – Difference between two s positions below which they should be treated as the same location.

Returns:

The new line.

Return type:

line

Examples

env = xt.Environment()
env['a'] = 3 # Define a variable
env.new('mq1', xt.Quadrupole, length=0.3, k1='a')  # Create an element
env.new('mq2', xt.Quadrupole, length=0.3, k1='-a')  # Create another element

ln = env.new_line(name='myline', components=[
    'mq',  # Add the element 'mq' at the start of the line
    env.new('mymark', xt.Marker, at=10.0),  # Create a marker at s=10
    env.new('mq1_clone', 'mq1', k1='2a'),   # Clone 'mq1' with a different k1
    env.place('mq2', at=20.0, from='mymark'),  # Place 'mq2' at s=20
])

Environment.place(name, obj=None, at=None, from_=None, anchor=None, from_anchor=None)

Create a place object.

Parameters:

name (str or Line) – Name of the element or line to be placed.
at (float or str, optional) – Position of the created object.
from (str, optional) – Name of the element from which the position is calculated (its center is used as reference).

Returns:

The new place object.

Return type:

Place

Environment.remove(key)

Remove an element, particle, line, or variable by name.

Parameters:: key (str) – Name of the object to remove.

Environment.replace_replica(name)

Replace a replica element with a clone of its parent element. Expressions on element attributes are preserved.

Parameters:: name (str) – Name of the replica element to replace.
Returns:: This method modifies the environment in place.
Return type:: None

Environment.set(name, *args, **kwargs)

Set the values or expressions of variables or element properties. A single call can set one or multiple variables or elements.

Parameters:

name (str or iterable of str) – Name or names of the variable(s) or element(s).
value (float or str) – Value or expression of the variable to set. Can be provided only if the name is associated to a variable.
**kwargs – Attributes to set. Can be provided only if the name is associated to an element.
str (float or) – Attributes to set. Can be provided only if the name is associated to an element.

Examples

>>> line.set('a', 0.1)
>>> line.set('k1', '3*a')
>>> line.set('quad', k1=0.1, k2='3*a')
>>> line.set(['quad1', 'quad2'], k1=0.1, k2='3*a')
>>> line.set(['c', 'd'], 0.1)
>>> line.set(['e', 'f'], '3*a')

property Environment.element_dict: Dictionary-like container of elements in the environment.

property Environment.element_refs: Dictionary-like container of xdeps element references.

property Environment.elements: Container of environment elements; item access returns View objects.

property Environment.functions

xdeps function container used in expressions.

Returns:: functions – Dictionary-like container of functions available in expressions.
Return type:: object

property Environment.line_names: List of names of all lines currently in the environment.

property Environment.lines: Container of named lines registered in this environment.

property Environment.metadata: User metadata associated with the environment.

property Environment.ref: xdeps reference container for variables, elements and particles.

property Environment.ref_manager

xdeps dependency manager for variables, element references, and expressions.

Returns:: ref_manager – Dependency manager used to register and update expression tasks.
Return type:: object

property Environment.vars

Variables container associated with the environment.

The container provides variable-management utilities such as keys(), get_table(), load() (JSON and MAD-X files), remove(), rename(), and update().

Returns:: vars – Dictionary-like container of variables.
Return type:: object

property Environment.xcoll: Xcoll-specific helpers associated with this environment.

property Environment.xfields: Xfields-specific helpers associated with this environment.

Reference Particle and Particle Generation

Go to Summary table

Environment.new_particle(name, parent=None, force=False, **kwargs)

Associate a particle type to a name. The particle is stored in Environment.particles, its properties can be controlled with deferred expressions and it can be used as reference particle for lines.

Note that this method is not meant to create particles distributions for tracking. For that purpose use xt.Particles(…), Line.build_particles(…) or the generation functions for particles distributions available in xpart. See https://xsuite.readthedocs.io/en/latest/particlesmanip.html for more details.

Parameters:

name (str) – Name of the new particle type
parent (str or class) – Parent class or name of the parent particle type
pdg_id_0 (int or str, optional, define reference mass and charge from) – PDG id or particle name.
mass0 (float, optional) – Reference rest mass [eV]
q0 (float, optional) – Reference charge [e]
p0c (array_like of float, optional) – Reference momentum [eV]
energy0 (array_like of float, optional) – Reference energy [eV]
gamma0 (array_like of float, optional) – Reference relativistic gamma
beta0 (array_like of float, optional) – Reference relativistic beta
rigidity0 (array_like of float, optional) – Reference magnetic rigidity [T.m]
kinetic_energy0 (array_like of float, optional) – Reference kinetic energy [eV]

Examples

Create a positron particle type with gamma0 controlled by a deferred expression:

>>> env = xt.Environment()
>>> env['a'] = 5
>>> env.new_particle('my_particle_type', pdg_id_0='positron', gamma0='3*a')
'my_particle_type'
>>> env['my_particle_type'].gamma0
View of LinkedArrayCpu([15.])
>>> env['a'] = 10
>>> env['my_particle_type'].gamma0
View of LinkedArrayCpu([30.])

Environment.set_particle_ref(*args, lines=True, **kwargs)

Set the environment reference particle and optionally propagate it to lines.

Parameters:

*args – Either a single xtrack.Particles, a particle name, or arguments passed to xtrack.Particles.
lines (bool, str, iterable of str, optional) – Which lines receive the same reference particle. True updates all lines, False/None updates none.
**kwargs – Extra keyword arguments forwarded to xtrack.Particles when constructing a new particle reference.

property Environment.particle_ref: Reference particle accessor, or None if not configured.

property Environment.particles: Container of named particles; item access returns View objects.

Analysis and Matching

Go to Summary table

Environment.match(vary, targets, restore_if_fail=True, solver=None, verbose=False, check_limits=True, **kwargs)

Change a set of knobs in the beam lines in order to match assigned targets.

Parameters:

vary (list of str or list of Vary objects) – List of knobs to be varied. Each knob can be a string or a Vary object including the knob name and the step used for computing the Jacobian for the optimization.
targets (list of Target objects) – List of targets to be matched.
restore_if_fail (bool) – If True, the beamline is restored to its initial state if the matching fails.
solver (str) – Solver to be used for the matching.
check_limits (bool) – If True (default), the limits of the knobs are checked before the optimization. If False, if the knobs are out of limits, the optimization knobs are set to the limits on the first iteration.
verbose (bool) – If True, the matching steps are printed.
**kwargs (dict) – Additional arguments to be passed to the twiss.

Returns:

result_info – Dictionary containing information about the matching result.

Return type:

dict

Environment.match_knob(knob_name, vary, targets, knob_value_start=0, knob_value_end=1, **kwargs)

Match a new knob in the beam line such that the specified targets are matched when the knob is set to the value knob_value_end and the state of the line before tha matching is recovered when the knob is set to the value knob_value_start.

Parameters:

knob_name (str) – Name of the knob to be matched.
vary (list of str or list of Vary objects) – List of existing knobs to be varied.
targets (list of Target objects) – List of targets to be matched.
knob_value_start (float) – Value of the knob before the matching. Defaults to 0.
knob_value_end (float) – Value of the knob after the matching. Defaults to 1.

Environment.twiss(lines=None, **kwargs)

Compute the twiss parameters for the lines.

Parameters:

lines (list of str) – The lines for which the twiss parameters are computed. If None, the twiss parameters are computed for all lines.
**kwargs (dict) – Additional keyword arguments are passed to the Line.twiss method.

Returns:

out – A MultiTwiss object containing the twiss parameters for the lines.

Return type:

MultiTwiss

Tracker Setup

Go to Summary table

Environment.build_trackers(_context=None, _buffer=None, **kwargs)

Build the trackers for the lines.

Parameters:

_context (xobjects.Context) – The context in which the trackers are built.
_buffer (xobjects.Buffer) – The buffer in which the trackers are built.
**kwargs (dict) – Additional keyword arguments are passed to the Line.build_tracker method.

Environment.discard_trackers(): Discard all trackers in all lines of the environment.

Constructors and Serialization

Go to Summary table

Environment.call(filename)

Call a file with xtrack commands.

Parameters:: filename (str) – Name of the file to be called.

Environment.copy()

Create a deep copy of the environment.

Returns:: Independent copy of the environment, including elements, lines, particles, variables, expressions and metadata.
Return type:: Environment

classmethod Environment.from_dict(dct, _context=None, _buffer=None, classes=())

Rebuild an environment from a serialized dictionary.

Parameters:

dct (dict) – Dictionary produced by to_dict().
_context (xobjects.Context, optional) – Context used to rebuild xobjects-backed data.
_buffer (xobjects.Buffer, optional) – Buffer used to rebuild xobjects-backed data.
classes (tuple, optional) – Extra element classes accepted during element deserialization.

Returns:

Reconstructed environment.

Return type:

Environment

classmethod Environment.from_json(file, **kwargs)

Constructs an environment from a JSON file.

Parameters:

file (str or file-like object) – Path to the JSON file or file-like object. If filename ends with ‘.gz’ file is decompressed.
**kwargs (dict) – Additional keyword arguments passed to Environment.from_dict.

Returns:

environment – Environment object.

Return type:

Environment

Environment.to_dict(include_var_management=True, include_version=True)

Serialize the environment to a JSON-compatible dictionary.

Parameters:

include_var_management (bool, optional) – If True, include deferred-expression data and variable manager state. Default is True.
include_version (bool, optional) – If True, include the xtrack version that generated the dictionary. Default is True.

Returns:

Serialized environment data.

Return type:

dict

Environment.to_json(file, indent=1, **kwargs)

Save the environment to a json file.

Parameters:

file (str or file-like object) – The file to save to. If a string is provided, a file is opened and closed. If a file-like object is provided, it is used directly.
**kwargs – Additional keyword arguments are passed to the Environment.to_dict method.

Deprecated

Go to Summary table

classmethod Environment.from_madx(filename=None, madx=None, stdout=None, return_lines=False, **kwargs)

Load a multiline from a MAD-X file.

Warning

This function is deprecated and will be removed in a future version. Please use xtrack.load(…), which uses the xsuite native MAD-X parser, without requiring Cpymad. In case you need to use cpymad for specific features, please load the individual lines using Line.from_madx_sequence(…) and add them to the environment using Environment.import_line(…).

Parameters:

file (str) – The MAD-X file to load from.
**kwargs – Additional keyword arguments are passed to the Line.from_madx_sequence method.

Returns:

new_multiline – The multiline object.

Return type:

Multiline

Environment.new_builder(components=None, name=None, refer: Literal['start', 'center', 'centre', 'end'] = 'center', length=None, s_tol=1e-06)

Deprecated. Create a new composer.

Warning

The new_builder method is deprecated and will be removed in a future version. Use new_line with compose=True instead.

Parameters:

components (list, optional) – List of components to be added to the composer. It can include strings, place objects, and lines.
name (str, optional) – Name of the line that will be built by the composer.
refer (str, optional) – Specifies which part of the component the at position will refer to. Allowed values are start, center (default; also allowed is centre`), and end.
length (float | str, optional) – Length of the line to be built by the composer. Can be an expression. If not specified, the length will be the minimum length that can fit all the components.

Returns:

The new composer.

Return type:

Composer

Environment.set_multipolar_errors(errors)

Deprecated: set multipolar errors for specified elements of the environment.

Warning

This function is deprecated and will be removed in a future version. Please use the attributes knl_rel and ksl_rel of the elements to set relative multipolar errors directly on the elements.

Parameters:

errors (dict) –

Dictionary with the errors to be set. The keys are the names of the elements, and the values are dictionaries with the following keys:

rel_knl: list of relative errors for the normal multipolar strengths.

rel_ksl: list of relative errors for the skew multipolar strengths.

refer: name of the strength to be used as reference, which is multiplied by the length. If None, the default reference strength is used (k0 for bends, k1 for quadrupoles, k2 for sextupoles, and k3 for octupoles).

Examples

env = xt.Environment()
env.vars.default_to_zero = True
line = env.new_line(components=[
    env.new('mq', 'Quadrupole', length=0.5, k1='kq'),
    env.new('mqs', 'Quadrupole', length=0.5, k1s='kqs'),
    env.new('mb', 'Bend', length=0.5, angle='ang', k0_from_h=True),
])

env.set_multipolar_errors({
    'mq': {'rel_knl': [1e-6, 1e-5, 1e-4],
           'rel_ksl': [-1e-6, -1e-5, -1e-4]},
    'mqs': {'rel_knl': [2e-6, 2e-5, 2e-4],
            'rel_ksl': [3e-6, 3e-5, 3e-4],
            'refer': 'k1s'},
    'mb': {'rel_knl': [2e-6, 3e-5, 4e-4],
           'rel_ksl': [5e-6, 6e-5, 7e-4]},
    })

property Environment.varval

Convenience accessor to variable values.

Equivalent to environment.vars.val.

Returns:: values – Mapping-like view exposing variable values.
Return type:: object

property Environment.vv

Short alias for variable values.

Equivalent to environment.varval (or environment.vars.val).

Returns:: values – Mapping-like view exposing variable values.
Return type:: object

Upcoming deprecations

Go to Summary table

Environment.apply_filling_pattern(filling_pattern_cw, filling_pattern_acw, i_bunch_cw, i_bunch_acw): Deprecated alias for env.xfields.apply_filling_pattern(...).

Environment.configure_beambeam_interactions(num_particles, nemitt_x, nemitt_y, crab_strong_beam=True, use_antisymmetry=False, separation_bumps=None): Deprecated alias for env.xfields.configure_beambeam_interactions(...).

Environment.install_beambeam_interactions(clockwise_line, anticlockwise_line, ip_names, num_long_range_encounters_per_side, num_slices_head_on, harmonic_number, bunch_spacing_buckets, sigmaz, delay_at_ips_slots=None): Deprecated alias for env.xfields.install_beambeam_interactions(...).