You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Magnetic field computation is the central functionality of Magpylib. It evolves about the two functions
641
+
Magnetic field computation is the central functionality of Magpylib. It evolves about the two top-level functions
646
642
647
643
::::{grid}
648
-
:gutter: 2
644
+
:gutter: 4
649
645
650
646
:::{grid-item}
651
647
:columns: 1
@@ -668,7 +664,7 @@ Magnetic field computation is the central functionality of Magpylib. It evolves
668
664
:::{grid-item-card}
669
665
:shadow: none
670
666
:columns: 10
671
-
<spanstyle="color: orange">**getH(**</span>`sources`, `observers`, `squeeze=True`, `pixel_agg=None`, `output="ndarray"`<spanstyle="color: orange">**)**</span> computes the H-field seen by `observers` generated by `sources`.
@@ -677,225 +673,176 @@ Magnetic field computation is the central functionality of Magpylib. It evolves
677
673
678
674
::::
679
675
680
-
which compute the magnetic field seen by `observers` in their local coordinates generated by `sources`.
681
-
682
-
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.
683
-
684
-
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 array input and `3` the three magnetic field components $(B_x, B_y, B_z)$.
685
-
686
-
With `squeeze=True` the output is squeezed, i.e. all axes of length 1 in the output (e.g. only a single source) are eliminated.
687
-
688
-
With the argument `pixel_agg` a compatible numpy aggregator function like "min" or "mean" is applied to the observer output values. For example, with `pixel_agg="mean"` the mean field measured at all observer points is returned. Only with this option it is possible to supply `getB` and `getH` with observers that have different pixel shapes.
689
-
690
-
With `output` it is possible to choose the output format. Options are "ndarray" (returns a numpy array) and "dataframe" (returns a 2D-table pandas DataFrame).
676
+
which compute the magnetic field generated by `sources` as seen by the `observers` in their local coordinates. `sources` can be any Magpylib source object (e.g. Magnets) or a flat list thereof. `observers` can be an array of position vectors with shape `(n1,n2,n3,...,3)`, any Magpylib observer object (e.g. Sensors), or a flat list thereof.
691
677
678
+
::::{grid}
679
+
:gutter: 5
692
680
693
-
## Direct interface
681
+
:::{grid-item}
682
+
:columns: 2
683
+
:::
694
684
695
-
## Core
685
+
:::{grid-item}
686
+
:columns: 8
687
+
```python
688
+
import magpylib as magpy
696
689
697
-
T
698
-
<!--
699
-
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)$.
690
+
# define source and observer
691
+
loop = magpy.current.Loop(current=1, diameter=1)
692
+
sens = magpy.Sensor()
700
693
701
-
**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:
694
+
# compute field
695
+
B = magpy.getB(loop, sens)
702
696
703
-
```{code-cell} ipython3
704
-
import magpylib as magpy
705
-
loop = magpy.current.Loop(current=1, diameter=2)
706
-
B = magpy.getB(loop, (1,2,3))
707
697
print(B)
698
+
# --> [0. 0. 1.2566]
708
699
```
700
+
:::
701
+
::::
709
702
710
-
**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:
703
+
The output of a field computation `magpy.getB(sources, observers)` is by default a Numpy array 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 observers, `n1,n2,n3,...` the sensor pixel shape or the shape of the observer position array input and `3` the three magnetic field components $(B_x, B_y, B_z)$.
711
704
712
-
```{code-cell} ipython3
713
-
import numpy as np
714
-
import matplotlib.pyplot as plt
715
-
import magpylib as magpy
705
+
With `squeeze=True` all axes of length 1 in the output (e.g. only a single source) are eliminated.
With `pixel_agg` one can select a compatible numpy aggregator function (e.g. `"min"`, `"mean"`) that is applied to the output. For example, with `pixel_agg="mean"` the mean field of all observer points is returned. Only with this option it is possible to supply `getB` and `getH` with multiple observers that have different pixel shapes.
718
708
719
-
# create an observer grid in the xz-symmetry plane
720
-
ts = np.linspace(-3, 3, 30)
721
-
grid = np.array([[(x,0,z) for x in ts] for z in ts])
709
+
With `output` it is possible to choose the output format. Options are `"ndarray"` (returns a numpy array) and `"dataframe"` (returns a 2D-table pandas DataFrame).
722
710
723
-
# compute B- and H-fields of a cuboid magnet on the grid
Magpylib collects all inputs (object parameters), and vectorizes them for the computation which reduces the computation time dramatically for large inputs.
The tutorial {ref}`gallery-tutorial-field-computation` shows good practices with Magpylib field computation.
734
718
735
-
# outline magnet boundary
736
-
for ax in [ax1,ax2]:
737
-
ax.plot([1,1,-1,-1,1], [1,-1,-1,1,1], 'k--')
738
719
739
-
plt.tight_layout()
740
-
plt.show()
741
-
```
720
+
(docu-direct-interface)=
721
+
## Direct interface
742
722
743
-
**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:
723
+
Users can bypass the object oriented functionality of Magpylib and instead compute the field for n given parameter sets. This is achieved by providing the following inputs to the top level functions `getB` and `getH`,
744
724
745
-
```{code-cell} ipython3
746
-
import numpy as np
747
-
import plotly.graph_objects as go
748
-
import magpylib as magpy
725
+
1.`sources`: a string denoting the source type
726
+
2.`observers`: array_like of shape (3,) or (n,3) giving the observer positions
727
+
3.`kwargs`: a dictionary with inputs of shape (x,) or (n,x)
749
728
750
-
# reset defaults set in previous example
751
-
magpy.defaults.reset()
729
+
The allowed values for `sources` are similar to the Magpylib source class names, e.g. `"Cuboid"`, see {ref}`docu-classes`. The `kwargs` must include all mandatory class-specific inputs. All "scalar" inputs of shape (x,) are automatically tiled up to shape (n,x) to create a set of n computation instances. The field is returned in the shape (n,3).
The direct interface is potentially faster than the object oriented one if users know how to generate the input array efficiently with numpy (e.g. `np.arange`, `np.linspace`, `np.tile`, `np.repeat`, ...).
777
761
```
778
762
779
763
780
-
**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.
764
+
(docu-field-comp-core)=
765
+
## Core interface
781
766
782
-
```{code-cell} ipython3
783
-
import magpylib as magpy
767
+
At the heart of Magpylib lies a set of core functions that are our implementations of the explicit field expressions, see {ref}`docu-physics`, described in convenient local source coordinates. Direct access to these functions is given through the `magpylib.core` subpackage which includes,
The input `field` is either `"B"` or `"H`. All other inputs must be Numpy ndarrays of shape (n,x). Details can be found in the respective function docstrings.
802
802
803
+
::::{grid}
804
+
:gutter: 5
803
805
804
-
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.
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.
821
+
# compute field with core functions
822
+
B = magpy.core.magnet_cylinder_field('B', obs, mag, dim)
838
823
839
-
```{code-cell} ipython3
840
-
import plotly.express as px
841
-
fig = px.line(
842
-
B_as_df,
843
-
x="path",
844
-
y="Bx",
845
-
color="pixel",
846
-
line_group="source",
847
-
facet_col="source",
848
-
symbol="sensor",
849
-
)
850
-
fig.show()
824
+
print(B.round())
825
+
# --> [[553. 0. 0.]
826
+
# [553. 0. 0.]
827
+
# [553. 0. 0.]]
851
828
```
829
+
:::
830
+
::::
852
831
853
832
854
-
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.
855
-
856
-
(intro-direct-interface)=
857
-
858
-
## Direct interface and core
859
-
860
-
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
861
-
862
-
1. `sources`: a string denoting the source type
863
-
2. `observers`: array_like of shape (3,) or (n,3) giving the positions
864
-
3. `kwargs`: a dictionary with array_likes of shape (x,) or (n,x) for all other inputs
865
-
866
-
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.
867
-
868
-
In the following example we compute the cuboid field for 5 input instances, each with different position and orientation and similar magnetization:
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`, ...).
885
841
886
-
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.
887
842
888
-
```{code-cell} ipython3
889
-
import numpy as np
890
-
import magpylib as magpy
891
843
892
-
mag = np.array([(100,0,0)]*5)
893
-
dim = np.array([(1,2,3,45,90)]*5)
894
-
obs = np.array([(0,0,0)]*5)
895
844
896
-
B = magpy.core.magnet_cylinder_segment_field('B', obs, mag, dim)
Copy file name to clipboardexpand all lines: docs/_pages/docu/docu_physics.md
+1-3
Original file line number
Diff line number
Diff line change
@@ -17,12 +17,10 @@ TODO: explain remanence VS magnetization
17
17
18
18
(phys-remanence)=
19
19
20
-
(physcomp)=
21
-
22
20
# Physics and Computation
23
21
24
22
## When can you use Magpylib ?
25
-
The expressions used in Magpylib describe perfectly homogeneous magnets, surface charges, and line currents with natural boundary conditions. Magpylib is at its best when dealing with static air-coils (no eddy currents, no soft-magnetic cores) and high grade permanent magnets (Ferrite, NdFeB, SmCo or similar materials). When **magnet** permeabilities are below $\mu_r < 1.1$ the error typically undercuts few % (long magnet shapes are better, large distance from magnet is better). Demagnetization factors are not included. The line **current** solutions give the exact same field as outside of a wire that carries a homogeneous current. For more details check out the :ref:`physComp` section.
23
+
The expressions used in Magpylib describe perfectly homogeneous magnets, surface charges, and line currents with natural boundary conditions. Magpylib is at its best when dealing with static air-coils (no eddy currents, no soft-magnetic cores) and high grade permanent magnets (Ferrite, NdFeB, SmCo or similar materials). When **magnet** permeabilities are below $\mu_r < 1.1$ the error typically undercuts few % (long magnet shapes are better, large distance from magnet is better). Demagnetization factors are not included. The line **current** solutions give the exact same field as outside of a wire that carries a homogeneous current. For more details check out the :ref:`docu-physics` section.
**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:
20
+
21
+
```{code-cell} ipython3
22
+
import magpylib as magpy
23
+
loop = magpy.current.Loop(current=1, diameter=2)
24
+
B = magpy.getB(loop, (1,2,3))
25
+
print(B)
26
+
```
27
+
28
+
**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:
**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:
**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.
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.
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.
The expressions used in Magpylib describe perfectly homogeneous magnets, surface charges, and line currents with natural boundary conditions. Magpylib is at its best when dealing with static air-coils (no eddy currents, no soft-magnetic cores) and high grade permanent magnets (Ferrite, NdFeB, SmCo or similar materials). When **magnet** permeabilities are below $\mu_r < 1.1$ the error typically undercuts few % (long magnet shapes are better, large distance from magnet is better). Demagnetization factors are not included. The line **current** solutions give the exact same field as outside of a wire that carries a homogeneous current. For more details check out the :ref:`physComp` section.
170
+
The expressions used in Magpylib describe perfectly homogeneous magnets, surface charges, and line currents with natural boundary conditions. Magpylib is at its best when dealing with static air-coils (no eddy currents, no soft-magnetic cores) and high grade permanent magnets (Ferrite, NdFeB, SmCo or similar materials). When **magnet** permeabilities are below $\mu_r < 1.1$ the error typically undercuts few % (long magnet shapes are better, large distance from magnet is better). Demagnetization factors are not included. The line **current** solutions give the exact same field as outside of a wire that carries a homogeneous current. For more details check out the :ref:`docu-physics section.
0 commit comments