Improve holding force example (#830)

OrtnerMichael · Alexboiboi · web-flow · commit 6f3e3d8216c5 · 2025-03-05T00:23:00.000+01:00
* improve holding-force example

* fix langage and typos (modelling -&gt; modeling, haftkraft -&gt; holding_force

---------

Co-authored-by: Alexandre Boisselet &lt;alexabois@gmail.com&gt;
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -4,6 +4,7 @@
 - Improved docstrings by adding examples where missing and by using rounding in all examples to avoid doctest fails
 - Fixed a bug where a core getH would return the B-field
 - Input `in_out` is by default set to `"auto"` for collections to avoiding ambiguities.
+- Improve documentation ([#829](https://github.com/magpylib/magpylib/issues/829))
 
 ## [5.1.1] - 2024-10-31
 - Included magpylib-force version 0.3.1 in documentation
diff --git a/docs/_pages/user_guide/docs/docs_classes.md b/docs/_pages/user_guide/docs/docs_classes.md
@@ -59,7 +59,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 relation $\vec{J}=\mu_0\cdot\vec{M}$. Information on how this is related to material properties from data sheets is found in {ref}`examples-tutorial-modelling-magnets`.
+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 relation $\vec{J}=\mu_0\cdot\vec{M}$. Information on how this is related to material properties from data sheets is found in {ref}`examples-tutorial-modeling-magnets`.
 
 
 ### Cuboid
diff --git a/docs/_pages/user_guide/docs/docs_units_types.md b/docs/_pages/user_guide/docs/docs_units_types.md
@@ -33,7 +33,7 @@ Up to version 4, Magpylib was unfortunately contributing to the naming confusion
 ```
 
 ```{note}
-The connection between the magnetic polarization J, the magnetization M and the material parameters of a real permanent magnet are shown in {ref}`examples-tutorial-modelling-magnets`.
+The connection between the magnetic polarization J, the magnetization M and the material parameters of a real permanent magnet are shown in {ref}`examples-tutorial-modeling-magnets`.
 ```
 
 (guide-docs-io-scale-invariance)=
diff --git a/docs/_pages/user_guide/examples/examples_app_halbach.md b/docs/_pages/user_guide/examples/examples_app_halbach.md
@@ -81,5 +81,5 @@ plt.show()
 ```
 
 ```{warning}
-Magpylib models magnets with perfect polarization. However, such magnets do not exist in reality due to fabrication tolerances and material response. While fabrication tolerances can be estimated easily, our [tutorial](examples-tutorial-modelling-magnets) explains how to deal with material response.
+Magpylib models magnets with perfect polarization. However, such magnets do not exist in reality due to fabrication tolerances and material response. While fabrication tolerances can be estimated easily, our [tutorial](examples-tutorial-modeling-magnets) explains how to deal with material response.
 ```
diff --git a/docs/_pages/user_guide/examples/examples_force_holding_force.md b/docs/_pages/user_guide/examples/examples_force_holding_force.md
@@ -1,12 +1,12 @@
-(examples-force-haftkraft)=
+(examples-force-holding-force)=
 
 # Magnetic Holding Force
 
 The examples here require installaion of the [magpylib-force package](https://pypi.org/project/magpylib-force/). See also the [magpylib-force documentation](docs-magpylib-force).
 
-With Magpylib-force it is possible to compute the holding force of a magnet attached magnetically to a soft-ferromagnetic plate.
+With Magpylib-force it is possible to compute the holding force of a magnet attached magnetically to a soft-ferromagnetic plate. The "pull-force" is the opposing force that is required to detach the magnet from the surface.
 
-```{figure} ../../../_static/images/examples_force_haftkraft.png
+```{figure} ../../../_static/images/examples_force_holding_force.png
 :width: 40%
 :align: center
 :alt: Sketch of holding force.
@@ -27,7 +27,7 @@ m1 = magpy.magnet.Cuboid(
     dimension=(5e-3, 2.5e-3, 1e-3),
     polarization=(0, 0, 1.33),
 )
-m1.meshing = (10,5,2)
+m1.meshing = 100
 
 # Mirror magnet
 m2 = m1.copy(position=(0,0,1e-3))
@@ -37,4 +37,4 @@ print(f"Holding Force: {round(F[2]*100)} g")
 # Holding Force: 349 g
 ```
 
-Magnet dimensions and material from this example are taken from the [web](https://www.supermagnete.at/quadermagnete-neodym/quadermagnet-5mm-2.5mm-1.5mm_Q-05-2.5-1.5-HN). The remanence of N45 material lies within 1.32 and 1.36 T. The computation confirms what is stated on the web-page, that the holding force of this magnet is about 350 g.
+Magnet dimensions and material from this example are taken from the [web](https://www.supermagnete.at/quadermagnete-neodym/quadermagnet-5mm-2.5mm-1.5mm_Q-05-2.5-1.5-HN). The remanence of N45 material lies within 1.32 and 1.36 T which corresponds to the polarization, see also the ["Modeling a real magnet"](examples-tutorial-modeling-magnets) tutorial. The computation confirms what is stated on the web-page, that the holding force of this magnet is about 350 g.
diff --git a/docs/_pages/user_guide/examples/examples_index.md b/docs/_pages/user_guide/examples/examples_index.md
@@ -38,12 +38,12 @@
 :img-bottom: ../../../_static/images/examples_icon_tutorial_custom.png
 :::
 
-:::{grid-item-card} {ref}`examples-tutorial-modelling-magnets`
+:::{grid-item-card} {ref}`examples-tutorial-modeling-magnets`
 :text-align: center
-:link: examples-tutorial-modelling-magnets
+:link: examples-tutorial-modeling-magnets
 :link-type: ref
 :link-alt: link to example
-:img-bottom: ../../../_static/images/examples_icon_tutorial_modelling_magnets.png
+:img-bottom: ../../../_static/images/examples_icon_tutorial_modeling_magnets.png
 :::
 
 ::::
@@ -231,12 +231,12 @@
 :img-bottom: ../../../_static/images/examples_icon_force_force.png
 :::
 
-:::{grid-item-card} {ref}`examples-force-haftkraft`
+:::{grid-item-card} {ref}`examples-force-holding-force`
 :text-align: center
-:link: examples-force-haftkraft
+:link: examples-force-holding-force
 :link-type: ref
 :link-alt: link to example
-:img-bottom: ../../../_static/images/examples_icon_force_haftkraft.png
+:img-bottom: ../../../_static/images/examples_icon_force_holding_force.png
 :::
 
 :::{grid-item-card} {ref}`examples-force-floating`
@@ -258,7 +258,7 @@ examples_tutorial_paths.md
 examples_tutorial_field_computation.md
 examples_tutorial_collection.md
 examples_tutorial_custom.md
-examples_tutorial_modelling_magnets.md
+examples_tutorial_modeling_magnets.md
 
 examples_vis_magnet_colors.md
 examples_vis_animations.md
@@ -282,7 +282,7 @@ examples_app_coils.md
 examples_app_scales.md
 
 examples_force_force.md
-examples_force_haftkraft.md
+examples_force_holding_force.md
 examples_force_floating.md
 ```
 
diff --git a/docs/_pages/user_guide/examples/examples_misc_inhom.md b/docs/_pages/user_guide/examples/examples_misc_inhom.md
@@ -16,7 +16,7 @@ kernelspec:
 
 # Inhomogeneous Magnetization
 
-The analytical expressions implemented in Magpylib treat only simple homogeneous polarizations. When dealing with high-grade materials that are magnetized in homogeneous fields this is a good approximation. However, there are many cases where such a homogeneous model is not justified. The tutorial {ref}`examples-tutorial-modelling-magnets` and the user-guide {ref}`guide-physics-demag` provide some insights on this topic.
+The analytical expressions implemented in Magpylib treat only simple homogeneous polarizations. When dealing with high-grade materials that are magnetized in homogeneous fields this is a good approximation. However, there are many cases where such a homogeneous model is not justified. The tutorial {ref}`examples-tutorial-modeling-magnets` and the user-guide {ref}`guide-physics-demag` provide some insights on this topic.
 
 Here we show how to deal with inhomogeneous polarization based on a commonly misunderstood example of a cylindrical quadrupol magnet. While graphical representations of such magnets usually depict only four poles, see {ref}`examples-vis-magnet-colors`, such magnets exhibit complex polarization given by the magnetization device that is used to magnetize them.
 
diff --git a/docs/_pages/user_guide/examples/examples_tutorial_modeling_magnets.md b/docs/_pages/user_guide/examples/examples_tutorial_modeling_magnets.md
@@ -1,6 +1,6 @@
-(examples-tutorial-modelling-magnets)=
+(examples-tutorial-modeling-magnets)=
 
-# Modelling a real magnet
+# Modeling a real magnet
 
 Whenever you wish to compare Magpylib simulations with experimental data obtained using a real permanent magnet, you might wonder how to properly set up a Magpylib magnet object to reflect the physical permanent magnet in question. The goal of this tutorial is to explain how to extract this information from respective datasheets, to provide better understanding of permanent magnets, and show how to align Magpylib simulations with experimental measurements.
 
diff --git a/docs/_pages/user_guide/examples/examples_vis_magnet_colors.md b/docs/_pages/user_guide/examples/examples_vis_magnet_colors.md
@@ -22,7 +22,7 @@ The polarization direction of a permanent magnet is often graphically displayed
 Magpylib uses the DIN Specification 91411 (soon 91479) standard as default setting. The tri-color scheme has the advantage that for multi-pole elements it becomes clear which north is "connected" to which south.
 
 ```{hint}
-The color schemes often seem to represent homogeneous polarizations, referred to as "ideal typical" magnets in DIN Specification 91479. However, they often just represent general "pole patterns", i.e. rough sketches where the field goes in and where it comes out, that are not the result of homogeneous polarizations. On this topic review also the examples example {ref}`examples-misc-inhom`, and the tutorial {ref}`examples-tutorial-modelling-magnets`.
+The color schemes often seem to represent homogeneous polarizations, referred to as "ideal typical" magnets in DIN Specification 91479. However, they often just represent general "pole patterns", i.e. rough sketches where the field goes in and where it comes out, that are not the result of homogeneous polarizations. On this topic review also the examples example {ref}`examples-misc-inhom`, and the tutorial {ref}`examples-tutorial-modeling-magnets`.
 ```
 
 With Magpylib users can easily tune the magnet color schemes. The `style` options are `tricolor` with north, middle and south colors, and `bicolor` with north and south colors.
diff --git a/docs/_pages/user_guide/guide_resources_01_physics.md b/docs/_pages/user_guide/guide_resources_01_physics.md
@@ -56,13 +56,13 @@ Demagnetization factors can be used to compensate a large part of the demagnetiz
 
 
 (phys-remanence)=
-### Modelling a datasheet magnet
+### Modeling 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](examples-tutorial-modelling-magnets) explains how to deal with demagnetization effects and how real magnets can be modeled using datasheet values.
+A [tutorial](examples-tutorial-modeling-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.
 
diff --git a/docs/_static/images/examples_force_holding_force.png b/docs/_static/images/examples_force_holding_force.png
diff --git a/docs/_static/images/examples_icon_force_holding_force.png b/docs/_static/images/examples_icon_force_holding_force.png
diff --git a/docs/_static/images/examples_icon_tutorial_modeling_magnets.png b/docs/_static/images/examples_icon_tutorial_modeling_magnets.png
