--- jupytext: text_representation: extension: .md format_name: myst format_version: 0.13 jupytext_version: 1.13.7 kernelspec: display_name: Python 3 (ipykernel) language: python name: python3 --- (intro)= # Introduction This section gives an introduction to the Magpylib API. More detailed information and practical examples how to use Magpylib can be found in the example galleries. The package documentation is found in the {ref}modindex. ## Contents - {ref}intro-idea - {ref}intro-when-to-use - {ref}intro-magpylib-objects - {ref}intro-position-and-orientation - {ref}intro-graphic-output - {ref}intro-field-computation - {ref}intro-direct-interface - {ref}intro-collections - {ref}intro-customization (intro-idea)= ## The idea behind Magpylib Magpylib provides fast and accurate magnetostatic field computation based on **analytical solutions** to permanent magnet and current problems. The field computation is coupled to a **position and orientation interface** that makes it easy to work with relative object positioning. The idea behind the main object oriented interface is: 1. Sensors, magnets, currents, etc. are created as Python objects with defined position and orientation in a global coordinate system. 2. After initialization, the Magpylib objects can easily be manipulated, grouped, moved around and displayed graphically using Matplotlib or Plotly 3D plotting. 3. When all objects are set up, the magnetic field generated by the source objects is computed at the observer objects. The following example code outlines this functionality: {code-cell} ipython3 import numpy as np import matplotlib.pyplot as plt import magpylib as magpy # 1. define sources and observers as objects cube = magpy.magnet.Cuboid(magnetization=(0,0,100), dimension=(1,1,1)) loop = magpy.current.Loop(current=5, diameter=3, position=(0,0,-3)) sensor = magpy.Sensor(position=(0,0,2), style_size=1.8) # 2. move objects and display graphically sensor.rotate_from_rotvec((0,0,225), degrees=True) cube.position = np.linspace((-3,0,0), (3,0,0), 50) loop.move(np.linspace((0,0,0), (0,0,6), 50), start=0) magpy.show(loop, cube, sensor, backend='plotly', animation=2, style_path_show=False) # 3. compute field at sensor (and plot with Matplotlib) B = sensor.getB(cube, loop, sumup=True) plt.plot(B, label=['Bx', 'By', 'Bz']) plt.legend() plt.grid(color='.8') plt.show()  For users who would like to avoid the object oriented interface, the field implementations can also be accessed directly, see {ref}intro-direct-interface. Details on how the analytical solutions are mathematically obtained can be found in the {ref}physComp section. (intro-when-to-use)= ## When can you use Magpylib ? The analytical solutions are exact when there is no material response and natural boundary conditions can be assumed. In general, Magpylib is at its best when dealing with air-coils (no eddy currents) and high grade permanent magnets (Ferrite, NdFeB, SmCo or similar materials). When **magnet** permeabilities are below $\mu_r < 1.1$ the error typically undercuts 1-5 % (long magnet shapes are better, large distance from magnet is better). Demagnetization factors are not automatically included at this point. The line **current** solutions give the exact same field as outside of a wire that carries a homogenous current. For more details check out the {ref}physComp section. Magpylib only provides solutions for simple geometric forms (cuboids, cylinders, lines, ...). How **complex shapes** can be constructed from these simple base shapes is described in {ref}examples-complex-forms. (intro-magpylib-objects)= ## The Magpylib objects The most convenient way of working with Magpylib is through the **object oriented interface**. Magpylib objects represent magnetic field sources, sensors and collections with various defining attributes and methods. By default all objects are initialized with position=(0,0,0) and orientation=None. The following classes are implemented: **Magnets** All magnet objects have the magnetization attribute which must be of the format $(m_x, m_y, m_z)$ and denotes the homogeneous magnetization vector in the local object coordinates in units of $mT$. It is often referred to as the remanence ($B_r=\mu_0 M$) in material data sheets. All magnets can be used as Magpylib sources input. - **Cuboid**(magnetization, dimension, position, orientation) represents a magnet with cuboid shape. dimension has the format $(a,b,c)$ and denotes the sides of the cuboid in units of $mm$. By default the center of the cuboid lies in the origin of the global coordinates, and the sides are parallel to the coordinate axes. - **Cylinder**(magnetization, dimension, position, orientation) represents a magnet with cylindrical shape. dimension has the format $(d,h)$ and denotes diameter and height of the cylinder in units of $mm$. By default the center of the cylinder lies in the origin of the global coordinates, and the cylinder axis coincides with the z-axis. - **CylinderSegment**(magnetization, dimension, position, orientation) represents a magnet with the shape of a cylindrical ring section. dimension has the format $(r_1,r_2,h,\varphi_1,\varphi_2)$ and denotes inner radius, outer radius and height in units of $mm$ and the two section angles $\varphi_1<\varphi_2$ in $deg$. By default the center of the full cylinder lies in the origin of the global coordinates, and the cylinder axis coincides with the z-axis. - **Sphere**(magnetization, diameter, position, orientation) represents a magnet of spherical shape. diameter is the sphere diameter $d$ in units of $mm$. By default the center of the sphere lies in the origin of the global coordinates. **Currents** All current objects have the current attribute which must be a scalar $i_0$ and denotes the electrical current in units of $A$. All currents can be used as Magpylib sources input. - **Loop**(current, diameter, position, orientation) represents a circular current loop where diameter is the loop diameter $d$ in units of $mm$. By default the loop lies in the xy-plane with it's center in the origin of the global coordinates. - **Line**(current, vertices, position, orientation) represents electrical current segments that flow in a straight line from vertex to vertex. By default the verticx positions coincide in the local object coordinates and the global coordinates. **Other** - **Dipole**(moment, position, orientation) represents a magnetic dipole moment with moment $(m_x,m_y,m_z)$ given in $mT mmÂ³]. For homogeneous magnets the relation moment=magnetization\timesvolume holds. Can be used as Magpylib sources input. - **CustomSource**(field_func, position, orientation) is used to create user defined custom sources with their own field functions. Can be used as Magpylib sources input. - **Sensor**(position, pixel, orientation) represents a 3D magnetic field sensor. The field is evaluated at the given pixel positions. By default (pixel=(0,0,0)) the pixel position coincide in the local object coordinates and the global coordinates. Can be used as Magpylib observers input. - **Collection**(*children, position, orientation) is a group of source and sensor objects (children) that is used for common manipulation. Depending on the children, a collection can be used as Magpylib sources and/or observers input. {code-cell} ipython3 import magpylib as magpy # magnets magnet1 = magpy.magnet.Cuboid() magnet2 = magpy.magnet.Cylinder() magnet3 = magpy.magnet.CylinderSegment() magnet4 = magpy.magnet.Sphere() # currents current1 = magpy.current.Loop() current2 = magpy.current.Line() # other dipole = magpy.misc.Dipole() custom = magpy.misc.CustomSource() sensor = magpy.Sensor() coll = magpy.Collection() # print object representation for obj in [magnet1, magnet2, magnet3, magnet4, current1, current2, dipole, custom, sensor, coll]: print(obj)  (intro-position-and-orientation)= ## Position and orientation All Magpylib objects have the position and orientation attributes that refer to position and orientation in the global Cartesian coordinate system. The position attribute is a numpy ndarray, shape (3,) or (m,3) and denotes the coordinates (x,y,z) in units of [mm]. By default every object is created at position=(0,0,0). The orientation attribute is a scipy [Rotation object](https://docs.scipy.org/doc/scipy/reference/generated/scipy.spatial.transform.Rotation.html) and denotes the object rotation relative to its initial state. By default the orientation of a Magpylib object is the unit rotation, orientation=None. python import magpylib as magpy sensor = magpy.Sensor() print(sensor.position) # out: [0. 0. 0.] print(sensor.orientation.as_euler('xyz', degrees=True)) # out: [0. 0. 0.]  Set absolute object position/orientation at initialization or through the properties directly. Add relative position/orientation with the move and rotate methods, python import magpylib as magpy from scipy.spatial.transform import Rotation as R # set at initialization sensor = magpy.Sensor(position=(1,1,1)) print(sensor.position) # out: [1. 1. 1.] print(sensor.orientation.as_euler('xyz', degrees=True)) # out: [0. 0. 0.] # set properties directly sensor.orientation = R.from_rotvec((0,0,45), degrees=True) print(sensor.position) # out: [1. 1. 1.] print(sensor.orientation.as_euler('xyz', degrees=True)) # out: [ 0. 0. 45.] # move and rotate sensor.move((1,2,3)) sensor.rotate_from_angax(45, 'z') print(sensor.position) # out: [2. 3. 4.] print(sensor.orientation.as_euler('xyz', degrees=True)) # out: [ 0. 0. 90.]  The attributes position and orientation can be either of **"scalar"** nature, i.e. a single position or a single rotation like in the examples above, or **"vectors"** when they are arrays of such scalars. The two attributes together define an object **"path"**. Paths should always be used when modelling object motion as the magnetic field is computed on the whole path with increased performance. With vector inputs, the move and rotate methods provide *append* and *merge* functionality. The following example shows how a path path1 is assigned to a magnet object, how path2 is appended with move and how path3 is merged on top starting at path index 25. {code-cell} ipython3 import numpy as np from magpylib.magnet import Cylinder magnet = Cylinder(magnetization=(100,0,0), dimension=(2,2)) # assign path path1 = np.linspace((0,0,0), (0,0,5), 20) magnet.position = path1 # append path path2 = np.linspace((0,0,0), (0,10,0), 40) magnet.move(path2[1:]) # merge path path3 = np.linspace(0, 360, 20) magnet.rotate_from_angax(angle=path3, axis='z', anchor=0, start=25) magnet.show(backend='plotly')  Notice that when one of the position and orientation attributes are modified in length, the other is automatically adjusted to the same length. A detailed outline of the functionality of position, orientation, move, rotate and paths is given in {ref}examples-paths. (intro-graphic-output)= ## Graphic output Once all Magpylib objects and their paths have been created, **show** provides a convenient way to graphically display the geometric arrangement using the Matplotlib (default) and Plotly packages. When show is called, it generates a new figure which is then automatically displayed. The desired graphic backend is selected with the backend keyword argument. To bring the output to a given, user-defined figure, the canvas kwarg is used. This is demonstrated in {ref}examples-backends-canvas. The following example shows the graphical representation of various Magpylib objects and their paths using the default Matplotlib graphic backend. {code-cell} ipython3 import numpy as np import magpylib as magpy from magpylib.magnet import Cuboid, Cylinder, CylinderSegment, Sphere from magpylib.current import Loop, Line from magpylib.misc import Dipole objects = [ Cuboid( magnetization=(0,100,0), dimension=(1,1,1), position=(-7,0,0), ), Cylinder( magnetization=(0,0,100), dimension=(1,1), position=(-5,0,0), ), CylinderSegment( magnetization=(0,0,100), dimension=(.3,1,1,0,140), position=(-3,0,0), ), Sphere( magnetization=(0,0,100), diameter=1, position=(-1,0,0), ), Loop( current=1, diameter=1, position=(1,0,0), ), Line( current=1, vertices=[(1,0,0), (0,1,0), (-1,0,0), (0,-1,0), (1,0,0)], position=(3,0,0), ), Dipole( moment=(0,0,100), position=(5,0,0), ), magpy.Sensor( pixel=[(0,0,z) for z in (-.5,0,.5)], position=(7,0,0), ), ] objects[5].move(np.linspace((0,0,0), (0,0,7), 20)) objects[0].rotate_from_angax(np.linspace(0, -90, 20), 'y', anchor=0) magpy.show(objects)  Notice that, objects and their paths are automatically assigned different colors, the magnetization vector, current directions and dipole objects are indicated by arrows and sensors are shown as tri-colored coordinate cross with pixel as markers. How objects are represented graphically (color, line thickness, ect.) is defined by the **style**. The default style, which can be seen above, is accessed and manipulated through magpy.defaults.display.style. In addition, each object can have an individual style, which takes precedence over the default setting. A local style override is also possible by passing style arguments directly to show. Some practical ways to set styles are shown in the next example: {code-cell} ipython3 import magpylib as magpy from magpylib.magnet import Cuboid cube1 = Cuboid(magnetization=(0,0,1), dimension=(2,4,4)) cube2 = cube1.copy(position=(3,0,0)) cube3 = cube1.copy(position=(6,0,0)) # change the default magpy.defaults.display.style.base.color = 'crimson' # set individual style through properties cube2.style.color = 'orangered' # set individual style using update with style dictionary cube3.style.update({'color': 'gold'}) # set individual style at initialization with underscore magic cube4 = cube1.copy(position=(9,0,0), style_color='linen') # show with local style override magpy.show(cube1, cube2, cube3, cube4, style_magnetization_show=False)  The hierarchy that decides about the final graphic object representation, a list of all style parameters and other options for tuning the show-output are described in {ref}examples-graphic-styles and {ref}examples-animation. (intro-field-computation)= ## Magnetic field computation Magnetic field computation in Magpylib is achieved through: - **getB**(sources, observers) computes the B-field seen by observers generated by sources in units of \[mT$ - **getH**(sources, observers) computes the H-field seen by observers generated by sources in units of $kA/m$ The argument sources can be any Magpylib **source object** or a flat list thereof. The argument observers can be an array_like of position vectors with shape $(n_1,n_2,n_3,...,3)$, any Magpylib **observer object** or a flat list thereof. getB and getH return the field for all combinations of sources, observers and paths. The output of a field computation getB(sources, observers) is a Numpy ndarray (alternatively a Pandas DataFrame, see below) of shape (l, m, k, n1, n2, n3, ..., 3) where l is the number of input sources, m the (maximal) object path length, k the number of sensors, n1,n2,n3,... the sensor pixel shape or the shape of the observer position vector input and 3 the three magnetic field components $(B_x, B_y, B_z)$. **Example 1:** As expressed by the old v2 slogan *"The magnetic field is only three lines of code away"*, this example demonstrates the most fundamental field computation: {code-cell} ipython3 import magpylib as magpy loop = magpy.current.Loop(current=1, diameter=2) B = magpy.getB(loop, (1,2,3)) print(B)  **Example 2:** When handed with multiple observer positions, getB and getH will return the field in the shape of the observer input. In the following example, B- and H-field of a cuboid magnet are computed on a position grid, and then displayed using Matplotlib: {code-cell} ipython3 import numpy as np import matplotlib.pyplot as plt import magpylib as magpy fig, [ax1,ax2] = plt.subplots(1, 2, figsize=(10,5)) # create an observer 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- and H-fields of a cuboid magnet on the grid cube = magpy.magnet.Cuboid(magnetization=(500,0,500), dimension=(2,2,2)) B = cube.getB(grid) H = cube.getH(grid) # display field with Pyplot ax1.streamplot(grid[:,:,0], grid[:,:,2], B[:,:,0], B[:,:,2], density=2, color=np.log(np.linalg.norm(B, axis=2)), linewidth=1, cmap='autumn') ax2.streamplot(grid[:,:,0], grid[:,:,2], H[:,:,0], H[:,:,2], density=2, color=np.log(np.linalg.norm(B, axis=2)), 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()  **Example 3:** The following example code shows how the field in a position system is computed with a sensor object. Both, magnet and sensor are moving. The 3D system and the field along the path are displayed with Plotly: {code-cell} ipython3 import numpy as np import plotly.graph_objects as go import magpylib as magpy # reset defaults set in previous example magpy.defaults.reset() # setup plotly figure and subplots fig = go.Figure().set_subplots(rows=1, cols=2, specs=[[{"type": "scene"}, {"type": "xy"}]]) # define sensor and source sensor = magpy.Sensor(pixel=[(0,0,-.2), (0,0,.2)], style_size=1.5) magnet = magpy.magnet.Cylinder(magnetization=(100,0,0), dimension=(1,2)) # define paths sensor.position = np.linspace((0,0,-3), (0,0,3), 40) magnet.position = (4,0,0) magnet.rotate_from_angax(angle=np.linspace(0, 300, 40)[1:], axis='z', anchor=0) # display system in 3D temp_fig = go.Figure() magpy.show(magnet, sensor, canvas=temp_fig, backend='plotly') fig.add_traces(temp_fig.data, rows=1, cols=1) # compute field and plot B = magpy.getB(magnet, sensor) for i,plab in enumerate(['pixel1', 'pixel2']): for j,lab in enumerate(['_Bx', '_By', '_Bz']): fig.add_trace(go.Scatter(x=np.arange(40), y=B[:,i,j], name=plab+lab)) fig.show()  **Example 4:** The last example demonstrates the most general form of a getB computation with multiple source and sensor inputs. Specifically, 3 sources, one with path length 11, and two sensors, each with pixel shape (4,5). Note that, when input objects have different path lengths, objects with shorter paths are treated as static beyond their path end. {code-cell} ipython3 import magpylib as magpy # 3 sources, one with length 11 path pos_path = [(i,0,1) for i in range(-1,1)] source1 = magpy.misc.Dipole(moment=(0,0,100), position=pos_path) source2 = magpy.current.Loop(current=10, diameter=3) source3 = source1 + source2 # 2 observers, each with 4x5 pixel pixel = [[[(i,j,0)] for i in range(4)] for j in range(5)] sensor1 = magpy.Sensor(pixel=pixel, position=(-1,0,-1)) sensor2 = sensor1.copy().move((2,0,0)) sources = [source1, source2, source3] sensors = [sensor1, sensor2] # compute field B = magpy.getB(sources, sensors) print(B.shape)  Instead of a Numpy ndarray, the field computation can also return a [pandas](https://pandas.pydata.org/).[dataframe](https://pandas.pydata.org/docs/user_guide/dsintro.html#dataframe) using the output='dataframe' kwarg. {code-cell} ipython3 import numpy as np import magpylib as magpy cube = magpy.magnet.Cuboid( magnetization=(0, 0, 1000), dimension=(1, 1, 1), style_label='cube' ) loop = magpy.current.Loop( current=200, diameter=2, style_label='loop', ) sens1 = magpy.Sensor( pixel=[(0,0,0), (.5,0,0)], position=np.linspace((-4, 0, 2), (4, 0, 2), 30), style_label='sens1' ) sens2 = sens1.copy(style_label='sens2').move((0,0,1)) B_as_df = magpy.getB( [cube, loop], [sens1, sens2], output='dataframe', ) B_as_df  Plotting libraries such as [plotly](https://plotly.com/python/plotly-express/) or [seaborn](https://seaborn.pydata.org/introduction.html) can take advantage of this feature, as they can deal with dataframes directly. {code-cell} ipython3 import plotly.express as px fig = px.line( B_as_df, x="path", y="Bx", color="pixel", line_group="source", facet_col="source", symbol="sensor", ) fig.show()  In terms of **performance** it must be noted that Magpylib automatically vectorizes all computations when getB and getH are called. This reduces the computation time dramatically for large inputs. For maximal performance try to make all field computations with as few calls to getB and getH as possible. (intro-direct-interface)= ## Direct interface and core The **direct interface** allows users to bypass the object oriented functionality of Magpylib. The magnetic field is computed for a set of $n$ arbitrary input instances by providing the top level functions getB and getH with 1. sources: a string denoting the source type 2. observers: array_like of shape (3,) or (n,3) giving the positions 3. kwargs: a dictionary with array_likes of shape (x,) or (n,x) for all other inputs All "scalar" inputs of shape (x,) are automatically tiled up to shape (n,x), and for every of the $n$ given instances the field is computed and returned with shape (n,3). The allowed source types are similar to the Magpylib source class names (see {ref}intro-magpylib-objects), and the required dictionary inputs are the respective class inputs. In the following example we compute the cuboid field for 5 input instances, each with different position and orientation and similar magnetization: {code-cell} ipython3 import magpylib as magpy B = magpy.getB( sources='Cuboid', observers=[(0,0,x) for x in range(5)], dimension=[(d,d,d) for d in range(1,6)], magnetization=(0,0,1000), ) print(B)  The direct interface is convenient for users who work with complex inputs or favor a more functional programming paradigm. It is typically faster than the object oriented interface, but it also requires that users know how to generate the inputs efficiently with numpy (e.g. np.arange, np.linspace, np.tile, np.repeat, ...). At the heart of Magpylib lies a set of **core functions** that are our implementations of the analytical field expressions, see {ref}physcomp. For users who are not interested in the position/orientation interface, the magpylib.core subpackage gives direct access to these functions. Inputs are ndarrays of shape (n,x). Details can be found in the respective function docstrings. {code-cell} ipython3 import numpy as np import magpylib as magpy mag = np.array([(100,0,0)]*5) dim = np.array([(1,2,3,45,90)]*5) obs = np.array([(0,0,0)]*5) B = magpy.core.magnet_cylinder_segment_field('B', obs, mag, dim) print(B)  (intro-collections)= ## Collections The top level class Collection allows users to group objects by reference for common manipulation. Objects that are part of a collection become **children** of that collection, and the collection itself becomes their **parent**. An object can only have a single parent. The child-parent relation is demonstrated with the describe method in the following example: {code-cell} ipython3 import magpylib as magpy sens = magpy.Sensor(style_label='sens') loop = magpy.current.Loop(style_label='loop') line = magpy.current.Line(style_label='line') cube = magpy.magnet.Cuboid(style_label='cube') coll1 = magpy.Collection(sens, loop, line, style_label='coll1') coll2 = cube + coll1 coll2.describe(format='type,label')  A detailed review of collection properties and construction is provided in the example gallery {ref}examples-collections-construction. It is specifically noteworthy in the above example, that any two Magpylib objects can simply be added up to form a collection. A collection object has its own position and orientation attributes and spans a local reference frame for all its children. An operation applied to a collection moves the frame, and is individually applied to all children such that their relative position in the local reference frame is maintained. This means that the collection functions only as a container for manipulation, but child position and orientation are always updated in the global coordinate system. After being added to a collection, it is still possible to manipulate the individual children, which will also move them to a new relative position in the collection frame. This enables user-friendly manipulation of groups, sub-groups and individual objects, which is demonstrated in the following example: {code-cell} ipython3 import numpy as np import magpylib as magpy from magpylib.current import Loop # construct two coil collections from windings coil1 = magpy.Collection(style_label='coil1') for z in np.linspace(-.5, .5, 5): coil1.add(Loop(current=1, diameter=20, position=(0,0,z))) coil1.position = (0,0,-5) coil2 = coil1.copy(position=(0,0,5)) # helmholtz consists of two coils helmholtz = coil1 + coil2 # move the helmholz helmholtz.position = np.linspace((0,0,0), (10,0,0), 30) helmholtz.rotate_from_angax(np.linspace(0,180,30), 'x', start=0) # move the coils coil1.move(np.linspace((0,0,0), ( 5,0,0), 30)) coil2.move(np.linspace((0,0,0), (-5,0,0), 30)) # move the windings for coil in [coil1, coil2]: for i,wind in enumerate(coil): wind.move(np.linspace((0,0,0), (0,0,2-i), 20)) magpy.show(*helmholtz, backend='plotly', animation=4, style_path_show=False)  Notice, that collections have their own style attributes, their paths are displayed in show, and all children are automatically assigned their parent color. For magnetic field computation a collection with source children behaves like a single source object, and a collection with sensor children behaves like a flat list of it's sensors when provided as sources and observers input respectively. This is demonstrated in the following continuation of the previous helmholtz example: {code-cell} ipython3 import matplotlib.pyplot as plt B = helmholtz.getB((10,0,0)) plt.plot(B, label=['Bx', 'By', 'Bz']) plt.gca().set( title='B-field [mT] at position (10,0,0)', xlabel='helmholtz path position index' ) plt.gca().grid(color='.9') plt.gca().legend() plt.show()  One central motivation behind the Collection class is enabling users to build **compound objects**, which refer to custom classes that inherit Collection. They can represent complex magnet structures like magnetic encoders, motor parts, halbach arrays, and other arrangments, and will naturally integrate into the Magpylib interface. An advanced tutorial how to sub-class Collection with dynamic properties and custom 3D models is given in {ref}examples-compounds. (intro-customization)= ## Customization **User-defined 3D models** (traces) for any object that will be displayed by show, can be stored in style.model3d.data. A trace itself is a dictionary that contains all information necessary for plotting, and can be added with the method style.model3d.data.add_trace. In the example gallery {ref}examples-3d-models it is explained how to create custom traces with standard plotting backends such as scatter3d or mesh3d in Plotly, or plot, plot_surface and plot_trisurf in Matplotlib. Some pre-defined models are also provided for easy parts visualization. **User-defined source objects** are easily realized with the CustomSource class. Such a custom source object is provided with a user-defined field computation function, that is stored in the attribute field_func and is used when getB and getH are called. Similar to core functions, field_func must have the two positional arguments field (can be 'B' or 'H') and observers (must accept ndarrays of shape (n,3)), and return the respective fields in units of $mT$ and $kA/m$ in the same shape. Details on working with custom sources are given in {ref}examples-custom-source-objects. While each of these features can be used individually, the combination of the two (own source class with own 3D representation) enables a high level of customization in Magpylib. Such user-defined objects will feel like native Magpylib objects and can be used in combination with all other features, which is demonstrated in the following example: {code-cell} ipython3 import numpy as np import plotly.graph_objects as go import magpylib as magpy # define B/H field function for custom source def easter_field(field, observers): """ points in z-direction and decays with 1/r^3""" dist = np.linalg.norm(observers, axis=1) return np.c_[np.zeros((len(observers),2)), 1/dist**3] # create custom source egg = magpy.misc.CustomSource( field_func=easter_field, style=dict(color='orange', model3d_showdefault=False, label='The Egg'), ) # add a custom 3D model trace = magpy.graphics.model3d.make_Ellipsoid( backend='plotly', dimension=(1,1,1.4), ) egg.style.model3d.add_trace(trace) # move the egg ts = np.linspace(-2*np.pi, 2*np.pi, 70) ts = ts + 0.75*np.sin(ts-np.pi/8)**2 egg.position = [(t/3, 0, -0.2*np.sin(t)**2) for t in ts] egg.rotate_from_euler(ts, 'y', start=0, degrees=False) # add sensor and compute field on path sensor = magpy.Sensor(position=(0,0,1.5), style_size=2) B = sensor.getB(egg) # animate path and plot field magpy.show(egg, sensor, backend='plotly', animation=True, style_path_show=False) fig = go.Figure() for i,lab in enumerate(['Bx', 'By', 'Bz']): fig.add_trace(go.Scatter(x=ts/2*3, y=B[:,i], name=lab)) fig.update_layout(title='Field at sensor', xaxis_title='animation time [s]') fig.show()