initial_beam_parameters module

Gather beam parameters at the entrance of a ListOfElements.

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

class InitialBeamParameters(z_abs, gamma_kin, beta_kin)

Bases: object

Hold all emittances, envelopes, etc in various planes at a single position.

Parameters:

• z_abs (float) – Absolute position in the linac in \(\mathrm{m}\).

• gamma_kin (float) – Lorentz gamma factor.

• beta_kin (float) – Lorentz beta factor.

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

z_abs: float

gamma_kin: float

beta_kin: float

__post_init__()

Declare the phase spaces without initalizing them.

Return type:

None

__str__()

Give compact information on the data that is stored.

Return type:

str

has(key)

Tell if the attribute exists, either directly or within a phase space.

Notes

key = 'property_phasespace' will return True if 'property' exists in phasespace. Hence, the following two commands will have the same return values:

self.has("twiss_zdelta")
self.zdelta.has("twiss")

See also

get

Parameters:

key (str)

Return type:

bool

get(*keys, to_numpy=True, none_to_nan=False, phase_space_name=None, **kwargs)

Get attribute values from the beam or its nested phase space objects.

This method supports flexible ways of accessing attributes such as alpha, beta, etc., which are common to all InitialPhaseSpaceBeamParameters. 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

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

See also

has()

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.

• none_to_nan (bool, default: False) – Whether to convert None values to np.nan.

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

• **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 tracewin_command: list[str]

Return the proper input beam parameters command.

property sigma: ndarray

Give value of sigma.

Todo

Could be cleaner.

_create_tracewin_command(warn_missing_phase_space=True)

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]

__init__(z_abs, gamma_kin, beta_kin)

Parameters:

• z_abs (float)

• gamma_kin (float)

• beta_kin (float)

Return type:

None