Members - short description

Loading and Serialization

Member	Description
from_​json(…)	Load an aperture from JSON and bind it to line.
from_​line_​with_​associated_​apertures(…)	Build an aperture from Xsuite elements that reference associated apertures.
from_​line_​with_​limits(…)	Build an aperture from limit elements installed in the line.
from_​line_​with_​madx_​metadata(…)	Build an aperture from MAD-X layout metadata attached to a line.
to_​json(…)	Serialize the aperture model and halo parameters to JSON.

Aperture Computations

Member	Description
cross_​sections_​at_​element(…)	Return aperture cross-sections sampled across an element.
cross_​sections_​at_​s(…)	Return aperture cross-sections at the requested s positions.
get_​aperture_​sigmas_​at_​element(…)	Compute the maximum number of sigmas at which the beam fits in the aperture at element element_​name.
get_​aperture_​sigmas_​at_​s(…)	Compute the maximum number of sigmas at which the beam fits in the aperture at the given s_​positions.
get_​aperture_​sigmas_​for_​twiss(…)	Compute the maximum aperture sigmas from an already sampled Twiss table.
get_​envelope_​at_​element(…)	Compute beam-envelope polygons at the cuts of element_​name for a fixed sigma value.
get_​envelope_​at_​s(…)	Compute beam-envelope polygons at the requested s_​positions for a fixed sigma value.
get_​envelope_​for_​twiss(…)	Compute beam envelopes from an already sampled Twiss table.
get_​hvd_​aperture_​sigmas_​at_​element(…)	Compute horizontal, vertical and diagonal (45°) max aperture sigmas at element element_​name.
get_​hvd_​aperture_​sigmas_​at_​s(…)	Compute horizontal, vertical and diagonal (45°) max aperture sigmas at the given s_​positions.
get_​limit_​elements(…)	Obtain interpolated cross-sections as limit beam elements.
poses_​at_​s(…)	Return a local coordinate system (each represented by a homogeneous matrix) at all s_​positions.

Introspection

Member	Description
get_​bounds_​table(…)	Return per-profile aperture-bound information as a table.
get_​pipe_​table(…)	Return installed-pipe interval information as a table.
get_​wrapped_​s_​interval(…)	Return an s interval split at the ring boundary when needed.
s_​around_​transitions(…)	Return sampling positions around aperture-profile transitions.
halo_​params	Dictionary of halo parameters controlling beam-envelope and aperture-sigma computations.
pipe_​positions	Return the pipe-position collection view.
pipes	Return the pipe collection view.
profiles	Return the profile collection view.

Visualization

Member	Description
plot_​extents(…)	Plot beam-envelope and aperture extents along the beam line.
plot_​floor_​projection(…)	Plot installed pipe segments projected onto the floor plane.
plot_​transverse(…)	Display transverse aperture cross-sections and beam envelopes.

Members - full description

Loading and Serialization

Go to Summary table

classmethod Aperture.from_json(filename, line, **kwargs)

Load an aperture from JSON and bind it to line.

classmethod Aperture.from_line_with_associated_apertures(line, context=None, **kwargs)

Build an aperture from Xsuite elements that reference associated apertures.

classmethod Aperture.from_line_with_limits(line, context=None, **kwargs)

Build an aperture from limit elements installed in the line.

classmethod Aperture.from_line_with_madx_metadata(line, include_offsets=True, context=None, **kwargs)

Build an aperture from MAD-X layout metadata attached to a line.

Aperture.to_json(filename)

Serialize the aperture model and halo parameters to JSON.

Aperture Computations

Go to Summary table

Aperture.cross_sections_at_element(element_name: str, resolution: float | None, extents: bool = False) → Table

Return aperture cross-sections sampled across an element.

Aperture.cross_sections_at_s(s_positions: Collection[float], extents: bool = False, polygons: bool = True) → Table

Return aperture cross-sections at the requested s positions.

Parameters:

• s_positions – Longitudinal positions at which to evaluate the aperture.

• extents – Whether to include the aperture intersections with the transverse coordinate axes.

• polygons – Whether to include the interpolated cross-section polygons.

Aperture.get_aperture_sigmas_at_element(element_name: str, resolution: float | None = None, twiss: xtrack.twiss.TwissTable | None = None, **kwargs) → tuple[xdeps.table.Table, xtrack.twiss.TwissTable]

Compute the maximum number of sigmas at which the beam fits in the aperture at element element_name.

Parameters:

• elment_name – The name of the element at which the sigmas should be computed.

• resolution – The desired resolution, in meters along s, at which the sigmas should be computed. If not provided only the values at the entry and exit will be output.

• twiss – Optionally provided twiss table from which to derive the initial beam parameters at the element.

• **kwargs – Other parameters to be forwarded to get_aperture_sigmas_at_s().

Return type:

See get_aperture_sigmas_at_s().

Aperture.get_aperture_sigmas_at_s(s_positions: Iterable[float], twiss_init: xtrack.twiss.TwissInit | None = None, method: Literal['bisection', 'rays', 'exact'] = 'rays', envelopes_num_points: int = 36, num_rays: int = 32, output_max_envelopes: bool = False, output_cross_sections: bool = False) → tuple[xdeps.table.Table, xtrack.twiss.TwissTable]

Compute the maximum number of sigmas at which the beam fits in the aperture at the given s_positions.

Parameters:

• s_positions – List of s positions at which to calculate the sigmas.

• twiss_init – Optionally provided initial twiss conditions.

• method –

  A method to use for the computation: - ‘rays’ - the aperture sigma is estimated from sampled rays and the minimum over the sampled directions

  is returned (faster method, O(R) where R is the number of rays)

  • ’exact’ - the aperture sigma is estimated from sampled points on the halo racetrack, at which new sample rays are emitted to compare the local directional sigma to the aperture (O(R^2), where R is the number of rays).

  • ’bisection’ - the smallest number of sigmas for the beam to fit in the aperture is computed by bisecting on a polygon-inside-polygon problem (slower method, O(EAK), where E is the number of envelope points, A is the number of aperture points, and K is the number of bisection steps; currently K <= 25, this depends on the tolerance and search space set in beam_aperture.h).

• envelopes_num_points – Number of points to use when discretising the beam cross-section.

• num_rays – Only for methods rays and exact: number of evenly-spaced ray directions to sample in [0, 2 * pi).

• output_max_envelopes – If true, output beam-envelope polygons at the computed n1.

• output_cross_sections – If true, output interpolated aperture cross-sections.

Returns:

• A two-tuple (table, sliced_twiss), where

• • table is an xdeps.table.Table with columns s and n1.

• • if output_cross_sections is true, table also contains cross_section.

• • if output_max_envelopes is true, table also contains envelope.

• • sliced_twiss is the twiss table computed as part of the calculation.

Aperture.get_aperture_sigmas_for_twiss(sliced_twiss: TwissTable, method: Literal['bisection', 'rays', 'exact'] = 'rays', envelopes_num_points: int = 36, num_rays: int = 32, output_max_envelopes: bool = False, output_cross_sections: bool = False) → Table

Compute the maximum aperture sigmas from an already sampled Twiss table.

Unlike get_aperture_sigmas_at_s(), this method does not slice the line or calculate Twiss parameters. Each row of sliced_twiss is used directly to determine the maximum beam size that fits in the aperture.

Parameters:

• sliced_twiss – Twiss table containing the longitudinal positions and optical quantities at which to compute the aperture sigmas.

• method –

  Algorithm used to determine the limiting sigma:

  • 'rays' estimates the limit along evenly spaced ray directions.

  • 'exact' samples the halo racetrack and emits additional rays from those points.

  • 'bisection' searches for the largest envelope polygon contained in the aperture polygon.

• envelopes_num_points – Number of points used to discretise beam-envelope polygons.

• num_rays – Number of evenly spaced ray directions used by the 'rays' and 'exact' methods.

• output_max_envelopes – Whether to include beam-envelope polygons at the computed sigma.

• output_cross_sections – Whether to include the interpolated aperture cross-sections.

Returns:

Table with one row per row of sliced_twiss and the following columns:

• index: row index.

• s: longitudinal position.

• n1: maximum number of beam sigmas that fit in the aperture.

• cross_section: aperture polygon, included when output_cross_sections is true.

• envelope: beam-envelope polygon at n1, included when output_max_envelopes is true.

Return type:

table

Aperture.get_envelope_at_element(element_name: str, sigmas: float, resolution: float | None = None, twiss: xtrack.twiss.TwissTable | None = None, **kwargs) → tuple[xdeps.table.Table, xtrack.twiss.TwissTable]

Compute beam-envelope polygons at the cuts of element_name for a fixed sigma value.

Parameters:

• element_name – The name of the element at which the envelope should be computed.

• sigmas – The beam size, in sigmas, at which the envelope should be evaluated.

• resolution – The desired resolution, in meters along s, at which the envelope should be computed. If not provided only the values at the entry and exit will be output.

• twiss – Optionally provided twiss table from which to derive the initial beam parameters at the element.

• **kwargs – Other parameters to be forwarded to Aperture.get_envelope_at_s.

Returns:

• A two-tuple (envelopes, sliced_twiss), where

• • envelopes is the table returned by get_envelope_at_s().

• • sliced_twiss is the twiss table computed as part of the calculation.

Aperture.get_envelope_at_s(s_positions: Iterable[float], sigmas: float, twiss_init: xtrack.twiss.TwissInit | None = None, envelopes_num_points: int = 128, include_aper_tols: bool = True, polygons: bool = True, extents: bool = False) → tuple[xdeps.table.Table, xtrack.twiss.TwissTable]

Compute beam-envelope polygons at the requested s_positions for a fixed sigma value.

Parameters:

• s_positions – List of s positions at which to compute the envelope.

• sigmas – The beam size, in sigmas, at which the envelope should be evaluated.

• twiss_init – Optionally provided initial twiss conditions.

• envelopes_num_points – Number of points to use when discretising the beam cross-section polygon.

• include_aper_tols – If true, include the aperture mechanical tolerances associated with the active profile at each s.

• polygons – Whether to include the beam-envelope polygons in the output table.

• extents – Whether to include the horizontal and vertical envelope extents.

Returns:

• A two-tuple (envelopes, sliced_twiss), where

• • envelopes is a table containing the sampled longitudinal positions and – the requested polygon and extent outputs.

• • sliced_twiss is the twiss table computed as part of the calculation.

Aperture.get_envelope_for_twiss(sliced_twiss: TwissTable, sigmas: float, envelopes_num_points: int, include_aper_tols: bool, polygons: bool, extents: bool) → Table

Compute beam envelopes from an already sampled Twiss table.

Unlike get_envelope_at_s(), this method does not slice the line or calculate Twiss parameters. Each row of sliced_twiss is used directly to construct the beam envelope at the requested sigma level.

Parameters:

• sliced_twiss – Twiss table containing the longitudinal positions and optical quantities at which to compute the envelopes.

• sigmas – Sigma level at which to evaluate the beam envelope.

• envelopes_num_points – Number of points used to discretise each envelope polygon.

• include_aper_tols – Whether to enlarge the beam envelope by the mechanical tolerances of the active aperture profile at each longitudinal position.

• polygons – Whether to include the discretised envelope polygons in the output.

• extents – Whether to include the minimum and maximum horizontal and vertical coordinates of each envelope.

Returns:

Table with one row per row of sliced_twiss and the following columns:

• index: row index.

• s: longitudinal position.

• cross_section: envelope polygon, included when polygons is true.

• min_x and max_x: horizontal extents, included when extents is true.

• min_y and max_y: vertical extents, included when extents is true.

Return type:

table

Aperture.get_hvd_aperture_sigmas_at_element(element_name: str, resolution: float | None = None, twiss: xtrack.twiss.TwissTable | None = None) → tuple[xdeps.table.Table, xtrack.twiss.TwissTable]

Compute horizontal, vertical and diagonal (45°) max aperture sigmas at element element_name.

Parameters:

• elment_name – The name of the element at which the sigmas should be computed.

• resolution – The desired resolution, in meters along s, at which the sigmas should be computed. If not provided only the values at the entry and exit will be output.

• twiss – Optionally provided twiss table from which to derive the initial beam parameters at the element.

• **kwargs – Other parameters to be forwarded to get_hvd_aperture_sigmas_at_s().

Return type:

See get_hvd_aperture_sigmas_at_s().

Aperture.get_hvd_aperture_sigmas_at_s(s_positions: Iterable[float], twiss_init: xtrack.twiss.TwissInit | None = None) → tuple[xdeps.table.Table, xtrack.twiss.TwissTable]

Compute horizontal, vertical and diagonal (45°) max aperture sigmas at the given s_positions.

Parameters:

• s_positions – Locations at which to compute the desired quantities.

• twiss_init – Initial conditions for the twiss.

Returns:

• A two-tuple (table, sliced_twiss)

• • table is an xdeps.table.Table with columns s, – n1_horizontal, n1_vertical, n1_diagonal, and

  cross_section.

• • sliced_twiss is the twiss table computed as part of the calculation.

Aperture.get_limit_elements(s_positions: list[float]) → dict[float, Union[xtrack.beam_elements.apertures.LimitRect, xtrack.beam_elements.apertures.LimitEllipse, xtrack.beam_elements.apertures.LimitRectEllipse, xtrack.beam_elements.apertures.LimitRacetrack, xtrack.beam_elements.apertures.LimitPolygon]]

Obtain interpolated cross-sections as limit beam elements.

Aperture.poses_at_s(s_positions: Collection[float]) → dtype[dtype('float64')]]

Return a local coordinate system (each represented by a homogeneous matrix) at all s_positions.

Introspection

Go to Summary table

Aperture.get_bounds_table() → Table

Return per-profile aperture-bound information as a table.

Returns:

Table with the following columns: - name: name of the aperture bound, formed from the pipe-position

name and, when needed, a ::i suffix identifying the profile order within the pipe

• pipe_name: name of the pipe in which the installed profile appears

• profile_name: name of the installed profile

• s: survey position at which the installed profile plane intersects the reference curve

• s_start, s_end: longitudinal footprint of the installed profile on the survey

• shape: profile shape name

• shape_param: dictionary of profile shape parameters

Return type:

bounds_table

Aperture.get_pipe_table()

Return installed-pipe interval information as a table.

Returns:

Table with the following columns: - name: pipe-position name - pipe_name: underlying pipe (type) name - survey_reference: survey element used as the placement reference - s_start, s_end: interval covered by the installed profile

centre positions

• length: length of that centre-position interval

• s_span_start, s_span_end: longitudinal footprint of the projected aperture itself

• span: length of that aperture-footprint interval

For rings, wrapped intervals are represented with s_start > s_end and likewise for s_span_start > s_span_end.

Return type:

pipe_table

Aperture.get_wrapped_s_interval(start: float, end: float) → list[tuple[float, float]]

Return an s interval split at the ring boundary when needed.

For ring apertures, start and end are interpreted modulo the line length. If the interval wraps around the end of the line, the result contains two non-wrapping segments. For non-ring apertures, the interval is returned unchanged.

Aperture.s_around_transitions(tol: float | None = None, resolution: float | None = None, s_range: tuple[float, float] | None = None) → ndarray

Return sampling positions around aperture-profile transitions.

The positions are built from the longitudinal locations of the installed aperture bounds. For each stored s position, the method emits points at s - tol and s + tol. This is useful when sampling quantities that can change abruptly at profile transitions.

Parameters:

• tol – Offset applied on both sides of each transition bound. If omitted, use self.s_tol.

• resolution – If provided, add a regular grid of sampling points spaced by this step size and union it with the transition-based points.

• s_range – If provided, restrict the returned positions to this longitudinal interval. For rings, wrapped intervals are supported.

Returns:

Sorted, unique s positions clipped to the line extent.

Return type:

np.ndarray

property Aperture.halo_params: dict

Dictionary of halo parameters controlling beam-envelope and aperture-sigma computations.

The keys and their default values are:

Key	Default	Description
emitx_norm	3.5e-6	Normalised horizontal emittance [m·rad]
emity_norm	3.5e-6	Normalised vertical emittance [m·rad]
delta_rms	0.0	RMS momentum spread
tol_co	0.0	Closed-orbit tolerance [m]
tol_disp	0.0	Normalised dispersion tolerance [m]
tol_disp_ref	1.8	Reference dispersion derivative tolerance [m]
tol_disp_ref_beta	170	Reference dispersion beta-function [m]
tol_beta_beating	1.0	Beta-beating tolerance [sigma]
halo_x	6.0	Horizontal halo size [sigma]
halo_y	6.0	Vertical halo size [sigma]
halo_r	6.0	45° halo size [sigma]
halo_primary	6.0	Primary halo size [sigma]

The dictionary is mutable; individual entries can be changed with aperture.halo_params['key'] = value or in bulk with aperture.halo_params.update({...}).

property Aperture.pipe_positions: PipePositionsView

Return the pipe-position collection view.

property Aperture.pipes: PipesView

Return the pipe collection view.

property Aperture.profiles: ProfilesView

Return the profile collection view.

Visualization

Go to Summary table

Aperture.plot_extents(s_positions: Collection[float], sigmas: float | None = None, twiss_init: xtrack.twiss.TwissInit | None = None, method: Literal['bisection', 'rays', 'exact'] = 'rays', envelopes_num_points: int = 64, include_aper_tols: bool = False, plot_s_positions: collections.abc.Collection[float] | None = None, axs=None)

Plot beam-envelope and aperture extents along the beam line.

Parameters:

• s_positions – Longitudinal positions at which the aperture cross-sections and beam envelopes are evaluated.

• sigmas – Sigma level used to build the beam envelope. If omitted, the minimum available aperture sigma across s_positions is computed using method.

• twiss_init – Twiss initial conditions forwarded to the envelope and aperture-sigma computations.

• method – Method used to compute the maximum aperture sigmas when sigmas is not given.

• envelopes_num_points – Number of points used to discretise each transverse beam envelope.

• include_aper_tols – Whether aperture tolerances should be included in the beam-envelope computation.

• plot_s_positions – Coordinates to be used on the horizontal axis. If omitted, s_positions are used directly. This is useful when the data are evaluated at one set of longitudinal positions but should be displayed against another abscissa, for example a shifted, reversed, or externally defined coordinate.

• axs – Two axes on which to draw the horizontal and vertical extents. If not provided, a new figure with two shared-x subplots is created.

Returns:

• fig (matplotlib.figure.Figure) – Figure containing the plots.

• axs (sequence of matplotlib.axes.Axes) – The x- and y-extent axes, in that order.

Aperture.plot_floor_projection(ax=None, max_curve_angle_rad: float = np.float64(0.017453292519943295), origin: str | None = None, s_range: tuple[float, float] | None = None, aspect: Literal['auto', 'equal'] = 'auto')

Plot installed pipe segments projected onto the floor plane.

Parameters:

• ax – Axes object to plot on. If not given, use the current axes.

• max_curve_angle_rad – Maximum angular step used to draw curved pipe boundaries and axes.

• origin – Name of a pipe position to use as the plotting origin. When given, the floor projection is expressed in the local frame of that pipe position.

• s_range – Longitudinal window, relative to origin when provided, used to restrict which pipe segments are plotted. On rings, wrapped ranges are handled across the end of the line.

• aspect – Aspect ratio applied to the axes after plotting.

Returns:

ax – Axes containing the floor projection.

Return type:

matplotlib.axes.Axes

Aperture.plot_transverse(name: str | None = None, s_positions: collections.abc.Collection[float] | None = None, resolution: float = 0.1, sigmas: float | None = None, method: Literal['bisection', 'rays', 'exact'] = 'rays', twiss_init: xtrack.twiss.TwissInit | None = None, middle='beam', ax=None)

Display transverse aperture cross-sections and beam envelopes.

Parameters:

• name – Name of the element at which to plot. If given, s_positions are obtained from the element entry, exit, and optional resolution cuts.

• s_positions – Longitudinal positions to plot directly. Provide either name or s_positions.

• resolution – The desired resolution, in metres along s, when plotting an element.

• sigmas – The number of sigmas to plot. If None, compute and plot the limiting n1 using method.

• method – If sigmas is None, method used to compute the limiting n1.

• twiss_init – Optional initial Twiss conditions forwarded to the envelope and aperture-sigma calculations.

• middle – Whether the plot should be centred around the aperture middle, or beam reference.

• ax – Axes object to plot on, if not given, spawn a new one.

Returns:

ax – Plot’s axes object.

Return type:

matplotlib.axes.Axes