magpylib.misc package¶

This sub-package contains miscellaneous source objects.

class magpylib.misc.Dipole(moment=(None, None, None), position=(0, 0, 0), orientation=None)[source]¶

Bases: magpylib._lib.obj_classes.class_BaseGeo.BaseGeo, magpylib._lib.obj_classes.class_BaseDisplayRepr.BaseDisplayRepr, magpylib._lib.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 [mTmm^3]) – Magnetic dipole moment in units of [mTmm^3] given in the local CS. For homogeneous magnets there is a relation moment=magnetizationvolume. 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 mag3
>>> dipole = mag3.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 ]]

display(markers=[(0, 0, 0)], axis=None, show_direction=False, show_path=True, size_sensors=1, size_direction=1, size_dipoles=1)¶

Display object graphically using matplotlib 3D plotting.

Parameters:	markers (array_like, shape (N,3), default=[(0,0,0)]) – Display position markers in the global CS. By default a marker is placed in the origin. axis (pyplot.axis, default=None) – Display graphical output in a given pyplot axis (must be 3D). By default a new pyplot figure is created and displayed. show_direction (bool, default=False) – Set True to show magnetization and current directions. show_path (bool or int, default=True) – Options True, False, positive int. By default object paths are shown. If show_path is a positive integer, objects will be displayed at multiple path positions along the path, in steps of show_path. size_sensor (float, default=1) – Adjust automatic display size of sensors. size_direction (float, default=1) – Adjust automatic display size of direction arrows. size_dipoles (float, default=1) – Adjust automatic display size of dipoles.
Returns:	None
Return type:	NoneType

Examples

Display Magpylib objects graphically using Matplotlib:

>>> import magpylib as mag3
>>> obj = mag3.magnet.Sphere(magnetization=(0,0,1), diameter=1)
>>> obj.move([(.2,0,0)]*50, increment=True)
>>> obj.rotate_from_angax(angle=[10]*50, axis='z', anchor=0, start=0, increment=True)
>>> obj.display(show_direction=True, show_path=10)
--> graphic output

Display figure on your own 3D Matplotlib axis:

>>> import matplotlib.pyplot as plt
>>> import magpylib as mag3
>>> my_axis = plt.axes(projection='3d')
>>> obj = mag3.magnet.Box(magnetization=(0,0,1), dimension=(1,2,3))
>>> obj.move([(x,0,0) for x in [0,1,2,3,4,5]])
>>> obj.display(axis=my_axis)
>>> plt.show()
--> 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

Compute the B-field [mT] at a sensor directly through the source method:

>>> import magpylib as mag3
>>> source = mag3.magnet.Sphere(magnetization=(1000,0,0), diameter=1)
>>> sensor = mag3.Sensor(position=(1,2,3))
>>> B = source.getB(sensor)
>>> print(B)
[-0.62497314  0.34089444  0.51134166]

Compute the B-field [mT] of a source at five path positions as seen by an observer at position (1,2,3):

>>> import magpylib as mag3
>>> source = mag3.magnet.Sphere(magnetization=(1000,0,0), diameter=1)
>>> source.move([(x,0,0) for x in [1,2,3,4,5]])
>>> B = source.getB((1,2,3))
>>> print(B)
[[-0.88894262  0.          0.        ]
[-0.62497314 -0.34089444 -0.51134166]
[-0.17483825 -0.41961181 -0.62941771]
[ 0.09177028 -0.33037301 -0.49555952]
[ 0.17480239 -0.22080302 -0.33120453]]

Compute the B-field [mT] of a source at two sensors:

>>> import magpylib as mag3
>>> source = mag3.current.Circular(current=15, diameter=1)
>>> sens1 = mag3.Sensor(position=(1,2,3))
>>> sens2 = mag3.Sensor(position=(2,3,4))
>>> B = source.getB(sens1, sens2)
>>> print(B)
[[0.01421427 0.02842853 0.02114728]
[0.00621368 0.00932052 0.00501254]]

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

Compute the H-field [kA/m] at a sensor directly through the source method:

>>> import magpylib as mag3
>>> source = mag3.magnet.Sphere(magnetization=(1000,0,0), diameter=1)
>>> sensor = mag3.Sensor(position=(1,2,3))
>>> H = source.getH(sensor)
>>> print(H)
[-0.49733782  0.27127518  0.40691277]

Compute the H-field [kA/m] of a source at five path positions as seen by an observer at position (1,2,3):

>>> import magpylib as mag3
>>> source = mag3.magnet.Sphere(magnetization=(1000,0,0), diameter=1)
>>> source.move([(x,0,0) for x in [1,2,3,4,5]])
>>> H = source.getH((1,2,3))
>>> print(H)
[[-0.70739806  0.          0.        ]
[-0.49733782 -0.27127518 -0.40691277]
[-0.13913186 -0.33391647 -0.5008747 ]
[ 0.07302847 -0.26290249 -0.39435373]
[ 0.13910332 -0.17570946 -0.26356419]]

Compute the H-field [kA/m] of a source at two sensors:

>>> import magpylib as mag3
>>> source = mag3.current.Circular(current=15, diameter=1)
>>> sens1 = mag3.Sensor(position=(1,2,3))
>>> sens2 = mag3.Sensor(position=(2,3,4))
>>> H = source.getH(sens1, sens2)
>>> print(H)
[[0.01131135 0.02262271 0.01682847]
[0.00494469 0.00741704 0.00398885]]

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 mag3
>>> sensor = mag3.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 mag3
>>> sensor = mag3.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 mag3
>>> sensor = mag3.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]]

orientation¶: Object orientation attribute getter and setter.

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 mag3
>>> obj = mag3.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 the object in the global coordinate system by a given rotation input (can be a path).

This method applies given rotations to the original orientation. If the input path extends beyond the existing path, the old path will be padded by its last entry before paths are added up.

Parameters:	rotation (scipy Rotation object) – Rotation to be applied. The rotation object can feature a single rotation of shape (3,) or a set of rotations of shape (N,3) that correspond to a path. 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 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 rotations are absolute. If increment=True, input rotations are interpreted as increments of each other.
Returns:	self
Return type:	Magpylib object

Examples

With the rotate method Magpylib objects can be rotated about their local coordinate system center:

>>> import magpylib as mag3
>>> from scipy.spatial.transform import Rotation as R
>>> sensor = mag3.Sensor()
>>> print(sensor.position)
[0. 0. 0.]
>>> print(sensor.orientation.as_euler('xyz'))
[0. 0. 0.]
>>> rotation_object = R.from_euler('x', 45, degrees=True)
>>> sensor.rotate(rotation_object)
>>> print(sensor.position)
[0. 0. 0.]
>>> print(sensor.orientation.as_euler('xyz', degrees=True))
[45.  0.  0.]

With the anchor keyword the object rotates about a designated axis that passes through the given anchor point:

>>> import magpylib as mag3
>>> from scipy.spatial.transform import Rotation as R
>>> sensor = mag3.Sensor()
>>> rotation_object = R.from_euler('x', 90, degrees=True)
>>> sensor.rotate(rotation_object, anchor=(0,1,0))
>>> print(sensor.position)
[ 0.  1. -1.]
>>> print(sensor.orientation.as_euler('xyz', degrees=True))
[90.  0.  0.]

The method can also be used to generate paths, making use of scipy.Rotation object vector input:

>>> import magpylib as mag3
>>> from scipy.spatial.transform import Rotation as R
>>> sensor = mag3.Sensor()
>>> rotation_object = R.from_euler('x', 90, degrees=True)
>>> sensor.rotate(rotation_object, anchor=(0,1,0), start='append')
>>> print(sensor.position)
[[ 0.  0.  0.]
 [ 0.  1. -1.]]
>>> print(sensor.orientation.as_euler('xyz', degrees=True))
[[ 0.  0.  0.]
 [90.  0.  0.]]
>>> rotation_object = R.from_euler('x', [10,20,30], degrees=True)
>>> sensor.rotate(rotation_object, anchor=(0,1,0), start='append')
>>> print(sensor.position)
[[ 0.          0.          0.        ]
 [ 0.          1.         -1.        ]
 [ 0.          1.17364818 -0.98480775]
 [ 0.          1.34202014 -0.93969262]
 [ 0.          1.5        -0.8660254 ]]
>>> print(sensor.orientation.as_euler('xyz', degrees=True))
[[  0.   0.   0.]
 [ 90.   0.   0.]
 [100.   0.   0.]
 [110.   0.   0.]
 [120.   0.   0.]]

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

>>> import magpylib as mag3
>>> from scipy.spatial.transform import Rotation as R
>>> sensor = mag3.Sensor()
>>> rotation_object = R.from_euler('x', [10]*3, degrees=True)
>>> sensor.rotate(rotation_object, anchor=(0,1,0), start='append', increment=True)
>>> print(sensor.position)
[[ 0.          0.          0.        ]
 [ 0.          0.01519225 -0.17364818]
 [ 0.          0.06030738 -0.34202014]
 [ 0.          0.1339746  -0.5       ]]
>>> print(sensor.orientation.as_euler('xyz', degrees=True))
[[ 0.  0.  0.]
 [10.  0.  0.]
 [20.  0.  0.]
 [30.  0.  0.]]
>>> rotation_object = R.from_euler('z', [5]*4, degrees=True)
>>> sensor.rotate(rotation_object, anchor=0, start=0, increment=True)
>>> print(sensor.position)
[[ 0.          0.          0.        ]
 [-0.00263811  0.01496144 -0.17364818]
 [-0.0156087   0.05825246 -0.34202014]
 [-0.04582201  0.12589494 -0.5       ]]
>>> print(sensor.orientation.as_euler('xyz', degrees=True))
[[ 0.  0.  5.]
 [10.  0. 10.]
 [20.  0. 15.]
 [30.  0. 20.]]

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

Object rotation in the global coordinate system from angle-axis input.

This method applies given rotations to the original orientation. If the input path extends beyond the existingp path, the oldpath will be padded by its last entry before paths are added up.

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 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 rotations are absolute. If increment=True, input rotations are interpreted as increments of each other. For example, the incremental angles [1,1,1,2,2] correspond to the absolute angles [1,2,3,5,7]. 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

With the rotate_from_angax method Magpylib objects can be rotated about their local coordinte system center:

>>> import magpylib as mag3
>>> sensor = mag3.Sensor()
>>> print(sensor.position)
[0. 0. 0.]
>>> print(sensor.orientation.as_euler('xyz'))
[0. 0. 0.]
>>> sensor.rotate_from_angax(angle=45, axis='x')
>>> print(sensor.position)
[0. 0. 0.]
>>> print(sensor.orientation.as_euler('xyz', degrees=True))
[45.  0.  0.]

With the anchor keyword the object rotates about a designated axis that passes through the given anchor point:

>>> import magpylib as mag3
>>> sensor = mag3.Sensor()
>>> sensor.rotate_from_angax(angle=90, axis=(1,0,0), anchor=(0,1,0))
>>> print(sensor.position)
[ 0.  1. -1.]
>>> print(sensor.orientation.as_euler('xyz', degrees=True))
[90.  0.  0.]

The method can also be used to generate paths, making use of scipy.Rotation object vector input:

>>> import magpylib as mag3
>>> sensor = mag3.Sensor()
>>> sensor.rotate_from_angax(angle=90, axis='x', anchor=(0,1,0), start='append')
>>> print(sensor.position)
[[ 0.  0.  0.]
 [ 0.  1. -1.]]
>>> print(sensor.orientation.as_euler('xyz', degrees=True))
[[ 0.  0.  0.]
 [90.  0.  0.]]
>>> sensor.rotate_from_angax(angle=[10,20,30], axis='x', anchor=(0,1,0), start='append')
>>> print(sensor.position)
[[ 0.          0.          0.        ]
 [ 0.          1.         -1.        ]
 [ 0.          1.17364818 -0.98480775]
 [ 0.          1.34202014 -0.93969262]
 [ 0.          1.5        -0.8660254 ]]
>>> print(sensor.orientation.as_euler('xyz', degrees=True))
[[  0.   0.   0.]
 [ 90.   0.   0.]
 [100.   0.   0.]
 [110.   0.   0.]
 [120.   0.   0.]]

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

>>> import magpylib as mag3
>>> sensor = mag3.Sensor()
>>> sensor.rotate_from_angax([10]*3, 'x', (0,1,0), start=1, increment=True)
>>> print(sensor.position)
[[ 0.          0.          0.        ]
 [ 0.          0.01519225 -0.17364818]
 [ 0.          0.06030738 -0.34202014]
 [ 0.          0.1339746  -0.5       ]]
>>> print(sensor.orientation.as_euler('xyz', degrees=True))
[[ 0.  0.  0.]
 [10.  0.  0.]
 [20.  0.  0.]
 [30.  0.  0.]]
>>> sensor.rotate_from_angax(angle=[5]*4, axis='z', anchor=0, start=0, increment=True)
>>> print(sensor.position)
[[ 0.          0.          0.        ]
 [-0.00263811  0.01496144 -0.17364818]
 [-0.0156087   0.05825246 -0.34202014]
 [-0.04582201  0.12589494 -0.5       ]]
>>> print(sensor.orientation.as_euler('xyz', degrees=True))
[[ 0.  0.  5.]
 [10.  0. 10.]
 [20.  0. 15.]
 [30.  0. 20.]]