at.latticetools.observablelist#

Grouping of Observable objects for fast evaluation.

ObservableList(lattice, …): This container based on list is in charge of optics computations and provides each individual Observable with its specific data.

ObservableList provides the evaluate() method and the following properties:

values
flat_values
weights
flat_weights
weighted_values
flat_weighted_values
deviations
flat_deviations
residuals
sum_residuals

Classes

`EvaluationVariable`(obslist, key, args, *kwargs)	A reference to a parameter given to the ObservableList.evaluate method.
`ObservableList`([obsiter, ring])	Handles a list of Observables to be evaluated together.

class EvaluationVariable(obslist, key, *args, **kwargs)[source]#

Bases: ItemVariable

A reference to a parameter given to the ObservableList.evaluate method.

The variable drives the default value of a ObservableList.evaluate() keyword argument.

Parameters:

obslist (ObservableList) – The ObservableList to control,
key – Index or attribute name of the variable. A str argument is interpreted as a dictionary key. Attribute names must be decorated with attr_(attrname) to distinguish them from directory keys.
*args – additional sequence of indices or attribute names allowing to extract elements deeper in the object structure.

Keyword Arguments:

name (str) – Name of the Variable. Default: ''
bounds (tuple[float, float]) – Lower and upper bounds of the variable value. Default: (-inf, inf)
delta (float) – Step. Default: 1.0

Example

Create a twiss_in input for computing optics in transfer-line mode:

>>> twiss_in = {"alpha": np.zeros(2), "beta": np.array([9.0, 2.5])}

Create the ObservableList:

>>> obs = at.ObservableList(
...     [
...         at.LocalOpticsObservable([0], "beta", plane="x"),
...         at.LocalOpticsObservable([0], "beta", plane="y"),
...     ],
...     ring=ring,
...     dp=0.01,
...     orbit=np.zeros(6),
...     twiss_in=twiss_in,
... )

Create a variable controlling \(\delta\):

>>> v3 = at.EvaluationVariable(obs, "dp")
>>> v3.value
0.01

Create a variable controlling \(p_x\):

>>> v2 = at.EvaluationVariable(obs, "orbit", 1)
>>> v2.value
np.float64(0.0)

Create a variable controlling \(\beta_x\):

>>> v1 = at.EvaluationVariable(obs, "twiss_in", "beta", 0)
>>> v1.value
np.float64(9.0)

class ObservableList(obsiter=(), ring=None, **kwargs)[source]#

Bases: list

Handles a list of Observables to be evaluated together.

ObservableList supports all the list methods, like appending, insertion or concatenation with the “+” operator.

Parameters:

obsiter (Iterable[Observable]) – Iterable of Observables
ring (Lattice | None) – Default lattice. It will be used if ring is not provided to the evaluate() function.

The following keyword arguments define the default values to be used when not given to the evaluate() method

Keyword Arguments:

orbit (Orbit) – Initial orbit. Avoids looking for the closed orbit if it is already known. Used for MatrixObservable and LocalOpticsObservable
twiss_in – Initial conditions for transfer line optics. See get_optics(). Used for LocalOpticsObservable
r_in (Orbit) – Initial trajectory, used for TrajectoryObservable, Default: zeros(6)
dp (float) – Momentum deviation. Defaults to None
dct (float) – Path lengthening. Defaults to None
df (float) – Deviation from the nominal RF frequency. Defaults to None
method (Callable) – Method for linear optics. Used for LocalOpticsObservable. Default: linopt6
use_mp (bool) – Activate parallel calculation. Used for RDTObservable, Default: False
pool_size (int | None) – Number of processes used for parallelization. Used for RDTObservable, Default: None
**kwargs – Other keywords are passed to the evaluation functions.

Example

>>> obslist = ObservableList()

Create an empty Observable list

>>> obslist.append(OrbitObservable(at.Monitor, plane="x"))
>>> obslist.append(GlobalOpticsObservable("tune"))
>>> obslist.append(EmittanceObservable("emittances", plane="h"))

Add observables for horizontal closed orbit at Monitor locations, tunes and horizontal emittance

>>> obslist.evaluate(ring, initial=True)

Compute the values and mark them as the initial value

>>> obslist.values
[array([-3.02189464e-09,  4.50695130e-07,  4.08205818e-07,
         2.37899969e-08, -1.31783561e-08,  2.47230794e-08,
         2.95310770e-08, -4.05598110e-07, -4.47398092e-07,
         2.24850671e-09]),
array([3.81563019e-01, 8.54376397e-01, 1.09060730e-04]),
1.320391045951568e-10]

>>> obslist.get_flat_values("tune", "emittances[h]")
array([3.815630e-01, 8.543764e-01, 1.090607e-04, 1.320391e-10])

Get a flattened array of tunes and horizontal emittance

append(obs)[source]#

Append observable to the end of the list.

check()[source]#

Check if all observables are evaluated.

Returns:: ok – True if evaluation is done, False otherwise
Raises:: AtError – any value is doubtful: evaluation failed, empty value…

evaluate(ring=None, *, initial=False, **kwargs)[source]#

Compute all the Observable values.

Parameters:

ring (Lattice | None) – Lattice used for evaluation
initial (bool) – If True, store the values as initial values

Keyword Arguments:

orbit (Orbit) – Initial orbit. Avoids looking for the closed orbit if it is already known. Used for MatrixObservable and LocalOpticsObservable
twiss_in – Initial conditions for transfer line optics. See get_optics(). Used for LocalOpticsObservable
r_in (Orbit) – Initial trajectory, used for TrajectoryObservable, Default: zeros(6)
dp (float) – Momentum deviation. Defaults to None
dct (float) – Path lengthening. Defaults to None
df (float) – Deviation from the nominal RF frequency. Defaults to None
method (Callable) – Method for linear optics. Used for LocalOpticsObservable. Default: linopt6
use_mp (bool) – Activate parallel calculation. Used for RDTObservable, Default: False
pool_size (int | None) – Number of processes used for parallelization. Used for RDTObservable, Default: None
**kwargs – Other keywords are passed to the evaluation functions.

exclude(obsname, excluded)[source]#

Set the excluded mask on the selected observable.

extend(obsiter)[source]#

Extend list by appending Observables from the iterable.

get_deviations(*obsid, err=None)[source]#

Return the deviations from target values.

Parameters:

*obsid (str | int) – name or index of selected observables (Default all)
err (float | None) – Default observable value to be used when the evaluation failed. By default, an Exception is raised.

get_flat_deviations(*obsid, err=None, order='F')[source]#

Return a 1-D array of deviations from target values.

Parameters:

*obsid (str | int) – name or index of selected observables (Default all)
err (float | None) – Default observable value to be used when the evaluation failed. By default, an Exception is raised.
order (str) – Ordering for reshaping. See reshape()

get_flat_shape(*obsid)[source]#

Return the shape of the flattened values.

Parameters:: *obsid (str | int) – name or index of selected observables (Default all)

get_flat_targets(*obsid)[source]#

Return a 1-D array of target values of observables.

Parameters:

*obsid (str | int) – name or index of selected observables (Default all)
err – Default observable value to be used when the evaluation failed. By default, an Exception is raised.

get_flat_values(*obsid, err=None, order='F')[source]#

Return a 1-D array of Observable values.

Parameters:

*obsid (str | int) – name or index of selected observables (Default all)
err (float | None) – Default observable value to be used when the evaluation failed. By default, an Exception is raised.
order (str) – Ordering for reshaping. See reshape()

get_flat_weighted_deviations(*obsid, err=None, order='F')[source]#

Return a 1-D array of weighted deviations from target values.

Parameters:

*obsid (str | int) – name or index of selected observables (Default all)
err (float | None) – Default observable value to be used when the evaluation failed. By default, an Exception is raised.
order (str) – Ordering for reshaping. See reshape()

get_flat_weighted_values(*obsid, err=None, order='F')[source]#

Return a 1-D array of Observable weighted values.

Parameters:

*obsid (str | int) – name or index of selected observables (Default all)
err (float | None) – Default observable value to be used when the evaluation failed. By default, an Exception is raised.
order (str) – Ordering for reshaping. See reshape()

get_flat_weights(*obsid, order='F')[source]#

Return a 1-D array of Observable weights.

Parameters:

*obsid (str | int) – name or index of selected observables (Default all)
order (str) – Ordering for reshaping. See reshape()

get_residuals(*obsid, err=None)[source]#

Return the residuals of observables.

Parameters:

*obsid (str | int) – name or index of selected observables (Default all)
err (float | None) – Default observable value to be used when the evaluation failed. By default, an Exception is raised.

get_shapes(*obsid)[source]#

Return the shapes of all values.

Parameters:: *obsid (str | int) – name or index of selected observables (Default all)

get_sum_residuals(*obsid, err=None)[source]#

Return the sum of residual values.

Parameters:

*obsid (str | int) – name or index of selected observables (Default all)
err (float | None) – Default observable value to be used when the evaluation failed. By default, an Exception is raised.

get_targets(*obsid, err=None)[source]#

Return the target values of observables.

Parameters:

*obsid (str | int) – name or index of selected observables (Default all)
err (float | None) – Default observable value to be used when the evaluation failed. By default, an Exception is raised.

get_values(*obsid, err=None)[source]#

Return the values of observables.

Parameters:

*obsid (str | int) – name or index of selected observables (Default all)
err (float | None) – Default observable value to be used when the evaluation failed. By default, an Exception is raised.

Raises:

Exception – Any exception raised during evaluation, unless err has been set.

get_weighted_deviations(*obsid, err=None)[source]#

Return the weighted deviations from target values.

Parameters:

*obsid (str | int) – name or index of selected observables (Default all)
err (float | None) – Default observable value to be used when the evaluation failed. By default, an Exception is raised.

get_weighted_values(*obsid, err=None)[source]#

Return the weighted values of observables.

Parameters:

*obsid (str | int) – name or index of selected observables (Default all)
err (float | None) – Default observable value to be used when the evaluation failed. By default, an Exception is raised.

get_weights(*obsid)[source]#

Return the weights of observables.

Parameters:: *obsid (str | int) – name or index of selected observables (Default all)

insert(index, obs)[source]#

Insert Observable before index.

property deviations: tuple#: Deviations from target values

property flat_deviations: ndarray[tuple[Any, ...], dtype[float64]]#: 1-D array of deviations from target value

property flat_shape#: Shape of the flattened values

property flat_targets: tuple#: 1-D array of target values

property flat_values: ndarray[tuple[Any, ...], dtype[float]]#: 1-D array of Observable values

property flat_weighted_deviations: ndarray[tuple[Any, ...], dtype[float]]#: 1-D array of weighted deviations from target values

property flat_weighted_values: ndarray[tuple[Any, ...], dtype[float]]#: 1-D array of Observable weigthed values

property flat_weights: ndarray[tuple[Any, ...], dtype[float]]#: 1-D array of Observable weights

property residuals: tuple#: Residuals of all observable

property shapes: tuple#: Shapes of all values

property sum_residuals: float#: Sum of all residual values

property targets: tuple#: Target values of all observables

property values: tuple#: values of all observables

property weighted_deviations: tuple#: Weighted deviations from target values

property weighted_values: tuple#: Weighted values of all observables

property weights: tuple#: Weights of all observables