# 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 docstrings are found in the Module Index.

## The idea behind Magpylib#

Magpylib provides fast and accurate magnetostatic field computation based on analytical solutions to permanent magnet and current problems. The fast field computation is coupled to a position and orientation API 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 3D graphic backends (Matplotlib, Plotly, Pyvista).

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:

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