magpylib.core package#

Core interface

magpylib.core.current_circle_Hfield(r0: ndarray, r: ndarray, z: ndarray, i0: ndarray) → ndarray#

H-field of i circular line-current loops in cylindrical coordinates.

The loop lies in the z=0 plane with the coordinate origin at its center. The output is proportional to the electrical current i0 in units (A) and independent of the length units chosen for observers and loop radii. The returned field is in units (A/m).

Parameters:

  • r0 (array-like, shape (i,)) – Loop radii, should be positive (r0 > 0).

  • r (array-like, shape (i,)) – Radial observer positions.

  • z (array-like, shape (i,)) – Axial observer positions.

  • i0 (array-like, shape (i,)) – Electrical currents in units (A).

Returns:

H-field in (A/m) at observer positions in cylindrical coordinates (H_r, H_φ, H_z). The azimuthal component is zero for symmetry.

Return type:

ndarray, shape (3, i)

Notes

Implementation based on “Numerically stable and computationally efficient expression for the magnetic field of a current loop.”, M. Ortner et al., Magnetism 2023, 3(1), 11-31.

Examples

>>> import numpy as np
>>> import magpylib as magpy
>>> H = magpy.core.current_circle_Hfield(
...     r0=np.array([1, 2]),
...     r=np.array([1, 1]),
...     z=np.array([1, 2]),
...     i0=np.array([1, 3]),
... )
>>> print(H.round(3))
[[0.091 0.094]
 [0.    0.   ]
 [0.077 0.226]]
magpylib.core.current_polyline_Hfield(observers: ndarray, segments_start: ndarray, segments_end: ndarray, currents: ndarray) → ndarray#

H-field of i straight current segments in Cartesian coordinates.

The current flows from start to end positions. The field is set to (0, 0, 0) on a line segment. The output is proportional to the current and independent of the length units chosen for observers and dimensions.

Parameters:

  • observers (ndarray, shape (i, 3)) – Observer positions (x, y, z) in Cartesian coordinates.

  • segments_start (ndarray, shape (i, 3)) – Segment start positions (x, y, z) in Cartesian coordinates.

  • segments_end (ndarray, shape (i, 3)) – Segment end positions (x, y, z) in Cartesian coordinates.

  • currents (ndarray, shape (i,)) – Electrical currents (A) in the segments.

Returns:

H-field in (A/m) at the observer positions.

Return type:

ndarray, shape (i, 3)

Notes

Field computation via the Biot-Savart law. See also many resources, e.g., http://www.phys.uri.edu/gerhard/PHY204/tsl216.pdf

Be careful with magnetic fields of isolated, discontinuous segments; they are unphysical and can lead to unphysical effects.

Examples

>>> import numpy as np
>>> import magpylib as magpy
>>> H = magpy.core.current_polyline_Hfield(
...     observers=np.array([(1.0, 1.0, 1.0), (2.0, 2.0, 2.0)]),
...     segments_start=np.array([(0.0, 0.0, 0.0), (0.0, 0.0, 0.0)]),
...     segments_end=np.array([(1.0, 0.0, 0.0), (-1.0, 0.0, 0.0)]),
...     currents=np.array([100.0, 200.0]),
... )
>>> with np.printoptions(precision=3):
...     print(H)
[[ 0.    -2.297  2.297]
 [ 0.     0.598 -0.598]]
magpylib.core.current_sheet_Hfield(observers: ndarray, vertices: ndarray, current_densities: ndarray) → ndarray#

H-field of i triangular current sheets.

Parameters:

  • observers (array-like, shape (i, 3)) – Observer positions in Cartesian coordinates.

  • vertices (array-like, shape (i, 3, 3)) – Triangle vertex positions ((P11, P12, P13), (P21, P22, P23), …) in Cartesian coordinates.

  • current_densities (array-like, shape (i, 3)) – Electrical current density vectors. The current density in a sheet is the projection of the vector onto the sheet.

Returns:

H-field in unit of current_densities input at observer positions.

Return type:

ndarray, shape (i, 3)

Notes

Field computation via law of Biot Savart. See also countless online resources. eg. http://www.phys.uri.edu/gerhard/PHY204/tsl216.pdf

Internally, each triangle is transformed to an elementar current sheet defined by the vertices (0, 0, 0), (u1, 0, 0), and (u2, v2, 0) in a local frame; computations are performed there and transformed back to the global frame.

Examples

Compute the H-field generated by a single triangle sheet at one observer position (0, 0, 1):

>>> import numpy as np
>>> from magpylib._src.fields.field_BH_current_sheet import current_sheet_Hfield
>>> np.set_printoptions(formatter={'float': '{:.2e}'.format})
>>> verts = np.array([[(0.0, 0.0, 0.0), (1.0, 0.0, 0.0), (0.0, 1.0, 0.0)]])
>>> J = np.array([(1.0, 0.0, 0.0)])
>>> H = current_sheet_Hfield(np.array([(0.0, 0.0, 1.0)]), verts, J)
>>> print(H)
[[0.00e+00 -2.70e-02 -8.32e-03]]
magpylib.core.dipole_Hfield(observers: ndarray, moments: ndarray) → ndarray#

Magnetic field of i dipole moments in Cartesian coordinates.

The dipole moment lies in the origin of the coordinate system. The output is proportional to the moment input, and is independent of length units used for observers (and moment) input considering that the moment is proportional to [L]**2. Returns np.inf for all non-zero moment components in the origin.

Parameters:

  • observers (ndarray, shape (i, 3)) – Observer positions (x, y, z) in Cartesian coordinates.

  • moments (ndarray, shape (i, 3)) – Dipole moment vectors at the origin.

Returns:

H-field in units of moments input in Cartesian coordinates.

Return type:

ndarray, shape (i, 3)

Notes

  • The moment of a magnet is given by its volume times magnetization.

  • At r = 0, non-zero moment components yield np.inf in the corresponding field components.

Examples

>>> import numpy as np
>>> import magpylib as magpy
>>> H = magpy.core.dipole_Hfield(
...    observers=np.array([(1.0, 1.0, 1.0), (2.0, 2.0, 2.0)]),
...    moments=np.array([(1e5, 0.0, 0.0), (0.0, 0.0, 1e5)]),
... )
>>> with np.printoptions(precision=3):
...     print(H)
[[2.895e-13 1.531e+03 1.531e+03]
 [1.914e+02 1.914e+02 3.619e-14]]
magpylib.core.magnet_cuboid_Bfield(observers: ndarray, dimensions: ndarray, polarizations: ndarray)#

B-field of i homogeneously magnetized cuboids in Cartesian coordinates.

Cuboid sides are parallel to the coordinate axes and the geometric center lies at the origin. The output is proportional to the polarization magnitude and independent of the length units chosen for observers and dimensions.

Parameters:

  • observers (array-like, shape (i, 3)) – Observer positions (x, y, z) in Cartesian coordinates.

  • dimensions (array-like, shape (i, 3)) – Lengths of the cuboid sides (a, b, c).

  • polarizations (array-like, shape (i, 3)) – Magnetic polarization vectors J.

Returns:

B-field in units of input polarization at the observer positions.

Return type:

ndarray, shape (i, 3)

Notes

Field computations use magnetic surface charge density; similar expressions were published repeatedly, e.g. Yang (Supercond. Sci. Technol. 3(12):591, 1990), Engel-Herbert (J. Appl. Phys. 97(7):074504-4, 2005), and Camacho (Rev. Mex. Fís. E 59 (2013) 8-17).

Avoiding indeterminate forms: at positions along extensions of edges (in all xyz-octants except the bottom negative-x/positive-y/positive-z quadrant), direct evaluation becomes numerically unstable. We exploit symmetry to map positions to their bottom-quadrant counterparts; see also Cichon, IEEE Sensors Journal 19(7):2509, 2019.

Examples

>>> import numpy as np
>>> import magpylib as magpy
>>> B = magpy.core.magnet_cuboid_Bfield(
...     observers=np.array([(1, 1, 1), (2, 2, 2)]),
...     dimensions=np.array([(1, 1, 1), (1, 2, 3)]),
...     polarizations=np.array([(0, 0, 1), (0.5, 0.5, 0.0)]),
... )
>>> with np.printoptions(precision=3):
...     print(B)
[[ 1.561e-02  1.561e-02 -3.534e-17]
 [ 7.732e-03  6.544e-03  1.048e-02]]
magpylib.core.magnet_cylinder_axial_Bfield(z0: ndarray, r: ndarray, z: ndarray) → list#

B-field of i axially magnetized cylinders in cylindrical coordinates.

The cylinder axes coincide with the z-axis of the Cylindrical CS and the geometric center of the cylinder lies in the origin. Length inputs are made dimensionless by division over the cylinder radii. Unit polarization is assumed.

Parameters:

  • z0 (ndarray, shape (i,)) – Ratios of half cylinder heights to cylinder radii.

  • r (ndarray, shape (i,)) – Ratios of radial observer positions to cylinder radii.

  • z (ndarray, shape (i,)) – Ratios of axial observer positions to cylinder radii.

Returns:

B-field components (Br, Bphi, Bz) in units (T) at the observer positions, for unit polarization. Values scale linearly with the polarization magnitude.

Return type:

ndarray, shape (3, i)

Notes

Implementation based on: Derby, American Journal of Physics 78(3) (2010), 229-235.

Examples

>>> import numpy as np
>>> import magpylib as magpy
>>> B = magpy.core.magnet_cylinder_axial_Bfield(
...    z0=np.array([1.0, 2.0]),
...    r=np.array([1.0, 2.0]),
...    z=np.array([2.0, 3.0]),
... )
>>> with np.printoptions(precision=3):
...    print(B)
[[0.056 0.041]
 [0.    0.   ]
 [0.067 0.018]]
magpylib.core.magnet_cylinder_diametral_Hfield(z0: ndarray, r: ndarray, z: ndarray, phi: ndarray) → list#

H-field of i diametrally magnetized cylinders in cylindrical coordinates.

The cylinder axes coincide with the z-axis of the Cylindrical CS and the geometric center of the cylinder lies in the origin. Length inputs are made dimensionless by division over the cylinder radii. Unit magnetization is assumed.

Parameters:

  • z0 (ndarray, shape (i,)) – Ratios of cylinder heights to cylinder radii.

  • r (ndarray, shape (i,)) – Ratios of radial observer positions to cylinder radii.

  • z (ndarray, shape (i,)) – Ratios of axial observer positions to cylinder radii.

  • phi (ndarray, shape (i,)) – Azimuth angles between observers and magnetization directions (radians).

Returns:

H-field components (Hr, Hphi, Hz) in (A/m) at the observer positions, for unit magnetization. Values scale linearly with the magnetization magnitude.

Return type:

ndarray, shape (3, i)

Notes

Implementation partially based on Caciagli, Journal of Magnetism and Magnetic Materials 456 (2018): 423-432, and [Ortner, Leitner, Rauber] (unpublished).

Examples

>>> import numpy as np
>>> import magpylib as magpy
>>> H = magpy.core.magnet_cylinder_diametral_Hfield(
...    z0=np.array([1.0, 2.0]),
...    r=np.array([1.0, 2.0]),
...    z=np.array([2.0, 3.0]),
...    phi=np.array([0.1, np.pi/4]),
... )
>>> with np.printoptions(precision=3):
...     print(H)
[[-0.021  0.007]
 [ 0.005  0.02 ]
 [ 0.055  0.029]]
magpylib.core.magnet_cylinder_segment_Hfield(observers: ndarray, dimensions: ndarray, magnetizations: ndarray) → ndarray#

H-field of i homogeneously magnetized cylinder segments (ring sections).

The cylinder axes coincide with the z-axis of the Cylindrical CS and the geometric center of the cylinder lies in the origin. The result is proportional to the magnetization magnitude, and independent of the length units used for dimensions and observers.

Parameters:

  • observers (array-like, shape (i, 3)) – Observer positions (r, φ, z) in cylindrical coordinates where φ is given in radians and positions.

  • dimensions (array-like, shape (i, 6)) – Segment dimensions (r1, r2, φ1, φ2, z1, z2) where r1 < r2 are inner and outer radii, φ1 < φ2 are azimuth section angles (rad), and z1 < z2 are axial limits.

  • magnetizations (array-like, shape (i, 3)) – Magnetization vectors in spherical coordinates (M, φ, θ) where M is the magnitude, and φ (azimuth) and θ (polar) are angles in radians.

Returns:

H-field in units of magnetization M at observer positions in Cartesian coordinates.

Return type:

ndarray, shape (i, 3)

Notes

Implementation based on F. Slanovc, Journal of Magnetism and Magnetic Materials 559 (2022): 169482.

Examples

>>> import numpy as np
>>> import magpylib as magpy
>>> H = magpy.core.magnet_cylinder_segment_Hfield(
...     observers=np.array([(1.0, 1.0, 2.0), (0.0, 0.0, 0.0)]),
...     dimensions=np.array([(1.0, 2.0, 0.1, 0.2, -1.0, 1.0),
...                           (1.0, 2.0, 0.3, 0.9, 0.0, 1.0)]),
...     magnetizations=np.array([(1.0e7, 0.1, 0.2), (1.0e6, 1.1, 2.2)]),
... )
>>> with np.printoptions(precision=3):
...     print(H)
[[-1948.144 32319.944 17616.886]
 [14167.65   1419.941 17921.646]]
magpylib.core.magnet_sphere_Bfield(observers: ndarray, diameters: ndarray, polarizations: ndarray) → ndarray#

B-field of i homogeneously magnetized spheres in Cartesian coordinates.

The center of the spheres lie in the origin of the coordinate system. The output is proportional to the polarization magnitudes, and independent of the length units chosen for observers and diameters.

Parameters:

  • observers (ndarray, shape (i, 3)) – Observer positions (x, y, z) in Cartesian coordinates.

  • diameters (ndarray, shape (i,)) – Sphere diameters.

  • polarizations (ndarray, shape (i, 3)) – Magnetic polarization vectors.

Returns:

B-field in units of polarization input at the observer positions.

Return type:

ndarray, shape (i, 3)

Notes

Outside the sphere, the field corresponds to a dipole field. Inside, it is 2/3 of the polarization (see e.g., “Theoretical Physics”, Bertelmann).

Examples

>>> import numpy as np
>>> import magpylib as magpy
>>> B = magpy.core.magnet_sphere_Bfield(
...     observers=np.array([(1.0, 1.0, 1.0), (2.0, 2.0, 2.0)]),
...     diameters=np.array([1.0, 2.0]),
...     polarizations=np.array([(1.0, 0.0, 0.0), (1.0, 1.0, 0.0)]),
... )
>>> with np.printoptions(precision=3):
...     print(B)
[[1.187e-18 8.019e-03 8.019e-03]
 [8.019e-03 8.019e-03 1.604e-02]]
magpylib.core.triangle_Bfield(observers: ndarray, vertices: ndarray, polarizations: ndarray) → ndarray#

B-field of i magnetically charged triangular surfaces.

The charge is proportional to the projection of the polarization vectors onto the triangle surfaces. The order of the triangle vertices defines the sign of the surface normal vector (right-hand-rule). The output is proportional to the polarization magnitude, and independent of the length units chosen for observers and vertices.

This function can be used to compute fields of homogeneously magnetized bodies represented by triangular surface meshes. In that case each triangle must be oriented such that its surface normal points outwards.

Parameters:

  • observers (ndarray, shape (i, 3)) – Observer positions (x, y, z) in Cartesian coordinates.

  • vertices (ndarray, shape (i, 3, 3)) – Triangle vertex positions ((P11, P12, P13), (P21, P22, P23), …) in Cartesian coordinates.

  • polarizations (ndarray, shape (i, 3)) – Magnetic polarization vectors.

Returns:

B-field in units of polarization input at the observer positions.

Return type:

ndarray, shape (i, 3)

Notes

Returns (0, 0, 0) at corners.

Field computation follows Guptasarma, Geophysics, 1999, 64(1), 70-74. Loss of precision occurs when approaching a triangle as (x - edge)**2 and with distance from the triangle as (distance**3).

Examples

>>> import numpy as np
>>> import magpylib as magpy
>>> B = magpy.core.triangle_Bfield(
...    observers=np.array([(2.0, 1.0, 1.0), (2.0, 2.0, 2.0)]),
...    vertices=np.array([
...        [(0.0, 0.0, 0.0), (0.0, 0.0, 1.0), (1.0, 0.0, 0.0)],
...        [(0.0, 0.0, 0.0), (0.0, 0.0, 1.0), (1.0, 0.0, 0.0)],
...    ]),
...    polarizations=np.array([(1.0, 1.0, 1.0), (1.0, 1.0, 0.0)]) * 1e3,
... )
>>> with np.printoptions(precision=3):
...    print(B)
[[7.452 4.62  3.136]
 [2.213 2.677 2.213]]