Merge branch 'main' of https://github.com/magpylib/magpylib into brin…

…g_flyout_back

.github/ISSUE_TEMPLATE/bug_report.yaml

@@ -12,8 +12,9 @@ body:
       label: Magpylib version
       description: What version of Magpylib are you running?
       options:
+        - 5.x (Latest)
         - 5.x (Unreleased)
-        - 4.x (Latest)
+        - 4.x
         - 3.x
         - 2.x
         - 1.x

.pre-commit-config.yaml

@@ -1,6 +1,6 @@
 repos:
   - repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v4.5.0
+    rev: v4.6.0
     hooks:
       - id: check-yaml
       - id: end-of-file-fixer
@@ -18,14 +18,14 @@ repos:
         name: isort (python)
 
   - repo: https://github.com/asottile/pyupgrade
-    rev: v3.15.1
+    rev: v3.15.2
     hooks:
       - id: pyupgrade
         args: [--py38-plus]
 
 
   - repo: https://github.com/psf/black
-    rev: "24.2.0"
+    rev: "24.4.0"
     hooks:
       - id: black
 

CHANGELOG.md

@@ -3,18 +3,22 @@ All notable changes to magpylib are documented here.
 
 # Changelog
 
-## [5.0.0] - Bald
+## [5.0.1] - 2024-04-12
+- Fixed a bug where `getBHJM` of a Collection would produce one extra dimension ([#753](https://github.com/magpylib/magpylib/issues/753))
+- Fixed a bug where the legend of a deeply nested Collection would be wrong ([#756](https://github.com/magpylib/magpylib/issues/756))
+
+## [5.0.0] - 2024-03-13
 ### ⚠️ 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.
+- 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))
+- The `in_out` (inside/outside) 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))
-- As Matplotlib graphic representation of 3D objects is terrible, we descided to go back to "arrow" graphic default mode when graphic backend is "Matplotlib".([#735](https://github.com/magpylib/magpylib/issues/735))
+- As Matplotlib graphic representation of 3D objects is terrible, we decided to go back to "arrow" graphic default mode when graphic backend is "Matplotlib".([#735](https://github.com/magpylib/magpylib/issues/735))
 
 ## [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))
@@ -36,12 +40,12 @@ All notable changes to magpylib are documented here.
 - Discontinuous segments in `current.Line` are now accepted and correctly treated as separate lines ([#632](https://github.com/magpylib/magpylib/pull/632), [#642](https://github.com/magpylib/magpylib/pull/642))
 - Objects can now be displayed with missing dimension and/or excitation ([#640](https://github.com/magpylib/magpylib/pull/640))
 - Added magnetization and current arrows `sizemode` styling option (absolute or scaled) ([#639](https://github.com/magpylib/magpylib/pull/639))
-- `Collection` objects now also have a default description when displayed (number of chidren) ([#634](https://github.com/magpylib/magpylib/pull/634))
+- `Collection` objects now also have a default description when displayed (number of children) ([#634](https://github.com/magpylib/magpylib/pull/634))
 - Many minor graphic improvements ([#663](https://github.com/magpylib/magpylib/pull/663), [#649](https://github.com/magpylib/magpylib/issues/649), [#653](https://github.com/magpylib/magpylib/issues/653))
 - `legend` style option ([#650](https://github.com/magpylib/magpylib/issues/650))
 - Changed unit naming in text to comply with DIN Norm 641 ([#614](https://github.com/magpylib/magpylib/issues/614))
 - Improved documentation now boasting a contribution guide, a news-blog, an example and tutorial gallery, a getting started section and many other improvements ([#621](https://github.com/magpylib/magpylib/issues/621), [#596](https://github.com/magpylib/magpylib/issues/596), [#580](https://github.com/magpylib/magpylib/issues/580))
-- Improved numerical stability of `CylinderSegement`, ([#648](https://github.com/magpylib/magpylib/issues/648), [#651](https://github.com/magpylib/magpylib/issues/651))
+- Improved numerical stability of `CylinderSegment`, ([#648](https://github.com/magpylib/magpylib/issues/648), [#651](https://github.com/magpylib/magpylib/issues/651))
 
 
 ## [4.3.0] - 2023-06-25
@@ -114,13 +118,13 @@ This is a major update that includes
 - All classes have the `describe` method which gives a quick object property overview.
 
 ### Field computation changes/fixes:
-- New computation core. Added top level subpackage `magpylib.core` where all field implementations can be accessed directly without the position/orienation interface. ([#376](https://github.com/magpylib/magpylib/issues/376))
-- Direct interface functions `getBdict` and `getHdict` (previously `getBv` and `getHv`) are now integrated into `getB` and `getH`. See docu for details ([#449](https://github.com/magpylib/magpylib/pull/449))
+- New computation core. Added top level subpackage `magpylib.core` where all field implementations can be accessed directly without the position/orientation interface. ([#376](https://github.com/magpylib/magpylib/issues/376))
+- Direct interface functions `getBdict` and `getHdict` (previously `getBv` and `getHv`) are now integrated into `getB` and `getH`. See docs for details ([#449](https://github.com/magpylib/magpylib/pull/449))
 - Generally improved field expressions: ([#374](https://github.com/magpylib/magpylib/issues/374))
   - Negative dimension input taken as absolute when only positive dimensions are allowed.
   - Scale invariant field evaluations.
   - Special cases caught within 1e-15 rtol and atol to account for numerical imprecision with positioning (e.g. object rotation).
-  - Supress numpy divide/invalid warnings. return `np.nan` as `(0,0,0)` (e.g. on magnet edges or on line currents) and allow return of `np.inf`.
+  - Suppress numpy divide/invalid warnings. return `np.nan` as `(0,0,0)` (e.g. on magnet edges or on line currents) and allow return of `np.inf`.
   - New closed form implementation for `Cylinder` with diametral magnetization is much faster (100-1000x) and numerically stable for small `r`. ([#404](https://github.com/magpylib/magpylib/issues/404), [#370](https://github.com/magpylib/magpylib/issues/370))
   - Improved numerical stability of current loop field. Now 12-14 correct digits everywhere. ([#374](https://github.com/magpylib/magpylib/issues/374))
   - Fixed `Collection` of `Lines` field computation error. ([#368](https://github.com/magpylib/magpylib/issues/368))
@@ -452,7 +456,8 @@ The first official release of the magpylib library.
 
 ---
 
-[5.0.0dev]:https://github.com/magpylib/magpylib/compare/4.5.1...HEAD
+[5.0.1]:https://github.com/magpylib/magpylib/compare/5.0.0...HEAD
+[5.0.0]:https://github.com/magpylib/magpylib/compare/4.5.1...5.0.0
 [4.5.1]:https://github.com/magpylib/magpylib/compare/4.5.0...4.5.1
 [4.5.0]:https://github.com/magpylib/magpylib/compare/4.4.0...4.5.0
 [4.4.1]:https://github.com/magpylib/magpylib/compare/4.4.0...4.4.1

README.md

@@ -20,7 +20,7 @@
 </a>
 <a href="https://anaconda.org/conda-forge/magpylib"> <img src="https://anaconda.org/conda-forge/magpylib/badges/version.svg" alt="Conda Cloud" height="18">
 </a>
-<a href="https://mybinder.org/v2/gh/magpylib/magpylib/5.0.0dev?filepath=docs%2Fexamples"> <img src="https://mybinder.org/badge_logo.svg" alt="MyBinder link" height="18">
+<a href="https://mybinder.org/v2/gh/magpylib/magpylib/5.0.0?filepath=docs%2Fexamples"> <img src="https://mybinder.org/badge_logo.svg" alt="MyBinder link" height="18">
 </a>
 <a href="https://github.com/psf/black"> <img src="https://img.shields.io/badge/code%20style-black-000000.svg" alt="black" height="18">
 </a>
@@ -40,12 +40,12 @@ conda install -c conda-forge magpylib
 ```
 Magpylib supports _Python3.8+_ and relies on common scientific computation libraries _Numpy_, _Scipy_, _Matplotlib_ and _Plotly_. Optionally, _Pyvista_ is recommended as graphical backend.
 
-# Ressources
+# Resources
 
  - Check out our **[Documentation](https://magpylib.readthedocs.io/en/latest)** for detailed information.
  - Please abide by our **[Code of Conduct](https://github.com/magpylib/magpylib/blob/main/CODE_OF_CONDUCT.md)**.
  - Contribute through **[Discussions](https://github.com/magpylib/magpylib/discussions)** and coding by following the **[Contribution Guide](https://github.com/magpylib/magpylib/blob/main/CONTRIBUTING.md)**. The Git project **[Issues](https://github.com/magpylib/magpylib/issues)** give an up-to-date list of potential enhancements and planned milestones. Propose new ones.
- - A **[Youtube video](https://www.youtube.com/watch?v=LeUx6cM1vcs)** introdution to Magpylib v4.0.0 within the **[GSC network](https://www.internationalcollaboration.org/).**
+ - A **[Youtube video](https://www.youtube.com/watch?v=LeUx6cM1vcs)** introduction to Magpylib v4.0.0 within the **[GSC network](https://www.internationalcollaboration.org/).**
 - An **[open-access paper](https://www.sciencedirect.com/science/article/pii/S2352711020300170)** from the year 2020 describes v2 of this library with most basic concepts still intact in later versions.
 
 # Quickstart
@@ -77,7 +77,7 @@ print(cube.orientation.as_rotvec(degrees=True))  # --> [0. 0. 45.]
 
 # Compute the magnetic B-field in units of T at a set of observer positions. Magpylib
 # makes use of vectorized computation. Hand over all field computation instances,
-# e.g. different observer positions, at one funtion call. Avoid Python loops !!!
+# e.g. different observer positions, at one function call. Avoid Python loops !!!
 observers = [(0, 0, 0), (0.01, 0, 0), (0.02, 0, 0)]  # in SI Units (m)
 B = magpy.getB(cube, observers)
 print(B.round(2))  # --> [[-0.09 -0.09  0.  ]
@@ -92,7 +92,7 @@ H = magpy.getH(cube, sensor)
 print(H.round())  # --> [-94537. -35642. -14085.]  # in SI Units (A/m)
 
 # Position and orientation attributes of Magpylib objects can be vectors of
-# multiple positions/orientations refered to as "paths". When computing the
+# multiple positions/orientations referred to as "paths". When computing the
 # magnetic field of an object with a path, it is computed at every path index.
 cube.position = [(0, 0, -.02), (1, 0, -.02), (2, 0, -.02)]  # in SI Units (m)
 B = cube.getB(sensor)
@@ -136,7 +136,7 @@ A valid software citation could be
     author = {{Michael-Ortner et al.}},
     title = {magpylib},
     url = {https://magpylib.readthedocs.io/en/latest/},
-    version = {5.0.0dev},
+    version = {5.0.1},
     date = {2023-06-25},
 }
 ```

docs/_pages/docu/docu_graphics.md

@@ -616,7 +616,7 @@ Magpylib also offers the possibility to display objects into separate subplots.
 
 +++
 
-3D suplots can be directly defined in the `show` function by passing input objects as dictionaries with the arguments `objects`, `col` (column) and `row`, as in the example below. If now `row` or no `col` is specified, it defaults to 1.
+3D subplots can be directly defined in the `show` function by passing input objects as dictionaries with the arguments `objects`, `col` (column) and `row`, as in the example below. If now `row` or no `col` is specified, it defaults to 1.
 
 ```{code-cell} ipython3
 import numpy as np

docs/_pages/docu/docu_magpylib_api.md

@@ -41,11 +41,12 @@ For historical reasons Magpylib used non-SI units until Version 4. Starting with
 ::::
 
 ```{warning}
-Up to version 4, Magpylib was unfortunately contributing to the naming confusion in magnetism that is explained well [here](https://www.e-magnetica.pl/doku.php/confusion_between_b_and_h). The input `magnetization` in Magpylib < v5 was refering to the magnetic polarization (and not the magnetization), the difference being only in the physical unit. From version 5 onwards this is fixed.
+Up to version 4, Magpylib was unfortunately contributing to the naming confusion in magnetism that is explained well [here](https://www.e-magnetica.pl/doku.php/confusion_between_b_and_h). The input `magnetization` in Magpylib < v5 was referring to the magnetic polarization (and not the magnetization), the difference being only in the physical unit. From version 5 onwards this is fixed.
 ```
 
-```{note}
-All input and output units in Magpylib (version 5 and higher) are SI-based, see table above. However, for advanced use one should be aware that the analytical solutions are scale invariant - _"a magnet with 1 mm sides creates the same field at 1 mm distance as a magnet with 1 m sides at 1 m distance"_. The choice of length input unit is therefore not relevant, but it is critical to keep the same length unit for all inputs in one computation.
+(docu-api-scale-invariance)=
+```{hint}
+All input and output units in Magpylib (version 5 and higher) are SI-based, see table above. However, for advanced use one should be aware that the analytical solutions are **scale invariant** - _"a magnet with 1 mm sides creates the same field at 1 mm distance as a magnet with 1 m sides at 1 m distance"_. The choice of length input unit is therefore not relevant, but it is critical to keep the same length unit for all inputs in one computation.
 
 In addition, `getB` returns the same unit as given by the `polarization` input. 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$.
 ```
@@ -125,7 +126,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-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}`gallery-tutorial-modelling-magnets`.
 
 
 ### Cuboid
@@ -306,7 +307,7 @@ magpylib.current.Polyline(position, orientation, vertices, current, style)
 ::::{grid} 2
 :::{grid-item}
 :columns: 9
-`Polyline` objects represent line current segements where the electric current flows in straight lines from vertex to vertex. The <span style="color: orange">**vertices**</span> attribute is a vector of all vertices $(\vec{P}_1, \vec{P}_2, ...)$ given in the local coordinates in units of meter.
+`Polyline` objects represent line current segments where the electric current flows in straight lines from vertex to vertex. The <span style="color: orange">**vertices**</span> attribute is a vector of all vertices $(\vec{P}_1, \vec{P}_2, ...)$ given in the local coordinates in units of meter.
 :::
 :::{grid-item}
 :columns: 3
@@ -316,7 +317,7 @@ magpylib.current.Polyline(position, orientation, vertices, current, style)
 
 ---------------------------------------------
 
-## Miscellanous classes
+## Miscellaneous classes
 
 There are classes listed hereon that function as sources, but they do not represent physical magnets or current distributions.
 
@@ -622,9 +623,9 @@ magpylib.getJ(sources, observers, squeeze=True, pixel_agg=None, output="ndarray"
 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. For quick-access, the functions `getBHJM` are also methods of all Magylib objects, such that the `sources` or `observers` input is the object itself.
+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 Magpylib objects, such that the `sources` or `observers` input is the object itself.
 
-The following code shows a minimal example for Magplyib field computation.
+The following code shows a minimal example for Magpylib field computation.
 
 ```python
 import magpylib as magpy
@@ -641,7 +642,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 as described in the docstings.
+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 docstrings.
 
 ```{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$.
@@ -723,7 +724,7 @@ At the heart of Magpylib lies a set of core functions that are our implementatio
 :::
 
 :::{grid-item}
-<span style="color: orange">**magnet_cylinder_segmet_Hfield(**</span> `observers`, `dimensions`, `magnetizations`<span style="color: orange">**)**</span>
+<span style="color: orange">**magnet_cylinder_segment_Hfield(**</span> `observers`, `dimensions`, `magnetizations`<span style="color: orange">**)**</span>
 :::
 
 :::{grid-item}