Finalizing documentation (magpylib#737)

Author: OrtnerMichael

CHANGELOG.md

@@ -3,10 +3,17 @@ All notable changes to magpylib are documented here.
 
 # Changelog
 
-## [5.0.0dev]
-- The Magpylib inputs and outputs are now in **SI Units**. The `magnetization` term has also been redefined and is now codependent with the `polarization` term ([#712](https://github.com/magpylib/magpylib/issues/712))
-- Added `getM` (magnetization) and `getJ` (polarization) top level functions. Also an `in_out` (inside/ouside) parameter is added to specify the location of the observers relative to the magnet body in order to increase performance ([#717](https://github.com/magpylib/magpylib/issues/717))
--
+## [5.0.0] - Bald
+### ⚠️ Breaking Changes ⚠️
+- ⚠️The Magpylib inputs and outputs are now in **SI Units**.
+- ⚠️The `magnetization` parameter has also been redefined to reflect the true physical magnetization quantity in units of A/m.
+### Other Improvements
+- The `magnetization` parameter is now codependent with the new `polarization` parameter that is the physical magnetic polarization ([#712](https://github.com/magpylib/magpylib/issues/712)) in units of Tesla.
+- Added `getM` (magnetization) and `getJ` (polarization) top level functions and class methods reminiscent of `getB` and `getH`.
+- The `in_out` (inside/ouside) parameter is added to all field functions (`getBHJM`) to specify the location of the observers relative to the magnet body in order to increase performance ([#717](https://github.com/magpylib/magpylib/issues/717), [#608](https://github.com/magpylib/magpylib/issues/608))
+- Review of documentation and adding a few requested things ([#685](https://github.com/magpylib/magpylib/issues/685), some of [#659](https://github.com/magpylib/magpylib/issues/659))
+- Added mu0 at top level as `magpylib.mu_0`. The value of mu0 is taken from scipy and follows the 2019 redefinition. All internal computations now include this new value. ([#714](https://github.com/magpylib/magpylib/issues/714), [#731](https://github.com/magpylib/magpylib/issues/731))
+- The core level now includes only the true bottom level implementations. ([#727](https://github.com/magpylib/magpylib/issues/727))
 
 ## [4.5.1] - 2023-12-28
 - Fixed a field computation issue where H-field resulting from axial magnetization is computed incorrectly inside of Cylinders ([#703](https://github.com/magpylib/magpylib/issues/703))

docs/_pages/docu/docu_graphics.md

@@ -600,6 +600,8 @@ Even with some implemented failsafes, such as a maximum frame rate and frame cou
 
 +++
 
+(docu-graphics-subplots)=
+
 ## Subplots
 
 :::{versionadded} 4.4

docs/_pages/docu/docu_magpylib_api.md

@@ -15,7 +15,7 @@ Magpylib requires no special input format. All scalar types (`int`, `float`, ...
 (docu-units)=
 ## Units
 
-The important quantity <span style="color: orange">**mu_0**</span> lies at the top level. It's value is not $4 \pi 10^{-7}$ since [the redefinition of the SI base units](https://en.wikipedia.org/wiki/2019_redefinition_of_the_SI_base_units), but a value close to it.
+The important vacuum permeability $\mu_0$ is provided at the package top-level <span style="color: orange">**mu_0**</span>. It's value is not $4 \pi 10^{-7}$ since [the redefinition of the SI base units](https://en.wikipedia.org/wiki/2019_redefinition_of_the_SI_base_units), but a value close to it.
 
 For historical reasons Magpylib used non-SI units until Version 4. Starting with version 5 all inputs and outputs are SI-based.
 
@@ -51,7 +51,7 @@ In addition, `getB` returns the same unit as given by the `polarization` input.
 ```
 
 ```{note}
-The connection between the magnetic polarization J, the magnetization M and the material parameters of a real permanent magnet are shown in {ref}`gallery-tutorial-magnetmodel`.
+The connection between the magnetic polarization J, the magnetization M and the material parameters of a real permanent magnet are shown in {ref}`gallery-tutorial-modelling-magnets`.
 ```
 
 <!-- ################################################################## -->
@@ -125,7 +125,7 @@ Magpylib objects span a local reference frame, and all object properties are def
 (docu-magnet-classes)=
 ## Magnet classes
 
-All magnets are sources. They have the <span style="color: orange">**polarization**</span> attribute which is of the format $\vec{J}=(J_x, J_y, J_z)$ and denotes a homogeneous magnetic polarization vector in the local object coordinates in units of T. Alternatively, the magnetization vector can be set via the  <span style="color: orange">**magnetization**</span> attribute of the format $\vec{M}=(M_x, M_y, M_z)$. These two parameters are codependent and Magpylib ensures that they stay in sync via the relatoin $\vec{J}=\mu_0\cdot\vec{M}$. Information on how this is related to material properties from data sheets is found in {ref}`gallery-tutorial-magnetmodel`.
+All magnets are sources. They have the <span style="color: orange">**polarization**</span> attribute which is of the format $\vec{J}=(J_x, J_y, J_z)$ and denotes a homogeneous magnetic polarization vector in the local object coordinates in units of T. Alternatively, the magnetization vector can be set via the  <span style="color: orange">**magnetization**</span> attribute of the format $\vec{M}=(M_x, M_y, M_z)$. These two parameters are codependent and Magpylib ensures that they stay in sync via the relatoin $\vec{J}=\mu_0\cdot\vec{M}$. Information on how this is related to material properties from data sheets is found in {ref}`gallery-tutorial-modelling-magnets`.
 
 
 ### Cuboid
@@ -612,27 +612,19 @@ The tutorial {ref}`gallery-tutorial-paths` shows intuitive good practice example
 
 <hr style="border:3px solid gray">
 
-Magnetic field computation in Magpylib is done via four top-level functions <span style="color: orange">**getB**</span>, <span style="color: orange">**getH**</span>, <span style="color: orange">**getJ**</span> and, <span style="color: orange">**getM**</span>.
+Magnetic field computation in Magpylib is done via four top-level functions <span style="color: orange">**getB**</span>, <span style="color: orange">**getH**</span>, <span style="color: orange">**getJ**</span> and, <span style="color: orange">**getM**</span>,
 
 
 ```python
 magpylib.getB(sources, observers, squeeze=True, pixel_agg=None, output="ndarray")
-```
-
-```python
 magpylib.getH(sources, observers, squeeze=True, pixel_agg=None, output="ndarray")
-```
-
-```python
 magpylib.getJ(sources, observers, squeeze=True, pixel_agg=None, output="ndarray")
-```
-
-```python
 magpylib.getM(sources, observers, squeeze=True, pixel_agg=None, output="ndarray")
 ```
 
-that compute the respective 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. The following code shows a minimal example for Magplyib field computation.
+that compute the respective 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. For quick-access, the functions `getBHJM` are also methods of all Magylib objects, such that the `sources` or `observers` input is the object itself.
 
+The following code shows a minimal example for Magplyib field computation.
 
 ```python
 import magpylib as magpy
@@ -649,7 +641,7 @@ print(B)
 #  --> [0.         0.         0.00125664]
 ```
 
-By default, `getB` returns the B-field in units of T, `getH` the H-field in units of A/m, `getJ` the magnetic polarization in T and, `getM` the magnetization in A/m, assuming that all inputs are given in SI units.
+By default, `getB` returns the B-field in units of T, `getH` the H-field in units of A/m, `getJ` the magnetic polarization in T and, `getM` the magnetization in A/m, assuming that all inputs are given in SI units as described in the docstings.
 
 ```{note}
 In reality, `getB` returns the same unit as given by the `polarization` input. For example, with polarization input in mT, getB will return mT as well. At the same time when the `magnetization` input is kA/m, then `getH` returns kA/m as well. The B/H-field outputs are related to a M/J-inputs via a factor of $µ_0$.
@@ -674,7 +666,7 @@ The tutorial {ref}`gallery-tutorial-field-computation` shows good practices with
 
 
 (docu-functional-interface)=
-## Direct interface
+## Functional interface
 
 Users can bypass the object oriented functionality of Magpylib and instead compute the field for n given parameter sets. This is done by providing the following inputs to the top level functions `getB`, `getH`, `getJ` and, `getM`.
 
@@ -688,7 +680,6 @@ All "scalar" inputs of shape (x,) are automatically tiled up to shape (n,x) to c
 import numpy as np
 import magpylib as magpy
 # All inputs and outputs in SI units
-# This example shows the scale invariance
 
 # compute the cuboid field for 3 input instances
 N = 3 # number of instances
@@ -699,6 +690,7 @@ B = magpy.getB(
     polarization=(0,0,1),
 )
 
+# This example demonstrates the scale invariance
 print(B)
 #  --> [[0.         0.         0.13478239]
 #       [0.         0.         0.13478239]

docs/_pages/docu/docu_physics.md

@@ -15,7 +15,7 @@ kernelspec:
 
 # Physics
 
-## When can you use Magpylib ?
+## What is implemented ?
 
 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 %. Demagnetization factors are not included. The line **current** solutions give the exact same field as outside of a wire that carries a homogeneous current.
 
@@ -67,18 +67,23 @@ Error estimation as a result of the material response is evaluated in more detai
 
 Demagnetization factors can be used to compensate a large part of the demagnetization effect. Analytical expressions for the demagnetization factors of cuboids can be found at [magpar.net](http://www.magpar.net/static/magpar/doc/html/demagcalc.html).
 
+
 (phys-remanence)=
 ### Modelling a datasheet magnet
 
 The material remanence, often found in data sheets, simply corresponds to the material magnetization/polarization when not under the influence of external fields. This can never happen, as the material itself generates a magnetic field. Such self-interactions result in self-demagnetization that can be approximated using the demagnetization factors and the material permeability (or susceptibility).
 
 For example, a cube with 1 mm sides has a demagnetization factor is 0.333, see [magpar.net](http://www.magpar.net/static/magpar/doc/html/demagcalc.html). When the remanence field of this cube is 1 T, and its susceptibility is 0.1, the magnetization resulting from self-interaction is reduced to 1 T - 0.3333*0.1 T = 0.9667 T, assuming linear material laws.
 
+A [tutorial](gallery-tutorial-modelling-magnets) explains how to deal with demagnetization effects and how real magnets can be modeled using datasheet values.
+
 It must be understood that the change in magnetization resulting from self-interaction has a homogeneous contribution which is approximated by the demagnetization factor, and an inhomogeneous contribution which cannot be modeled easily with analytical solutions. The inhomogeneous part, however, is typically an order of magnitude lower than the homogenous part. You can use the Magpylib extension [Magpylib material response](https://github.com/magpylib/magpylib-material-response) to model the self-interactions.
 
 ### Soft-Magnetic Materials
 
-Soft-magnetic materials like iron or steel with large permeabilities $\mu_r \sim 1000$ and low remanence fields are dominated by the material response. It is not possible to describe such bodies with analytical solutions. However, recent developments showed that the Magnetostatic Method of Moments can be a powerful tool in combination with Magpylib to compute such a material response. An integration into Magpylib is planned for the future.
+Soft-magnetic materials like iron or steel with large permeabilities $\mu_r \sim 1000$ and low remanence fields are dominated by the material response. It is not possible to describe such bodies with analytical solutions. However, recent developments showed that the **Magnetostatic Method of Moments** can be a powerful tool in combination with Magpylib to compute such a material response. An integration into Magpylib is planned in the future.
+
+When a magnet lies in front of a soft-magnetic plate, the contribution from the plate can be modeled with high accuracy using a **mirror**-approach, similar to the electrostatic "mirror charge".
 
 
 (docu-performance)=
@@ -92,7 +97,7 @@ Maximal performance is achieved when `.getB(sources, observers)` is called only
 
 The object oriented interface comes with an overhead. If you want to achieve maximal performance this overhead can be avoided with {ref}`docu-functional-interface`.
 
-The analytical solutions provide extreme performance. Single field evaluations take of the order of `100 µs`. For large input arrays (e.g. many observer positions or many similar magnets) the computation time drops below `1 µs` per evaluation point on single state-of-the-art x86 mobile cores (tested on `Intel Core i5-8365U @ 1.60GHz`), depending on the source type.
+The analytical solutions provide extreme performance. Single field evaluations take of the order of `100 µs`. For large input arrays (e.g. many observer positions or many similar magnets) the computation time can drop below `1 µs` per evaluation point on single state-of-the-art x86 mobile cores (tested on `Intel Core i5-8365U @ 1.60GHz`), depending on the source type.
 
 ## Numerical stability
 

docs/_pages/gallery/gallery_app_end_of_shaft.md

@@ -16,7 +16,7 @@ orphan: true
 
 # Magnetic Angle Sensor
 
-End of shaft angle sensing is a classical example for a magnetic position system. The goal is to determine the angular position of a rotating shaft. A magnet, typically a diametrically magnetized cylinder, is mounted at the end of the shaft. A 2D sensor is mounted below. When the shaft rotates the two sensor outputs will be $s_1=B_0 sin(\varphi)$ and $s_2=B_0 cos(\varphi)$, so that the angle is uniquely given by $\varphi = arctan(s_1/s_2)$.
+End of shaft angle sensing is a classical example for a magnetic position system. The goal is to determine the angular position of a rotating shaft. A magnet, typically a diametrically magnetized cylinder, is mounted at the end of the shaft. A 2D sensor is mounted below. When the shaft rotates the two sensor outputs will be $s_1=B_0 sin(\varphi)$ and $s_2=B_0 cos(\varphi)$, so that the angle is uniquely given by $\varphi = arctan_2(s_1,s_2)$.
 
 In the example below we show such a typical end-of-shaft system with a 2-pixel sensor, that is commonly used to eliminate external stray fields. In addition, we assume that the magnet is not perfectly mounted at the end of the shaft, but slightly displaced to the side, which results in a wobble motion. Such tolerances are easily implemented with Magpylib, they can be visualized and their influence on the sensor output signal can be tested quickly.
 

docs/_pages/gallery/gallery_app_halbach.md

@@ -16,5 +16,8 @@ kernelspec:
 
 # Halbach Magnets
 
-- halbach ring with fine discretization
-- discrete halbach cylinder models
+Magpylib is an excellent tool to create magnet assemblies. In this example we will show how to model Halbach magnets.
+
+Example 1: Halbach magnetization using CylinderSegmetns
+
+Example 2: Discreete Halbach magnets