Access to the lattice energy in integrators

[lfarv]

As discussed here, the origin of the energy parameters in the integrators is ambiguous. To make that simpler and clearer, the strategy in this PR is the following:

1. For the entry point common to Matlab and python (trackFunction): this is the only entry point in python, and the one used for lattice tracking in Matlab.

   • python: the energy comes from the parameters structure and the element's energy attribute is always ignored,
   • Matlab: the energy comes from the parameters structure if available, and otherwise from the element's energy attribute.

   This is implemented by a new atEnergy macro and is generalized in all the integrators requiring energy. The previous behavior was giving priority to the element's attribute.
   The energy is taken from the parameters on each call, rather than being stored on the elements parameters, which make it suitable for ramping (Energy ramp #810).

2. For the Matlab-specific entry point (MexFunction): it is used in Matlab for tracking in a single element (findelemm66, findelemm44). It is now necessary to provide the energy to the function. So a 3rd optional argument is introduced, as a structure containing Energy, Particle, and possibly others in the future. Unfortunately, allowing this 3rd argument implied the modification of all integrators (nrhs >= 2 instead of nrhs == 2), though only some of them use this 3rd argument. On top of that, a new Matlab function is created: rout=elempass(elem,rin), with optional keyword arguments Energy and Particle. It is similar to the python element_track function.

Consequences:

• the behavior is unchanged in python: the energy was already always provided by the Lattice energy. But the change in priority can affect cases where there was a conflict between element and lattice energies. These are considered as erroneous cases, and the new new behavior of completely ignoring the element's energy is safer.
• in Matlab, the behavior is similar to python if there is a RIngParam element. If not, the energy is taken from elements, as before.

Removing the Energy attribute of all elements was tested in both Matlab and python. Such a new lattice is added in the automatic test sequence.

Though the modifications are moderate, any intervention on integrators is critical and requires a lot of testing. Please help!

[lfarv]

Added 2 new test lattices identical to hmba:

• noenergy.mat has no energy field anywhere (except in RF cavities: see below)
• noringparam.mat has no RingParam element
  This is to ensure that the element's Energy attribute is no more necessary, but is still scanned when reading the file to guess the lattice energy if there is no RingParam

Note: the Energy field is still required to construct a RFCavity element. It will be set as optional in another PR.

[lfarv]

I'll be away for 2 weeks. There is still a Matlab function quantumDiff.m which needs te Energy element attribute. I'll upgrade it later. In the mean time, this branch should be fully operational. To summarise:

• Everything should work as before,
• In addition, the Energy element attribute can be removed in python, and in Matlab if there is a RingParam attribute

Please test…

[carmignani]

Hello Laurent,
I'm testing your modifications on Matlab and I have a few comments.
From the pull request #623, the energy in the elements with rad pass methods became not mandatory. In the track function, this line
Energy=atGetDouble(ElemData,"Energy"); check_error();
has been replaced with this
Energy=atGetOptionalDouble(ElemData,"Energy",Param->energy); check_error();
It is not clear to me what should happen in case there is no "Energy" field and there is no RingParam element in the lattice. I think there should be an error in that case, but currently there is no error. Both Elem->Energy and Param->energy are 0 and I don't get any error message.
This behaviour would not be modified by your recent pull request, where you call the atEnergy function.
Let me know if I misunderstood something. I think in python there is not such problem, because the energy lattice parameter is mandatory.

[carmignani]

And my second comment is about the mexFunction. I think we could consider to get rid completely of the mexFunctions. The elempass Matlab function is a nice development, but it could probably be written using the standard atpass.c and so using the trackFunction instead of the mexfunction. We could insert a ringparam element in the Matlab function elempass, in front of the element we want to track through, so we would have the energy available.

[lfarv]

Hi Nicola. You are right, we miss a test on energy. This could be inserted in atEnergy (Matlab version): in the end, energy must not be zero. I can’t do anything for the moment but If you want, you can take the control of this PR and go on. You may also have a better idea !

[lfarv]

2nd comment : I fully agree. But atpass has a large overhead, useless in this case. Another simpler mex-function calling trackFunction would be better. But then, we would duplicate the loading of integrators… unless we put this in a common shared library used by both… I suggest to take note of that and solve this in another PR.

[carmignani]

I modified the atEnergy for Matlab, but I wrote it as a function, not within the #define. If energy is 0.0 we get an error.

[lfarv]

@carmignani : the 2 Matlab functions computing the diffusion matrix (ohmienvelope and quantumDiff) are now using the same code in atdiffmat.

I added automatic tests for emittances and damping rates. Everything looks correct for me.

[swhite2401]

@lfarv @carmignani this look OK for me, shall we merge this? I think it is a pre-requisit for #810 right?

[lfarv]

I rebased this branch on master, and backported a few evolutions from #742. Since the number of modified files is very large, here is a summary of the modifications:

• All *RadPass and *CavityPass methods are modified to handle the ring energy, always taken from the lattice in python, and preferably from the lattice in Matlab. Some other methods also using the energy are modified in the same way,
• All other passmethod are slightly modified in the Matlab-only part to allow additional input parameters in the MexFunction (necessary to provide the energy and particle to the MexFunction),
• In Matlab, 2 new functions are created: elempass to track through a single element (still uses the MexFunction entry point), and atdiffmat which factorises the computation of diffusion matrices. A number of functions findm44, ohmienvelope, atx,… are modified to provide an "energy" entry,
• in python, almost nothing changes since the strategy for providing the energy in unchanged.

For me, it's ready for merging.

[carmignani]

Hello, I had a look again to the modifications and all seem good to me.