generic fields#

This module implements the generic Field class, and some perfect fields (Offset, Gradient, Quadrupole). Those are abstract classes, and actual implementations are gathered in other packages

See also

atomsmltr.utils.infostring.InfoString

class atomsmltr.environment.fields.generic.Field(*args, **kwargs)[source]#

Bases: EnvObject

A generic class to describe Field objects.

get_norm(position: ndarray) → ndarray[source]#

Returns the field norm at a given position in the lab frame

Parameters:: position (np.ndarray, shape (,3) or (n1, n2, .., 3)) – positions at which the intensity is computed, given as cartesian coordinates in the lab frame.
Returns:: norm – returns the (scalar) field norm
Return type:: np.ndarray, shape (,1) or (n1, n2, .., 1)

get_value(position: ndarray) → ndarray[source]#

returns the value of the field at a given position.

Parameters:: position (np.ndarray, shape (,3) or (n1, n2, .., 3)) – positions at which the intensity is computed, given as cartesian coordinates in the lab frame.
Returns:: value – returns the (vector) field value
Return type:: np.ndarray, same shape as position

Notes

position is an array_like object, with shape (3,) or (n1, n2, .., 3). In all cases, the last dimension contains cordinates (x, y, z), in meter and in the lab frame

The field value is returned as an array with the same shape as position.

>>> field_value = field.get_value(position)
>>> X, Y, Z = position.T
>>> Fx, Fy, Fz = field_value.T

plot1D(start: ndarray, stop: ndarray, Npoints: int = 100, component: str = 'Bz', ax=None, show: bool = False, space_scale: float = 1.0)[source]#

Plots a 1D line cut of the magnetic field using Matplotlib

Parameters:

start (array-like, shape (3,)) – Starting point (x, y, z) of the line along which to sample the field.
stop (array-like, shape (3,)) – Ending point (x, y, z) of the line along which to sample the field.
Npoints (int, optional) – Number of points sampled along the line. Defaults to 100.
component (str, optional) – Field component to plot. Accepted values are “Bx”, “By”, “Bz” for vector components, or “B” for total field magnitude. Defaults to “Bz”.
ax (Matplotlib Axes, optional) – The matplotlib axis on which to plot. If None is given, a new figure is created. Defaults to None.
show (bool, optional) – Whether to show the figure after calling the method. Defaults to False.
space_scale (float, optional) – Space coordinates will be multiplied by this when plotting. Defaults to 1.

Returns:

ax – The axis on which the plot was performed.

Return type:

Matplotlib Axes

Notes

The field is sampled along a straight line between start and stop using Npoints equally spaced positions. The field component or magnitude is computed and plotted as a function of the distance along the line.

Examples

>>> field.plot1D(start=[0, 0, -10], stop=[0, 0, 10], Npoints=200)
>>> field.plot1D(start=[0, 0, -5], stop=[5, 0, 0], component="B", show=True)
>>> field.plot1D(start=[-5, 0, 0], stop=[5, 0, 0], component="Bx", space_scale=1e-3)

plot2D(limits: ndarray, Npoints: ndarray, cut: float = 0.0, ax=None, plane: str = 'XY', cmap=None, show: bool = False, space_scale: float = 1.0)[source]#

Plots a 2D cut of the field, using Matplotlib streamplot()

Parameters:

limits (array, shape (4,)) – an array of size 4, providing (xmin, xmax, ymin, ymax).
Npoints (int or array of shape (2,)) – number of points for each dimension, either a int or an array of two ints (Nx, Ny).
cut (float, optional) – coordinate of the third axis for the cut. Defaults to 0.
ax (Matplotlib Axes, optional) – the matplotlib axis on which to plot. If None is given a new figure is created. Defaults to None.
plane (str, optional) – the plane for the cut. Accepted values are “XY”, “YZ” and “ZX”. Defaults to “XY”.
cmap (Matplotlib cmap, optional) – passed to matplotlib streamplot() function
show (bool, optional) – whether to show the figure after calling the method. Defaults to False.
space_scale (float, optional) – space coordinates will be multiplied by this when plotting. Defaults to 1.

Returns:

ax – the axis on which the plot was performed.

Return type:

Matplotlib Axes

Notes

The limits are given via an array of size 4 ‘limits’, providing providing (xmin, xmax, ymin, ymax) Number of points are given with ‘Npoints’, either as an integer (same value for x and y) or an array of size 2 the coordinate of the cut axis is given by ‘cut’

Examples

>>> field.plot2D(limits=(-5, 5, -4, 4), Npoints=200)
>>> field.plot2D(limits=(-5, 5, -4, 4), Npoints=200, cut=-5)
>>> field.plot2D(limits=(-5, 5, -4, 4), Npoints=(200, 100))

plot3D(limits, Npoints, ax=None, color=None, name=None, show=False, scale=1.0, normalize=False)[source]#

plots a 3D representation of the field, using Matplotlib quiver()

Parameters:

limits (array, shape (,6)) – limits for the plot (xmin, xmax, ymin, ymax, zmin, zmax)
Npoints (int or array of shape (,3)) – number of points for each dimension, either a int or an array of three ints (Nx, Ny, Nz)
ax (custom Axes3D, optional) – the axis in which to plot. If None is given (default value) a new ax is generated
color (str, optional) – a matplotlib compatible color. Defaults to None.
name (str, optional) – the name of the field, passed as a label when plotting. Defaults to None.
show (bool, optional) – whether the show the figure after calling the method. Defaults to False.
scale (float, optional) – a scale factor for plotting the arrows (defaults to 1)
normalize (bool, optional) – if set to True, we normalize the magnetic field to have a max value of 1 before plotting. Defaults to False

Returns:

ax – the axis on which the plot was performed.

Return type:

Matplotlib Axes

abstract property unit#

returns the unit of the field

Type:: str

property vector#

True it the object value is vectorial, False if scalar

Type:: bool

class atomsmltr.environment.fields.generic.GradientField(origin: ndarray, slope: float, gradient_direction: ndarray, field_direction: ndarray, offset: float = 0.0, tag: str = None)[source]#

Bases: Field

A perfect linear field gradient

Parameters:

origin (array, shape (,3)) – origin for the gradient, in cartesian coordinates in the lab frame
slope (float) – the slope of the gradient, in ‘field unit’ / m
gradient_direction (array, shape (.3)) – the direction of the gradient
field_direction (array, shae (,3)) – the direction of the field
offset (float, optional) – an offset for the field amplitude at origin, in ‘field unit’, by default 0.0
tag (str, optional) – field tag, by default None

Notes

Note that ‘gradient_direction’ and ‘field_direction’ are meant to be unit vectors, but the class will take care of normalizing any non normalized entry

Examples

Create a field pointing along z, with a amplitude increasing linearly along x

>>> gradient = GradientField(
...  origin=(0, 0, 0),
...  slope=1,
...  gradient_direction=(1, 0, 0),
...  field_direction=(0, 0, 1),
...  tag="gradient",
... )

property field_direction: ndarray#

the field direction

Type:: array, shape (,3)

gen_infostring_obj()[source]#: Generates an info string object

property gradient_direction: ndarray#

the gradient direction

Type:: array, shape (,3)

property offset: float#

the field amplitude value at origin

Type:: float

property origin: ndarray#

the origin for the gradient

Type:: array, shape (,3)

property slope: float#

the field amplitude gradient slope

Type:: float

class atomsmltr.environment.fields.generic.QuadrupoleField(origin: ndarray, strong_axis: ndarray, slope: float, tag: str = None)[source]#

Bases: BaseQuadrupoleField

A perfect quadrupole field with strong axis along a given vector

Parameters:

origin (array, shape (,3)) – origin for the quadrupole, in cartesian coordinates in the lab frame
strong_axis (array, shape (,3)) – the direction of the strong axis
slope (float) – the gradient of the weak axes
tag (str, optional) – field tag, by default None

Notes

Note that ‘strong_axis’ is meant to be a unit vector, but the class will take care of normalizing any non normalized entry

class atomsmltr.environment.fields.generic.QuadrupoleFieldX(origin: ndarray, slope: float, tag: str = None)[source]#

Bases: BaseQuadrupoleField

A perfect quadrupole field with strong axis along X

Parameters:

origin (array, shape (,3)) – origin for the quadrupole, in cartesian coordinates in the lab frame
slope (float) – the gradient of the weak axes
tag (str, optional) – field tag, by default None

Notes

Note that ‘strong_axis’ is meant to be a unit vector, but the class will take care of normalizing any non normalized entry

class atomsmltr.environment.fields.generic.QuadrupoleFieldY(origin: ndarray, slope: float, tag: str = None)[source]#

Bases: BaseQuadrupoleField

A perfect quadrupole field with strong axis along Y

Parameters:

origin (array, shape (,3)) – origin for the quadrupole, in cartesian coordinates in the lab frame
slope (float) – the gradient of the weak axes
tag (str, optional) – field tag, by default None

Notes

Note that ‘strong_axis’ is meant to be a unit vector, but the class will take care of normalizing any non normalized entry

class atomsmltr.environment.fields.generic.QuadrupoleFieldZ(origin: ndarray, slope: float, tag: str = None)[source]#

Bases: BaseQuadrupoleField

A perfect quadrupole field with strong axis along Z

Parameters:

origin (array, shape (,3)) – origin for the quadrupole, in cartesian coordinates in the lab frame
slope (float) – the gradient of the weak axes
tag (str, optional) – field tag, by default None

Notes

Note that ‘strong_axis’ is meant to be a unit vector, but the class will take care of normalizing any non normalized entry

generic fields#

This Page