transfer_matrices_p module
Define every element transfer matrix.
Units are taken exactly as in TraceWin, i.e. fifth line is z (m) and
sixth line is dp/p.
Todo
3D field maps?
Todo
Maybe it would be clearer to compose r_xx, r_yy, r_zz. As an example, the zz_drift is used in several places.
Todo
Will be necessary to separate this module into several sub-packages
- drift(gamma_in, delta_s, omega_0_bunch, n_steps=1)[source]
Calculate the transfer matrix of a drift.
- Parameters:
gamma_in (
float) – Lorentz gamma at entry of drift.delta_s (
float) – Size of the drift in \(\mathrm{mm}\).omega_0_bunch (
float) – Pulsation of the beam.n_steps (
int, default:1) – Number of integration steps. The number of integration steps has no influence on the results. The default is one. It is different from unity when crossing a failed field map, as it allows to keep the same size oftransfer_matrixandgamma_phibetween nominal and fixed linacs.
- Return type:
tuple[ndarray[tuple[Any,...],dtype[double]],ndarray[tuple[Any,...],dtype[double]],None]- Returns:
NDArray[np.float64] –
(n_steps, 6, 6)array containing the transfer matrices.NDArray[np.float64] –
(n_steps, 2)with Lorentz gamma in first column and relative phase in second column.None – Dummy variable for consistency with the field map function.
- quad(gamma_in, delta_s, gradient, omega_0_bunch, q_adim, e_rest_mev)[source]
Calculate the transfer matrix of a quadrupole.
Todo
There is room for speeding up this function. Could have one function for focusing and one for defocusing. Magnetic rigidity, focusing strength could be calculated inline.
- Parameters:
delta_s (
float) – Size of the drift in \(\mathrm{m}\).gamma_in (
float) – Lorentz gamma at entry of drift.n_steps – Number of integration steps. The number of integration steps has no influence on the results. The default is one. It is different from unity when crossing a failed field map, as it allows to keep the same size of
transfer_matrixandgamma_phibetween nominal and fixed linacs.gradient (
float) – Quadrupole gradient in \(\mathrm{T/m}\).omega_0_bunch (
float) – Pulsation of the beam.q_adim (
float) – Adimensioned charge of accelerated particle.e_rest_mev (
float) – Rest energy of the accelerated particle.
- Return type:
tuple[ndarray[tuple[Any,...],dtype[double]],ndarray[tuple[Any,...],dtype[double]],None]- Returns:
NDArray[np.float64] –
(1, 6, 6)array containing the transfer matrices.NDArray[np.float64] –
(1, 2)array with Lorentz factor in first column and relative phase in second column.None – Dummy variable for consistency with the field map function.
- _horizontal_focusing_quadrupole(focusing_strength, delta_s, gamma_in_min2)[source]
Transfer matrix of a quadrupole focusing in horizontal plane.
- _horizontal_defocusing_quadrupole(focusing_strength, delta_s, gamma_in_min2)[source]
Transfer matrix of a quadrupole defocusing in horizontal plane.
- field_map_rk4(gamma_in, d_z, n_steps, omega0_rf, delta_phi_norm, delta_gamma_norm, complex_e_func, real_e_func)[source]
Calculate the transfer matrix of
FieldMapusing Runge-Kutta.We slice the field map in a serie of drift-thin acceleration gap-drift. We pre-compute some constants to speed up the calculation:
- Parameters:
gamma_in (
float) – Lorentz factor at entry of field map.d_z (
float) – Size of the integration step in \(\mathrm{m}\).n_steps (
int) – Number of integration steps.omega0_rf (
float) – RF pulsation in \(\mathrm{rad/s}\).delta_phi_norm (
float) –Constant to speed up calculation.
\[\Delta\phi_\mathrm{norm} = \frac{\omega_0 \Delta z}{c}\]delta_gamma_norm (
float) –Constant to speed up calculation.
\[\Delta\gamma_\mathrm{norm} = \frac{q_\mathrm{adim} \Delta z} {E_\mathrm{rest}}\]complex_e_func (
Callable[[float|tuple[float,float] |tuple[float,float,float],float],complex]) – Takes in the z-position of the particle and the phase, return the complex field component at this phase and position.real_e_func (
Callable[[float|tuple[float,float] |tuple[float,float,float],float],float]) – Takes in the z-position of the particle and the phase, return the real field component at this phase and position.
- Return type:
tuple[ndarray[tuple[Any,...],dtype[double]],ndarray[tuple[Any,...],dtype[double]],complex]- Returns:
NDArray[np.float64] – \(6\times 6 \times n\) matrix, holding the \(2\times2\) longitudinal transfer matrix of every field map slice along the field map.
NDArray[np.float64] – \(2\times n\) array, holding Lorentz factor and phase of the synchronous particle along the linac.
complex – Complex integral of the field experienced by the synchronous particle when crossing the cavity.
- thin_lense(scaled_e_middle, scaled_delta_e, gamma_in, gamma_out, gamma_m, half_dz, omega0_rf)[source]
Compute propagation in a slice of field map using thin lense approximation.
Thin lense approximation: drift-acceleration-drift. The transfer matrix of the thin accelerating gap is:
\[\begin{split}\begin{bmatrix} 1 & 1 & 0 & 0 & 0 & 0 \\ k_{1xy} & k_{2xy} & 0 & 0 & 0 & 0 \\ 0 & 0 & 1 & 1 & 0 & 0 \\ 0 & 0 & k_{1xy} & k_{2xy} & 0 & 0 \\ 0 & 0 & 0 & 0 & k_{3z} & 1 \\ 0 & 0 & 0 & 0 & k_{1z} & k_{2z} \\ \end{bmatrix}\end{split}\]Where:
\[\begin{split}\left\{ \begin{aligned} k_{1z} &= \Im(\widetilde{E}) \frac{\omega_0}{\beta_m c} \\ k_{2z} &= 1 - (2 - \beta_m^2)\Re(\widetilde{E}) \\ k_{3z} &= \frac{1 - \Re(\widetilde{E})}{k_{2z}} \end{aligned} \right.\end{split}\]and:
\[\begin{split}\left\{ \begin{aligned} k_{1xy} &= \frac{1}{2} \left( \Im(\widetilde{E}) \frac{\omega_0 \beta_m}{c} - \Delta E \right) \\ k_{2xy} &= 1 - \Re(\widetilde{E}) \end{aligned} \right.\end{split}\]We use:
\[\begin{split}\left\{ \begin{aligned} \widetilde{E} &= \frac{\Delta\gamma_\mathrm{norm}}{\gamma_m\beta_m^2} \widetilde{E_z}\left(z + \frac{\Delta z}{2}, \phi_m\right) \\ \Delta E &= \frac{\Delta\gamma_\mathrm{norm}}{\gamma_m\beta_m^2} \Re\left( \widetilde{E_z}(z + \Delta z, \phi_m) - \widetilde{E_z}(z, \phi_m) \right) \end{aligned} \right.\end{split}\]In the script, \(\widetilde{E}\) is
scaled_e_middle_norm, and \(\gamma_m\beta_m^2\Delta E\) isscaled_delta_e.Quantities with a \(m\) subscript are taken at the middle of the accelerating gap. \(i\) are in the first drift, \(i+1\) in the second.
Note
In TraceWin documentation:
\(k_{1z}\) and \(k_{2z}\) are called \(K_1\) and \(K_2\). They miss a \(\Delta z\) term.
\(k_{1xy}\) and \(k_{2xy}\) are called \(k_1\) and \(k_2\).
Our complex electric field \(\widetilde{E_z}\) would be written:
\[\widetilde{E_z} = E_0 \sin{ \left( \frac{Kz}{\beta_c} \right) } \left[ \cos{(\omega t_s + \varphi_0)} + j\sin{(\omega t_s + \varphi_0)} \right]\]Constants used to speed up calculations:
\[\begin{split}\left\{ \begin{aligned} \Delta\gamma_\mathrm{norm} &= \frac{q_\mathrm{adim} \Delta z} {E_\mathrm{rest}}\\ \Delta\phi_\mathrm{norm} &= \frac{\omega_0 \Delta z}{c} \end{aligned} \right.\end{split}\]
- Parameters:
scaled_e_middle (
complex) –Complex electric field in the accelerating gap multiplied by \(\Delta\gamma_\mathrm{norm}\). We normalize this quantity by \(\gamma_m\beta_m^2\) in the routine to obtain \(\widetilde{E}\).
\[\Delta\gamma_\mathrm{norm} \widetilde{E_z}\left(z + \frac{\Delta z}{2}, \phi_m\right)\]scaled_delta_e (
float) –Electric field multiplied by \(\Delta\gamma_\mathrm{norm}\) and differenciated between start and and of the thin lense.
\[\Delta\gamma_\mathrm{norm} \frac{ E_z(z + \Delta z, \phi_m) - E_z(z, \phi_m) }{ \Delta z }\]gamma_in (
float) – Lorentz factor at entrance of first drift.gamma_out (
float) – Lorentz factor at exit of first drift.gamma_m (
float) – Lorentz factor at the thin acceleration gap.half_dz (
float) – Half a spatial step in \(\mathrm{m}\).omega0_rf (
float) – Pulsation of the cavity.
- Return type:
- Returns:
(1, 6, 6)transfer matrix of the thin lense.
- _focusing_strength(gradient, magnetic_rigidity)[source]
Compute focusing strength of the quadrupole.