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)

VariableBase methods

VariableBase provides the following methods:

VariableBase properties

VariableBase provides the following properties:

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

On this page