# magpylib package¶

## Welcome to Magpylib !¶

Magpylib provides static 3D magnetic field computation for permanent magnets, currents and other sources using (semi-) analytical formulas from the literature.

## Resources¶

Github repository:

https://github.com/magpylib/magpylib

Original software publication (version 2):

https://www.sciencedirect.com/science/article/pii/S2352711020300170

## Introduction (version 4.0.0dev)¶

Magpylib uses units of

• [mT]: for the B-field and the magnetization (mu0*M).

• [kA/m]: for the H-field.

• [mm]: for all position inputs.

• [deg]: for angle inputs by default.

• [A]: for current inputs.

## Magpylib objects¶

The most convenient way to compute magnetic fields is through the object oriented interface. Magpylib objects represent magnetic field sources and sensors with various defining attributes.

```>>> import magpylib as magpy
>>>
>>> # magnets
>>> src1 = magpy.magnet.Cuboid(magnetization=(0,0,1000), dimension=(1,2,3))
>>> src2 = magpy.magnet.Cylinder(magnetization=(0,1000,0), dimension=(1,2))
>>> src3 = magpy.magnet.CylinderSegment(magnetization=(0,1000,0), dimension=(1,2,2,45,90))
>>> src4 = magpy.magnet.Sphere(magnetization=(1000,0,0), diameter=1)
>>>
>>> # currents
>>> src5 = magpy.current.Loop(current=15, diameter=3)
>>> src6 = magpy.current.Line(current=15, vertices=[(0,0,0), (1,2,3)])
>>>
>>> # misc
>>> src7 = magpy.misc.Dipole(moment=(100,200,300))
>>>
>>> # sensor
>>> sens = magpy.Sensor()
>>>
>>> # print object representation
>>> for obj in [src1, src2, src3, src4, src5, src6, src7, sens]:
>>>     print(obj)
Cuboid(id=1331541150016)
Cylinder(id=1331541148672)
CylinderSegment(id=1331541762784)
Sphere(id=1331541762448)
Loop(id=1331543166304)
Line(id=1331543188720)
Dipole(id=1331543189632)
Sensor(id=1331642701760)
```

## Position and orientation¶

All Magpylib objects are endowed with `position` (ndarray, shape (m,3)) and `orientation` (scipy Rotation object, shape (m,3)) attributes that describe their state in a global coordinate system. Details on default object position (0-position) and alignment (unit-rotation) are found in the respective docstrings.

```>>> import magpylib as magpy
>>> sens = magpy.Sensor()
>>> print(sens.position)
>>> print(sens.orientation.as_euler('xyz', degrees=True))
[0. 0. 0.]
[0. 0. 0.]
```

Manipulate position and orientation attributes directly through source attributes, or by using built-in `move`, `rotate` or `rotate_from_angax` methods.

```>>> import magpylib as magpy
>>> from scipy.spatial.transform import Rotation as R
>>>
>>> sens = magpy.Sensor(position=(1,1,1))
>>> print(sens.position)
>>>
>>> sens.move((1,1,1))
>>> print(sens.position)
>>>
[1. 1. 1.]
[2. 2. 2.]
```
```>>> sens = magpy.Sensor(orientation=R.from_euler('x', 10, degrees=True))
>>> print(sens.orientation.as_euler('xyz'))
>>>
>>> sens.rotate(R.from_euler('x', 10, degrees=True)))
>>> print(sens.orientation.as_euler('xyz'))
>>>
>>> sens.rotate_from_angax(angle=10, axis=(1,0,0))
>>> print(sens.orientation.as_euler('xyz'))
[10 0. 0.]
[20 0. 0.]
[30 0. 0.]
```

Source position and orientation attributes can also represent complete source paths in the global coordinate system. Such paths can be generated conveniently using the `move` and `rotate` methods.

```>>> import magpylib as magpy
>>>
>>> src = magpy.magnet.Cuboid(magnetization=(1,2,3), dimension=(1,2,3))
>>> src.move([(1,1,1),(2,2,2),(3,3,3),(4,4,4)], start='append')
>>> print(src.position)
[[0. 0. 0.]  [1. 1. 1.]  [2. 2. 2.]  [3. 3. 3.]  [4. 4. 4.]]
```

Details on rotation arguments, and how to conveniently generate complex paths are found in the docstings and some examples below.

## Grouping objects with Collection¶

The top level class `magpylib.Collection` allows a user to group sources for common manipulation. A Collection functions like a list of source objects extended by Magpylib source methods: all operations applied to a Collection are applied to each source individually. Specific sources in the Collection can still be accessed and manipulated individually.

```>>> import magpylib as magpy
>>>
>>> src1 = magpy.magnet.Cuboid(magnetization=(0,0,11), dimension=(1,2,3))
>>> src2 = magpy.magnet.Cylinder(magnetization=(0,22,0), dimension=(1,2))
>>> src3 = magpy.magnet.Sphere(magnetization=(33,0,0), diameter=2)
>>>
>>> col = magpy.Collection(src1, src2, src3)
>>> col.move((1,2,3))
>>> src1.move((1,2,3))
>>>
>>> for src in col:
>>>     print(src.position)
[2. 4. 6.]
[1. 2. 3.]
[1. 2. 3.]
```

Magpylib sources have addition and subtraction methods defined, adding up to a Collection, or removing a specific source from a Collection.

```>>> import magpylib as magpy
>>>
>>> src1 = magpy.misc.Dipole(moment=(1,2,3))
>>> src2 = magpy.current.Loop(current=1, diameter=2)
>>> src3 = magpy.magnet.Sphere(magnetization=(1,2,3), diameter=1)
>>>
>>> col = src1 + src2 + src3
>>>
>>> for src in col:
>>>     print(src)
Dipole(id=2158565624128)
Loop(id=2158565622784)
Sphere(id=2158566236896)
```
```>>> col - src1
>>>
>>> for src in col:
>>>     print(src)
Loop(id=2158565622784)
Sphere(id=2158566236896)
```

## Graphic output with display¶

When all source and sensor objects are created and all paths are defined `display` (top level function and method of all Magpylib objects) provides a convenient way to graphically view the geometric arrangement through Matplotlib.

```>>> import magpylib as magpy
>>>
>>> # create a Collection of three sources
>>> s1 = magpy.magnet.Sphere(magnetization=(0,0,100), diameter=3, position=(3,0,0))
>>> s2 = magpy.magnet.Cuboid(magnetization=(0,0,100), dimension=(2,2,2), position=(-3,0,0))
>>> col = s1 + s2
>>>
>>> # generate a spiral path
>>> s1.move([(.2,0,0)]*100, increment=True)
>>> s2.move([(-.2,0,0)]*100, increment=True)
>>> col.rotate_from_angax([5]*100, 'z', anchor=0, increment=True, start=0)
>>>
>>> # display
>>> col.display(zoom=-.3, show_path=10)
---> graphic output
```

Various arguments like axis, show_direction, show_path, size_sensors, size_direction, size_dipoles and zoom can be used to customize the output and are described in the docstring in detail.

## Field computation¶

Field computation is done through the `getB` and `getH` function/methods. They always require sources and observers inputs. Sources are single Magpylib source objects, Collections or lists thereof. Observers are arbitrary tensors of position vectors (shape (n1,n2,n3,…,3)), sensors or lists thereof. A most fundamental field computation example is

```>>> from magpylib.magnet import Cylinder
>>>
>>> src = Cylinder(magnetization=(222,333,444), dimension=(2,2))
>>> B = src.getB((1,2,3))
>>> print(B)
[-2.74825633  9.77282601 21.43280135]
```

The magnetization input is in units of [mT], the B-field is returned in [mT], the H-field in [kA/m]. Field computation is also valid inside of the magnets.

```>>> import numpy as np
>>> import matplotlib.pyplot as plt
>>> import magpylib as magpy
>>>
>>> # define Pyplot figure
>>> fig, [ax1,ax2] = plt.subplots(1, 2, figsize=(10,5))
>>>
>>> # define Magpylib source
>>> src = magpy.magnet.Cuboid(magnetization=(500,0,500), dimension=(2,2,2))
>>>
>>> # create a grid in the xz-symmetry plane
>>> ts = np.linspace(-3, 3, 30)
>>> grid = np.array([[(x,0,z) for x in ts] for z in ts])
>>>
>>> # compute B field on grid using a source method
>>> B = src.getB(grid)
>>> ampB = np.linalg.norm(B, axis=2)
>>>
>>> # compute H-field on grid using the top-level function
>>> H = magpy.getH(src, grid)
>>> ampH = np.linalg.norm(H, axis=2)
>>>
>>> # display field with Pyplot
>>> ax1.streamplot(grid[:,:,0], grid[:,:,2], B[:,:,0], B[:,:,2],
>>>     density=2, color=np.log(ampB), linewidth=1, cmap='autumn')
>>>
>>> ax2.streamplot(grid[:,:,0], grid[:,:,2], H[:,:,0], H[:,:,2],
>>>     density=2, color=np.log(ampH), linewidth=1, cmap='winter')
>>>
>>> # outline magnet boundary
>>> for ax in [ax1,ax2]:
>>>     ax.plot([1,1,-1,-1,1], [1,-1,-1,1,1], 'k--')
>>>
>>> plt.tight_layout()
>>> plt.show()
---> graphic output
```

The output of the most general field computation through the top level function `magpylib.getB(sources, observers)` is an ndarray of shape (l,m,k,n1,n2,n3,…,3) where l is the number of input sources, m the pathlength, k the number of sensors, n1,n2,n3,… the sensor pixel shape or shape of position vector and 3 the three magnetic field components (Bx,By,Bz).

```>>> import magpylib as magpy
>>>
>>> # three sources
>>> s1 = magpy.misc.Dipole(moment=(0,0,100))
>>> s2 = magpy.current.Loop(current=1, diameter=3)
>>> col = s1 + s2
>>>
>>> # two observers with 4x5 pixel
>>> pix = [[(1,2,3)]*4]*5
>>> sens1 = magpy.Sensor(pixel=pix)
>>> sens2 = magpy.Sensor(pixel=pix)
>>>
>>> # path of length 11
>>> s1.move([(1,1,1)]*11)
>>>
>>> B = magpy.getB([s1,s2,col], [sens1, sens2])
>>> print(B.shape)
(3, 11, 2, 5, 4, 3)
```

The object-oriented interface automatically vectorizes the computation for the user. Similar source types of multiple input-objects are automatically tiled up.

## getB_dict and getH_dict¶

The `magpylib.getB_dict` and `magpylib.getH_dict` top-level functions avoid the object oriented interface, yet enable usage of the position/orientation implementations. The input arguments must be shape (n,x) vectors/lists/tuple. Static inputs e.g. of shape (x,) are automatically tiled up to shape (n,x). Depending on the source_type, different input arguments are expected (see docstring for details).

```>>> import magpylib as magpy
>>>
>>> # observer positions
>>> poso = [(0,0,x) for x in range(5)]
>>>
>>> # magnet dimensions
>>> dim = [(d,d,d) for d in range(1,6)]
>>>
>>> # getB_dict computation - magnetization is automatically tiled
>>> B = magpy.getB_dict(
>>>     source_type='Cuboid',
>>>     magnetization=(0,0,1000),
>>>     dimension=dim,
>>>     observer=poso)
>>> print(B)
[[  0.           0.         666.66666667]
[  0.           0.         435.90578315]
[  0.           0.         306.84039675]
[  0.           0.         251.12200327]
[  0.           0.         221.82226656]]
```

The `getBH_dict` functions can be up to 2 times faster than the object oriented interface. However, this requires that the user knows how to properly generate the vectorized input.

For users who do not want to use the position/orientation interface, Magpylib offers direct access to the vectorized analytical implementations that lie at the bottom of the library through the `magpylib.lib` subpackage. Details on the implementations can be found in the respective function docstrings.

```>>> import numpy as np
>>> import magpylib as magpy
>>>
>>> mag = np.array([(100,0,0)]*5)
>>> dim = np.array([(1,2,45,90,-1,1)]*5)
>>> poso = np.array([(0,0,0)]*5)
>>>
>>> B = magpy.lib.magnet_cyl_tile_H_Slanovc2021(mag, dim, poso)
>>> print(B)
[[   0.           0.        -186.1347833]
[   0.           0.        -186.1347833]
[   0.           0.        -186.1347833]
[   0.           0.        -186.1347833]
[   0.           0.        -186.1347833]]
```

As all input checks, coordinate transformations and position/orientation implementation are avoided, this is the fastest way to compute fields in Magpylib.

class magpylib.Collection(*objects)

Bases: `magpylib._src.obj_classes.class_BaseDisplayRepr.BaseDisplayRepr`, `magpylib._src.obj_classes.class_BaseRotation.BaseRotation`

Group multiple objects in one Collection for common manipulation.

Operations applied to a Collection are sequentially applied to all objects in the Collection. Collections do not allow duplicate objects (will be eliminated automatically).

Collections have the following dunders defined: __add__, __sub__, __iter__, __getitem__, __repr__.

Depending on the input, Collection objects can be sources, observers or both. A Collection with only source objects will become either a SourceCollection, one with only Sensors a SensorCollection, and one with sources and sensors a MixedCollection A SourceCollection functions like any SINGLE source. A SensorCollection functions like a list of observer inputs. A MixedCollection will function as source or as observer.

Parameters

objects (sources, sensors, collections or arbitrary lists thereof) – Ordered list of objects in the Collection.

Returns

Collection object

Return type

Collection

Examples

Create Collections for common manipulation. All objects added to a Collection are stored in the `objects` attribute, and additionally in the `sensors` and `sources` attributes. These three return ordered sets (lists with unique elements only)

```>>> import magpylib as magpy
>>> sphere = magpy.magnet.Sphere((1,2,3),1)
>>> loop = magpy.current.Loop(1,1)
>>> dipole = magpy.misc.Dipole((1,2,3))
>>> col = magpy.Collection(sphere, loop, dipole)
>>> print(col.objects)
[Sphere(id=1879891544384), Loop(id=1879891543040), Dipole(id=1879892157152)]
```

Cycle directly through the Collection `objects` attribute

```>>> for src in col:
>>>    print(src)
Sphere(id=1879891544384)
Loop(id=1879891543040)
Dipole(id=1879892157152)
```

and directly access objects from the Collection

```>>> print(col[1])
Loop(id=1879891543040)
```

Add and subtract objects to form a Collection and to remove objects from a Collection.

```>>> col = sphere + loop
>>> print(col.objects)
[Sphere(id=1879891544384), Loop(id=1879891543040)]
>>> col - sphere
>>> print(col.objects)
[Loop(id=1879891543040)]
```

Manipulate all objects in a Collection directly using `move` and `rotate` methods

```>>> import magpylib as magpy
>>> sphere = magpy.magnet.Sphere((1,2,3),1)
>>> loop = magpy.current.Loop(1,1)
>>> col = sphere + loop
>>> col.move((1,1,1))
>>> print(sphere.position)
[1. 1. 1.]
```

and compute the total magnetic field generated by the Collection.

```>>> B = col.getB((1,2,3))
>>> print(B)
[-0.00372678  0.01820438  0.03423079]
```

Consider three collections, a SourceCollection sCol a SensorCollection xCol and a MixedCollection mCol, all made up from the same objects.

```>>> import numpy as np
>>> import magpylib as magpy
```
```>>> s1=magpy.magnet.Sphere((1,2,3), 1)
>>> s2=magpy.magnet.Cylinder((1,2,3), (1,1), (3,0,0))
>>> s3=magpy.magnet.Cuboid((1,2,3), (1,1,1), (6,0,0))
```
```>>> x1=magpy.Sensor((1,0,3))
>>> x2=magpy.Sensor((4,0,3))
>>> x3=magpy.Sensor((7,0,3))
```
```>>> sCol = magpy.Collection(s1, s2, s3)
>>> xCol = magpy.Collection(x1, x2, x3)
>>> mCol = magpy.Collection(sCol, xCol)
```

All the following lines will all give the same output

```>>> magpy.getB([s1,s2,s3], [x1,x2,x3], sumup=True)
>>> magpy.getB(sCol, xCol)
>>> magpy.getB(mCol, mCol)
>>> sCol.getB(xCol)
>>> xCol.getB(sCol)
>>> sCol.getB(mCol)
>>> xCol.getB(mCol)
>>> mCol.getB()
```
_rotate(rotation, anchor=None, start=- 1, increment=False)

rotate_from_XXX generates a scipy Rotation object R then rotate() is called with R then _rotate() is called from rotate() to enable Collection application

Inputs: rotation: scipy rotation object anchor: anchor point start: int or ‘append’, path start position increment: bool, interpretation of path-input

Rotates the object in the global coordinate system by a given rotation input (can be a path).

_update_src_and_sens()

updates source and sensor list when an object is added or removed

_validate_getBH_inputs(*objects)

validate Collection.getBH inputs

Add arbitrary Magpylib objects or Collections.

Parameters

objects (sources, Sensors, Collections or arbitrary lists thereof) – Add arbitrary sequences of objects and Collections to the Collection. The new objects will be added at the end of self.objects. Duplicates will be eliminated.

Returns

self

Return type

Collection

Examples

```>>> import magpylib as magpy
>>> src = magpy.current.Loop(1,1)
>>> col = magpy.Collection()
>>> print(col.objects)
[Loop(id=2519738714432)]
```
copy()

Returns a copy of the Collection.

Returns

self

Return type

Collection

Examples

Create a copy of a Collection object:

```>>> import magpylib as magpy
>>> col = magpy.Collection()
>>> print(id(col))
2221754911040
>>> col2 = col.copy()
>>> print(id(col2))
2221760504160
```
display(*, path=True, zoom=0, animate_time=3, markers=None, backend=None, canvas=None, **kwargs)

Display objects and paths graphically. Style input can be a style-dict or style-underscore_magic.

Parameters
• objects (sources, collections or sensors) – Objects to be displayed.

• path (bool or int i or array_like shape (n,) or ‘animate’, default = True) – Option False shows objects at final path position and hides paths. Option True shows objects at final path position and shows object paths. Option int i displays the objects at every i’th path position. Option array_like shape (n,) discribes certain path indices. The objects displays are displayed at every given path index. Option ‘animate’ (Plotly backend only) shows an animation of objectes moving along their paths.

• zoom (float, default = 0) – Adjust plot zoom-level. When zoom=0 3D-figure boundaries are tight.

• animate_time (float, default = 3) – Sets the animation duration.

• markers (array_like, shape (N,3), default=None) – Display position markers in the global CS. By default no marker is displayed.

• backend (string, default=None) – One of ‘matplotlib’ or ‘plotly’. If not set, parameter will default to magpylib.defaults.display.backend which comes as ‘matplotlib’ with installation.

• canvas (pyplot Axis or plotly Figure, default=None) – Display graphical output in a given canvas: - with matplotlib: pyplot axis (must be 3D). - with plotly: plotly.graph_objects.Figure or plotly.graph_objects.FigureWidget By default a new canvas is created and displayed.

Returns

None

Return type

NoneType

Examples

Display multiple objects, object paths, markers in 3D using Matplotlib or Plotly:

```>>> import magpylib as magpy
>>> src = magpy.magnet.Sphere(magnetization=(0,0,1), diameter=1)
>>> src.move([(.1,0,0)]*50, increment=True)
>>> src.rotate_from_angax(angle=[10]*50, axis='z', anchor=0, start=0, increment=True)
>>> ts = [-.4,0,.4]
>>> sens = magpy.Sensor(position=(0,0,2), pixel=[(x,y,0) for x in ts for y in ts])
>>> magpy.display(src, sens)
>>> magpy.display(src, sens, backend='plotly')
--> graphic output
```

Display figure on your own canvas (here Matplotlib 3D axis):

```>>> import matplotlib.pyplot as plt
>>> import magpylib as magpy
>>> my_axis = plt.axes(projection='3d')
>>> magnet = magpy.magnet.Cuboid(magnetization=(1,1,1), dimension=(1,2,3))
>>> sens = magpy.Sensor(position=(0,0,3))
>>> magpy.display(magnet, sens, canvas=my_axis, zoom=1)
>>> plt.show()
--> graphic output
```

Use sophisticated figure styling options accessible from defaults, as individual object styles or as global style arguments in display.

```>>> import magpylib as magpy
>>> src1 = magpy.magnet.Sphere((1,1,1), 1)
>>> src2 = magpy.magnet.Sphere((1,1,1), 1, (1,0,0))
>>> magpy.defaults.display.style.magnet.magnetization.size = 2
>>> src1.style.magnetization.size = 1
>>> magpy.display(src1, src2, style_color='r', zoom=3)
--> graphic output
```
getB(*objects, sumup=False, squeeze=True)

Compute B-field in [mT] for given sources and observers.

Parameters
• objects (source or observer objects) – If parent is a SourceCollection, input can only be M observers. If parent is a SensorCollection, input can only be L sources.

• sumup (bool, default=False) – If True, the fields of all sources are summed up.

• squeeze (bool, default=True) – If True, the output is squeezed, i.e. all axes of length 1 in the output (e.g. only a single sensor or only a single source) are eliminated.

Returns

B-field – B-field of each source (L) at each path position (M) and each sensor pixel position (N1,N2,…) in units of [mT]. Paths of objects that are shorter than M will be considered as static beyond their end.

Return type

ndarray, shape squeeze(L, M, N1, N2, …, 3)

Examples

getH(*objects, sumup=False, squeeze=True)

Compute H-field in [kA/m] for given sources and observers.

Parameters
• objects (source or observer objects) – If parent is a SourceCollection, input can only be M observers. If parent is a SensorCollection, input can only be L sources.

• sumup (bool, default=False) – If True, the fields of all sources are summed up.

• squeeze (bool, default=True) – If True, the output is squeezed, i.e. all axes of length 1 in the output (e.g. only a single sensor or only a single source) are eliminated.

Returns

H-field – H-field of each source (L) at each path position (M) and each sensor pixel position (N1,N2,…) in units of [kA/m]. Paths of objects that are shorter than M will be considered as static beyond their end.

Return type

ndarray, shape squeeze(L, M, N1, N2, …, 3)

Examples

move(displacement, start=- 1, increment=False)

Translates each object in the Collection individually by the input displacement (can be a path).

This method uses vector addition to merge the input path given by displacement and the existing old path of an object. It keeps the old orientation. If the input path extends beyond the old path, the old path will be padded by its last entry before paths are added up.

Parameters
• displacement (array_like, shape (3,) or (N,3)) – Displacement vector shape=(3,) or path shape=(N,3) in units of [mm].

• start (int or str, default=-1) – Choose at which index of the original object path, the input path will begin. If start=-1, inp_path will start at the last old_path position. If start=0, inp_path will start with the beginning of the old_path. If start=len(old_path) or start=’append’, inp_path will be attached to the old_path.

• increment (bool, default=False) – If increment=False, input displacements are absolute. If increment=True, input displacements are interpreted as increments of each other. For example, an incremental input displacement of [(2,0,0), (2,0,0), (2,0,0)] corresponds to an absolute input displacement of [(2,0,0), (4,0,0), (6,0,0)].

Returns

self

Return type

Collection

Examples

This method will apply the `move` operation to each Collection object individually.

```>>> import magpylib as magpy
>>> dipole = magpy.misc.Dipole((1,2,3))
>>> loop = magpy.current.Loop(1,1)
>>> col = loop + dipole
>>> col.move([(1,1,1), (2,2,2)])
>>> for src in col:
>>>     print(src.position)
[[1. 1. 1.]  [2. 2. 2.]]
[[1. 1. 1.]  [2. 2. 2.]]
```

But manipulating individual objects keeps them in the Collection

```>>> dipole.move((1,1,1))
>>> for src in col:
>>>     print(src.position)
[[1. 1. 1.]  [2. 2. 2.]]
[[1. 1. 1.]  [3. 3. 3.]]
```
property objects

Collection objects attribute getter and setter.

remove(obj)

Remove a specific object from the Collection.

Parameters

object (object object) – Remove the given object from the Collection.

Returns

self

Return type

Collection

Examples

Remove a specific object from a Collection:

```>>> import magpylib as magpy
>>> src1 = magpy.current.Loop(1,1)
>>> src2 = magpy.current.Loop(1,1)
>>> col = src1 + src2
>>> print(col.objects)
[Loop(id=2405009623360), Loop(id=2405010235504)]
>>> col.remove(src1)
>>> print(col.objects)
[Loop(id=2405010235504)]
```
reset_path()

Reset all object paths to position = (0,0,0) and orientation = unit rotation.

Returns

self

Return type

Collection

Examples

Create a collection with non-zero paths

```>>> import magpylib as magpy
>>> dipole = magpy.misc.Dipole((1,2,3), position=(1,2,3))
>>> loop = magpy.current.Loop(1,1, position=[(1,1,1)]*2)
>>> col = loop + dipole
>>> for src in col:
>>>     print(src.position)
[[1. 1. 1.]  [1. 1. 1.]]
[1. 2. 3.]
>>> col.reset_path()
>>> for src in col:
>>>     print(src.position)
[0. 0. 0.]
[0. 0. 0.]
```
rotate(rotation, anchor=None, start=- 1, increment=False)

Rotates object in the global coordinate system using a scipy Rotation object as input.

Parameters
• rotation (scipy Rotation object) – Rotation to be applied to existing object orientation. The scipy Rotation object can be of shape (3,) or (N,3).

• anchor (None, 0 or array_like, shape (3,), default=None) – The axis of rotation passes through the anchor point given in units of [mm]. By default (anchor=None) the object will rotate about its own center. anchor=0 rotates the object about the origin (0,0,0).

• start (int or str, default=-1) – Choose at which index of the original object path, the input path will begin. If start=-1, inp_path will overwrite the last old_path position. If start=0, inp_path will start with the beginning of the old_path. If start=len(old_path) or start=’append’, inp_path will be attached to the old_path.

• increment (bool, default=False) – If increment=False, input rotations are absolute. If increment=True, input rotations are interpreted as increments of each other.

Returns

self

Return type

Magpylib object

Examples

```>>> from scipy.spatial.transform import Rotation as R
>>> import magpylib as magpy
>>> s = magpy.Sensor(position=(1,0,0))
```

print initial position and orientation >>> print(s.position) >>> print(s.orientation.as_euler(‘xyz’, degrees=True)) [1. 0. 0.] [0. 0. 0.]

rotate and print resulting position and orientation >>> s.rotate(R.from_euler(‘z’, 45, degrees=True), anchor=0) >>> print(s.position) >>> print(s.orientation.as_euler(‘xyz’, degrees=True)) [0.70710678 0.70710678 0. ] [ 0. 0. 45.]

rotate_from_angax(angle, axis, anchor=None, start=- 1, increment=False, degrees=True)

Rotates object in the global coordinate system from angle-axis input.

Parameters
• angle (int/float or array_like with shape (n,) unit [deg] (by default)) – Angle of rotation, or a vector of n angles defining a rotation path in units of [deg] (by default).

• axis (str or array_like, shape (3,)) – The direction of the axis of rotation. Input can be a vector of shape (3,) or a string ‘x’, ‘y’ or ‘z’ to denote respective directions.

• anchor (None or array_like, shape (3,), default=None, unit [mm]) – The axis of rotation passes through the anchor point given in units of [mm]. By default (anchor=None) the object will rotate about its own center. anchor=0 rotates the object about the origin (0,0,0).

• start (int or str, default=-1) – Choose at which index of the original object path, the input path will begin. If start=-1, inp_path will overwrite the last old_path position. If start=0, inp_path will start with the beginning of the old_path. If start=len(old_path) or start=’append’, inp_path will be attached to the old_path.

• increment (bool, default=False) – If increment=False, input rotations are absolute. If increment=True, input rotations are interpreted as increments of each other.

• degrees (bool, default=True) – By default angle is given in units of [deg]. If degrees=False, angle is given in units of [rad].

Returns

self

Return type

Magpylib object

Examples

```>>> import magpylib as magpy
>>> s = magpy.Sensor(position=(1,0,0))
```

print initial position and orientation >>> print(s.position) >>> print(s.orientation.as_euler(‘xyz’, degrees=True)) [1. 0. 0.] [0. 0. 0.]

rotate and print resulting position and orientation >>> s.rotate_from_angax(45, (0,0,1), anchor=0) >>> print(s.position) >>> print(s.orientation.as_euler(‘xyz’, degrees=True)) [0.70710678 0.70710678 0. ] [ 0. 0. 45.]

rotate_from_euler(seq, angles, anchor=None, start=- 1, increment=False, degrees=False)

Rotates object in the global coordinate system from Euler angle input.

Parameters
• seq (string) – Specifies sequence of axes for rotations. Up to 3 characters belonging to the set {‘X’, ‘Y’, ‘Z’} for intrinsic rotations, or {‘x’, ‘y’, ‘z’} for extrinsic rotations. Extrinsic and intrinsic rotations cannot be mixed in one function call.

• angles (float or array_like, shape (N,) or (N, [1 or 2 or 3])) – Euler angles specified in radians (degrees is False) or degrees (degrees is True).

• anchor (None or array_like, shape (3,), default=None, unit [mm]) – The axis of rotation passes through the anchor point given in units of [mm]. By default (anchor=None) the object will rotate about its own center. anchor=0 rotates the object about the origin (0,0,0).

• start (int or str, default=-1) – Choose at which index of the original object path, the input path will begin. If start=-1, inp_path will overwrite the last old_path position. If start=0, inp_path will start with the beginning of the old_path. If start=len(old_path) or start=’append’, inp_path will be attached to the old_path.

• increment (bool, default=False) – If increment=False, input rotations are absolute. If increment=True, input rotations are interpreted as increments of each other.

• degrees (bool, default False) – If True, then the given angles are assumed to be in degrees.

Returns

self

Return type

Magpylib object

Examples

```>>> import magpylib as magpy
>>> s = magpy.Sensor(position=(1,0,0))
```

print initial position and orientation >>> print(s.position) >>> print(s.orientation.as_euler(‘xyz’, degrees=True)) [1. 0. 0.] [0. 0. 0.]

rotate and print resulting position and orientation >>> s.rotate_from_euler(‘z’, 45, anchor=0, degrees=True) >>> print(s.position) >>> print(s.orientation.as_euler(‘xyz’, degrees=True)) [0.70710678 0.70710678 0. ] [ 0. 0. 45.]

rotate_from_matrix(matrix, anchor=None, start=- 1, increment=False)

Rotates object in the global coordinate system from matrix input. (see scipy rotation package matrix input)

Parameters
• matrix (array_like, shape (N, 3, 3) or (3, 3)) – A single matrix or a stack of matrices, where matrix[i] is the i-th matrix.

• anchor (None or array_like, shape (3,), default=None, unit [mm]) – The axis of rotation passes through the anchor point given in units of [mm]. By default (anchor=None) the object will rotate about its own center. anchor=0 rotates the object about the origin (0,0,0).

• start (int or str, default=-1) – Choose at which index of the original object path, the input path will begin. If start=-1, inp_path will overwrite the last old_path position. If start=0, inp_path will start with the beginning of the old_path. If start=len(old_path) or start=’append’, inp_path will be attached to the old_path.

• increment (bool, default=False) – If increment=False, input rotations are absolute. If increment=True, input rotations are interpreted as increments of each other.

Returns

self

Return type

Magpylib object

Examples

```>>> import magpylib as magpy
>>> s = magpy.Sensor(position=(1,0,0))
```

print initial position and orientation >>> print(s.position) >>> print(s.orientation.as_matrix()) [1. 0. 0.] [[1. 0. 0.]

[0. 1. 0.] [0. 0. 1.]]

rotate and print resulting position and orientation >>> s.rotate_from_matrix([(0,-1,0),(1,0,0),(0,0,1)], anchor=0) >>> print(s.position) >>> print(s.orientation.as_matrix()) [0. 1. 0.] [[ 0. -1. 0.]

[ 1. 0. 0.] [ 0. 0. 1.]]

rotate_from_mrp(mrp, anchor=None, start=- 1, increment=False)

Rotates object in the global coordinate system from Modified Rodrigues Parameters input. (see scipy rotation package Modified Rodrigues Parameters (MRPs))

Parameters
• mrp (array_like, shape (N, 3) or (3,)) – A single vector or a stack of vectors, where mrp[i] gives the ith set of MRPs.

• anchor (None or array_like, shape (3,), default=None, unit [mm]) – The axis of rotation passes through the anchor point given in units of [mm]. By default (anchor=None) the object will rotate about its own center. anchor=0 rotates the object about the origin (0,0,0).

• start (int or str, default=-1) – Choose at which index of the original object path, the input path will begin. If start=-1, inp_path will overwrite the last old_path position. If start=0, inp_path will start with the beginning of the old_path. If start=len(old_path) or start=’append’, inp_path will be attached to the old_path.

• increment (bool, default=False) – If increment=False, input rotations are absolute. If increment=True, input rotations are interpreted as increments of each other.

Returns

self

Return type

Magpylib object

Examples

```>>> import magpylib as magpy
>>> s = magpy.Sensor(position=(1,0,0))
```

print initial position and orientation >>> print(s.position) >>> print(s.orientation.as_mrp()) [1. 0. 0.] [0. 0. 0.]

rotate and print resulting position and orientation >>> s.rotate_from_mrp((0,0,1), anchor=0) >>> print(s.position) >>> print(s.orientation.as_mrp()) [-1. 0. 0.] [0. 0. 1.]

rotate_from_quat(quat, anchor=None, start=- 1, increment=False)

Rotates object in the global coordinate system from Quaternion input.

Parameters
• quat (array_like, shape (N, 4) or (4,)) – Each row is a (possibly non-unit norm) quaternion in scalar-last (x, y, z, w) format. Each quaternion will be normalized to unit norm.

• anchor (None or array_like, shape (3,), default=None, unit [mm]) – The axis of rotation passes through the anchor point given in units of [mm]. By default (anchor=None) the object will rotate about its own center. anchor=0 rotates the object about the origin (0,0,0).

• start (int or str, default=-1) – Choose at which index of the original object path, the input path will begin. If start=-1, inp_path will overwrite the last old_path position. If start=0, inp_path will start with the beginning of the old_path. If start=len(old_path) or start=’append’, inp_path will be attached to the old_path.

• increment (bool, default=False) – If increment=False, input rotations are absolute. If increment=True, input rotations are interpreted as increments of each other.

Returns

self

Return type

Magpylib object

Examples

```>>> import magpylib as magpy
>>> s = magpy.Sensor(position=(1,0,0))
```

print initial position and orientation >>> print(s.position) >>> print(s.orientation.as_quat()) [1. 0. 0.] [0. 0. 0. 1.]

rotate and print resulting position and orientation >>> s.rotate_from_quat((0,0,1,1), anchor=0) >>> print(s.position) >>> print(s.orientation.as_quat()) [0. 1. 0.] [0. 0. 0.70710678 0.70710678]

rotate_from_rotvec(rotvec, anchor=None, start=- 1, increment=False, degrees=False)

Rotates object in the global coordinate system from rotation vector input. (vector direction is the rotation axis, vector length is the rotation angle in [rad])

Parameters
• rotvec (array_like, shape (N, 3) or (3,)) – A single vector or a stack of vectors, where rot_vec[i] gives the ith rotation vector.

• anchor (None or array_like, shape (3,), default=None, unit [mm]) – The axis of rotation passes through the anchor point given in units of [mm]. By default (anchor=None) the object will rotate about its own center. anchor=0 rotates the object about the origin (0,0,0).

• start (int or str, default=-1) – Choose at which index of the original object path, the input path will begin. If start=-1, inp_path will overwrite the last old_path position. If start=0, inp_path will start with the beginning of the old_path. If start=len(old_path) or start=’append’, inp_path will be attached to the old_path.

• increment (bool, default=False) – If increment=False, input rotations are absolute. If increment=True, input rotations are interpreted as increments of each other.

• degrees (bool, default False) – If True, then the given angles are assumed to be in degrees.

Returns

self

Return type

Magpylib object

Examples

```>>> import magpylib as magpy
>>> s = magpy.Sensor(position=(1,0,0))
```

print initial position and orientation >>> print(s.position) >>> print(s.orientation.as_rotvec()) [1. 0. 0.] [0. 0. 0.]

rotate and print resulting position and orientation >>> s.rotate_from_rotvec((0,0,1), anchor=0) >>> print(s.position) >>> print(s.orientation.as_rotvec()) [0.54030231 0.84147098 0. ] [0. 0. 1.]

property sensors

Collection sensors attribute getter and setter.

set_styles(arg=None, **kwargs)

Set display style of all objects in the Collection. Only matching properties will be applied. Input can be a style-dict or style-underscore_magic.

Returns

Return type

self

Examples

Apply a style to all objects inside a Collection using a style-dict or style-underscore_magic.

```>>> import magpylib as magpy
>>>
>>> # create collection
>>> col = magpy.Collection()
>>> for i in range(3):
>>>     col + magpy.magnet.Sphere((1,1,1), 1, (i,0,0))
>>>
>>> # separate object
>>> src = magpy.magnet.Sphere((1,1,1), 1, (3,0,0))
>>>
>>> # set collection style
>>> col.set_styles(color='g')
>>>
>>> # set collection style with style-dict
>>> style_dict = {'magnetization_size':0.5}
>>> col.set_styles(style_dict)
>>>
>>> magpy.display(col, src)
---> graphic output
```
property sources

Collection sources attribute getter and setter.

class magpylib.Sensor(position=(0, 0, 0), pixel=(0, 0, 0), orientation=None, style=None, **kwargs)

Bases: `magpylib._src.obj_classes.class_BaseGeo.BaseGeo`, `magpylib._src.obj_classes.class_BaseDisplayRepr.BaseDisplayRepr`

Magnetic field sensor. Can be used as observer input for magnetic field computation.

Local object coordinates: Sensor pixel (=sensing elements) are defined in the local object coordinate system. Local (Sensor) and global CS coincide when position=(0,0,0) and orientation=unit_rotation.

Parameters
• position (array_like, shape (3,) or (M,3), default=(0,0,0)) – Object position (local CS origin) in the global CS in units of [mm]. For M>1, the position represents a path. The position and orientation parameters must always be of the same length.

• pixel (array_like, shape (3,) or (N1,N2,...,3), default=(0,0,0)) – Sensor pixel positions (=sensing elements) in the local Sensor CS in units of [mm]. The magnetic field is evaluated at Sensor pixels.

• orientation (scipy Rotation object with length 1 or M, default=unit rotation) – Object orientation (local CS orientation) in the global CS. For M>1 orientation represents different values along a path. The position and orientation parameters must always be of the same length.

Returns

Sensor object

Return type

Sensor

Examples

By default a Sensor is initialized at position (0,0,0), with unit rotation and pixel (0,0,0):

```>>> import magpylib as magpy
>>> sensor = magpy.Sensor()
>>> print(sensor.position)
[0. 0. 0.]
>>> print(sensor.pixel)
[0. 0. 0.]
>>> print(sensor.orientation.as_quat())
[0. 0. 0. 1.]
```

Sensors are observers for magnetic field computation. In this example we compute the H-field as seen by the sensor in the center of a circular current loop:

```>>> import magpylib as magpy
>>> sensor = magpy.Sensor()
>>> loop = magpy.current.Loop(current=1, diameter=1)
>>> H = sensor.getH(loop)
>>> print(H)
[0. 0. 1.]
```

Field computation is performed at every pixel of a sensor. The above example is reproduced for a 2x2-pixel sensor:

```>>> import magpylib as magpy
>>> sensor = magpy.Sensor(pixel=[[(0,0,0), (0,0,1)],[(0,0,2), (0,0,3)]])
>>> loop = magpy.current.Loop(current=1, diameter=1)
>>> H = sensor.getH(loop)
>>> print(H.shape)
(2, 2, 3)
>>> print(H)
[[[0.         0.         1.        ]
[0.         0.         0.08944272]]
[[0.         0.         0.0142668 ]
[0.         0.         0.00444322]]]
```

Compute the field of a sensor along a path. The path positions are chosen so that they coincide with the pixel positions of the previous example:

```>>> import magpylib as magpy
>>> loop = magpy.current.Loop(current=1, diameter=1)
>>> sensor = magpy.Sensor()
>>> sensor.move([(0,0,1)]*3, start=1, increment=True)
>>> print(sensor.position)
[[0. 0. 0.]
[0. 0. 1.]
[0. 0. 2.]
[0. 0. 3.]]
>>> H = sensor.getH(loop)
>>> print(H)
[[0.         0.         1.        ]
[0.         0.         0.08944272]
[0.         0.         0.0142668 ]
[0.         0.         0.00444322]]
```
_get_style_class()

returns style class based on object type. If class has no attribute _object_type or is not found in MAGPYLIB_FAMILIES returns BaseStyle class.

_rotate(rotation, anchor=None, start=- 1, increment=False)

rotate_from_XXX generates a scipy Rotation object R then rotate() is called with R then _rotate() is called from rotate() to enable Collection application

Inputs: rotation: scipy rotation object anchor: anchor point start: int or ‘append’, path start position increment: bool, interpretation of path-input

Rotates the object in the global coordinate system by a given rotation input (can be a path).

display(*, path=True, zoom=0, animate_time=3, markers=None, backend=None, canvas=None, **kwargs)

Display objects and paths graphically. Style input can be a style-dict or style-underscore_magic.

Parameters
• objects (sources, collections or sensors) – Objects to be displayed.

• path (bool or int i or array_like shape (n,) or ‘animate’, default = True) – Option False shows objects at final path position and hides paths. Option True shows objects at final path position and shows object paths. Option int i displays the objects at every i’th path position. Option array_like shape (n,) discribes certain path indices. The objects displays are displayed at every given path index. Option ‘animate’ (Plotly backend only) shows an animation of objectes moving along their paths.

• zoom (float, default = 0) – Adjust plot zoom-level. When zoom=0 3D-figure boundaries are tight.

• animate_time (float, default = 3) – Sets the animation duration.

• markers (array_like, shape (N,3), default=None) – Display position markers in the global CS. By default no marker is displayed.

• backend (string, default=None) – One of ‘matplotlib’ or ‘plotly’. If not set, parameter will default to magpylib.defaults.display.backend which comes as ‘matplotlib’ with installation.

• canvas (pyplot Axis or plotly Figure, default=None) – Display graphical output in a given canvas: - with matplotlib: pyplot axis (must be 3D). - with plotly: plotly.graph_objects.Figure or plotly.graph_objects.FigureWidget By default a new canvas is created and displayed.

Returns

None

Return type

NoneType

Examples

Display multiple objects, object paths, markers in 3D using Matplotlib or Plotly:

```>>> import magpylib as magpy
>>> src = magpy.magnet.Sphere(magnetization=(0,0,1), diameter=1)
>>> src.move([(.1,0,0)]*50, increment=True)
>>> src.rotate_from_angax(angle=[10]*50, axis='z', anchor=0, start=0, increment=True)
>>> ts = [-.4,0,.4]
>>> sens = magpy.Sensor(position=(0,0,2), pixel=[(x,y,0) for x in ts for y in ts])
>>> magpy.display(src, sens)
>>> magpy.display(src, sens, backend='plotly')
--> graphic output
```

Display figure on your own canvas (here Matplotlib 3D axis):

```>>> import matplotlib.pyplot as plt
>>> import magpylib as magpy
>>> my_axis = plt.axes(projection='3d')
>>> magnet = magpy.magnet.Cuboid(magnetization=(1,1,1), dimension=(1,2,3))
>>> sens = magpy.Sensor(position=(0,0,3))
>>> magpy.display(magnet, sens, canvas=my_axis, zoom=1)
>>> plt.show()
--> graphic output
```

Use sophisticated figure styling options accessible from defaults, as individual object styles or as global style arguments in display.

```>>> import magpylib as magpy
>>> src1 = magpy.magnet.Sphere((1,1,1), 1)
>>> src2 = magpy.magnet.Sphere((1,1,1), 1, (1,0,0))
>>> magpy.defaults.display.style.magnet.magnetization.size = 2
>>> src1.style.magnetization.size = 1
>>> magpy.display(src1, src2, style_color='r', zoom=3)
--> graphic output
```
getB(*sources, sumup=False, squeeze=True)

Compute B-field in [mT] for given sources as seen by the Sensor.

Parameters
• sources (source objects or Collections) – Sources can be a mixture of L source objects or Collections.

• sumup (bool, default=False) – If True, the fields of all sources are summed up.

• squeeze (bool, default=True) – If True, the output is squeezed, i.e. all axes of length 1 in the output (e.g. only a single sensor or only a single source) are eliminated.

Returns

B-field – B-field of each source (L) at each path position (M) and each sensor pixel position (N1,N2,…) in units of [mT]. Paths of objects that are shorter than M will be considered as static beyond their end.

Return type

ndarray, shape squeeze(L, M, N1, N2, …, 3)

Examples

Sensors are observers for magnetic field computation. In this example we compute the B-field [mT] as seen by the sensor in the center of a circular current loop:

```>>> import magpylib as magpy
>>> sensor = magpy.Sensor()
>>> loop = magpy.current.Loop(current=1, diameter=1)
>>> B = sensor.getB(loop)
>>> print(B)
[0.         0.         1.25663706]
```

Field computation is performed at every pixel of a sensor. The above example is reproduced for a 2x2-pixel sensor:

```>>> import magpylib as magpy
>>> sensor = magpy.Sensor(pixel=[[(0,0,0), (0,0,1)],[(0,0,2), (0,0,3)]])
>>> loop = magpy.current.Loop(current=1, diameter=1)
>>> B = sensor.getB(loop)
>>> print(B.shape)
(2, 2, 3)
>>> print(B)
[[[0.         0.         1.25663706]
[0.         0.         0.11239704]]
[[0.         0.         0.01792819]
[0.         0.         0.00558351]]]
```

Compute the field of a sensor along a path. The path positions are chosen so that they coincide with the pixel positions in the previous example.

```>>> import magpylib as magpy
>>> loop = magpy.current.Loop(current=1, diameter=1)
>>> sensor = magpy.Sensor()
>>> sensor.move([(0,0,1)]*3, start=1, increment=True)
>>> print(sensor.position)
[[0. 0. 0.]
[0. 0. 1.]
[0. 0. 2.]
[0. 0. 3.]]
>>> B = sensor.getB(loop)
>>> print(B)
[[0.         0.         1.25663706]
[0.         0.         0.11239704]
[0.         0.         0.01792819]
[0.         0.         0.00558351]]
```
getH(*sources, sumup=False, squeeze=True)

Compute H-field in [kA/m] for given sources as seen by the Sensor.

Parameters
• sources (source objects or Collections) – Sources can be a mixture of L source objects or Collections.

• sumup (bool, default=False) – If True, the fields of all sources are summed up.

• squeeze (bool, default=True) – If True, the output is squeezed, i.e. all axes of length 1 in the output (e.g. only a single sensor or only a single source) are eliminated.

Returns

H-field – H-field of each source (L) at each path position (M) and each sensor pixel position (N1,N2,…) in units of [kA/m]. Paths of objects that are shorter than M will be considered as static beyond their end.

Return type

ndarray, shape squeeze(L, M, N1, N2, …, 3)

Examples

Sensors are observers for magnetic field computation. In this example we compute the H-field as seen by the sensor in the center of a circular current loop:

```>>> import magpylib as magpy
>>> sensor = magpy.Sensor()
>>> loop = magpy.current.Loop(current=1, diameter=1)
>>> H = sensor.getH(loop)
>>> print(H)
[0. 0. 1.]
```

Field computation is performed at every pixel of a sensor. The above example is reproduced for a 2x2-pixel sensor:

```>>> import magpylib as magpy
>>> sensor = magpy.Sensor(pixel=[[(0,0,0), (0,0,1)],[(0,0,2), (0,0,3)]])
>>> loop = magpy.current.Loop(current=1, diameter=1)
>>> H = sensor.getH(loop)
>>> print(H.shape)
(2, 2, 3)
>>> print(H)
[[[0.         0.         1.        ]
[0.         0.         0.08944272]]
[[0.         0.         0.0142668 ]
[0.         0.         0.00444322]]]
```

Compute the field of a sensor along a path. The path positions are chosen so that they coincide with the pixel positions in the previous example.

```>>> import magpylib as magpy
>>> loop = magpy.current.Loop(current=1, diameter=1)
>>> sensor = magpy.Sensor()
>>> sensor.move([(0,0,1)]*3, start=1, increment=True)
>>> print(sensor.position)
[[0. 0. 0.]
[0. 0. 1.]
[0. 0. 2.]
[0. 0. 3.]]
>>> H = sensor.getH(loop)
>>> print(H)
[[0.         0.         1.        ]
[0.         0.         0.08944272]
[0.         0.         0.0142668 ]
[0.         0.         0.00444322]]
```
move(displacement, start=- 1, increment=False)

Translates the object by the input displacement (can be a path).

This method uses vector addition to merge the input path given by displacement and the existing old path of an object. It keeps the old orientation. If the input path extends beyond the old path, the old path will be padded by its last entry before paths are added up.

Parameters
• displacement (array_like, shape (3,) or (N,3)) – Displacement vector shape=(3,) or path shape=(N,3) in units of [mm].

• start (int or str, default=-1) – Choose at which index of the original object path, the input path will begin. If start=-1, inp_path will start at the last old_path position. If start=0, inp_path will start with the beginning of the old_path. If start=len(old_path) or start=’append’, inp_path will be attached to the old_path.

• increment (bool, default=False) – If increment=False, input displacements are absolute. If increment=True, input displacements are interpreted as increments of each other. For example, an incremental input displacement of [(2,0,0), (2,0,0), (2,0,0)] corresponds to an absolute input displacement of [(2,0,0), (4,0,0), (6,0,0)].

Returns

self

Return type

Magpylib object

Examples

With the `move` method Magpylib objects can be repositioned in the global coordinate system:

```>>> import magpylib as magpy
>>> sensor = magpy.Sensor()
>>> print(sensor.position)
[0. 0. 0.]
>>> sensor.move((1,1,1))
>>> print(sensor.position)
[1. 1. 1.]
```

It is also a powerful tool for creating paths:

```>>> import magpylib as magpy
>>> sensor = magpy.Sensor()
>>> sensor.move((1,1,1), start='append')
>>> print(sensor.position)
[[0. 0. 0.]
[1. 1. 1.]]
>>> sensor.move([(.1,.1,.1)]*2, start='append')
>>> print(sensor.position)
[[0.  0.  0. ]
[1.  1.  1. ]
[1.1 1.1 1.1]
[1.1 1.1 1.1]]
```

Complex paths can be generated with ease, by making use of the `increment` keyword and superposition of subsequent paths:

```>>> import magpylib as magpy
>>> sensor = magpy.Sensor()
>>> sensor.move([(1,1,1)]*4, start='append', increment=True)
>>> print(sensor.position)
[[0. 0. 0.]
[1. 1. 1.]
[2. 2. 2.]
[3. 3. 3.]
[4. 4. 4.]]
>>> sensor.move([(.1,.1,.1)]*5, start=2)
>>> print(sensor.position)
[[0.  0.  0. ]
[1.  1.  1. ]
[2.1 2.1 2.1]
[3.1 3.1 3.1]
[4.1 4.1 4.1]
[4.1 4.1 4.1]
[4.1 4.1 4.1]]
```
property orientation

Object orientation attribute getter and setter.

property pixel

Sensor pixel attribute getter and setter.

property position

Object position attribute getter and setter.

reset_path()

Reset object path to position = (0,0,0) and orientation = unit rotation.

Returns

self

Return type

Magpylib object

Examples

Create an object with non-zero path

```>>> import magpylib as magpy
>>> obj = magpy.Sensor(position=(1,2,3))
>>> print(obj.position)
[1. 2. 3.]
>>> obj.reset_path()
>>> print(obj.position)
[0. 0. 0.]
```
rotate(rotation, anchor=None, start=- 1, increment=False)

Rotates object in the global coordinate system using a scipy Rotation object as input.

Parameters
• rotation (scipy Rotation object) – Rotation to be applied to existing object orientation. The scipy Rotation object can be of shape (3,) or (N,3).

• anchor (None, 0 or array_like, shape (3,), default=None) – The axis of rotation passes through the anchor point given in units of [mm]. By default (anchor=None) the object will rotate about its own center. anchor=0 rotates the object about the origin (0,0,0).

• start (int or str, default=-1) – Choose at which index of the original object path, the input path will begin. If start=-1, inp_path will overwrite the last old_path position. If start=0, inp_path will start with the beginning of the old_path. If start=len(old_path) or start=’append’, inp_path will be attached to the old_path.

• increment (bool, default=False) – If increment=False, input rotations are absolute. If increment=True, input rotations are interpreted as increments of each other.

Returns

self

Return type

Magpylib object

Examples

```>>> from scipy.spatial.transform import Rotation as R
>>> import magpylib as magpy
>>> s = magpy.Sensor(position=(1,0,0))
```

print initial position and orientation >>> print(s.position) >>> print(s.orientation.as_euler(‘xyz’, degrees=True)) [1. 0. 0.] [0. 0. 0.]

rotate and print resulting position and orientation >>> s.rotate(R.from_euler(‘z’, 45, degrees=True), anchor=0) >>> print(s.position) >>> print(s.orientation.as_euler(‘xyz’, degrees=True)) [0.70710678 0.70710678 0. ] [ 0. 0. 45.]

rotate_from_angax(angle, axis, anchor=None, start=- 1, increment=False, degrees=True)

Rotates object in the global coordinate system from angle-axis input.

Parameters
• angle (int/float or array_like with shape (n,) unit [deg] (by default)) – Angle of rotation, or a vector of n angles defining a rotation path in units of [deg] (by default).

• axis (str or array_like, shape (3,)) – The direction of the axis of rotation. Input can be a vector of shape (3,) or a string ‘x’, ‘y’ or ‘z’ to denote respective directions.

• anchor (None or array_like, shape (3,), default=None, unit [mm]) – The axis of rotation passes through the anchor point given in units of [mm]. By default (anchor=None) the object will rotate about its own center. anchor=0 rotates the object about the origin (0,0,0).

• start (int or str, default=-1) – Choose at which index of the original object path, the input path will begin. If start=-1, inp_path will overwrite the last old_path position. If start=0, inp_path will start with the beginning of the old_path. If start=len(old_path) or start=’append’, inp_path will be attached to the old_path.

• increment (bool, default=False) – If increment=False, input rotations are absolute. If increment=True, input rotations are interpreted as increments of each other.

• degrees (bool, default=True) – By default angle is given in units of [deg]. If degrees=False, angle is given in units of [rad].

Returns

self

Return type

Magpylib object

Examples

```>>> import magpylib as magpy
>>> s = magpy.Sensor(position=(1,0,0))
```

print initial position and orientation >>> print(s.position) >>> print(s.orientation.as_euler(‘xyz’, degrees=True)) [1. 0. 0.] [0. 0. 0.]

rotate and print resulting position and orientation >>> s.rotate_from_angax(45, (0,0,1), anchor=0) >>> print(s.position) >>> print(s.orientation.as_euler(‘xyz’, degrees=True)) [0.70710678 0.70710678 0. ] [ 0. 0. 45.]

rotate_from_euler(seq, angles, anchor=None, start=- 1, increment=False, degrees=False)

Rotates object in the global coordinate system from Euler angle input.

Parameters
• seq (string) – Specifies sequence of axes for rotations. Up to 3 characters belonging to the set {‘X’, ‘Y’, ‘Z’} for intrinsic rotations, or {‘x’, ‘y’, ‘z’} for extrinsic rotations. Extrinsic and intrinsic rotations cannot be mixed in one function call.

• angles (float or array_like, shape (N,) or (N, [1 or 2 or 3])) – Euler angles specified in radians (degrees is False) or degrees (degrees is True).

• anchor (None or array_like, shape (3,), default=None, unit [mm]) – The axis of rotation passes through the anchor point given in units of [mm]. By default (anchor=None) the object will rotate about its own center. anchor=0 rotates the object about the origin (0,0,0).

• start (int or str, default=-1) – Choose at which index of the original object path, the input path will begin. If start=-1, inp_path will overwrite the last old_path position. If start=0, inp_path will start with the beginning of the old_path. If start=len(old_path) or start=’append’, inp_path will be attached to the old_path.

• increment (bool, default=False) – If increment=False, input rotations are absolute. If increment=True, input rotations are interpreted as increments of each other.

• degrees (bool, default False) – If True, then the given angles are assumed to be in degrees.

Returns

self

Return type

Magpylib object

Examples

```>>> import magpylib as magpy
>>> s = magpy.Sensor(position=(1,0,0))
```

print initial position and orientation >>> print(s.position) >>> print(s.orientation.as_euler(‘xyz’, degrees=True)) [1. 0. 0.] [0. 0. 0.]

rotate and print resulting position and orientation >>> s.rotate_from_euler(‘z’, 45, anchor=0, degrees=True) >>> print(s.position) >>> print(s.orientation.as_euler(‘xyz’, degrees=True)) [0.70710678 0.70710678 0. ] [ 0. 0. 45.]

rotate_from_matrix(matrix, anchor=None, start=- 1, increment=False)

Rotates object in the global coordinate system from matrix input. (see scipy rotation package matrix input)

Parameters
• matrix (array_like, shape (N, 3, 3) or (3, 3)) – A single matrix or a stack of matrices, where matrix[i] is the i-th matrix.

• anchor (None or array_like, shape (3,), default=None, unit [mm]) – The axis of rotation passes through the anchor point given in units of [mm]. By default (anchor=None) the object will rotate about its own center. anchor=0 rotates the object about the origin (0,0,0).

• start (int or str, default=-1) – Choose at which index of the original object path, the input path will begin. If start=-1, inp_path will overwrite the last old_path position. If start=0, inp_path will start with the beginning of the old_path. If start=len(old_path) or start=’append’, inp_path will be attached to the old_path.

• increment (bool, default=False) – If increment=False, input rotations are absolute. If increment=True, input rotations are interpreted as increments of each other.

Returns

self

Return type

Magpylib object

Examples

```>>> import magpylib as magpy
>>> s = magpy.Sensor(position=(1,0,0))
```

print initial position and orientation >>> print(s.position) >>> print(s.orientation.as_matrix()) [1. 0. 0.] [[1. 0. 0.]

[0. 1. 0.] [0. 0. 1.]]

rotate and print resulting position and orientation >>> s.rotate_from_matrix([(0,-1,0),(1,0,0),(0,0,1)], anchor=0) >>> print(s.position) >>> print(s.orientation.as_matrix()) [0. 1. 0.] [[ 0. -1. 0.]

[ 1. 0. 0.] [ 0. 0. 1.]]

rotate_from_mrp(mrp, anchor=None, start=- 1, increment=False)

Rotates object in the global coordinate system from Modified Rodrigues Parameters input. (see scipy rotation package Modified Rodrigues Parameters (MRPs))

Parameters
• mrp (array_like, shape (N, 3) or (3,)) – A single vector or a stack of vectors, where mrp[i] gives the ith set of MRPs.

• anchor (None or array_like, shape (3,), default=None, unit [mm]) – The axis of rotation passes through the anchor point given in units of [mm]. By default (anchor=None) the object will rotate about its own center. anchor=0 rotates the object about the origin (0,0,0).

• start (int or str, default=-1) – Choose at which index of the original object path, the input path will begin. If start=-1, inp_path will overwrite the last old_path position. If start=0, inp_path will start with the beginning of the old_path. If start=len(old_path) or start=’append’, inp_path will be attached to the old_path.

• increment (bool, default=False) – If increment=False, input rotations are absolute. If increment=True, input rotations are interpreted as increments of each other.

Returns

self

Return type

Magpylib object

Examples

```>>> import magpylib as magpy
>>> s = magpy.Sensor(position=(1,0,0))
```

print initial position and orientation >>> print(s.position) >>> print(s.orientation.as_mrp()) [1. 0. 0.] [0. 0. 0.]

rotate and print resulting position and orientation >>> s.rotate_from_mrp((0,0,1), anchor=0) >>> print(s.position) >>> print(s.orientation.as_mrp()) [-1. 0. 0.] [0. 0. 1.]

rotate_from_quat(quat, anchor=None, start=- 1, increment=False)

Rotates object in the global coordinate system from Quaternion input.

Parameters
• quat (array_like, shape (N, 4) or (4,)) – Each row is a (possibly non-unit norm) quaternion in scalar-last (x, y, z, w) format. Each quaternion will be normalized to unit norm.

• anchor (None or array_like, shape (3,), default=None, unit [mm]) – The axis of rotation passes through the anchor point given in units of [mm]. By default (anchor=None) the object will rotate about its own center. anchor=0 rotates the object about the origin (0,0,0).

• start (int or str, default=-1) – Choose at which index of the original object path, the input path will begin. If start=-1, inp_path will overwrite the last old_path position. If start=0, inp_path will start with the beginning of the old_path. If start=len(old_path) or start=’append’, inp_path will be attached to the old_path.

• increment (bool, default=False) – If increment=False, input rotations are absolute. If increment=True, input rotations are interpreted as increments of each other.

Returns

self

Return type

Magpylib object

Examples

```>>> import magpylib as magpy
>>> s = magpy.Sensor(position=(1,0,0))
```

print initial position and orientation >>> print(s.position) >>> print(s.orientation.as_quat()) [1. 0. 0.] [0. 0. 0. 1.]

rotate and print resulting position and orientation >>> s.rotate_from_quat((0,0,1,1), anchor=0) >>> print(s.position) >>> print(s.orientation.as_quat()) [0. 1. 0.] [0. 0. 0.70710678 0.70710678]

rotate_from_rotvec(rotvec, anchor=None, start=- 1, increment=False, degrees=False)

Rotates object in the global coordinate system from rotation vector input. (vector direction is the rotation axis, vector length is the rotation angle in [rad])

Parameters
• rotvec (array_like, shape (N, 3) or (3,)) – A single vector or a stack of vectors, where rot_vec[i] gives the ith rotation vector.

• anchor (None or array_like, shape (3,), default=None, unit [mm]) – The axis of rotation passes through the anchor point given in units of [mm]. By default (anchor=None) the object will rotate about its own center. anchor=0 rotates the object about the origin (0,0,0).

• start (int or str, default=-1) – Choose at which index of the original object path, the input path will begin. If start=-1, inp_path will overwrite the last old_path position. If start=0, inp_path will start with the beginning of the old_path. If start=len(old_path) or start=’append’, inp_path will be attached to the old_path.

• increment (bool, default=False) – If increment=False, input rotations are absolute. If increment=True, input rotations are interpreted as increments of each other.

• degrees (bool, default False) – If True, then the given angles are assumed to be in degrees.

Returns

self

Return type

Magpylib object

Examples

```>>> import magpylib as magpy
>>> s = magpy.Sensor(position=(1,0,0))
```

print initial position and orientation >>> print(s.position) >>> print(s.orientation.as_rotvec()) [1. 0. 0.] [0. 0. 0.]

rotate and print resulting position and orientation >>> s.rotate_from_rotvec((0,0,1), anchor=0) >>> print(s.position) >>> print(s.orientation.as_rotvec()) [0.54030231 0.84147098 0. ] [0. 0. 1.]

property style

instance of MagpyStyle for display styling options

magpylib.display(*objects, path=True, zoom=0, animate_time=3, markers=None, backend=None, canvas=None, **kwargs)

Display objects and paths graphically. Style input can be a style-dict or style-underscore_magic.

Parameters
• objects (sources, collections or sensors) – Objects to be displayed.

• path (bool or int i or array_like shape (n,) or ‘animate’, default = True) – Option False shows objects at final path position and hides paths. Option True shows objects at final path position and shows object paths. Option int i displays the objects at every i’th path position. Option array_like shape (n,) discribes certain path indices. The objects displays are displayed at every given path index. Option ‘animate’ (Plotly backend only) shows an animation of objectes moving along their paths.

• zoom (float, default = 0) – Adjust plot zoom-level. When zoom=0 3D-figure boundaries are tight.

• animate_time (float, default = 3) – Sets the animation duration.

• markers (array_like, shape (N,3), default=None) – Display position markers in the global CS. By default no marker is displayed.

• backend (string, default=None) – One of ‘matplotlib’ or ‘plotly’. If not set, parameter will default to magpylib.defaults.display.backend which comes as ‘matplotlib’ with installation.

• canvas (pyplot Axis or plotly Figure, default=None) – Display graphical output in a given canvas: - with matplotlib: pyplot axis (must be 3D). - with plotly: plotly.graph_objects.Figure or plotly.graph_objects.FigureWidget By default a new canvas is created and displayed.

Returns

None

Return type

NoneType

Examples

Display multiple objects, object paths, markers in 3D using Matplotlib or Plotly:

```>>> import magpylib as magpy
>>> src = magpy.magnet.Sphere(magnetization=(0,0,1), diameter=1)
>>> src.move([(.1,0,0)]*50, increment=True)
>>> src.rotate_from_angax(angle=[10]*50, axis='z', anchor=0, start=0, increment=True)
>>> ts = [-.4,0,.4]
>>> sens = magpy.Sensor(position=(0,0,2), pixel=[(x,y,0) for x in ts for y in ts])
>>> magpy.display(src, sens)
>>> magpy.display(src, sens, backend='plotly')
--> graphic output
```

Display figure on your own canvas (here Matplotlib 3D axis):

```>>> import matplotlib.pyplot as plt
>>> import magpylib as magpy
>>> my_axis = plt.axes(projection='3d')
>>> magnet = magpy.magnet.Cuboid(magnetization=(1,1,1), dimension=(1,2,3))
>>> sens = magpy.Sensor(position=(0,0,3))
>>> magpy.display(magnet, sens, canvas=my_axis, zoom=1)
>>> plt.show()
--> graphic output
```

Use sophisticated figure styling options accessible from defaults, as individual object styles or as global style arguments in display.

```>>> import magpylib as magpy
>>> src1 = magpy.magnet.Sphere((1,1,1), 1)
>>> src2 = magpy.magnet.Sphere((1,1,1), 1, (1,0,0))
>>> magpy.defaults.display.style.magnet.magnetization.size = 2
>>> src1.style.magnetization.size = 1
>>> magpy.display(src1, src2, style_color='r', zoom=3)
--> graphic output
```
magpylib.getB(sources, observers, sumup=False, squeeze=True)

Compute B-field in [mT] for given sources and observers.

Parameters
• sources (source object, Collection or 1D list thereof) – Sources can be a single source object, a Collection or a 1D list of L source objects and/or collections.

• observers (array_like or Sensor or 1D list thereof) – Observers can be array_like positions of shape (N1, N2, …, 3) where the field should be evaluated, can be a Sensor object with pixel shape (N1, N2, …, 3) or a 1D list of K Sensor objects with similar pixel shape. All positions are given in units of [mm].

• sumup (bool, default=False) – If True, the fields of all sources are summed up.

• squeeze (bool, default=True) – If True, the output is squeezed, i.e. all axes of length 1 in the output (e.g. only a single sensor or only a single source) are eliminated.

Returns

B-field – B-field of each source (L) at each path position (M) for each sensor (K) and each sensor pixel position (N1,N2,…) in units of [mT]. Sensor pixel positions are equivalent to simple observer positions. Paths of objects that are shorter than M will be considered as static beyond their end.

Return type

ndarray, shape squeeze(L, M, K, N1, N2, …, 3)

Notes

This function automatically joins all sensor and position inputs together and groups similar sources for optimal vectorization of the computation. For maximal performance call this function as little as possible and avoid using it in loops.

Examples

Compute the B-field of a spherical magnet at a sensor positioned at (1,2,3):

```>>> import magpylib as magpy
>>> source = magpy.magnet.Sphere(magnetization=(1000,0,0), diameter=1)
>>> sensor = magpy.Sensor(position=(1,2,3))
>>> B = magpy.getB(source, sensor)
>>> print(B)
[-0.62497314  0.34089444  0.51134166]
```

Compute the B-field of a spherical magnet at five path positions as seen by an observer at position (1,2,3):

```>>> import magpylib as magpy
>>> source = magpy.magnet.Sphere(magnetization=(1000,0,0), diameter=1)
>>> source.move([(x,0,0) for x in [1,2,3,4,5]])
>>> B = magpy.getB(source, (1,2,3))
>>> print(B)
[[-0.88894262  0.          0.        ]
[-0.62497314 -0.34089444 -0.51134166]
[-0.17483825 -0.41961181 -0.62941771]
[ 0.09177028 -0.33037301 -0.49555952]
[ 0.17480239 -0.22080302 -0.33120453]]
```

Compute the B-field of two sources at two observer positions, with and without sumup:

```>>> import magpylib as magpy
>>> src1 = magpy.current.Loop(current=15, diameter=2)
>>> src2 = magpy.misc.Dipole(moment=(100,100,100))
>>> obs_pos = [(1,1,1), (1,2,3)]
>>> B = magpy.getB([src1,src2], obs_pos)
>>> print(B)
[[[0.93539608 0.93539608 0.40046672]
[0.05387784 0.10775569 0.0872515 ]]
[[3.06293831 3.06293831 3.06293831]
[0.04340403 0.23872216 0.43404028]]]
>>> B = magpy.getB([src1,src2], obs_pos, sumup=True)
>>> print(B)
[[3.99833439 3.99833439 3.46340502]
[0.09728187 0.34647784 0.52129178]]
```
magpylib.getB_dict(**kwargs)

B-Field computation in units of [mT] from a dictionary of input vectors of length N.

This function avoids the object-oriented Magpylib interface and gives direct access to the field implementations. It is the fastet way to compute fields with Magpylib.

“Static” inputs of shape (x,) will automatically be tiled to shape (N,x) to fit with other inputs.

Required inputs depend on chosen source_type!

Parameters
• source_type (string) – Source type for computation. Must be either ‘Cuboid’, ‘Cylinder’, ‘Cylinder_old’, ‘Sphere’, ‘Dipole’, ‘Loop’ or ‘Line’. Expected input parameters depend on source_type.

• position (array_like, shape (3,) or (N,3), default=(0,0,0)) – Source positions in units of [mm].

• orientation (scipy Rotation object, default=unit rotation) – Source rotations relative to the initial state (see object docstrings).

• observer (array_like, shape (3,) or (N,3)) – Observer positions in units of [mm].

• squeeze (bool, default=True) – If True, the output is squeezed, i.e. all axes of length 1 in the output are eliminated.

• magnetization (array_like, shape (3,) or (N,3)) – Only source_type in (‘Cuboid’, ‘Cylinder’, ‘Sphere’)! Magnetization vector (mu0*M) or remanence field of homogeneous magnet magnetization in units of [mT].

• moment (array_like, shape (3,) or (N,3)) – Only source_type = ‘Moment’! Magnetic dipole moment in units of [mT*mm^3]. For homogeneous magnets the relation is moment = magnetization*volume.

• current (array_like, shape (N,)) – Only source_type in (‘Line’, ‘Loop’)! Current flowing in loop in units of [A].

• dimension (array_like) – Only source_type in (‘Cuboid’, ‘Cylinder’, ‘CylinderSegment’)! Magnet dimension input in units of [mm]. Dimension format of sources similar as in object oriented interface.

• diameter (array_like, shape (N)) – Only source_type in (Sphere, Loop)! Diameter of source in units of [mm].

• segment_start (array_like, shape (N,3)) – Only source_type = ‘Line’! Start positions of line current segments in units of [mm].

• segment_end (array_like, shape (N,3)) – Only source_type = ‘Line’! End positions of line current segments in units of [mm].

Returns

B-field – B-field generated by sources at observer positions in units of [mT].

Return type

ndarray, shape (N,3)

Examples

Three-fold evaluation of the dipole field. For each computation the moment is (100,100,100).

```>>> import magpylib as magpy
>>> B = magpy.getB_dict(
>>>     source_type='Dipole',
>>>     position=[(1,2,3), (2,3,4), (3,4,5)],
>>>     moment=(100,100,100),
>>>     observer=[(1,1,1), (2,2,2), (3,3,3)])
>>> print(B)
[[-0.71176254  0.56941003  1.85058261]
[-0.71176254  0.56941003  1.85058261]
[-0.71176254  0.56941003  1.85058261]]
```

Six-fold evaluation of a Cuboid magnet field with increasing size and magnetization of the magnet. Position and orientation are by default (0,0,0) and unit-orientation, respectively. The observer position is (1,2,3) for each evaluation.

```>>> import numpy as np
>>> import magpylib as magpy
>>> B = magpy.getB_dict(
>>>     source_type='Cuboid',
>>>     magnetization = [(0,0,m) for m in np.linspace(500,1000,6)],
>>>     dimension = [(a,a,a) for a in np.linspace(1,2,6)],
>>>     observer=(1,2,3))
>>> print(B)
[[ 0.48818967  0.97689261  0.70605984]
[ 1.01203491  2.02636222  1.46575704]
[ 1.87397714  3.756164    2.72063422]
[ 3.19414311  6.41330652  4.65485356]
[ 5.10909461 10.2855981   7.4881383 ]
[ 7.76954697 15.70382556 11.48192812]]
```
magpylib.getH(sources, observers, sumup=False, squeeze=True)

Compute H-field in [kA/m] for given sources and observers.

Parameters
• sources (source object, Collection or 1D list thereof) – Sources can be a single source object, a Collection or a 1D list of L source objects and/or collections.

• observers (array_like or Sensor or 1D list thereof) – Observers can be array_like positions of shape (N1, N2, …, 3) where the field should be evaluated, can be a Sensor object with pixel shape (N1, N2, …, 3) or a 1D list of K Sensor objects with similar pixel shape. All positions are given in units of [mm].

• sumup (bool, default=False) – If True, the fields of all sources are summed up.

• squeeze (bool, default=True) – If True, the output is squeezed, i.e. all axes of length 1 in the output (e.g. only a single sensor or only a single source) are eliminated.

Returns

H-field – H-field of each source (L) at each path position (M) for each sensor (K) and each sensor pixel position (N1,N2,…) in units of [kA/m]. Sensor pixel positions are equivalent to simple observer positions. Paths of objects that are shorter than M will be considered as static beyond their end.

Return type

ndarray, shape squeeze(L, M, K, N1, N2, …, 3)

Notes

This function automatically joins all sensor and position inputs together and groups similar sources for optimal vectorization of the computation. For maximal performance call this function as little as possible and avoid using it in loops.

Examples

Compute the H-field of a spherical magnet at a sensor positioned at (1,2,3):

```>>> import magpylib as magpy
>>> source = magpy.magnet.Sphere(magnetization=(1000,0,0), diameter=1)
>>> sensor = magpy.Sensor(position=(1,2,3))
>>> H = magpy.getH(source, sensor)
>>> print(H)
[-0.49733782  0.27127518  0.40691277]
```

Compute the H-field of a spherical magnet at five path positions as seen by an observer at position (1,2,3):

```>>> import magpylib as magpy
>>> source = magpy.magnet.Sphere(magnetization=(1000,0,0), diameter=1)
>>> source.move([(x,0,0) for x in [1,2,3,4,5]])
>>> H = magpy.getH(source, (1,2,3))
>>> print(H)
[[-0.70739806  0.          0.        ]
[-0.49733782 -0.27127518 -0.40691277]
[-0.13913186 -0.33391647 -0.5008747 ]
[ 0.07302847 -0.26290249 -0.39435373]
[ 0.13910332 -0.17570946 -0.26356419]]
```

Compute the H-field of two sources at two observer positions, with and without sumup:

```>>> import magpylib as magpy
>>> src1 = magpy.current.Loop(current=15, diameter=2)
>>> src2 = magpy.misc.Dipole(moment=(100,100,100))
>>> obs_pos = [(1,1,1), (1,2,3)]
>>> H = magpy.getH([src1,src2], obs_pos)
>>> print(H)
[[[0.74436455 0.74436455 0.31868129]
[0.04287463 0.08574925 0.06943254]]
[[2.43740886 2.43740886 2.43740886]
[0.03453983 0.18996906 0.34539828]]]
>>> H = magpy.getH([src1,src2], obs_pos, sumup=True)
>>> print(H)
[[3.18177341 3.18177341 2.75609015]
[0.07741445 0.27571831 0.41483082]]
```
magpylib.getH_dict(**kwargs)

H-Field computation in units of [kA/m] from a dictionary of input vectors of length N.

This function avoids the object-oriented Magpylib interface and gives direct access to the field implementations. It is the fastet way to compute fields with Magpylib.

“Static” inputs of shape (x,) will automatically be tiled to shape (N,x) to fit with other inputs.

Required inputs depend on chosen source_type!

Parameters
• source_type (string) – Source type for computation. Must be either ‘Cuboid’, ‘Cylinder’,’Cylinder_old’, ‘Sphere’, ‘Dipole’, ‘Loop’ or ‘Line’. Expected input parameters depend on source_type.

• position (array_like, shape (3,) or (N,3), default=(0,0,0)) – Source positions in units of [mm].

• orientation (scipy Rotation object, default=unit rotation) – Source rotations relative to the initial state (see object docstrings).

• observer (array_like, shape (3,) or (N,3)) – Observer positions in units of [mm].

• squeeze (bool, default=True) – If True, the output is squeezed, i.e. all axes of length 1 in the output are eliminated.

• magnetization (array_like, shape (3,) or (N,3)) – Only source_type in (‘Cuboid’, ‘Cylinder’, ‘Sphere’)! Magnetization vector (mu0*M) or remanence field of homogeneous magnet magnetization in units of [mT].

• moment (array_like, shape (3,) or (N,3)) – Only source_type = ‘Moment’! Magnetic dipole moment in units of [mT*mm^3]. For homogeneous magnets the relation is moment = magnetization*volume.

• current (array_like, shape (N,)) – Only source_type in (‘Line’, ‘Loop’)! Current flowing in loop in units of [A].

• dimension (array_like) – Only source_type in (‘Cuboid’, ‘Cylinder’, ‘CylinderSegment’)! Magnet dimension input in units of [mm]. Dimension format of sources similar as in object oriented interface.

• diameter (array_like, shape (N)) – Only source_type in (Sphere, Loop)! Diameter of source in units of [mm].

• segment_start (array_like, shape (N,3)) – Only source_type = ‘Line’! Start positions of line current segments in units of [mm].

• segment_end (array_like, shape (N,3)) – Only source_type = ‘Line’! End positions of line current segments in units of [mm].

Returns

H-field – H-field generated by sources at observer positions in units of [kA/m].

Return type

ndarray, shape (N,3)

Examples

Three-fold evaluation of the dipole field. For each computation the moment is (100,100,100).

```>>> import magpylib as magpy
>>> H = magpy.getH_dict(
>>>     source_type='Dipole',
>>>     position=[(1,2,3), (2,3,4), (3,4,5)],
>>>     moment=(100,100,100),
>>>     observer=[(1,1,1), (2,2,2), (3,3,3)])
>>> print(H)
[[-0.56640264  0.45312211  1.47264685]
[-0.56640264  0.45312211  1.47264685]
[-0.56640264  0.45312211  1.47264685]]
```

Six-fold evaluation of a Cuboid magnet field with increasing size and magnetization of the magnet. Position and orientation are (0,0,0) and unit-orientation, respectively, by default. The observer position is (1,2,3) for each evaluation.

```>>> import numpy as np
>>> import magpylib as magpy
>>> H = magpy.getH_dict(
>>>     source_type='Cuboid',
>>>     magnetization = [(0,0,m) for m in np.linspace(500,1000,6)],
>>>     dimension = [(a,a,a) for a in np.linspace(1,2,6)],
>>>     observer=(1,2,3))
>>> print(H)
[[ 0.388489    0.77738644  0.56186457]
[ 0.80535179  1.61252782  1.16641239]
[ 1.49126363  2.98906034  2.16501192]
[ 2.54181833  5.10354717  3.70421476]
[ 4.06568831  8.1850189   5.95887113]
[ 6.18280903 12.49670731  9.13702808]]
```