Change coordinate system

[jank324]

In our meeting today, we talked about changing the default coordinate system in Cheetah. @cr-xu @jp-ga can we assign this to either one of you? I think you have more expertise regarding this than I do.

[cr-xu]

I'll try to clearly document the changes we want to make. @jp-ga Please check if there's anything incorrect.

The coordinate system should be explained properly in the documentation.

Transverse

Change the current coordinates $(x, x', y, y')$ to the canonical cooridnates $(x,p_x, y, p_y)$.

The new transverse momentum should be the scaled one w.r.t. the reference momentum $p_x = \frac{P_x}{P_0}$ (as in bmad).

This should be merely a change in the documentation at this point as the linear transfer matrices are still correct.

Longitudinal

For the longitudinal coordinate we will stay with $(\tau, \delta)$, where $\tau = ct - \frac{s}{\beta_0} = c (t - t_0(s)) = c \Delta t$, and $\delta=\frac{E}{p_0 c} - \frac{1}{\beta_0} = \frac{E-E_0}{p_0 c} = \frac{E - E_0}{\beta_0 E_0}$. For particle arriving at a earlier time than the reference particle (bunch head), $\tau <0$. The longitudinal coordinates are derived from the $F_2 = (\frac{z}{\beta_0} - ct)(\frac{1}{\beta_0} + \delta)$ (A. Wolski Eq. 2.45).

Note:

• This coordinate $(\tau, \delta)$ is the same as in OCELOT
• In A. Wolski's book, the sign of $\tau$ is inverted
• Related to the Mad-x coordinates $(T, PT)$ as $(\tau, \delta) = (- T, PT)$, (according to this paper also in TEAPOT, PyORBIT, )
• Related to the Bmad coordinates $(z, pz)$ (Bmad manual 15.28, 15.32) as $z\text{Bmad} = -\beta \tau$ (not the reference velocity $\beta0$) and $p{z, \text{Bmad}} = \frac{\Delta E}{E_0} = \beta_0 \delta$

[cr-xu]

In addition, we should also clearly distinguish the reference energy $E_0$ and reference momentum $p_0$ ($p_0 c$), which will be different for non-relativisitic particles. Right now the attribute is called Beam.energy and should return the energy. We could add another property Beam.p0c as convenient method

[jank324]

If we are already in here, maybe we should also think about the fact that beam's currently don't track their reference s and whether doing so would be make sense (for example in light of the space charge implementation).

[cr-xu]

@jank324 Now that we're clarifying the meaning of a few variables, does it make sense to rename also the properties $s$ and $p$?

In Cheetah now $s$ actually stands for $\tau$ as in OCELOT (or $-z$ as in other simulation code like mad-x). $s$ is usually used as the position of the reference particle along the beamline, (independent variable). Also having the real $s$ would make sense now since we have space charge integration etc.

$p$ is the dimensionless relative energy offset, which is $\delta$ in most literatures, probably we can rename it to something like $dp$? So that we can provide a new property $p$ or $momentum$ to denote the actual momentum of a particle.

[jank324]

@jank324 Now that we're clarifying the meaning of a few variables, does it make sense to rename also the properties s and p?

In Cheetah now s actually stands for τ as in OCELOT (or −z as in other simulation code like mad-x). s is usually used as the position of the reference particle along the beamline, (independent variable). Also having the real s would make sense now since we have space charge integration etc.

p is the dimensionless relative energy offset, which is δ in most literatures, probably we can rename it to something like dp? So that we can provide a new property p or momentum to denote the actual momentum of a particle.

Yes, this sounds like it would make a lot of sense to do this now.

[jp-ga]

I'll try to clearly document the changes we want to make. @jp-ga Please check if there's anything incorrect.

The coordinate system should be explained properly in the documentation.

Transverse

Change the current coordinates (x,x′,y,y′) to the canonical cooridnates (x,px,y,py).

The new transverse momentum should be the scaled one w.r.t. the reference momentum px=PxP0 (as in bmad).

This should be merely a change in the documentation at this point as the linear transfer matrices are still correct.

Longitudinal

For the longitudinal coordinate we will stay with (τ,δ), where τ=ct−sβ0=c(t−t0(s))=cΔt, and δ=Ep0c−1β0=E−E0p0c=E−E0β0E0. For particle arriving at a earlier time than the reference particle (bunch head), τ<0. The longitudinal coordinates are derived from the F2=(zβ0−ct)(1β0+δ) (A. Wolski Eq. 2.45).

Note:

This coordinate (τ,δ) is the same as in OCELOT

In A. Wolski's book, the sign of τ is inverted

Related to the Mad-x coordinates (T,PT) as (τ,δ)=(−T,PT), (according to this paper also in TEAPOT, PyORBIT, )

Related to the Bmad coordinates (z,pz) (Bmad manual 15.28, 15.32) as zBmad=−βτ (not the reference velocity β0) and pz,Bmad=ΔEE0=β0δ

The longitudinal momentum coordinate in Bmad is $p_{z, \mathrm{Bmad}} = \frac{\Delta P}{P_0}$, where $P$ is the total momentum of the particle (Bmad manual Eq. 15.31). The equation you referenced is an approximation for ultra-relativistic particles. Other than that, it looks good to me.

In addition, we should also clearly distinguish the reference energy E0 and reference momentum p0 (p0c), which will be different for non-relativisitic particles. Right now the attribute is called Beam.energy and should return the energy. We could add another property Beam.p0c as convenient method

I think the distinction between $E_0$ and $p_0$ is clear. What is not clear in is that Beam.energy is $E_0$. It could be renamed to Beam.ref_energy or something similar.

[jp-ga]

As a reference, this is how I implemented the coordinate transform for bmadx: https://github.com/desy-ml/cheetah/blob/0d702e6d4e548bfc0c5173c4f6341e3e3f2d798a/cheetah/bmadx_utils.py#L4-L62