The Field container class¶
General empyre.fields docu here!
All functions implemented in the subpackages can be accessed directly in the empyre.fields
namespace.
The field module¶
This module provides a container class for multidimensional scalar or vector fields.

class
Field
(data, scale=1.0, vector=False)[source]¶ Bases:
numpy.lib.mixins.NDArrayOperatorsMixin
Container class for storing multidimensional scalar or vector fields.
The Field class is a sophisticated wrapper around a multidimensional numpy array. The user can access the underlying data via the data attribute, or by using the numpy.asarray function.
Field defines the ufunc interface for numpys vast library of universal functions. This includes all operator definitions, i.e., you can add, subtract, multiply and devide Field objects elementwise. Note that for vector fields, Field will handle all vector components separately and for ufuncs with two inputs, the other object will be broadcast accordingly. It is therefore also possible to add (or multiply) vector and scalar fields, assuming their dimensions dim match (their shape can’t match, because it includes the number of components ncomp for the vector field). For ufuncs that reduce the output shape (e.g. numpy.sum), if the axis parameter is set to None (default), component axes for vector fields are kept (they can however explicitely reduced by including them in the axis paremeter, e.g. by setting axis = 1).
Field objects can be indexed like numpy arrays and scalar fields (vector=False) behave as expected. A vector field (vector=True) can be indexed by only the noncomponent indices (see dim) and the according components of the specified point are returned as a tuple. Slicing with integers will return a Field object with reduced dimensionality (or a scalar/tuple if all spatial dimensions are reduced) that also drops the associated scales as needed. New axes (indexing with None or numpy.newaxis) is disabled because that would mean that an unknown scale would need to be added (you can always create a new Field object with an appropriately prepared ndarray).
Some callables exposed by numpy’s public API (e.g. numpy.mean(…)) will treat Field objects as if they were identical to their underlying numpy array (by envoking the __array__ function which just returns data). The result often is a simple numpy.ndarray and not a Field object. Some functions (e.g. clip) are also defined on Field as methods. They might behave differently and will return Field objects instead, so take care and refer to their docstrings for further information! # TODO: Too verbose? In documentation instead?
Notes
See https://docs.scipy.org/doc/numpy/reference/arrays.classes.html for information about ndarray subclassing! See https://docs.scipy.org/doc/numpy1.13.0/neps/ufuncoverrides.html for information about __array_ufunc__! See https://numpy.org/neps/nep0018arrayfunctionprotocol.html for information about __array_function__!
 Attributes
 data: np.ndarray
The underlying data array of the field.
 scale: tuple of float
Scaling along the dimensions of the underlying data.
 vector: bool
True if the field is a vector field, False if it is a scalar field.
 shape: tuple of ints
Shape of the underlying data. Includes the number of components as the first dimension if the field is a vector field.
 dim: tuple of ints
Dimensions of the underlying data. Only includes spatial dimensions, NOT the number of vector components! (Use ncomp to get the number of components, if any, shape for the full shape of the underlying array).
 ncomp: None or tuple of ints
Number of components if the field is a vector field (can be 2 or 3), None if it is a scalar field. The component axis is always the last axis (index 1) of the underlying data array!

bin
(self, n)[source]¶ Bins data of the Field to decrease the size of the underlying array by averaging over a number of values.
 Parameters
 n{sequence, array_like, int}
Number of entries along each axis over which the average is taken. Can be a single integer for all axes or a list, specifying the number of entries over which to average for each individual axis.
 Returns
 field: Field
The binned Field object.
Notes
Padding takes place before binning to ensure the dimensions are multiples of n. The padding mode is edge.

clip
(self, vmin=None, vmax=None, sigma=None, mask=None)[source]¶ Clip (limit) the values in an array. For vector fields, this will take the amplitude into account.
 Parameters
 vminfloat, optional
Mimimum value, by default None. Is ignored for vector fields. Will overwrite values found via sigma or mask.
 vmaxfloat, optional
Maximum value, by default None. Will overwrite values found via sigma or mask.
 sigmafloat, optional
Defines a range in standard deviations, that results in a boolean mask that excludes outliers, by default None. E.g. sigma=2 will mark points within the 5% highest amplitude as outliers. vmin and vmax will be searched in the remaining region. Is logically combined with mask if both are set.
 maskndarray, optional
Boolean array that directly describes where to search for vmin and vmax, by default None. Is logically combined with the mask from sigma if both are set.
 Returns
 field: Field
The clipped Field.
Notes
In contrast to the corresponding numpy function, vmin and vmax can both be None due to the alternative clipping strategies employed here.

curl
(self)[source]¶ Returns the curl of an Ndimensional Field.
 Returns
 field: Field
The curl/rotation.
Notes
The calculation depends on the input: 3 dimensions, 3 components: Calculates the full 3D rotational vector field! 2 dimensions, 2 components: Calculates the outofplane component of the curl as a 2D scalar field! 2 dimensions, scalar: Calculates the planar rotation as a 2D vector field!

flip
(self, axis=None, **kwargs)[source]¶ Returns a Field with entries flipped along specified axes.
 Parameters
 axistuple or None, optional
Axes whose entries will be flipped, by default None.

classmethod
from_scalar_fields
(scalar_list)[source]¶ Create a vector Field object from a list of scalar Fields.
 Parameters
 scalar_listlist
List of scalar Field objects (vector=False).
 Returns
 vector_field: Field
A vector Field object containing the input scalar fields as components.

classmethod
from_signal
(signal, scale=None, vector=None, comp_pos=1)[source]¶ Convert a
Signal
object to aField
object. Parameters
 signal: :class:`~hyperspy.signals.Signal`
The
Signal
object which should be converted to Field.
 Returns
 field:
Field
A
Field
object containing the loaded data. scale: tuple of float, optional
Scaling along the dimensions of the underlying data. If not provided, will be read from the axes_manager.
 vector: boolean, optional
If set to True, forces the signal to be interpreted as a vector field. EMPyRe will check if the first axis is named ‘vector components’ (EMPyRe saves vector fields like this). If this is the case, vector will be automatically set to True and the signal will also be interpreted as a vector field.
 comp_pos: int, optoinal
The index of the axis containing the vector components (if vector=True). EMPyRe needs this to be the last axis (index 1, which is the default). In case another position is given, the vector component will be moved to the last axis. Old Pyramid files will have this axis at index 0, so use this for backwards compatibilty.
 field:
Notes
Signals recquire the hyperspy package!

get_vector
(self, mask=None)[source]¶ Returns the field as a vector, specified by a mask.
 Parameters
 mask
ndarray
(boolean) Masks the pixels from which the entries should be taken. Must be a numpy array for indexing to work!
 mask
 Returns
 vector
ndarray
(N=1) The vector containing the field of the specified pixels. If the field is a vector field, components are first vectorised, then concatenated!
 vector

gradient
(self)[source]¶ Returns the gradient of an Ndimensional scalar Field. Wrapper around the according numpy function.
 Returns
 gradients: ndarray or list of ndarray
A set of ndarrays (or a single ndarray for 1D input), corresponding to the derivatives of the field with respect to each dimension.
Notes
The field is implicitely squeezed before the gradient is calculated!

pad
(self, pad_width, mode='constant', **kwargs)[source]¶ Pad the Field object and increase the size of the underlying array.
 Parameters
 pad_width{sequence, array_like, int}
Number of values padded to the edges of each axis. Can be a single number for all, one number per axis or a tuple (before, after) for each axis for finer control.
 modestr, optional
Padding mode (see numpy.pad for all options), by default ‘constant’, which pads with zeros.
 Returns
 field: Field
The padded Field object.

rot90
(self, k=1, axis='z')[source]¶ Rotate the
Field
90° around the specified axis (right hand rotation).

rotate
(self, angle, axis='z', **kwargs)[source]¶ Rotate the
Field
, based onrotate()
.Rotation direction is from the first towards the second axis. Works for 2D and 3D Fields.
 Parameters
 anglefloat
The rotation angle in degrees.
 axis: {‘x’, ‘y’, ‘z’}, optional
The axis around which the vector field is rotated. Default is ‘z’. Ignored for 2D Fields.
 Returns
Notes
All additional kwargs are passed through to
rotate()
. The reshape parameter, controlling if the output shape is adapted so that the input array is contained completely in the output is False per default, contrary torotate()
, where it is True.

set_vector
(self, vector, mask=None)[source]¶ Set the field of the masked pixels to the values specified by vector.
 Parameters
 mask
ndarray
(boolean), optional Masks the pixels from which the field should be taken.
 vector
ndarray
(N=1) The vector containing the field of the specified pixels.
 mask
 Returns
 None

squeeze
(self)[source]¶ Squeeze the Field object to remove singledimensional entries in the shape.
 Returns
 field: Field
Squeezed Field object. Note that scales associated with squeezed dimensions are also dropped.
Notes
Also works via numpy.squeeze(field), because numpy.squeeze searches for a local implementation first and then uses _wrapit to envoke this function here!

to_signal
(self)[source]¶ Convert
Field
data into a HyperSpy signal. Returns
 signal:
Signal
Representation of the
Field
object as a HyperSpy Signal.
 signal:
Notes
This method recquires the hyperspy package!

zoom
(self, zoom, **kwargs)[source]¶ Wrapper for the scipy.ndimage.zoom function.
 Parameters
 zoomfloat or sequence
Zoom factor along the axes. If a float, zoom is the same for each axis. If a sequence, zoom needs to contain one value for each axis.
 Returns
 field: Field
The zoomed in Field object.
Notes
As in scipy.ndimage.zoom, a spline order can be specified, which defaults to 3.
The shapes module¶

create_shape_slab
(dim, center=None, width=None, scale=1.0)[source]¶ Creates a Field object with the shape of a slab as a scalar field in arbitrary dimensions.
 Attributes
 dimtuple
The dimensions of the grid.
 centertuple, optional
The center of the slab in pixel coordinates.
 widthtuple, optional
The width of the slab in pixel coordinates.
 scale: tuple of float
Scaling along the dimensions of the underlying data.

create_shape_disc
(dim, center=None, radius=None, height=None, axis=0, scale=1.0)[source]¶ Creates a Field object with the shape of a cylindrical disc in 2D or 3D.
 Attributes
 dimtuple
The dimensions of the grid.
 centertuple, optional
The center of the disc in pixel coordinates.
 radiusfloat, optional
The radius of the disc in pixel coordinates.
 heightfloat, optional
The height of the disc in pixel coordinates. Unused if only 2D.
 axisint, optional
The orientation of the discs orthogonal axis. Only used in 3D case with zaxis as default.
 scale: tuple of float
Scaling along the dimensions of the underlying data.

create_shape_ellipse
(dim, center=None, width=None, height=None, axis=0, scale=1.0)[source]¶ Creates a Field object with the shape of an ellipse in 2D or 3D.
 Attributes
 dimtuple
The dimensions of the grid.
 centertuple, optional
The center of the ellipse in pixel coordinates.
 widthtuple, optional
The two half axes of the ellipse in pixel coordinates.
 heightfloat, optional
The height of the ellipse in pixel coordinates. Unused if only 2D.
 axisint, optional
The orientation of the ellipses orthogonal axis. Only used in 3D case with zaxis as default.
 scale: tuple of float
Scaling along the dimensions of the underlying data.

create_shape_ellipsoid
(dim, center=None, width=None, scale=1.0)[source]¶ Creates a Field object with the shape of an ellipsoid in arbitrary dimensions.
 Attributes
 dimtuple
The dimensions of the grid.
 centertuple, optional
The center of the ellipsoid in pixel coordinates.
 widthtuple, optional
The half axes of the ellipsoid in pixel coordinates.
 scale: tuple of float
Scaling along the dimensions of the underlying data.

create_shape_sphere
(dim, center=None, radius=None, scale=1.0)[source]¶ Creates a Field object with the shape of a sphere in arbitrary dimensions.
 Attributes
 dimtuple
The dimensions of the grid.
 centertuple, optional
The center of the sphere in pixel coordinates.
 widthtuple, optional
The half axes of the sphere in pixel coordinates.
 scale: tuple of float
Scaling along the dimensions of the underlying data.

create_shape_filament
(dim, pos=None, axis=0, scale=1.0)[source]¶ Creates a Field object with the shape of a filament in arbitrary dimension.
 Parameters
 dimtuple
The dimensions of the grid.
 postuple, optional
The position of the filament in pixel coordinates. Has to be a tuple of len(dim)  1 and denotes the index positions along all axes aside from the specified axis along which the filament is placed.
 axisint, optional
The orientation of the filament axis. Defaults to the first axis.
 scale: tuple of float
Scaling along the dimensions of the underlying data.
The vectors module¶

create_vector_homog
(dim, phi=0, theta=None, scale=1.0)[source]¶ Field subclass implementing a homogeneous vector field with 2 or 3 components in 2 or 3 dimensions.
 Attributes
 dimtuple
The dimensions of the grid.
 phifloat
The azimuthal angle. The default is 0, i.e., the vectors point in x direction.
 thetafloat, optional
The polar angle. If None (default), only two components will be created (corresponds to pi/2 in 3D, i.e., the vectors are in the xy plane).
 scale: tuple of float
Scaling along the dimensions of the underlying data.

create_vector_vortex
(dim, center=None, phi_0=1.5707963267948966, oop_r=None, oop_sign=1, core_r=0, axis=0, scale=1.0)[source]¶ Field subclass implementing a vortex vector field with 3 components in 2 or 3 dimensions.
 Returns
 field~.Field object
The resulting vector field.
 Attributes
 dimtuple
The dimensions of the grid.
 centertuple (N=2 or N=3), optional
The vortex center, given in 2D (v, u) or 3D (z, y, x), where the perpendicular axis is discarded (determined by the axis parameter). Is set to the center of the field of view if not specified. The vortex center should be between two pixels to avoid singularities.
 axisint, optional
The orientation of the vortex axis. The default is 0 and corresponds to the zaxis. Is ignored if dim is only 2D.
 phi_0float, optional
Angular offset that allows all arrows to be rotated simultaneously. The default value is pi/2 and corresponds to an anticlockwise rotation, while a value of pi/2 corresponds to a clockwise rotation. 0 and pi lead to arrows that all point in/outward.
 oop_rfloat, optional
Radius of a potential outofplane (“oop”) component in the vortex center. If None, the vortex is purely inplane, which is the default. Set this to a number (in pixels) that determines the radius in which the oopcomponent is tilted into the plane. A 0 leads to an immediate/sharp tilt (not visible without setting a core radius, see core_r), while setting this to the radius of your vortex disc, will let it tilt smoothly until reaching the edge. If this is None, only two components will be created for 2dimensional vortices!
 oop_sign{1, 1}, optional
Only used if oop_r is not None (i.e. there is an outofplane component). Can be 1 (default) or 1 and determines if the core (if it exists) is aligned parallel (+1) or antiparallel (1) to the chosen symmetry axis.
 core_rfloat, optional
Radius of a potential vortex core that’s homogeneously oriented outofplane. Is not used when oop_r is not set and defaults to 0, which means the vortex core is infinitely small.
 scale: tuple of float
Scaling along the dimensions of the underlying data.

create_vector_skyrmion
(dim, center=None, phi_0=0, core_sign=1, skyrm_d=None, wall_d=None, axis=0, scale=1.0)[source]¶ Create a 3dimensional magnetic Bloch or Neel type skyrmion distribution.
 Parameters
 dimtuple
The dimensions of the grid.
 centertuple (N=2 or N=3), optional
The source center, given in 2D (v, u) or 3D (z, y, x), where the perpendicular axis is discarded. Is set to the center of the field of view if not specified. The center has to be between two pixels.
 phi_0float, optional
Angular offset switching between Neel type (0 [default] or pi) or Bloch type (+/ pi/2) skyrmions.
 core_sign{1, 1}, optional
Can be 1 (default) or 1 and determines if the skyrmion core is aligned parallel (+1) or antiparallel (1) to the chosen symmetry axis.
 skyrm_dfloat, optional
Diameter of the skyrmion. Defaults to half of the smaller dimension perpendicular to the skyrmion axis if not specified.
 wall_dfloat, optional
Diameter of the domain wall of the skyrmion. Defaults to skyrm_d / 4 if not specified.
 axisint, optional
The orientation of the vortex axis. The default is 0 and corresponds to the zaxis. Is ignored if dim is only 2D.
 scale: tuple of float
Scaling along the dimensions of the underlying data.
 Returns
 field~.Field object
The resulting vector field.
Notes
To avoid singularities, the source center should lie between the pixel centers (which reside at coordinates with _.5 at the end), i.e. integer values should be used as center coordinates (e.g. coordinate 1 lies between the first and the second pixel).
Skyrmion wall width is dependant on exchange stiffness A [J/m] and anisotropy K [J/m³] The outofplane magnetization at the domain wall is described in a paper by Romming et al (see DOI: 10.1103/PhysRevLett.114.177203s)

create_vector_singularity
(dim, center=None, scale=1.0)[source]¶ Create a 3dimensional magnetic distribution of a homogeneous magnetized object.
 Parameters
 dimtuple
The dimensions of the grid.
 centertuple (N=2 or N=3), optional
The source center, given in 2D (v, u) or 3D (z, y, x), where the perpendicular axis is discarded. Is set to the center of the field of view if not specified. The source center has to be between two pixels.
 scale: tuple of float
Scaling along the dimensions of the underlying data.
 Returns
 field~.Field object
The resulting vector field.
Notes
To avoid singularities, the source center should lie between the pixel centers (which reside at coordinates with _.5 at the end), i.e. integer values should be used as center coordinates (e.g. coordinate 1 lies between the first and the second pixel).
Per default, all arrows point outwards, negate the resulting Field object with a minus after creation to let them point inwards.