magpylib/magpylib 3.0.0 on GitHub

This is a major update that includes

The .magnet and .current sub-packges 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.
The top level function displaySystem() was renamed to display().

All parameters are now in explicit format following the Zen of Python and cannot be initialized in their short forms anymore.

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

The construction col = Collection(src1, col1, [src2, ...],...) now features
- arbitrary input levels,
- input oder is kept,
- duplicates are automatically removed.
The method .addSources() is now called .add()
The method .removeSource() is now called .remove()
Sources and Collections nove have +/- operations defined:
- construct as col1 = src1 + src2 + col2
- remove as col1 - src1
Collection objects are now iterable themselves. The iteration goes over their col.sources attribute. [s for s in col.sources] is similar to [s for s in col]
Collections have getitem defined. col.sources[i] is similar to col[i].

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).

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

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 gloabl 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 unsing 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())

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 lenghth 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.

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.
4. 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 top-level Config allows users to access and edit Magpylib default values.
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.
The Box field is now more stable. Numerical instabilities in the outfield were completely removed.
By default (turn off in Config.CHECK_INPUTS) Magplyib now performs some checks of the input format to alert the user and avoid cryptic error messages.
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.