at.latticetools.observables#

Definition of Observable objects used in matching and response matrices

Observables are ways to monitor various lattice parameters and use them in matching and correction procedures.

Class hierarchy#

Observable(evalfun, name, target, weight, bounds, …)

RingObservable(fun, …)

GlobalOpticsObservable()(attrname, plane, name, …)

EmittanceObservable(attrname, plane, name, …)

ElementObservable(fun, …)

OrbitObservable(refpts, axis, name, …)

TrajectoryObservable(refpts, axis, name, …)

MatrixObservable(refpts, axis, name, …)

LocalOpticsObservable(refpts, attrname, axis, name, …)

LatticeObservable(refpts, attrname, index, name, …)

GeometryObservable(refpts, attrname, name, …)

Observables are usually not evaluated directly, but through a container which performs the required optics computation and feeds each Observable with its specific data. After evaluation, each Observable provides the following properties:

Functions

GlobalOpticsObservable(param[, plane, name, ...])

Observe a global optics parameter.

Classes

Observable(fun, *args[, name, target, ...])

Base class for Observables.

RingObservable(fun[, name])

Observe any user-defined property of a ring

EmittanceObservable(param[, plane, name])

Observe emittance-related parameters.

ElementObservable(fun, refpts[, name, ...])

Base class for Observables linked to a position in the lattice

OrbitObservable(refpts[, axis, name])

Observe the transfer matrix at selected locations.

GeometryObservable(refpts, param[, name])

Observe the geometrical parameters of the reference trajectory.

LocalOpticsObservable(refpts, param[, ...])

Observe a local optics parameter at selected locations.

LatticeObservable(refpts, attrname[, index, ...])

Observe an attribute of selected lattice elements.

MatrixObservable(refpts[, axis, name])

Observe the closed orbit at selected locations.

TrajectoryObservable(refpts[, axis, name])

Observe trajectory coordinates at selected locations

Need(value)

Defines the computation requirements for an Observable.
class ElementObservable(fun, refpts, name=None, summary=False, statfun=None, **kwargs)[source]#

Bases: Observable

Base class for Observables linked to a position in the lattice

Parameters:
Keyword Arguments:

  • target – Target value for a constraint. If None (default), the residual will always be zero.

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

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

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

class EmittanceObservable(param, plane=None, name=None, **kwargs)[source]#

Bases: Observable

Observe emittance-related parameters.

Process the output of envelope_parameters().

Parameters:

  • param (str) – Parameter name (see envelope_parameters()) or user-defined evaluation function

  • plane (AxisDef) – One out of {0, ‘x’, ‘h’, ‘H’} for horizontal plane, one out of {1, ‘y’, ‘v’, ‘V’} for vertival plane or one out of {2, ‘z’, ‘l’, ‘L’} for longitudinal plane

  • name (str) – Observable name. If None, an explicit name will be generated

Keyword Arguments:

  • statfun – Post-processing function called on the value of the observable. Example: statfun=numpy.mean

  • target – Target value for a constraint. If None (default), the residual will always be zero.

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

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

User-defined evaluation function

It is called as:

value = fun(paramdata)

paramdata if the RingParameters object returned by envelope_parameters().

value is the value of the Observable.

Example

>>> EmittanceObservable("emittances", plane="h")

Observe the horizontal emittance

class GeometryObservable(refpts, param, name=None, **kwargs)[source]#

Bases: ElementObservable

Observe the geometrical parameters of the reference trajectory.

Process the geomdata output of get_geometry().

Parameters:

  • refpts (Refpts) – Observation points. See “Selecting elements in a lattice”

  • param (str) – Geometry parameter name: one in {‘x’, ‘y’, ‘angle’}

  • name (str) – Observable name. If None, an explicit name will be generated

Keyword Arguments:

  • statfun – Post-processing function called on the value of the observable. Example: statfun=numpy.mean

  • target – Target value for a constraint. If None (default), the residual will always be zero.

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

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

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

Example

>>> obs = GeometryObservable(at.Monitor, param="x")

Observe x coordinate of monitors

class LatticeObservable(refpts, attrname, index=None, name=None, **kwargs)[source]#

Bases: ElementObservable

Observe an attribute of selected lattice elements.

Parameters:

  • refpts (Refpts) – Elements to be observed See “Selecting elements in a lattice”

  • attrname (str) – Attribute name

  • index (int | None) – Index in the attribute array. If None, the whole array is specified

  • name (str) – Observable name. If None, an explicit name will be generated

Keyword Arguments:

statfun – Post-processing function called on the value of the observable. Example: statfun=numpy.mean

Example

>>> obs = LatticeObservable(at.Sextupole, "KickAngle", index=0, statfun=np.sum)

Observe the sum of horizontal kicks in Sextupoles

class LocalOpticsObservable(refpts, param, plane=Ellipsis, name=None, all_points=False, **kwargs)[source]#

Bases: ElementObservable

Observe a local optics parameter at selected locations.

Process the local output of get_optics().

Parameters:

  • refpts (Refpts) – Observation points. See “Selecting elements in a lattice”

  • param (str | Callable) – Optics parameter name (see get_optics()) or user-defined evaluation function

  • plane (AxisDef) – Index in the parameter array, If Ellipsis, the whole array is specified

  • name (str) – Observable name. If None, an explicit name will be generated

  • all_points (bool) – Compute the local optics at all elements. This avoids discontinuities in phase advances. This is automatically set for the ‘mu’ parameter, but may need to be specified for user-defined evaluation functions using the phase advance.

Keyword Arguments:

  • summary – Set to True if the user-defined evaluation function returns a single item (see below)

  • statfun – Post-processing function called on the value of the observable. Example: statfun=numpy.mean

  • target – Target value for a constraint. If None (default), the residual will always be zero.

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

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

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

User-defined evaluation function

It is called as:

value = fun(elemdata)

  • elemdata is the output of get_optics(), evaluated at the refpts of the observable,

  • value is the value of the Observable and must have one line per refpoint. Alternatively, it may be a single line, but then the summary keyword must be set to True.

Examples

>>> obs = LocalOpticsObservable(at.Monitor, "beta")

Observe the beta in both planes at all Monitor locations

>>> obs = LocalOpticsObservable(
...     at.Quadrupole, "beta", plane="y", statfun=np.max
... )

Observe the maximum vertical beta in Quadrupoles

>>> def phase_advance(elemdata):
...     mu = elemdata.mu
...     return mu[-1] - mu[0]
>>>
>>> allobs.append(
...     LocalOpticsObservable(
...         [33, 101], phase_advance, all_points=True, summary=True
...     )
... )

The user-defined evaluation function computes the phase-advance between the 1st and last given reference points, here the elements 33 and 101 of the lattice

class MatrixObservable(refpts, axis=Ellipsis, name=None, **kwargs)[source]#

Bases: ElementObservable

Observe the closed orbit at selected locations.

Processs the result of calling find_m44() or find_m44() depending upon is_6d().

Parameters:

  • refpts (Refpts) – Observation points. See “Selecting elements in a lattice”

  • axis (AxisDef) – Index in the transfer matrix, If Ellipsis, the whole matrix is specified

  • name (str) – Observable name. If None, an explicit name will be generated

Keyword Arguments:

  • statfun – Post-processing function called on the value of the observable. Example: statfun=numpy.mean

  • target – Target value for a constraint. If None (default), the residual will always be zero.

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

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

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

Example

>>> obs = MatrixObservable(at.Monitor, axis=("x", "px"))

Observe the transfer matrix from origin to monitor locations and extract T[0,1]

class Need(value)[source]#

Bases: Enum

Defines the computation requirements for an Observable.

ALL_POINTS = 8#

Associated with LOCALOPTICS, require local optics computation at all points: slower but avoids jumps in phase advance

CHROMATICITY = 9#

Associated with LOCALOPTICS, require the get_chrom keyword

EMITTANCE = 7#

Specify envelope_parameters() computation and provide its params output to the evaluation function

GEOMETRY = 11#

Specify get_geometry() computation and provide its ? output to the evaluation function

GLOBALOPTICS = 4#

Specify get_optics() computation and provide its ringdata output to the evaluation function

LOCALOPTICS = 5#

Specify get_optics() computation and provide its elemdata output to the evaluation function

MATRIX = 3#

Specify find_m44() or find_m44() computation and provide its m44 or m66 output to the evaluation function

ORBIT = 2#

Specify find_orbit() computation and provide its orbit output to the evaluation function

RING = 1#

Provides the ring data to the evaluation function

TRAJECTORY = 6#

Specify lattice_pass() computation and provide its r_out to the evaluation function

W_FUNCTIONS = 10#

Associatef with LOCALOPTICS, require the get_w keyword

class Observable(fun, *args, name=None, target=None, weight=1.0, bounds=(0.0, 0.0), needs=None, **kwargs)[source]#

Bases: object

Base class for Observables. Can be used for user-defined observables

Parameters:

  • name (str) – Observable name. If None, an explicit name will be generated

  • fun (Callable) – evaluation function

  • *args – Arguments provided to the evaluation function

  • target – Target value for a constraint. If None (default), the residual will always be zero.

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

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

  • needs (Set[Need]) – Set of requirements. This selects the data provided to the evaluation function. needs items are members of the Need enumeration

Keyword Arguments:

**kwargs – Keyword arguments provided to the evaluation function

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

User-defined evaluation function

The general form is:

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

  • data depends on the needs argument, and by default is empty. If several needed values are specified, their order is: ring, orbit, m44/m66, ringdata, elemdata, r_out, params, geomdata,

  • args are the positional arguments provided to the observable constructor,

  • kwargs are the keyword arguments provided to the observable constructor,

  • value is the value of the observable.

For user-defined evaluation functions using linear optics data or emittance data, it is recommended to use LocalOpticsObservable, GlobalOpticsObservable or EmittanceObservable which provide the corresponding data argument.

evaluate(*data, initial=False)[source]#

Compute and store the value of the observable

The direct evaluation of a single Observable is normally not used. This method is called by the ObservableList container which provides the data arguments.

Parameters:

  • *data – Raw data, provided by ObservableList and sent to the evaluation function

  • initial (bool) – It None, store the result as the initial value

property deviation#

Deviation from target value, computed as deviation = value-target

fun: Callable#

Evaluation function

name: str#

Observable name

needs: Set[Need]#

Set of requirements

property residual#

residual, computed as residual = ((value-target)/weight)**2

target#

Target value

property value#

Value of the observable

property weight#

Observable weight

property weighted_deviation#

weighted_deviation = (value-target)/weight

property weighted_value#

Weighted value of the Observable, computed as weighted_value = value/weight

class OrbitObservable(refpts, axis=None, name=None, **kwargs)[source]#

Bases: ElementObservable

Observe the transfer matrix at selected locations.

Process the orbit output of find_orbit().

Parameters:

  • refpts (Refpts) – Observation points. See “Selecting elements in a lattice”

  • axis (AxisDef) – Index in the orbit vector, If None, the whole vector is specified

  • name (str) – Observable name. If None, an explicit name will be generated

Keyword Arguments:

  • statfun – Post-processing function called on the value of the observable. Example: statfun=numpy.mean

  • target – Target value for a constraint. If None (default), the residual will always be zero.

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

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

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

Example

>>> obs = OrbitObservable(at.Monitor, axis=0)

Observe the horizontal closed orbit at monitor locations

class RingObservable(fun, name=None, **kwargs)[source]#

Bases: Observable

Observe any user-defined property of a ring

Parameters:
Keyword Arguments:

  • target – Target value for a constraint. If None (default), the residual will always be zero.

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

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

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

User-defined evaluation function

It is called as:

value = fun(ring)

  • ring is the lattice description,

  • value is the value of the Observable.

Examples

>>> def circumference(ring):
...     return ring.get_s_pos(len(ring))[0]
>>> obs = RingObservable(circumference)

Defines an Observable for the ring circumference.

>>> def momentum_compaction(ring):
...     return ring.get_mcf()
>>> obs = RingObservable(momentum_compaction)

Defines an Observable for the momentum compaction factor.

class TrajectoryObservable(refpts, axis=Ellipsis, name=None, **kwargs)[source]#

Bases: ElementObservable

Observe trajectory coordinates at selected locations

Process the r_out output if Lattice.track()

Parameters:

  • refpts (Refpts) – Observation points. See “Selecting elements in a lattice”

  • axis (AxisDef) – Index in the orbit array, If Ellipsis, the whole array is specified

  • name (str) – Observable name. If None, an explicit name will be generated

Keyword Arguments:

  • statfun – Post-processing function called on the value of the observable. Example: statfun=numpy.mean

  • target – Target value for a constraint. If None (default), the residual will always be zero.

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

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

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

GlobalOpticsObservable(param, plane=Ellipsis, name=None, use_integer=False, **kwargs)[source]#

Observe a global optics parameter.

Process the ringdata output of get_optics().

Parameters:

  • param (str) – Optics parameter name (see get_optics()) or user-defined evaluation function

  • plane (AxisDef) – Index in the parameter array, If Ellipsis, the whole array is specified

  • name (str | None) – Observable name. If None, an explicit name will be generated

  • use_integer (bool) – For ‘tune’ parameter: derive the tune from the phase advance to avoid skipping integers. Slower than looking only at the fractional part

Keyword Arguments:

  • target – Target value for a constraint. If None (default), the residual will always be zero.

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

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

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

User-defined evaluation function

It is called as:

value = fun(ring, ringdata)

  • ringdata is the output of get_optics(),

  • value is the value of the Observable.

Examples

>>> obs = GlobalOpticsObservable("tune", use_integer=True)

Observe the tune in both planes, including the integer part (slower)

>>> obs = GlobalOpticsObservable("chromaticity", plane="v")

Observe the vertical chromaticity