Twiss Transport (Twiss)

Twiss computes uncoupled transverse transport from entrance and exit optical functions and phase advances, with optional longitudinal linear maps and chromatic phase corrections. Coordinate, reference-momentum, and arrival-time conventions are defined in Longitudinal coordinate and reference time.

The supplied optics already contains design focusing; additional magnets apply additional effects and must not double-count it. Transverse beta functions must be positive. Mu is in cycles (1 corresponds to 2π); retain the full required phase difference. The drift mode needs the bunch transition gamma, while matrix requires positive bunch length and relative momentum spread.

Usage Example

The following JSON snippet shows a Twiss entry inside Sequence:

"Twiss1": {
    "S (m)": 10.0,
    "Command": "Twiss",
    "S previous (m)": 5.0,
    "Alpha x": 0.5,
    "Alpha y": -0.3,
    "Alpha x previous": 0.4,
    "Alpha y previous": -0.2,
    "Beta x (m)": 3.5,
    "Beta y (m)": 2.8,
    "Beta x previous (m)": 3.0,
    "Beta y previous (m)": 2.5,
    "Mu x": 0.123,
    "Mu y": 0.456,
    "Mu x previous": 0.1,
    "Mu y previous": 0.4,
    "Dx (m)": 0.5,
    "Dx previous (m)": 0.3,
    "Dpx": 0.01,
    "Dpx previous": 0.005,
    "DQx": 2.0,
    "DQy": 2.0,
    "Longitudinal transfer": "drift"
}

Interface parameters

Python attribute	JSON key	Unit	Default	Description
s	S (m)	m	Required	Exit position.
command	Command	—	Twiss	Command identifier.
s_previous	S previous (m)	m	Required	Entrance position; the difference gives transport length.
alpha_x	Alpha x	—	Required	Exit horizontal Twiss α.
alpha_y	Alpha y	—	Required	Exit vertical Twiss α.
beta_x	Beta x (m)	m	Required	Positive exit horizontal Twiss β.
beta_y	Beta y (m)	m	Required	Positive exit vertical Twiss β.
mu_x	Mu x	cycles	Required	Exit horizontal phase.
mu_y	Mu y	cycles	Required	Exit vertical phase.
mu_z	Mu z	cycles	0.0	Exit longitudinal phase.
dx	Dx (m)	m	Required	Exit horizontal position dispersion.
dpx	Dpx	—	Required	Exit normalized horizontal momentum dispersion.
alpha_x_previous	Alpha x previous	—	Required	Entrance horizontal Twiss α.
alpha_y_previous	Alpha y previous	—	Required	Entrance vertical Twiss α.
beta_x_previous	Beta x previous (m)	m	Required	Positive entrance horizontal Twiss β.
beta_y_previous	Beta y previous (m)	m	Required	Positive entrance vertical Twiss β.
mu_x_previous	Mu x previous	cycles	Required	Entrance horizontal phase.
mu_y_previous	Mu y previous	cycles	Required	Entrance vertical phase.
mu_z_previous	Mu z previous	cycles	0.0	Entrance longitudinal phase.
dx_previous	Dx previous (m)	m	0.0	Entrance horizontal position dispersion.
dpx_previous	Dpx previous	—	0.0	Entrance normalized horizontal momentum dispersion.
dqx	DQx	—	0.0	Horizontal chromatic phase coefficient for this segment.
dqy	DQy	—	0.0	Vertical chromatic phase coefficient for this segment.
longitudinal_transfer	Longitudinal transfer	—	off	off, drift, or matrix.

Output and scope

The command updates particle coordinates and reference passage time but writes no diagnostic file. Place a monitor from Monitors and output at its exit to record the result. The transverse model includes neither x–y coupling nor vertical dispersion. Nonzero DQx or DQy makes phase depend on relative momentum deviation, so the full map is not a fixed six-dimensional linear matrix.

DQx and DQy are applied directly to this segment; no additional segment-length/circumference factor is applied. They must be consistent with the supplied optics and any additional nonlinear elements.

Hand-written runtime JSON may include Aperture type and Aperture value (defaults off and []), but TwissItem does not currently export these fields. When using the parameter builder, place an aperture-bearing Marker at the same location; see Aperture.

Physics Derivation

Longitudinal Transport

The central longitudinal map, between the entrance and exit dispersion transformations below, is controlled by the Longitudinal transfer parameter and supports three modes:

drift mode : Uses the gamma transition parameter. The longitudinal transport matrix element is:

\[m_{12,z} = -\left(\frac{1}{\gamma_t^2} - \frac{1}{\gamma^2}\right)(s - s_\mathrm{previous})\]

where \(\gamma_t\) is the transition gamma, \(\gamma\) is the bunch reference-particle Lorentz factor, \(s\) is the current longitudinal position, and \(s_\mathrm{previous}\) is the longitudinal position of the previous element.

matrix mode : Uses the prescribed longitudinal phase advance. The transport matrix is:

\[m_{11,z} = \cos(\phi_z)\]

\[m_{12,z} = \frac{\sigma_z}{\sigma_\delta} \sin(\phi_z)\]

\[m_{21,z} = -\frac{\sigma_\delta}{\sigma_z} \sin(\phi_z)\]

\[m_{22,z} = \cos(\phi_z)\]

where \(\phi_z\) is the longitudinal phase advance, \(\sigma_z\) is the bunch longitudinal size, and \(\sigma_\delta\) is the configured RMS relative momentum spread.

off mode : The central longitudinal transport matrix is the identity matrix. With nonzero dispersion, the entrance and exit companion terms can still change stored z.

Dispersion Handling

Since the transverse transport matrix describes only the non-dispersive part of the motion, dispersion must be removed before transport and restored after. These energy-dependent coordinate transformations also have longitudinal companion terms. For the canonical energy \(\eta=(E-E_\mathrm{ref})/(\beta_0P_0c)\), define

\[g(\delta)=\frac{d\delta}{d\eta} =\frac{\beta_0}{\beta_\mathrm{particle}} =\frac{\sqrt{a+(1-a)(1+\delta)^2}}{1+\delta}, \qquad a=\frac{1}{\gamma_0^2}.\]

Here \(\beta_0\) and \(\gamma_0\) describe the current bunch reference particle; \(g(0)=1\). The transformations are:

1. Remove dispersion at the previous point :

\[x_1 = x - D_{x,\mathrm{previous}} \cdot \delta\]

\[px_1 = px - D_{px,\mathrm{previous}} \cdot \delta\]

\[z_\beta = z + g(\delta) \left(D_{px,\mathrm{previous}}x-D_{x,\mathrm{previous}}px\right)\]

2. Apply the prescribed transport :

The central longitudinal map acts on \((z_\beta,\delta)\):

\[z_L=m_{11,z}z_\beta+m_{12,z}\delta, \qquad \delta_2=m_{21,z}z_\beta+m_{22,z}\delta.\]

The transverse map uses the entrance momentum deviation \(\delta\) for its chromatic phase:

\[x_\mathrm{temp} = x_1 \cdot m_{11} + px_1 \cdot m_{12}\]

\[px_\mathrm{temp} = x_1 \cdot m_{21} + px_1 \cdot m_{22}\]

3. Add dispersion at the new point :

\[z_2=z_L+g(\delta_2) \left(D_x px_\mathrm{temp}-D_{px}x_\mathrm{temp}\right)\]

\[x_2 = x_\mathrm{temp} + D_x \cdot \delta_2\]

\[px_2 = px_\mathrm{temp} + D_{px} \cdot \delta_2\]

where \(D_x\) is the horizontal dispersion at the current point, \(D_{x,\mathrm{previous}}\) is the horizontal dispersion at the previous point, and \(\delta\) is the relative particle momentum deviation.

For zero betatron amplitude on the prescribed dispersion orbit, both companion terms vanish; the existing drift slip set by \(\gamma_t\) is retained. In matrix mode, the entrance correction can also change \(\delta_2\) and hence the restored transverse dispersion.

These terms complete the dispersion coordinate transformations, not the full six-dimensional symplectic map: the action-dependent flight-time term associated with DQx/DQy is not included, and matrix retains its linear map in \((z_\beta,\delta)\) rather than canonical energy at finite momentum deviation.

Transverse Transport Matrix

The transverse transport matrix is expressed in terms of the Twiss parameters and phase advance at the previous and current points. Taking the horizontal direction as an example:

\[m_{11,x} = \sqrt{\frac{\beta_x}{\beta_{x,\mathrm{prev}}}} \left(\cos\phi_x + \alpha_{x,\mathrm{prev}} \sin\phi_x\right)\]

\[m_{12,x} = \sqrt{\beta_x \, \beta_{x,\mathrm{prev}}} \sin\phi_x\]

\[m_{21,x} = -\frac{1 + \alpha_x \, \alpha_{x,\mathrm{prev}}} {\sqrt{\beta_x \, \beta_{x,\mathrm{prev}}}} \sin\phi_x + \frac{\alpha_{x,\mathrm{prev}} - \alpha_x} {\sqrt{\beta_x \, \beta_{x,\mathrm{prev}}}} \cos\phi_x\]

\[m_{22,x} = \sqrt{\frac{\beta_{x,\mathrm{prev}}}{\beta_x}} \left(\cos\phi_x - \alpha_x \sin\phi_x\right)\]

where \(\beta_x\) and \(\alpha_x\) are the horizontal Twiss parameters at the current point, \(\beta_{x,\mathrm{prev}}\) and \(\alpha_{x,\mathrm{prev}}\) are the horizontal Twiss parameters at the previous point, and \(\phi_x\) is the horizontal phase advance between the two points.

The transport matrix for the vertical direction (y) has exactly the same form; simply replace the subscript x with y.

Chromaticity Correction

Momentum deviation causes tune shifts, which are corrected through the chromaticity parameters:

\[\phi_x = \phi_x + \delta \cdot \Delta Q_x \cdot 2\pi\]

\[\phi_y = \phi_y + \delta \cdot \Delta Q_y \cdot 2\pi\]

where \(\Delta Q_x\) and \(\Delta Q_y\) are the horizontal and vertical chromaticities, respectively, and \(\delta\) is the relative particle momentum deviation.

Longitudinal Coordinate Continuity

Stored z remains continuous, retaining multi-turn slip. Physical arrival time is \(t_i=T_b-z_i/(\beta_b c)\) using the current reference event; nominal slot offsets do not enter this reconstruction.

t0 Update

The reference time t0 is updated based on the longitudinal position change:

\[\Delta t = \frac{s - s_\mathrm{previous}}{\beta \, c}\]

where \(\beta\) is the normalized reference-particle speed and \(c\) is the speed of light.

Phase and momentum notation

Momentum deviation in these equations is the dimensionless \(\delta=P/P_0-1\), not an absolute momentum increment. Before chromatic correction, \(\phi_u=2\pi(\mu_u-\mu_{u,\mathrm{previous}})\). The longitudinal matrix map uses the configured RMS bunch length and relative momentum spread; it does not recompute them from the current particle distribution.