All notable changes to magpylib are documented here.



This is a major update that includes

  • API changes

  • New features

  • Improved internal workings


  • New sources classes:

    • New CylinderSegment computation with sector angles (r1,r2,h,phi1,phi2). (#386, #385)

    • New CustomSource class for user defined field functions (#349, #409, #411)

  • New display features:

    • 🚀 New plotly plotting backend: (#396, #353)

      • plotly remains a optional dependency, needs extra installation (#395)

      • Interactive animation feature with animation_time and animation_fps display arguments

    • Display defaults can be now set in magpylib.defaults.display (#291, #396)

    • Ability to define extra 3d-model for any object. (#416)

    • Zoom option in display function.

    • Display specific path positions.

    • matplotlib plotting backend:

      • Added matplotlib pixel display (#279)

  • Documentation and Example codes now available on read the docs with binder links and live code. (#389)

  • Collection objects can now be composed of sources, sensors or both types. The getB and getH functions accommodate for all cases. (#410, #415, #297)

  • Add all scipy Rotation forms as object methods (#427)


  • Box class renamed to Cuboid. (#350)

  • Circular class renamed to Loop. (#402)

  • magpylib.defaults.edgesize set to 1e-8 by default to avoid problems in Cuboid corners.

  • Magpylib objects can now be initialized without excitation and without dimension attributes.

  • magpylib.Config parameters are now in magpylib.defaults (#387)

  • getBv and getHv are renamed to getB_dict and getH_dict (#294)

  • Renamed display arguments

    • axis ➡️ canvas

    • show_direction ➡️ style_magnetization_show

    • show_path ➡️ path

    • size_sensors&size_dipoles ➡️ style_size

    • size_direction ➡️ style_magnetization_size


  • Computation:

    • Updated Cylinder computation with a new exact closed form implementation without iteration, from a new paper (F.Slanovc, preprint-2021). Computation times are around 50-100 µs, with some performance improvement planned in the future.

    • Added __len__ dunder for Collection (#383)

    • Improved performance of getB and getH functions and methods.

    • Improved numerical stability (#374)

  • Docs:


  • Computation:

    • Diametral Solid Cylinder Field singularity at the axis. (#370)

    • Collection of Lines return incorret field (#368)

    • Field array dimension wrongly reduced when sumup=True and squeeze=False ind getB and getH functions (#425, #426)

  • UI:

    • Adding multiple Collection objects does not mutate the first element.

    • Fix empty display (#401)


  • config.ITERCYLINDER is now obsolete. The iterative solution replaced by a new analytical expression.

3.0.2 - 2021-06-27

This is a major update that includes

  • API changes

  • New features

  • Improved internal workings


  • New orientation property:

    • The orientation attribute stores the relative rotation of an object with respect to the reference orientation (defined in each class docstring).

    • The default (orientation=None) corresponds to a unit rotation.

    • orientation is stored as a scipy.spatial.transform.Rotation object.

    • Calling the attribute source.orientation returns a scipy Rotation object R.

    • Make use of all advantages of this great scipy package:

      • define R.from_rotvec() or R.from_quat() or …

      • view with R.as_rotvec() or R.as_quat() or …

      • combine subsequent rotations R1 * R2 * R3

  • Sensor pixel:

    • The new Sensor(position, pixel, orientation) class has the argument pixel which is (0,0,0) by default and refers to pixel positions inside the Sensor (in the Sensor local CS). pixel is an arbitrary array_like of the shape (N1, N2, …, 3).

  • Geometry paths:

    • The position and orientation attributes can now store paths in the global CS. For a path of length M the attribute position is an array of the shape (M,3) and orientation is a Rotation object with length M. Each path position is associated with a respective rotation.

    • Field computations getB() and getH() will evaluate the field for all source path positions.

    • Paths can be set by hand position = X, orientation = Y, but they can also conveniently be generated using the rotate and move methods.

    • Paths can be shown via the show_path=True kwarg in display(). By setting show_path=x the object will be displayed at every x’th path step. This helps to follow up on object rotation along the path.

    • All objects have a reset_path() method defined to set their paths to position=(0,0,0) and orientation=None.

  • Streamlining operation with all Magpylib objects:

    • All objects (Sensors, Sources, Collections) have additional direct access to

      • .display() method for quick self-inspection.

      • getB() and getH() methods for fast field computations

      • __repr__ attribute defined and will return their type and their id.

  • Other new features:

    • The top-level Config allows users to access and edit Magpylib default values.


  • Renamed modules:

    • .magnet and .current sub-packages were moved to the top level.

    • The .moment sub-package was renamed to .misc and was moved to the top level.

    • The .vector sub-package was completely removed. Functionalities are mostly replaced by new top-level function getBv().

    • The .math sub-package was removed. Functionalities are mostly provided by the scipy - Rotation package.

  • Renamed functions:

    • The top level function displaySystem() was renamed to display().

  • Renamed attributes (parameters cannot be initialized in their short forms anymore):

    • angle and axis are replaced by orientation

    • dimension is replaced by diameter for Loop and Sphere classes.

    • angle&axis are replaced by orientation (see Added Section)

  • Modified rotate methods:

    • The class methods .rotate(angle, axis, anchor) have been replaced by a new .rotate(rotation, anchor, increment, start) method where rotation ist a scipy Rotation object.

    • The original angle-axis-anchor rotation is now provided by the new method .rotate_from_angax(angle, axis, anchor, increment, start, degrees).

      • The argument axis can now easily be set to the global CS axes with "x", "y", "z".

      • The anchor argument anchor=0 represents the origin (0,0,0).

      • angle argument is in units of deg by default. It can now be set to rad using the degrees argument.

    • The “move”-class method is now .move(displacement, increment, start)

    • Rotation and move methods can now be used to generate paths using vector input and the increment and start arguments.

    • All operations can now be chained (e.g. .move_by().rotate().move_to())

  • Miscellaneous:

    • getB(pos) now takes single AND vector position arguments. If a vector is handed to getB it will automatically execute vectorized code from the vector module.

    • In a finite region (size defined by Config.EDGESIZE) about magnet edges and line currents the field evaluates to (0,0,0) instead of (NaN, NaN, NaN). Special case catching reduces performance slightly.


  • Improved Computation:

    • The Box field is now more stable. Numerical instabilities in the outfield were completely removed.

  • Updated Field computation interface

    • There are two fundamental arguments for field computation:

      • The argument sources refers to a source/Collection or to a 1D list of L sources and/or Collections.

      • The argument observers refers to a set of positions of shape (N1, N2, …, 3) or a Sensor with pixel shape (N1, N2, …, 3) or a 1D list of K Sensors.

    • With Magpylib3 there are several ways to compute the field:

      1. source.getB(*observers)

      2. sensor.getB(*sources)

      3. magpylib.getB(sources, observers)

      • The output shape is always (L, M, K, N1, N2, …, 3) with L sources, M path positions, K sensors and N (pixel) positions.

      • Objects with shorter paths will be considered as static once their path ends while other paths still continue.

      1. magpylib.getBv(**kwargs) gives direct access to the field formulas and mostly replaces the getBv_XXX() functionality of v2. All inputs must be arrays of length N or of length 1 (statics will be tiled).

    • While getBv is the fastest way to compute the fields it is much more convenient to use getB() which mostly provides the same performance. Specifically,the new getB() automatically groups all inputs for combined vectorized evaluation. This leads to a massive speedup when dealing with large Collections of similar sources.

    • In addition to getB, the new getH returns the field in [kA/m].


  • the kwarg niter=50 does not exist anymore for the Cylinder field computation. The functionality was completely replaced by the config setting Config.ITER_CYLINDER=50.

2.3.0b - 2020-01-17


  • Improved performance of getB for diametral magnetized Cylinders by 20%.

  • GetB of Line current now uses vectorized code which leads to massive performance enhancement.

  • IMPORTANT: position arguments of getBv functions have been flipped! First comes the source position POSm THEN the observer position POSo!


  • completed the library vector functionality adding magnet Cylinder, moment Dipole, current Loop and Line. This includes adding several private vectorized functions (e.g. ellipticV) to mathLib_vector, adding respective tests and docs examples.

2.1.0b - 2019-12-06


  • Docstrings for vector functions.

  • displaySystem kwarg figsize

  • bringing documentation up to speed


  • init file bug

2.0.0b - 2019-11-29

This is a major update that includes

API changes New features Improved internal workings


  • Restructuring

    • displaySystem is now a top-level function, not a Collection method anymore.

    • getBsweep and multiprocessing options have been completely removed, this functionality should be overtaken by the new vector functionality which uses the numpy native vectorized code paradigm. If mkl library is set (test by numpy.show_config()) numpy will also automatically use multiprocessing. Code parallelization at magpylib level should be done by hand.

  • Docstrings are adjusted to work better with intellisense. (Problems with *.rst code)

  • public rotatePosition() is now called angleAxisRotation(), former private angleAxisRotation is now called angleAxisRotation_priv().

  • Major rework of the documentation and examples.


  • Performance computation trough vector functionality included in new top-level subpackage “vector”

  • Vectorized versions of math functions added to “math” subpackage

1.2.1b0 - 2019-07-31


  • Optimized getB call (utility integrated)

  • Improved Documentation (added Sensor class v1)

1.2.0b0 - 2019-07-16


  • Sensor Class

    • This allows users to create a coordinate system-enabled Sensor object, which can be placed, rotated, moved and oriented.

    • This object can take the B-Field of a system (be it single source or a Collection) with the added functionality of having its own reference in the coordinate space, allowing users to easily acquire relative B-Field measurements of a system from an arbitrarily placed sensor object.

    • Sensors in a list may be displayed in the Collection.displaySystem() by using the sensors keyword argument.

  • Added content to the __repr__ builtin to all source classes for quick console evaluations, simply call a defined object in your Python shell to print out its attributes.


  • Edge cases in field calculations now return a proper RuntimeWarning instead of console prints


  • Unused imports and variables

1.1.1b0 - 2019-06-25


  • Changelog


  • Change Collection.displaySystem() not having the block=False setting for matplotlib’s by default, this meant that outside interactive mode calling this function would hang the script until the plot was closed.

    • If for some reason you want to block the application, you may still use Collection.displaySystem()’s suppress=True kwarg then call normally.

    • This should cause no API changes, if you have problems please notify us.


  • Fix multiprocessing enabled Collection.getBsweep() for lots of objects with few positions causing great performance loss. This functionality now behaves as expected for the use case.

  • Fix Collection.displaySystem()’s drawing of Dipole objects in external axes (plots) using the subplotAx kwarg crashing the application. This functionality now behaves as expected for the use case.

1.1.0b0 - 2019-06-14


  • Implemented one new kwarg for Collection.displaySystem():

    subplotAx=None Draw into a subplot axe that already exists. The subplot needs to be 3D projected

    This allows for creating side-by-side plots using displaySystem. Figure information must be set manually in pyplot.figure() in order to not squash the plots upon subplotting.

    Click here for Example


    Output: image


  • getBsweep() for Collections and Sources now always returns a numpy array

  • Zero-length segments in Line sources now return [0,0,0] and a warning, making it easier to draw spirals without letting users do this unaware.


  • Added a workaround fix for a rotation bug we are still working on.

1.0.2b0 - 2019-05-29


  • file containing the LICENSE for bundling in PyPi

1.0.1b0 - 2019-05-28


  • Issue and Pull Request Templates to Repository

  • Continuous Integration settings (Azure and Appveyor)

  • Code Coverage Reports with codecov


  • Support for Python 3.5 and under.

1.0.0b0 - 2019-05-21

The first official release of the magpylib library.


  • Source classes:

    • Box

    • Cylinder

    • Sphere

    • Loop Current

    • Current Line

    • Dipole

  • Collection class

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.