at.matching.matching

Classes for matching variables and constraints

Functions

match(ring, variables, constraints[, ...])

Perform matching of constraints by varying variables

Classes

Constraints(*args, **kwargs)	Container for generic constraints:
ElementConstraints(ring, *args, **kwargs)	Base class for position-related constraints: handle the refpoints of each target
ElementVariable(refpts, attname[, index, ...])	An ElementVariable is:
EnvelopeConstraints(ring)	Container for envelope constraints:
LinoptConstraints(ring, **kwargs)	Container for linear optics constraints:
OrbitConstraints(ring, *args, **kwargs)	Container for orbit constraints: The closed orbit can be handled with :py:class`LinoptConstraints`, but for problems which do not involve parameters other than orbit, like steering or orbit bumps, OrbitConstraints is much faster.
Variable(setfun, getfun[, name, bounds, ...])	A Variable is a scalar value acting on a lattice through the user-defined functions setfun and getfun

class Constraints(*args, **kwargs)

Bases: object

Container for generic constraints:

• a constraint is defined by a user-defined evaluation function,

• constraints are added to the container with the add() method.

Parameters:

*args – Positional arguments sent to the evaluation functions of all the embedded constraints

Keyword Arguments:

**kwargs – Keyword arguments sent to the evaluation functions of all the embedded constraints

Examples

Define an evaluation function for the ring circumference:

>>> def circ_fun(ring):
...     return ring.get_s_pos(len(ring) + 1)

Define an evaluation function for the momentum compaction factor:

>>> def mcf_fun(ring):
...     return ring.get_mcf()

Construct the container:

>>> cnstrs = Constraints()

Add the two constraints:

>>> cnstrs.add(circ_fun, 850.0)
>>> cnstrs.add(mcf_fun, 1.0e-4, weight=0.1)

add(fun, target, name=None, weight=1.0, bounds=(0.0, 0.0))

Add a target to the Constraints container

Parameters:

• fun (Callable) –

  Evaluation function. Called as:

  value = fun(ring, *args, **kwargs)

  value is the constrained parameter value,

  value may be a scalar or an array.

  The positional and keyword parameters come from the Constraints initialisation

• target – Desired value.

• name (str | None) – Name of the constraint. If None, a name is generated from the name of the evaluation function

• weight – Weight factor: the residual is (value-target)/weight

• bounds – Lower and upper bounds. The parameter is constrained in the interval [target-low_bound target+up_bound]

The “target”, “weight” and “bounds” input must be broadcastable to the shape of “value”.

evaluate(ring)

Return a flattened array of weighted residuals

static header()

Header for the display of constraint values and residuals

status(ring, initial=None)

Return a string giving the actual state of constraints

values(ring)

Return the list of actual parameter values

class ElementConstraints(ring, *args, **kwargs)

Bases: Constraints

Base class for position-related constraints: handle the refpoints of each target

add(fun, target, refpts=None, **kwargs)

Add a target to the ElementConstraints container

Parameters:

• fun (Callable) –

  Evaluation function. Called as:

  value = fun(ring, *args, **kwargs)

  value is the constrained parameter value

  value may be a scalar or an array.

  the positional and keyword parameters come from the ElementConstraints initialisation

• target – Desired value.

• refpts (Type[Element] | Element | Callable[[Element], bool] | str | None | int | Sequence[int] | bool | Sequence[bool] | RefptsCode) – Location of the constraint

Keyword Arguments:

• name – Name of the constraint. If None, a name is generated from the name of the evaluation function

• weight – Weight factor: the residual is (value-target)/weight

• bounds – Lower and upper bounds. The parameter is constrained in the interval [target-low_bound target+up_bound]

The “target”, “weight” and “bounds” input must be broadcastable to the shape of “value”.

compute(ring, *args, **kwargs)

Dummy computation. Compute must return: - an iterator over local data for each target - a tuple of global data

values(ring)

Return the list of actual parameter values

class ElementVariable(refpts, attname, index=None, name='', bounds=(-inf, inf))

Bases: Variable

An ElementVariable is:

• a scalar attribute or

• an element of an array attribute

of one or several Element (s) of a lattice.

Parameters:

• refpts (Refpts) – Location of variable Element (s)

• attname (str) – Attribute name

• index (Optional[int]) – Index in the attribute array. Use None for scalar attributes

• name (str) – Name of the Variable; Default: ''

• bounds (tuple[float, float]) – Lower and upper bounds of the variable value

class EnvelopeConstraints(ring)

Bases: ElementConstraints

Container for envelope constraints:

• a constraint can be set on any result of ohmi_envelope(),

• constraints are added to the container with the add() method.

ohmi_envelope() is called once before the evaluation of all constraints.

Parameters:

ring (Lattice) – Lattice description

add(param, target, refpts=None, index=None, name=None, **kwargs)

Add a target to the EnvelopeConstraints container

Parameters:

• param –

  2 possibilities:

  • parameter name: see ohmi_envelope() for the name of available parameters. In addition to local parameters, 'tunes', 'damping_rates', 'mode_matrices' and 'mode_emittance' are allowed.

  • user-supplied parameter evaluation function:

    value = param(emit_data, beam_data)

    emit_data contains the emittance data at all the specified refpoints value is the constrained parameter value (scalar or array).

• target – desired value.

• refpts (Type[Element] | Element | Callable[[Element], bool] | str | None | int | Sequence[int] | bool | Sequence[bool] | RefptsCode) – location of the constraint. Several locations may be given to apply the same constraint at several points.

• index (int | slice | None) – index in the parameter array. If None, the full array is used.

• name (str | None) – name of the constraint. If None, name is generated from param and index.

Keyword Arguments:

• weight – Weight factor: the residual is (value-target)/weight

• bounds – lower and upper bounds. The parameter is constrained in the interval [target-low_bound target+up_bound]

The target, weight and bounds values must be broadcastable to the shape of value.

compute(ring, *args, **kwargs)

Optics computation before evaluation of all constraints

class LinoptConstraints(ring, **kwargs)

Bases: ElementConstraints

Container for linear optics constraints:

• a constraint can be set on any result of at.get_optics

• constraints are added to the container with the LinoptConstraints.add method.

get_optics() is called once before the evaluation of all constraints

Parameters:

ring (Lattice) – Lattice description

Keyword Arguments:

• dp (float) – Momentum deviation.

• dct (float) – Path lengthening. If specified, dp is ignored and the off-momentum is deduced from the path lengthening.

• orbit (Optional[Orbit]) – Avoids looking for the closed orbit if is already known ((6,) array)

• twiss_in – Initial twiss parameters for transfer line optics. See linopt6()

• method (Callable) –

  Method used for the analysis of the transfer matrix. Can be linopt2, linopt4, linopt6

  • linopt2: No longitudinal motion,

    no H/V coupling,

  • linopt4: No longitudinal motion, Sagan/Rubin 4D-analysis of coupled motion,

  • linopt6 (default): With or without longitudinal motion, normal mode analysis

Example

>>> cnstrs = LinoptConstraints(ring, dp=0.01, coupled=False)

Add a beta x (beta[0]) constraint at location ref_inj:

>>> cnstrs.add('beta', 18.0, refpts=ref_inj,
               name='beta_x_inj', index=0)

Add an horizontal tune (tunes[0]) constraint:

>>> cnstrs.add('tunes', 0.44, index=0, weight=0.01)

Add a chromaticity constraint (both planes):

>>> cnstrs.add('chroms', [0.0 0.0])

Define a constraint of phase advances between 2 points:

>>> def mu_diff(lindata, tune, chrom):
...     delta_mu = (lindata[1].mu - lindata[0].mu)/(2*np.pi)
...     return delta_mu % 1.0

Add a H phase advance constraint, giving the desired locations:

>>> cnstrs.add(mu_diff, 0.5, refpts=[sf0 sf1], index=0)

add(param, target, refpts=None, index=None, name=None, **kwargs)

Add a target to the LinoptConstraints container

Parameters:

• param –

  2 possibilities:

  • parameter name: see linopt6() for the name of available parameters. In addition to local optical parameters, 'tunes' and 'chroms' are allowed.

  • user-supplied parameter evaluation function:

    value = param(lindata, tune, chrom)

    lindata contains the optics parameters at all the specified refpoints value is the constrained parameter value (scalar or array).

• target – desired value.

• refpts (Type[Element] | Element | Callable[[Element], bool] | str | None | int | Sequence[int] | bool | Sequence[bool] | RefptsCode) – location of the constraint. Several locations may be given to apply the same constraint at several points.

• index (int | slice | None) – index in the parameter array. If None, the full array is used.

• name (str | None) – name of the constraint. If None, name is generated from param and index.

Keyword Arguments:

• weight – Weight factor: the residual is (value-target)/weight

• bounds – lower and upper bounds. The parameter is constrained in the interval [target-low_bound target+up_bound]

• UseInteger – Match integer part of mu, much slower as the optics calculation is done for all refpts

The target, weight and bounds values must be broadcastable to the shape of value.

compute(ring, *args, **kwargs)

Optics computation before evaluation of all constraints

class OrbitConstraints(ring, *args, **kwargs)

Bases: ElementConstraints

Container for orbit constraints: The closed orbit can be handled with :py:class`LinoptConstraints`, but for problems which do not involve parameters other than orbit, like steering or orbit bumps, OrbitConstraints is much faster.

find_orbit() is called once before the evaluation of all constraints

Parameters:

ring (Lattice) – Lattice description

Keyword Arguments:

• dp (float) – Momentum deviation.

• dct (float) – Path lengthening. If specified, dp is ignored and the off-momentum is deduced from the path lengthening.

• orbit (Optional[Orbit]) – Avoids looking for the closed orbit if is already known ((6,) array)

Example

>>> cnstrs = OrbitConstraints(ring, dp=0.01)

Add a bump (x=-0.004, x’=0) constraint at location ref_inj

>>> cnstrs.add([-0.004, 0.0], refpts=ref_inj, index=slice(2))

add(target, refpts=None, index=None, name=None, **kwargs)

Add a target to the OrbitConstraints container

Parameters:

• target – desired value.

• refpts (Type[Element] | Element | Callable[[Element], bool] | str | None | int | Sequence[int] | bool | Sequence[bool] | RefptsCode) – location of the constraint. Several locations may be given to apply the same constraint at several points.

• index (int | slice | None) – index in the orbit vector. If None, the full orbit is used.

• name (str | None) – name of the constraint. Default: 'orbit'

Keyword Arguments:

• weight – Weight factor: the residual is (value-target)/weight

• bounds – lower and upper bounds. The parameter is constrained in the interval [target-low_bound target+up_bound]

The target, weight and bounds values must be broadcastable to the shape of value.

compute(ring, *args, **kwargs)

Orbit computation before evaluation of all constraints

class Variable(setfun, getfun, name='', bounds=(-inf, inf), fun_args=(), **fun_kwargs)

Bases: object

A Variable is a scalar value acting on a lattice through the user-defined functions setfun and getfun

Parameters:

• setfun (Callable) –

  User-defined function for setting the Variable. Called as:

  setfun(ring, value, *args, **kwargs)

  where value is the scalar value to apply

  The positional and keyword parameters come from the Variable initialisation

• getfun (Callable) –

  User-defined function for retrieving the actual value of the variable: Called as:

  value = getfun(ring, *args, **kwargs)

  The positional and keyword parameters come from the Variable initialisation

• name (str) – Name of the Variable; Default: ''

• bounds (tuple[float, float]) – Lower and upper bounds of the variable value

• fun_args (tuple) – Positional arguments transmitted to setfun and getfun functions

Keyword Arguments:

**fun_kwargs – Keyword arguments transmitted to setfun``and ``getfun functions

get(ring)

Get the actual variable value

static header()

set(ring, value)

Set the variable value

status(ring, vini=nan)

match(ring, variables, constraints, verbose=2, max_nfev=1000, diff_step=1e-10, method=None, copy=True)

Perform matching of constraints by varying variables

Parameters:

• ring (Lattice) – Lattice description

• variables (Sequence[Variable]) – sequence of Variable objects

• constraints (Sequence[Constraints]) – sequence of Constraints objects

• verbose (int) – Print additional information

• max_nfev (int) – Maximum number of evaluations

• diff_step (float) – Convergence threshold

• method

• copy (bool)