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 BeamParameters.<lambda> at 0x73dca86ed300>)[source]

Bases: InitialBeamParameters

Hold all emittances, envelopes, etc in various planes.

Parameters:

  • z_abs (ndarray) – Absolute position in the linac in m.

  • gamma_kin (ndarray) – Lorentz gamma factor.

  • beta_kin (ndarray) – Lorentz gamma factor.

  • sigma_in (ndarray | None, default: None) – Holds the (6, 6) \(\sigma\) beam matrix at the entrance of the linac/portion of linac.

  • zdelta – Holds beam parameters respectively in the \([z-z\delta]\), \([z-z']\), \([\phi-W]\), \([x-x']\), \([y-y']\) and \([t-t']\) planes.

  • z – Holds beam parameters respectively in the \([z-z\delta]\), \([z-z']\), \([\phi-W]\), \([x-x']\), \([y-y']\) and \([t-t']\) planes.

  • phiw – Holds beam parameters respectively in the \([z-z\delta]\), \([z-z']\), \([\phi-W]\), \([x-x']\), \([y-y']\) and \([t-t']\) planes.

  • x – Holds beam parameters respectively in the \([z-z\delta]\), \([z-z']\), \([\phi-W]\), \([x-x']\), \([y-y']\) and \([t-t']\) planes.

  • y – Holds beam parameters respectively in the \([z-z\delta]\), \([z-z']\), \([\phi-W]\), \([x-x']\), \([y-y']\) and \([t-t']\) planes.

  • t – Holds beam parameters respectively in the \([z-z\delta]\), \([z-z']\), \([\phi-W]\), \([x-x']\), \([y-y']\) and \([t-t']\) planes.

  • phiw99 – Holds 99% beam parameters respectively in the \([\phi-W]\), \([x-x']\) and \([y-y']\) planes. Only used with multiparticle simulations.

  • x99 – Holds 99% beam parameters respectively in the \([\phi-W]\), \([x-x']\) and \([y-y']\) planes. Only used with multiparticle simulations.

  • y99 – Holds 99% beam parameters respectively in the \([\phi-W]\), \([x-x']\) and \([y-y']\) planes. Only used with multiparticle simulations.

  • element_to_index (Callable[[str | Element, str | None], int | slice], default: <function BeamParameters.<lambda> at 0x73dca86ed300>) – 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)
__post_init__()[source]

Declare the phase spaces.

Return type:

None

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

Get attributes from this class or its attributes.

Notes

What is particular in this getter is that all PhaseSpaceBeamParameters objects have attributes with the same name: twiss, alpha, beta, gamma, eps, etc.

Hence, you must provide either a phase_space_name argument which shall be in PHASE_SPACES, either or you must append the name of the phase space to the name of the desired variable with an underscore.

Examples

>>> beam_parameters: BeamParameters
>>> beam_parameters.get("beta", phase_space_name="zdelta")
>>> beam_parameters.get("beta_zdelta")  # Alternative
>>> beam_parameters.get("beta")  # Incorrect
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']) – Name of the desired attributes.

  • to_numpy (bool, default: True) – If you want the list output to be converted to a np.ndarray.

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

  • elt (Element | None, default: None) – If provided, return the attributes only at the considered Element.

  • pos (Literal['in', 'out'] | None, default: None) – If you want the attribute at the entry, exit, or in the whole Element. The default is None, in which case you get an array with keys from the start to the end of the element.

  • phase_space_name (Literal['phiw', 'phiw99', 't', 'x', 'x99', 'y', 'y99', 'z', 'zdelta'] | None, default: None) – Phase space in which you want the key. The default is None. In this case, the quantities from the zdelta phase space are taken. Otherwise, it must be in PHASE_SPACES.

  • **kwargs (Any) – Other arguments passed to recursive getter.

Returns:

out – Attribute(s) value(s).

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 BeamParameters.<lambda> at 0x73dca86ed300>)
Parameters:
_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:
Return type:

tuple[float, float, float]