at.latticetools.matching#

Matching of lattice parameters.

The matching acts on a VariableList to statisfy the constraints expressed in an ObservableList.

Examples of use of such classes are available in:

Examples of matching are given in Matching.

Functions

`match`(variables, constraints, *[, method, ...])	Observable matching.
`ring_match`(ring, variables, constraints, *)	Match constraints by varying variables.

Classes

MatchingMethod(*values)

Methods for the matching algorithm.

class MatchingMethod(*values)[source]#

Bases: Enum

Methods for the matching algorithm.

LEASTSQUARES: least_squares_match(), based on least_squares(),
JACOBIAN: jacobian_match().

JACOBIAN = 1#

LEASTSQUARES = 0#

match(variables, constraints, *, method=MatchingMethod.LEASTSQUARES, verbose=2, max_nfev=1000, lstsq_method=None, optim_kw=None, **eval_kw)[source]#

Observable matching.

Minimisation is performed by least_squares_match() or jacobian_match(), depending on method.

Parameters:

variables (VariableList) – Variable parameters
constraints (ObservableList) – Constraints to fulfill
method (MatchingMethod) – Matching algorithm: MatchingMethod.LEASTSQUARES for least_squares_match() or MatchingMethod.JACOBIAN for jacobian_match(),
verbose (int) – Level of verbosity,
max_nfev (int) – Maximum number of function evaluation,
lstsq_method (str | None) – least_squares() algorithm, ‘trf’, ‘dogbox’ or ‘lm’. If None, use ‘lm’ for unbounded problems with at least as many constraints as variables, ‘trf’ otherwise. ‘lm’ supports neither bounds nor fewer constraints than variables.
optim_kw (dict | None) – Dictionary of optimiser keyword arguments sent to least_squares_match() or jacobian_match(). The tolerances ftol, xtol and gtol have the same meaning for both methods,

Keyword Arguments:

**eval_kw – Evaluation keywords provided to the ObservableList.evaluate() method. For instance “ring” (for lattice-dependent observables), “dp”, “dct”, “orbit”, “twiss_in”, “r_in”… Default values are taken from the ObservableList.

Returns:

Matching result – solution for the variable values.

Raises:

RuntimeError – If optimisation fails

ring_match(ring, variables, constraints, *, copy=False, method=MatchingMethod.LEASTSQUARES, verbose=2, max_nfev=1000, lstsq_method=None, **kwargs)[source]#

Match constraints by varying variables.

Minimisation is performed by least_squares_match() or jacobian_match(), depending on method.

Parameters:

ring (Lattice) – Lattice description
variables (VariableList) – Variable parameters
constraints (ObservableList) – Constraints to fulfill
copy (bool) – If True, return a modified copy of ring, otherwise perform the match in-line
method (MatchingMethod) – Matching algorithm: MatchingMethod.LEASTSQUARES or MatchingMethod.JACOBIAN, see match(),
verbose (int) – Level of verbosity,
max_nfev (int) – Maximum number of function evaluation,

Keyword Arguments:

dp (float | None) – Momentum deviation. Default taken from the ObservableList,
dct (float | None) – Path lengthening. Default taken from the ObservableList,
df (float | None) – Deviation from the nominal RF frequency. Default taken from the ObservableList,
orbit (Orbit | None) – Initial orbit. Avoids looking for the closed orbit if it is already known. Used for MatrixObservable and LocalOpticsObservable. Default taken from the ObservableList,
twiss_in – Initial conditions for transfer line optics See get_optics(). Used for LocalOpticsObservable. Default taken from the ObservableList,
r_in (Orbit | None) – Initial trajectory, used for TrajectoryObservable. Default taken from the ObservableList,
lstsq_method – least_squares() algorithm, ‘trf’, ‘dogbox’ or ‘lm’. If None, use ‘lm’ for unbounded problems with at least as many constraints as variables, ‘trf’ otherwise. ‘lm’ supports neither bounds nor fewer constraints than variables.
**kwargs – The other keyword arguments are sent to the matching algorithm, see optim_kw in match().

Returns:

Modified Lattice if copy=True, None otherwise

Raises:

TypeError – If copy=True and ElementVariable is present
RuntimeError – If optimisation fails

Examples

See Matching