magpylib.func package

Functional interface

magpylib.func.circle_field(field, observers, diameters, currents, positions=(0, 0, 0), orientations=None, squeeze=True)

Return B- or H-field of circular current loops for i instances.

With positions=(0, 0, 0) and orientations=None a loop lies in the z=0 plane with its center at the origin. Positive current flows in the mathematically positive (counter-clockwise) direction.

Parameters:

• field ({'B', 'H'}) – Select which field is returned.

• observers (array-like, shape (3,) or (i, 3)) – Points where the field is evaluated in units (m).

• diameters (float | array-like, shape (i,)) – Loop diameters in units (m).

• currents (float | array-like, shape (i,)) – Electric currents in units (A).

• positions (array-like, shape (3,) or (i, 3), default (0, 0, 0)) – Loop centers in units (m).

• orientations (None | Rotation, default None) – Loop orientations. If None, the unit rotation is applied.

• squeeze (bool, default True) – If True, squeeze singleton axis when i=1.

Returns:

Field at the observer locations.

Return type:

ndarray, shape (3,) or (i, 3)

Notes

Returns (0, 0, 0) on the loop.

Examples

>>> import numpy as np
>>> from magpylib.func import circle_field
>>> B = circle_field(
...     field='B',
...     observers=(0.2, 0.3, 0.1),
...     diameters=(1.0, 1.5),
...     currents=1.0
... )
>>> with np.printoptions(precision=3):
...     print(B)
[[3.863e-07 5.795e-07 1.604e-06]
 [6.756e-08 1.013e-07 9.694e-07]]

magpylib.func.cuboid_field(field, observers, dimensions, polarizations, positions=(0, 0, 0), orientations=None, squeeze=True)

Return B- or H-field of cuboid magnets for i instances.

With positions=(0, 0, 0) and orientations=None the cuboid sides are parallel to the coordinate axes and the geometric center lies at the origin.

Parameters:

• field ({'B', 'H'}) – Select which field is returned.

• observers (array-like, shape (3,) or (i, 3)) – Points where the field is evaluated in units (m).

• dimensions (array-like, shape (3,) or (i, 3)) – Cuboid sides (a, b, c) in units (m).

• polarizations (array-like, shape (3,) or (i, 3)) – Magnetic polarization in units (T).

• positions (array-like, shape (3,) or (i, 3), default (0, 0, 0)) – Cuboid centers in units (m).

• orientations (None | Rotation, default None) – Cuboid orientations. If None, the unit rotation is applied.

• squeeze (bool, default True) – If True, squeeze singleton axis when i=1.

Returns:

Field at the observer locations.

Return type:

ndarray, shape (3,) or (i, 3)

Notes

Returns (0, 0, 0) on edges and corners.

Examples

>>> import numpy as np
>>> from magpylib.func import cuboid_field
>>> B = cuboid_field(
...     field='B',
...     observers=(0.2, 1.3, 1.1),
...     dimensions=[(1.0, 1.0, 1.0), (2.0, 2.0, 2.0)],
...     polarizations=(0.0, 0.0, 1.0),
... )
>>> with np.printoptions(precision=3):
...     print(B)
[[ 0.003  0.023  0.004]
 [ 0.017  0.206 -0.006]]

magpylib.func.cylinder_field(field, observers, dimensions, polarizations, positions=(0, 0, 0), orientations=None, squeeze=True)

Return B- or H-field of solid cylinder magnets for i instances.

With positions=(0, 0, 0) and orientations=None the cylinder axis coincides with the global z-axis and the geometric center lies at the origin.

Parameters:

• field ({'B', 'H'}) – Select which field is returned.

• observers (array-like, shape (3,) or (i, 3)) – Points where the field is evaluated in units (m).

• dimensions (array-like, shape (2,) or (i, 2)) – Cylinder dimensions (diameter, height) in units (m).

• polarizations (array-like, shape (3,) or (i, 3)) – Magnetic polarization in units (T).

• positions (array-like, shape (3,) or (i, 3), default (0, 0, 0)) – Cylinder centers in units (m).

• orientations (None | Rotation, default None) – Cylinder orientations. If None, the unit rotation is applied.

• squeeze (bool, default True) – If True, squeeze singleton axis when i=1.

Returns:

Field at the observer locations.

Return type:

ndarray, shape (3,) or (i, 3)

Notes

Returns (0, 0, 0) on edges.

Examples

>>> import numpy as np
>>> from magpylib.func import cylinder_field
>>> B = cylinder_field(
...     field='B',
...     observers=(0.2, 1.3, 1.1),
...     dimensions=[(1.0, 1.0), (2.0, 2.0)],
...     polarizations=(0.0, 0.0, 1.0),
... )
>>> with np.printoptions(precision=3):
...     print(B)
[[ 0.003  0.018  0.002]
 [ 0.026  0.17  -0.006]]

magpylib.func.cylinder_segment_field(field, observers, dimensions, polarizations, positions=(0, 0, 0), orientations=None, squeeze=True)

Return B- or H-field of cylinder-segment magnets for i instances.

With positions=(0, 0, 0) and orientations=None the segment’s cylinder axis coincides with the global z-axis and the geometric center lies at the origin.

Parameters:

• field ({'B', 'H'}) – Select which field is returned.

• observers (array-like, shape (3,) or (i, 3)) – Points where the field is evaluated in units (m).

• dimensions (array-like, shape (5,) or (i, 5)) – Segment dimensions (r1, r2, h, φ1, φ2) where r1 < r2 are inner and outer radii in units (m), h is the height in units (m), and φ1 < φ2 are azimuth section angles in radians (rad).

• polarizations (array-like, shape (3,) or (i, 3)) – Magnetic polarization in units (T).

• positions (array-like, shape (3,) or (i, 3), default (0, 0, 0)) – Cylinder centers in units (m).

• orientations (None | Rotation, default None) – Magnet orientations. If None, the unit rotation is applied.

• squeeze (bool, default True) – If True, squeeze singleton axis when i=1.

Returns:

Field at the observer locations.

Return type:

ndarray, shape (3,) or (i, 3)

Notes

Returns (0, 0, 0) on surface, edges, and corners.

Examples

>>> import numpy as np
>>> from magpylib.func import cylinder_segment_field
>>> B = cylinder_segment_field(
...     field='B',
...     observers=(0.2, 0.3, 0.1),
...     dimensions=[(1.0, 2.0, 1.0, 45, 225), (1.0, 2.0, 1.0, 90, 270)],
...     polarizations=(0.0, 0.0, 1.0),
... )
>>> with np.printoptions(precision=3):
...    print(B)
[[ 0.006 -0.017 -0.122]
 [ 0.011 -0.004 -0.084]]

magpylib.func.dipole_field(field, observers, moments, positions=(0, 0, 0), orientations=None, squeeze=True)

Return B- or H-field of magnetic dipoles for i instances.

With positions=(0, 0, 0) and orientations=None local and global coordinates coincide and the dipole lies at the origin.

Parameters:

• field ({'B', 'H'}) – Select which field is returned.

• observers (array-like, shape (3,) or (i, 3)) – Points where the field is evaluated in units (m).

• moments (array-like, shape (3,) or (i, 3)) – Magnetic dipole moments in units (A m²).

• positions (array-like, shape (3,) or (i, 3), default (0, 0, 0)) – Dipole positions in units (m).

• orientations (None | Rotation, default None) – Orientation of local coordinates. If None, the unit rotation is applied.

• squeeze (bool, default True) – If True, squeeze singleton axis when i=1.

Returns:

Field at the observer locations.

Return type:

ndarray, shape (3,) or (i, 3)

Notes

Returns inf or nan at the dipole position.

Examples

>>> import numpy as np
>>> from magpylib.func import dipole_field
>>> B = dipole_field(
...     field='B',
...     observers=(1.2, 0.3, 0.1),
...     moments=[(1e6, 0, 0), (0, 1e6, 0)]
... )
>>> with np.printoptions(precision=3):
...     print(B)
[[ 0.094  0.037  0.012]
 [ 0.037 -0.043  0.003]]

magpylib.func.polyline_field(field, observers, segments_start, segments_end, currents, positions=(0, 0, 0), orientations=None, squeeze=True)

Return B- or H-field of straight current segments for i instances.

With positions=(0, 0, 0) and orientations=None local and global coordinates coincide. Current flows in straight lines from segment start to end positions. The field is set to (0, 0, 0) on the segments.

Parameters:

• field ({'B', 'H'}) – Select which field is returned.

• observers (array-like, shape (3,) or (i, 3)) – Points where the field is evaluated in units (m).

• segments_start (array-like, shape (3,) or (i, 3)) – Segment start points in units (m).

• segments_end (array-like, shape (3,) or (i, 3)) – Segment end points in units (m).

• currents (float | array-like, shape (i,)) – Electric currents in units (A).

• positions (array-like, shape (3,) or (i, 3), default (0, 0, 0)) – Local coordinate origin in units (m).

• orientations (None | Rotation, default None) – Local coordinate orientations. If None, the unit rotation is applied.

• squeeze (bool, default True) – If True, squeeze singleton axis when i=1.

Notes

Returns (0, 0, 0) on the line segments.

Returns:

Field at the observer locations.

Return type:

ndarray, shape (3,) or (i, 3)

Examples

>>> import numpy as np
>>> from magpylib.func import polyline_field
>>> B = polyline_field(
...     field='B',
...     observers=(0.2, 0.3, 0.1),
...     segments_start=[(-0.5, -1.0, 0), (-1.0, -1.0, 0)],
...     segments_end=[(0.5, 1.0, 0), (1.0, 1.0, 0)],
...     currents=1e6
... )
>>> with np.printoptions(precision=3):
...     print(B)
[[ 1.481 -0.741 -0.741]
 [ 0.939 -0.939  0.939]]

magpylib.func.sphere_field(field, observers, diameters, polarizations, positions=(0, 0, 0), orientations=None, squeeze=True)

Return B- or H-field of sphere magnets for i instances.

With positions=(0, 0, 0) and orientations=None local and global coordinates coincide and the sphere center lies at the origin.

Parameters:

• field ({'B', 'H'}) – Select which field is returned.

• observers (array-like, shape (3,) or (i, 3)) – Points where the field is evaluated in units (m).

• diameters (float | array-like, shape (i,)) – Sphere diameters in units (m).

• polarizations (array-like, shape (3,) or (i, 3)) – Magnetic polarization in units (T).

• positions (array-like, shape (3,) or (i, 3), default (0, 0, 0)) – Sphere centers in units (m).

• orientations (None | Rotation, default None) – Magnet orientations. If None, the unit rotation is applied.

• squeeze (bool, default True) – If True, squeeze singleton axis when i=1.

Returns:

Field at the observer locations.

Return type:

ndarray, shape (3,) or (i, 3)

Examples

>>> import numpy as np
>>> from magpylib.func import sphere_field
>>> B = sphere_field(
...     field='B',
...     observers=(1.2, 0.3, 0.1),
...     diameters=(1.0, 1.5),
...     polarizations=(0.0, 0.0, 1.0),
... )
>>> with np.printoptions(precision=3):
...     print(B)
[[ 0.005  0.001 -0.021]
 [ 0.017  0.004 -0.072]]

magpylib.func.tetrahedron_field(field, observers, vertices, polarizations, positions=(0, 0, 0), orientations=None, squeeze=True)

Return B- or H-field of tetrahedron magnets for i instances.

With positions=(0, 0, 0) and orientations=None local and global coordinates coincide. The tetrahedron is defined by four vertices in the local coordinate system.

Parameters:

• field ({'B', 'H'}) – Select which field is returned.

• observers (array-like, shape (3,) or (i, 3)) – Points where the field is evaluated in units (m).

• vertices (array-like, shape (4, 3) or (i, 4, 3)) – Vertices of the tetrahedra in units (m).

• polarizations (array-like, shape (3,) or (i, 3)) – Magnetic polarization in units (T).

• positions (array-like, shape (3,) or (i, 3), default (0, 0, 0)) – Position of local coordinate origin in units (m).

• orientations (None | Rotation, default None) – Orientation of local coordinates. If None, the unit rotation is applied.

• squeeze (bool, default True) – If True, squeeze singleton axis when i=1.

Returns:

Field at the observer locations.

Return type:

ndarray, shape (3,) or (i, 3)

Notes

Returns (0, 0, 0) on corners.

Examples

>>> import numpy as np
>>> from magpylib.func import tetrahedron_field
>>> B = tetrahedron_field(
...     field='B',
...     observers=(-.2, 0.3, 0.1),
...     vertices=[
...         ((0, 0, 0), (1, 0, 0), (0, 1, 0), (0, 0, 1)),
...         ((0, 0, 0), (2, 0, 0), (0, 2, 0), (0, 0, 2)),
...     ],
...     polarizations=(0.0, 0.0, 1.0),
... )
>>> with np.printoptions(precision=3):
...     print(B)
[[ 0.065 -0.007 -0.075]
 [ 0.146  0.026 -0.09 ]]

magpylib.func.triangle_charge_field(field, observers, vertices, polarizations, positions=(0, 0, 0), orientations=None, squeeze=True)

Return B- or H-field of magnetically charged triangles for i instances.

With positions=(0, 0, 0) and orientations=None local and global coordinates coincide. Triangles are defined by three vertices in the local coordinates.

Parameters:

• field ({'B', 'H'}) – Select which field is returned.

• observers (array-like, shape (3,) or (i, 3)) – Points where the field is evaluated in units (m).

• vertices (array-like, shape (3, 3) or (i, 3, 3)) – Triangle vertices [(V1a, V1b, V1c), (V2a, V2b, V2c), …] in units (m).

• polarizations (array-like, shape (3,) or (i, 3)) – Magnetic polarization in units (T).

• positions (array-like, shape (3,) or (i, 3), default (0, 0, 0)) – Position of local coordinate origin in units (m).

• orientations (None | Rotation, default None) – Orientation of local coordinates. If None, the unit rotation is applied.

• squeeze (bool, default True) – If True, squeeze singleton axis when i=1.

Returns:

Field at the observer locations.

Return type:

ndarray, shape (3,) or (i, 3)

Notes

Returns (0, 0, 0) on corners.

Examples

>>> import numpy as np
>>> from magpylib.func import triangle_charge_field
>>> B = triangle_charge_field(
...     field='B',
...     observers=(1.2, 0.3, 0.1),
...     vertices=[
...         ((0, 0, 0), (1, 0, 0), (0, 1, 0)),
...         ((0, 0, 0), (2, 0, 0), (0, 2, 0)),
...         ],
...     polarizations=[0, 0, 1],
... )
>>> with np.printoptions(precision=3):
...     print(B)
[[ 0.06   0.009  0.01 ]
 [ 0.11  -0.074  0.403]]

magpylib.func.triangle_current_field(field, observers, vertices, current_densities, positions=(0, 0, 0), orientations=None, squeeze=True)

Return B- or H-field of triangular current sheets for i instances.

With positions=(0, 0, 0) and orientations=None local and global coordinates coincide. Triangles are defined by three vertices in the local coordinates.

Parameters:

• field ({'B', 'H'}) – Select which field is returned.

• observers (array-like, shape (3,) or (i, 3)) – Points where the field is evaluated in units (m).

• vertices (array-like, shape (3, 3) or (i, 3, 3)) – Triangle vertices in units (m).

• current_densities (array-like, shape (3,) or (i, 3)) – Surface current densities in units (A/m²).

• positions (array-like, shape (3,) or (i, 3), default (0, 0, 0)) – Position of local coordinate origin in units (m).

• orientations (None | Rotation, default None) – Orientation of local coordinates. If None, the unit rotation is applied.

• squeeze (bool, default True) – If True, squeeze singleton axis when i=1.

Returns:

Field at the observer locations.

Return type:

ndarray, shape (3,) or (i, 3)

Notes

Returns (0, 0, 0) on a sheet.

Examples

>>> import numpy as np
>>> from magpylib.func import triangle_current_field
>>> B = triangle_current_field(
...     field='B',
...     observers=(1.2, 0.3, 0.1),
...     vertices=[
...         ((0, 0, 0), (1, 0, 0), (0, 1, 0)),
...         ((0, 0, 0), (2, 0, 0), (0, 2, 0)),
...         ],
...     current_densities=(1e6, 1e6, 1e6),
... )
>>> with np.printoptions(precision=3):
...     print(B)
[[ 0.012 -0.012 -0.065]
 [ 0.506 -0.506 -0.231]]