magpylib.misc package

magpylib.misc package

This sub-package contains miscellaneous source objects.

class magpylib.misc.CustomSource(field_B_lambda=None, field_H_lambda=None, position=(0, 0, 0), orientation=None, style=None, **kwargs)

Bases: magpylib._src.obj_classes.class_BaseGeo.BaseGeo, magpylib._src.obj_classes.class_BaseDisplayRepr.BaseDisplayRepr, magpylib._src.obj_classes.class_BaseGetBH.BaseGetBH

Custom Source class

Parameters
  • field_B_lambda (function) – field function for B-field, should accept (n,3) position array and return B-field array of same shape in the global coordinate system.

  • field_H_lambda (function) – field function for H-field, should accept (n,3) position array and return H-field array of same shape in the global coordinate system.

  • position (array_like, shape (3,) or (M,3), default=(0,0,0)) – Object position (local CS origin) in the global CS in units of [mm]. For M>1, the position represents a path. The position and orientation parameters must always be of the same length.

  • orientation (scipy Rotation object with length 1 or M, default=unit rotation) – Object orientation (local CS orientation) in the global CS. For M>1 orientation represents different values along a path. The position and orientation parameters must always be of the same length.

Returns

CustomSource object

Return type

CustomSource

Examples

By default the CustomSource is initialized at position (0,0,0), with unit rotation:

>>> import magpylib as magpy
>>> import numpy as np

Define a external B-field function which returns constant vector in x-direction

>>> def constant_Bfield(position=((0,0,0))):
...    return np.array([[1,0,0]]*len(position))

Construct a CustomSource from the field function

>>> external_field = magpy.misc.CustomSource(field_B_lambda=constant_Bfield)
>>> B = external_field.getB([[1,2,3],[4,5,6]])
>>> print(B)
[[1. 0. 0.]
 [1. 0. 0.]]

The custom source can be rotated as any other source object in the library.

>>> external_field.rotate_from_angax(90, 'z')
>>> B = external_field.getB([[1,2,3],[4,5,6]])
>>> print(B) # Notice the outut field is now pointing in y-direction
[[0. 1. 0.]
 [0. 1. 0.]]
_get_style_class()

returns style class based on object type. If class has no attribute _object_type or is not found in MAGPYLIB_FAMILIES returns BaseStyle class.

_rotate(rotation, anchor=None, start=- 1, increment=False)

rotate_from_XXX generates a scipy Rotation object R then rotate() is called with R then _rotate() is called from rotate() to enable Collection application

Inputs: rotation: scipy rotation object anchor: anchor point start: int or ‘append’, path start position increment: bool, interpretation of path-input

Rotates the object in the global coordinate system by a given rotation input (can be a path).

display(*, path=True, zoom=0, animate_time=3, markers=None, backend=None, canvas=None, **kwargs)

Display objects and paths graphically. Style input can be a style-dict or style-underscore_magic.

Parameters
  • objects (sources, collections or sensors) – Objects to be displayed.

  • path (bool or int i or array_like shape (n,) or ‘animate’, default = True) – Option False shows objects at final path position and hides paths. Option True shows objects at final path position and shows object paths. Option int i displays the objects at every i’th path position. Option array_like shape (n,) discribes certain path indices. The objects displays are displayed at every given path index. Option ‘animate’ (Plotly backend only) shows an animation of objectes moving along their paths.

  • zoom (float, default = 0) – Adjust plot zoom-level. When zoom=0 3D-figure boundaries are tight.

  • animate_time (float, default = 3) – Sets the animation duration.

  • markers (array_like, shape (N,3), default=None) – Display position markers in the global CS. By default no marker is displayed.

  • backend (string, default=None) – One of ‘matplotlib’ or ‘plotly’. If not set, parameter will default to magpylib.defaults.display.backend which comes as ‘matplotlib’ with installation.

  • canvas (pyplot Axis or plotly Figure, default=None) – Display graphical output in a given canvas: - with matplotlib: pyplot axis (must be 3D). - with plotly: plotly.graph_objects.Figure or plotly.graph_objects.FigureWidget By default a new canvas is created and displayed.

Returns

None

Return type

NoneType

Examples

Display multiple objects, object paths, markers in 3D using Matplotlib or Plotly:

>>> import magpylib as magpy
>>> src = magpy.magnet.Sphere(magnetization=(0,0,1), diameter=1)
>>> src.move([(.1,0,0)]*50, increment=True)
>>> src.rotate_from_angax(angle=[10]*50, axis='z', anchor=0, start=0, increment=True)
>>> ts = [-.4,0,.4]
>>> sens = magpy.Sensor(position=(0,0,2), pixel=[(x,y,0) for x in ts for y in ts])
>>> magpy.display(src, sens)
>>> magpy.display(src, sens, backend='plotly')
--> graphic output

Display figure on your own canvas (here Matplotlib 3D axis):

>>> import matplotlib.pyplot as plt
>>> import magpylib as magpy
>>> my_axis = plt.axes(projection='3d')
>>> magnet = magpy.magnet.Cuboid(magnetization=(1,1,1), dimension=(1,2,3))
>>> sens = magpy.Sensor(position=(0,0,3))
>>> magpy.display(magnet, sens, canvas=my_axis, zoom=1)
>>> plt.show()
--> graphic output

Use sophisticated figure styling options accessible from defaults, as individual object styles or as global style arguments in display.

>>> import magpylib as magpy
>>> src1 = magpy.magnet.Sphere((1,1,1), 1)
>>> src2 = magpy.magnet.Sphere((1,1,1), 1, (1,0,0))
>>> magpy.defaults.display.style.magnet.magnetization.size = 2
>>> src1.style.magnetization.size = 1
>>> magpy.display(src1, src2, style_color='r', zoom=3)
--> graphic output
property field_B_lambda

field function for B-field, should accept (n,3) position array and return B-field array of same shape in the global coordinate system.

property field_H_lambda

field function for H-field, should accept (n,3) position array and return H-field array of same shape in the global coordinate system.

getB(*observers, squeeze=True)

Compute B-field in units of [mT] for given observers.

Parameters
  • observers (array_like or Sensors) – Observers can be array_like positions of shape (N1, N2, …, 3) where the field should be evaluated or Sensor objects with pixel shape (N1, N2, …, 3). Pixel shapes (or observer positions) of all inputs must be the same. All positions are given in units of [mm].

  • sumup (bool, default=False) – If True, the fields of all sources are summed up.

  • squeeze (bool, default=True) – If True, the output is squeezed, i.e. all axes of length 1 in the output (e.g. only a single source) are eliminated.

Returns

B-field – B-field at each path position (M) for each sensor (K) and each sensor pixel position (N1,N2,…) in units of [mT]. Sensor pixel positions are equivalent to simple observer positions. Paths of objects that are shorter than M will be considered as static beyond their end.

Return type

ndarray, shape squeeze(M, K, N1, N2, …, 3)

Examples

getH(*observers, squeeze=True)

Compute H-field in units of [kA/m] for given observers.

Parameters
  • observers (array_like or Sensors) – Observers can be array_like positions of shape (N1, N2, …, 3) where the field should be evaluated or Sensor objects with pixel shape (N1, N2, …, 3). Pixel shapes (or observer positions) of all inputs must be the same. All positions are given in units of [mm].

  • sumup (bool, default=False) – If True, the fields of all sources are summed up.

  • squeeze (bool, default=True) – If True, the output is squeezed, i.e. all axes of length 1 in the output (e.g. only a single source) are eliminated.

Returns

H-field – H-field at each path position (M) for each sensor (K) and each sensor pixel position (N1,N2,…) in units of [kA/m]. Sensor pixel positions are equivalent to simple observer positions. Paths of objects that are shorter than M will be considered as static beyond their end.

Return type

ndarray, shape squeeze(M, K, N1, N2, …, 3)

Examples

move(displacement, start=- 1, increment=False)

Translates the object by the input displacement (can be a path).

This method uses vector addition to merge the input path given by displacement and the existing old path of an object. It keeps the old orientation. If the input path extends beyond the old path, the old path will be padded by its last entry before paths are added up.

Parameters
  • displacement (array_like, shape (3,) or (N,3)) – Displacement vector shape=(3,) or path shape=(N,3) in units of [mm].

  • start (int or str, default=-1) – Choose at which index of the original object path, the input path will begin. If start=-1, inp_path will start at the last old_path position. If start=0, inp_path will start with the beginning of the old_path. If start=len(old_path) or start=’append’, inp_path will be attached to the old_path.

  • increment (bool, default=False) – If increment=False, input displacements are absolute. If increment=True, input displacements are interpreted as increments of each other. For example, an incremental input displacement of [(2,0,0), (2,0,0), (2,0,0)] corresponds to an absolute input displacement of [(2,0,0), (4,0,0), (6,0,0)].

Returns

self

Return type

Magpylib object

Examples

With the move method Magpylib objects can be repositioned in the global coordinate system:

>>> import magpylib as magpy
>>> sensor = magpy.Sensor()
>>> print(sensor.position)
[0. 0. 0.]
>>> sensor.move((1,1,1))
>>> print(sensor.position)
[1. 1. 1.]

It is also a powerful tool for creating paths:

>>> import magpylib as magpy
>>> sensor = magpy.Sensor()
>>> sensor.move((1,1,1), start='append')
>>> print(sensor.position)
[[0. 0. 0.]
 [1. 1. 1.]]
>>> sensor.move([(.1,.1,.1)]*2, start='append')
>>> print(sensor.position)
[[0.  0.  0. ]
 [1.  1.  1. ]
 [1.1 1.1 1.1]
 [1.1 1.1 1.1]]

Complex paths can be generated with ease, by making use of the increment keyword and superposition of subsequent paths:

>>> import magpylib as magpy
>>> sensor = magpy.Sensor()
>>> sensor.move([(1,1,1)]*4, start='append', increment=True)
>>> print(sensor.position)
[[0. 0. 0.]
 [1. 1. 1.]
 [2. 2. 2.]
 [3. 3. 3.]
 [4. 4. 4.]]
>>> sensor.move([(.1,.1,.1)]*5, start=2)
>>> print(sensor.position)
[[0.  0.  0. ]
 [1.  1.  1. ]
 [2.1 2.1 2.1]
 [3.1 3.1 3.1]
 [4.1 4.1 4.1]
 [4.1 4.1 4.1]
 [4.1 4.1 4.1]]
property orientation

Object orientation attribute getter and setter.

property position

Object position attribute getter and setter.

reset_path()

Reset object path to position = (0,0,0) and orientation = unit rotation.

Returns

self

Return type

Magpylib object

Examples

Create an object with non-zero path

>>> import magpylib as magpy
>>> obj = magpy.Sensor(position=(1,2,3))
>>> print(obj.position)
[1. 2. 3.]
>>> obj.reset_path()
>>> print(obj.position)
[0. 0. 0.]
rotate(rotation, anchor=None, start=- 1, increment=False)

Rotates object in the global coordinate system using a scipy Rotation object as input.

Parameters
  • rotation (scipy Rotation object) – Rotation to be applied to existing object orientation. The scipy Rotation object can be of shape (3,) or (N,3).

  • anchor (None, 0 or array_like, shape (3,), default=None) – The axis of rotation passes through the anchor point given in units of [mm]. By default (anchor=None) the object will rotate about its own center. anchor=0 rotates the object about the origin (0,0,0).

  • start (int or str, default=-1) – Choose at which index of the original object path, the input path will begin. If start=-1, inp_path will overwrite the last old_path position. If start=0, inp_path will start with the beginning of the old_path. If start=len(old_path) or start=’append’, inp_path will be attached to the old_path.

  • increment (bool, default=False) – If increment=False, input rotations are absolute. If increment=True, input rotations are interpreted as increments of each other.

Returns

self

Return type

Magpylib object

Examples

>>> from scipy.spatial.transform import Rotation as R
>>> import magpylib as magpy
>>> s = magpy.Sensor(position=(1,0,0))

print initial position and orientation >>> print(s.position) >>> print(s.orientation.as_euler(‘xyz’, degrees=True)) [1. 0. 0.] [0. 0. 0.]

rotate and print resulting position and orientation >>> s.rotate(R.from_euler(‘z’, 45, degrees=True), anchor=0) >>> print(s.position) >>> print(s.orientation.as_euler(‘xyz’, degrees=True)) [0.70710678 0.70710678 0. ] [ 0. 0. 45.]

rotate_from_angax(angle, axis, anchor=None, start=- 1, increment=False, degrees=True)

Rotates object in the global coordinate system from angle-axis input.

Parameters
  • angle (int/float or array_like with shape (n,) unit [deg] (by default)) – Angle of rotation, or a vector of n angles defining a rotation path in units of [deg] (by default).

  • axis (str or array_like, shape (3,)) – The direction of the axis of rotation. Input can be a vector of shape (3,) or a string ‘x’, ‘y’ or ‘z’ to denote respective directions.

  • anchor (None or array_like, shape (3,), default=None, unit [mm]) – The axis of rotation passes through the anchor point given in units of [mm]. By default (anchor=None) the object will rotate about its own center. anchor=0 rotates the object about the origin (0,0,0).

  • start (int or str, default=-1) – Choose at which index of the original object path, the input path will begin. If start=-1, inp_path will overwrite the last old_path position. If start=0, inp_path will start with the beginning of the old_path. If start=len(old_path) or start=’append’, inp_path will be attached to the old_path.

  • increment (bool, default=False) – If increment=False, input rotations are absolute. If increment=True, input rotations are interpreted as increments of each other.

  • degrees (bool, default=True) – By default angle is given in units of [deg]. If degrees=False, angle is given in units of [rad].

Returns

self

Return type

Magpylib object

Examples

>>> import magpylib as magpy
>>> s = magpy.Sensor(position=(1,0,0))

print initial position and orientation >>> print(s.position) >>> print(s.orientation.as_euler(‘xyz’, degrees=True)) [1. 0. 0.] [0. 0. 0.]

rotate and print resulting position and orientation >>> s.rotate_from_angax(45, (0,0,1), anchor=0) >>> print(s.position) >>> print(s.orientation.as_euler(‘xyz’, degrees=True)) [0.70710678 0.70710678 0. ] [ 0. 0. 45.]

rotate_from_euler(seq, angles, anchor=None, start=- 1, increment=False, degrees=False)

Rotates object in the global coordinate system from Euler angle input.

Parameters
  • seq (string) – Specifies sequence of axes for rotations. Up to 3 characters belonging to the set {‘X’, ‘Y’, ‘Z’} for intrinsic rotations, or {‘x’, ‘y’, ‘z’} for extrinsic rotations. Extrinsic and intrinsic rotations cannot be mixed in one function call.

  • angles (float or array_like, shape (N,) or (N, [1 or 2 or 3])) – Euler angles specified in radians (degrees is False) or degrees (degrees is True).

  • anchor (None or array_like, shape (3,), default=None, unit [mm]) – The axis of rotation passes through the anchor point given in units of [mm]. By default (anchor=None) the object will rotate about its own center. anchor=0 rotates the object about the origin (0,0,0).

  • start (int or str, default=-1) – Choose at which index of the original object path, the input path will begin. If start=-1, inp_path will overwrite the last old_path position. If start=0, inp_path will start with the beginning of the old_path. If start=len(old_path) or start=’append’, inp_path will be attached to the old_path.

  • increment (bool, default=False) – If increment=False, input rotations are absolute. If increment=True, input rotations are interpreted as increments of each other.

  • degrees (bool, default False) – If True, then the given angles are assumed to be in degrees.

Returns

self

Return type

Magpylib object

Examples

>>> import magpylib as magpy
>>> s = magpy.Sensor(position=(1,0,0))

print initial position and orientation >>> print(s.position) >>> print(s.orientation.as_euler(‘xyz’, degrees=True)) [1. 0. 0.] [0. 0. 0.]

rotate and print resulting position and orientation >>> s.rotate_from_euler(‘z’, 45, anchor=0, degrees=True) >>> print(s.position) >>> print(s.orientation.as_euler(‘xyz’, degrees=True)) [0.70710678 0.70710678 0. ] [ 0. 0. 45.]

rotate_from_matrix(matrix, anchor=None, start=- 1, increment=False)

Rotates object in the global coordinate system from matrix input. (see scipy rotation package matrix input)

Parameters
  • matrix (array_like, shape (N, 3, 3) or (3, 3)) – A single matrix or a stack of matrices, where matrix[i] is the i-th matrix.

  • anchor (None or array_like, shape (3,), default=None, unit [mm]) – The axis of rotation passes through the anchor point given in units of [mm]. By default (anchor=None) the object will rotate about its own center. anchor=0 rotates the object about the origin (0,0,0).

  • start (int or str, default=-1) – Choose at which index of the original object path, the input path will begin. If start=-1, inp_path will overwrite the last old_path position. If start=0, inp_path will start with the beginning of the old_path. If start=len(old_path) or start=’append’, inp_path will be attached to the old_path.

  • increment (bool, default=False) – If increment=False, input rotations are absolute. If increment=True, input rotations are interpreted as increments of each other.

Returns

self

Return type

Magpylib object

Examples

>>> import magpylib as magpy
>>> s = magpy.Sensor(position=(1,0,0))

print initial position and orientation >>> print(s.position) >>> print(s.orientation.as_matrix()) [1. 0. 0.] [[1. 0. 0.]

[0. 1. 0.] [0. 0. 1.]]

rotate and print resulting position and orientation >>> s.rotate_from_matrix([(0,-1,0),(1,0,0),(0,0,1)], anchor=0) >>> print(s.position) >>> print(s.orientation.as_matrix()) [0. 1. 0.] [[ 0. -1. 0.]

[ 1. 0. 0.] [ 0. 0. 1.]]

rotate_from_mrp(mrp, anchor=None, start=- 1, increment=False)

Rotates object in the global coordinate system from Modified Rodrigues Parameters input. (see scipy rotation package Modified Rodrigues Parameters (MRPs))

Parameters
  • mrp (array_like, shape (N, 3) or (3,)) – A single vector or a stack of vectors, where mrp[i] gives the ith set of MRPs.

  • anchor (None or array_like, shape (3,), default=None, unit [mm]) – The axis of rotation passes through the anchor point given in units of [mm]. By default (anchor=None) the object will rotate about its own center. anchor=0 rotates the object about the origin (0,0,0).

  • start (int or str, default=-1) – Choose at which index of the original object path, the input path will begin. If start=-1, inp_path will overwrite the last old_path position. If start=0, inp_path will start with the beginning of the old_path. If start=len(old_path) or start=’append’, inp_path will be attached to the old_path.

  • increment (bool, default=False) – If increment=False, input rotations are absolute. If increment=True, input rotations are interpreted as increments of each other.

Returns

self

Return type

Magpylib object

Examples

>>> import magpylib as magpy
>>> s = magpy.Sensor(position=(1,0,0))

print initial position and orientation >>> print(s.position) >>> print(s.orientation.as_mrp()) [1. 0. 0.] [0. 0. 0.]

rotate and print resulting position and orientation >>> s.rotate_from_mrp((0,0,1), anchor=0) >>> print(s.position) >>> print(s.orientation.as_mrp()) [-1. 0. 0.] [0. 0. 1.]

rotate_from_quat(quat, anchor=None, start=- 1, increment=False)

Rotates object in the global coordinate system from Quaternion input.

Parameters
  • quat (array_like, shape (N, 4) or (4,)) – Each row is a (possibly non-unit norm) quaternion in scalar-last (x, y, z, w) format. Each quaternion will be normalized to unit norm.

  • anchor (None or array_like, shape (3,), default=None, unit [mm]) – The axis of rotation passes through the anchor point given in units of [mm]. By default (anchor=None) the object will rotate about its own center. anchor=0 rotates the object about the origin (0,0,0).

  • start (int or str, default=-1) – Choose at which index of the original object path, the input path will begin. If start=-1, inp_path will overwrite the last old_path position. If start=0, inp_path will start with the beginning of the old_path. If start=len(old_path) or start=’append’, inp_path will be attached to the old_path.

  • increment (bool, default=False) – If increment=False, input rotations are absolute. If increment=True, input rotations are interpreted as increments of each other.

Returns

self

Return type

Magpylib object

Examples

>>> import magpylib as magpy
>>> s = magpy.Sensor(position=(1,0,0))

print initial position and orientation >>> print(s.position) >>> print(s.orientation.as_quat()) [1. 0. 0.] [0. 0. 0. 1.]

rotate and print resulting position and orientation >>> s.rotate_from_quat((0,0,1,1), anchor=0) >>> print(s.position) >>> print(s.orientation.as_quat()) [0. 1. 0.] [0. 0. 0.70710678 0.70710678]

rotate_from_rotvec(rotvec, anchor=None, start=- 1, increment=False, degrees=False)

Rotates object in the global coordinate system from rotation vector input. (vector direction is the rotation axis, vector length is the rotation angle in [rad])

Parameters
  • rotvec (array_like, shape (N, 3) or (3,)) – A single vector or a stack of vectors, where rot_vec[i] gives the ith rotation vector.

  • anchor (None or array_like, shape (3,), default=None, unit [mm]) – The axis of rotation passes through the anchor point given in units of [mm]. By default (anchor=None) the object will rotate about its own center. anchor=0 rotates the object about the origin (0,0,0).

  • start (int or str, default=-1) – Choose at which index of the original object path, the input path will begin. If start=-1, inp_path will overwrite the last old_path position. If start=0, inp_path will start with the beginning of the old_path. If start=len(old_path) or start=’append’, inp_path will be attached to the old_path.

  • increment (bool, default=False) – If increment=False, input rotations are absolute. If increment=True, input rotations are interpreted as increments of each other.

  • degrees (bool, default False) – If True, then the given angles are assumed to be in degrees.

Returns

self

Return type

Magpylib object

Examples

>>> import magpylib as magpy
>>> s = magpy.Sensor(position=(1,0,0))

print initial position and orientation >>> print(s.position) >>> print(s.orientation.as_rotvec()) [1. 0. 0.] [0. 0. 0.]

rotate and print resulting position and orientation >>> s.rotate_from_rotvec((0,0,1), anchor=0) >>> print(s.position) >>> print(s.orientation.as_rotvec()) [0.54030231 0.84147098 0. ] [0. 0. 1.]

property style

instance of MagpyStyle for display styling options

class magpylib.misc.Dipole(moment=(None, None, None), position=(0, 0, 0), orientation=None, style=None, **kwargs)

Bases: magpylib._src.obj_classes.class_BaseGeo.BaseGeo, magpylib._src.obj_classes.class_BaseDisplayRepr.BaseDisplayRepr, magpylib._src.obj_classes.class_BaseGetBH.BaseGetBH

Magnetic dipole moment.

Local object coordinates: The Dipole is located in the origin of the local object coordinate system. Local (Dipole) and global CS coincide when position=(0,0,0) and orientation=unit_rotation.

Parameters
  • moment (array_like, shape (3,), unit [mT*mm^3]) – Magnetic dipole moment in units of [mT*mm^3] given in the local CS. For homogeneous magnets there is a relation moment=magnetization*volume.

  • position (array_like, shape (3,) or (M,3), default=(0,0,0)) – Object position (local CS origin) in the global CS in units of [mm]. For M>1, the position represents a path. The position and orientation parameters must always be of the same length.

  • orientation (scipy Rotation object with length 1 or M, default=unit rotation) – Object orientation (local CS orientation) in the global CS. For M>1 orientation represents different values along a path. The position and orientation parameters must always be of the same length.

Returns

Dipole object

Return type

Dipole

Examples

By default a Dipole is initialized at position (0,0,0), with unit rotation:

>>> import magpylib as magpy
>>> dipole = magpy.misc.Dipole(moment=(100,100,100))
>>> print(dipole.position)
[0. 0. 0.]
>>> print(dipole.orientation.as_quat())
[0. 0. 0. 1.]

Dipoles are magnetic field sources. Below we compute the H-field [kA/m] of the above Dipole at an observer position (1,1,1),

>>> H = dipole.getH((1,1,1))
>>> print(H)
[2.43740886 2.43740886 2.43740886]

or at a set of observer positions:

>>> H = dipole.getH([(1,1,1), (2,2,2), (3,3,3)])
>>> print(H)
[[2.43740886 2.43740886 2.43740886]
 [0.30467611 0.30467611 0.30467611]
 [0.0902744  0.0902744  0.0902744 ]]

The same result is obtained when the Dipole object moves along a path, away from the observer:

>>> dipole.move([(-1,-1,-1), (-2,-2,-2)], start=1)
>>> H = dipole.getH((1,1,1))
>>> print(H)
[[2.43740886 2.43740886 2.43740886]
 [0.30467611 0.30467611 0.30467611]
 [0.0902744  0.0902744  0.0902744 ]]
_get_style_class()

returns style class based on object type. If class has no attribute _object_type or is not found in MAGPYLIB_FAMILIES returns BaseStyle class.

_rotate(rotation, anchor=None, start=- 1, increment=False)

rotate_from_XXX generates a scipy Rotation object R then rotate() is called with R then _rotate() is called from rotate() to enable Collection application

Inputs: rotation: scipy rotation object anchor: anchor point start: int or ‘append’, path start position increment: bool, interpretation of path-input

Rotates the object in the global coordinate system by a given rotation input (can be a path).

display(*, path=True, zoom=0, animate_time=3, markers=None, backend=None, canvas=None, **kwargs)

Display objects and paths graphically. Style input can be a style-dict or style-underscore_magic.

Parameters
  • objects (sources, collections or sensors) – Objects to be displayed.

  • path (bool or int i or array_like shape (n,) or ‘animate’, default = True) – Option False shows objects at final path position and hides paths. Option True shows objects at final path position and shows object paths. Option int i displays the objects at every i’th path position. Option array_like shape (n,) discribes certain path indices. The objects displays are displayed at every given path index. Option ‘animate’ (Plotly backend only) shows an animation of objectes moving along their paths.

  • zoom (float, default = 0) – Adjust plot zoom-level. When zoom=0 3D-figure boundaries are tight.

  • animate_time (float, default = 3) – Sets the animation duration.

  • markers (array_like, shape (N,3), default=None) – Display position markers in the global CS. By default no marker is displayed.

  • backend (string, default=None) – One of ‘matplotlib’ or ‘plotly’. If not set, parameter will default to magpylib.defaults.display.backend which comes as ‘matplotlib’ with installation.

  • canvas (pyplot Axis or plotly Figure, default=None) – Display graphical output in a given canvas: - with matplotlib: pyplot axis (must be 3D). - with plotly: plotly.graph_objects.Figure or plotly.graph_objects.FigureWidget By default a new canvas is created and displayed.

Returns

None

Return type

NoneType

Examples

Display multiple objects, object paths, markers in 3D using Matplotlib or Plotly:

>>> import magpylib as magpy
>>> src = magpy.magnet.Sphere(magnetization=(0,0,1), diameter=1)
>>> src.move([(.1,0,0)]*50, increment=True)
>>> src.rotate_from_angax(angle=[10]*50, axis='z', anchor=0, start=0, increment=True)
>>> ts = [-.4,0,.4]
>>> sens = magpy.Sensor(position=(0,0,2), pixel=[(x,y,0) for x in ts for y in ts])
>>> magpy.display(src, sens)
>>> magpy.display(src, sens, backend='plotly')
--> graphic output

Display figure on your own canvas (here Matplotlib 3D axis):

>>> import matplotlib.pyplot as plt
>>> import magpylib as magpy
>>> my_axis = plt.axes(projection='3d')
>>> magnet = magpy.magnet.Cuboid(magnetization=(1,1,1), dimension=(1,2,3))
>>> sens = magpy.Sensor(position=(0,0,3))
>>> magpy.display(magnet, sens, canvas=my_axis, zoom=1)
>>> plt.show()
--> graphic output

Use sophisticated figure styling options accessible from defaults, as individual object styles or as global style arguments in display.

>>> import magpylib as magpy
>>> src1 = magpy.magnet.Sphere((1,1,1), 1)
>>> src2 = magpy.magnet.Sphere((1,1,1), 1, (1,0,0))
>>> magpy.defaults.display.style.magnet.magnetization.size = 2
>>> src1.style.magnetization.size = 1
>>> magpy.display(src1, src2, style_color='r', zoom=3)
--> graphic output
getB(*observers, squeeze=True)

Compute B-field in units of [mT] for given observers.

Parameters
  • observers (array_like or Sensors) – Observers can be array_like positions of shape (N1, N2, …, 3) where the field should be evaluated or Sensor objects with pixel shape (N1, N2, …, 3). Pixel shapes (or observer positions) of all inputs must be the same. All positions are given in units of [mm].

  • sumup (bool, default=False) – If True, the fields of all sources are summed up.

  • squeeze (bool, default=True) – If True, the output is squeezed, i.e. all axes of length 1 in the output (e.g. only a single source) are eliminated.

Returns

B-field – B-field at each path position (M) for each sensor (K) and each sensor pixel position (N1,N2,…) in units of [mT]. Sensor pixel positions are equivalent to simple observer positions. Paths of objects that are shorter than M will be considered as static beyond their end.

Return type

ndarray, shape squeeze(M, K, N1, N2, …, 3)

Examples

getH(*observers, squeeze=True)

Compute H-field in units of [kA/m] for given observers.

Parameters
  • observers (array_like or Sensors) – Observers can be array_like positions of shape (N1, N2, …, 3) where the field should be evaluated or Sensor objects with pixel shape (N1, N2, …, 3). Pixel shapes (or observer positions) of all inputs must be the same. All positions are given in units of [mm].

  • sumup (bool, default=False) – If True, the fields of all sources are summed up.

  • squeeze (bool, default=True) – If True, the output is squeezed, i.e. all axes of length 1 in the output (e.g. only a single source) are eliminated.

Returns

H-field – H-field at each path position (M) for each sensor (K) and each sensor pixel position (N1,N2,…) in units of [kA/m]. Sensor pixel positions are equivalent to simple observer positions. Paths of objects that are shorter than M will be considered as static beyond their end.

Return type

ndarray, shape squeeze(M, K, N1, N2, …, 3)

Examples

property moment

Object moment attributes getter and setter.

move(displacement, start=- 1, increment=False)

Translates the object by the input displacement (can be a path).

This method uses vector addition to merge the input path given by displacement and the existing old path of an object. It keeps the old orientation. If the input path extends beyond the old path, the old path will be padded by its last entry before paths are added up.

Parameters
  • displacement (array_like, shape (3,) or (N,3)) – Displacement vector shape=(3,) or path shape=(N,3) in units of [mm].

  • start (int or str, default=-1) – Choose at which index of the original object path, the input path will begin. If start=-1, inp_path will start at the last old_path position. If start=0, inp_path will start with the beginning of the old_path. If start=len(old_path) or start=’append’, inp_path will be attached to the old_path.

  • increment (bool, default=False) – If increment=False, input displacements are absolute. If increment=True, input displacements are interpreted as increments of each other. For example, an incremental input displacement of [(2,0,0), (2,0,0), (2,0,0)] corresponds to an absolute input displacement of [(2,0,0), (4,0,0), (6,0,0)].

Returns

self

Return type

Magpylib object

Examples

With the move method Magpylib objects can be repositioned in the global coordinate system:

>>> import magpylib as magpy
>>> sensor = magpy.Sensor()
>>> print(sensor.position)
[0. 0. 0.]
>>> sensor.move((1,1,1))
>>> print(sensor.position)
[1. 1. 1.]

It is also a powerful tool for creating paths:

>>> import magpylib as magpy
>>> sensor = magpy.Sensor()
>>> sensor.move((1,1,1), start='append')
>>> print(sensor.position)
[[0. 0. 0.]
 [1. 1. 1.]]
>>> sensor.move([(.1,.1,.1)]*2, start='append')
>>> print(sensor.position)
[[0.  0.  0. ]
 [1.  1.  1. ]
 [1.1 1.1 1.1]
 [1.1 1.1 1.1]]

Complex paths can be generated with ease, by making use of the increment keyword and superposition of subsequent paths:

>>> import magpylib as magpy
>>> sensor = magpy.Sensor()
>>> sensor.move([(1,1,1)]*4, start='append', increment=True)
>>> print(sensor.position)
[[0. 0. 0.]
 [1. 1. 1.]
 [2. 2. 2.]
 [3. 3. 3.]
 [4. 4. 4.]]
>>> sensor.move([(.1,.1,.1)]*5, start=2)
>>> print(sensor.position)
[[0.  0.  0. ]
 [1.  1.  1. ]
 [2.1 2.1 2.1]
 [3.1 3.1 3.1]
 [4.1 4.1 4.1]
 [4.1 4.1 4.1]
 [4.1 4.1 4.1]]
property orientation

Object orientation attribute getter and setter.

property position

Object position attribute getter and setter.

reset_path()

Reset object path to position = (0,0,0) and orientation = unit rotation.

Returns

self

Return type

Magpylib object

Examples

Create an object with non-zero path

>>> import magpylib as magpy
>>> obj = magpy.Sensor(position=(1,2,3))
>>> print(obj.position)
[1. 2. 3.]
>>> obj.reset_path()
>>> print(obj.position)
[0. 0. 0.]
rotate(rotation, anchor=None, start=- 1, increment=False)

Rotates object in the global coordinate system using a scipy Rotation object as input.

Parameters
  • rotation (scipy Rotation object) – Rotation to be applied to existing object orientation. The scipy Rotation object can be of shape (3,) or (N,3).

  • anchor (None, 0 or array_like, shape (3,), default=None) – The axis of rotation passes through the anchor point given in units of [mm]. By default (anchor=None) the object will rotate about its own center. anchor=0 rotates the object about the origin (0,0,0).

  • start (int or str, default=-1) – Choose at which index of the original object path, the input path will begin. If start=-1, inp_path will overwrite the last old_path position. If start=0, inp_path will start with the beginning of the old_path. If start=len(old_path) or start=’append’, inp_path will be attached to the old_path.

  • increment (bool, default=False) – If increment=False, input rotations are absolute. If increment=True, input rotations are interpreted as increments of each other.

Returns

self

Return type

Magpylib object

Examples

>>> from scipy.spatial.transform import Rotation as R
>>> import magpylib as magpy
>>> s = magpy.Sensor(position=(1,0,0))

print initial position and orientation >>> print(s.position) >>> print(s.orientation.as_euler(‘xyz’, degrees=True)) [1. 0. 0.] [0. 0. 0.]

rotate and print resulting position and orientation >>> s.rotate(R.from_euler(‘z’, 45, degrees=True), anchor=0) >>> print(s.position) >>> print(s.orientation.as_euler(‘xyz’, degrees=True)) [0.70710678 0.70710678 0. ] [ 0. 0. 45.]

rotate_from_angax(angle, axis, anchor=None, start=- 1, increment=False, degrees=True)

Rotates object in the global coordinate system from angle-axis input.

Parameters
  • angle (int/float or array_like with shape (n,) unit [deg] (by default)) – Angle of rotation, or a vector of n angles defining a rotation path in units of [deg] (by default).

  • axis (str or array_like, shape (3,)) – The direction of the axis of rotation. Input can be a vector of shape (3,) or a string ‘x’, ‘y’ or ‘z’ to denote respective directions.

  • anchor (None or array_like, shape (3,), default=None, unit [mm]) – The axis of rotation passes through the anchor point given in units of [mm]. By default (anchor=None) the object will rotate about its own center. anchor=0 rotates the object about the origin (0,0,0).

  • start (int or str, default=-1) – Choose at which index of the original object path, the input path will begin. If start=-1, inp_path will overwrite the last old_path position. If start=0, inp_path will start with the beginning of the old_path. If start=len(old_path) or start=’append’, inp_path will be attached to the old_path.

  • increment (bool, default=False) – If increment=False, input rotations are absolute. If increment=True, input rotations are interpreted as increments of each other.

  • degrees (bool, default=True) – By default angle is given in units of [deg]. If degrees=False, angle is given in units of [rad].

Returns

self

Return type

Magpylib object

Examples

>>> import magpylib as magpy
>>> s = magpy.Sensor(position=(1,0,0))

print initial position and orientation >>> print(s.position) >>> print(s.orientation.as_euler(‘xyz’, degrees=True)) [1. 0. 0.] [0. 0. 0.]

rotate and print resulting position and orientation >>> s.rotate_from_angax(45, (0,0,1), anchor=0) >>> print(s.position) >>> print(s.orientation.as_euler(‘xyz’, degrees=True)) [0.70710678 0.70710678 0. ] [ 0. 0. 45.]

rotate_from_euler(seq, angles, anchor=None, start=- 1, increment=False, degrees=False)

Rotates object in the global coordinate system from Euler angle input.

Parameters
  • seq (string) – Specifies sequence of axes for rotations. Up to 3 characters belonging to the set {‘X’, ‘Y’, ‘Z’} for intrinsic rotations, or {‘x’, ‘y’, ‘z’} for extrinsic rotations. Extrinsic and intrinsic rotations cannot be mixed in one function call.

  • angles (float or array_like, shape (N,) or (N, [1 or 2 or 3])) – Euler angles specified in radians (degrees is False) or degrees (degrees is True).

  • anchor (None or array_like, shape (3,), default=None, unit [mm]) – The axis of rotation passes through the anchor point given in units of [mm]. By default (anchor=None) the object will rotate about its own center. anchor=0 rotates the object about the origin (0,0,0).

  • start (int or str, default=-1) – Choose at which index of the original object path, the input path will begin. If start=-1, inp_path will overwrite the last old_path position. If start=0, inp_path will start with the beginning of the old_path. If start=len(old_path) or start=’append’, inp_path will be attached to the old_path.

  • increment (bool, default=False) – If increment=False, input rotations are absolute. If increment=True, input rotations are interpreted as increments of each other.

  • degrees (bool, default False) – If True, then the given angles are assumed to be in degrees.

Returns

self

Return type

Magpylib object

Examples

>>> import magpylib as magpy
>>> s = magpy.Sensor(position=(1,0,0))

print initial position and orientation >>> print(s.position) >>> print(s.orientation.as_euler(‘xyz’, degrees=True)) [1. 0. 0.] [0. 0. 0.]

rotate and print resulting position and orientation >>> s.rotate_from_euler(‘z’, 45, anchor=0, degrees=True) >>> print(s.position) >>> print(s.orientation.as_euler(‘xyz’, degrees=True)) [0.70710678 0.70710678 0. ] [ 0. 0. 45.]

rotate_from_matrix(matrix, anchor=None, start=- 1, increment=False)

Rotates object in the global coordinate system from matrix input. (see scipy rotation package matrix input)

Parameters
  • matrix (array_like, shape (N, 3, 3) or (3, 3)) – A single matrix or a stack of matrices, where matrix[i] is the i-th matrix.

  • anchor (None or array_like, shape (3,), default=None, unit [mm]) – The axis of rotation passes through the anchor point given in units of [mm]. By default (anchor=None) the object will rotate about its own center. anchor=0 rotates the object about the origin (0,0,0).

  • start (int or str, default=-1) – Choose at which index of the original object path, the input path will begin. If start=-1, inp_path will overwrite the last old_path position. If start=0, inp_path will start with the beginning of the old_path. If start=len(old_path) or start=’append’, inp_path will be attached to the old_path.

  • increment (bool, default=False) – If increment=False, input rotations are absolute. If increment=True, input rotations are interpreted as increments of each other.

Returns

self

Return type

Magpylib object

Examples

>>> import magpylib as magpy
>>> s = magpy.Sensor(position=(1,0,0))

print initial position and orientation >>> print(s.position) >>> print(s.orientation.as_matrix()) [1. 0. 0.] [[1. 0. 0.]

[0. 1. 0.] [0. 0. 1.]]

rotate and print resulting position and orientation >>> s.rotate_from_matrix([(0,-1,0),(1,0,0),(0,0,1)], anchor=0) >>> print(s.position) >>> print(s.orientation.as_matrix()) [0. 1. 0.] [[ 0. -1. 0.]

[ 1. 0. 0.] [ 0. 0. 1.]]

rotate_from_mrp(mrp, anchor=None, start=- 1, increment=False)

Rotates object in the global coordinate system from Modified Rodrigues Parameters input. (see scipy rotation package Modified Rodrigues Parameters (MRPs))

Parameters
  • mrp (array_like, shape (N, 3) or (3,)) – A single vector or a stack of vectors, where mrp[i] gives the ith set of MRPs.

  • anchor (None or array_like, shape (3,), default=None, unit [mm]) – The axis of rotation passes through the anchor point given in units of [mm]. By default (anchor=None) the object will rotate about its own center. anchor=0 rotates the object about the origin (0,0,0).

  • start (int or str, default=-1) – Choose at which index of the original object path, the input path will begin. If start=-1, inp_path will overwrite the last old_path position. If start=0, inp_path will start with the beginning of the old_path. If start=len(old_path) or start=’append’, inp_path will be attached to the old_path.

  • increment (bool, default=False) – If increment=False, input rotations are absolute. If increment=True, input rotations are interpreted as increments of each other.

Returns

self

Return type

Magpylib object

Examples

>>> import magpylib as magpy
>>> s = magpy.Sensor(position=(1,0,0))

print initial position and orientation >>> print(s.position) >>> print(s.orientation.as_mrp()) [1. 0. 0.] [0. 0. 0.]

rotate and print resulting position and orientation >>> s.rotate_from_mrp((0,0,1), anchor=0) >>> print(s.position) >>> print(s.orientation.as_mrp()) [-1. 0. 0.] [0. 0. 1.]

rotate_from_quat(quat, anchor=None, start=- 1, increment=False)

Rotates object in the global coordinate system from Quaternion input.

Parameters
  • quat (array_like, shape (N, 4) or (4,)) – Each row is a (possibly non-unit norm) quaternion in scalar-last (x, y, z, w) format. Each quaternion will be normalized to unit norm.

  • anchor (None or array_like, shape (3,), default=None, unit [mm]) – The axis of rotation passes through the anchor point given in units of [mm]. By default (anchor=None) the object will rotate about its own center. anchor=0 rotates the object about the origin (0,0,0).

  • start (int or str, default=-1) – Choose at which index of the original object path, the input path will begin. If start=-1, inp_path will overwrite the last old_path position. If start=0, inp_path will start with the beginning of the old_path. If start=len(old_path) or start=’append’, inp_path will be attached to the old_path.

  • increment (bool, default=False) – If increment=False, input rotations are absolute. If increment=True, input rotations are interpreted as increments of each other.

Returns

self

Return type

Magpylib object

Examples

>>> import magpylib as magpy
>>> s = magpy.Sensor(position=(1,0,0))

print initial position and orientation >>> print(s.position) >>> print(s.orientation.as_quat()) [1. 0. 0.] [0. 0. 0. 1.]

rotate and print resulting position and orientation >>> s.rotate_from_quat((0,0,1,1), anchor=0) >>> print(s.position) >>> print(s.orientation.as_quat()) [0. 1. 0.] [0. 0. 0.70710678 0.70710678]

rotate_from_rotvec(rotvec, anchor=None, start=- 1, increment=False, degrees=False)

Rotates object in the global coordinate system from rotation vector input. (vector direction is the rotation axis, vector length is the rotation angle in [rad])

Parameters
  • rotvec (array_like, shape (N, 3) or (3,)) – A single vector or a stack of vectors, where rot_vec[i] gives the ith rotation vector.

  • anchor (None or array_like, shape (3,), default=None, unit [mm]) – The axis of rotation passes through the anchor point given in units of [mm]. By default (anchor=None) the object will rotate about its own center. anchor=0 rotates the object about the origin (0,0,0).

  • start (int or str, default=-1) – Choose at which index of the original object path, the input path will begin. If start=-1, inp_path will overwrite the last old_path position. If start=0, inp_path will start with the beginning of the old_path. If start=len(old_path) or start=’append’, inp_path will be attached to the old_path.

  • increment (bool, default=False) – If increment=False, input rotations are absolute. If increment=True, input rotations are interpreted as increments of each other.

  • degrees (bool, default False) – If True, then the given angles are assumed to be in degrees.

Returns

self

Return type

Magpylib object

Examples

>>> import magpylib as magpy
>>> s = magpy.Sensor(position=(1,0,0))

print initial position and orientation >>> print(s.position) >>> print(s.orientation.as_rotvec()) [1. 0. 0.] [0. 0. 0.]

rotate and print resulting position and orientation >>> s.rotate_from_rotvec((0,0,1), anchor=0) >>> print(s.position) >>> print(s.orientation.as_rotvec()) [0.54030231 0.84147098 0. ] [0. 0. 1.]

property style

instance of MagpyStyle for display styling options