beam_parameters module

Gather the beam parameters of all the phase spaces.

For a list of the units associated with every parameter, see Units and conventions.

class BeamParameters(z_abs, gamma_kin, beta_kin, sigma_in=None, element_to_index=<function default_element_to_index at 0x7318fb3614e0>)[source]

Bases: InitialBeamParameters

Hold all emittances, envelopes, etc in various planes.

Parameters:

z_abs (ndarray) – Absolute position in the linac in \(\mathrm{m}\).
gamma_kin (ndarray) – Lorentz gamma factor.
beta_kin (ndarray) – Lorentz gamma factor.
sigma_in (ndarray | None, default: None) – The (6, 6) \(\sigma\) beam matrix at the entrance of the linac/ portion of linac.
zdelta – Beam parameters respectively in the \([z-z\delta]\), \([z-z']\), \([\phi-W]\), \([x-x']\), \([y-y']\) and \([t-t']\) planes.
z – Beam parameters respectively in the \([z-z\delta]\), \([z-z']\), \([\phi-W]\), \([x-x']\), \([y-y']\) and \([t-t']\) planes.
phiw – Beam parameters respectively in the \([z-z\delta]\), \([z-z']\), \([\phi-W]\), \([x-x']\), \([y-y']\) and \([t-t']\) planes.
x – Beam parameters respectively in the \([z-z\delta]\), \([z-z']\), \([\phi-W]\), \([x-x']\), \([y-y']\) and \([t-t']\) planes.
y – Beam parameters respectively in the \([z-z\delta]\), \([z-z']\), \([\phi-W]\), \([x-x']\), \([y-y']\) and \([t-t']\) planes.
t – Beam parameters respectively in the \([z-z\delta]\), \([z-z']\), \([\phi-W]\), \([x-x']\), \([y-y']\) and \([t-t']\) planes.
phiw99 – 99% beam parameters respectively in the \([\phi-W]\), \([x-x']\) and \([y-y']\) planes. Only used with multiparticle simulations.
x99 – 99% beam parameters respectively in the \([\phi-W]\), \([x-x']\) and \([y-y']\) planes. Only used with multiparticle simulations.
y99 – 99% beam parameters respectively in the \([\phi-W]\), \([x-x']\) and \([y-y']\) planes. Only used with multiparticle simulations.
element_to_index (ELEMENT_TO_INDEX_T, default: <function default_element_to_index at 0x7318fb3614e0>) – Takes an Element, its name, 'first' or 'last' as argument, and returns corresponding index. Index should be the same in all the arrays attributes of this class: z_abs, beam_parameters attributes, etc. Used to easily get the desired properties at the proper position.

z_abs: ndarray

gamma_kin: ndarray

beta_kin: ndarray

sigma_in: ndarray | None = None

element_to_index(*, pos=None, return_elt_idx=False, handle_missing_elt=False)

Return all indexes whatever the inputs are.

Parameters:

elt (str | Element | Literal['first', 'last']) – Element for which you want position. Can be the Element.name attribute or the Element instance itself. Actually unused in this default function.
pos (Literal['in', 'out'] | None, default: None) – Position within the Element. If not provided, all indexes of Element will be returned. Actually unused in this default function.
return_elt_idx (bool, default: False) – Return a position in a ListOfElements instance. Used for arguments such as phi_s, which holds one value per Element. Actually unused in this default function.
handle_missing_elt (bool, default: False) – Look for an equivalent element when elt is not in _elts.

Return type:

int | slice

Returns:

Index(es) of given elt, at given pos. Returns all indexes in this default function.

__post_init__()[source]

Declare the phase spaces.

Return type:: None

get(*keys, to_numpy=True, none_to_nan=False, phase_space_name=None, elt=None, pos=None, handle_missing_elt=False, **kwargs)[source]

Retrieve attribute values from the beam or its nested phase spaces.

This method supports flexible ways of accessing attributes such as alpha, beta, etc., which are common to all PhaseSpaceBeamParameters. Attributes can be retrieved directly, from a specific phase space, or using a compound key like "alpha_zdelta".

If a phase_space_name is provided, the method will first attempt to resolve all keys through that phase space. If a key is not found there, it will fall back to a recursive global search.

Notes

All phase space components (e.g., x, y, z, zdelta) share the same attribute names. To disambiguate, you can either: - Provide a phase_space_name argument, or - Use compound keys such as "alpha_zdelta".

If neither method is used and ambiguity arises, a recursive search is performed.

Examples

>>> beam_parameters.get("beta", phase_space_name="zdelta")
>>> beam_parameters.get("beta_zdelta")  # Alternative
>>> beam_parameters.get("beta")  # May fail or be ambiguous

Parameters:

*keys (Literal['alpha_phiw', 'beta_phiw', 'envelope_energy_phiw', 'envelope_pos_phiw', 'eps_phiw', 'eps_no_normalization_phiw', 'eps_normalized_phiw', 'gamma_phiw', 'sigma_phiw', 'twiss_phiw', 'alpha_phiw99', 'beta_phiw99', 'envelope_energy_phiw99', 'envelope_pos_phiw99', 'eps_phiw99', 'eps_no_normalization_phiw99', 'eps_normalized_phiw99', 'gamma_phiw99', 'sigma_phiw99', 'twiss_phiw99', 'alpha_t', 'beta_t', 'envelope_energy_t', 'envelope_pos_t', 'eps_t', 'eps_no_normalization_t', 'eps_normalized_t', 'gamma_t', 'sigma_t', 'twiss_t', 'alpha_x', 'beta_x', 'envelope_energy_x', 'envelope_pos_x', 'eps_x', 'eps_no_normalization_x', 'eps_normalized_x', 'gamma_x', 'sigma_x', 'twiss_x', 'alpha_x99', 'beta_x99', 'envelope_energy_x99', 'envelope_pos_x99', 'eps_x99', 'eps_no_normalization_x99', 'eps_normalized_x99', 'gamma_x99', 'sigma_x99', 'twiss_x99', 'alpha_y', 'beta_y', 'envelope_energy_y', 'envelope_pos_y', 'eps_y', 'eps_no_normalization_y', 'eps_normalized_y', 'gamma_y', 'sigma_y', 'twiss_y', 'alpha_y99', 'beta_y99', 'envelope_energy_y99', 'envelope_pos_y99', 'eps_y99', 'eps_no_normalization_y99', 'eps_normalized_y99', 'gamma_y99', 'sigma_y99', 'twiss_y99', 'alpha_z', 'beta_z', 'envelope_energy_z', 'envelope_pos_z', 'eps_z', 'eps_no_normalization_z', 'eps_normalized_z', 'gamma_z', 'sigma_z', 'twiss_z', 'alpha_zdelta', 'beta_zdelta', 'envelope_energy_zdelta', 'envelope_pos_zdelta', 'eps_zdelta', 'eps_no_normalization_zdelta', 'eps_normalized_zdelta', 'gamma_zdelta', 'sigma_zdelta', 'twiss_zdelta'] | Literal['alpha', 'beta', 'beta_kin', 'envelope_energy', 'envelope_pos', 'eps', 'eps_no_normalization', 'eps_normalized', 'gamma', 'gamma_kin', 'sigma', 'twiss', 'z_abs'] | Literal['phiw', 'phiw99', 't', 'x', 'x99', 'y', 'y99', 'z', 'zdelta']) – One or more names of attributes to retrieve.
to_numpy (bool, default: True) – Whether to convert list-like outputs to NumPy arrays. The default is True.
none_to_nan (bool, default: False) – Whether to convert None values to np.nan. The default is False.
phase_space_name (Literal['phiw', 'phiw99', 't', 'x', 'x99', 'y', 'y99', 'z', 'zdelta'] | None, default: None) – If specified, restricts the search to the given phase space component before falling back.
elt (str | Element | None, default: None) – Element name for slicing data arrays.
pos (Literal['in', 'out'] | None, default: None) – Position key for slicing data arrays.
handle_missing_elt (bool, default: False) – Look for an equivalent element when elt is not in BeamParameters.element_to_index ‘s _elts.
**kwargs (Any) – Additional keyword arguments passed to the internal recursive getter.

Returns:

A single value if one key is provided, or a tuple of values if multiple keys are given.

Return type:

Any

property sigma: ndarray: Give value of sigma.

sub_sigma_in(phase_space_name)[source]

Give the entry \(\sigma\) beam matrix in a single phase space.

Parameters:

phase_space_name (Literal['x', 'y', 'zdelta']) – Name of the phase space from which you want the \(\sigma\) beam matrix.

Return type:

ndarray

Returns:

(2, 2) \(\sigma\) beam matrix at the linac entrance, in a
single phase space.

property tracewin_command: list[str]: Return the proper input beam parameters command.

_create_tracewin_command(warn_missing_phase_space=True)[source]

Turn emittance, alpha, beta from the proper phase-spaces into command.

When phase-spaces were not created, we return np.nan which will ultimately lead TraceWin to take this data from its INI file.

Parameters:: warn_missing_phase_space (bool, default: True)
Return type:: list[str]

set_mismatches(reference_beam_parameters, *phase_space_names, **mismatch_kw)[source]

Compute and set mismatch in every possible phase space.

Parameters:

reference_beam_parameters (Self)
phase_space_names (Literal['phiw', 'phiw99', 't', 'x', 'x99', 'y', 'y99', 'z', 'zdelta'])
mismatch_kw (bool)

Return type:

None

_get_phase_spaces(reference_beam_parameters, phase_space_name, raise_missing_phase_space_error, **mismatch_kw)[source]

Get the two phase spaces between which mismatch will be computed.

Parameters:

reference_beam_parameters (Self)
phase_space_name (Literal['phiw', 'phiw99', 't', 'x', 'x99', 'y', 'y99', 'z', 'zdelta'])
raise_missing_phase_space_error (bool)
mismatch_kw (bool)

Return type:

tuple[PhaseSpaceBeamParameters | None, PhaseSpaceBeamParameters | None]

_set_mismatch_for_transverse(raise_missing_phase_space_error=True, raise_missing_mismatch_error=True, **mismatch_kw)[source]

Set t mismatch as average of x and y.

Parameters:

raise_missing_phase_space_error (bool, default: True)
raise_missing_mismatch_error (bool, default: True)
mismatch_kw (bool)

Return type:

None

__init__(z_abs, gamma_kin, beta_kin, sigma_in=None, element_to_index=<function default_element_to_index at 0x7318fb3614e0>)

Parameters:

z_abs (ndarray)
gamma_kin (ndarray)
beta_kin (ndarray)
sigma_in (ndarray | None, default: None)
element_to_index (ELEMENT_TO_INDEX_T, default: <function default_element_to_index at 0x7318fb3614e0>)

Return type:

None

_to_float_if_necessary(eps, alpha, beta)[source]

Ensure that the data given to TraceWin will be float.

Deprecated since version v3.2.2.3: eps, alpha, beta will always be arrays of size 1.

Parameters:

eps (float | ndarray)
alpha (float | ndarray)
beta (float | ndarray)

Return type:

tuple[float, float, float]