magpylib.magnet package#
The magpylib.magnet subpackage contains all magnet classes.
- class magpylib.magnet.Cuboid(magnetization=None, dimension=None, position=(0, 0, 0), orientation=None, style=None, **kwargs)#
Bases:
BaseMagnetCuboid magnet with homogeneous magnetization.
Can be used as sources input for magnetic field computation.
When position=(0,0,0) and orientation=None the Cuboid sides are parallel to the global coordinate basis vectors and the geometric center of the Cuboid is located in the origin.
Units can be chosen freely. B-field output unit is the same as magnetization input unit. Computation is independend of Length-unit. See online documentation for fore information
- Parameters
magnetization (array_like, shape (3,), default=`None`) – Magnetization (polarization) vector (mu0*M, remanence field) in arbitrary units given in the local object coordinates (rotates with object).
dimension (array_like, shape (3,), default=`None`) – Length of the cuboid sides [a,b,c] in arbitrary units.
position (array_like, shape (3,) or (m,3), default=`(0,0,0)`) – Object position(s) in the global coordinates in arbitrary units. For m>1, the position and orientation attributes together represent an object path.
orientation (scipy Rotation object with length 1 or m, default=`None`) – Object orientation(s) in the global coordinates. None corresponds to a unit-rotation. For m>1, the position and orientation attributes together represent an object path.
parent (Collection object or None) – The object is a child of it’s parent collection.
style (dict) – Object style inputs must be in dictionary form, e.g. {‘color’:’red’} or using style underscore magic, e.g. style_color=’red’.
- Returns
magnet source
- Return type
Cuboid object
Examples
Cuboid magnets are magnetic field sources. Below we compute the H-field in kA/m of a cubical magnet with magnetization (100,200,300) in units of mT and 1 mm sides at the observer position (1,1,1) given in units of mm:
>>> import magpylib as magpy >>> src = magpy.magnet.Cuboid(magnetization=(100,200,300), dimension=(1,1,1)) >>> H = src.getH((1,1,1)) >>> print(H) [6.21116976 4.9689358 3.72670185]
We rotate the source object, and compute the B-field, this time at a set of observer positions:
>>> src.rotate_from_angax(45, 'x') Cuboid(id=...) >>> B = src.getB([(1,1,1), (2,2,2), (3,3,3)]) >>> print(B) [[4.30496934 6.9363475 0.50728577] [0.54127889 0.86827283 0.05653357] [0.1604214 0.25726266 0.01664045]]
The same result is obtained when the rotated source moves along a path away from an observer at position (1,1,1). Here we use a Sensor object as observer.
>>> sens = magpy.Sensor(position=(1,1,1)) >>> src.move([(-1,-1,-1), (-2,-2,-2)]) Cuboid(id=...) >>> B = src.getB(sens) >>> print(B) [[4.30496934 6.9363475 0.50728577] [0.54127889 0.86827283 0.05653357] [0.1604214 0.25726266 0.01664045]]
- copy(**kwargs)#
Returns a copy of the current object instance. The copy method returns a deep copy of the object, that is independent of the original object.
- Parameters
kwargs (dict) – Keyword arguments (for example position=(1,2,3)) are applied to the copy.
Examples
Create a Sensor object and copy to an another position:
>>> import magpylib as magpy >>> sens1 = magpy.Sensor(style_label='sens1') >>> sens2 = sens1.copy(position=(2,6,10), style_label='sens2') >>> print(f"Instance {sens1.style.label} with position {sens1.position}.") Instance sens1 with position [0. 0. 0.]. >>> print(f"Instance {sens2.style.label} with position {sens2.position}.") Instance sens2 with position [ 2. 6. 10.].
- describe(*, exclude=('style', 'field_func'), return_string=False)#
Returns a view of the object properties.
- Parameters
exclude (bool, default=("style",)) – Properties to be excluded in the description view.
return_string (bool, default=`False`) – If False print description with stdout, if True return as string.
- property dimension#
Length of the cuboid sides [a,b,c] in units of mm.
- property field_func#
The function for B- and H-field computation must have the two positional arguments field and observers. With field=’B’ or field=’H’ the B- or H-field in units of mT or kA/m must be returned respectively. The observers argument must accept numpy ndarray inputs of shape (n,3), in which case the returned fields must be numpy ndarrays of shape (n,3) themselves.
- getB(*observers, squeeze=True, pixel_agg=None, output='ndarray')#
Compute the B-field in units of mT generated by the source.
- Parameters
observers (array_like or (list of) Sensor objects) – Can be array_like positions of shape (n1, n2, …, 3) where the field should be evaluated, a Sensor object with pixel shape (n1, n2, …, 3) or a list of such sensor objects (must all have similar pixel shapes). All positions are given in units of mm.
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.
pixel_agg (str, default=`None`) – Reference to a compatible numpy aggregator function like ‘min’ or ‘mean’, which is applied to observer output values, e.g. mean of all sensor pixel outputs. With this option, observers input with different (pixel) shapes is allowed.
output (str, default='ndarray') – Output type, which must be one of (‘ndarray’, ‘dataframe’). By default a multi- dimensional array (‘ndarray’) is returned. If ‘dataframe’ is chosen, the function returns a 2D-table as a pandas.DataFrame object (the Pandas library must be installed).
- 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) or DataFrame
Examples
Compute the B-field of a spherical magnet at three positions:
>>> import magpylib as magpy >>> src = magpy.magnet.Sphere((0,0,1000), 1) >>> B = src.getB(((0,0,0), (1,0,0), (2,0,0))) >>> print(B) [[ 0. 0. 666.66666667] [ 0. 0. -41.66666667] [ 0. 0. -5.20833333]]
Compute the B-field at two sensors, each one with two pixels
>>> sens1 = magpy.Sensor(position=(1,0,0), pixel=((0,0,.1), (0,0,-.1))) >>> sens2 = sens1.copy(position=(2,0,0)) >>> B = src.getB(sens1, sens2) >>> print(B) [[[ 12.19288783 0. -39.83010025] [-12.19288783 0. -39.83010025]] [[ 0.77638847 0. -5.15004352] [ -0.77638847 0. -5.15004352]]]
- getH(*observers, squeeze=True, pixel_agg=None, output='ndarray')#
Compute the H-field in units of kA/m generated by the source.
- Parameters
observers (array_like or (list of) Sensor objects) – Can be array_like positions of shape (n1, n2, …, 3) where the field should be evaluated, a Sensor object with pixel shape (n1, n2, …, 3) or a list of such sensor objects (must all have similar pixel shapes). All positions are given in units of mm.
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.
pixel_agg (str, default=`None`) – Reference to a compatible numpy aggregator function like ‘min’ or ‘mean’, which is applied to observer output values, e.g. mean of all sensor pixel outputs. With this option, observers input with different (pixel) shapes is allowed.
output (str, default='ndarray') – Output type, which must be one of (‘ndarray’, ‘dataframe’). By default a multi- dimensional array (‘ndarray’) is returned. If ‘dataframe’ is chosen, the function returns a 2D-table as a pandas.DataFrame object (the Pandas library must be installed).
- 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) or DataFrame
Examples
Compute the H-field of a spherical magnet at three positions:
>>> import magpylib as magpy
>>> src = magpy.magnet.Sphere((0,0,1000), 1) >>> H = src.getH(((0,0,0), (1,0,0), (2,0,0))) >>> print(H) [[ 0. 0. -265.25823849] [ 0. 0. -33.15727981] [ 0. 0. -4.14465998]]
Compute the H-field at two sensors, each one with two pixels
>>> sens1 = magpy.Sensor(position=(1,0,0), pixel=((0,0,.1), (0,0,-.1))) >>> sens2 = sens1.copy(position=(2,0,0)) >>> H = src.getH(sens1, sens2) >>> print(H) [[[ 9.70279185 0. -31.69578669] [ -9.70279185 0. -31.69578669]] [[ 0.61783031 0. -4.09827441] [ -0.61783031 0. -4.09827441]]]
- get_trace(**kwargs) Dict[str, Any]#
Create the plotly mesh3d parameters for a Cuboid Magnet in a dictionary based on the provided arguments.
- property magnetization#
Object magnetization attribute getter and setter.
- move(displacement, start='auto')#
Move object by the displacement input.
Terminology for move/rotate methods:
path refers to position and orientation of an object.
When an input is just a single operation (e.g. one displacement vector or one angle) we call it ‘scalar input’. When it is an array_like of multiple scalars, we refer to it as ‘vector input’.
General move/rotate behavior:
Scalar input is applied to the whole object path, starting with path index start.
Vector input of length n applies the individual n operations to n object path entries, starting with path index start.
When an input extends beyond the object path, the object path will be padded by its edge-entries before the operation is applied.
By default (start=’auto’) the index is set to start=0 for scalar input [=move whole object path], and to start=len(object path) for vector input [=append to existing object path].
- Parameters
displacement (array_like, shape (3,) or (n,3)) – Displacement vector in units of mm.
start (int or str, default=`'auto'`) – Starting index when applying operations. See ‘General move/rotate behavior’ above for details.
- Returns
self
- Return type
Magpylib object
Examples
Move objects around with scalar input:
>>> import magpylib as magpy >>> sens = magpy.Sensor(position=(1,1,1)) >>> print(sens.position) [1. 1. 1.] >>> sens.move((1,1,1)) Sensor(id=...) >>> print(sens.position) [2. 2. 2.]
Create len>1 object paths with vector input:
>>> sens.move([(1,1,1),(2,2,2),(3,3,3)]) Sensor(id=...) >>> print(sens.position) [[2. 2. 2.] [3. 3. 3.] [4. 4. 4.] [5. 5. 5.]]
Apply operations starting with a designated path index:
>>> sens.move((0,0,2), start=2) Sensor(id=...) >>> print(sens.position) [[2. 2. 2.] [3. 3. 3.] [4. 4. 6.] [5. 5. 7.]]
- property orientation#
Object orientation(s) in the global coordinates. None corresponds to a unit-rotation. For m>1, the position and orientation attributes together represent an object path.
- property parent#
The object is a child of it’s parent collection.
- property position#
Object position(s) in the global coordinates in units of mm. For m>1, the position and orientation attributes together represent an object path.
- reset_path()#
Set object position to (0,0,0) and orientation = unit rotation.
- Returns
self
- Return type
magpylib object
Examples
Demonstration of reset_path functionality:
>>> import magpylib as magpy >>> obj = magpy.Sensor(position=(1,2,3)) >>> obj.rotate_from_angax(45, 'z') Sensor... >>> print(obj.position) [1. 2. 3.] >>> print(obj.orientation.as_euler('xyz', degrees=True)) [ 0. 0. 45.]
>>> obj.reset_path() Sensor(id=...) >>> print(obj.position) [0. 0. 0.] >>> print(obj.orientation.as_euler('xyz', degrees=True)) [0. 0. 0.]
- rotate(rotation: Rotation, anchor=None, start='auto')#
Rotate object about a given anchor.
Terminology for move/rotate methods:
path refers to position and orientation of an object.
When an input is just a single operation (e.g. one displacement vector or one angle) we call it ‘scalar input’. When it is an array_like of multiple scalars, we refer to it as ‘vector input’.
General move/rotate behavior:
Scalar input is applied to the whole object path, starting with path index start.
Vector input of length n applies the individual n operations to n object path entries, starting with path index start.
When an input extends beyond the object path, the object path will be padded by its edge-entries before the operation is applied.
By default (start=’auto’) the index is set to start=0 for scalar input [=move whole object path], and to start=len(object path) for vector input [=append to existing object path].
- Parameters
rotation (None or scipy Rotation object) – Rotation to be applied to the object. The scipy Rotation input can be scalar or vector type (see terminology above). None input is interpreted as unit rotation.
anchor (None, 0 or array_like with shape (3,) or (n,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=`'auto'`) – Starting index when applying operations. See ‘General move/rotate behavior’ above for details.
- Returns
self
- Return type
Magpylib object
Examples
Rotate an object about the origin:
>>> from scipy.spatial.transform import Rotation as R >>> import magpylib as magpy >>> sens = magpy.Sensor(position=(1,0,0)) >>> sens.rotate(R.from_euler('z', 45, degrees=True), anchor=0) Sensor(id=...) >>> print(sens.position) [0.70710678 0.70710678 0. ] >>> print(sens.orientation.as_euler('xyz', degrees=True)) [ 0. 0. 45.]
Rotate the object about itself:
>>> sens.rotate(R.from_euler('z', 45, degrees=True)) Sensor(id=...) >>> print(sens.position) [0.70710678 0.70710678 0. ] >>> print(sens.orientation.as_euler('xyz', degrees=True)) [ 0. 0. 90.]
Create a rotation path by rotating in several steps about an anchor:
>>> sens.rotate(R.from_euler('z', (15,30,45), degrees=True), anchor=(0,0,0)) Sensor(id=...) >>> print(sens.position) [[ 7.07106781e-01 7.07106781e-01 0.00000000e+00] [ 5.00000000e-01 8.66025404e-01 0.00000000e+00] [ 2.58819045e-01 9.65925826e-01 0.00000000e+00] [-2.22044605e-16 1.00000000e+00 0.00000000e+00]] >>> print(sens.orientation.as_euler('xyz', degrees=True)) [[ 0. 0. 90.] [ 0. 0. 105.] [ 0. 0. 120.] [ 0. 0. 135.]]
- rotate_from_angax(angle, axis, anchor=None, start='auto', degrees=True)#
Rotates object using angle-axis input.
Terminology for move/rotate methods:
path refers to position and orientation of an object.
When an input is just a single operation (e.g. one displacement vector or one angle) we call it ‘scalar input’. When it is an array_like of multiple scalars, we refer to it as ‘vector input’.
General move/rotate behavior:
Scalar input is applied to the whole object path, starting with path index start.
Vector input of length n applies the individual n operations to n object path entries, starting with path index start.
When an input extends beyond the object path, the object path will be padded by its edge-entries before the operation is applied.
By default (start=’auto’) the index is set to start=0 for scalar input [=move whole object path], and to start=len(object path) for vector input [=append to existing object path].
- Parameters
angle (int, float or array_like with shape (n,)) – Angle(s) of rotation 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, 0 or array_like with shape (3,) or (n,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=`'auto'`) – Starting index when applying operations. See ‘General move/rotate behavior’ above for details.
degrees (bool, default=`True`) – Interpret input in units of deg or rad.
- Returns
self
- Return type
Magpylib object
Examples
Rotate an object about the origin:
>>> import magpylib as magpy >>> sens = magpy.Sensor(position=(1,0,0)) >>> sens.rotate_from_angax(45, axis='z', anchor=0) Sensor(id=...) >>> print(sens.position) [0.70710678 0.70710678 0. ] >>> print(sens.orientation.as_euler('xyz', degrees=True)) [ 0. 0. 45.]
Rotate the object about itself:
>>> sens.rotate_from_angax(45, axis=(0,0,1)) Sensor(id=...) >>> print(sens.position) [0.70710678 0.70710678 0. ] >>> print(sens.orientation.as_euler('xyz', degrees=True)) [ 0. 0. 90.]
Create a rotation path by rotating in several steps about an anchor:
>>> sens.rotate_from_angax((15,30,45), axis='z', anchor=(0,0,0)) Sensor(id=...) >>> print(sens.position) [[ 7.07106781e-01 7.07106781e-01 0.00000000e+00] [ 5.00000000e-01 8.66025404e-01 0.00000000e+00] [ 2.58819045e-01 9.65925826e-01 0.00000000e+00] [-2.22044605e-16 1.00000000e+00 0.00000000e+00]] >>> print(sens.orientation.as_euler('xyz', degrees=True)) [[ 0. 0. 90.] [ 0. 0. 105.] [ 0. 0. 120.] [ 0. 0. 135.]]
- rotate_from_euler(angle, seq, anchor=None, start='auto', degrees=True)#
Rotates object using Euler angle input.
Terminology for move/rotate methods:
path refers to position and orientation of an object.
When an input is just a single operation (e.g. one displacement vector or one angle) we call it ‘scalar input’. When it is an array_like of multiple scalars, we refer to it as ‘vector input’.
General move/rotate behavior:
Scalar input is applied to the whole object path, starting with path index start.
Vector input of length n applies the individual n operations to n object path entries, starting with path index start.
When an input extends beyond the object path, the object path will be padded by its edge-entries before the operation is applied.
By default (start=’auto’) the index is set to start=0 for scalar input [=move whole object path], and to start=len(object path) for vector input [=append to existing object path].
- Parameters
angle (int, float or array_like with shape (n,)) – Angle(s) of rotation in units of deg (by default).
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.
anchor (None, 0 or array_like with shape (3,) or (n,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=`'auto'`) – Starting index when applying operations. See ‘General move/rotate behavior’ above for details.
degrees (bool, default=`True`) – Interpret input in units of deg or rad.
- Returns
self
- Return type
Magpylib object
Examples
Rotate an object about the origin:
>>> import magpylib as magpy >>> sens = magpy.Sensor(position=(1,0,0)) >>> sens.rotate_from_euler(45, 'z', anchor=0) Sensor... >>> print(sens.position) [0.70710678 0.70710678 0. ] >>> print(sens.orientation.as_euler('xyz', degrees=True)) [ 0. 0. 45.]
Rotate the object about itself:
>>> sens.rotate_from_euler(45, 'z') Sensor(id=...) >>> print(sens.position) [0.70710678 0.70710678 0. ] >>> print(sens.orientation.as_euler('xyz', degrees=True)) [ 0. 0. 90.]
Create a rotation path by rotating in several steps about an anchor:
>>> sens.rotate_from_euler((15,30,45), 'z', anchor=(0,0,0)) Sensor(id=...) >>> print(sens.position) [[ 7.07106781e-01 7.07106781e-01 0.00000000e+00] [ 5.00000000e-01 8.66025404e-01 0.00000000e+00] [ 2.58819045e-01 9.65925826e-01 0.00000000e+00] [-2.22044605e-16 1.00000000e+00 0.00000000e+00]] >>> print(sens.orientation.as_euler('xyz', degrees=True)) [[ 0. 0. 90.] [ 0. 0. 105.] [ 0. 0. 120.] [ 0. 0. 135.]]
- rotate_from_matrix(matrix, anchor=None, start='auto')#
Rotates object using matrix input.
Terminology for move/rotate methods:
path refers to position and orientation of an object.
When an input is just a single operation (e.g. one displacement vector or one angle) we call it ‘scalar input’. When it is an array_like of multiple scalars, we refer to it as ‘vector input’.
General move/rotate behavior:
Scalar input is applied to the whole object path, starting with path index start.
Vector input of length n applies the individual n operations to n object path entries, starting with path index start.
When an input extends beyond the object path, the object path will be padded by its edge-entries before the operation is applied.
By default (start=’auto’) the index is set to start=0 for scalar input [=move whole object path], and to start=len(object path) for vector input [=append to existing object path].
- Parameters
matrix (array_like, shape (n,3,3) or (3,3)) – Rotation input. See scipy.spatial.transform.Rotation for details.
anchor (None, 0 or array_like with shape (3,) or (n,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=`'auto'`) – Starting index when applying operations. See ‘General move/rotate behavior’ above for details.
- Returns
self
- Return type
Magpylib object
Examples
Rotate an object about the origin:
>>> import magpylib as magpy >>> sens = magpy.Sensor(position=(1,0,0)) >>> sens.rotate_from_matrix([(0,-1,0),(1,0,0),(0,0,1)], anchor=0) Sensor(id=...) >>> print(sens.position) [0. 1. 0.] >>> print(sens.orientation.as_euler('xyz', degrees=True)) [ 0. 0. 90.]
Rotate the object about itself:
>>> sens.rotate_from_matrix([(0,-1,0),(1,0,0),(0,0,1)]) Sensor(id=...) >>> print(sens.position) [0. 1. 0.] >>> print(sens.orientation.as_euler('xyz', degrees=True)) [ 0. 0. 180.]
- rotate_from_mrp(mrp, anchor=None, start='auto')#
Rotates object using Modified Rodrigues Parameters (MRPs) input.
Terminology for move/rotate methods:
path refers to position and orientation of an object.
When an input is just a single operation (e.g. one displacement vector or one angle) we call it ‘scalar input’. When it is an array_like of multiple scalars, we refer to it as ‘vector input’.
General move/rotate behavior:
Scalar input is applied to the whole object path, starting with path index start.
Vector input of length n applies the individual n operations to n object path entries, starting with path index start.
When an input extends beyond the object path, the object path will be padded by its edge-entries before the operation is applied.
By default (start=’auto’) the index is set to start=0 for scalar input [=move whole object path], and to start=len(object path) for vector input [=append to existing object path].
- Parameters
mrp (array_like, shape (n,3) or (3,)) – Rotation input. See scipy Rotation package for details on Modified Rodrigues Parameters (MRPs).
anchor (None, 0 or array_like with shape (3,) or (n,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=`'auto'`) – Starting index when applying operations. See ‘General move/rotate behavior’ above for details.
- Returns
self
- Return type
Magpylib object
Examples
Rotate an object about the origin:
>>> import magpylib as magpy >>> sens = magpy.Sensor(position=(1,0,0)) >>> sens.rotate_from_mrp((0,0,1), anchor=0) Sensor(id=...) >>> print(sens.position) [-1. 0. 0.] >>> print(sens.orientation.as_euler('xyz', degrees=True)) [ 0. 0. 180.]
Rotate the object about itself:
>>> sens.rotate_from_matrix([(0,-1,0),(1,0,0),(0,0,1)]) Sensor(id=...) >>> print(sens.position) [-1. 0. 0.] >>> print(sens.orientation.as_euler('xyz', degrees=True)) [ 0. 0. -90.]
- rotate_from_quat(quat, anchor=None, start='auto')#
Rotates object using quaternion input.
Terminology for move/rotate methods:
path refers to position and orientation of an object.
When an input is just a single operation (e.g. one displacement vector or one angle) we call it ‘scalar input’. When it is an array_like of multiple scalars, we refer to it as ‘vector input’.
General move/rotate behavior:
Scalar input is applied to the whole object path, starting with path index start.
Vector input of length n applies the individual n operations to n object path entries, starting with path index start.
When an input extends beyond the object path, the object path will be padded by its edge-entries before the operation is applied.
By default (start=’auto’) the index is set to start=0 for scalar input [=move whole object path], and to start=len(object path) for vector input [=append to existing object path].
- Parameters
quat (array_like, shape (n,4) or (4,)) – Rotation input in quaternion form.
anchor (None, 0 or array_like with shape (3,) or (n,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=`'auto'`) – Starting index when applying operations. See ‘General move/rotate behavior’ above for details.
- Returns
self
- Return type
Magpylib object
Examples
Rotate an object about the origin:
>>> import magpylib as magpy >>> sens = magpy.Sensor(position=(1,0,0)) >>> sens.rotate_from_quat((0,0,1,1), anchor=0) Sensor(id=...) >>> print(sens.position) [0. 1. 0.] >>> print(sens.orientation.as_euler('xyz', degrees=True)) [ 0. 0. 90.]
Rotate the object about itself:
>>> sens.rotate_from_quat((0,0,1,1)) Sensor(id=...) >>> print(sens.position) [0. 1. 0.] >>> print(sens.orientation.as_euler('xyz', degrees=True)) [ 0. 0. 180.]
- rotate_from_rotvec(rotvec, anchor=None, start='auto', degrees=True)#
Rotates object using rotation vector input.
Terminology for move/rotate methods:
path refers to position and orientation of an object.
When an input is just a single operation (e.g. one displacement vector or one angle) we call it ‘scalar input’. When it is an array_like of multiple scalars, we refer to it as ‘vector input’.
General move/rotate behavior:
Scalar input is applied to the whole object path, starting with path index start.
Vector input of length n applies the individual n operations to n object path entries, starting with path index start.
When an input extends beyond the object path, the object path will be padded by its edge-entries before the operation is applied.
By default (start=’auto’) the index is set to start=0 for scalar input [=move whole object path], and to start=len(object path) for vector input [=append to existing object path].
- Parameters
rotvec (array_like, shape (n,3) or (3,)) – Rotation input. Rotation vector direction is the rotation axis, vector length is the rotation angle in units of rad.
anchor (None, 0 or array_like with shape (3,) or (n,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=`'auto'`) – Starting index when applying operations. See ‘General move/rotate behavior’ above for details.
degrees (bool, default=`True`) – Interpret input in units of deg or rad.
- Returns
self
- Return type
Magpylib object
Examples
Rotate an object about the origin:
>>> import magpylib as magpy >>> sens = magpy.Sensor(position=(1,0,0)) >>> sens.rotate_from_rotvec((0,0,45), anchor=0) Sensor(id=...) >>> print(sens.position) [0.70710678 0.70710678 0. ] >>> print(sens.orientation.as_euler('xyz', degrees=True)) [ 0. 0. 45.]
Rotate the object about itself:
>>> sens.rotate_from_rotvec((0,0,45)) Sensor(id=...) >>> print(sens.position) [0.70710678 0.70710678 0. ] >>> print(sens.orientation.as_euler('xyz', degrees=True)) [ 0. 0. 90.]
Create a rotation path by rotating in several steps about an anchor:
>>> sens.rotate_from_rotvec([(0,0,15), (0,0,30), (0,0,45)], anchor=(0,0,0)) Sensor(id=...) >>> print(sens.position) [[ 7.07106781e-01 7.07106781e-01 0.00000000e+00] [ 5.00000000e-01 8.66025404e-01 0.00000000e+00] [ 2.58819045e-01 9.65925826e-01 0.00000000e+00] [-2.22044605e-16 1.00000000e+00 0.00000000e+00]] >>> print(sens.orientation.as_euler('xyz', degrees=True)) [[ 0. 0. 90.] [ 0. 0. 105.] [ 0. 0. 120.] [ 0. 0. 135.]]
- show(*, backend=<default>, canvas=<default>, animation=<default>, zoom=<default>, markers=<default>, return_fig=<default>, row=<default>, col=<default>, output=<default>, sumup=<default>, pixel_agg=<default>, style=<default>, **kwargs)#
Display objects and paths graphically.
Global graphic styles can be set with kwargs as style dictionary or using style underscore magic.
- Parameters
objects (Magpylib objects (sources, collections, sensors)) – Objects to be displayed.
backend (string, default=`None`) – Define plotting backend. Must be one of [‘auto’, ‘matplotlib’, ‘plotly’, ‘pyvista’]. If not set, parameter will default to magpylib.defaults.display.backend which is ‘auto’ by installation default. With ‘auto’, the backend defaults to ‘plotly’ if plotly is installed and the function is called in an IPython environment, otherwise defaults to ‘matplotlib’ which comes installed with magpylib. If the canvas is set, the backend defaults to the one corresponding to the canvas object (see canvas parameter).
canvas (matplotlib.pyplot AxesSubplot or plotly Figure object, default=`None`) – Display graphical output on a given canvas: - with matplotlib: matplotlib.axes.Axes with projection=3d. - with plotly: `plotly.graph_objects.Figure or plotly.graph_objects.FigureWidget. - with pyvista: pyvista.Plotter. By default a new canvas is created and immediately displayed.
animation (bool or float, default=`False`) – If True and at least one object has a path, the paths are rendered. If input is a positive float, the animation time is set to the given value. This feature is only available for the plotly backend.
zoom (float, default=`0`) – Adjust plot zoom-level. When zoom=0 3D-figure boundaries are tight.
markers (array_like, shape (n,3), default=`None`) – Display position markers in the global coordinate system.
return_fig (bool, default=False) –
If True, the function call returns the figure object.
with matplotlib: matplotlib.figure.Figure.
with plotly: plotly.graph_objects.Figure or plotly.graph_objects.FigureWidget.
with pyvista: pyvista.Plotter.
row (int or None,) – If provided specifies the row in which the objects will be displayed.
col (int or None,) – If provided specifies the column in which the objects will be displayed.
output (tuple or string, default="model3d") – Can be a string or a tuple of strings specifying the plot output type. By default output=’model3d’ displays the 3D representations of the objects. If output is a tuple of strings it must be a combination of ‘B’ or ‘H’ and ‘x’, ‘y’ and/or ‘z’. When having multiple coordinates, the field value is the combined vector length (e.g. (‘Bx’, ‘Hxy’, ‘Byz’)) ‘Bxy’ is equivalent to sqrt(|Bx|^2 + |By|^2). A 2D line plot is then represented accordingly if the objects contain at least one source and one sensor.
sumup (bool, default=True) – If True, sums the field values of the sources. Applies only if output is not ‘model3d’.
pixel_agg (bool, default="mean") – Reference to a compatible numpy aggregator function like ‘min’ or ‘mean’, which is applied to observer output values, e.g. mean of all sensor pixel outputs. Applies only if output is not ‘model3d’.
style (dict) – Object style inputs must be in dictionary form, e.g. {‘color’:’red’} or using style underscore magic, e.g. style_color=’red’. Applies to all objects matching the given style properties.
- Return type
None or figure object
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([(0.1*x,0,0) for x in range(50)]) Sphere... >>> src.rotate_from_angax(angle=[*range(0,400,10)], axis='z', anchor=0, start=11) Sphere... >>> ts = [-.4,0,.4] >>> sens = magpy.Sensor(position=(0,0,2), pixel=[(x,y,0) for x in ts for y in ts]) >>> magpy.show(src, sens) >>> magpy.show(src, sens, backend='plotly') >>> # graphic output
Display output on your own canvas (here a Matplotlib 3d-axes):
>>> 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.show(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, [(0,0,0), (0,0,3)]) >>> src2 = magpy.magnet.Sphere((1,1,1), 1, [(1,0,0), (1,0,3)], style_path_show=False) >>> magpy.defaults.display.style.magnet.magnetization.size = 2 >>> src1.style.magnetization.size = 1 >>> magpy.show(src1, src2, style_color='r') >>> # graphic output
Use a context manager to jointly animate 3d and 2d subplots
>>> import magpylib as magpy >>> import numpy as np >>> import plotly.graph_objects as go >>> path_len = 40 >>> sensor = magpy.Sensor() >>> cyl1 = magpy.magnet.Cylinder( ... magnetization=(100, 0, 0), ... dimension=(1, 2), ... position=(4, 0, 0), ... style_label="Cylinder1", ... ) >>> sensor.move(np.linspace((0, 0, -3), (0, 0, 3), path_len), start=0) Sensor(id=...) >>> cyl1.rotate_from_angax(angle=np.linspace(0, 300, path_len), start=0, axis="z", anchor=0) Cylinder(id=...) >>> cyl2 = cyl1.copy().move((0, 0, 5)) >>> fig = go.Figure() >>> with magpy.show_context(cyl1, cyl2, sensor, canvas=fig, backend="plotly", animation=True): ... magpy.show(col=1, output="model3d") ... magpy.show(col=2, output="Bxy", sumup=True) ... magpy.show(col=3, output="Bz", sumup=False) >>> fig.show() >>> # graphic output
- property style#
Object style in the form of a BaseStyle object. Input must be in the form of a style dictionary.
- class magpylib.magnet.Cylinder(magnetization=None, dimension=None, position=(0, 0, 0), orientation=None, style=None, **kwargs)#
Bases:
BaseMagnetCylinder magnet with homogeneous magnetization.
Can be used as sources input for magnetic field computation.
When position=(0,0,0) and orientation=None the geometric center of the cylinder lies in the origin of the global coordinate system and the cylinder axis coincides with the global z-axis.
- Parameters
magnetization (array_like, shape (3,), default=`None`) – Magnetization vector (mu0*M, remanence field) in units of mT given in the local object coordinates (rotates with object).
dimension (array_like, shape (2,), default=`None`) – Dimension (d,h) denote diameter and height of the cylinder in units of mm.
position (array_like, shape (3,) or (m,3), default=`(0,0,0)`) – Object position(s) in the global coordinates in units of mm. For m>1, the position and orientation attributes together represent an object path.
orientation (scipy Rotation object with length 1 or m, default=`None`) – Object orientation(s) in the global coordinates. None corresponds to a unit-rotation. For m>1, the position and orientation attributes together represent an object path.
parent (Collection object or None) – The object is a child of it’s parent collection.
style (dict) – Object style inputs must be in dictionary form, e.g. {‘color’:’red’} or using style underscore magic, e.g. style_color=’red’.
- Returns
magnet source
- Return type
Cylinder
Examples
Cylinder magnets are magnetic field sources. Below we compute the H-field in kA/m of a cylinder magnet with magnetization (100,200,300) in units of mT and 1 mm diameter and height at the observer position (1,1,1) given in units of mm:
>>> import magpylib as magpy >>> src = magpy.magnet.Cylinder(magnetization=(100,200,300), dimension=(1,1)) >>> H = src.getH((1,1,1)) >>> print(H) [4.84991343 3.88317816 2.73973202]
We rotate the source object, and compute the B-field, this time at a set of observer positions:
>>> src.rotate_from_angax(45, 'x') Cylinder(id=...) >>> B = src.getB([(1,1,1), (2,2,2), (3,3,3)]) >>> print(B) [[3.31419501 5.26683023 0.37767015] [0.42298405 0.67710536 0.04464932] [0.12571523 0.20144503 0.01312389]]
The same result is obtained when the rotated source moves along a path away from an observer at position (1,1,1). Here we use a Sensor object as observer.
>>> sens = magpy.Sensor(position=(1,1,1)) >>> src.move([(-1,-1,-1), (-2,-2,-2)]) Cylinder(id=...) >>> B = src.getB(sens) >>> print(B) [[3.31419501 5.26683023 0.37767015] [0.42298405 0.67710536 0.04464932] [0.12571523 0.20144503 0.01312389]]
- copy(**kwargs)#
Returns a copy of the current object instance. The copy method returns a deep copy of the object, that is independent of the original object.
- Parameters
kwargs (dict) – Keyword arguments (for example position=(1,2,3)) are applied to the copy.
Examples
Create a Sensor object and copy to an another position:
>>> import magpylib as magpy >>> sens1 = magpy.Sensor(style_label='sens1') >>> sens2 = sens1.copy(position=(2,6,10), style_label='sens2') >>> print(f"Instance {sens1.style.label} with position {sens1.position}.") Instance sens1 with position [0. 0. 0.]. >>> print(f"Instance {sens2.style.label} with position {sens2.position}.") Instance sens2 with position [ 2. 6. 10.].
- describe(*, exclude=('style', 'field_func'), return_string=False)#
Returns a view of the object properties.
- Parameters
exclude (bool, default=("style",)) – Properties to be excluded in the description view.
return_string (bool, default=`False`) – If False print description with stdout, if True return as string.
- property dimension#
Dimension (d,h) denote diameter and height of the cylinder in units of mm.
- property field_func#
The function for B- and H-field computation must have the two positional arguments field and observers. With field=’B’ or field=’H’ the B- or H-field in units of mT or kA/m must be returned respectively. The observers argument must accept numpy ndarray inputs of shape (n,3), in which case the returned fields must be numpy ndarrays of shape (n,3) themselves.
- getB(*observers, squeeze=True, pixel_agg=None, output='ndarray')#
Compute the B-field in units of mT generated by the source.
- Parameters
observers (array_like or (list of) Sensor objects) – Can be array_like positions of shape (n1, n2, …, 3) where the field should be evaluated, a Sensor object with pixel shape (n1, n2, …, 3) or a list of such sensor objects (must all have similar pixel shapes). All positions are given in units of mm.
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.
pixel_agg (str, default=`None`) – Reference to a compatible numpy aggregator function like ‘min’ or ‘mean’, which is applied to observer output values, e.g. mean of all sensor pixel outputs. With this option, observers input with different (pixel) shapes is allowed.
output (str, default='ndarray') – Output type, which must be one of (‘ndarray’, ‘dataframe’). By default a multi- dimensional array (‘ndarray’) is returned. If ‘dataframe’ is chosen, the function returns a 2D-table as a pandas.DataFrame object (the Pandas library must be installed).
- 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) or DataFrame
Examples
Compute the B-field of a spherical magnet at three positions:
>>> import magpylib as magpy >>> src = magpy.magnet.Sphere((0,0,1000), 1) >>> B = src.getB(((0,0,0), (1,0,0), (2,0,0))) >>> print(B) [[ 0. 0. 666.66666667] [ 0. 0. -41.66666667] [ 0. 0. -5.20833333]]
Compute the B-field at two sensors, each one with two pixels
>>> sens1 = magpy.Sensor(position=(1,0,0), pixel=((0,0,.1), (0,0,-.1))) >>> sens2 = sens1.copy(position=(2,0,0)) >>> B = src.getB(sens1, sens2) >>> print(B) [[[ 12.19288783 0. -39.83010025] [-12.19288783 0. -39.83010025]] [[ 0.77638847 0. -5.15004352] [ -0.77638847 0. -5.15004352]]]
- getH(*observers, squeeze=True, pixel_agg=None, output='ndarray')#
Compute the H-field in units of kA/m generated by the source.
- Parameters
observers (array_like or (list of) Sensor objects) – Can be array_like positions of shape (n1, n2, …, 3) where the field should be evaluated, a Sensor object with pixel shape (n1, n2, …, 3) or a list of such sensor objects (must all have similar pixel shapes). All positions are given in units of mm.
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.
pixel_agg (str, default=`None`) – Reference to a compatible numpy aggregator function like ‘min’ or ‘mean’, which is applied to observer output values, e.g. mean of all sensor pixel outputs. With this option, observers input with different (pixel) shapes is allowed.
output (str, default='ndarray') – Output type, which must be one of (‘ndarray’, ‘dataframe’). By default a multi- dimensional array (‘ndarray’) is returned. If ‘dataframe’ is chosen, the function returns a 2D-table as a pandas.DataFrame object (the Pandas library must be installed).
- 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) or DataFrame
Examples
Compute the H-field of a spherical magnet at three positions:
>>> import magpylib as magpy
>>> src = magpy.magnet.Sphere((0,0,1000), 1) >>> H = src.getH(((0,0,0), (1,0,0), (2,0,0))) >>> print(H) [[ 0. 0. -265.25823849] [ 0. 0. -33.15727981] [ 0. 0. -4.14465998]]
Compute the H-field at two sensors, each one with two pixels
>>> sens1 = magpy.Sensor(position=(1,0,0), pixel=((0,0,.1), (0,0,-.1))) >>> sens2 = sens1.copy(position=(2,0,0)) >>> H = src.getH(sens1, sens2) >>> print(H) [[[ 9.70279185 0. -31.69578669] [ -9.70279185 0. -31.69578669]] [[ 0.61783031 0. -4.09827441] [ -0.61783031 0. -4.09827441]]]
- get_trace(base=50, **kwargs) Dict[str, Any]#
Create the plotly mesh3d parameters for a Cylinder Magnet in a dictionary based on the provided arguments.
- property magnetization#
Object magnetization attribute getter and setter.
- move(displacement, start='auto')#
Move object by the displacement input.
Terminology for move/rotate methods:
path refers to position and orientation of an object.
When an input is just a single operation (e.g. one displacement vector or one angle) we call it ‘scalar input’. When it is an array_like of multiple scalars, we refer to it as ‘vector input’.
General move/rotate behavior:
Scalar input is applied to the whole object path, starting with path index start.
Vector input of length n applies the individual n operations to n object path entries, starting with path index start.
When an input extends beyond the object path, the object path will be padded by its edge-entries before the operation is applied.
By default (start=’auto’) the index is set to start=0 for scalar input [=move whole object path], and to start=len(object path) for vector input [=append to existing object path].
- Parameters
displacement (array_like, shape (3,) or (n,3)) – Displacement vector in units of mm.
start (int or str, default=`'auto'`) – Starting index when applying operations. See ‘General move/rotate behavior’ above for details.
- Returns
self
- Return type
Magpylib object
Examples
Move objects around with scalar input:
>>> import magpylib as magpy >>> sens = magpy.Sensor(position=(1,1,1)) >>> print(sens.position) [1. 1. 1.] >>> sens.move((1,1,1)) Sensor(id=...) >>> print(sens.position) [2. 2. 2.]
Create len>1 object paths with vector input:
>>> sens.move([(1,1,1),(2,2,2),(3,3,3)]) Sensor(id=...) >>> print(sens.position) [[2. 2. 2.] [3. 3. 3.] [4. 4. 4.] [5. 5. 5.]]
Apply operations starting with a designated path index:
>>> sens.move((0,0,2), start=2) Sensor(id=...) >>> print(sens.position) [[2. 2. 2.] [3. 3. 3.] [4. 4. 6.] [5. 5. 7.]]
- property orientation#
Object orientation(s) in the global coordinates. None corresponds to a unit-rotation. For m>1, the position and orientation attributes together represent an object path.
- property parent#
The object is a child of it’s parent collection.
- property position#
Object position(s) in the global coordinates in units of mm. For m>1, the position and orientation attributes together represent an object path.
- reset_path()#
Set object position to (0,0,0) and orientation = unit rotation.
- Returns
self
- Return type
magpylib object
Examples
Demonstration of reset_path functionality:
>>> import magpylib as magpy >>> obj = magpy.Sensor(position=(1,2,3)) >>> obj.rotate_from_angax(45, 'z') Sensor... >>> print(obj.position) [1. 2. 3.] >>> print(obj.orientation.as_euler('xyz', degrees=True)) [ 0. 0. 45.]
>>> obj.reset_path() Sensor(id=...) >>> print(obj.position) [0. 0. 0.] >>> print(obj.orientation.as_euler('xyz', degrees=True)) [0. 0. 0.]
- rotate(rotation: Rotation, anchor=None, start='auto')#
Rotate object about a given anchor.
Terminology for move/rotate methods:
path refers to position and orientation of an object.
When an input is just a single operation (e.g. one displacement vector or one angle) we call it ‘scalar input’. When it is an array_like of multiple scalars, we refer to it as ‘vector input’.
General move/rotate behavior:
Scalar input is applied to the whole object path, starting with path index start.
Vector input of length n applies the individual n operations to n object path entries, starting with path index start.
When an input extends beyond the object path, the object path will be padded by its edge-entries before the operation is applied.
By default (start=’auto’) the index is set to start=0 for scalar input [=move whole object path], and to start=len(object path) for vector input [=append to existing object path].
- Parameters
rotation (None or scipy Rotation object) – Rotation to be applied to the object. The scipy Rotation input can be scalar or vector type (see terminology above). None input is interpreted as unit rotation.
anchor (None, 0 or array_like with shape (3,) or (n,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=`'auto'`) – Starting index when applying operations. See ‘General move/rotate behavior’ above for details.
- Returns
self
- Return type
Magpylib object
Examples
Rotate an object about the origin:
>>> from scipy.spatial.transform import Rotation as R >>> import magpylib as magpy >>> sens = magpy.Sensor(position=(1,0,0)) >>> sens.rotate(R.from_euler('z', 45, degrees=True), anchor=0) Sensor(id=...) >>> print(sens.position) [0.70710678 0.70710678 0. ] >>> print(sens.orientation.as_euler('xyz', degrees=True)) [ 0. 0. 45.]
Rotate the object about itself:
>>> sens.rotate(R.from_euler('z', 45, degrees=True)) Sensor(id=...) >>> print(sens.position) [0.70710678 0.70710678 0. ] >>> print(sens.orientation.as_euler('xyz', degrees=True)) [ 0. 0. 90.]
Create a rotation path by rotating in several steps about an anchor:
>>> sens.rotate(R.from_euler('z', (15,30,45), degrees=True), anchor=(0,0,0)) Sensor(id=...) >>> print(sens.position) [[ 7.07106781e-01 7.07106781e-01 0.00000000e+00] [ 5.00000000e-01 8.66025404e-01 0.00000000e+00] [ 2.58819045e-01 9.65925826e-01 0.00000000e+00] [-2.22044605e-16 1.00000000e+00 0.00000000e+00]] >>> print(sens.orientation.as_euler('xyz', degrees=True)) [[ 0. 0. 90.] [ 0. 0. 105.] [ 0. 0. 120.] [ 0. 0. 135.]]
- rotate_from_angax(angle, axis, anchor=None, start='auto', degrees=True)#
Rotates object using angle-axis input.
Terminology for move/rotate methods:
path refers to position and orientation of an object.
When an input is just a single operation (e.g. one displacement vector or one angle) we call it ‘scalar input’. When it is an array_like of multiple scalars, we refer to it as ‘vector input’.
General move/rotate behavior:
Scalar input is applied to the whole object path, starting with path index start.
Vector input of length n applies the individual n operations to n object path entries, starting with path index start.
When an input extends beyond the object path, the object path will be padded by its edge-entries before the operation is applied.
By default (start=’auto’) the index is set to start=0 for scalar input [=move whole object path], and to start=len(object path) for vector input [=append to existing object path].
- Parameters
angle (int, float or array_like with shape (n,)) – Angle(s) of rotation 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, 0 or array_like with shape (3,) or (n,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=`'auto'`) – Starting index when applying operations. See ‘General move/rotate behavior’ above for details.
degrees (bool, default=`True`) – Interpret input in units of deg or rad.
- Returns
self
- Return type
Magpylib object
Examples
Rotate an object about the origin:
>>> import magpylib as magpy >>> sens = magpy.Sensor(position=(1,0,0)) >>> sens.rotate_from_angax(45, axis='z', anchor=0) Sensor(id=...) >>> print(sens.position) [0.70710678 0.70710678 0. ] >>> print(sens.orientation.as_euler('xyz', degrees=True)) [ 0. 0. 45.]
Rotate the object about itself:
>>> sens.rotate_from_angax(45, axis=(0,0,1)) Sensor(id=...) >>> print(sens.position) [0.70710678 0.70710678 0. ] >>> print(sens.orientation.as_euler('xyz', degrees=True)) [ 0. 0. 90.]
Create a rotation path by rotating in several steps about an anchor:
>>> sens.rotate_from_angax((15,30,45), axis='z', anchor=(0,0,0)) Sensor(id=...) >>> print(sens.position) [[ 7.07106781e-01 7.07106781e-01 0.00000000e+00] [ 5.00000000e-01 8.66025404e-01 0.00000000e+00] [ 2.58819045e-01 9.65925826e-01 0.00000000e+00] [-2.22044605e-16 1.00000000e+00 0.00000000e+00]] >>> print(sens.orientation.as_euler('xyz', degrees=True)) [[ 0. 0. 90.] [ 0. 0. 105.] [ 0. 0. 120.] [ 0. 0. 135.]]
- rotate_from_euler(angle, seq, anchor=None, start='auto', degrees=True)#
Rotates object using Euler angle input.
Terminology for move/rotate methods:
path refers to position and orientation of an object.
When an input is just a single operation (e.g. one displacement vector or one angle) we call it ‘scalar input’. When it is an array_like of multiple scalars, we refer to it as ‘vector input’.
General move/rotate behavior:
Scalar input is applied to the whole object path, starting with path index start.
Vector input of length n applies the individual n operations to n object path entries, starting with path index start.
When an input extends beyond the object path, the object path will be padded by its edge-entries before the operation is applied.
By default (start=’auto’) the index is set to start=0 for scalar input [=move whole object path], and to start=len(object path) for vector input [=append to existing object path].
- Parameters
angle (int, float or array_like with shape (n,)) – Angle(s) of rotation in units of deg (by default).
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.
anchor (None, 0 or array_like with shape (3,) or (n,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=`'auto'`) – Starting index when applying operations. See ‘General move/rotate behavior’ above for details.
degrees (bool, default=`True`) – Interpret input in units of deg or rad.
- Returns
self
- Return type
Magpylib object
Examples
Rotate an object about the origin:
>>> import magpylib as magpy >>> sens = magpy.Sensor(position=(1,0,0)) >>> sens.rotate_from_euler(45, 'z', anchor=0) Sensor... >>> print(sens.position) [0.70710678 0.70710678 0. ] >>> print(sens.orientation.as_euler('xyz', degrees=True)) [ 0. 0. 45.]
Rotate the object about itself:
>>> sens.rotate_from_euler(45, 'z') Sensor(id=...) >>> print(sens.position) [0.70710678 0.70710678 0. ] >>> print(sens.orientation.as_euler('xyz', degrees=True)) [ 0. 0. 90.]
Create a rotation path by rotating in several steps about an anchor:
>>> sens.rotate_from_euler((15,30,45), 'z', anchor=(0,0,0)) Sensor(id=...) >>> print(sens.position) [[ 7.07106781e-01 7.07106781e-01 0.00000000e+00] [ 5.00000000e-01 8.66025404e-01 0.00000000e+00] [ 2.58819045e-01 9.65925826e-01 0.00000000e+00] [-2.22044605e-16 1.00000000e+00 0.00000000e+00]] >>> print(sens.orientation.as_euler('xyz', degrees=True)) [[ 0. 0. 90.] [ 0. 0. 105.] [ 0. 0. 120.] [ 0. 0. 135.]]
- rotate_from_matrix(matrix, anchor=None, start='auto')#
Rotates object using matrix input.
Terminology for move/rotate methods:
path refers to position and orientation of an object.
When an input is just a single operation (e.g. one displacement vector or one angle) we call it ‘scalar input’. When it is an array_like of multiple scalars, we refer to it as ‘vector input’.
General move/rotate behavior:
Scalar input is applied to the whole object path, starting with path index start.
Vector input of length n applies the individual n operations to n object path entries, starting with path index start.
When an input extends beyond the object path, the object path will be padded by its edge-entries before the operation is applied.
By default (start=’auto’) the index is set to start=0 for scalar input [=move whole object path], and to start=len(object path) for vector input [=append to existing object path].
- Parameters
matrix (array_like, shape (n,3,3) or (3,3)) – Rotation input. See scipy.spatial.transform.Rotation for details.
anchor (None, 0 or array_like with shape (3,) or (n,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=`'auto'`) – Starting index when applying operations. See ‘General move/rotate behavior’ above for details.
- Returns
self
- Return type
Magpylib object
Examples
Rotate an object about the origin:
>>> import magpylib as magpy >>> sens = magpy.Sensor(position=(1,0,0)) >>> sens.rotate_from_matrix([(0,-1,0),(1,0,0),(0,0,1)], anchor=0) Sensor(id=...) >>> print(sens.position) [0. 1. 0.] >>> print(sens.orientation.as_euler('xyz', degrees=True)) [ 0. 0. 90.]
Rotate the object about itself:
>>> sens.rotate_from_matrix([(0,-1,0),(1,0,0),(0,0,1)]) Sensor(id=...) >>> print(sens.position) [0. 1. 0.] >>> print(sens.orientation.as_euler('xyz', degrees=True)) [ 0. 0. 180.]
- rotate_from_mrp(mrp, anchor=None, start='auto')#
Rotates object using Modified Rodrigues Parameters (MRPs) input.
Terminology for move/rotate methods:
path refers to position and orientation of an object.
When an input is just a single operation (e.g. one displacement vector or one angle) we call it ‘scalar input’. When it is an array_like of multiple scalars, we refer to it as ‘vector input’.
General move/rotate behavior:
Scalar input is applied to the whole object path, starting with path index start.
Vector input of length n applies the individual n operations to n object path entries, starting with path index start.
When an input extends beyond the object path, the object path will be padded by its edge-entries before the operation is applied.
By default (start=’auto’) the index is set to start=0 for scalar input [=move whole object path], and to start=len(object path) for vector input [=append to existing object path].
- Parameters
mrp (array_like, shape (n,3) or (3,)) – Rotation input. See scipy Rotation package for details on Modified Rodrigues Parameters (MRPs).
anchor (None, 0 or array_like with shape (3,) or (n,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=`'auto'`) – Starting index when applying operations. See ‘General move/rotate behavior’ above for details.
- Returns
self
- Return type
Magpylib object
Examples
Rotate an object about the origin:
>>> import magpylib as magpy >>> sens = magpy.Sensor(position=(1,0,0)) >>> sens.rotate_from_mrp((0,0,1), anchor=0) Sensor(id=...) >>> print(sens.position) [-1. 0. 0.] >>> print(sens.orientation.as_euler('xyz', degrees=True)) [ 0. 0. 180.]
Rotate the object about itself:
>>> sens.rotate_from_matrix([(0,-1,0),(1,0,0),(0,0,1)]) Sensor(id=...) >>> print(sens.position) [-1. 0. 0.] >>> print(sens.orientation.as_euler('xyz', degrees=True)) [ 0. 0. -90.]
- rotate_from_quat(quat, anchor=None, start='auto')#
Rotates object using quaternion input.
Terminology for move/rotate methods:
path refers to position and orientation of an object.
When an input is just a single operation (e.g. one displacement vector or one angle) we call it ‘scalar input’. When it is an array_like of multiple scalars, we refer to it as ‘vector input’.
General move/rotate behavior:
Scalar input is applied to the whole object path, starting with path index start.
Vector input of length n applies the individual n operations to n object path entries, starting with path index start.
When an input extends beyond the object path, the object path will be padded by its edge-entries before the operation is applied.
By default (start=’auto’) the index is set to start=0 for scalar input [=move whole object path], and to start=len(object path) for vector input [=append to existing object path].
- Parameters
quat (array_like, shape (n,4) or (4,)) – Rotation input in quaternion form.
anchor (None, 0 or array_like with shape (3,) or (n,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=`'auto'`) – Starting index when applying operations. See ‘General move/rotate behavior’ above for details.
- Returns
self
- Return type
Magpylib object
Examples
Rotate an object about the origin:
>>> import magpylib as magpy >>> sens = magpy.Sensor(position=(1,0,0)) >>> sens.rotate_from_quat((0,0,1,1), anchor=0) Sensor(id=...) >>> print(sens.position) [0. 1. 0.] >>> print(sens.orientation.as_euler('xyz', degrees=True)) [ 0. 0. 90.]
Rotate the object about itself:
>>> sens.rotate_from_quat((0,0,1,1)) Sensor(id=...) >>> print(sens.position) [0. 1. 0.] >>> print(sens.orientation.as_euler('xyz', degrees=True)) [ 0. 0. 180.]
- rotate_from_rotvec(rotvec, anchor=None, start='auto', degrees=True)#
Rotates object using rotation vector input.
Terminology for move/rotate methods:
path refers to position and orientation of an object.
When an input is just a single operation (e.g. one displacement vector or one angle) we call it ‘scalar input’. When it is an array_like of multiple scalars, we refer to it as ‘vector input’.
General move/rotate behavior:
Scalar input is applied to the whole object path, starting with path index start.
Vector input of length n applies the individual n operations to n object path entries, starting with path index start.
When an input extends beyond the object path, the object path will be padded by its edge-entries before the operation is applied.
By default (start=’auto’) the index is set to start=0 for scalar input [=move whole object path], and to start=len(object path) for vector input [=append to existing object path].
- Parameters
rotvec (array_like, shape (n,3) or (3,)) – Rotation input. Rotation vector direction is the rotation axis, vector length is the rotation angle in units of rad.
anchor (None, 0 or array_like with shape (3,) or (n,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=`'auto'`) – Starting index when applying operations. See ‘General move/rotate behavior’ above for details.
degrees (bool, default=`True`) – Interpret input in units of deg or rad.
- Returns
self
- Return type
Magpylib object
Examples
Rotate an object about the origin:
>>> import magpylib as magpy >>> sens = magpy.Sensor(position=(1,0,0)) >>> sens.rotate_from_rotvec((0,0,45), anchor=0) Sensor(id=...) >>> print(sens.position) [0.70710678 0.70710678 0. ] >>> print(sens.orientation.as_euler('xyz', degrees=True)) [ 0. 0. 45.]
Rotate the object about itself:
>>> sens.rotate_from_rotvec((0,0,45)) Sensor(id=...) >>> print(sens.position) [0.70710678 0.70710678 0. ] >>> print(sens.orientation.as_euler('xyz', degrees=True)) [ 0. 0. 90.]
Create a rotation path by rotating in several steps about an anchor:
>>> sens.rotate_from_rotvec([(0,0,15), (0,0,30), (0,0,45)], anchor=(0,0,0)) Sensor(id=...) >>> print(sens.position) [[ 7.07106781e-01 7.07106781e-01 0.00000000e+00] [ 5.00000000e-01 8.66025404e-01 0.00000000e+00] [ 2.58819045e-01 9.65925826e-01 0.00000000e+00] [-2.22044605e-16 1.00000000e+00 0.00000000e+00]] >>> print(sens.orientation.as_euler('xyz', degrees=True)) [[ 0. 0. 90.] [ 0. 0. 105.] [ 0. 0. 120.] [ 0. 0. 135.]]
- show(*, backend=<default>, canvas=<default>, animation=<default>, zoom=<default>, markers=<default>, return_fig=<default>, row=<default>, col=<default>, output=<default>, sumup=<default>, pixel_agg=<default>, style=<default>, **kwargs)#
Display objects and paths graphically.
Global graphic styles can be set with kwargs as style dictionary or using style underscore magic.
- Parameters
objects (Magpylib objects (sources, collections, sensors)) – Objects to be displayed.
backend (string, default=`None`) – Define plotting backend. Must be one of [‘auto’, ‘matplotlib’, ‘plotly’, ‘pyvista’]. If not set, parameter will default to magpylib.defaults.display.backend which is ‘auto’ by installation default. With ‘auto’, the backend defaults to ‘plotly’ if plotly is installed and the function is called in an IPython environment, otherwise defaults to ‘matplotlib’ which comes installed with magpylib. If the canvas is set, the backend defaults to the one corresponding to the canvas object (see canvas parameter).
canvas (matplotlib.pyplot AxesSubplot or plotly Figure object, default=`None`) – Display graphical output on a given canvas: - with matplotlib: matplotlib.axes.Axes with projection=3d. - with plotly: `plotly.graph_objects.Figure or plotly.graph_objects.FigureWidget. - with pyvista: pyvista.Plotter. By default a new canvas is created and immediately displayed.
animation (bool or float, default=`False`) – If True and at least one object has a path, the paths are rendered. If input is a positive float, the animation time is set to the given value. This feature is only available for the plotly backend.
zoom (float, default=`0`) – Adjust plot zoom-level. When zoom=0 3D-figure boundaries are tight.
markers (array_like, shape (n,3), default=`None`) – Display position markers in the global coordinate system.
return_fig (bool, default=False) –
If True, the function call returns the figure object.
with matplotlib: matplotlib.figure.Figure.
with plotly: plotly.graph_objects.Figure or plotly.graph_objects.FigureWidget.
with pyvista: pyvista.Plotter.
row (int or None,) – If provided specifies the row in which the objects will be displayed.
col (int or None,) – If provided specifies the column in which the objects will be displayed.
output (tuple or string, default="model3d") – Can be a string or a tuple of strings specifying the plot output type. By default output=’model3d’ displays the 3D representations of the objects. If output is a tuple of strings it must be a combination of ‘B’ or ‘H’ and ‘x’, ‘y’ and/or ‘z’. When having multiple coordinates, the field value is the combined vector length (e.g. (‘Bx’, ‘Hxy’, ‘Byz’)) ‘Bxy’ is equivalent to sqrt(|Bx|^2 + |By|^2). A 2D line plot is then represented accordingly if the objects contain at least one source and one sensor.
sumup (bool, default=True) – If True, sums the field values of the sources. Applies only if output is not ‘model3d’.
pixel_agg (bool, default="mean") – Reference to a compatible numpy aggregator function like ‘min’ or ‘mean’, which is applied to observer output values, e.g. mean of all sensor pixel outputs. Applies only if output is not ‘model3d’.
style (dict) – Object style inputs must be in dictionary form, e.g. {‘color’:’red’} or using style underscore magic, e.g. style_color=’red’. Applies to all objects matching the given style properties.
- Return type
None or figure object
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([(0.1*x,0,0) for x in range(50)]) Sphere... >>> src.rotate_from_angax(angle=[*range(0,400,10)], axis='z', anchor=0, start=11) Sphere... >>> ts = [-.4,0,.4] >>> sens = magpy.Sensor(position=(0,0,2), pixel=[(x,y,0) for x in ts for y in ts]) >>> magpy.show(src, sens) >>> magpy.show(src, sens, backend='plotly') >>> # graphic output
Display output on your own canvas (here a Matplotlib 3d-axes):
>>> 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.show(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, [(0,0,0), (0,0,3)]) >>> src2 = magpy.magnet.Sphere((1,1,1), 1, [(1,0,0), (1,0,3)], style_path_show=False) >>> magpy.defaults.display.style.magnet.magnetization.size = 2 >>> src1.style.magnetization.size = 1 >>> magpy.show(src1, src2, style_color='r') >>> # graphic output
Use a context manager to jointly animate 3d and 2d subplots
>>> import magpylib as magpy >>> import numpy as np >>> import plotly.graph_objects as go >>> path_len = 40 >>> sensor = magpy.Sensor() >>> cyl1 = magpy.magnet.Cylinder( ... magnetization=(100, 0, 0), ... dimension=(1, 2), ... position=(4, 0, 0), ... style_label="Cylinder1", ... ) >>> sensor.move(np.linspace((0, 0, -3), (0, 0, 3), path_len), start=0) Sensor(id=...) >>> cyl1.rotate_from_angax(angle=np.linspace(0, 300, path_len), start=0, axis="z", anchor=0) Cylinder(id=...) >>> cyl2 = cyl1.copy().move((0, 0, 5)) >>> fig = go.Figure() >>> with magpy.show_context(cyl1, cyl2, sensor, canvas=fig, backend="plotly", animation=True): ... magpy.show(col=1, output="model3d") ... magpy.show(col=2, output="Bxy", sumup=True) ... magpy.show(col=3, output="Bz", sumup=False) >>> fig.show() >>> # graphic output
- property style#
Object style in the form of a BaseStyle object. Input must be in the form of a style dictionary.
- class magpylib.magnet.CylinderSegment(magnetization=None, dimension=None, position=(0, 0, 0), orientation=None, style=None, **kwargs)#
Bases:
BaseMagnetCylinder segment (ring-section) magnet with homogeneous magnetization.
Can be used as sources input for magnetic field computation.
When position=(0,0,0) and orientation=None the geometric center of the cylinder lies in the origin of the global coordinate system and the cylinder axis coincides with the global z-axis. Section angle 0 corresponds to an x-z plane section of the cylinder.
- Parameters
magnetization (array_like, shape (3,), default=`None`) – Magnetization vector (mu0*M, remanence field) in units of mT given in the local object coordinates (rotates with object).
dimension (array_like, shape (5,), default=`None`) – Dimension/Size of the cylinder segment of the form (r1, r2, h, phi1, phi2) where r1<r2 denote inner and outer radii in units of mm, phi1<phi2 denote the cylinder section angles in units of deg and h is the cylinder height in units of mm.
position (array_like, shape (3,) or (m,3), default=`(0,0,0)`) – Object position(s) in the global coordinates in units of mm. For m>1, the position and orientation attributes together represent an object path.
barycenter (array_like, shape (3,)) – Read only property that returns the geometric barycenter (=center of mass) of the object.
orientation (scipy Rotation object with length 1 or m, default=`None`) – Object orientation(s) in the global coordinates. None corresponds to a unit-rotation. For m>1, the position and orientation attributes together represent an object path.
parent (Collection object or None) – The object is a child of it’s parent collection.
style (dict) – Object style inputs must be in dictionary form, e.g. {‘color’:’red’} or using style underscore magic, e.g. style_color=’red’.
- Returns
magnet source
- Return type
CylinderSegment object
Examples
CylinderSegment magnets are magnetic field sources. In this example we compute the H-field kA/m of such a cylinder segment magnet with magnetization (100,200,300) in units of mT, inner radius 1 mm, outer radius 2 mm, height 1 mm, and section angles 0 and 45 deg at the observer position (2,2,2) in units of mm:
>>> import magpylib as magpy >>> src = magpy.magnet.CylinderSegment(magnetization=(100,200,300), dimension=(1,2,1,0,45)) >>> H = src.getH((2,2,2)) >>> print(H) [0.80784692 1.93422813 2.74116805]
We rotate the source object, and compute the B-field, this time at a set of observer positions:
>>> src.rotate_from_angax(45, 'x') CylinderSegment(id=...) >>> B = src.getB([(1,1,1), (2,2,2), (3,3,3)]) >>> print(B) [[-32.82849635 30.15882073 -16.32885658] [ 0.62876075 3.97579164 0.73297829] [ 0.25439493 0.74331628 0.11682542]]
The same result is obtained when the rotated source moves along a path away from an observer at position (1,1,1). Here we use a Sensor object as observer.
>>> sens = magpy.Sensor(position=(1,1,1)) >>> src.move([(-1,-1,-1), (-2,-2,-2)]) CylinderSegment(id=...) >>> B = src.getB(sens) >>> print(B) [[-32.82849635 30.15882073 -16.32885658] [ 0.62876075 3.97579164 0.73297829] [ 0.25439493 0.74331628 0.11682542]]
- property barycenter#
Object barycenter.
- copy(**kwargs)#
Returns a copy of the current object instance. The copy method returns a deep copy of the object, that is independent of the original object.
- Parameters
kwargs (dict) – Keyword arguments (for example position=(1,2,3)) are applied to the copy.
Examples
Create a Sensor object and copy to an another position:
>>> import magpylib as magpy >>> sens1 = magpy.Sensor(style_label='sens1') >>> sens2 = sens1.copy(position=(2,6,10), style_label='sens2') >>> print(f"Instance {sens1.style.label} with position {sens1.position}.") Instance sens1 with position [0. 0. 0.]. >>> print(f"Instance {sens2.style.label} with position {sens2.position}.") Instance sens2 with position [ 2. 6. 10.].
- describe(*, exclude=('style', 'field_func'), return_string=False)#
Returns a view of the object properties.
- Parameters
exclude (bool, default=("style",)) – Properties to be excluded in the description view.
return_string (bool, default=`False`) – If False print description with stdout, if True return as string.
- property dimension#
Dimension/Size of the cylinder segment of the form (r1, r2, h, phi1, phi2) where r1<r2 denote inner and outer radii in units of mm, phi1<phi2 denote the cylinder section angles in units of deg and h is the cylinder height in units of mm.
- property field_func#
The function for B- and H-field computation must have the two positional arguments field and observers. With field=’B’ or field=’H’ the B- or H-field in units of mT or kA/m must be returned respectively. The observers argument must accept numpy ndarray inputs of shape (n,3), in which case the returned fields must be numpy ndarrays of shape (n,3) themselves.
- getB(*observers, squeeze=True, pixel_agg=None, output='ndarray')#
Compute the B-field in units of mT generated by the source.
- Parameters
observers (array_like or (list of) Sensor objects) – Can be array_like positions of shape (n1, n2, …, 3) where the field should be evaluated, a Sensor object with pixel shape (n1, n2, …, 3) or a list of such sensor objects (must all have similar pixel shapes). All positions are given in units of mm.
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.
pixel_agg (str, default=`None`) – Reference to a compatible numpy aggregator function like ‘min’ or ‘mean’, which is applied to observer output values, e.g. mean of all sensor pixel outputs. With this option, observers input with different (pixel) shapes is allowed.
output (str, default='ndarray') – Output type, which must be one of (‘ndarray’, ‘dataframe’). By default a multi- dimensional array (‘ndarray’) is returned. If ‘dataframe’ is chosen, the function returns a 2D-table as a pandas.DataFrame object (the Pandas library must be installed).
- 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) or DataFrame
Examples
Compute the B-field of a spherical magnet at three positions:
>>> import magpylib as magpy >>> src = magpy.magnet.Sphere((0,0,1000), 1) >>> B = src.getB(((0,0,0), (1,0,0), (2,0,0))) >>> print(B) [[ 0. 0. 666.66666667] [ 0. 0. -41.66666667] [ 0. 0. -5.20833333]]
Compute the B-field at two sensors, each one with two pixels
>>> sens1 = magpy.Sensor(position=(1,0,0), pixel=((0,0,.1), (0,0,-.1))) >>> sens2 = sens1.copy(position=(2,0,0)) >>> B = src.getB(sens1, sens2) >>> print(B) [[[ 12.19288783 0. -39.83010025] [-12.19288783 0. -39.83010025]] [[ 0.77638847 0. -5.15004352] [ -0.77638847 0. -5.15004352]]]
- getH(*observers, squeeze=True, pixel_agg=None, output='ndarray')#
Compute the H-field in units of kA/m generated by the source.
- Parameters
observers (array_like or (list of) Sensor objects) – Can be array_like positions of shape (n1, n2, …, 3) where the field should be evaluated, a Sensor object with pixel shape (n1, n2, …, 3) or a list of such sensor objects (must all have similar pixel shapes). All positions are given in units of mm.
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.
pixel_agg (str, default=`None`) – Reference to a compatible numpy aggregator function like ‘min’ or ‘mean’, which is applied to observer output values, e.g. mean of all sensor pixel outputs. With this option, observers input with different (pixel) shapes is allowed.
output (str, default='ndarray') – Output type, which must be one of (‘ndarray’, ‘dataframe’). By default a multi- dimensional array (‘ndarray’) is returned. If ‘dataframe’ is chosen, the function returns a 2D-table as a pandas.DataFrame object (the Pandas library must be installed).
- 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) or DataFrame
Examples
Compute the H-field of a spherical magnet at three positions:
>>> import magpylib as magpy
>>> src = magpy.magnet.Sphere((0,0,1000), 1) >>> H = src.getH(((0,0,0), (1,0,0), (2,0,0))) >>> print(H) [[ 0. 0. -265.25823849] [ 0. 0. -33.15727981] [ 0. 0. -4.14465998]]
Compute the H-field at two sensors, each one with two pixels
>>> sens1 = magpy.Sensor(position=(1,0,0), pixel=((0,0,.1), (0,0,-.1))) >>> sens2 = sens1.copy(position=(2,0,0)) >>> H = src.getH(sens1, sens2) >>> print(H) [[[ 9.70279185 0. -31.69578669] [ -9.70279185 0. -31.69578669]] [[ 0.61783031 0. -4.09827441] [ -0.61783031 0. -4.09827441]]]
- get_trace(vertices=25, **kwargs) Dict[str, Any]#
Create the plotly mesh3d parameters for a Cylinder Segment Magnet in a dictionary based on the provided arguments.
- property magnetization#
Object magnetization attribute getter and setter.
- move(displacement, start='auto')#
Move object by the displacement input.
Terminology for move/rotate methods:
path refers to position and orientation of an object.
When an input is just a single operation (e.g. one displacement vector or one angle) we call it ‘scalar input’. When it is an array_like of multiple scalars, we refer to it as ‘vector input’.
General move/rotate behavior:
Scalar input is applied to the whole object path, starting with path index start.
Vector input of length n applies the individual n operations to n object path entries, starting with path index start.
When an input extends beyond the object path, the object path will be padded by its edge-entries before the operation is applied.
By default (start=’auto’) the index is set to start=0 for scalar input [=move whole object path], and to start=len(object path) for vector input [=append to existing object path].
- Parameters
displacement (array_like, shape (3,) or (n,3)) – Displacement vector in units of mm.
start (int or str, default=`'auto'`) – Starting index when applying operations. See ‘General move/rotate behavior’ above for details.
- Returns
self
- Return type
Magpylib object
Examples
Move objects around with scalar input:
>>> import magpylib as magpy >>> sens = magpy.Sensor(position=(1,1,1)) >>> print(sens.position) [1. 1. 1.] >>> sens.move((1,1,1)) Sensor(id=...) >>> print(sens.position) [2. 2. 2.]
Create len>1 object paths with vector input:
>>> sens.move([(1,1,1),(2,2,2),(3,3,3)]) Sensor(id=...) >>> print(sens.position) [[2. 2. 2.] [3. 3. 3.] [4. 4. 4.] [5. 5. 5.]]
Apply operations starting with a designated path index:
>>> sens.move((0,0,2), start=2) Sensor(id=...) >>> print(sens.position) [[2. 2. 2.] [3. 3. 3.] [4. 4. 6.] [5. 5. 7.]]
- property orientation#
Object orientation(s) in the global coordinates. None corresponds to a unit-rotation. For m>1, the position and orientation attributes together represent an object path.
- property parent#
The object is a child of it’s parent collection.
- property position#
Object position(s) in the global coordinates in units of mm. For m>1, the position and orientation attributes together represent an object path.
- reset_path()#
Set object position to (0,0,0) and orientation = unit rotation.
- Returns
self
- Return type
magpylib object
Examples
Demonstration of reset_path functionality:
>>> import magpylib as magpy >>> obj = magpy.Sensor(position=(1,2,3)) >>> obj.rotate_from_angax(45, 'z') Sensor... >>> print(obj.position) [1. 2. 3.] >>> print(obj.orientation.as_euler('xyz', degrees=True)) [ 0. 0. 45.]
>>> obj.reset_path() Sensor(id=...) >>> print(obj.position) [0. 0. 0.] >>> print(obj.orientation.as_euler('xyz', degrees=True)) [0. 0. 0.]
- rotate(rotation: Rotation, anchor=None, start='auto')#
Rotate object about a given anchor.
Terminology for move/rotate methods:
path refers to position and orientation of an object.
When an input is just a single operation (e.g. one displacement vector or one angle) we call it ‘scalar input’. When it is an array_like of multiple scalars, we refer to it as ‘vector input’.
General move/rotate behavior:
Scalar input is applied to the whole object path, starting with path index start.
Vector input of length n applies the individual n operations to n object path entries, starting with path index start.
When an input extends beyond the object path, the object path will be padded by its edge-entries before the operation is applied.
By default (start=’auto’) the index is set to start=0 for scalar input [=move whole object path], and to start=len(object path) for vector input [=append to existing object path].
- Parameters
rotation (None or scipy Rotation object) – Rotation to be applied to the object. The scipy Rotation input can be scalar or vector type (see terminology above). None input is interpreted as unit rotation.
anchor (None, 0 or array_like with shape (3,) or (n,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=`'auto'`) – Starting index when applying operations. See ‘General move/rotate behavior’ above for details.
- Returns
self
- Return type
Magpylib object
Examples
Rotate an object about the origin:
>>> from scipy.spatial.transform import Rotation as R >>> import magpylib as magpy >>> sens = magpy.Sensor(position=(1,0,0)) >>> sens.rotate(R.from_euler('z', 45, degrees=True), anchor=0) Sensor(id=...) >>> print(sens.position) [0.70710678 0.70710678 0. ] >>> print(sens.orientation.as_euler('xyz', degrees=True)) [ 0. 0. 45.]
Rotate the object about itself:
>>> sens.rotate(R.from_euler('z', 45, degrees=True)) Sensor(id=...) >>> print(sens.position) [0.70710678 0.70710678 0. ] >>> print(sens.orientation.as_euler('xyz', degrees=True)) [ 0. 0. 90.]
Create a rotation path by rotating in several steps about an anchor:
>>> sens.rotate(R.from_euler('z', (15,30,45), degrees=True), anchor=(0,0,0)) Sensor(id=...) >>> print(sens.position) [[ 7.07106781e-01 7.07106781e-01 0.00000000e+00] [ 5.00000000e-01 8.66025404e-01 0.00000000e+00] [ 2.58819045e-01 9.65925826e-01 0.00000000e+00] [-2.22044605e-16 1.00000000e+00 0.00000000e+00]] >>> print(sens.orientation.as_euler('xyz', degrees=True)) [[ 0. 0. 90.] [ 0. 0. 105.] [ 0. 0. 120.] [ 0. 0. 135.]]
- rotate_from_angax(angle, axis, anchor=None, start='auto', degrees=True)#
Rotates object using angle-axis input.
Terminology for move/rotate methods:
path refers to position and orientation of an object.
When an input is just a single operation (e.g. one displacement vector or one angle) we call it ‘scalar input’. When it is an array_like of multiple scalars, we refer to it as ‘vector input’.
General move/rotate behavior:
Scalar input is applied to the whole object path, starting with path index start.
Vector input of length n applies the individual n operations to n object path entries, starting with path index start.
When an input extends beyond the object path, the object path will be padded by its edge-entries before the operation is applied.
By default (start=’auto’) the index is set to start=0 for scalar input [=move whole object path], and to start=len(object path) for vector input [=append to existing object path].
- Parameters
angle (int, float or array_like with shape (n,)) – Angle(s) of rotation 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, 0 or array_like with shape (3,) or (n,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=`'auto'`) – Starting index when applying operations. See ‘General move/rotate behavior’ above for details.
degrees (bool, default=`True`) – Interpret input in units of deg or rad.
- Returns
self
- Return type
Magpylib object
Examples
Rotate an object about the origin:
>>> import magpylib as magpy >>> sens = magpy.Sensor(position=(1,0,0)) >>> sens.rotate_from_angax(45, axis='z', anchor=0) Sensor(id=...) >>> print(sens.position) [0.70710678 0.70710678 0. ] >>> print(sens.orientation.as_euler('xyz', degrees=True)) [ 0. 0. 45.]
Rotate the object about itself:
>>> sens.rotate_from_angax(45, axis=(0,0,1)) Sensor(id=...) >>> print(sens.position) [0.70710678 0.70710678 0. ] >>> print(sens.orientation.as_euler('xyz', degrees=True)) [ 0. 0. 90.]
Create a rotation path by rotating in several steps about an anchor:
>>> sens.rotate_from_angax((15,30,45), axis='z', anchor=(0,0,0)) Sensor(id=...) >>> print(sens.position) [[ 7.07106781e-01 7.07106781e-01 0.00000000e+00] [ 5.00000000e-01 8.66025404e-01 0.00000000e+00] [ 2.58819045e-01 9.65925826e-01 0.00000000e+00] [-2.22044605e-16 1.00000000e+00 0.00000000e+00]] >>> print(sens.orientation.as_euler('xyz', degrees=True)) [[ 0. 0. 90.] [ 0. 0. 105.] [ 0. 0. 120.] [ 0. 0. 135.]]
- rotate_from_euler(angle, seq, anchor=None, start='auto', degrees=True)#
Rotates object using Euler angle input.
Terminology for move/rotate methods:
path refers to position and orientation of an object.
When an input is just a single operation (e.g. one displacement vector or one angle) we call it ‘scalar input’. When it is an array_like of multiple scalars, we refer to it as ‘vector input’.
General move/rotate behavior:
Scalar input is applied to the whole object path, starting with path index start.
Vector input of length n applies the individual n operations to n object path entries, starting with path index start.
When an input extends beyond the object path, the object path will be padded by its edge-entries before the operation is applied.
By default (start=’auto’) the index is set to start=0 for scalar input [=move whole object path], and to start=len(object path) for vector input [=append to existing object path].
- Parameters
angle (int, float or array_like with shape (n,)) – Angle(s) of rotation in units of deg (by default).
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.
anchor (None, 0 or array_like with shape (3,) or (n,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=`'auto'`) – Starting index when applying operations. See ‘General move/rotate behavior’ above for details.
degrees (bool, default=`True`) – Interpret input in units of deg or rad.
- Returns
self
- Return type
Magpylib object
Examples
Rotate an object about the origin:
>>> import magpylib as magpy >>> sens = magpy.Sensor(position=(1,0,0)) >>> sens.rotate_from_euler(45, 'z', anchor=0) Sensor... >>> print(sens.position) [0.70710678 0.70710678 0. ] >>> print(sens.orientation.as_euler('xyz', degrees=True)) [ 0. 0. 45.]
Rotate the object about itself:
>>> sens.rotate_from_euler(45, 'z') Sensor(id=...) >>> print(sens.position) [0.70710678 0.70710678 0. ] >>> print(sens.orientation.as_euler('xyz', degrees=True)) [ 0. 0. 90.]
Create a rotation path by rotating in several steps about an anchor:
>>> sens.rotate_from_euler((15,30,45), 'z', anchor=(0,0,0)) Sensor(id=...) >>> print(sens.position) [[ 7.07106781e-01 7.07106781e-01 0.00000000e+00] [ 5.00000000e-01 8.66025404e-01 0.00000000e+00] [ 2.58819045e-01 9.65925826e-01 0.00000000e+00] [-2.22044605e-16 1.00000000e+00 0.00000000e+00]] >>> print(sens.orientation.as_euler('xyz', degrees=True)) [[ 0. 0. 90.] [ 0. 0. 105.] [ 0. 0. 120.] [ 0. 0. 135.]]
- rotate_from_matrix(matrix, anchor=None, start='auto')#
Rotates object using matrix input.
Terminology for move/rotate methods:
path refers to position and orientation of an object.
When an input is just a single operation (e.g. one displacement vector or one angle) we call it ‘scalar input’. When it is an array_like of multiple scalars, we refer to it as ‘vector input’.
General move/rotate behavior:
Scalar input is applied to the whole object path, starting with path index start.
Vector input of length n applies the individual n operations to n object path entries, starting with path index start.
When an input extends beyond the object path, the object path will be padded by its edge-entries before the operation is applied.
By default (start=’auto’) the index is set to start=0 for scalar input [=move whole object path], and to start=len(object path) for vector input [=append to existing object path].
- Parameters
matrix (array_like, shape (n,3,3) or (3,3)) – Rotation input. See scipy.spatial.transform.Rotation for details.
anchor (None, 0 or array_like with shape (3,) or (n,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=`'auto'`) – Starting index when applying operations. See ‘General move/rotate behavior’ above for details.
- Returns
self
- Return type
Magpylib object
Examples
Rotate an object about the origin:
>>> import magpylib as magpy >>> sens = magpy.Sensor(position=(1,0,0)) >>> sens.rotate_from_matrix([(0,-1,0),(1,0,0),(0,0,1)], anchor=0) Sensor(id=...) >>> print(sens.position) [0. 1. 0.] >>> print(sens.orientation.as_euler('xyz', degrees=True)) [ 0. 0. 90.]
Rotate the object about itself:
>>> sens.rotate_from_matrix([(0,-1,0),(1,0,0),(0,0,1)]) Sensor(id=...) >>> print(sens.position) [0. 1. 0.] >>> print(sens.orientation.as_euler('xyz', degrees=True)) [ 0. 0. 180.]
- rotate_from_mrp(mrp, anchor=None, start='auto')#
Rotates object using Modified Rodrigues Parameters (MRPs) input.
Terminology for move/rotate methods:
path refers to position and orientation of an object.
When an input is just a single operation (e.g. one displacement vector or one angle) we call it ‘scalar input’. When it is an array_like of multiple scalars, we refer to it as ‘vector input’.
General move/rotate behavior:
Scalar input is applied to the whole object path, starting with path index start.
Vector input of length n applies the individual n operations to n object path entries, starting with path index start.
When an input extends beyond the object path, the object path will be padded by its edge-entries before the operation is applied.
By default (start=’auto’) the index is set to start=0 for scalar input [=move whole object path], and to start=len(object path) for vector input [=append to existing object path].
- Parameters
mrp (array_like, shape (n,3) or (3,)) – Rotation input. See scipy Rotation package for details on Modified Rodrigues Parameters (MRPs).
anchor (None, 0 or array_like with shape (3,) or (n,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=`'auto'`) – Starting index when applying operations. See ‘General move/rotate behavior’ above for details.
- Returns
self
- Return type
Magpylib object
Examples
Rotate an object about the origin:
>>> import magpylib as magpy >>> sens = magpy.Sensor(position=(1,0,0)) >>> sens.rotate_from_mrp((0,0,1), anchor=0) Sensor(id=...) >>> print(sens.position) [-1. 0. 0.] >>> print(sens.orientation.as_euler('xyz', degrees=True)) [ 0. 0. 180.]
Rotate the object about itself:
>>> sens.rotate_from_matrix([(0,-1,0),(1,0,0),(0,0,1)]) Sensor(id=...) >>> print(sens.position) [-1. 0. 0.] >>> print(sens.orientation.as_euler('xyz', degrees=True)) [ 0. 0. -90.]
- rotate_from_quat(quat, anchor=None, start='auto')#
Rotates object using quaternion input.
Terminology for move/rotate methods:
path refers to position and orientation of an object.
When an input is just a single operation (e.g. one displacement vector or one angle) we call it ‘scalar input’. When it is an array_like of multiple scalars, we refer to it as ‘vector input’.
General move/rotate behavior:
Scalar input is applied to the whole object path, starting with path index start.
Vector input of length n applies the individual n operations to n object path entries, starting with path index start.
When an input extends beyond the object path, the object path will be padded by its edge-entries before the operation is applied.
By default (start=’auto’) the index is set to start=0 for scalar input [=move whole object path], and to start=len(object path) for vector input [=append to existing object path].
- Parameters
quat (array_like, shape (n,4) or (4,)) – Rotation input in quaternion form.
anchor (None, 0 or array_like with shape (3,) or (n,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=`'auto'`) – Starting index when applying operations. See ‘General move/rotate behavior’ above for details.
- Returns
self
- Return type
Magpylib object
Examples
Rotate an object about the origin:
>>> import magpylib as magpy >>> sens = magpy.Sensor(position=(1,0,0)) >>> sens.rotate_from_quat((0,0,1,1), anchor=0) Sensor(id=...) >>> print(sens.position) [0. 1. 0.] >>> print(sens.orientation.as_euler('xyz', degrees=True)) [ 0. 0. 90.]
Rotate the object about itself:
>>> sens.rotate_from_quat((0,0,1,1)) Sensor(id=...) >>> print(sens.position) [0. 1. 0.] >>> print(sens.orientation.as_euler('xyz', degrees=True)) [ 0. 0. 180.]
- rotate_from_rotvec(rotvec, anchor=None, start='auto', degrees=True)#
Rotates object using rotation vector input.
Terminology for move/rotate methods:
path refers to position and orientation of an object.
When an input is just a single operation (e.g. one displacement vector or one angle) we call it ‘scalar input’. When it is an array_like of multiple scalars, we refer to it as ‘vector input’.
General move/rotate behavior:
Scalar input is applied to the whole object path, starting with path index start.
Vector input of length n applies the individual n operations to n object path entries, starting with path index start.
When an input extends beyond the object path, the object path will be padded by its edge-entries before the operation is applied.
By default (start=’auto’) the index is set to start=0 for scalar input [=move whole object path], and to start=len(object path) for vector input [=append to existing object path].
- Parameters
rotvec (array_like, shape (n,3) or (3,)) – Rotation input. Rotation vector direction is the rotation axis, vector length is the rotation angle in units of rad.
anchor (None, 0 or array_like with shape (3,) or (n,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=`'auto'`) – Starting index when applying operations. See ‘General move/rotate behavior’ above for details.
degrees (bool, default=`True`) – Interpret input in units of deg or rad.
- Returns
self
- Return type
Magpylib object
Examples
Rotate an object about the origin:
>>> import magpylib as magpy >>> sens = magpy.Sensor(position=(1,0,0)) >>> sens.rotate_from_rotvec((0,0,45), anchor=0) Sensor(id=...) >>> print(sens.position) [0.70710678 0.70710678 0. ] >>> print(sens.orientation.as_euler('xyz', degrees=True)) [ 0. 0. 45.]
Rotate the object about itself:
>>> sens.rotate_from_rotvec((0,0,45)) Sensor(id=...) >>> print(sens.position) [0.70710678 0.70710678 0. ] >>> print(sens.orientation.as_euler('xyz', degrees=True)) [ 0. 0. 90.]
Create a rotation path by rotating in several steps about an anchor:
>>> sens.rotate_from_rotvec([(0,0,15), (0,0,30), (0,0,45)], anchor=(0,0,0)) Sensor(id=...) >>> print(sens.position) [[ 7.07106781e-01 7.07106781e-01 0.00000000e+00] [ 5.00000000e-01 8.66025404e-01 0.00000000e+00] [ 2.58819045e-01 9.65925826e-01 0.00000000e+00] [-2.22044605e-16 1.00000000e+00 0.00000000e+00]] >>> print(sens.orientation.as_euler('xyz', degrees=True)) [[ 0. 0. 90.] [ 0. 0. 105.] [ 0. 0. 120.] [ 0. 0. 135.]]
- show(*, backend=<default>, canvas=<default>, animation=<default>, zoom=<default>, markers=<default>, return_fig=<default>, row=<default>, col=<default>, output=<default>, sumup=<default>, pixel_agg=<default>, style=<default>, **kwargs)#
Display objects and paths graphically.
Global graphic styles can be set with kwargs as style dictionary or using style underscore magic.
- Parameters
objects (Magpylib objects (sources, collections, sensors)) – Objects to be displayed.
backend (string, default=`None`) – Define plotting backend. Must be one of [‘auto’, ‘matplotlib’, ‘plotly’, ‘pyvista’]. If not set, parameter will default to magpylib.defaults.display.backend which is ‘auto’ by installation default. With ‘auto’, the backend defaults to ‘plotly’ if plotly is installed and the function is called in an IPython environment, otherwise defaults to ‘matplotlib’ which comes installed with magpylib. If the canvas is set, the backend defaults to the one corresponding to the canvas object (see canvas parameter).
canvas (matplotlib.pyplot AxesSubplot or plotly Figure object, default=`None`) – Display graphical output on a given canvas: - with matplotlib: matplotlib.axes.Axes with projection=3d. - with plotly: `plotly.graph_objects.Figure or plotly.graph_objects.FigureWidget. - with pyvista: pyvista.Plotter. By default a new canvas is created and immediately displayed.
animation (bool or float, default=`False`) – If True and at least one object has a path, the paths are rendered. If input is a positive float, the animation time is set to the given value. This feature is only available for the plotly backend.
zoom (float, default=`0`) – Adjust plot zoom-level. When zoom=0 3D-figure boundaries are tight.
markers (array_like, shape (n,3), default=`None`) – Display position markers in the global coordinate system.
return_fig (bool, default=False) –
If True, the function call returns the figure object.
with matplotlib: matplotlib.figure.Figure.
with plotly: plotly.graph_objects.Figure or plotly.graph_objects.FigureWidget.
with pyvista: pyvista.Plotter.
row (int or None,) – If provided specifies the row in which the objects will be displayed.
col (int or None,) – If provided specifies the column in which the objects will be displayed.
output (tuple or string, default="model3d") – Can be a string or a tuple of strings specifying the plot output type. By default output=’model3d’ displays the 3D representations of the objects. If output is a tuple of strings it must be a combination of ‘B’ or ‘H’ and ‘x’, ‘y’ and/or ‘z’. When having multiple coordinates, the field value is the combined vector length (e.g. (‘Bx’, ‘Hxy’, ‘Byz’)) ‘Bxy’ is equivalent to sqrt(|Bx|^2 + |By|^2). A 2D line plot is then represented accordingly if the objects contain at least one source and one sensor.
sumup (bool, default=True) – If True, sums the field values of the sources. Applies only if output is not ‘model3d’.
pixel_agg (bool, default="mean") – Reference to a compatible numpy aggregator function like ‘min’ or ‘mean’, which is applied to observer output values, e.g. mean of all sensor pixel outputs. Applies only if output is not ‘model3d’.
style (dict) – Object style inputs must be in dictionary form, e.g. {‘color’:’red’} or using style underscore magic, e.g. style_color=’red’. Applies to all objects matching the given style properties.
- Return type
None or figure object
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([(0.1*x,0,0) for x in range(50)]) Sphere... >>> src.rotate_from_angax(angle=[*range(0,400,10)], axis='z', anchor=0, start=11) Sphere... >>> ts = [-.4,0,.4] >>> sens = magpy.Sensor(position=(0,0,2), pixel=[(x,y,0) for x in ts for y in ts]) >>> magpy.show(src, sens) >>> magpy.show(src, sens, backend='plotly') >>> # graphic output
Display output on your own canvas (here a Matplotlib 3d-axes):
>>> 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.show(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, [(0,0,0), (0,0,3)]) >>> src2 = magpy.magnet.Sphere((1,1,1), 1, [(1,0,0), (1,0,3)], style_path_show=False) >>> magpy.defaults.display.style.magnet.magnetization.size = 2 >>> src1.style.magnetization.size = 1 >>> magpy.show(src1, src2, style_color='r') >>> # graphic output
Use a context manager to jointly animate 3d and 2d subplots
>>> import magpylib as magpy >>> import numpy as np >>> import plotly.graph_objects as go >>> path_len = 40 >>> sensor = magpy.Sensor() >>> cyl1 = magpy.magnet.Cylinder( ... magnetization=(100, 0, 0), ... dimension=(1, 2), ... position=(4, 0, 0), ... style_label="Cylinder1", ... ) >>> sensor.move(np.linspace((0, 0, -3), (0, 0, 3), path_len), start=0) Sensor(id=...) >>> cyl1.rotate_from_angax(angle=np.linspace(0, 300, path_len), start=0, axis="z", anchor=0) Cylinder(id=...) >>> cyl2 = cyl1.copy().move((0, 0, 5)) >>> fig = go.Figure() >>> with magpy.show_context(cyl1, cyl2, sensor, canvas=fig, backend="plotly", animation=True): ... magpy.show(col=1, output="model3d") ... magpy.show(col=2, output="Bxy", sumup=True) ... magpy.show(col=3, output="Bz", sumup=False) >>> fig.show() >>> # graphic output
- property style#
Object style in the form of a BaseStyle object. Input must be in the form of a style dictionary.
- class magpylib.magnet.Sphere(magnetization=None, diameter=None, position=(0, 0, 0), orientation=None, style=None, **kwargs)#
Bases:
BaseMagnetSpherical magnet with homogeneous magnetization.
Can be used as sources input for magnetic field computation.
When position=(0,0,0) and orientation=None the sphere center is located in the origin of the global coordinate system.
- Parameters
magnetization (array_like, shape (3,), default=`None`) – Magnetization vector (mu0*M, remanence field) in units of mT given in the local object coordinates (rotates with object).
diameter (float, default=`None`) – Diameter of the sphere in units of mm.
position (array_like, shape (3,) or (m,3), default=`(0,0,0)`) – Object position(s) in the global coordinates in units of mm. For m>1, the position and orientation attributes together represent an object path.
orientation (scipy Rotation object with length 1 or m, default=`None`) – Object orientation(s) in the global coordinates. None corresponds to a unit-rotation. For m>1, the position and orientation attributes together represent an object path.
parent (Collection object or None) – The object is a child of it’s parent collection.
style (dict) – Object style inputs must be in dictionary form, e.g. {‘color’:’red’} or using style underscore magic, e.g. style_color=’red’.
- Returns
magnet source
- Return type
Sphere object
Examples
Sphere objects are magnetic field sources. In this example we compute the H-field kA/m of a spherical magnet with magnetization (100,200,300) in units of mT and diameter of 1 mm at the observer position (1,1,1) given in units of mm:
>>> import magpylib as magpy >>> src = magpy.magnet.Sphere(magnetization=(100,200,300), diameter=1) >>> H = src.getH((1,1,1)) >>> print(H) [3.19056074 2.55244859 1.91433644]
We rotate the source object, and compute the B-field, this time at a set of observer positions:
>>> src.rotate_from_angax(45, 'x') Sphere(id=...) >>> B = src.getB([(1,1,1), (2,2,2), (3,3,3)]) >>> print(B) [[2.26804606 3.63693295 0.23486386] [0.28350576 0.45461662 0.02935798] [0.08400171 0.13470122 0.00869866]]
The same result is obtained when the rotated source moves along a path away from an observer at position (1,1,1). This time we use a Sensor object as observer.
>>> src.move([(-1,-1,-1), (-2,-2,-2)]) Sphere(id=...) >>> sens = magpy.Sensor(position=(1,1,1)) >>> B = src.getB(sens) >>> print(B) [[2.26804606 3.63693295 0.23486386] [0.28350576 0.45461662 0.02935798] [0.08400171 0.13470122 0.00869866]]
- copy(**kwargs)#
Returns a copy of the current object instance. The copy method returns a deep copy of the object, that is independent of the original object.
- Parameters
kwargs (dict) – Keyword arguments (for example position=(1,2,3)) are applied to the copy.
Examples
Create a Sensor object and copy to an another position:
>>> import magpylib as magpy >>> sens1 = magpy.Sensor(style_label='sens1') >>> sens2 = sens1.copy(position=(2,6,10), style_label='sens2') >>> print(f"Instance {sens1.style.label} with position {sens1.position}.") Instance sens1 with position [0. 0. 0.]. >>> print(f"Instance {sens2.style.label} with position {sens2.position}.") Instance sens2 with position [ 2. 6. 10.].
- describe(*, exclude=('style', 'field_func'), return_string=False)#
Returns a view of the object properties.
- Parameters
exclude (bool, default=("style",)) – Properties to be excluded in the description view.
return_string (bool, default=`False`) – If False print description with stdout, if True return as string.
- property diameter#
Diameter of the sphere in units of mm.
- property field_func#
The function for B- and H-field computation must have the two positional arguments field and observers. With field=’B’ or field=’H’ the B- or H-field in units of mT or kA/m must be returned respectively. The observers argument must accept numpy ndarray inputs of shape (n,3), in which case the returned fields must be numpy ndarrays of shape (n,3) themselves.
- getB(*observers, squeeze=True, pixel_agg=None, output='ndarray')#
Compute the B-field in units of mT generated by the source.
- Parameters
observers (array_like or (list of) Sensor objects) – Can be array_like positions of shape (n1, n2, …, 3) where the field should be evaluated, a Sensor object with pixel shape (n1, n2, …, 3) or a list of such sensor objects (must all have similar pixel shapes). All positions are given in units of mm.
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.
pixel_agg (str, default=`None`) – Reference to a compatible numpy aggregator function like ‘min’ or ‘mean’, which is applied to observer output values, e.g. mean of all sensor pixel outputs. With this option, observers input with different (pixel) shapes is allowed.
output (str, default='ndarray') – Output type, which must be one of (‘ndarray’, ‘dataframe’). By default a multi- dimensional array (‘ndarray’) is returned. If ‘dataframe’ is chosen, the function returns a 2D-table as a pandas.DataFrame object (the Pandas library must be installed).
- 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) or DataFrame
Examples
Compute the B-field of a spherical magnet at three positions:
>>> import magpylib as magpy >>> src = magpy.magnet.Sphere((0,0,1000), 1) >>> B = src.getB(((0,0,0), (1,0,0), (2,0,0))) >>> print(B) [[ 0. 0. 666.66666667] [ 0. 0. -41.66666667] [ 0. 0. -5.20833333]]
Compute the B-field at two sensors, each one with two pixels
>>> sens1 = magpy.Sensor(position=(1,0,0), pixel=((0,0,.1), (0,0,-.1))) >>> sens2 = sens1.copy(position=(2,0,0)) >>> B = src.getB(sens1, sens2) >>> print(B) [[[ 12.19288783 0. -39.83010025] [-12.19288783 0. -39.83010025]] [[ 0.77638847 0. -5.15004352] [ -0.77638847 0. -5.15004352]]]
- getH(*observers, squeeze=True, pixel_agg=None, output='ndarray')#
Compute the H-field in units of kA/m generated by the source.
- Parameters
observers (array_like or (list of) Sensor objects) – Can be array_like positions of shape (n1, n2, …, 3) where the field should be evaluated, a Sensor object with pixel shape (n1, n2, …, 3) or a list of such sensor objects (must all have similar pixel shapes). All positions are given in units of mm.
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.
pixel_agg (str, default=`None`) – Reference to a compatible numpy aggregator function like ‘min’ or ‘mean’, which is applied to observer output values, e.g. mean of all sensor pixel outputs. With this option, observers input with different (pixel) shapes is allowed.
output (str, default='ndarray') – Output type, which must be one of (‘ndarray’, ‘dataframe’). By default a multi- dimensional array (‘ndarray’) is returned. If ‘dataframe’ is chosen, the function returns a 2D-table as a pandas.DataFrame object (the Pandas library must be installed).
- 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) or DataFrame
Examples
Compute the H-field of a spherical magnet at three positions:
>>> import magpylib as magpy
>>> src = magpy.magnet.Sphere((0,0,1000), 1) >>> H = src.getH(((0,0,0), (1,0,0), (2,0,0))) >>> print(H) [[ 0. 0. -265.25823849] [ 0. 0. -33.15727981] [ 0. 0. -4.14465998]]
Compute the H-field at two sensors, each one with two pixels
>>> sens1 = magpy.Sensor(position=(1,0,0), pixel=((0,0,.1), (0,0,-.1))) >>> sens2 = sens1.copy(position=(2,0,0)) >>> H = src.getH(sens1, sens2) >>> print(H) [[[ 9.70279185 0. -31.69578669] [ -9.70279185 0. -31.69578669]] [[ 0.61783031 0. -4.09827441] [ -0.61783031 0. -4.09827441]]]
- get_trace(vertices=15, **kwargs) Dict[str, Any]#
Create the plotly mesh3d parameters for a Sphere Magnet in a dictionary based on the provided arguments.
- property magnetization#
Object magnetization attribute getter and setter.
- move(displacement, start='auto')#
Move object by the displacement input.
Terminology for move/rotate methods:
path refers to position and orientation of an object.
When an input is just a single operation (e.g. one displacement vector or one angle) we call it ‘scalar input’. When it is an array_like of multiple scalars, we refer to it as ‘vector input’.
General move/rotate behavior:
Scalar input is applied to the whole object path, starting with path index start.
Vector input of length n applies the individual n operations to n object path entries, starting with path index start.
When an input extends beyond the object path, the object path will be padded by its edge-entries before the operation is applied.
By default (start=’auto’) the index is set to start=0 for scalar input [=move whole object path], and to start=len(object path) for vector input [=append to existing object path].
- Parameters
displacement (array_like, shape (3,) or (n,3)) – Displacement vector in units of mm.
start (int or str, default=`'auto'`) – Starting index when applying operations. See ‘General move/rotate behavior’ above for details.
- Returns
self
- Return type
Magpylib object
Examples
Move objects around with scalar input:
>>> import magpylib as magpy >>> sens = magpy.Sensor(position=(1,1,1)) >>> print(sens.position) [1. 1. 1.] >>> sens.move((1,1,1)) Sensor(id=...) >>> print(sens.position) [2. 2. 2.]
Create len>1 object paths with vector input:
>>> sens.move([(1,1,1),(2,2,2),(3,3,3)]) Sensor(id=...) >>> print(sens.position) [[2. 2. 2.] [3. 3. 3.] [4. 4. 4.] [5. 5. 5.]]
Apply operations starting with a designated path index:
>>> sens.move((0,0,2), start=2) Sensor(id=...) >>> print(sens.position) [[2. 2. 2.] [3. 3. 3.] [4. 4. 6.] [5. 5. 7.]]
- property orientation#
Object orientation(s) in the global coordinates. None corresponds to a unit-rotation. For m>1, the position and orientation attributes together represent an object path.
- property parent#
The object is a child of it’s parent collection.
- property position#
Object position(s) in the global coordinates in units of mm. For m>1, the position and orientation attributes together represent an object path.
- reset_path()#
Set object position to (0,0,0) and orientation = unit rotation.
- Returns
self
- Return type
magpylib object
Examples
Demonstration of reset_path functionality:
>>> import magpylib as magpy >>> obj = magpy.Sensor(position=(1,2,3)) >>> obj.rotate_from_angax(45, 'z') Sensor... >>> print(obj.position) [1. 2. 3.] >>> print(obj.orientation.as_euler('xyz', degrees=True)) [ 0. 0. 45.]
>>> obj.reset_path() Sensor(id=...) >>> print(obj.position) [0. 0. 0.] >>> print(obj.orientation.as_euler('xyz', degrees=True)) [0. 0. 0.]
- rotate(rotation: Rotation, anchor=None, start='auto')#
Rotate object about a given anchor.
Terminology for move/rotate methods:
path refers to position and orientation of an object.
When an input is just a single operation (e.g. one displacement vector or one angle) we call it ‘scalar input’. When it is an array_like of multiple scalars, we refer to it as ‘vector input’.
General move/rotate behavior:
Scalar input is applied to the whole object path, starting with path index start.
Vector input of length n applies the individual n operations to n object path entries, starting with path index start.
When an input extends beyond the object path, the object path will be padded by its edge-entries before the operation is applied.
By default (start=’auto’) the index is set to start=0 for scalar input [=move whole object path], and to start=len(object path) for vector input [=append to existing object path].
- Parameters
rotation (None or scipy Rotation object) – Rotation to be applied to the object. The scipy Rotation input can be scalar or vector type (see terminology above). None input is interpreted as unit rotation.
anchor (None, 0 or array_like with shape (3,) or (n,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=`'auto'`) – Starting index when applying operations. See ‘General move/rotate behavior’ above for details.
- Returns
self
- Return type
Magpylib object
Examples
Rotate an object about the origin:
>>> from scipy.spatial.transform import Rotation as R >>> import magpylib as magpy >>> sens = magpy.Sensor(position=(1,0,0)) >>> sens.rotate(R.from_euler('z', 45, degrees=True), anchor=0) Sensor(id=...) >>> print(sens.position) [0.70710678 0.70710678 0. ] >>> print(sens.orientation.as_euler('xyz', degrees=True)) [ 0. 0. 45.]
Rotate the object about itself:
>>> sens.rotate(R.from_euler('z', 45, degrees=True)) Sensor(id=...) >>> print(sens.position) [0.70710678 0.70710678 0. ] >>> print(sens.orientation.as_euler('xyz', degrees=True)) [ 0. 0. 90.]
Create a rotation path by rotating in several steps about an anchor:
>>> sens.rotate(R.from_euler('z', (15,30,45), degrees=True), anchor=(0,0,0)) Sensor(id=...) >>> print(sens.position) [[ 7.07106781e-01 7.07106781e-01 0.00000000e+00] [ 5.00000000e-01 8.66025404e-01 0.00000000e+00] [ 2.58819045e-01 9.65925826e-01 0.00000000e+00] [-2.22044605e-16 1.00000000e+00 0.00000000e+00]] >>> print(sens.orientation.as_euler('xyz', degrees=True)) [[ 0. 0. 90.] [ 0. 0. 105.] [ 0. 0. 120.] [ 0. 0. 135.]]
- rotate_from_angax(angle, axis, anchor=None, start='auto', degrees=True)#
Rotates object using angle-axis input.
Terminology for move/rotate methods:
path refers to position and orientation of an object.
When an input is just a single operation (e.g. one displacement vector or one angle) we call it ‘scalar input’. When it is an array_like of multiple scalars, we refer to it as ‘vector input’.
General move/rotate behavior:
Scalar input is applied to the whole object path, starting with path index start.
Vector input of length n applies the individual n operations to n object path entries, starting with path index start.
When an input extends beyond the object path, the object path will be padded by its edge-entries before the operation is applied.
By default (start=’auto’) the index is set to start=0 for scalar input [=move whole object path], and to start=len(object path) for vector input [=append to existing object path].
- Parameters
angle (int, float or array_like with shape (n,)) – Angle(s) of rotation 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, 0 or array_like with shape (3,) or (n,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=`'auto'`) – Starting index when applying operations. See ‘General move/rotate behavior’ above for details.
degrees (bool, default=`True`) – Interpret input in units of deg or rad.
- Returns
self
- Return type
Magpylib object
Examples
Rotate an object about the origin:
>>> import magpylib as magpy >>> sens = magpy.Sensor(position=(1,0,0)) >>> sens.rotate_from_angax(45, axis='z', anchor=0) Sensor(id=...) >>> print(sens.position) [0.70710678 0.70710678 0. ] >>> print(sens.orientation.as_euler('xyz', degrees=True)) [ 0. 0. 45.]
Rotate the object about itself:
>>> sens.rotate_from_angax(45, axis=(0,0,1)) Sensor(id=...) >>> print(sens.position) [0.70710678 0.70710678 0. ] >>> print(sens.orientation.as_euler('xyz', degrees=True)) [ 0. 0. 90.]
Create a rotation path by rotating in several steps about an anchor:
>>> sens.rotate_from_angax((15,30,45), axis='z', anchor=(0,0,0)) Sensor(id=...) >>> print(sens.position) [[ 7.07106781e-01 7.07106781e-01 0.00000000e+00] [ 5.00000000e-01 8.66025404e-01 0.00000000e+00] [ 2.58819045e-01 9.65925826e-01 0.00000000e+00] [-2.22044605e-16 1.00000000e+00 0.00000000e+00]] >>> print(sens.orientation.as_euler('xyz', degrees=True)) [[ 0. 0. 90.] [ 0. 0. 105.] [ 0. 0. 120.] [ 0. 0. 135.]]
- rotate_from_euler(angle, seq, anchor=None, start='auto', degrees=True)#
Rotates object using Euler angle input.
Terminology for move/rotate methods:
path refers to position and orientation of an object.
When an input is just a single operation (e.g. one displacement vector or one angle) we call it ‘scalar input’. When it is an array_like of multiple scalars, we refer to it as ‘vector input’.
General move/rotate behavior:
Scalar input is applied to the whole object path, starting with path index start.
Vector input of length n applies the individual n operations to n object path entries, starting with path index start.
When an input extends beyond the object path, the object path will be padded by its edge-entries before the operation is applied.
By default (start=’auto’) the index is set to start=0 for scalar input [=move whole object path], and to start=len(object path) for vector input [=append to existing object path].
- Parameters
angle (int, float or array_like with shape (n,)) – Angle(s) of rotation in units of deg (by default).
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.
anchor (None, 0 or array_like with shape (3,) or (n,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=`'auto'`) – Starting index when applying operations. See ‘General move/rotate behavior’ above for details.
degrees (bool, default=`True`) – Interpret input in units of deg or rad.
- Returns
self
- Return type
Magpylib object
Examples
Rotate an object about the origin:
>>> import magpylib as magpy >>> sens = magpy.Sensor(position=(1,0,0)) >>> sens.rotate_from_euler(45, 'z', anchor=0) Sensor... >>> print(sens.position) [0.70710678 0.70710678 0. ] >>> print(sens.orientation.as_euler('xyz', degrees=True)) [ 0. 0. 45.]
Rotate the object about itself:
>>> sens.rotate_from_euler(45, 'z') Sensor(id=...) >>> print(sens.position) [0.70710678 0.70710678 0. ] >>> print(sens.orientation.as_euler('xyz', degrees=True)) [ 0. 0. 90.]
Create a rotation path by rotating in several steps about an anchor:
>>> sens.rotate_from_euler((15,30,45), 'z', anchor=(0,0,0)) Sensor(id=...) >>> print(sens.position) [[ 7.07106781e-01 7.07106781e-01 0.00000000e+00] [ 5.00000000e-01 8.66025404e-01 0.00000000e+00] [ 2.58819045e-01 9.65925826e-01 0.00000000e+00] [-2.22044605e-16 1.00000000e+00 0.00000000e+00]] >>> print(sens.orientation.as_euler('xyz', degrees=True)) [[ 0. 0. 90.] [ 0. 0. 105.] [ 0. 0. 120.] [ 0. 0. 135.]]
- rotate_from_matrix(matrix, anchor=None, start='auto')#
Rotates object using matrix input.
Terminology for move/rotate methods:
path refers to position and orientation of an object.
When an input is just a single operation (e.g. one displacement vector or one angle) we call it ‘scalar input’. When it is an array_like of multiple scalars, we refer to it as ‘vector input’.
General move/rotate behavior:
Scalar input is applied to the whole object path, starting with path index start.
Vector input of length n applies the individual n operations to n object path entries, starting with path index start.
When an input extends beyond the object path, the object path will be padded by its edge-entries before the operation is applied.
By default (start=’auto’) the index is set to start=0 for scalar input [=move whole object path], and to start=len(object path) for vector input [=append to existing object path].
- Parameters
matrix (array_like, shape (n,3,3) or (3,3)) – Rotation input. See scipy.spatial.transform.Rotation for details.
anchor (None, 0 or array_like with shape (3,) or (n,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=`'auto'`) – Starting index when applying operations. See ‘General move/rotate behavior’ above for details.
- Returns
self
- Return type
Magpylib object
Examples
Rotate an object about the origin:
>>> import magpylib as magpy >>> sens = magpy.Sensor(position=(1,0,0)) >>> sens.rotate_from_matrix([(0,-1,0),(1,0,0),(0,0,1)], anchor=0) Sensor(id=...) >>> print(sens.position) [0. 1. 0.] >>> print(sens.orientation.as_euler('xyz', degrees=True)) [ 0. 0. 90.]
Rotate the object about itself:
>>> sens.rotate_from_matrix([(0,-1,0),(1,0,0),(0,0,1)]) Sensor(id=...) >>> print(sens.position) [0. 1. 0.] >>> print(sens.orientation.as_euler('xyz', degrees=True)) [ 0. 0. 180.]
- rotate_from_mrp(mrp, anchor=None, start='auto')#
Rotates object using Modified Rodrigues Parameters (MRPs) input.
Terminology for move/rotate methods:
path refers to position and orientation of an object.
When an input is just a single operation (e.g. one displacement vector or one angle) we call it ‘scalar input’. When it is an array_like of multiple scalars, we refer to it as ‘vector input’.
General move/rotate behavior:
Scalar input is applied to the whole object path, starting with path index start.
Vector input of length n applies the individual n operations to n object path entries, starting with path index start.
When an input extends beyond the object path, the object path will be padded by its edge-entries before the operation is applied.
By default (start=’auto’) the index is set to start=0 for scalar input [=move whole object path], and to start=len(object path) for vector input [=append to existing object path].
- Parameters
mrp (array_like, shape (n,3) or (3,)) – Rotation input. See scipy Rotation package for details on Modified Rodrigues Parameters (MRPs).
anchor (None, 0 or array_like with shape (3,) or (n,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=`'auto'`) – Starting index when applying operations. See ‘General move/rotate behavior’ above for details.
- Returns
self
- Return type
Magpylib object
Examples
Rotate an object about the origin:
>>> import magpylib as magpy >>> sens = magpy.Sensor(position=(1,0,0)) >>> sens.rotate_from_mrp((0,0,1), anchor=0) Sensor(id=...) >>> print(sens.position) [-1. 0. 0.] >>> print(sens.orientation.as_euler('xyz', degrees=True)) [ 0. 0. 180.]
Rotate the object about itself:
>>> sens.rotate_from_matrix([(0,-1,0),(1,0,0),(0,0,1)]) Sensor(id=...) >>> print(sens.position) [-1. 0. 0.] >>> print(sens.orientation.as_euler('xyz', degrees=True)) [ 0. 0. -90.]
- rotate_from_quat(quat, anchor=None, start='auto')#
Rotates object using quaternion input.
Terminology for move/rotate methods:
path refers to position and orientation of an object.
When an input is just a single operation (e.g. one displacement vector or one angle) we call it ‘scalar input’. When it is an array_like of multiple scalars, we refer to it as ‘vector input’.
General move/rotate behavior:
Scalar input is applied to the whole object path, starting with path index start.
Vector input of length n applies the individual n operations to n object path entries, starting with path index start.
When an input extends beyond the object path, the object path will be padded by its edge-entries before the operation is applied.
By default (start=’auto’) the index is set to start=0 for scalar input [=move whole object path], and to start=len(object path) for vector input [=append to existing object path].
- Parameters
quat (array_like, shape (n,4) or (4,)) – Rotation input in quaternion form.
anchor (None, 0 or array_like with shape (3,) or (n,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=`'auto'`) – Starting index when applying operations. See ‘General move/rotate behavior’ above for details.
- Returns
self
- Return type
Magpylib object
Examples
Rotate an object about the origin:
>>> import magpylib as magpy >>> sens = magpy.Sensor(position=(1,0,0)) >>> sens.rotate_from_quat((0,0,1,1), anchor=0) Sensor(id=...) >>> print(sens.position) [0. 1. 0.] >>> print(sens.orientation.as_euler('xyz', degrees=True)) [ 0. 0. 90.]
Rotate the object about itself:
>>> sens.rotate_from_quat((0,0,1,1)) Sensor(id=...) >>> print(sens.position) [0. 1. 0.] >>> print(sens.orientation.as_euler('xyz', degrees=True)) [ 0. 0. 180.]
- rotate_from_rotvec(rotvec, anchor=None, start='auto', degrees=True)#
Rotates object using rotation vector input.
Terminology for move/rotate methods:
path refers to position and orientation of an object.
When an input is just a single operation (e.g. one displacement vector or one angle) we call it ‘scalar input’. When it is an array_like of multiple scalars, we refer to it as ‘vector input’.
General move/rotate behavior:
Scalar input is applied to the whole object path, starting with path index start.
Vector input of length n applies the individual n operations to n object path entries, starting with path index start.
When an input extends beyond the object path, the object path will be padded by its edge-entries before the operation is applied.
By default (start=’auto’) the index is set to start=0 for scalar input [=move whole object path], and to start=len(object path) for vector input [=append to existing object path].
- Parameters
rotvec (array_like, shape (n,3) or (3,)) – Rotation input. Rotation vector direction is the rotation axis, vector length is the rotation angle in units of rad.
anchor (None, 0 or array_like with shape (3,) or (n,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=`'auto'`) – Starting index when applying operations. See ‘General move/rotate behavior’ above for details.
degrees (bool, default=`True`) – Interpret input in units of deg or rad.
- Returns
self
- Return type
Magpylib object
Examples
Rotate an object about the origin:
>>> import magpylib as magpy >>> sens = magpy.Sensor(position=(1,0,0)) >>> sens.rotate_from_rotvec((0,0,45), anchor=0) Sensor(id=...) >>> print(sens.position) [0.70710678 0.70710678 0. ] >>> print(sens.orientation.as_euler('xyz', degrees=True)) [ 0. 0. 45.]
Rotate the object about itself:
>>> sens.rotate_from_rotvec((0,0,45)) Sensor(id=...) >>> print(sens.position) [0.70710678 0.70710678 0. ] >>> print(sens.orientation.as_euler('xyz', degrees=True)) [ 0. 0. 90.]
Create a rotation path by rotating in several steps about an anchor:
>>> sens.rotate_from_rotvec([(0,0,15), (0,0,30), (0,0,45)], anchor=(0,0,0)) Sensor(id=...) >>> print(sens.position) [[ 7.07106781e-01 7.07106781e-01 0.00000000e+00] [ 5.00000000e-01 8.66025404e-01 0.00000000e+00] [ 2.58819045e-01 9.65925826e-01 0.00000000e+00] [-2.22044605e-16 1.00000000e+00 0.00000000e+00]] >>> print(sens.orientation.as_euler('xyz', degrees=True)) [[ 0. 0. 90.] [ 0. 0. 105.] [ 0. 0. 120.] [ 0. 0. 135.]]
- show(*, backend=<default>, canvas=<default>, animation=<default>, zoom=<default>, markers=<default>, return_fig=<default>, row=<default>, col=<default>, output=<default>, sumup=<default>, pixel_agg=<default>, style=<default>, **kwargs)#
Display objects and paths graphically.
Global graphic styles can be set with kwargs as style dictionary or using style underscore magic.
- Parameters
objects (Magpylib objects (sources, collections, sensors)) – Objects to be displayed.
backend (string, default=`None`) – Define plotting backend. Must be one of [‘auto’, ‘matplotlib’, ‘plotly’, ‘pyvista’]. If not set, parameter will default to magpylib.defaults.display.backend which is ‘auto’ by installation default. With ‘auto’, the backend defaults to ‘plotly’ if plotly is installed and the function is called in an IPython environment, otherwise defaults to ‘matplotlib’ which comes installed with magpylib. If the canvas is set, the backend defaults to the one corresponding to the canvas object (see canvas parameter).
canvas (matplotlib.pyplot AxesSubplot or plotly Figure object, default=`None`) – Display graphical output on a given canvas: - with matplotlib: matplotlib.axes.Axes with projection=3d. - with plotly: `plotly.graph_objects.Figure or plotly.graph_objects.FigureWidget. - with pyvista: pyvista.Plotter. By default a new canvas is created and immediately displayed.
animation (bool or float, default=`False`) – If True and at least one object has a path, the paths are rendered. If input is a positive float, the animation time is set to the given value. This feature is only available for the plotly backend.
zoom (float, default=`0`) – Adjust plot zoom-level. When zoom=0 3D-figure boundaries are tight.
markers (array_like, shape (n,3), default=`None`) – Display position markers in the global coordinate system.
return_fig (bool, default=False) –
If True, the function call returns the figure object.
with matplotlib: matplotlib.figure.Figure.
with plotly: plotly.graph_objects.Figure or plotly.graph_objects.FigureWidget.
with pyvista: pyvista.Plotter.
row (int or None,) – If provided specifies the row in which the objects will be displayed.
col (int or None,) – If provided specifies the column in which the objects will be displayed.
output (tuple or string, default="model3d") – Can be a string or a tuple of strings specifying the plot output type. By default output=’model3d’ displays the 3D representations of the objects. If output is a tuple of strings it must be a combination of ‘B’ or ‘H’ and ‘x’, ‘y’ and/or ‘z’. When having multiple coordinates, the field value is the combined vector length (e.g. (‘Bx’, ‘Hxy’, ‘Byz’)) ‘Bxy’ is equivalent to sqrt(|Bx|^2 + |By|^2). A 2D line plot is then represented accordingly if the objects contain at least one source and one sensor.
sumup (bool, default=True) – If True, sums the field values of the sources. Applies only if output is not ‘model3d’.
pixel_agg (bool, default="mean") – Reference to a compatible numpy aggregator function like ‘min’ or ‘mean’, which is applied to observer output values, e.g. mean of all sensor pixel outputs. Applies only if output is not ‘model3d’.
style (dict) – Object style inputs must be in dictionary form, e.g. {‘color’:’red’} or using style underscore magic, e.g. style_color=’red’. Applies to all objects matching the given style properties.
- Return type
None or figure object
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([(0.1*x,0,0) for x in range(50)]) Sphere... >>> src.rotate_from_angax(angle=[*range(0,400,10)], axis='z', anchor=0, start=11) Sphere... >>> ts = [-.4,0,.4] >>> sens = magpy.Sensor(position=(0,0,2), pixel=[(x,y,0) for x in ts for y in ts]) >>> magpy.show(src, sens) >>> magpy.show(src, sens, backend='plotly') >>> # graphic output
Display output on your own canvas (here a Matplotlib 3d-axes):
>>> 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.show(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, [(0,0,0), (0,0,3)]) >>> src2 = magpy.magnet.Sphere((1,1,1), 1, [(1,0,0), (1,0,3)], style_path_show=False) >>> magpy.defaults.display.style.magnet.magnetization.size = 2 >>> src1.style.magnetization.size = 1 >>> magpy.show(src1, src2, style_color='r') >>> # graphic output
Use a context manager to jointly animate 3d and 2d subplots
>>> import magpylib as magpy >>> import numpy as np >>> import plotly.graph_objects as go >>> path_len = 40 >>> sensor = magpy.Sensor() >>> cyl1 = magpy.magnet.Cylinder( ... magnetization=(100, 0, 0), ... dimension=(1, 2), ... position=(4, 0, 0), ... style_label="Cylinder1", ... ) >>> sensor.move(np.linspace((0, 0, -3), (0, 0, 3), path_len), start=0) Sensor(id=...) >>> cyl1.rotate_from_angax(angle=np.linspace(0, 300, path_len), start=0, axis="z", anchor=0) Cylinder(id=...) >>> cyl2 = cyl1.copy().move((0, 0, 5)) >>> fig = go.Figure() >>> with magpy.show_context(cyl1, cyl2, sensor, canvas=fig, backend="plotly", animation=True): ... magpy.show(col=1, output="model3d") ... magpy.show(col=2, output="Bxy", sumup=True) ... magpy.show(col=3, output="Bz", sumup=False) >>> fig.show() >>> # graphic output
- property style#
Object style in the form of a BaseStyle object. Input must be in the form of a style dictionary.
- class magpylib.magnet.Tetrahedron(magnetization=None, vertices=None, position=(0, 0, 0), orientation=None, style=None, **kwargs)#
Bases:
BaseMagnetTetrahedron magnet with homogeneous magnetization.
Can be used as sources input for magnetic field computation.
When position=(0,0,0) and orientation=None the Tetrahedron vertices coordinates are the same as in the global coordinate system. The geometric center of the Tetrahedron is determined by its vertices and. It is not necessarily located in the origin an can be computed with the barycenter property.
- Parameters
magnetization (array_like, shape (3,), default=`None`) – Magnetization vector (mu0*M, remanence field) in units of mT given in the local object coordinates (rotates with object).
vertices (ndarray, shape (4,3)) – Vertices [(x1,y1,z1), (x2,y2,z2), (x3,y3,z3), (x4,y4,z4)], in the relative coordinate system of the tetrahedron.
position (array_like, shape (3,) or (m,3)) – Object position(s) in the global coordinates in units of mm. For m>1, the position and orientation attributes together represent an object path. When setting vertices, the initial position is set to the barycenter.
barycenter (array_like, shape (3,)) – Read only property that returns the geometric barycenter (=center of mass) of the object.
orientation (scipy Rotation object with length 1 or m, default=`None`) – Object orientation(s) in the global coordinates. None corresponds to a unit-rotation. For m>1, the position and orientation attributes together represent an object path.
parent (Collection object or None) – The object is a child of it’s parent collection.
style (dict) – Object style inputs must be in dictionary form, e.g. {‘color’:’red’} or using style underscore magic, e.g. style_color=’red’.
- Returns
magnet source
- Return type
Tetrahedron object
Examples
Tetrahedron magnets are magnetic field sources. Below we compute the H-field in kA/m of a tetrahedron magnet with magnetization (100,200,300) in units of mT dimensions defined through the vertices (0,0,0), (1,0,0), (0,1,0) and (0,0,1) in units of mm at the observer position (1,1,1) given in units of mm:
>>> import magpylib as magpy >>> verts = [(0,0,0), (1,0,0), (0,1,0), (0,0,1)] >>> src = magpy.magnet.Tetrahedron(magnetization=(100,200,300), vertices=verts) >>> H = src.getH((1,1,1)) >>> print(H) [2.07089783 1.65671826 1.2425387 ]
We rotate the source object, and compute the B-field, this time at a set of observer positions:
src.rotate_from_angax(45, ‘x’) Tetrahedron(id=…) B = src.getB([(1,1,1), (2,2,2), (3,3,3)]) print(B) [[ 8.68006559e-01 2.00895792e+00 -5.03469140e-01] [ 1.01357229e-01 1.93731796e-01 -1.59677364e-02] [ 2.90426931e-02 5.22556994e-02 -1.70596096e-03]]
The same result is obtained when the rotated source moves along a path away from an observer at position (1,1,1). Here we use a Sensor object as observer.
sens = magpy.Sensor(position=(1,1,1)) src.move([(-1,-1,-1), (-2,-2,-2)]) Sensor(id=…) B = src.getB(sens) print(B) [[ 8.68006559e-01 2.00895792e+00 -5.03469140e-01] [ 1.01357229e-01 1.93731796e-01 -1.59677364e-02] [ 2.90426931e-02 5.22556994e-02 -1.70596096e-03]]
- property barycenter#
Object barycenter.
- copy(**kwargs)#
Returns a copy of the current object instance. The copy method returns a deep copy of the object, that is independent of the original object.
- Parameters
kwargs (dict) – Keyword arguments (for example position=(1,2,3)) are applied to the copy.
Examples
Create a Sensor object and copy to an another position:
>>> import magpylib as magpy >>> sens1 = magpy.Sensor(style_label='sens1') >>> sens2 = sens1.copy(position=(2,6,10), style_label='sens2') >>> print(f"Instance {sens1.style.label} with position {sens1.position}.") Instance sens1 with position [0. 0. 0.]. >>> print(f"Instance {sens2.style.label} with position {sens2.position}.") Instance sens2 with position [ 2. 6. 10.].
- describe(*, exclude=('style', 'field_func'), return_string=False)#
Returns a view of the object properties.
- Parameters
exclude (bool, default=("style",)) – Properties to be excluded in the description view.
return_string (bool, default=`False`) – If False print description with stdout, if True return as string.
- property field_func#
The function for B- and H-field computation must have the two positional arguments field and observers. With field=’B’ or field=’H’ the B- or H-field in units of mT or kA/m must be returned respectively. The observers argument must accept numpy ndarray inputs of shape (n,3), in which case the returned fields must be numpy ndarrays of shape (n,3) themselves.
- getB(*observers, squeeze=True, pixel_agg=None, output='ndarray')#
Compute the B-field in units of mT generated by the source.
- Parameters
observers (array_like or (list of) Sensor objects) – Can be array_like positions of shape (n1, n2, …, 3) where the field should be evaluated, a Sensor object with pixel shape (n1, n2, …, 3) or a list of such sensor objects (must all have similar pixel shapes). All positions are given in units of mm.
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.
pixel_agg (str, default=`None`) – Reference to a compatible numpy aggregator function like ‘min’ or ‘mean’, which is applied to observer output values, e.g. mean of all sensor pixel outputs. With this option, observers input with different (pixel) shapes is allowed.
output (str, default='ndarray') – Output type, which must be one of (‘ndarray’, ‘dataframe’). By default a multi- dimensional array (‘ndarray’) is returned. If ‘dataframe’ is chosen, the function returns a 2D-table as a pandas.DataFrame object (the Pandas library must be installed).
- 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) or DataFrame
Examples
Compute the B-field of a spherical magnet at three positions:
>>> import magpylib as magpy >>> src = magpy.magnet.Sphere((0,0,1000), 1) >>> B = src.getB(((0,0,0), (1,0,0), (2,0,0))) >>> print(B) [[ 0. 0. 666.66666667] [ 0. 0. -41.66666667] [ 0. 0. -5.20833333]]
Compute the B-field at two sensors, each one with two pixels
>>> sens1 = magpy.Sensor(position=(1,0,0), pixel=((0,0,.1), (0,0,-.1))) >>> sens2 = sens1.copy(position=(2,0,0)) >>> B = src.getB(sens1, sens2) >>> print(B) [[[ 12.19288783 0. -39.83010025] [-12.19288783 0. -39.83010025]] [[ 0.77638847 0. -5.15004352] [ -0.77638847 0. -5.15004352]]]
- getH(*observers, squeeze=True, pixel_agg=None, output='ndarray')#
Compute the H-field in units of kA/m generated by the source.
- Parameters
observers (array_like or (list of) Sensor objects) – Can be array_like positions of shape (n1, n2, …, 3) where the field should be evaluated, a Sensor object with pixel shape (n1, n2, …, 3) or a list of such sensor objects (must all have similar pixel shapes). All positions are given in units of mm.
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.
pixel_agg (str, default=`None`) – Reference to a compatible numpy aggregator function like ‘min’ or ‘mean’, which is applied to observer output values, e.g. mean of all sensor pixel outputs. With this option, observers input with different (pixel) shapes is allowed.
output (str, default='ndarray') – Output type, which must be one of (‘ndarray’, ‘dataframe’). By default a multi- dimensional array (‘ndarray’) is returned. If ‘dataframe’ is chosen, the function returns a 2D-table as a pandas.DataFrame object (the Pandas library must be installed).
- 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) or DataFrame
Examples
Compute the H-field of a spherical magnet at three positions:
>>> import magpylib as magpy
>>> src = magpy.magnet.Sphere((0,0,1000), 1) >>> H = src.getH(((0,0,0), (1,0,0), (2,0,0))) >>> print(H) [[ 0. 0. -265.25823849] [ 0. 0. -33.15727981] [ 0. 0. -4.14465998]]
Compute the H-field at two sensors, each one with two pixels
>>> sens1 = magpy.Sensor(position=(1,0,0), pixel=((0,0,.1), (0,0,-.1))) >>> sens2 = sens1.copy(position=(2,0,0)) >>> H = src.getH(sens1, sens2) >>> print(H) [[[ 9.70279185 0. -31.69578669] [ -9.70279185 0. -31.69578669]] [[ 0.61783031 0. -4.09827441] [ -0.61783031 0. -4.09827441]]]
- get_trace(**kwargs) Dict[str, Any]#
Create the plotly mesh3d parameters for a Tetrahedron Magnet in a dictionary based on the provided arguments.
- property magnetization#
Object magnetization attribute getter and setter.
- move(displacement, start='auto')#
Move object by the displacement input.
Terminology for move/rotate methods:
path refers to position and orientation of an object.
When an input is just a single operation (e.g. one displacement vector or one angle) we call it ‘scalar input’. When it is an array_like of multiple scalars, we refer to it as ‘vector input’.
General move/rotate behavior:
Scalar input is applied to the whole object path, starting with path index start.
Vector input of length n applies the individual n operations to n object path entries, starting with path index start.
When an input extends beyond the object path, the object path will be padded by its edge-entries before the operation is applied.
By default (start=’auto’) the index is set to start=0 for scalar input [=move whole object path], and to start=len(object path) for vector input [=append to existing object path].
- Parameters
displacement (array_like, shape (3,) or (n,3)) – Displacement vector in units of mm.
start (int or str, default=`'auto'`) – Starting index when applying operations. See ‘General move/rotate behavior’ above for details.
- Returns
self
- Return type
Magpylib object
Examples
Move objects around with scalar input:
>>> import magpylib as magpy >>> sens = magpy.Sensor(position=(1,1,1)) >>> print(sens.position) [1. 1. 1.] >>> sens.move((1,1,1)) Sensor(id=...) >>> print(sens.position) [2. 2. 2.]
Create len>1 object paths with vector input:
>>> sens.move([(1,1,1),(2,2,2),(3,3,3)]) Sensor(id=...) >>> print(sens.position) [[2. 2. 2.] [3. 3. 3.] [4. 4. 4.] [5. 5. 5.]]
Apply operations starting with a designated path index:
>>> sens.move((0,0,2), start=2) Sensor(id=...) >>> print(sens.position) [[2. 2. 2.] [3. 3. 3.] [4. 4. 6.] [5. 5. 7.]]
- property orientation#
Object orientation(s) in the global coordinates. None corresponds to a unit-rotation. For m>1, the position and orientation attributes together represent an object path.
- property parent#
The object is a child of it’s parent collection.
- property position#
Object position(s) in the global coordinates in units of mm. For m>1, the position and orientation attributes together represent an object path.
- reset_path()#
Set object position to (0,0,0) and orientation = unit rotation.
- Returns
self
- Return type
magpylib object
Examples
Demonstration of reset_path functionality:
>>> import magpylib as magpy >>> obj = magpy.Sensor(position=(1,2,3)) >>> obj.rotate_from_angax(45, 'z') Sensor... >>> print(obj.position) [1. 2. 3.] >>> print(obj.orientation.as_euler('xyz', degrees=True)) [ 0. 0. 45.]
>>> obj.reset_path() Sensor(id=...) >>> print(obj.position) [0. 0. 0.] >>> print(obj.orientation.as_euler('xyz', degrees=True)) [0. 0. 0.]
- rotate(rotation: Rotation, anchor=None, start='auto')#
Rotate object about a given anchor.
Terminology for move/rotate methods:
path refers to position and orientation of an object.
When an input is just a single operation (e.g. one displacement vector or one angle) we call it ‘scalar input’. When it is an array_like of multiple scalars, we refer to it as ‘vector input’.
General move/rotate behavior:
Scalar input is applied to the whole object path, starting with path index start.
Vector input of length n applies the individual n operations to n object path entries, starting with path index start.
When an input extends beyond the object path, the object path will be padded by its edge-entries before the operation is applied.
By default (start=’auto’) the index is set to start=0 for scalar input [=move whole object path], and to start=len(object path) for vector input [=append to existing object path].
- Parameters
rotation (None or scipy Rotation object) – Rotation to be applied to the object. The scipy Rotation input can be scalar or vector type (see terminology above). None input is interpreted as unit rotation.
anchor (None, 0 or array_like with shape (3,) or (n,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=`'auto'`) – Starting index when applying operations. See ‘General move/rotate behavior’ above for details.
- Returns
self
- Return type
Magpylib object
Examples
Rotate an object about the origin:
>>> from scipy.spatial.transform import Rotation as R >>> import magpylib as magpy >>> sens = magpy.Sensor(position=(1,0,0)) >>> sens.rotate(R.from_euler('z', 45, degrees=True), anchor=0) Sensor(id=...) >>> print(sens.position) [0.70710678 0.70710678 0. ] >>> print(sens.orientation.as_euler('xyz', degrees=True)) [ 0. 0. 45.]
Rotate the object about itself:
>>> sens.rotate(R.from_euler('z', 45, degrees=True)) Sensor(id=...) >>> print(sens.position) [0.70710678 0.70710678 0. ] >>> print(sens.orientation.as_euler('xyz', degrees=True)) [ 0. 0. 90.]
Create a rotation path by rotating in several steps about an anchor:
>>> sens.rotate(R.from_euler('z', (15,30,45), degrees=True), anchor=(0,0,0)) Sensor(id=...) >>> print(sens.position) [[ 7.07106781e-01 7.07106781e-01 0.00000000e+00] [ 5.00000000e-01 8.66025404e-01 0.00000000e+00] [ 2.58819045e-01 9.65925826e-01 0.00000000e+00] [-2.22044605e-16 1.00000000e+00 0.00000000e+00]] >>> print(sens.orientation.as_euler('xyz', degrees=True)) [[ 0. 0. 90.] [ 0. 0. 105.] [ 0. 0. 120.] [ 0. 0. 135.]]
- rotate_from_angax(angle, axis, anchor=None, start='auto', degrees=True)#
Rotates object using angle-axis input.
Terminology for move/rotate methods:
path refers to position and orientation of an object.
When an input is just a single operation (e.g. one displacement vector or one angle) we call it ‘scalar input’. When it is an array_like of multiple scalars, we refer to it as ‘vector input’.
General move/rotate behavior:
Scalar input is applied to the whole object path, starting with path index start.
Vector input of length n applies the individual n operations to n object path entries, starting with path index start.
When an input extends beyond the object path, the object path will be padded by its edge-entries before the operation is applied.
By default (start=’auto’) the index is set to start=0 for scalar input [=move whole object path], and to start=len(object path) for vector input [=append to existing object path].
- Parameters
angle (int, float or array_like with shape (n,)) – Angle(s) of rotation 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, 0 or array_like with shape (3,) or (n,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=`'auto'`) – Starting index when applying operations. See ‘General move/rotate behavior’ above for details.
degrees (bool, default=`True`) – Interpret input in units of deg or rad.
- Returns
self
- Return type
Magpylib object
Examples
Rotate an object about the origin:
>>> import magpylib as magpy >>> sens = magpy.Sensor(position=(1,0,0)) >>> sens.rotate_from_angax(45, axis='z', anchor=0) Sensor(id=...) >>> print(sens.position) [0.70710678 0.70710678 0. ] >>> print(sens.orientation.as_euler('xyz', degrees=True)) [ 0. 0. 45.]
Rotate the object about itself:
>>> sens.rotate_from_angax(45, axis=(0,0,1)) Sensor(id=...) >>> print(sens.position) [0.70710678 0.70710678 0. ] >>> print(sens.orientation.as_euler('xyz', degrees=True)) [ 0. 0. 90.]
Create a rotation path by rotating in several steps about an anchor:
>>> sens.rotate_from_angax((15,30,45), axis='z', anchor=(0,0,0)) Sensor(id=...) >>> print(sens.position) [[ 7.07106781e-01 7.07106781e-01 0.00000000e+00] [ 5.00000000e-01 8.66025404e-01 0.00000000e+00] [ 2.58819045e-01 9.65925826e-01 0.00000000e+00] [-2.22044605e-16 1.00000000e+00 0.00000000e+00]] >>> print(sens.orientation.as_euler('xyz', degrees=True)) [[ 0. 0. 90.] [ 0. 0. 105.] [ 0. 0. 120.] [ 0. 0. 135.]]
- rotate_from_euler(angle, seq, anchor=None, start='auto', degrees=True)#
Rotates object using Euler angle input.
Terminology for move/rotate methods:
path refers to position and orientation of an object.
When an input is just a single operation (e.g. one displacement vector or one angle) we call it ‘scalar input’. When it is an array_like of multiple scalars, we refer to it as ‘vector input’.
General move/rotate behavior:
Scalar input is applied to the whole object path, starting with path index start.
Vector input of length n applies the individual n operations to n object path entries, starting with path index start.
When an input extends beyond the object path, the object path will be padded by its edge-entries before the operation is applied.
By default (start=’auto’) the index is set to start=0 for scalar input [=move whole object path], and to start=len(object path) for vector input [=append to existing object path].
- Parameters
angle (int, float or array_like with shape (n,)) – Angle(s) of rotation in units of deg (by default).
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.
anchor (None, 0 or array_like with shape (3,) or (n,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=`'auto'`) – Starting index when applying operations. See ‘General move/rotate behavior’ above for details.
degrees (bool, default=`True`) – Interpret input in units of deg or rad.
- Returns
self
- Return type
Magpylib object
Examples
Rotate an object about the origin:
>>> import magpylib as magpy >>> sens = magpy.Sensor(position=(1,0,0)) >>> sens.rotate_from_euler(45, 'z', anchor=0) Sensor... >>> print(sens.position) [0.70710678 0.70710678 0. ] >>> print(sens.orientation.as_euler('xyz', degrees=True)) [ 0. 0. 45.]
Rotate the object about itself:
>>> sens.rotate_from_euler(45, 'z') Sensor(id=...) >>> print(sens.position) [0.70710678 0.70710678 0. ] >>> print(sens.orientation.as_euler('xyz', degrees=True)) [ 0. 0. 90.]
Create a rotation path by rotating in several steps about an anchor:
>>> sens.rotate_from_euler((15,30,45), 'z', anchor=(0,0,0)) Sensor(id=...) >>> print(sens.position) [[ 7.07106781e-01 7.07106781e-01 0.00000000e+00] [ 5.00000000e-01 8.66025404e-01 0.00000000e+00] [ 2.58819045e-01 9.65925826e-01 0.00000000e+00] [-2.22044605e-16 1.00000000e+00 0.00000000e+00]] >>> print(sens.orientation.as_euler('xyz', degrees=True)) [[ 0. 0. 90.] [ 0. 0. 105.] [ 0. 0. 120.] [ 0. 0. 135.]]
- rotate_from_matrix(matrix, anchor=None, start='auto')#
Rotates object using matrix input.
Terminology for move/rotate methods:
path refers to position and orientation of an object.
When an input is just a single operation (e.g. one displacement vector or one angle) we call it ‘scalar input’. When it is an array_like of multiple scalars, we refer to it as ‘vector input’.
General move/rotate behavior:
Scalar input is applied to the whole object path, starting with path index start.
Vector input of length n applies the individual n operations to n object path entries, starting with path index start.
When an input extends beyond the object path, the object path will be padded by its edge-entries before the operation is applied.
By default (start=’auto’) the index is set to start=0 for scalar input [=move whole object path], and to start=len(object path) for vector input [=append to existing object path].
- Parameters
matrix (array_like, shape (n,3,3) or (3,3)) – Rotation input. See scipy.spatial.transform.Rotation for details.
anchor (None, 0 or array_like with shape (3,) or (n,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=`'auto'`) – Starting index when applying operations. See ‘General move/rotate behavior’ above for details.
- Returns
self
- Return type
Magpylib object
Examples
Rotate an object about the origin:
>>> import magpylib as magpy >>> sens = magpy.Sensor(position=(1,0,0)) >>> sens.rotate_from_matrix([(0,-1,0),(1,0,0),(0,0,1)], anchor=0) Sensor(id=...) >>> print(sens.position) [0. 1. 0.] >>> print(sens.orientation.as_euler('xyz', degrees=True)) [ 0. 0. 90.]
Rotate the object about itself:
>>> sens.rotate_from_matrix([(0,-1,0),(1,0,0),(0,0,1)]) Sensor(id=...) >>> print(sens.position) [0. 1. 0.] >>> print(sens.orientation.as_euler('xyz', degrees=True)) [ 0. 0. 180.]
- rotate_from_mrp(mrp, anchor=None, start='auto')#
Rotates object using Modified Rodrigues Parameters (MRPs) input.
Terminology for move/rotate methods:
path refers to position and orientation of an object.
When an input is just a single operation (e.g. one displacement vector or one angle) we call it ‘scalar input’. When it is an array_like of multiple scalars, we refer to it as ‘vector input’.
General move/rotate behavior:
Scalar input is applied to the whole object path, starting with path index start.
Vector input of length n applies the individual n operations to n object path entries, starting with path index start.
When an input extends beyond the object path, the object path will be padded by its edge-entries before the operation is applied.
By default (start=’auto’) the index is set to start=0 for scalar input [=move whole object path], and to start=len(object path) for vector input [=append to existing object path].
- Parameters
mrp (array_like, shape (n,3) or (3,)) – Rotation input. See scipy Rotation package for details on Modified Rodrigues Parameters (MRPs).
anchor (None, 0 or array_like with shape (3,) or (n,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=`'auto'`) – Starting index when applying operations. See ‘General move/rotate behavior’ above for details.
- Returns
self
- Return type
Magpylib object
Examples
Rotate an object about the origin:
>>> import magpylib as magpy >>> sens = magpy.Sensor(position=(1,0,0)) >>> sens.rotate_from_mrp((0,0,1), anchor=0) Sensor(id=...) >>> print(sens.position) [-1. 0. 0.] >>> print(sens.orientation.as_euler('xyz', degrees=True)) [ 0. 0. 180.]
Rotate the object about itself:
>>> sens.rotate_from_matrix([(0,-1,0),(1,0,0),(0,0,1)]) Sensor(id=...) >>> print(sens.position) [-1. 0. 0.] >>> print(sens.orientation.as_euler('xyz', degrees=True)) [ 0. 0. -90.]
- rotate_from_quat(quat, anchor=None, start='auto')#
Rotates object using quaternion input.
Terminology for move/rotate methods:
path refers to position and orientation of an object.
When an input is just a single operation (e.g. one displacement vector or one angle) we call it ‘scalar input’. When it is an array_like of multiple scalars, we refer to it as ‘vector input’.
General move/rotate behavior:
Scalar input is applied to the whole object path, starting with path index start.
Vector input of length n applies the individual n operations to n object path entries, starting with path index start.
When an input extends beyond the object path, the object path will be padded by its edge-entries before the operation is applied.
By default (start=’auto’) the index is set to start=0 for scalar input [=move whole object path], and to start=len(object path) for vector input [=append to existing object path].
- Parameters
quat (array_like, shape (n,4) or (4,)) – Rotation input in quaternion form.
anchor (None, 0 or array_like with shape (3,) or (n,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=`'auto'`) – Starting index when applying operations. See ‘General move/rotate behavior’ above for details.
- Returns
self
- Return type
Magpylib object
Examples
Rotate an object about the origin:
>>> import magpylib as magpy >>> sens = magpy.Sensor(position=(1,0,0)) >>> sens.rotate_from_quat((0,0,1,1), anchor=0) Sensor(id=...) >>> print(sens.position) [0. 1. 0.] >>> print(sens.orientation.as_euler('xyz', degrees=True)) [ 0. 0. 90.]
Rotate the object about itself:
>>> sens.rotate_from_quat((0,0,1,1)) Sensor(id=...) >>> print(sens.position) [0. 1. 0.] >>> print(sens.orientation.as_euler('xyz', degrees=True)) [ 0. 0. 180.]
- rotate_from_rotvec(rotvec, anchor=None, start='auto', degrees=True)#
Rotates object using rotation vector input.
Terminology for move/rotate methods:
path refers to position and orientation of an object.
When an input is just a single operation (e.g. one displacement vector or one angle) we call it ‘scalar input’. When it is an array_like of multiple scalars, we refer to it as ‘vector input’.
General move/rotate behavior:
Scalar input is applied to the whole object path, starting with path index start.
Vector input of length n applies the individual n operations to n object path entries, starting with path index start.
When an input extends beyond the object path, the object path will be padded by its edge-entries before the operation is applied.
By default (start=’auto’) the index is set to start=0 for scalar input [=move whole object path], and to start=len(object path) for vector input [=append to existing object path].
- Parameters
rotvec (array_like, shape (n,3) or (3,)) – Rotation input. Rotation vector direction is the rotation axis, vector length is the rotation angle in units of rad.
anchor (None, 0 or array_like with shape (3,) or (n,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=`'auto'`) – Starting index when applying operations. See ‘General move/rotate behavior’ above for details.
degrees (bool, default=`True`) – Interpret input in units of deg or rad.
- Returns
self
- Return type
Magpylib object
Examples
Rotate an object about the origin:
>>> import magpylib as magpy >>> sens = magpy.Sensor(position=(1,0,0)) >>> sens.rotate_from_rotvec((0,0,45), anchor=0) Sensor(id=...) >>> print(sens.position) [0.70710678 0.70710678 0. ] >>> print(sens.orientation.as_euler('xyz', degrees=True)) [ 0. 0. 45.]
Rotate the object about itself:
>>> sens.rotate_from_rotvec((0,0,45)) Sensor(id=...) >>> print(sens.position) [0.70710678 0.70710678 0. ] >>> print(sens.orientation.as_euler('xyz', degrees=True)) [ 0. 0. 90.]
Create a rotation path by rotating in several steps about an anchor:
>>> sens.rotate_from_rotvec([(0,0,15), (0,0,30), (0,0,45)], anchor=(0,0,0)) Sensor(id=...) >>> print(sens.position) [[ 7.07106781e-01 7.07106781e-01 0.00000000e+00] [ 5.00000000e-01 8.66025404e-01 0.00000000e+00] [ 2.58819045e-01 9.65925826e-01 0.00000000e+00] [-2.22044605e-16 1.00000000e+00 0.00000000e+00]] >>> print(sens.orientation.as_euler('xyz', degrees=True)) [[ 0. 0. 90.] [ 0. 0. 105.] [ 0. 0. 120.] [ 0. 0. 135.]]
- show(*, backend=<default>, canvas=<default>, animation=<default>, zoom=<default>, markers=<default>, return_fig=<default>, row=<default>, col=<default>, output=<default>, sumup=<default>, pixel_agg=<default>, style=<default>, **kwargs)#
Display objects and paths graphically.
Global graphic styles can be set with kwargs as style dictionary or using style underscore magic.
- Parameters
objects (Magpylib objects (sources, collections, sensors)) – Objects to be displayed.
backend (string, default=`None`) – Define plotting backend. Must be one of [‘auto’, ‘matplotlib’, ‘plotly’, ‘pyvista’]. If not set, parameter will default to magpylib.defaults.display.backend which is ‘auto’ by installation default. With ‘auto’, the backend defaults to ‘plotly’ if plotly is installed and the function is called in an IPython environment, otherwise defaults to ‘matplotlib’ which comes installed with magpylib. If the canvas is set, the backend defaults to the one corresponding to the canvas object (see canvas parameter).
canvas (matplotlib.pyplot AxesSubplot or plotly Figure object, default=`None`) – Display graphical output on a given canvas: - with matplotlib: matplotlib.axes.Axes with projection=3d. - with plotly: `plotly.graph_objects.Figure or plotly.graph_objects.FigureWidget. - with pyvista: pyvista.Plotter. By default a new canvas is created and immediately displayed.
animation (bool or float, default=`False`) – If True and at least one object has a path, the paths are rendered. If input is a positive float, the animation time is set to the given value. This feature is only available for the plotly backend.
zoom (float, default=`0`) – Adjust plot zoom-level. When zoom=0 3D-figure boundaries are tight.
markers (array_like, shape (n,3), default=`None`) – Display position markers in the global coordinate system.
return_fig (bool, default=False) –
If True, the function call returns the figure object.
with matplotlib: matplotlib.figure.Figure.
with plotly: plotly.graph_objects.Figure or plotly.graph_objects.FigureWidget.
with pyvista: pyvista.Plotter.
row (int or None,) – If provided specifies the row in which the objects will be displayed.
col (int or None,) – If provided specifies the column in which the objects will be displayed.
output (tuple or string, default="model3d") – Can be a string or a tuple of strings specifying the plot output type. By default output=’model3d’ displays the 3D representations of the objects. If output is a tuple of strings it must be a combination of ‘B’ or ‘H’ and ‘x’, ‘y’ and/or ‘z’. When having multiple coordinates, the field value is the combined vector length (e.g. (‘Bx’, ‘Hxy’, ‘Byz’)) ‘Bxy’ is equivalent to sqrt(|Bx|^2 + |By|^2). A 2D line plot is then represented accordingly if the objects contain at least one source and one sensor.
sumup (bool, default=True) – If True, sums the field values of the sources. Applies only if output is not ‘model3d’.
pixel_agg (bool, default="mean") – Reference to a compatible numpy aggregator function like ‘min’ or ‘mean’, which is applied to observer output values, e.g. mean of all sensor pixel outputs. Applies only if output is not ‘model3d’.
style (dict) – Object style inputs must be in dictionary form, e.g. {‘color’:’red’} or using style underscore magic, e.g. style_color=’red’. Applies to all objects matching the given style properties.
- Return type
None or figure object
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([(0.1*x,0,0) for x in range(50)]) Sphere... >>> src.rotate_from_angax(angle=[*range(0,400,10)], axis='z', anchor=0, start=11) Sphere... >>> ts = [-.4,0,.4] >>> sens = magpy.Sensor(position=(0,0,2), pixel=[(x,y,0) for x in ts for y in ts]) >>> magpy.show(src, sens) >>> magpy.show(src, sens, backend='plotly') >>> # graphic output
Display output on your own canvas (here a Matplotlib 3d-axes):
>>> 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.show(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, [(0,0,0), (0,0,3)]) >>> src2 = magpy.magnet.Sphere((1,1,1), 1, [(1,0,0), (1,0,3)], style_path_show=False) >>> magpy.defaults.display.style.magnet.magnetization.size = 2 >>> src1.style.magnetization.size = 1 >>> magpy.show(src1, src2, style_color='r') >>> # graphic output
Use a context manager to jointly animate 3d and 2d subplots
>>> import magpylib as magpy >>> import numpy as np >>> import plotly.graph_objects as go >>> path_len = 40 >>> sensor = magpy.Sensor() >>> cyl1 = magpy.magnet.Cylinder( ... magnetization=(100, 0, 0), ... dimension=(1, 2), ... position=(4, 0, 0), ... style_label="Cylinder1", ... ) >>> sensor.move(np.linspace((0, 0, -3), (0, 0, 3), path_len), start=0) Sensor(id=...) >>> cyl1.rotate_from_angax(angle=np.linspace(0, 300, path_len), start=0, axis="z", anchor=0) Cylinder(id=...) >>> cyl2 = cyl1.copy().move((0, 0, 5)) >>> fig = go.Figure() >>> with magpy.show_context(cyl1, cyl2, sensor, canvas=fig, backend="plotly", animation=True): ... magpy.show(col=1, output="model3d") ... magpy.show(col=2, output="Bxy", sumup=True) ... magpy.show(col=3, output="Bz", sumup=False) >>> fig.show() >>> # graphic output
- property style#
Object style in the form of a BaseStyle object. Input must be in the form of a style dictionary.
- property vertices#
Length of the Tetrahedron sides [a,b,c] in units of mm.
- class magpylib.magnet.TriangularMesh(magnetization=None, vertices=None, faces=None, position=(0, 0, 0), orientation=None, check_open='warn', check_disconnected='warn', check_selfintersecting='warn', reorient_faces='warn', style=None, **kwargs)#
Bases:
BaseMagnetMagnet with homogeneous magnetization defined by triangular surface mesh. Can be used as sources input for magnetic field computation. When position=(0,0,0) and orientation=None the TriangularMesh vertices are the same as in the global coordinate system.
- Parameters
magnetization (array_like, shape (3,), default=`None`) – Magnetization vector (mu0*M, remanence field) in units of mT given in the local object coordinates (rotates with object).
vertices (ndarray, shape (n,3)) – A set of points in units of mm in the local object coordinates from which the triangular faces of the mesh are constructed by the additional `faces`input.
faces (ndarray, shape (n,3)) – Indices of vertices. Each triplet represents one triangle of the mesh.
position (array_like, shape (3,) or (m,3), default=`(0,0,0)`) – Object position(s) in the global coordinates in units of mm. For m>1, the position and orientation attributes together represent an object path.
orientation (scipy Rotation object with length 1 or m, default=`None`) – Object orientation(s) in the global coordinates. None corresponds to a unit-rotation. For m>1, the position and orientation attributes together represent an object path.
reorient_faces (bool or string, default=`True`) – In a properly oriented mesh, all faces must be oriented outwards. If True, check and fix the orientation of each triangle. Options are ‘skip’`(=`False), ‘warn’`(=`True), ‘raise’, ‘ignore’.
check_open (bool or string, default=`True`) – Only a closed mesh guarantees correct B-field computation. If True, check if mesh is open. Options are ‘skip’`(=`False), ‘warn’`(=`True), ‘raise’, ‘ignore’.
check_disconnected (bool or string, default=`True`) – Individual magnets should be connected bodies to avoid confusion. If True, check if mesh is disconnected. Options are ‘skip’`(=`False), ‘warn’`(=`True), ‘raise’, ‘ignore’.
check_selfintersecting (bool, optional) – a proper body cannot have a self-intersecting mesh. If True, check if mesh is self-intersecting. Options are ‘skip’`(=`False), ‘warn’`(=`True), ‘raise’, ‘ignore’.
check_selfintersecting – If True, the provided set of facets is validated by checking if the body is not self-intersecting. Can be deactivated for performance reasons by setting it to False.
parent (Collection object or None) – The object is a child of it’s parent collection.
style (dict) – Object style inputs must be in dictionary form, e.g. {‘color’:’red’} or using style underscore magic, e.g. style_color=’red’.
Notes
Faces are automatically reoriented since scipy.spatial.ConvexHull objects do not guarantee that the faces are all pointing outwards. A mesh validation is also performed.
- Returns
magnet source
- Return type
TriangularMesh object
Examples
We compute the B-field in units of mT of a triangular mesh (4 vertices, 4 faces) with magnetization (100,200,300) in units of mT at the observer position (1,1,1) given in units of mm:
>>> import magpylib as magpy >>> vv = ((0,0,0), (1,0,0), (0,1,0), (0,0,1)) >>> tt = ((0,1,2), (0,1,3), (0,2,3), (1,2,3)) >>> trim = magpy.magnet.TriangularMesh(magnetization=(100,200,300), vertices=vv, faces=tt) >>> print(trim.getB((1,1,1))) [2.60236696 2.08189357 1.56142018]
- property barycenter#
Object barycenter.
- check_disconnected(mode='warn')#
Check whether the mesh is connected.
This function checks if the mesh is connected. If the mesh is not connected, it issues a warning or raises a ValueError, depending on the ‘mode’ parameter. If ‘mode’ is set to ‘ignore’, it does not issue a warning or raise an error.
- Parameters
mode (str, optional) – Controls how to handle if the mesh is not connected. Accepted values are “warn”, “raise”, or “ignore”. If “warn”, a warning is issued. If “raise”, a ValueError is raised. If “ignore”, no action is taken. By default “warn”.
- Returns
True if the mesh is disconnected, False otherwise.
- Return type
bool
- Raises
ValueError – If ‘mode’ is not one of the accepted values or if ‘mode’ is “raise” and the mesh is disconnected.
- Warns
UserWarning – If the mesh is disconnected and ‘mode’ is “warn”.
- check_open(mode='warn')#
Check whether the mesh is closed.
This function checks if the mesh is closed. If the mesh is not closed, it issues a warning or raises a ValueError, depending on the ‘mode’ parameter. If ‘mode’ is set to ‘ignore’, it does not issue a warning or raise an error.
- Parameters
mode (str, optional) – Controls how to handle if the mesh is not closed. Accepted values are “warn”, “raise”, or “ignore”. If “warn”, a warning is issued. If “raise”, a ValueError is raised. If “ignore”, no action is taken. By default “warn”.
- Returns
True if the mesh is open, False otherwise.
- Return type
bool
- Raises
ValueError – If ‘mode’ is not one of the accepted values or if ‘mode’ is “raise” and the mesh is open.
- Warns
UserWarning – If the mesh is open and ‘mode’ is “warn”.
- check_selfintersecting(mode='warn')#
Check whether the mesh is self-intersecting.
This function checks if the mesh is self-intersecting. If the mesh is self-intersecting, it issues a warning or raises a ValueError, depending on the ‘mode’ parameter. If ‘mode’ is set to ‘ignore’, it does not issue a warning or raise an error.
- Parameters
mode (str, optional) – Controls how to handle if the mesh is self-intersecting. Accepted values are “warn”, “raise”, or “ignore”. If “warn”, a warning is issued. If “raise”, a ValueError is raised. If “ignore”, no action is taken. By default “warn”.
- Returns
True if the mesh is self-intersecting, False otherwise.
- Return type
bool
- Raises
ValueError – If ‘mode’ is not one of the accepted values or if ‘mode’ is “raise” and the mesh is self-intersecting.
- Warns
UserWarning – If the mesh is self-intersecting and ‘mode’ is “warn”.
- copy(**kwargs)#
Returns a copy of the current object instance. The copy method returns a deep copy of the object, that is independent of the original object.
- Parameters
kwargs (dict) – Keyword arguments (for example position=(1,2,3)) are applied to the copy.
Examples
Create a Sensor object and copy to an another position:
>>> import magpylib as magpy >>> sens1 = magpy.Sensor(style_label='sens1') >>> sens2 = sens1.copy(position=(2,6,10), style_label='sens2') >>> print(f"Instance {sens1.style.label} with position {sens1.position}.") Instance sens1 with position [0. 0. 0.]. >>> print(f"Instance {sens2.style.label} with position {sens2.position}.") Instance sens2 with position [ 2. 6. 10.].
- describe(*, exclude=('style', 'field_func'), return_string=False)#
Returns a view of the object properties.
- Parameters
exclude (bool, default=("style",)) – Properties to be excluded in the description view.
return_string (bool, default=`False`) – If False print description with stdout, if True return as string.
- property faces#
Mesh faces
- property field_func#
The function for B- and H-field computation must have the two positional arguments field and observers. With field=’B’ or field=’H’ the B- or H-field in units of mT or kA/m must be returned respectively. The observers argument must accept numpy ndarray inputs of shape (n,3), in which case the returned fields must be numpy ndarrays of shape (n,3) themselves.
- classmethod from_ConvexHull(magnetization=None, points=None, position=(0, 0, 0), orientation=None, check_open='warn', check_disconnected='warn', reorient_faces=True, style=None, **kwargs)#
Create a TriangularMesh magnet from a point cloud via its convex hull.
- Parameters
magnetization (array_like, shape (3,), default=`None`) – Magnetization vector (mu0*M, remanence field) in units of mT given in the local object coordinates (rotates with object).
points (ndarray, shape (n,3)) – Point cloud from which the convex hull is computed.
position (array_like, shape (3,) or (m,3)) – Object position(s) in the global coordinates in units of mm. For m>1, the position and orientation attributes together represent an object path.
orientation (scipy Rotation object with length 1 or m, default=`None`) – Object orientation(s) in the global coordinates. None corresponds to a unit-rotation. For m>1, the position and orientation attributes together represent an object path.
reorient_faces (bool, default=`True`) – In a properly oriented mesh, all faces must be oriented outwards. If True, check and fix the orientation of each triangle.
check_open ({'warn', 'raise', 'ignore'}, default='warn') – Only a closed mesh guarantees a physical magnet. If the mesh is open and “warn”, a warning is issued. If the mesh is open and “raise”, a ValueError is raised. If “ignore”, no mesh check is performed.
check_disconnected ({'warn', 'raise', 'ignore'}, default='warn') – If the mesh is disconnected and “warn”, a warning is issued. If the mesh is disconnected and “raise”, a ValueError is raised. If “ignore”, no mesh check is performed.
check_selfintersecting ({'warn', 'raise', 'ignore'}, default='warn') – If the mesh is self-intersecting and “warn”, a warning is issued. If the mesh is self-intersecting and “raise”, a ValueError is raised. If “ignore”, no mesh check is performed.
parent (Collection object or None) – The object is a child of it’s parent collection.
style (dict) – Object style inputs must be in dictionary form, e.g. {‘color’:’red’} or using style underscore magic, e.g. style_color=’red’.
Notes
Faces are automatically reoriented since scipy.spatial.ConvexHull objects do not guarantee that the faces are all pointing outwards. A mesh validation is also performed.
- Returns
magnet source
- Return type
TriangularMesh object
Examples
- classmethod from_mesh(magnetization=None, mesh=None, position=(0, 0, 0), orientation=None, reorient_faces=True, check_open='warn', check_disconnected='warn', style=None, **kwargs)#
Create a TriangularMesh magnet from a mesh input.
- Parameters
magnetization (array_like, shape (3,), default=`None`) – Magnetization vector (mu0*M, remanence field) in units of mT given in the local object coordinates (rotates with object).
mesh (array_like, shape (n,3,3)) – An array_like of triangular faces that make up a triangular mesh.
position (array_like, shape (3,) or (m,3)) – Object position(s) in the global coordinates in units of mm. For m>1, the position and orientation attributes together represent an object path.
orientation (scipy Rotation object with length 1 or m, default=`None`) – Object orientation(s) in the global coordinates. None corresponds to a unit-rotation. For m>1, the position and orientation attributes together represent an object path.
reorient_faces (bool, default=`True`) – In a properly oriented mesh, all faces must be oriented outwards. If True, check and fix the orientation of each triangle.
check_open ({'warn', 'raise', 'ignore'}, default='warn') – Only a closed mesh guarantees a physical magnet. If the mesh is open and “warn”, a warning is issued. If the mesh is open and “raise”, a ValueError is raised. If “ignore”, no mesh check is performed.
check_disconnected ({'warn', 'raise', 'ignore'}, default='warn') – If the mesh is disconnected and “warn”, a warning is issued. If the mesh is disconnected and “raise”, a ValueError is raised. If “ignore”, no mesh check is performed.
check_selfintersecting ({'warn', 'raise', 'ignore'}, default='warn') – If the mesh is self-intersecting and “warn”, a warning is issued. If the mesh is self-intersecting and “raise”, a ValueError is raised. If “ignore”, no mesh check is performed.
parent (Collection object or None) – The object is a child of it’s parent collection.
style (dict) – Object style inputs must be in dictionary form, e.g. {‘color’:’red’} or using style underscore magic, e.g. style_color=’red’.
Notes
Faces are automatically reoriented since pyvista.core.pointset.PolyData objects do not guarantee that the faces are all pointing outwards. A mesh validation is also performed.
- Returns
magnet source
- Return type
TriangularMesh object
Examples
- classmethod from_pyvista(magnetization=None, polydata=None, position=(0, 0, 0), orientation=None, check_open='warn', check_disconnected='warn', reorient_faces=True, style=None, **kwargs)#
Create a TriangularMesh magnet from a pyvista PolyData mesh object.
- Parameters
magnetization (array_like, shape (3,), default=`None`) – Magnetization vector (mu0*M, remanence field) in units of mT given in the local object coordinates (rotates with object).
polydata (pyvista.core.pointset.PolyData object) – A valid pyvista Polydata mesh object. (e.g. pyvista.Sphere())
position (array_like, shape (3,) or (m,3)) – Object position(s) in the global coordinates in units of mm. For m>1, the position and orientation attributes together represent an object path.
orientation (scipy Rotation object with length 1 or m, default=`None`) – Object orientation(s) in the global coordinates. None corresponds to a unit-rotation. For m>1, the position and orientation attributes together represent an object path.
reorient_faces (bool, default=`True`) – In a properly oriented mesh, all faces must be oriented outwards. If True, check and fix the orientation of each triangle.
check_open ({'warn', 'raise', 'ignore'}, default='warn') – Only a closed mesh guarantees a physical magnet. If the mesh is open and “warn”, a warning is issued. If the mesh is open and “raise”, a ValueError is raised. If “ignore”, no mesh check is performed.
check_disconnected ({'warn', 'raise', 'ignore'}, default='warn') – If the mesh is disconnected and “warn”, a warning is issued. If the mesh is disconnected and “raise”, a ValueError is raised. If “ignore”, no mesh check is performed.
check_selfintersecting ({'warn', 'raise', 'ignore'}, default='warn') – If the mesh is self-intersecting and “warn”, a warning is issued. If the mesh is self-intersecting and “raise”, a ValueError is raised. If “ignore”, no mesh check is performed.
parent (Collection object or None) – The object is a child of it’s parent collection.
style (dict) – Object style inputs must be in dictionary form, e.g. {‘color’:’red’} or using style underscore magic, e.g. style_color=’red’.
Notes
Faces are automatically reoriented since pyvista.core.pointset.PolyData objects do not guarantee that the faces are all pointing outwards. A mesh validation is also performed.
- Returns
magnet source
- Return type
TriangularMesh object
Examples
- classmethod from_triangles(magnetization=None, triangles=None, position=(0, 0, 0), orientation=None, reorient_faces=True, check_open='warn', check_disconnected='warn', style=None, **kwargs)#
Create a TriangularMesh magnet from a list or Collection of Triangle objects.
- Parameters
magnetization (array_like, shape (3,), default=`None`) – Magnetization vector (mu0*M, remanence field) in units of mT given in the local object coordinates (rotates with object).
triangles (list or Collection of Triangle objects) – Only vertices of Triangle objects are taken, magnetization is ignored.
position (array_like, shape (3,) or (m,3)) – Object position(s) in the global coordinates in units of mm. For m>1, the position and orientation attributes together represent an object path.
orientation (scipy Rotation object with length 1 or m, default=`None`) – Object orientation(s) in the global coordinates. None corresponds to a unit-rotation. For m>1, the position and orientation attributes together represent an object path.
reorient_faces (bool, default=`True`) – In a properly oriented mesh, all faces must be oriented outwards. If True, check and fix the orientation of each triangle.
check_open ({'warn', 'raise', 'ignore'}, default='warn') – Only a closed mesh guarantees a physical magnet. If the mesh is open and “warn”, a warning is issued. If the mesh is open and “raise”, a ValueError is raised. If “ignore”, no mesh check is performed.
check_disconnected ({'warn', 'raise', 'ignore'}, default='warn') – If the mesh is disconnected and “warn”, a warning is issued. If the mesh is disconnected and “raise”, a ValueError is raised. If “ignore”, no mesh check is performed.
check_selfintersecting ({'warn', 'raise', 'ignore'}, default='warn') – If the mesh is self-intersecting and “warn”, a warning is issued. If the mesh is self-intersecting and “raise”, a ValueError is raised. If “ignore”, no mesh check is performed.
parent (Collection object or None) – The object is a child of it’s parent collection.
style (dict) – Object style inputs must be in dictionary form, e.g. {‘color’:’red’} or using style underscore magic, e.g. style_color=’red’.
Notes
Faces are automatically reoriented since pyvista.core.pointset.PolyData objects do not guarantee that the faces are all pointing outwards. A mesh validation is also performed.
- Returns
magnet source
- Return type
TriangularMesh object
Examples
- getB(*observers, squeeze=True, pixel_agg=None, output='ndarray')#
Compute the B-field in units of mT generated by the source.
- Parameters
observers (array_like or (list of) Sensor objects) – Can be array_like positions of shape (n1, n2, …, 3) where the field should be evaluated, a Sensor object with pixel shape (n1, n2, …, 3) or a list of such sensor objects (must all have similar pixel shapes). All positions are given in units of mm.
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.
pixel_agg (str, default=`None`) – Reference to a compatible numpy aggregator function like ‘min’ or ‘mean’, which is applied to observer output values, e.g. mean of all sensor pixel outputs. With this option, observers input with different (pixel) shapes is allowed.
output (str, default='ndarray') – Output type, which must be one of (‘ndarray’, ‘dataframe’). By default a multi- dimensional array (‘ndarray’) is returned. If ‘dataframe’ is chosen, the function returns a 2D-table as a pandas.DataFrame object (the Pandas library must be installed).
- 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) or DataFrame
Examples
Compute the B-field of a spherical magnet at three positions:
>>> import magpylib as magpy >>> src = magpy.magnet.Sphere((0,0,1000), 1) >>> B = src.getB(((0,0,0), (1,0,0), (2,0,0))) >>> print(B) [[ 0. 0. 666.66666667] [ 0. 0. -41.66666667] [ 0. 0. -5.20833333]]
Compute the B-field at two sensors, each one with two pixels
>>> sens1 = magpy.Sensor(position=(1,0,0), pixel=((0,0,.1), (0,0,-.1))) >>> sens2 = sens1.copy(position=(2,0,0)) >>> B = src.getB(sens1, sens2) >>> print(B) [[[ 12.19288783 0. -39.83010025] [-12.19288783 0. -39.83010025]] [[ 0.77638847 0. -5.15004352] [ -0.77638847 0. -5.15004352]]]
- getH(*observers, squeeze=True, pixel_agg=None, output='ndarray')#
Compute the H-field in units of kA/m generated by the source.
- Parameters
observers (array_like or (list of) Sensor objects) – Can be array_like positions of shape (n1, n2, …, 3) where the field should be evaluated, a Sensor object with pixel shape (n1, n2, …, 3) or a list of such sensor objects (must all have similar pixel shapes). All positions are given in units of mm.
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.
pixel_agg (str, default=`None`) – Reference to a compatible numpy aggregator function like ‘min’ or ‘mean’, which is applied to observer output values, e.g. mean of all sensor pixel outputs. With this option, observers input with different (pixel) shapes is allowed.
output (str, default='ndarray') – Output type, which must be one of (‘ndarray’, ‘dataframe’). By default a multi- dimensional array (‘ndarray’) is returned. If ‘dataframe’ is chosen, the function returns a 2D-table as a pandas.DataFrame object (the Pandas library must be installed).
- 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) or DataFrame
Examples
Compute the H-field of a spherical magnet at three positions:
>>> import magpylib as magpy
>>> src = magpy.magnet.Sphere((0,0,1000), 1) >>> H = src.getH(((0,0,0), (1,0,0), (2,0,0))) >>> print(H) [[ 0. 0. -265.25823849] [ 0. 0. -33.15727981] [ 0. 0. -4.14465998]]
Compute the H-field at two sensors, each one with two pixels
>>> sens1 = magpy.Sensor(position=(1,0,0), pixel=((0,0,.1), (0,0,-.1))) >>> sens2 = sens1.copy(position=(2,0,0)) >>> H = src.getH(sens1, sens2) >>> print(H) [[[ 9.70279185 0. -31.69578669] [ -9.70279185 0. -31.69578669]] [[ 0.61783031 0. -4.09827441] [ -0.61783031 0. -4.09827441]]]
- get_faces_subsets()#
Obtain and return subsets of the mesh. If the mesh has n parts, returns and list of length n of faces (m,3) vertices indices triplets corresponding to each part.
- Returns
status_disconnected_data – Subsets of faces data.
- Return type
list of numpy.ndarray
- get_open_edges()#
Obtain and return the potential open edges. If the mesh has n open edges, returns an corresponding (n,2) array of vertices indices doubles.
- Returns
status_open_data – Open edges data.
- Return type
numpy.ndarray
- get_selfintersecting_faces()#
Obtain and return the potential self intersecting faces indices. If the mesh has n intersecting faces, returns a corresponding 1D array length n faces indices.
- Returns
status_open_data – Open edges data.
- Return type
numpy.ndarray
- get_trace(**kwargs) Union[Dict[str, Any], List[Dict[str, Any]]]#
Creates the plotly mesh3d parameters for a Trianglular facet mesh in a dictionary based on the provided arguments.
- property magnetization#
Object magnetization attribute getter and setter.
- property mesh#
Mesh
- move(displacement, start='auto')#
Move object by the displacement input.
Terminology for move/rotate methods:
path refers to position and orientation of an object.
When an input is just a single operation (e.g. one displacement vector or one angle) we call it ‘scalar input’. When it is an array_like of multiple scalars, we refer to it as ‘vector input’.
General move/rotate behavior:
Scalar input is applied to the whole object path, starting with path index start.
Vector input of length n applies the individual n operations to n object path entries, starting with path index start.
When an input extends beyond the object path, the object path will be padded by its edge-entries before the operation is applied.
By default (start=’auto’) the index is set to start=0 for scalar input [=move whole object path], and to start=len(object path) for vector input [=append to existing object path].
- Parameters
displacement (array_like, shape (3,) or (n,3)) – Displacement vector in units of mm.
start (int or str, default=`'auto'`) – Starting index when applying operations. See ‘General move/rotate behavior’ above for details.
- Returns
self
- Return type
Magpylib object
Examples
Move objects around with scalar input:
>>> import magpylib as magpy >>> sens = magpy.Sensor(position=(1,1,1)) >>> print(sens.position) [1. 1. 1.] >>> sens.move((1,1,1)) Sensor(id=...) >>> print(sens.position) [2. 2. 2.]
Create len>1 object paths with vector input:
>>> sens.move([(1,1,1),(2,2,2),(3,3,3)]) Sensor(id=...) >>> print(sens.position) [[2. 2. 2.] [3. 3. 3.] [4. 4. 4.] [5. 5. 5.]]
Apply operations starting with a designated path index:
>>> sens.move((0,0,2), start=2) Sensor(id=...) >>> print(sens.position) [[2. 2. 2.] [3. 3. 3.] [4. 4. 6.] [5. 5. 7.]]
- property orientation#
Object orientation(s) in the global coordinates. None corresponds to a unit-rotation. For m>1, the position and orientation attributes together represent an object path.
- property parent#
The object is a child of it’s parent collection.
- property position#
Object position(s) in the global coordinates in units of mm. For m>1, the position and orientation attributes together represent an object path.
- reorient_faces(mode='warn')#
Correctly reorients the mesh’s faces.
In a properly oriented mesh, all faces must be oriented outwards. This function fixes the orientation of each face. It issues a warning or raises a ValueError, depending on the ‘mode’ parameter. If ‘mode’ is set to ‘ignore’, it does not issue a warning or raise an error. Note that this parameter is passed on the check_closed() function as the mesh is only orientable if it is closed.
- Parameters
mode (str, optional) – Controls how to handle if the mesh is open and not orientable. Accepted values are “warn”, “raise”, or “ignore”. If “warn”, a warning is issued. If “raise”, a ValueError is raised. If “ignore”, no action is taken. By default “warn”.
- Returns
True if the mesh is connected, False otherwise.
- Return type
bool
- Raises
ValueError – If ‘mode’ is not one of the accepted values or if ‘mode’ is “raise” and the mesh is open and not orientable.
- Warns
UserWarning – If the mesh is not connected and ‘mode’ is “warn”.
- reset_path()#
Set object position to (0,0,0) and orientation = unit rotation.
- Returns
self
- Return type
magpylib object
Examples
Demonstration of reset_path functionality:
>>> import magpylib as magpy >>> obj = magpy.Sensor(position=(1,2,3)) >>> obj.rotate_from_angax(45, 'z') Sensor... >>> print(obj.position) [1. 2. 3.] >>> print(obj.orientation.as_euler('xyz', degrees=True)) [ 0. 0. 45.]
>>> obj.reset_path() Sensor(id=...) >>> print(obj.position) [0. 0. 0.] >>> print(obj.orientation.as_euler('xyz', degrees=True)) [0. 0. 0.]
- rotate(rotation: Rotation, anchor=None, start='auto')#
Rotate object about a given anchor.
Terminology for move/rotate methods:
path refers to position and orientation of an object.
When an input is just a single operation (e.g. one displacement vector or one angle) we call it ‘scalar input’. When it is an array_like of multiple scalars, we refer to it as ‘vector input’.
General move/rotate behavior:
Scalar input is applied to the whole object path, starting with path index start.
Vector input of length n applies the individual n operations to n object path entries, starting with path index start.
When an input extends beyond the object path, the object path will be padded by its edge-entries before the operation is applied.
By default (start=’auto’) the index is set to start=0 for scalar input [=move whole object path], and to start=len(object path) for vector input [=append to existing object path].
- Parameters
rotation (None or scipy Rotation object) – Rotation to be applied to the object. The scipy Rotation input can be scalar or vector type (see terminology above). None input is interpreted as unit rotation.
anchor (None, 0 or array_like with shape (3,) or (n,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=`'auto'`) – Starting index when applying operations. See ‘General move/rotate behavior’ above for details.
- Returns
self
- Return type
Magpylib object
Examples
Rotate an object about the origin:
>>> from scipy.spatial.transform import Rotation as R >>> import magpylib as magpy >>> sens = magpy.Sensor(position=(1,0,0)) >>> sens.rotate(R.from_euler('z', 45, degrees=True), anchor=0) Sensor(id=...) >>> print(sens.position) [0.70710678 0.70710678 0. ] >>> print(sens.orientation.as_euler('xyz', degrees=True)) [ 0. 0. 45.]
Rotate the object about itself:
>>> sens.rotate(R.from_euler('z', 45, degrees=True)) Sensor(id=...) >>> print(sens.position) [0.70710678 0.70710678 0. ] >>> print(sens.orientation.as_euler('xyz', degrees=True)) [ 0. 0. 90.]
Create a rotation path by rotating in several steps about an anchor:
>>> sens.rotate(R.from_euler('z', (15,30,45), degrees=True), anchor=(0,0,0)) Sensor(id=...) >>> print(sens.position) [[ 7.07106781e-01 7.07106781e-01 0.00000000e+00] [ 5.00000000e-01 8.66025404e-01 0.00000000e+00] [ 2.58819045e-01 9.65925826e-01 0.00000000e+00] [-2.22044605e-16 1.00000000e+00 0.00000000e+00]] >>> print(sens.orientation.as_euler('xyz', degrees=True)) [[ 0. 0. 90.] [ 0. 0. 105.] [ 0. 0. 120.] [ 0. 0. 135.]]
- rotate_from_angax(angle, axis, anchor=None, start='auto', degrees=True)#
Rotates object using angle-axis input.
Terminology for move/rotate methods:
path refers to position and orientation of an object.
When an input is just a single operation (e.g. one displacement vector or one angle) we call it ‘scalar input’. When it is an array_like of multiple scalars, we refer to it as ‘vector input’.
General move/rotate behavior:
Scalar input is applied to the whole object path, starting with path index start.
Vector input of length n applies the individual n operations to n object path entries, starting with path index start.
When an input extends beyond the object path, the object path will be padded by its edge-entries before the operation is applied.
By default (start=’auto’) the index is set to start=0 for scalar input [=move whole object path], and to start=len(object path) for vector input [=append to existing object path].
- Parameters
angle (int, float or array_like with shape (n,)) – Angle(s) of rotation 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, 0 or array_like with shape (3,) or (n,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=`'auto'`) – Starting index when applying operations. See ‘General move/rotate behavior’ above for details.
degrees (bool, default=`True`) – Interpret input in units of deg or rad.
- Returns
self
- Return type
Magpylib object
Examples
Rotate an object about the origin:
>>> import magpylib as magpy >>> sens = magpy.Sensor(position=(1,0,0)) >>> sens.rotate_from_angax(45, axis='z', anchor=0) Sensor(id=...) >>> print(sens.position) [0.70710678 0.70710678 0. ] >>> print(sens.orientation.as_euler('xyz', degrees=True)) [ 0. 0. 45.]
Rotate the object about itself:
>>> sens.rotate_from_angax(45, axis=(0,0,1)) Sensor(id=...) >>> print(sens.position) [0.70710678 0.70710678 0. ] >>> print(sens.orientation.as_euler('xyz', degrees=True)) [ 0. 0. 90.]
Create a rotation path by rotating in several steps about an anchor:
>>> sens.rotate_from_angax((15,30,45), axis='z', anchor=(0,0,0)) Sensor(id=...) >>> print(sens.position) [[ 7.07106781e-01 7.07106781e-01 0.00000000e+00] [ 5.00000000e-01 8.66025404e-01 0.00000000e+00] [ 2.58819045e-01 9.65925826e-01 0.00000000e+00] [-2.22044605e-16 1.00000000e+00 0.00000000e+00]] >>> print(sens.orientation.as_euler('xyz', degrees=True)) [[ 0. 0. 90.] [ 0. 0. 105.] [ 0. 0. 120.] [ 0. 0. 135.]]
- rotate_from_euler(angle, seq, anchor=None, start='auto', degrees=True)#
Rotates object using Euler angle input.
Terminology for move/rotate methods:
path refers to position and orientation of an object.
When an input is just a single operation (e.g. one displacement vector or one angle) we call it ‘scalar input’. When it is an array_like of multiple scalars, we refer to it as ‘vector input’.
General move/rotate behavior:
Scalar input is applied to the whole object path, starting with path index start.
Vector input of length n applies the individual n operations to n object path entries, starting with path index start.
When an input extends beyond the object path, the object path will be padded by its edge-entries before the operation is applied.
By default (start=’auto’) the index is set to start=0 for scalar input [=move whole object path], and to start=len(object path) for vector input [=append to existing object path].
- Parameters
angle (int, float or array_like with shape (n,)) – Angle(s) of rotation in units of deg (by default).
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.
anchor (None, 0 or array_like with shape (3,) or (n,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=`'auto'`) – Starting index when applying operations. See ‘General move/rotate behavior’ above for details.
degrees (bool, default=`True`) – Interpret input in units of deg or rad.
- Returns
self
- Return type
Magpylib object
Examples
Rotate an object about the origin:
>>> import magpylib as magpy >>> sens = magpy.Sensor(position=(1,0,0)) >>> sens.rotate_from_euler(45, 'z', anchor=0) Sensor... >>> print(sens.position) [0.70710678 0.70710678 0. ] >>> print(sens.orientation.as_euler('xyz', degrees=True)) [ 0. 0. 45.]
Rotate the object about itself:
>>> sens.rotate_from_euler(45, 'z') Sensor(id=...) >>> print(sens.position) [0.70710678 0.70710678 0. ] >>> print(sens.orientation.as_euler('xyz', degrees=True)) [ 0. 0. 90.]
Create a rotation path by rotating in several steps about an anchor:
>>> sens.rotate_from_euler((15,30,45), 'z', anchor=(0,0,0)) Sensor(id=...) >>> print(sens.position) [[ 7.07106781e-01 7.07106781e-01 0.00000000e+00] [ 5.00000000e-01 8.66025404e-01 0.00000000e+00] [ 2.58819045e-01 9.65925826e-01 0.00000000e+00] [-2.22044605e-16 1.00000000e+00 0.00000000e+00]] >>> print(sens.orientation.as_euler('xyz', degrees=True)) [[ 0. 0. 90.] [ 0. 0. 105.] [ 0. 0. 120.] [ 0. 0. 135.]]
- rotate_from_matrix(matrix, anchor=None, start='auto')#
Rotates object using matrix input.
Terminology for move/rotate methods:
path refers to position and orientation of an object.
When an input is just a single operation (e.g. one displacement vector or one angle) we call it ‘scalar input’. When it is an array_like of multiple scalars, we refer to it as ‘vector input’.
General move/rotate behavior:
Scalar input is applied to the whole object path, starting with path index start.
Vector input of length n applies the individual n operations to n object path entries, starting with path index start.
When an input extends beyond the object path, the object path will be padded by its edge-entries before the operation is applied.
By default (start=’auto’) the index is set to start=0 for scalar input [=move whole object path], and to start=len(object path) for vector input [=append to existing object path].
- Parameters
matrix (array_like, shape (n,3,3) or (3,3)) – Rotation input. See scipy.spatial.transform.Rotation for details.
anchor (None, 0 or array_like with shape (3,) or (n,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=`'auto'`) – Starting index when applying operations. See ‘General move/rotate behavior’ above for details.
- Returns
self
- Return type
Magpylib object
Examples
Rotate an object about the origin:
>>> import magpylib as magpy >>> sens = magpy.Sensor(position=(1,0,0)) >>> sens.rotate_from_matrix([(0,-1,0),(1,0,0),(0,0,1)], anchor=0) Sensor(id=...) >>> print(sens.position) [0. 1. 0.] >>> print(sens.orientation.as_euler('xyz', degrees=True)) [ 0. 0. 90.]
Rotate the object about itself:
>>> sens.rotate_from_matrix([(0,-1,0),(1,0,0),(0,0,1)]) Sensor(id=...) >>> print(sens.position) [0. 1. 0.] >>> print(sens.orientation.as_euler('xyz', degrees=True)) [ 0. 0. 180.]
- rotate_from_mrp(mrp, anchor=None, start='auto')#
Rotates object using Modified Rodrigues Parameters (MRPs) input.
Terminology for move/rotate methods:
path refers to position and orientation of an object.
When an input is just a single operation (e.g. one displacement vector or one angle) we call it ‘scalar input’. When it is an array_like of multiple scalars, we refer to it as ‘vector input’.
General move/rotate behavior:
Scalar input is applied to the whole object path, starting with path index start.
Vector input of length n applies the individual n operations to n object path entries, starting with path index start.
When an input extends beyond the object path, the object path will be padded by its edge-entries before the operation is applied.
By default (start=’auto’) the index is set to start=0 for scalar input [=move whole object path], and to start=len(object path) for vector input [=append to existing object path].
- Parameters
mrp (array_like, shape (n,3) or (3,)) – Rotation input. See scipy Rotation package for details on Modified Rodrigues Parameters (MRPs).
anchor (None, 0 or array_like with shape (3,) or (n,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=`'auto'`) – Starting index when applying operations. See ‘General move/rotate behavior’ above for details.
- Returns
self
- Return type
Magpylib object
Examples
Rotate an object about the origin:
>>> import magpylib as magpy >>> sens = magpy.Sensor(position=(1,0,0)) >>> sens.rotate_from_mrp((0,0,1), anchor=0) Sensor(id=...) >>> print(sens.position) [-1. 0. 0.] >>> print(sens.orientation.as_euler('xyz', degrees=True)) [ 0. 0. 180.]
Rotate the object about itself:
>>> sens.rotate_from_matrix([(0,-1,0),(1,0,0),(0,0,1)]) Sensor(id=...) >>> print(sens.position) [-1. 0. 0.] >>> print(sens.orientation.as_euler('xyz', degrees=True)) [ 0. 0. -90.]
- rotate_from_quat(quat, anchor=None, start='auto')#
Rotates object using quaternion input.
Terminology for move/rotate methods:
path refers to position and orientation of an object.
When an input is just a single operation (e.g. one displacement vector or one angle) we call it ‘scalar input’. When it is an array_like of multiple scalars, we refer to it as ‘vector input’.
General move/rotate behavior:
Scalar input is applied to the whole object path, starting with path index start.
Vector input of length n applies the individual n operations to n object path entries, starting with path index start.
When an input extends beyond the object path, the object path will be padded by its edge-entries before the operation is applied.
By default (start=’auto’) the index is set to start=0 for scalar input [=move whole object path], and to start=len(object path) for vector input [=append to existing object path].
- Parameters
quat (array_like, shape (n,4) or (4,)) – Rotation input in quaternion form.
anchor (None, 0 or array_like with shape (3,) or (n,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=`'auto'`) – Starting index when applying operations. See ‘General move/rotate behavior’ above for details.
- Returns
self
- Return type
Magpylib object
Examples
Rotate an object about the origin:
>>> import magpylib as magpy >>> sens = magpy.Sensor(position=(1,0,0)) >>> sens.rotate_from_quat((0,0,1,1), anchor=0) Sensor(id=...) >>> print(sens.position) [0. 1. 0.] >>> print(sens.orientation.as_euler('xyz', degrees=True)) [ 0. 0. 90.]
Rotate the object about itself:
>>> sens.rotate_from_quat((0,0,1,1)) Sensor(id=...) >>> print(sens.position) [0. 1. 0.] >>> print(sens.orientation.as_euler('xyz', degrees=True)) [ 0. 0. 180.]
- rotate_from_rotvec(rotvec, anchor=None, start='auto', degrees=True)#
Rotates object using rotation vector input.
Terminology for move/rotate methods:
path refers to position and orientation of an object.
When an input is just a single operation (e.g. one displacement vector or one angle) we call it ‘scalar input’. When it is an array_like of multiple scalars, we refer to it as ‘vector input’.
General move/rotate behavior:
Scalar input is applied to the whole object path, starting with path index start.
Vector input of length n applies the individual n operations to n object path entries, starting with path index start.
When an input extends beyond the object path, the object path will be padded by its edge-entries before the operation is applied.
By default (start=’auto’) the index is set to start=0 for scalar input [=move whole object path], and to start=len(object path) for vector input [=append to existing object path].
- Parameters
rotvec (array_like, shape (n,3) or (3,)) – Rotation input. Rotation vector direction is the rotation axis, vector length is the rotation angle in units of rad.
anchor (None, 0 or array_like with shape (3,) or (n,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=`'auto'`) – Starting index when applying operations. See ‘General move/rotate behavior’ above for details.
degrees (bool, default=`True`) – Interpret input in units of deg or rad.
- Returns
self
- Return type
Magpylib object
Examples
Rotate an object about the origin:
>>> import magpylib as magpy >>> sens = magpy.Sensor(position=(1,0,0)) >>> sens.rotate_from_rotvec((0,0,45), anchor=0) Sensor(id=...) >>> print(sens.position) [0.70710678 0.70710678 0. ] >>> print(sens.orientation.as_euler('xyz', degrees=True)) [ 0. 0. 45.]
Rotate the object about itself:
>>> sens.rotate_from_rotvec((0,0,45)) Sensor(id=...) >>> print(sens.position) [0.70710678 0.70710678 0. ] >>> print(sens.orientation.as_euler('xyz', degrees=True)) [ 0. 0. 90.]
Create a rotation path by rotating in several steps about an anchor:
>>> sens.rotate_from_rotvec([(0,0,15), (0,0,30), (0,0,45)], anchor=(0,0,0)) Sensor(id=...) >>> print(sens.position) [[ 7.07106781e-01 7.07106781e-01 0.00000000e+00] [ 5.00000000e-01 8.66025404e-01 0.00000000e+00] [ 2.58819045e-01 9.65925826e-01 0.00000000e+00] [-2.22044605e-16 1.00000000e+00 0.00000000e+00]] >>> print(sens.orientation.as_euler('xyz', degrees=True)) [[ 0. 0. 90.] [ 0. 0. 105.] [ 0. 0. 120.] [ 0. 0. 135.]]
- show(*, backend=<default>, canvas=<default>, animation=<default>, zoom=<default>, markers=<default>, return_fig=<default>, row=<default>, col=<default>, output=<default>, sumup=<default>, pixel_agg=<default>, style=<default>, **kwargs)#
Display objects and paths graphically.
Global graphic styles can be set with kwargs as style dictionary or using style underscore magic.
- Parameters
objects (Magpylib objects (sources, collections, sensors)) – Objects to be displayed.
backend (string, default=`None`) – Define plotting backend. Must be one of [‘auto’, ‘matplotlib’, ‘plotly’, ‘pyvista’]. If not set, parameter will default to magpylib.defaults.display.backend which is ‘auto’ by installation default. With ‘auto’, the backend defaults to ‘plotly’ if plotly is installed and the function is called in an IPython environment, otherwise defaults to ‘matplotlib’ which comes installed with magpylib. If the canvas is set, the backend defaults to the one corresponding to the canvas object (see canvas parameter).
canvas (matplotlib.pyplot AxesSubplot or plotly Figure object, default=`None`) – Display graphical output on a given canvas: - with matplotlib: matplotlib.axes.Axes with projection=3d. - with plotly: `plotly.graph_objects.Figure or plotly.graph_objects.FigureWidget. - with pyvista: pyvista.Plotter. By default a new canvas is created and immediately displayed.
animation (bool or float, default=`False`) – If True and at least one object has a path, the paths are rendered. If input is a positive float, the animation time is set to the given value. This feature is only available for the plotly backend.
zoom (float, default=`0`) – Adjust plot zoom-level. When zoom=0 3D-figure boundaries are tight.
markers (array_like, shape (n,3), default=`None`) – Display position markers in the global coordinate system.
return_fig (bool, default=False) –
If True, the function call returns the figure object.
with matplotlib: matplotlib.figure.Figure.
with plotly: plotly.graph_objects.Figure or plotly.graph_objects.FigureWidget.
with pyvista: pyvista.Plotter.
row (int or None,) – If provided specifies the row in which the objects will be displayed.
col (int or None,) – If provided specifies the column in which the objects will be displayed.
output (tuple or string, default="model3d") – Can be a string or a tuple of strings specifying the plot output type. By default output=’model3d’ displays the 3D representations of the objects. If output is a tuple of strings it must be a combination of ‘B’ or ‘H’ and ‘x’, ‘y’ and/or ‘z’. When having multiple coordinates, the field value is the combined vector length (e.g. (‘Bx’, ‘Hxy’, ‘Byz’)) ‘Bxy’ is equivalent to sqrt(|Bx|^2 + |By|^2). A 2D line plot is then represented accordingly if the objects contain at least one source and one sensor.
sumup (bool, default=True) – If True, sums the field values of the sources. Applies only if output is not ‘model3d’.
pixel_agg (bool, default="mean") – Reference to a compatible numpy aggregator function like ‘min’ or ‘mean’, which is applied to observer output values, e.g. mean of all sensor pixel outputs. Applies only if output is not ‘model3d’.
style (dict) – Object style inputs must be in dictionary form, e.g. {‘color’:’red’} or using style underscore magic, e.g. style_color=’red’. Applies to all objects matching the given style properties.
- Return type
None or figure object
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([(0.1*x,0,0) for x in range(50)]) Sphere... >>> src.rotate_from_angax(angle=[*range(0,400,10)], axis='z', anchor=0, start=11) Sphere... >>> ts = [-.4,0,.4] >>> sens = magpy.Sensor(position=(0,0,2), pixel=[(x,y,0) for x in ts for y in ts]) >>> magpy.show(src, sens) >>> magpy.show(src, sens, backend='plotly') >>> # graphic output
Display output on your own canvas (here a Matplotlib 3d-axes):
>>> 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.show(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, [(0,0,0), (0,0,3)]) >>> src2 = magpy.magnet.Sphere((1,1,1), 1, [(1,0,0), (1,0,3)], style_path_show=False) >>> magpy.defaults.display.style.magnet.magnetization.size = 2 >>> src1.style.magnetization.size = 1 >>> magpy.show(src1, src2, style_color='r') >>> # graphic output
Use a context manager to jointly animate 3d and 2d subplots
>>> import magpylib as magpy >>> import numpy as np >>> import plotly.graph_objects as go >>> path_len = 40 >>> sensor = magpy.Sensor() >>> cyl1 = magpy.magnet.Cylinder( ... magnetization=(100, 0, 0), ... dimension=(1, 2), ... position=(4, 0, 0), ... style_label="Cylinder1", ... ) >>> sensor.move(np.linspace((0, 0, -3), (0, 0, 3), path_len), start=0) Sensor(id=...) >>> cyl1.rotate_from_angax(angle=np.linspace(0, 300, path_len), start=0, axis="z", anchor=0) Cylinder(id=...) >>> cyl2 = cyl1.copy().move((0, 0, 5)) >>> fig = go.Figure() >>> with magpy.show_context(cyl1, cyl2, sensor, canvas=fig, backend="plotly", animation=True): ... magpy.show(col=1, output="model3d") ... magpy.show(col=2, output="Bxy", sumup=True) ... magpy.show(col=3, output="Bz", sumup=False) >>> fig.show() >>> # graphic output
- property status_disconnected#
Return disconnected status
- property status_disconnected_data#
Status for connectedness (faces subsets)
- property status_open#
Return open status
- property status_open_data#
Status for openness (open edges)
- property status_reoriented#
Return reoriented status
- property status_selfintersecting#
Is-selfintersecting boolean check
- property status_selfintersecting_data#
return self-intersecting faces
- property style#
Object style in the form of a BaseStyle object. Input must be in the form of a style dictionary.
- to_TriangleCollection()#
Return a Collection of Triangle objects from the current TriangularMesh
- property vertices#
Mesh vertices