magpylib

[![Actions Status][actions-badge]][actions-link] [![Documentation Status][rtd-badge]][rtd-link]

[![PyPI version][pypi-version]][pypi-link] [![Conda-Forge][conda-badge]][conda-link] [![PyPI platforms][pypi-platforms]][pypi-link]

[![GitHub Discussion][github-discussions-badge]][github-discussions-link]

[![Coverage][coverage-badge]][coverage-link]

[actions-badge]: https://github.com/magpylib/magpylib/actions/workflows/ci.yml/badge.svg [actions-link]: https://github.com/magpylib/magpylib/actions [conda-badge]: https://img.shields.io/conda/vn/conda-forge/magpylib [conda-link]: https://github.com/conda-forge/magpylib-feedstock [github-discussions-badge]: https://img.shields.io/static/v1?label=Discussions&message=Ask&color=blue&logo=github [github-discussions-link]: https://github.com/magpylib/magpylib/discussions [pypi-link]: https://pypi.org/project/magpylib/ [pypi-platforms]: https://img.shields.io/pypi/pyversions/magpylib [pypi-version]: https://img.shields.io/pypi/v/magpylib [rtd-badge]: https://readthedocs.org/projects/magpylib/badge/?version=latest [rtd-link]: https://magpylib.readthedocs.io/en/latest/?badge=latest [coverage-badge]: https://codecov.io/github/magpylib/magpylib/branch/main/graph/badge.svg [coverage-link]: https://codecov.io/github/magpylib/magpylib

[!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 an open-source Python package for calculating static **magnetic fields of magnets, currents, and other sources. It uses analytical expressions**, solutions to macroscopic magnetostatic problems, implemented in vectorized form which makes the computation extremely fast and leverages the open-source Python ecosystem for spectacular visualizations!

Installation

Install from PyPI using pip

pip install magpylib

Install from conda forge using conda

conda install -c conda-forge magpylib

Magpylib supports _Python3.11+_ and relies on common scientific computation libraries _NumPy_, _Scipy_, _Matplotlib_ and _Plotly_. Optionally, _Pyvista_ is recommended as graphical backend.

Resources

• Check out our Documentation

• Please abide by our

• Contribute through

• A Youtube video

• An

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, -0.02), (1, 0, -0.02), (2, 0, -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.2.2},
    date = {2023-06-25},
}