Address the dipole kick through KickAngle where the pass method uses it

[thellert]

Description

AT keeps the dipole kick of an element in the polynom and in KickAngle; the simulator's magnet accessors read and write the polynom only. As a result a strength set on a CorrectorPass element never reaches the beam, and a KickAngle carried by a multipole element is not read and is doubled by a write. Details, measurements and a script are in the issue.

Related Issue

• Fixes Dipole kick held in KickAngle is not seen by the magnet accessors #471

Features/issues described there are:

• bugfix: one small view class in pyaml/lattice/abstract_impl.py (_KickAngleCoefficients) presents the dipole strength of an element that carries a KickAngle as a single polynom coefficient. The scalar and array accessors use it wherever they looked up the polynom, so their arithmetic is unchanged. This keeps the fix in one place instead of branching in each accessor.

Changes to existing functionality

• CorrectorPass elements: the strength is written to and read from KickAngle (PolynomB[0] * L = -KickAngle[0], PolynomA[0] * L = KickAngle[1]), because that pass method ignores the polynoms. A polynom the element carries is kept in step, so the existing accessor tests hold unchanged.
• at.Corrector elements defined without PolynomA/B now work; building the accessor raised AttributeError.
• Multipole elements that carry a KickAngle (ThinMPolePass, StrMPole*, BndMPole*, ExactMultipole*): the strength reads polynom + KickAngle; a write stores the value in the polynom and resets that plane's KickAngle, so it is not applied twice. This changes an attribute of the user's lattice on write — the alternative is to keep KickAngle and store the difference in the polynom; say which you prefer.
• Elements without a KickAngle, or whose pass method ignores it (QuadLinearPass, DriftPass), are untouched.

Testing

The following tests (compatible with pytest) were added to tests/lattice/test_magnet_accessors.py; each compares the closed orbit of a small ring against a KickAngle reference:

• test_corrector_pass_strength_moves_the_orbit — thin and thick CorrectorPass, both planes
• test_corrector_pass_without_polynoms_is_supported
• test_corrector_pass_reads_the_kick_of_the_lattice
• test_corrector_pass_combined_function_strengths_move_the_orbit — strength and hardware arrays
• test_split_corrector_pass_shares_the_kick_by_length
• test_multipole_corrector_agrees_with_corrector_pass
• test_multipole_kick_angle_is_part_of_the_strength — thin multipole, multipole, dipole
• test_kick_angle_ignored_by_the_pass_method_is_not_read

The orbit tests fail on main and pass here.

Verify that your checklist complies with the project

• New and existing unit tests pass locally — 467 passed, 6 skipped, 1 failed: tests/tuning_tools/test_tune_hardware.py::test_tune (4.1e-8 against a 1e-8 tolerance), which fails with the same value on unmodified main on my machine (macOS, Python 3.12, AT 0.8.0)
• Tests were added to prove that all features/changes are effective
• The code is commented where appropriate
• Any existing features are not broken (unless there is an explicit change to an existing functionality)

[gubaidulinvadim]

@thellert Thanks for the contribution. Normally, we've discussed limiting pyAML elements to PolynomA/PolynomB, no kick angle, as the maintaining lab of AT is not using KickAngles much. But I think now there's enough demand to also have KickAngle in pyAML. So, this is a good addition.

[gubaidulinvadim]

I think here you need to test also if it works with a combined function magnet, having a sextupole with dipolar correctors as KickAngles. I think @gupichon did something similar a while ago, but maybe it was never merged.

[JeanLucPons]

Thank for the contribution.
Yes theoretically, we should use H or VCorrector.angle.set() which do the angle kick.
The KickAncgle of AT is a bit wrong.
As it is done in the PR I'm affraid that if you use angle.set() it will be worse.
So either we support the CorrectorPass as done is this PR and we remove angle or we forget KickAngle.