Xline API

Line

class xline.Line(elements: tuple = (), element_names: tuple = ())

Bases: xline.base_classes.Element

Fields:

  • elements []: List of elements

  • element_names []: List of element names

to_dict(keepextra=True)
classmethod from_dict(dct, keepextra=True)
to_json(filename, keepextra=True)
classmethod from_json(filename, keepextra=True)
append_line(line)
track(p)
track_elem_by_elem(p, start=True, end=False)
insert_element(idx, element, name)
append_element(element, name)
get_length()
get_s_elements(mode='upstream')
remove_inactive_multipoles(inplace=False)
remove_zero_length_drifts(inplace=False)
merge_consecutive_drifts(inplace=False)
merge_consecutive_multipoles(inplace=False)
get_elements_of_type(types)
get_element_ids_of_type(types, start_idx_offset=0)
linear_normal_form(M)
find_closed_orbit_and_linear_OTM(p0c, guess=None, d=1e-07, tol=1e-10, max_iterations=20, longitudinal_coordinate='zeta')
find_closed_orbit(p0c, guess=[0.0, 0.0, 0.0, 0.0, 0.0, 0.0], method='Nelder-Mead', **kwargs)
enable_beambeam()
disable_beambeam()
beambeam_store_closed_orbit_and_dipolar_kicks(particle_on_CO, separation_given_wrt_closed_orbit_4D=True, separation_given_wrt_closed_orbit_6D=True)
classmethod from_sixinput(sixinput, classes=<module 'xline.elements' from '/home/docs/checkouts/readthedocs.org/user_builds/xsuite/checkouts/latest/docs/xline/xline/elements.py'>)
classmethod from_madx_sequence(sequence, classes=<module 'xline.elements' from '/home/docs/checkouts/readthedocs.org/user_builds/xsuite/checkouts/latest/docs/xline/xline/elements.py'>, ignored_madtypes=[], exact_drift=False, drift_threshold=1e-06, install_apertures=False, apply_madx_errors=False)
find_element_ids(element_name)

Find element_name in this Line instance’s self.elements_name list. Assumes the names are unique.

Return index before and after the element, taking into account attached _aperture instances (LimitRect, LimitEllipse, …) which would follow the element occurrence in the list.

Raises IndexError if element_name not found in this Line.

element_names: tuple = ()
elements: tuple = ()

Beam elements

Drift

class xline.Drift(length: int = 0)

Bases: xline.base_classes.Element

Drift in expanded form

Fields:

  • length [m]: Length of the drift

track(p)
length: int = 0

Multipole

class xline.Multipole(knl: List = <factory>, ksl: List = <factory>, hxl: int = 0, hyl: int = 0, length: int = 0)

Bases: xline.base_classes.Element

Fields:

  • knl [m^-n]: Normalized integrated strength of normal components

  • ksl [m^-n]: Normalized integrated strength of skew components

  • hxl [rad]: Rotation angle of the reference trajectoryin the horizzontal plane

  • hyl [rad]: Rotation angle of the reference trajectory in the vertical plane

  • length [m]: Length of the originating thick multipole

property order
track(p)
hxl: int = 0
hyl: int = 0
length: int = 0
knl: List
ksl: List

Cavity

class xline.Cavity(voltage: int = 0, frequency: int = 0, lag: int = 0)

Bases: xline.base_classes.Element

Radio-frequency cavity

Fields:

  • voltage [V]: Integrated energy change

  • frequency [Hz]: Frequency of the cavity

  • lag [degree]: Delay in the cavity sin(lag - w tau)

track(p)
frequency: int = 0
lag: int = 0
voltage: int = 0

RFMultipole

class xline.RFMultipole(voltage: int = 0, frequency: int = 0, lag: int = 0, knl: List = <factory>, ksl: List = <factory>, pn: List = <factory>, ps: List = <factory>)

Bases: xline.base_classes.Element

H= -l sum Re[ (kn[n](zeta) + i ks[n](zeta) ) (x+iy)**(n+1)/ n ]

kn[n](z) = k_n cos(2pi w tau + pn/180*pi) ks[n](z) = k_n cos(2pi w tau + pn/180*pi)

Fields:

  • voltage [volt]: Voltage

  • frequency [hertz]: Frequency

  • lag [degree]: Delay in the cavity sin(lag - w tau)

  • knl []: …

  • ksl []: …

  • pn []: …

  • ps []: …

property order
track(p)
frequency: int = 0
lag: int = 0
voltage: int = 0
knl: List
ksl: List
pn: List
ps: List

DipoleEdge

class xline.DipoleEdge(h: int = 0, e1: int = 0, hgap: int = 0, fint: int = 0)

Bases: xline.base_classes.Element

Fields:

  • h [1/m]: Curvature

  • e1 [rad]: Face angle

  • hgap [m]: Equivalent gap

  • fint []: Fringe integral

track(p)
e1: int = 0
fint: int = 0
h: int = 0
hgap: int = 0

XYShift

class xline.XYShift(dx: int = 0, dy: int = 0)

Bases: xline.base_classes.Element

shift of the reference

Fields:

  • dx [m]: Horizontal shift

  • dy [m]: Vertical shift

track(p)
dx: int = 0
dy: int = 0

SRotation

class xline.SRotation(angle: int = 0)

Bases: xline.base_classes.Element

anti-clockwise rotation of the reference frame

Fields:

  • angle []: Rotation angle

track(p)
angle: int = 0

LimitEllipse

class xline.LimitEllipse(a: float = 1.0, b: float = 1.0)

Bases: xline.base_classes.Element

Fields:

  • a [m]: Horizontal semiaxis

  • b [m]: Vertical semiaxis

track(particle)
a: float = 1.0
b: float = 1.0

LimitRect

class xline.LimitRect(min_x: float = - 1.0, max_x: float = 1.0, min_y: float = - 1.0, max_y: float = 1.0)

Bases: xline.base_classes.Element

Fields:

  • min_x [m]: Minimum horizontal aperture

  • max_x [m]: Maximum horizontal aperture

  • min_y [m]: Minimum vertical aperture

  • max_y [m]: Minimum vertical aperture

track(particle)
max_x: float = 1.0
max_y: float = 1.0
min_x: float = -1.0
min_y: float = -1.0

BeamBeam4D

class xline.BeamBeam4D(charge: int = 0, sigma_x: float = 1.0, sigma_y: float = 1.0, beta_r: float = 1.0, x_bb: int = 0, y_bb: int = 0, d_px: int = 0, d_py: int = 0, min_sigma_diff: float = 1e-28, enabled: bool = True)

Bases: xline.base_classes.Element

Interaction with a transverse-Gaussian strong beam (4D modelling).

Fields:

  • charge [e]: Charge of the interacting distribution (strong beam)

  • sigma_x [m]: Horizontal size of the strong beam (r.m.s.)

  • sigma_y [m]: Vertical size of the strong beam (r.m.s.)

  • beta_r []: Relativistic beta of the stron beam

  • x_bb [m]: H. position of the strong beam w.r.t. the reference trajectory

  • y_bb [m]: V. position of the strong beam w.r.t. the reference trajectory

  • d_px []: H. kick subtracted after the interaction.

  • d_py []: V. kick subtracted after the interaction.

  • min_sigma_diff [m]: Threshold to detect round beam

  • enabled []: Switch for closed orbit search

track(p)
beta_r: float = 1.0
charge: int = 0
d_px: int = 0
d_py: int = 0
enabled: bool = True
min_sigma_diff: float = 1e-28
sigma_x: float = 1.0
sigma_y: float = 1.0
x_bb: int = 0
y_bb: int = 0

BeamBeam6D

class xline.BeamBeam6D(phi: int = 0, alpha: int = 0, x_bb_co: int = 0, y_bb_co: int = 0, charge_slices: float = 0.0, zeta_slices: float = 0.0, sigma_11: float = 1.0, sigma_12: int = 0, sigma_13: int = 0, sigma_14: int = 0, sigma_22: int = 0, sigma_23: int = 0, sigma_24: int = 0, sigma_33: float = 1.0, sigma_34: int = 0, sigma_44: int = 0, x_co: int = 0, px_co: int = 0, y_co: int = 0, py_co: int = 0, zeta_co: int = 0, delta_co: int = 0, d_x: int = 0, d_px: int = 0, d_y: int = 0, d_py: int = 0, d_zeta: int = 0, d_delta: int = 0, min_sigma_diff: float = 1e-28, threshold_singular: float = 1e-28, enabled: bool = True)

Bases: xline.base_classes.Element

Interaction with a transverse-Gaussian strong beam (6D modelling).

Fields:

  • phi [rad]: Crossing angle (>0 weak beam increasesx in the direction motion)

  • alpha [rad]: Crossing plane tilt angle (>0 x tends to y)

  • x_bb_co [m]: H. position of the strong beam w.r.t. the closed orbit

  • y_bb_co [m]: V. position of the strong beam w.r.t. the closed orbit

  • charge_slices [qe]: Charge of the interacting slices (strong beam)

  • zeta_slices [m]: Longitudinal position of the interactingslices (>0 head of the strong).

  • sigma_11 [m^2]: Sigma_11 element of the sigma matrix of the strong beam

  • sigma_12 [m]: Sigma_12 element of the sigma matrix of the strong beam

  • sigma_13 [m^2]: Sigma_13 element of the sigma matrix of the strong beam

  • sigma_14 [m]: Sigma_14 element of the sigma matrix of the strong beam

  • sigma_22 []: Sigma_22 element of the sigma matrix of the strong beam

  • sigma_23 [m]: Sigma_23 element of the sigma matrix of the strong beam

  • sigma_24 []: Sigma_24 element of the sigma matrix of the strong beam

  • sigma_33 [m^2]: Sigma_33 element of the sigma matrix of the strong beam

  • sigma_34 [m]: Sigma_34 element of the sigma matrix of the strong beam

  • sigma_44 []: Sigma_44 element of the sigma matrix of the strong beam

  • x_co [m]: x coordinate the closed orbit (weak beam).

  • px_co []: px coordinate the closed orbit (weak beam).

  • y_co [m]: y coordinate the closed orbit (weaek beam).

  • py_co []: py coordinate the closed orbit (weaek beam).

  • zeta_co [m]: zeta coordinate the closed orbit (weaek beam).

  • delta_co []: delta coordinate the closed orbit (weaek beam).

  • d_x [m]: Quantity subtracted from x after the interaction.

  • d_px []: Quantity subtracted from px after the interaction.

  • d_y [m]: Quantity subtracted from y after the interaction.

  • d_py []: Quantity subtracted from py after the interaction.

  • d_zeta [m]: Quantity subtracted from sigma after the interaction.

  • d_delta []: Quantity subtracted from delta after the interaction.

  • min_sigma_diff [m]: Threshold to detect round beam

  • threshold_singular []: Threshold to detect small denominator

  • enabled []: Switch for closed orbit search

track(p)
alpha: int = 0
charge_slices: float = 0.0
d_delta: int = 0
d_px: int = 0
d_py: int = 0
d_x: int = 0
d_y: int = 0
d_zeta: int = 0
delta_co: int = 0
enabled: bool = True
min_sigma_diff: float = 1e-28
phi: int = 0
px_co: int = 0
py_co: int = 0
sigma_11: float = 1.0
sigma_12: int = 0
sigma_13: int = 0
sigma_14: int = 0
sigma_22: int = 0
sigma_23: int = 0
sigma_24: int = 0
sigma_33: float = 1.0
sigma_34: int = 0
sigma_44: int = 0
threshold_singular: float = 1e-28
x_bb_co: int = 0
x_co: int = 0
y_bb_co: int = 0
y_co: int = 0
zeta_co: int = 0
zeta_slices: float = 0.0

SCCoasting

class xline.SCCoasting(number_of_particles: float = 0.0, circumference: float = 1.0, sigma_x: float = 1.0, sigma_y: float = 1.0, length: float = 0.0, x_co: float = 0.0, y_co: float = 0.0, min_sigma_diff: float = 1e-08, enabled: bool = True)

Bases: xline.base_classes.Element

Space charge for a coasting beam.

Fields:

  • number_of_particles []: Number of particles in the beam

  • circumference [m]: Machine circumference

  • sigma_x [m]: Horizontal size of the beam (r.m.s.)

  • sigma_y [m]: Vertical size of the beam (r.m.s.)

  • length [m]: Integration length of space charge kick

  • x_co [m]: Horizontal closed orbit offset

  • y_co [m]: Vertical closed orbit offset

  • min_sigma_diff [m]: Threshold to detect round beam

  • enabled []: Switch to disable space charge effect

track(p)
circumference: float = 1.0
enabled: bool = True
length: float = 0.0
min_sigma_diff: float = 1e-08
number_of_particles: float = 0.0
sigma_x: float = 1.0
sigma_y: float = 1.0
x_co: float = 0.0
y_co: float = 0.0

SCInterpolatedProfile

class xline.SCInterpolatedProfile(number_of_particles: float = 0.0, line_density_profile: List = <factory>, dz: float = 1.0, z0: float = -0.5, sigma_x: float = 1.0, sigma_y: float = 1.0, length: float = 0.0, x_co: float = 0.0, y_co: float = 0.0, method: int = 0, min_sigma_diff: float = 1e-08, enabled: bool = True)

Bases: xline.base_classes.Element

Space charge for a bunched beam with discretised profile.

Fields:

  • number_of_particles []: Number of particles in the bunch

  • line_density_profile [1/m]: Discretised list of density values with integral normalised to 1

  • dz [m]: Unit distance in zeta between profile points

  • z0 [m]: Start zeta position of line density profile

  • sigma_x [m]: Horizontal size of the beam (r.m.s.)

  • sigma_y [m]: Vertical size of the beam (r.m.s.)

  • length [m]: Integration length of space charge kick

  • x_co [m]: Horizontal closed orbit offset

  • y_co [m]: Vertical closed orbit offset

  • method []: Interpolation method; 0 == linear (default), 1 == cubic spline

  • min_sigma_diff [m]: Threshold to detect round beam

  • enabled []: Switch to disable space charge effect

track(p)
dz: float = 1.0
enabled: bool = True
length: float = 0.0
method: int = 0
min_sigma_diff: float = 1e-08
number_of_particles: float = 0.0
sigma_x: float = 1.0
sigma_y: float = 1.0
x_co: float = 0.0
y_co: float = 0.0
z0: float = -0.5
line_density_profile: List

SCQGaussProfile

class xline.SCQGaussProfile(number_of_particles: float = 0.0, bunchlength_rms: float = 1.0, sigma_x: float = 1.0, sigma_y: float = 1.0, length: float = 0.0, x_co: float = 0.0, y_co: float = 0.0, min_sigma_diff: float = 1e-08, enabled: bool = True, q_parameter: float = 1.0)

Bases: xline.base_classes.Element

Space charge for a bunched beam with generalised

Gaussian profile.

Fields:

  • number_of_particles []: Number of particles in the bunch

  • bunchlength_rms [m]: Length of the bunch (r.m.s.)

  • sigma_x [m]: Horizontal size of the beam (r.m.s.)

  • sigma_y [m]: Vertical size of the beam (r.m.s.)

  • length [m]: Integration length of space charge kick

  • x_co [m]: Horizontal closed orbit offset

  • y_co [m]: Vertical closed orbit offset

  • min_sigma_diff [m]: Threshold to detect round beam

  • enabled []: Switch to disable space charge effect

  • q_parameter []: q parameter of generalised Gaussian distribution (q=1 for standard Gaussian)

track(p)
bunchlength_rms: float = 1.0
enabled: bool = True
length: float = 0.0
min_sigma_diff: float = 1e-08
number_of_particles: float = 0.0
q_parameter: float = 1.0
sigma_x: float = 1.0
sigma_y: float = 1.0
x_co: float = 0.0
y_co: float = 0.0

BeamMonitor

class xline.BeamMonitor(num_stores: int = 0, start: int = 0, skip: int = 1, max_particle_id: int = 0, min_particle_id: int = 0, is_rolling: bool = False, is_turn_ordered: bool = True, data: List = <factory>)

Bases: xline.base_classes.Element

Fields:

  • num_stores []: …

  • start []: …

  • skip []: …

  • max_particle_id []:

  • min_particle_id []:

  • is_rolling []:

  • is_turn_ordered []:

  • data []: …

offset(particle)
track(p)
is_rolling: bool = False
is_turn_ordered: bool = True
max_particle_id: int = 0
min_particle_id: int = 0
num_stores: int = 0
skip: int = 1
start: int = 0
data: List