atomsmltr.environment.zones package#

The atomsmltr.environment.zones subpackage provides definitions for spatial zones

Those zones are then used in Configuration objects to define position and speed zones in which some actions have to be taken - for instance, stopping the simulation

Create a zone#

Define two zones, for x and vx

from atomsmltr.environment.zones import Limits

xlim = Limits(min=-1, max=1, axis=0, target="position", action="stop", tag="xlim")
vxlim = Limits(min=0, max=500, axis=0, target="speed", action="stop", tag="vxlim")

Combining Zones#

Once a series of Zone are defined, it is possible to combine them using basic python operators. The result will be a ZoneCollection with different combination rules, depending on the operator.

Note that a ZoneCollection is a particular kind of Zone, so operators also work on ZoneCollection.

ANDCollection#

A ANDCollection can be generated using the & operator :

>>> and_collection = zone1 & zone2

The created and_collection object then has two zones in its .zones list, namely zone1 and zone2. Its in_zone() method will return the result of zone1.get_value() and zone2.get_value()

ORCollection#

A ORCollection can be generated using the | operator :

>>> or_collection = zone1 | zone2

XORCollection#

A XORCollection can be generated using the ^ operator :

>>> xor_collection = zone1 ^ zone2

Adding zones to a collection#

Zones can be added to a collection using the += operator :

>>> xor_collection = zone1 ^ zone2
>>> xor_collection += zone3

Zones of a same kind can also be appended

>>> and_coll1 = zone1 & zone2
>>> and_coll2 = zone3 & zone4
>>> and_coll3 = and_coll1 + and_coll2

See also

atomsmltr.environment.zones.generic, atomsmltr.environment.zones.limits, atomsmltr.environment.zones.volumes

class atomsmltr.environment.zones.Box(xmin: float, xmax: float, ymin: float, ymax: float, zmin: float, zmax: float, target: str = 'position', action: str = 'stop', tag: str = None, in_tag: str = None, out_tag: str = None)[source]#

Bases: Zone

A 3D box with cartesian coordinates

Parameters:

  • xmin (float) – minimum value for x

  • xmax (float) – maximum value for x

  • ymin (float) – minimum value for y

  • ymax (float) – maximum value for y

  • zmin (float) – minimum value for z

  • zmax (float) – maximum value for z

  • target (str, optional) – the target for the zone, can be “position” or “speed”, by default “position”

  • action (str, optional) – the action associated to the zone. Currently only “stop” is implemented, by default “stop”

  • tag (str, optional) – the zone tag

  • in_tag (str, optional) – tag for an object inside the zone, by default None

  • out_tag (str, optional) – tag for an object inside the zone, by default None

Example

from atomsmltr.environment.zones import Box

pos_box = Box(
    xmin=-10,
    xmax=10,
    ymin=0,
    ymax=5,
    zmin=-8,
    zmax=100,
    target="position",
    action="tag",
    tag="position box",
)
gen_infostring_obj()[source]#

Generates an info string object

property type#

a description of the object type

Type:

str

property xmax#

the maximum value for x

Type:

float

property xmin#

the minimum value for x

Type:

float

property ymax#

the maximum value for y

Type:

float

property ymin#

the minimum value for y

Type:

float

property zmax#

the maximum value for z

Type:

float

property zmin#

the minimum value for z

Type:

float

class atomsmltr.environment.zones.Cylinder(origin: ndarray = (0, 0, 0), direction: ndarray = (1, 0, 0), radius: float = 1.0, target='position', action='stop', tag=None, in_tag: str = None, out_tag: str = None)[source]#

Bases: Zone

A cylinder zone

Parameters:

  • origin (array, shape (3), optional) – the ‘center’ of the cylinder, i.e. a point on its axis, by default (0, 0, 0)

  • direction (array, shape (3), optional) – a vector along the axis of the cylinder, by default (1, 0, 0)

  • radius (float, optional) – the cylinder radius, in m or m/s, by default 1.0

  • target (str, optional) – the target for the zone, can be “position” or “speed”, by default “position”

  • action (str, optional) – the action associated to the zone. Currently only “stop” is implemented, by default “stop”

  • tag (str, optional) – the zone tag

  • in_tag (str, optional) – tag for an object inside the zone, by default None

  • out_tag (str, optional) – tag for an object inside the zone, by default None

property direction: ndarray#

cylinder axis direction

Type:

array, shape (3)

gen_infostring_obj()[source]#

Generates an info string object

property origin: ndarray#

cylinder ‘center’

Type:

array, shape (3)

property power: float#

cylinder radius (m) or (m/s)

Type:

float

property type#

a description of the object type

Type:

str

class atomsmltr.environment.zones.Limits(min: float, max: float, axis: int = 0, target: str = 'position', action: str = 'stop', tag: str = None, in_tag: str = None, out_tag: str = None)[source]#

Bases: Zone

Defines a 1D segment, with min / max value

Parameters:

  • min (float) – minimum value

  • max (float) – maximum value

  • axis (int, optional) – axis to consider (0:x, 1:y, 2:z), by default 0

  • target (str, optional) – the target for the zone, can be “position” or “speed”, by default “position”

  • action (str, optional) – the action associated to the zone. implemented actions = [“stop”, “ignore”], default is “stop”

  • tag (str, optional) – the zone tag

  • in_tag (str, optional) – tag for an object inside the zone, by default None

  • out_tag (str, optional) – tag for an object inside the zone, by default None

Example

>>> xlim = Limits(min=-1, max=1, axis=0, target="position", action="stop", tag="xlim")
property axis: int#

the target axis

Type:

int

gen_infostring_obj()[source]#

Generates an info string object

property max: float#

the upper limit

Type:

float

property min: float#

the lower limit

Type:

float

property type#

a description of the object type

Type:

str

class atomsmltr.environment.zones.LowerLimit(value: float, axis: int = 0, target: str = 'position', action: str = 'stop', tag: str = None, in_tag: str = None, out_tag: str = None)[source]#

Bases: SingleLimit

Defines a zone by its (1D) upper limit

Parameters:

  • value (float) – the lower limit

  • axis (int, optional) – axis to consider (0:x, 1:y, 2:z), by default 0

  • target (str, optional) – the target for the zone, can be “position” or “speed”, by default “position”

  • action (str, optional) – the action associated to the zone. implemented actions = [“stop”, “ignore”], default is “stop”

  • tag (str, optional) – the zone tag

  • in_tag (str, optional) – tag for an object inside the zone, by default None

  • out_tag (str, optional) – tag for an object inside the zone, by default None

Example

>>> low_x = LowerLimit(value=-5, axis=0, tag="lowx")
property type#

a description of the object type

Type:

str

class atomsmltr.environment.zones.SuperZone(zones: list = [], logic: str = 'AND', action: str = 'stop', tag: str = None, in_tag: str = None, out_tag: str = None)[source]#

Bases: ZoneCollection

SuperZone is a zone collection for position/speed vectors

Parameters:

  • zones (list, optional) – list of zones to add at object creation, by default []

  • logic (str, optional) – the logic of zone combination. Can be “OR”, “AND”, “XOR”, by default “AND”

  • action (str, optional) – the action to trigger implemented actions = [“stop”, “ignore”], default is “stop”

  • tag (str, optional) – the tag of the zone, by default None

  • in_tag (str, optional) – tag for an object inside the zone, by default None

  • out_tag (str, optional) – tag for an object inside the zone, by default None

gen_infostring_obj()[source]#

Generates an info string object

get_value(vector: ndarray, nocheck: bool = False) → ndarray[source]#

Evaluates whether ‘vector’ is in the zone

Parameters:

  • vector (array of shape (6,) or (n1, n2, ..., 6)) – cartesian coordinates of the vectors in the lab frame

  • nocheck (bool, optional) – if set to True, function will not check that the shape of position matches requirements, by default False

Returns:

value – whether the vector is ‘in the zone’

Return type:

array of shape (1,) or (n1, n2, …, 1)

Notes

This is a SuperZone object, so it acts on position-speed vectors of dimensions 6 !

vector should be an array of shape (6,) or (n1, n2, .., 6), where last axis contains the coordinates (position & speed) to evaluate.

In all cases, the last dimension contains cordinates (x, y, z, vx, vy, vz),

if the inverted property is set to true, get_value will return True outside the zone

property logic#

the logic for the SuperZone combination (“OR”, “XOR”, “AND”)

Type:

str

property target#

not used in this case

property type#

a description of the object type

Type:

str

class atomsmltr.environment.zones.UpperLimit(value: float, axis: int = 0, target: str = 'position', action: str = 'stop', tag: str = None, in_tag: str = None, out_tag: str = None)[source]#

Bases: SingleLimit

Defines a zone by its (1D) upper limit

Parameters:

  • value (float) – the upper limit

  • axis (int, optional) – axis to consider (0:x, 1:y, 2:z), by default 0

  • target (str, optional) – the target for the zone, can be “position” or “speed”, by default “position”

  • action (str, optional) – the action associated to the zone. implemented actions = [“stop”, “ignore”], default is “stop”

  • tag (str, optional) – the zone tag

  • in_tag (str, optional) – tag for an object inside the zone, by default None

  • out_tag (str, optional) – tag for an object inside the zone, by default None

Example

>>> up_x = UpperLimit(value=5, axis=0, tag="upx")
property type#

a description of the object type

Type:

str

class atomsmltr.environment.zones.Zone(target: str = 'position', action: str = 'stop', tag: str = None, in_tag: str = None, out_tag: str = None)[source]#

Bases: EnvObject

A generic Zone object

Parameters:

  • target (str, optional) – the target for the zone, can be “position” or “speed”, by default “position”

  • action (str, optional) – the action associated to the zone. implemented actions = [“stop”, “ignore”], default is “stop”

  • tag (str, optional) – the zone tag

  • in_tag (str, optional) – tag for an object inside the zone, by default None

  • out_tag (str, optional) – tag for an object inside the zone, by default None

property action#

the action associated with the zone. implemented actions = [“stop”, “ignore”].

Type:

str

get_value(vector: ndarray, nocheck: bool = False) → ndarray[source]#

Evaluates whether ‘vector’ is in the zone

Parameters:

  • vector (array of shape (3,) or (n1, n2, ..., 3)) – cartesian coordinates of the vectors in the lab frame

  • nocheck (bool, optional) – if set to True, function will not check that the shape of position matches requirements, by default False

Returns:

value – wheter the vector is ‘in the zone’

Return type:

array of shape (1,) or (n1, n2, …, 1)

Notes

vector should be an array of shape (…,3), where last axis contains the coordinates to evaluate.

if the inverted property is set to true, get_value will return True outside the zone

property in_tag: str#

tag for a object inside the zone

Type:

str

invert()[source]#

toggles the ‘inverted’ status

property inverted#

if inverted, the zone logic is inverted

Type:

bool

inverted_copy()[source]#

Returns an inverted copy of the object

property out_tag: str#

tag for a object outside the zone

Type:

str

property target#

the target for the zone. Can be “position” or “speed”

Type:

str

property vector#

True it the object value is vectorial, False if scalar

Type:

bool

Submodules#