at.lattice.variables#

Definition of Variable objects used in matching and response matrices.

See Example notebooks for examples of matching and response matrices.

Each Variable has a scalar value.

Class hierarchy

VariableBase(name, bounds, delta)

ElementVariable(elements, attrname, index, …)
RefptsVariable(refpts, attrname, index, …)
CustomVariable(setfun, getfun, …)

VariableBase methods

VariableBase provides the following methods:

get()
set()
set_previous()
reset()
increment()
step_up()
step_down()

VariableBase properties

VariableBase provides the following properties:

initial_value
last_value
previous_value
history

The VariableBase abstract class may be used as a base class to define custom variables (see examples). Typically, this consist in overloading the abstract methods _setfun and _getfun

Examples

Write a subclass of VariableBase which varies two drift lengths so that their sum is constant:

class ElementShifter(at.VariableBase):
    '''Varies the length of the elements identified by *ref1* and *ref2*
    keeping the sum of their lengths equal to *total_length*.

    If *total_length* is None, it is set to the initial total length
    '''

    def __init__(self, drift1, drift2, total_length=None, **kwargs):
        # store the 2 variable elements
        self.drift1 = drift1
        self.drift2 = drift2
        # store the initial total length
        if total_length is None:
            total_length = drift1.Length + drift2.Length
        self.length = total_length
        super().__init__(bounds=(0.0, total_length), **kwargs)

    def _setfun(self, value, **kwargs):
        self.drift1.Length = value
        self.drift2.Length = self.length - value

    def _getfun(self, **kwargs):
        return self.drift1.Length

And create a variable varying the length of drifts DR_01 and DR_01 and keeping their sum constant:

drift1 = hmba_lattice["DR_01"]
drift2 = hmba_lattice["DR_02"]
var2 = ElementShifter(drift1, drift2, name="DR_01")

Classes

`CustomVariable`(setfun, getfun, *args[, ...])	A Variable with user-defined get and set functions.
`VariableBase`(*args[, name, bounds, delta, ...])	A Variable abstract base class.
`VariableList`([iterable])	Container for Variable objects.

class CustomVariable(setfun, getfun, *args, name='', bounds=None, delta=1.0, history_length=None, **kwargs)[source]#

Bases: VariableBase

A Variable with user-defined get and set functions.

This is a convenience function allowing user-defined get and set functions. But subclassing Variable should always be preferred for clarity and efficiency.

Parameters:

getfun (Callable[..., Number]) – Function for getting the variable value. Called as getfun(*args, **kwargs) -> Number. args are the positional arguments given to the constructor, kwargs are the keyword arguments given to the constructor augmented with the keywords given to the get() function.
setfun (Callable[..., None]) – Function for setting the variable value. Called as setfun(value: Number, *args, **kwargs): None. args are the positional arguments given to the constructor, kwargs are the keyword arguments given to the constructor augmented with the keywords given to the set() function.
name (str) – Name of the Variable. If empty, a unique name is generated.
bounds (tuple[Number, Number] | None) – Lower and upper bounds of the variable value
delta (int | float) – Initial variation step
*args – Variable argument list transmitted to both the getfun and setfun functions. Such arguments can always be avoided by using partial() or callable class objects.

Keyword Arguments:

**kwargs – Keyword arguments transmitted to both the getfun and setfun functions. Such arguments can always be avoided by using partial() or callable class objects.

class VariableBase(*args, name='', bounds=None, delta=1.0, history_length=None, **kwargs)[source]#

Bases: ABC

A Variable abstract base class.

Derived classes must implement the _getfun() and _setfun() methods

Parameters:

*args – Positional arguments passed to the _setfun and _getfun methods
name (str) – Name of the Variable. If omitted or blank, a unique name is generated.
bounds (tuple[Number | None, Number | None] | None) – Lower and upper bounds of the variable value
delta (int | float) – Initial variation step
history_length (int | None) – Maximum length of the history buffer. None means infinite.

Keyword Arguments:

**kwargs – Keyword arguments passed to the _setfun and _getfun methods

check_bounds(value)[source]#

Check that a value is within the variable bounds.

Raises:: ValueError – If the value is not within bounds

get(*, initial=False, check_bounds=False, **getkw)[source]#

Get the actual variable value.

Parameters:

initial (bool) – If True, clear the history and set the variable initial value
check_bounds (bool) – If True, raise a ValueError if the value is out of bounds

Keyword Arguments:

ring – Depending on the variable type, a Lattice argument may be necessary to set the variable.
**getkw – Other keyword arguments to be passed to the getfun function. They augment the keyword arguments given in the constructor.

Returns:

value – Value of the variable

increment(incr, **setkw)[source]#

Increment the variable value.

Parameters:

incr (int | float) – Increment value

Keyword Arguments:

ring – Depending on the variable type, a Lattice argument may be necessary to set the variable.
**setkw – Other keyword arguments to be passed to the setfun function. They augment the keyword arguments given in the constructor.

reset(**setkw)[source]#

Reset to the initial value and clear the history buffer.

Keyword Arguments:

ring – Depending on the variable type, a Lattice argument may be necessary to set the variable.
**setkw – Other keyword arguments to be passed to the setfun function. They augment the keyword arguments given in the constructor.

Raises:

IndexError – If no initial value has been set yet

set(value, **setkw)[source]#

Set the variable value.

Parameters:

value (int | float) – New value to be applied on the variable

Keyword Arguments:

ring – Depending on the variable type, a Lattice argument may be necessary to set the variable.
**setkw – Other keyword arguments to be passed to the setfun function. They augment the keyword arguments given in the constructor.

set_previous(**setkw)[source]#

Reset to the value before the last one.

Keyword Arguments:

ring – Depending on the variable type, a Lattice argument may be necessary to set the variable.
**setkw – Other keyword arguments to be passed to the setfun function. They augment the keyword arguments given in the constructor.

Raises:

IndexError – If there are fewer than 2 values in the history

status()[source]#

Return a string describing the current status of the variable.

Returns:: status – Variable description

step_down(**setkw)[source]#

Set to initial_value - delta.

Keyword Arguments:

ring – Depending on the variable type, a Lattice argument may be necessary to set the variable.
**setkw – Other keyword arguments to be passed to the setfun function. They augment the keyword arguments given in the constructor.

step_up(**setkw)[source]#

Set to initial_value + delta.

Keyword Arguments:

ring – Depending on the variable type, a Lattice argument may be necessary to set the variable.
**setkw – Other keyword arguments to be passed to the setfun function. They augment the keyword arguments given in the constructor.

DEFAULT_DELTA = 1.0#

property bounds: tuple[float, float]#: Lower and upper bounds of the variable.

delta: int | float#: Increment step

property history: list[int | float]#: History of the values of the variable.

history_length#: Maximum length of the history buffer. None means infinite

property initial_value: int | float#

Initial value of the variable.

Raises:: IndexError – If no initial value has been set yet

property last_value: int | float#

Last value of the variable.

Raises:: IndexError – If no value has been set yet

name: str#: Variable name

property previous_value: int | float#

Value before the last one.

Raises:: IndexError – If there are fewer than 2 values in the history

property value: int | float#: Actual value

class VariableList(iterable=(), /)[source]#

Bases: list

Container for Variable objects.

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

get(ring=None, **kwargs)[source]#

Get the current values of Variables.

Parameters:

ring – Depending on the variable type, a Lattice argument may be necessary to set the variable.

Keyword Arguments:

initial – If True, set the Variables’ initial value
check_bounds – If True, raise a ValueError if the value is out of bounds

Returns:

values – 1D array of values of all variables

increment(increment, ring=None)[source]#

Increment the values of Variables.

Parameters:

increment (Iterable[float]) – Iterable of values
ring – Depending on the variable type, a Lattice argument may be necessary to increment the variable.

reset(ring=None)[source]#

Reset to all variables their initial value and clear their history buffer.

Parameters:: ring – Depending on the variable type, a Lattice argument may be necessary to reset the variable.

set(values, ring=None)[source]#

Set the values of Variables.

Parameters:

values (Iterable[float]) – Iterable of values
ring – Depending on the variable type, a Lattice argument may be necessary to set the variable.

status(**kwargs)[source]#

String description of the variables.

property deltas: ndarray[tuple[Any, ...], dtype[int | float]]#: delta values of the variables.