Proposal for Combined Function Magnet

[JeanLucPons]

I would like to propose this implementation for combined function magnets.
It is not yet complete and hardware links have still to be handled.
Any comments, tips are welcome.

Config file:

type: pyaml.magnet.cfm_magnet
name: SH1-C01A         #Name of the element in the lattice model
mapping:
  # Multipole mapping for usage in families, in this example SH1-C01A-H is not 
  # a lattice element present in the model, it is just a name to use in 
  # PyAML families. When this 'virutal' element is set, it then applies
  # the corresponding multipole on the parent element.
  - [B0, SH1-C01A-H]
  - [A0, SH1-C01A-V]
  - [A1, SH1-C01A-SQ]
unitconv:
  # pyaml.magnet.linear_cfm_unitconv is a default implementation available in pyaml, see below
  type: pyaml.magnet.linear_cfm_unitconv
  multipoles: [B0,A0,A1]
  units: [rad,rad,m-1]
  pseudo_factors: [1.0,-1.0,-1.0]
  curves:
    - type: pyaml.configuration.csvcurve
      file: tests/config/sr/unitconv/SH_h_strength.csv
    - type: pyaml.configuration.csvcurve
      file: tests/config/sr/unitconv/SH_v_strength.csv
    - type: pyaml.configuration.csvcurve
      file: tests/config/sr/unitconv/SH_sq_strength.csv
  matrix:
    type: pyaml.configuration.csvmatrix
    file: tests/config/sr/unitconv/SH_matrix.csv
  powerconverters:
    - type: pyaml.control.device
      setpoint:  sr/ps-sh3/c01-e-1/current
      readback:  sr/ps-sh3/c01-e-1/current
      unit: A
    - type: pyaml.control.device
      setpoint:  sr/ps-sh3/c01-e-2/current
      readback:  sr/ps-sh3/c01-e-2/current
      unit: A
    - type: pyaml.control.device
      setpoint:  sr/ps-sh3/c01-e-3/current
      readback:  sr/ps-sh3/c01-e-3/current
      unit: A

pydantic model of the LinearCFMagnetUnitConv (a basic model which will be provided in pyaml):

# Define the main class name for this module
PYAMLCLASS = "LinearCFMagnetUnitConv"

class ConfigModel(BaseModel):

    multipoles: list[str]
    """List of supported functions: A0,B0,A1,B1,etc (i.e. [B0,A1,B2])"""
    curves: list[Curve]
    """Exitacion curves, 1 curve per function"""
    calibration_factors: list[float] = None
    """Correction factor applied to curves, 1 factor per function
       Delfault: ones"""
    calibration_offsets: list[float] = None
    """Correction offset applied to curves, 1 offset per function
       Delfault: zeros"""
    pseudo_factors: list[float] = None
    """Factors applied to 'pseudo currents', 1 factor per function.
       Delfault: ones"""
    pseudo_offsets: list[float] = None
    """Offsets applied to 'pseudo currents', 1 factor per function.
       Delfault: zeros"""
    powerconverters: list[DeviceAccess]
    """List of power converter devices to apply currrents (can be different
       from number of function)"""
    matrix: Matrix = None
    """n x m matrix (n rows for n function , m columns for m currents) 
       to handle multipoles separation. Default: Identity"""
    units: list[str]
    """List of strength unit (i.e. ['rad','m-1','m-2'])"""

class LinearCFMagnetUnitConv(UnitConv):
    """
    Class providing a simple linear model for combined function magnets. A matrix
    can handle separation of multipoles. A pseudo current is a linear combination
    of power supply currents associated to a single function.
    """

[JeanLucPons]

Using the above model, we can handle all EBS combined function magnets.
Our sextupole model is much more complex, the matrix is replaced by a tensor which handle multipole separation according to the main current as our sextupoles works in a zone close to saturation.
However, after private discussion with G.Le Bec, a linear approximation of this complex model could give good results as well.

[JeanLucPons]

In general case,a combined function magnet is a magnet where currents cannot be changed separately.
If in your control system you have simulated magnet that directly maps to AT polynoms, CombinedFunctionMagnet is useless.

Anyway, in the example i gave, you need a name for your horizontal corrector which is not in AT unless you patch your lattice with non standard attributes. The only keyword I can consider is FamName and this will force to implement models in that way. We can define some extended attributes as well but this was not specified.

[TeresiaOlsson]

In my control system I have one power supply for the sextupole component and one power supply for the corrector component. I then in MML define them as separate elements which map to the same element in the lattice file. MML then does the mapping to the correct component of the polynoms. So then if I understand correctly, those type of magnets should in pyAML still be configured as separate devices.

But then isn't it just the unit conversion part that makes the CombinedFunctionMagnet a combined function magnet? This is where I get confused because I could choose a different unit conversion and together with the mapping part get a magnet which is a sextupole + corrector with individually controlled power supplies. Or not?

[JeanLucPons]

In fact you cannot choose a wrong unitconv, it will fail. CombinedFunctionMagnet check that multipoles are coherent.
https://github.com/python-accelerator-middle-layer/pyaml/blob/970c49ab7ad890b61431426ebfdac92a28ffca8b/pyaml/magnet/cfm_magnet.py#L63

[TeresiaOlsson]

For the mapping to the lattice model, in MML it is solved by not just mapping to the FamName but also the index within that family if there is more than one element with that name. There can also be cases where you have several cavities with different FamName that all needs to map to the master clock in the pyAML. So I think we need some more flexible way to map to the lattice model. I think it would also be good to separate the pyAML element name from the lattice model names because they don't necessarily need to be the same.

[JeanLucPons]

In fact, this will work with PyAML. In your case (I guess) you won't use CombinedFunctionMagnet and you will be able to define some array with same name for HCorrector and SkewQuad and different curves using either SplineUnitConv or LinearUnitconv. It will bind to the correct polynomial as in MML and will compute good currents (if i guess well: your multipoles are well separated at the hardware level). It is foreseen that FamName is not unique as well.
Today, the register_element() and arrays are basics but implementation is progressing.

[GamelinAl]

For me it seems fine at the first look. With a structure like this you should be able to generate "virtual single function magnets" which call this combined function magnet under the hood.

@JeanLucPons It's more complex, but probably it's straightforward to generalize to a tensor, no?

Maybe another thing that may be needed to deal with is the forbidden combinations. For example, there are cases where if the sextupole strength is maximal, the available corrector strength is limited, and vice versa. Would your proposal be able to deal with this?

[JeanLucPons]

This is this the main idea of the Gael's model. It drives correctors according to the main currents.
For limitation, we have just a flag like below:
In case of saturation of correctors, we get some alarms.
To my knowledge, we never had to block a function.
We use the freeze only for our DQ (we perform DQ steering only 2 or 3 times per year using more eigen vectors).

[JeanLucPons]

The freeze is also foreseen in the specification documents and should be implemented.

[JeanLucPons]

Generalization to a tensor field in not so straightforward.
I would like to have just this simple model in pyaml core which can handle already lots of cases.
For the EBS sextupole model, it will be in an external module and will likely use C++ binding (it is time consuming).
I recall that pyaml have to deal with lots of abstraction (magnet, control system, archiving, curve and matrix format,...) and that the development of external module is a key point.
If someone has time, he is welcome to write a UnitConv. There is a naive example on how to write it one there and it follows exactly the same rules as internal modules.

[JeanLucPons]

After the discussion during the meeting, it is now a bit clearest for me.
@ersf, to handle this we have the setpoint check. The idea is to check that all power supplies are able to perform the required strength otherwise you get an error.
This is a different approach and no extra model for dynamic range is needed, but it requires the [min,max] of all underlying power supplies.

[kparasch]

Should we have B0 correspond to a dipole field or should B1 be a dipole field? In my experience, all magnet measurements I have seen take B1 to be a dipole field and I think it would be nice to stay consistent with them.

[TeresiaOlsson]

Hmm... Always complicated that. Maybe instead of B0 and B1 we should just call it "dipole". Perhaps also "dipole_normal" and "dipole_skew" instead of B and A? It feels like self explanatory keywords might be useful?

[JeanLucPons]

I use the AT notation, starting at 0.

_fmap:dict = {
    "B0":HCorrector,
    "A0":VCorrector,
    "B1":Quadrupole,
    "A1":SkewQuad,
    "B2":Sextupole,
    "A2":SkewSext,
    "B3":Octupole,
    "A3":SkewOctu,
    "B4":Decapole,
    "A4":SkewDeca
}