helper module

Define functions useful for beam parameters calculations.

For more information on the units that are used in this module, see Units and conventions.

reconstruct_sigma(phase_space_name, sigma_00, sigma_01, eps, tol=1e-08, eps_is_normalized=False, gamma_kin=None, beta_kin=None, **beam)[source]

Set \(\sigma\) matrix from the two top components and emittance.

Inputs are in \(\mathrm{mm}\) and \(\mathrm{mrad}\), but the \(\sigma\) matrix is in SI units (\(\mathrm{m}\) and \(\mathrm{rad}\)).

See also

Units and conventions.

Parameters:

  • phase_space_name (str) – Name of the phase space.

  • sigma_00 (ndarray[tuple[Any, ...], dtype[TypeVar(_ScalarT, bound= generic)]]) – (n, ) array of top-left sigma matrix components.

  • sigma_01 (ndarray[tuple[Any, ...], dtype[TypeVar(_ScalarT, bound= generic)]]) – (n, ) array of top-right (bottom-left) sigma matrix components.

  • eps (ndarray[tuple[Any, ...], dtype[TypeVar(_ScalarT, bound= generic)]]) – (n, ) un-normalized emittance array, in units consistent with sigma_00 and sigma_01.

  • tol (float, default: 1e-08) – sigma_00 is set to np.nan where it is under tol to avoid RuntimeWarning. The default is 1e-8.

  • eps_is_normalized (bool, default: False) – To tell if the given emittance is already normalized. The default is True. In this case, it is de-normalized and gamma_kin must be provided.

  • gamma_kin (ndarray[tuple[Any, ...], dtype[TypeVar(_ScalarT, bound= generic)]] | None, default: None) – Lorentz gamma factor. The default is None. It is mandatory to give it if the emittance is given unnormalized.

  • beta_kin (ndarray[tuple[Any, ...], dtype[TypeVar(_ScalarT, bound= generic)]] | None, default: None) – Lorentz beta factor. The default is None. In this case, we compute it from gamma_kin.

  • beam – Configuration dictionary holding the beam parameters.

Return type:

ndarray[tuple[Any, ...], dtype[TypeVar(_ScalarT, bound= generic)]]

Returns:

(n, 2, 2) full sigma matrix along the linac.

eps_from_sigma(phase_space_name, sigma, gamma_kin, beta_kin, beam_kwargs)[source]
Overloads:

  • phase_space_name (str), sigma (NDArray), gamma_kin (NDArray), beta_kin (NDArray), beam_kwargs (BeamKwargs) → tuple[NDArray, NDArray]

  • phase_space_name (str), sigma (NDArray), gamma_kin (float), beta_kin (float), beam_kwargs (BeamKwargs) → tuple[float, float]

Parameters:
Return type:

tuple[ndarray[tuple[Any, …], dtype[_ScalarT]] | float, ndarray[tuple[Any, …], dtype[_ScalarT]] | float]

Compute emittance from \(\sigma\) beam matrix.

In the \([z-\delta]\) phase space, emittance is in \(\mathrm{\pi.mm.\%}\). In the transverse phase spaces, emittance is in \(\mathrm{\pi.mm.mrad}\). \(\sigma\) is always in SI units.

Parameters:
Returns:

  • eps_no_normalization – (n, ) array (or float) of emittance, not normalized.

  • eps_normalized – (n, ) array (or float) of emittance, normalized.

Return type:

tuple[ndarray[tuple[Any, …], dtype[_ScalarT]] | float, ndarray[tuple[Any, …], dtype[_ScalarT]] | float]

twiss_from_sigma(phase_space_name, sigma, eps_no_normalization, tol=1e-08)[source]

Compute the Twiss parameters using the \(\sigma\) matrix.

In the \([z-\delta]\) phase space, emittance and Twiss are in \(\mathrm{mm}\) and \(\mathrm{\%}\). In the transverse phase spaces, emittance and Twiss are in \(\mathrm{mm}\) and \(\mathrm{mrad}\). \(\sigma\) is always in SI units.

Todo

Would be better if all emittances had the same units? Check consistency with rest of the code…

Parameters:

  • phase_space_name (str) – Name of the phase space, used to set the proper normalization.

  • sigma (ndarray[tuple[Any, ...], dtype[TypeVar(_ScalarT, bound= generic)]]) – (n, 2, 2) array (or (2, 2)) holding \(\sigma\) beam matrix.

  • eps_no_normalization (ndarray[tuple[Any, ...], dtype[TypeVar(_ScalarT, bound= generic)]] | float) – (n, ) array (or float) of unnormalized emittance.

  • tol (float, default: 1e-08) – eps_no_normalization is set to np.nan where it is under tol to avoid RuntimeWarning. The default is 1e-8.

Return type:

ndarray[tuple[Any, ...], dtype[TypeVar(_ScalarT, bound= generic)]]

Returns:

(n, 3) (or (3, )) array of Twiss parameters.

envelopes_from_sigma(phase_space_name, sigma)[source]

Compute the envelopes.

Units are \(\mathrm{mm}\) for the position envelope in \([z-\delta]\), \([x-x']\), \([y-y']\). Units are \(\mathrm{\%}\) for the energy envelope in \([z-\delta]\), and \(\mathrm{mrad}\) for \([x-x']\) and \([y-y']\).

Parameters:

  • phase_space_name (str) – Name of the phase space, used to set the proper normalization.

  • sigma (ndarray[tuple[Any, ...], dtype[TypeVar(_ScalarT, bound= generic)]]) – (n, 2, 2) (or (2, 2)) array holding \(\sigma\) beam matrix.

Return type:

ndarray[tuple[Any, ...], dtype[TypeVar(_ScalarT, bound= generic)]]

Returns:

(n, 2) (or (2, )) array with position envelope in first column, energy envelope in second.

sigma_from_transfer_matrices(sigma_in, tm_cumul)[source]

Compute the \(\sigma\) beam matrices over the linac.

sigma_in and transfer matrices shall have same units, in the same phase space.

Parameters:
Return type:

ndarray[tuple[Any, ...], dtype[TypeVar(_ScalarT, bound= generic)]]

Returns:

(n, 2, 2) \(\sigma\) beam matrix along the linac.

envelopes_from_twiss_eps(twiss, eps)[source]

Compute the envelopes from the Twiss parameters and emittance.

Parameters:
Return type:

ndarray[tuple[Any, ...], dtype[TypeVar(_ScalarT, bound= generic)]]

Returns:

(n, 2) (or (2, )) array with position envelope in first column, energy envelope in second.

eps_from_other_phase_space(other_phase_space_name, phase_space_name, eps_other, gamma_kin, beta_kin, **beam_kwargs)[source]
Overloads:

  • other_phase_space_name (str), phase_space_name (str), eps_other (NDArray), gamma_kin (NDArray), beta_kin (NDArray), beam_kwargs → tuple[NDArray, NDArray]

  • other_phase_space_name (str), phase_space_name (str), eps_other (float), gamma_kin (float), beta_kin (float), beam_kwargs → tuple[float, float]

Parameters:
Return type:

tuple[ndarray[tuple[Any, …], dtype[_ScalarT]] | float, ndarray[tuple[Any, …], dtype[_ScalarT]] | float]

Convert emittance from another phase space.

Output emittance is normalized if input is, and is un-normalized if the input emittance is not normalized.

Warning

old funct returned eps with same normalisation state as given eps_other

Parameters:

  • other_phase_space_name (str) – Name of the original phase space.

  • phase_space_name (str) – Name of the phase space, used to ensure correct normalization/denormalization.

  • eps_other (ndarray[tuple[Any, ...], dtype[TypeVar(_ScalarT, bound= generic)]] | float) – (n, ) array (or float) of emittance of starting phase-space.

  • gamma_kin (ndarray[tuple[Any, ...], dtype[TypeVar(_ScalarT, bound= generic)]] | float) – (n, ) array (or float) of Lorentz gamma.

  • beta_kin (ndarray[tuple[Any, ...], dtype[TypeVar(_ScalarT, bound= generic)]] | float) – (n, ) array (or float) of Lorentz beta

  • beam_kwargs – Configuration dictionary holding the initial beam parameters.

Returns:

  • eps_no_normalization – (n, ) array (or float) of emittance, not normalized.

  • eps_normalized – (n, ) array (or float) of emittance, normalized.

Return type:

tuple[ndarray[tuple[Any, …], dtype[_ScalarT]] | float, ndarray[tuple[Any, …], dtype[_ScalarT]] | float]

twiss_from_other_phase_space(other_phase_space_name, phase_space_name, twiss_other, gamma_kin, beta_kin, **beam)[source]

Compute Twiss parameters from Twiss parameters in another plane.

Parameters:
Return type:

ndarray[tuple[Any, ...], dtype[TypeVar(_ScalarT, bound= generic)]]

Returns:

(n, 3) array of Twiss parameters.

mismatch_from_arrays(ref, fix, transp=False)[source]

Compute the mismatch factor between two ellipses.

Parameters:
Return type:

ndarray[tuple[Any, ...], dtype[TypeVar(_ScalarT, bound= generic)]]

resample_twiss_on_fix(reference_z_abs, reference_twiss, z_abs)[source]

Interpolate ref Twiss on fix Twiss to compute mismatch afterwards.

Parameters:
Return type:

ndarray[tuple[Any, ...], dtype[TypeVar(_ScalarT, bound= generic)]]

phase_space_name_hidden_in_key(key)[source]

Tell if the name of a phase-space is present in key.

Parameters:

key (str)

Return type:

bool

separate_var_from_phase_space(key)[source]

Separate variable name from phase space name.

Parameters:

key (str)

Return type:

tuple[str, Literal['phiw', 'phiw99', 't', 'x', 'x99', 'y', 'y99', 'z', 'zdelta']]