> [!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](https://github.com/magpylib/magpylib/discussions/647))
<p align="left"><img align="center" src=docs/_static/images/magpylib_flag.png width=35%>
</p>
---
<div>
<a href="https://opensource.org/licenses/BSD-2-Clause"> <img src="https://img.shields.io/badge/License-BSD_2--Clause-orange.svg">
</a>
<a href="https://github.com/magpylib/magpylib/actions/workflows/python-app.yml"> <img src="https://github.com/magpylib/magpylib/actions/workflows/python-app.yml/badge.svg">
</a>
<a href="https://magpylib.readthedocs.io/en/latest/"> <img src="https://readthedocs.org/projects/magpylib/badge/?version=latest">
</a>
<a href="https://codecov.io/gh/magpylib/magpylib"> <img src="https://codecov.io/gh/magpylib/magpylib/branch/main/graph/badge.svg">
</a>
<a href="https://pypi.org/project/magpylib/"> <img src="https://badge.fury.io/py/magpylib.svg" alt="PyPI version" height="18">
</a>
<a href="https://anaconda.org/conda-forge/magpylib"> <img src="https://anaconda.org/conda-forge/magpylib/badges/version.svg" alt="Conda Cloud" height="18">
</a>
<a href="https://mybinder.org/v2/gh/magpylib/magpylib/5.0.0?filepath=docs%2Fexamples"> <img src="https://mybinder.org/badge_logo.svg" alt="MyBinder link" height="18">
</a>
<a href="https://github.com/psf/black"> <img src="https://img.shields.io/badge/code%20style-black-000000.svg" alt="black" height="18">
</a>
</div>
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](https://magpylib.readthedocs.io/en/latest)** for detailed information.
- Please abide by our **[Code of Conduct](https://github.com/magpylib/magpylib/blob/main/CODE_OF_CONDUCT.md)**.
- Contribute through **[Discussions](https://github.com/magpylib/magpylib/discussions)** and coding by following the **[Contribution Guide](https://github.com/magpylib/magpylib/blob/main/CONTRIBUTING.md)**. The Git project **[Issues](https://github.com/magpylib/magpylib/issues)** give an up-to-date list of potential enhancements and planned milestones. Propose new ones.
- A **[Youtube video](https://www.youtube.com/watch?v=LeUx6cM1vcs)** introduction to Magpylib v4.0.0 within the **[GSC network](https://www.internationalcollaboration.org/).**
- An **[open-access paper](https://www.sciencedirect.com/science/article/pii/S2352711020300170)** 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.
```python
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](https://magpylib.readthedocs.io/en/latest)**. 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](https://www.sciencedirect.com/science/article/pii/S2352711020300170) 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},
}
```
Raw data
{
"_id": null,
"home_page": null,
"name": "magpylib",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "Alexandre Boisselet <alexabois+magpylib@gmail.com>",
"keywords": "magnetism, physics, analytical, electromagnetic, magnetic-field, B-field",
"author": null,
"author_email": "Michael Ortner <magpylib@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/19/d3/8603a7392382bcc8927443281adcd8292318598c8889084f85acbc4a2ddb/magpylib-5.0.1.tar.gz",
"platform": null,
"description": "\n> [!WARNING]\n> 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](https://github.com/magpylib/magpylib/discussions/647))\n\n<p align=\"left\"><img align=\"center\" src=docs/_static/images/magpylib_flag.png width=35%>\n</p>\n\n---\n\n<div>\n<a href=\"https://opensource.org/licenses/BSD-2-Clause\"> <img src=\"https://img.shields.io/badge/License-BSD_2--Clause-orange.svg\">\n</a>\n<a href=\"https://github.com/magpylib/magpylib/actions/workflows/python-app.yml\"> <img src=\"https://github.com/magpylib/magpylib/actions/workflows/python-app.yml/badge.svg\">\n</a>\n<a href=\"https://magpylib.readthedocs.io/en/latest/\"> <img src=\"https://readthedocs.org/projects/magpylib/badge/?version=latest\">\n</a>\n<a href=\"https://codecov.io/gh/magpylib/magpylib\"> <img src=\"https://codecov.io/gh/magpylib/magpylib/branch/main/graph/badge.svg\">\n</a>\n<a href=\"https://pypi.org/project/magpylib/\"> <img src=\"https://badge.fury.io/py/magpylib.svg\" alt=\"PyPI version\" height=\"18\">\n</a>\n<a href=\"https://anaconda.org/conda-forge/magpylib\"> <img src=\"https://anaconda.org/conda-forge/magpylib/badges/version.svg\" alt=\"Conda Cloud\" height=\"18\">\n</a>\n<a href=\"https://mybinder.org/v2/gh/magpylib/magpylib/5.0.0?filepath=docs%2Fexamples\"> <img src=\"https://mybinder.org/badge_logo.svg\" alt=\"MyBinder link\" height=\"18\">\n</a>\n<a href=\"https://github.com/psf/black\"> <img src=\"https://img.shields.io/badge/code%20style-black-000000.svg\" alt=\"black\" height=\"18\">\n</a>\n</div>\n\nMagpylib 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.\n\n# Installation\n\nInstall from PyPI using **pip**\n```\npip install magpylib\n```\nInstall from conda forge using **conda**\n```\nconda install -c conda-forge magpylib\n```\nMagpylib supports _Python3.8+_ and relies on common scientific computation libraries _Numpy_, _Scipy_, _Matplotlib_ and _Plotly_. Optionally, _Pyvista_ is recommended as graphical backend.\n\n# Resources\n\n - Check out our **[Documentation](https://magpylib.readthedocs.io/en/latest)** for detailed information.\n - Please abide by our **[Code of Conduct](https://github.com/magpylib/magpylib/blob/main/CODE_OF_CONDUCT.md)**.\n - Contribute through **[Discussions](https://github.com/magpylib/magpylib/discussions)** and coding by following the **[Contribution Guide](https://github.com/magpylib/magpylib/blob/main/CONTRIBUTING.md)**. The Git project **[Issues](https://github.com/magpylib/magpylib/issues)** give an up-to-date list of potential enhancements and planned milestones. Propose new ones.\n - A **[Youtube video](https://www.youtube.com/watch?v=LeUx6cM1vcs)** introduction to Magpylib v4.0.0 within the **[GSC network](https://www.internationalcollaboration.org/).**\n- An **[open-access paper](https://www.sciencedirect.com/science/article/pii/S2352711020300170)** from the year 2020 describes v2 of this library with most basic concepts still intact in later versions.\n\n# Quickstart\n\nHere is an example on how to use Magpylib.\n\n```python\nimport magpylib as magpy\n\n# Create a Cuboid magnet with sides 1,2 and 3 cm respectively, and a polarization\n# of 1000 mT pointing in x-direction.\ncube = magpy.magnet.Cuboid(\n polarization=(1, 0, 0), # in SI Units (T)\n dimension=(0.01, 0.02, 0.03), # in SI Units (m)\n)\n\n# By default, the magnet position is (0,0,0) and its orientation is the unit\n# rotation (given by a scipy rotation object), which corresponds to magnet sided\n# parallel to global coordinate axes.\nprint(cube.position) # --> [0. 0. 0.]\nprint(cube.orientation.as_rotvec()) # --> [0. 0. 0.]\n\n# Manipulate object position and orientation through the respective attributes,\n# or by using the powerful `move` and `rotate` methods.\ncube.move((0, 0, -0.02))# in SI Units (m)\ncube.rotate_from_angax(angle=45, axis=\"z\")\nprint(cube.position) # --> [0. 0. -0.02]\nprint(cube.orientation.as_rotvec(degrees=True)) # --> [0. 0. 45.]\n\n# Compute the magnetic B-field in units of T at a set of observer positions. Magpylib\n# makes use of vectorized computation. Hand over all field computation instances,\n# e.g. different observer positions, at one function call. Avoid Python loops !!!\nobservers = [(0, 0, 0), (0.01, 0, 0), (0.02, 0, 0)] # in SI Units (m)\nB = magpy.getB(cube, observers)\nprint(B.round(2)) # --> [[-0.09 -0.09 0. ]\n# [ 0. -0.04 0.08]\n# [ 0.02 -0.01 0.03]] # in SI Units (T)\n\n# Sensors are observer objects that can have their own position and orientation.\n# Compute the H-field in units of A/m.\nsensor = magpy.Sensor(position=(0, 0, 0))\nsensor.rotate_from_angax(angle=45, axis=(1, 1, 1))\nH = magpy.getH(cube, sensor)\nprint(H.round()) # --> [-94537. -35642. -14085.] # in SI Units (A/m)\n\n# Position and orientation attributes of Magpylib objects can be vectors of\n# multiple positions/orientations referred to as \"paths\". When computing the\n# magnetic field of an object with a path, it is computed at every path index.\ncube.position = [(0, 0, -.02), (1, 0, -.02), (2, 0, -.02)] # in SI Units (m)\nB = cube.getB(sensor)\nprint(B.round(2)) # --> [[-0.12 -0.04 -0.02]\n# [ 0. -0. 0. ]\n# [ 0. -0. 0. ]] # in SI Units (T)\n\n# When several objects are involved and things are getting complex, make use of\n# the `show` function to view your system through Matplotlib, Plotly or Pyvista backends.\nmagpy.show(cube, sensor, backend=\"pyvista\")\n```\n\nMore details and other important features are described in detail in the **[Documentation](https://magpylib.readthedocs.io/en/latest)**. Key features are:\n\n- **Collections**: Group multiple objects for common manipulation\n- **Complex shapes**: Create magnets with arbitrary shapes\n- **Graphics**: Styling options, graphic backends, animations, and 3D models\n- **CustomSource**: Integrate your own field implementation\n- **Direct interface**: Bypass the object oriented interface (max speed)\n\n# How can I cite this library ?\n\nWe would be happy if you give us credit for our efforts. A valid bibtex entry for the [2020 open-access paper](https://www.sciencedirect.com/science/article/pii/S2352711020300170) would be\n\n```\n@article{ortner2020magpylib,\n title={Magpylib: A free Python package for magnetic field computation},\n author={Ortner, Michael and Bandeira, Lucas Gabriel Coliado},\n journal={SoftwareX},\n volume={11},\n pages={100466},\n year={2020},\n publisher={Elsevier}\n}\n```\n\nA valid software citation could be\n\n```\n@software{magpylib,\n author = {{Michael-Ortner et al.}},\n title = {magpylib},\n url = {https://magpylib.readthedocs.io/en/latest/},\n version = {5.0.1},\n date = {2023-06-25},\n}\n```\n\n",
"bugtrack_url": null,
"license": null,
"summary": "Free Python3 package to compute magnetic fields.",
"version": "5.0.1",
"project_urls": {
"Bug Tracker": "https://github.com/magpylib/magpylib/issues",
"Changelog": "https://github.com/magpylib/magpylib/blob/master/CHANGELOG.md",
"Documentation": "https://magpylib.readthedocs.io/en/latest/",
"Repository": "https://github.com/magpylib/magpylib.git"
},
"split_keywords": [
"magnetism",
" physics",
" analytical",
" electromagnetic",
" magnetic-field",
" b-field"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "ebc6ec74e54b75f6386115a6a4bec66e8ad4ffb7af695b0b71c74d4f3242f731",
"md5": "2c742d222308d877c8a2a8beb4e60cf2",
"sha256": "a9d5967be0897bdb6965e53fe7777f6d685ca8ecb2db4baa2fad383954bba8d6"
},
"downloads": -1,
"filename": "magpylib-5.0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "2c742d222308d877c8a2a8beb4e60cf2",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 184906,
"upload_time": "2024-04-12T06:53:01",
"upload_time_iso_8601": "2024-04-12T06:53:01.427774Z",
"url": "https://files.pythonhosted.org/packages/eb/c6/ec74e54b75f6386115a6a4bec66e8ad4ffb7af695b0b71c74d4f3242f731/magpylib-5.0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "19d38603a7392382bcc8927443281adcd8292318598c8889084f85acbc4a2ddb",
"md5": "7a38cba43520f1ce78476ce2e41456c4",
"sha256": "80f0d387f779ef4a7583c999555cfe0d603f37aabbc4b57f25dac22db035efb2"
},
"downloads": -1,
"filename": "magpylib-5.0.1.tar.gz",
"has_sig": false,
"md5_digest": "7a38cba43520f1ce78476ce2e41456c4",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 10354729,
"upload_time": "2024-04-12T06:53:03",
"upload_time_iso_8601": "2024-04-12T06:53:03.833917Z",
"url": "https://files.pythonhosted.org/packages/19/d3/8603a7392382bcc8927443281adcd8292318598c8889084f85acbc4a2ddb/magpylib-5.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-04-12 06:53:03",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "magpylib",
"github_project": "magpylib",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "magpylib"
}
JSON
