Warning

Version 5 introduces critical breaking changes with, among others, the move to SI units. We recommended to pin your dependencies to magpylib>=4.5<5 until you are ready to migrate to the latest version! (see details)

---

Magpylib is a Python package for calculating 3D static magnetic fields of magnets, line currents and other sources. The computation is based on explicit expressions and is therefore extremely fast. A user friendly API enables convenient positioning of sources and observers.

Installation

Install from PyPI using pip

pip install magpylib

Install from conda forge using conda

conda install -c conda-forge magpylib

Magpylib supports Python3.8+ and relies on common scientific computation libraries Numpy, Scipy, Matplotlib and Plotly. Optionally, Pyvista is recommended as graphical backend.

Resources

• Check out our Documentation for detailed information.
• Please abide by our Code of Conduct.
• Contribute through Discussions and coding by following the Contribution Guide. The Git project Issues give an up-to-date list of potential enhancements and planned milestones. Propose new ones.
• A Youtube video introduction to Magpylib v4.0.0 within the GSC network.
• An open-access paper from the year 2020 describes v2 of this library with most basic concepts still intact in later versions.

Quickstart

Here is an example on how to use Magpylib.

import magpylib as magpy

# Create a Cuboid magnet with sides 1,2 and 3 cm respectively, and a polarization
# of 1000 mT pointing in x-direction.
cube = magpy.magnet.Cuboid(
    polarization=(1, 0, 0),  # in SI Units (T)
    dimension=(0.01, 0.02, 0.03),  # in SI Units (m)
)

# By default, the magnet position is (0,0,0) and its orientation is the unit
# rotation (given by a scipy rotation object), which corresponds to magnet sided
# parallel to global coordinate axes.
print(cube.position)  # --> [0. 0. 0.]
print(cube.orientation.as_rotvec())  # --> [0. 0. 0.]

# Manipulate object position and orientation through the respective attributes,
# or by using the powerful `move` and `rotate` methods.
cube.move((0, 0, -0.02))# in SI Units (m)
cube.rotate_from_angax(angle=45, axis="z")
print(cube.position)  # --> [0. 0. -0.02]
print(cube.orientation.as_rotvec(degrees=True))  # --> [0. 0. 45.]

# Compute the magnetic B-field in units of T at a set of observer positions. Magpylib
# makes use of vectorized computation. Hand over all field computation instances,
# e.g. different observer positions, at one function call. Avoid Python loops !!!
observers = [(0, 0, 0), (0.01, 0, 0), (0.02, 0, 0)]  # in SI Units (m)
B = magpy.getB(cube, observers)
print(B.round(2))  # --> [[-0.09 -0.09  0.  ]
#                         [ 0.   -0.04  0.08]
#                         [ 0.02 -0.01  0.03]]  # in SI Units (T)

# Sensors are observer objects that can have their own position and orientation.
# Compute the H-field in units of A/m.
sensor = magpy.Sensor(position=(0, 0, 0))
sensor.rotate_from_angax(angle=45, axis=(1, 1, 1))
H = magpy.getH(cube, sensor)
print(H.round())  # --> [-94537. -35642. -14085.]  # in SI Units (A/m)

# Position and orientation attributes of Magpylib objects can be vectors of
# multiple positions/orientations referred to as "paths". When computing the
# magnetic field of an object with a path, it is computed at every path index.
cube.position = [(0, 0, -.02), (1, 0, -.02), (2, 0, -.02)]  # in SI Units (m)
B = cube.getB(sensor)
print(B.round(2))  # --> [[-0.12 -0.04 -0.02]
#                         [ 0.   -0.    0.  ]
#                         [ 0.   -0.    0.  ]] # in SI Units (T)

# When several objects are involved and things are getting complex, make use of
# the `show` function to view your system through Matplotlib, Plotly or Pyvista backends.
magpy.show(cube, sensor, backend="pyvista")

More details and other important features are described in detail in the Documentation. Key features are:

• Collections: Group multiple objects for common manipulation
• Complex shapes: Create magnets with arbitrary shapes
• Graphics: Styling options, graphic backends, animations, and 3D models
• CustomSource: Integrate your own field implementation
• Direct interface: Bypass the object oriented interface (max speed)

How can I cite this library ?

We would be happy if you give us credit for our efforts. A valid bibtex entry for the 2020 open-access paper would be

@article{ortner2020magpylib,
  title={Magpylib: A free Python package for magnetic field computation},
  author={Ortner, Michael and Bandeira, Lucas Gabriel Coliado},
  journal={SoftwareX},
  volume={11},
  pages={100466},
  year={2020},
  publisher={Elsevier}
}

A valid software citation could be

@software{magpylib,
    author = {{Michael-Ortner et al.}},
    title = {magpylib},
    url = {https://magpylib.readthedocs.io/en/latest/},
    version = {5.0.1},
    date = {2023-06-25},
}