Longitudinal Phase-Space Rework

[VitorSouzaLNLS]

Description

This PR introduces a rework for a consistent implementation of the path length coordinate ($z$, or dl in code) for longitudinal dynamics.

In the current Trackcpp, the path length is implemented as the deviation of a particle’s traveled path relative to the design orbit length. This leads to physically inconsistent results when simulating accelerators with RF cavities running at non-nominal RF frequencies, since the synchronous particle is no longer preserved as the fixed point of the longitudinal motion.

* In-deep explanations can be found at [1] ~ chapter 4, Path Length.

What has changed

This PR implements a global adjustment of the path length, to keep the arrival-time of particles in sync with wall-clock, maintaining the synchronous particle as the fixed point of the longitudinal dynamics even under non-nominal RF conditions. The adjustment is applied incrementally along the accelerator before time-aware elements such as RF cavities.

* Also at [1] ~ chapter 4, Path Length.

Key points:

• The synchronous particle is now correctly preserved for any RF frequency.

• An old local and artificial correction term θ used only in the "find orbit" algorithm is no longer needed.

• Path length is now globally consistent across all tracking routines.

Validation and Comparison

The following plots show tracking results comparing Trackcpp in its current version and the proposed version on this PR.

line_pass

Note: using the find_orbit6 the fixed point was obtained and then propagated with the line_pass routine.

$\longrightarrow$ Radiation OFF, Cavity ON

As we tracked the fixed point through the ring once, the expectation was for final values of $\delta$ and $z$ to be back equal their initial values. Running under the nominal RF frequency, this condition is satisfied. However, under non-nominal RF frequency, the path length is varied on the old version of Trackcpp, which is adjusted with the new proposed version.

$\longrightarrow$ Radiation ON, Cavity ON

Here, the path length once again is varied under non-nominal RF frequency with the old version of Trackcpp, while in the new version both $\delta$ and $z$ change along the ring but are restored to their initial values, as a fixed point should be.

Now, we simulated the same ring in the same conditions with 5 more cavities inserted (6 total).

$\longrightarrow$ Radiation OFF, Cavity ON

When we propagate the fixed point without radiation the energy should not change along the ring, which is seen under nominal RF operating frequency. However, with non-nominal RF frequency, both the energy and the path length vary within the turn on the old Trackcpp's version. On the other hand, with the new version, the energy stays constant the whole time.

$\longrightarrow$ Radiation ON, Cavity ON

ring_pass

• Note: as did before, we got the fixed point with the find_orbit6 routine and, now, propagated it with the ring_pass for 10k turns.

$\longrightarrow$ Radiation ON. Cavity ON. The particle was released from the calculated closed orbit (Fixed Point)

Operating with the nominal RF frequency we see that the calculated fixed point and the phase-space are the same on both versions. Its important to note the vertical and horizontal scales on the plots are on the order of $10^{-15}$ ~ $10^{-16}$, i.e., the variations only represent a numerical precision noise on the tracking calculations, which means the tracked particle stayed still at the fixed point.

However, when under non-nominal RF frequency, only the new version of Trackcpp preserved the particle's phase-space trajectory at the fixed point, while with the old version the particle is performing synchrotron oscillations, which is physically inconsistent with the synchronous particle definition, that does not perform these oscillations.

$\longrightarrow$ Radiation ON. Cavity ON. The particle was released from the calculated closed orbit plus an energy shift of $0.5\times 10^{-5}$.

Now, releasing a particle deviated from the synchronous particle we expected to see the synchrotron oscillations around the fixed point. This behavior is correctly observed under the nominal RF frequency, where the particle's trajectory makes spirals aimed to the fixed point with the both old and new Trackcpp's versions.

Under non-nominal RF frequency we again observe an inconsistent result given by the old Trackcpp version: although synchrotron oscillations are present, the spirals are not centered on the fixed point. With the new version this inconsistency is fixed, and the phase-space trajectory is correctly centered around the fixed point.

Impact

The modification alters the phase-space definition used in fundamental tracking simulations, and the new implementation is physically correct for both nominal and non-nominal RF frequencies.

Bibliography

[1] SOUZA, Vitor Davi de. Improvement on particle tracking tool for accelerator simulations at LNLS. 2024. Trabalho de Conclusão de Curso (Graduação) – Instituto de Física de São Carlos, Universidade de São Paulo, São Carlos, 2024. Disponível em: https://bdta.abcd.usp.br/directbitstream/2eff6ac1-e821-4b0d-82d9-00f8ee7e78da/Vitor_Davi_de_Souza.pdf. Acesso em: 26 set. 2025.

[fernandohds564]

very nice, @VitorSouzaLNLS ! I left some suggestions in the code.

[fernandohds564]

very nice @VitorSouzaLNLS ! I think we could test it and maybe you could add some description to the PR with some code to run examples.

[xresende]

I consider this important PR a major modification of trackcpp. it changes the phase space we use to do our fundamental tracking simulations, underneath all our beam dynamics and lattice optics calculations. A clear description of the PR, with a physical discussion of the change, is in order. I recomend reusing the description text as comments in the code.

[xresende]

@VitorSouzaLNLS , I think these changes deserve a major update of the package version to 5.0.0

[fernandohds564]

@lnls-fac/lnls-fac, @lnls-fac/lnls-ids, please take a look at this PR. It is a nice new addition to our tracking code.

[fernandohds564]

@VitorSouzaLNLS , I think these changes deserve a major update of the package version to 5.0.0

@VitorSouzaLNLS, did you update the version?

[VitorSouzaLNLS]

@VitorSouzaLNLS , I think these changes deserve a major update of the package version to 5.0.0

@VitorSouzaLNLS, did you update the version?

Not yet, @fernandohds564 ... I thought it'd be better to leave the version update for the last commit, so I was waiting to see if any more changes would come up after the reviews.

[fernandohds564]

@lnls-fac/lnls-fac, @lnls-fac/lnls-ids, please take a look at this PR. It is a nice new addition to our tracking code.

@lnls-fac/lnls-fac could you take a look at this PR, please?