Add a "turn" input to atpass

[lfarv]

Until now, the default passmethod for cavities is CavityPass. #372 (pending) will change it for RFCavityPass.
Unlike CavityPass, RFCavityPass can handle multi-turn tracking with a RF frequency different from nominal. For this, it has to compute the total path length since the beginning of tracking ("turn 0"). This is done by internally maintaining a "turn counter". This has a drawback: since the turn counter is set to zero on each call to atpass, splitting a long tracking is wrong. A statement like:

lattice_pass(ring, particle, nturns=100)

is correct, but the sequence:

for turn in range(100):
    lattice_pass(ring, particle, nturns=1)

is wrong because the turn counter is reset to zero, thus re-synchronising the particle with the RF on each turn. The same applies to the Matlab equivalent ringpass. In such a case, we are back to the behaviour of CavityPass!

This PR adds a new keyword turn to lattice_pass, allowing to handle the "turn counter" externally, so that the sequence:

for turn in range(100):
    lattice_pass(ring, particle, nturns=1, turn=turn)

is now correct.

[swhite2401]

Indeed this is necessary!

[swhite2401]

I have a question: what happens if we input the wrong counter, i.e. if turn is non zero but inconsistent with ct drift?

[swhite2401]

Wouldn't it be more convenient to have an input argument keep_counter that would just increment instead of resetting to zero at each atpass call?

[lfarv]

The way the absolute path length is computed is:

dct (lengthening with respect to the reference) + turn * circumference (absolute path length of the reference).

The location of the cavity along the circumference does not matter when β=1: the time reference for a cavity at any location is the passage of the reference particle.

So if you enter a wrong turn number,

• on the nominal frequency, the circumference is a multiple of the RF wave length (by definition), so turn does not matter. That's why CavityPass works,
• if not on the nominal frequency, then you get garbage ! The starting point does not matter, 0 just means that you start in phase with the RF. The critical point is that it increases by 1 on each turn.

Looking at the examples given for DA computation or Hassinski, a turn argument is the easiest to use. In different cases, keep_counter could be convenient… So we can provide both ! (in 3 weeks…)

[lfarv]

Added a keep_counter keyword (python) and a KeepCounter flag (Matlab).
This is an alternative to the turn keyword to ensure the continuity of the turn number for splitted tracking.

So now one can choose between:

for turn in range(100):
    lattice_pass(ring, particle, nturns=1, turn=turn)

and:

lattice_pass(ring, particle, nturns=1)
for turn in range(1,100):
    lattice_pass(ring, particle, nturns=1, keep_counter=True)

[lfarv]

Any more comment ?

[swhite2401]

Any more comment ?

All good for me