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 element-wise. 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 non-component 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/numpy-1.13.0/neps/ufunc-overrides.html for information about __array_ufunc__! See https://numpy.org/neps/nep-0018-array-function-protocol.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.

copy(self)[source]

Returns a copy of the Field object.

Returns
field: Field

A copy of the Field.

curl(self)[source]

Returns the curl of an N-dimensional 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 out-of-plane 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 a Field 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.

Notes

Signals recquire the hyperspy package!

get_vector(self, mask=None)[source]

Returns the field as a vector, specified by a mask.

Parameters
maskndarray (boolean)

Masks the pixels from which the entries should be taken. Must be a numpy array for indexing to work!

Returns
vectorndarray (N=1)

The vector containing the field of the specified pixels. If the field is a vector field, components are first vectorised, then concatenated!

gradient(self)[source]

Returns the gradient of an N-dimensional 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).

Parameters
kinteger

Number of times the array is rotated by 90 degrees.

axis: {‘x’, ‘y’, ‘z’}, optional

The axis around which the vector field is rotated. Default is ‘z’. Ignored for 2D Fields.

Returns
field: Field

The rotated Field.

rotate(self, angle, axis='z', **kwargs)[source]

Rotate the Field, based on rotate().

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
field: Field

The rotated Field.

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 to rotate(), 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
maskndarray (boolean), optional

Masks the pixels from which the field should be taken.

vectorndarray (N=1)

The vector containing the field of the specified pixels.

Returns
None
squeeze(self)[source]

Squeeze the Field object to remove single-dimensional 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.

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 z-axis 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 z-axis 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.

create_shape_voxel(dim, pos=None, scale=1.0)[source]

Creates a Field object with the shape of a single voxel in arbitrary dimension.

Parameters
dimtuple

The dimensions of the grid.

postuple, optional

The position of the voxel.

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 z-axis. 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 anti-clockwise 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 out-of-plane (“oop”) component in the vortex center. If None, the vortex is purely in-plane, which is the default. Set this to a number (in pixels) that determines the radius in which the oop-component 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 2-dimensional vortices!

oop_sign{1, -1}, optional

Only used if oop_r is not None (i.e. there is an out-of-plane 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 out-of-plane. 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 3-dimensional 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 z-axis. 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 out-of-plane 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 3-dimensional 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.