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

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

class CustomVariable(setfun, getfun, *args, name='', bounds=(-inf, inf), delta=1.0, history_length=None, ring=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) – Function for getting the variable value. Called as getfun(*args, ring=ring, **kwargs) -> Number
setfun (Callable) – Function for setting the variable value. Called as setfun(value: Number, *args, ring=ring, **kwargs): None
name (str) – Name of the Variable
bounds (tuple[int | float, int | float]) – 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(*, name='', bounds=(-inf, inf), delta=1.0, history_length=None, ring=None)[source]#

Bases: ABC

A Variable abstract base class

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

Parameters:

name (str) – Name of the Variable
bounds (tuple[int | float, int | float]) – Lower and upper bounds of the variable value
delta (int | float) – Initial variation step
history_length (int) – Maximum length of the history buffer. None means infinite
ring – provided to an attempt to get the initial value of the variable

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

Get the actual variable value

Parameters:

ring – Depending on the variable type, a Lattice argument may be necessary to get the variable value.
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

Returns:

value – Value of the variable

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

Increment the variable value

Parameters:

incr (int | float) – Increment value
ring – Depending on the variable type, a Lattice argument may be necessary to increment the variable.

reset(ring=None)[source]#

Reset to the initial value and clear the history buffer

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

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

Set the variable value

Parameters:

value (int | float) – New value to be applied on the variable
ring – Depending on the variable type, a Lattice argument may be necessary to set the variable.

set_previous(ring=None)[source]#

Reset to the value before the last one

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

status()[source]#

Return a string describing the current status of the variable

Returns:: status – Variable description

step_down(ring=None)[source]#

Set to initial_value - delta

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

step_up(ring=None)[source]#

Set to initial_value + delta

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

bounds: tuple[int | float, int | float]#: Variable bounds

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

property last_value: int | float#: Last value of the variable

name: str#: Variable name

property previous_value: int | float#: Value before the last one

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.

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: Sequence[int | float]#: delta values of the variables