magpylib.current package

magpylib.current package

This subpackage contains all electric current classes. Currents are modeled as line-currents, input is the current in units of Ampere [A]. Field computation formulas are obtained via the law of Biot-Savardt.

class magpylib.current.Line(current=None, vertices=[(None, None, None), (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, magpylib._src.obj_classes.class_BaseExcitations.BaseCurrent

Current flowing in straight lines from vertex to vertex.

Local object coordinates: The Line current vertices are defined in the local object coordinate system. Local (Line) and global CS coincide when position=(0,0,0) and orientation=unit_rotation.

Parameters
  • current (float) – Electrical current in units of [A].

  • vertices (array_like, shape (N,3)) – The current flows along the vertices which are given in units of [mm] in the local CS of the Line object.

  • 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

Line object

Return type

Line

Examples

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

>>> import magpylib as magpy
>>> magnet = magpy.current.Line(current=100, vertices=[(-1,0,0),(1,0,0)])
>>> print(magnet.position)
[0. 0. 0.]
>>> print(magnet.orientation.as_quat())
[0. 0. 0. 1.]

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

>>> H = magnet.getH((1,1,1))
>>> print(H)
[ 0.         -3.24873667  3.24873667]

or at a set of observer positions:

>>> H = magnet.getH([(1,1,1), (2,2,2), (3,3,3)])
>>> print(H)
[[ 0.         -3.24873667  3.24873667]
 [ 0.         -0.78438229  0.78438229]
 [ 0.         -0.34429579  0.34429579]]

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

>>> magnet.move([(-1,-1,-1), (-2,-2,-2)], start=1)
>>> H = magnet.getH((1,1,1))
>>> print(H)
[[ 0.         -3.24873667  3.24873667]
 [ 0.         -0.78438229  0.78438229]
 [ 0.         -0.34429579  0.34429579]]
_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).

property current

Object current attribute getter and setter.

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

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

property vertices

Object vertices attribute getter and setter.

class magpylib.current.Loop(current=None, diameter=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, magpylib._src.obj_classes.class_BaseExcitations.BaseCurrent

Loop current loop.

Local object coordinates: The Loop current loop lies in the x-y plane of the local object coordinate system, with its center in the origin. Local (Loop) and global CS coincide when position=(0,0,0) and orientation=unit_rotation.

Parameters
  • current (float) – Electrical current in units of [A].

  • diameter (float) – Diameter of the loop in units of [mm].

  • 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

Loop object

Return type

Loop

Examples

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

>>> import magpylib as magpy
>>> magnet = magpy.current.Loop(current=100, diameter=2)
>>> print(magnet.position)
[0. 0. 0.]
>>> print(magnet.orientation.as_quat())
[0. 0. 0. 1.]

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

>>> H = magnet.getH((1,1,1))
>>> print(H)
[4.96243034 4.96243034 2.12454191]

or at a set of observer positions:

>>> H = magnet.getH([(1,1,1), (2,2,2), (3,3,3)])
>>> print(H)
[[4.96243034 4.96243034 2.12454191]
 [0.61894364 0.61894364 0.06167939]
 [0.18075829 0.18075829 0.00789697]]

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

>>> magnet.move([(-1,-1,-1), (-2,-2,-2)], start=1)
>>> H = magnet.getH((1,1,1))
>>> print(H)
[[4.96243034 4.96243034 2.12454191]
 [0.61894364 0.61894364 0.06167939]
 [0.18075829 0.18075829 0.00789697]]
_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).

property current

Object current attribute getter and setter.

property diameter

Object diameter attribute getter and setter.

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

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