3.0.0
Overview
This is a major update that includes
- API changes
- New features
- Improved internal workings
Interface changes
- 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 functiongetBv()
. - The
.math
sub-package was removed. Functionalities are mostly provided by thescipy - Rotation
package. - The top level function
displaySystem()
was renamed todisplay()
.
Source class attribute changes
All parameters are now in explicit format following the Zen of Python and cannot be initialized in their short forms anymore.
angle
andaxis
are replaced byorientation
dimension
is replaced bydiameter
for Circular and Sphere classes.
The new orientation attribute (CORE FEATURE OF v3)
- 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 ascipy.spatial.transform.Rotation
object.- Calling the attribute
source.orientation
returns a scipy Rotation objectR
. - Make use of all advantages of this great scipy package:
- define
R.from_rotvec()
orR.from_quat()
or ... - view with
R.as_rotvec()
orR.as_quat()
or ... - combine subsequent rotations
R1 * R2 * R3
- define
New ways to work with Collections and Sources
- 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
- construct as
- 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 tocol[i]
.
The Sensor class
- The new
Sensor(position, pixel, orientation)
class has the argumentpixel
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).
Streamlining operation with all Magpylib objects
All objects (Sensors, Sources, Collections) have additional direct access to
.display()
method for quick self-inspection.getB()
andgetH()
methods for fast field computations__repr__
attribute defined and will return their type and theirid
.
Class method changes
- The class methods
.rotate(angle, axis, anchor)
have been replaced by a new.rotate(rotation, anchor, increment, start)
method whererotation
ist a scipyRotation
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 thedegrees
argument.
- The 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
andstart
arguments. - All operations can now be chained (e.g.
.move_by().rotate().move_to()
)
Paths (CORE FEATURE OF v3)
- The
position
andorientation
attributes can now store paths in the global CS. For a path of length M the attributeposition
is an array of the shape (M,3) andorientation
is a Rotation object with lenghth M. Each path position is associated with a respective rotation. - Field computations
getB()
andgetH()
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 therotate
andmove
methods. - Paths can be shown via the
show_path=True
kwarg indisplay()
. By settingshow_path=x
the object will be displayed at everyx
'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 toposition=(0,0,0)
andorientation=None
.
Compute magnetic fields (CORE FEATURE OF v3)
- 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 withpixel
shape (N1, N2, ..., 3) or a 1D list of K Sensors.
- The argument
- With Magpylib3 there are several ways to compute the field:
source.getB(*observers)
sensor.getB(*sources)
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.
magpylib.getBv(**kwargs)
gives direct access to the field formulas and mostly replaces thegetBv_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 usegetB()
which mostly provides the same performance. Specifically,the newgetB()
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 newgetH
returns the field in [kA/m].
Miscellaneous and Config
- 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 settingConfig.ITER_CYLINDER=50
.