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.
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.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