Merge branch 'doku_rework' of https://github.com/magpylib/magpylib into doku_rework

Author: OrtnerMichael

docs/_pages/gallery/gallery_tutorial_custom.md

@@ -34,6 +34,10 @@ import magpylib as magpy
 
 While each of these features can be used individually, the combination of the two (own source class with own 3D representation) enables a high level of customization in Magpylib. Such user-defined objects will feel like native Magpylib objects and can be used in combination with all other features, which is demonstrated in the following example:
 
+<<<<<<< HEAD:docs/examples/examples_04_custom_source.md
+The class `CustomSource` allows users to integrate their own custom-object field computation into the Magpylib interface. For this, the argument `field_func` must be provided with a function that is then automatically called with `getB` and `getH`. This custom field function is treated like a core function. It must have the positional arguments `field` (with values `'B'` or `'H'`), and `observers` (must accept array_like, shape (n,3)) and return the B-field in units of mT and the H-field in units of kA/m with a similar shape. A fundamental example how to create a custom source object is shown below:
+=======
+>>>>>>> 0ad604af38a3349f58f35e8e8e911c4eb2961e3c:docs/_pages/gallery/gallery_tutorial_custom.md
 
 ```{code-cell} ipython3
 import numpy as np
@@ -136,7 +140,7 @@ ax2.set(
     ylabel='z-position (mm)',
     aspect=1,
 )
-fig.colorbar(cp, label='[$charge/mm^2$]', ax=ax2)
+fig.colorbar(cp, label='($charge/mm^2$)', ax=ax2)
 
 plt.tight_layout()
 plt.show()

docs/_pages/page_01_introduction.md

@@ -286,6 +286,13 @@ def draw_frame(frame_ind):
             constructor = tr["constructor"]
             args = tr.get("args", ())
             kwargs = tr.get("kwargs", {})
+<<<<<<< HEAD
+            getattr(ax, constructor)(*args, **kwargs)
+        ax.set(
+            **{f"{k}label": f"{k} (mm)" for k in "xyz"},
+            **{f"{k}lim": r for k, r in zip("xyz", ranges)},
+        )
+=======
             if frame_ind == 0:
                 if row_col_num not in count_with_labels:
                     count_with_labels[row_col_num] = 0
@@ -318,6 +325,7 @@ def draw_frame(frame_ind):
                     )
             else:
                 ax.legend(loc="best")
+>>>>>>> 0ad604af38a3349f58f35e8e8e911c4eb2961e3c
 
     def animate(ind):  # pragma: no cover
         for ax in axes.values():

magpylib/_src/display/backend_matplotlib.py

@@ -87,7 +87,7 @@ def fieldH_cylinder_diametral(
     dim: ndarray, shape (n,2)
         dimension of cylinder (d, h), diameter and height, in units of mm
     tetta: ndarray, shape (n,)
-        angle between magnetization vector and x-axis in [rad]. M = (cos(tetta), sin(tetta), 0)
+        angle between magnetization vector and x-axis in rad. M = (cos(tetta), sin(tetta), 0)
     obs_pos: ndarray, shape (n,3)
         position of observer (r,phi,z) in cylindrical coordinates in units of mm and rad
 
@@ -410,7 +410,7 @@ def magnet_cylinder_field(
 #     dim: ndarray, shape (n,2)
 #         dimension of cylinder (d, h), diameter and height, in units of mm
 #     tetta: ndarray, shape (n,)
-#         angle between magnetization vector and x-axis in [rad]. M = (cos(tetta), sin(tetta), 0)
+#         angle between magnetization vector and x-axis in rad. M = (cos(tetta), sin(tetta), 0)
 #     obs_pos: ndarray, shape (n,3)
 #         position of observer (r,phi,z) in cylindrical coordinates in units of mm and rad
 #     niter: int

magpylib/_src/fields/field_BH_cylinder.py

@@ -2140,11 +2140,19 @@ def magnet_cylinder_segment_core(
     Parameters
     ----------
     mag: ndarray, shape (n,3)
+<<<<<<< HEAD
+        magnetization vector (M, phi, th) in spherical CS, units: mT rad
+    obs_pos : ndarray, shape (n,3)
+        observer positions (r,phi,z) in cy CS, units: mm rad
+    dim: ndarray, shape (n,6)
+        segment dimensions (r1,r2,phi1,phi2,z1,z2) in cy CS , units: mm rad
+=======
         magnetization vector (M, phi, th) in spherical CS, units: mT, rad
     obs_pos : ndarray, shape (n,3)
         observer positions (r,phi,z) in cy CS, units: mm rad
     dim: ndarray, shape (n,6)
         segment dimensions (r1,r2,phi1,phi2,z1,z2) in cy CS , units: mm, rad
+>>>>>>> 0ad604af38a3349f58f35e8e8e911c4eb2961e3c
 
     Returns
     -------

magpylib/_src/fields/field_BH_cylinder_segment.py

@@ -543,7 +543,11 @@ def getB(
     output="ndarray",
     **kwargs,
 ):
+<<<<<<< HEAD
+    """Compute B-field in mT for given sources and observers.
+=======
     """Compute B-field in units of mT for given sources and observers.
+>>>>>>> 0ad604af38a3349f58f35e8e8e911c4eb2961e3c
 
     Field implementations can be directly accessed (avoiding the object oriented
     Magpylib interface) by providing a string input `sources=source_type`, array_like
@@ -647,7 +651,11 @@ def getB(
 
     Examples
     --------
+<<<<<<< HEAD
+    In this example we compute the B-field (mT) of a spherical magnet and a current loop
+=======
     In this example we compute the B-field in units of mT of a spherical magnet and a current loop
+>>>>>>> 0ad604af38a3349f58f35e8e8e911c4eb2961e3c
     at the observer position (1,1,1) given in units of mm:
 
     >>> import magpylib as magpy

magpylib/_src/fields/field_wrap_BH.py

@@ -202,7 +202,11 @@ def magnetization(self):
 
     @magnetization.setter
     def magnetization(self, mag):
+<<<<<<< HEAD
+        """Set magnetization vector, array_like, shape (3,), unit (mT)."""
+=======
         """Set magnetization vector, array_like, shape (3,), unit mT."""
+>>>>>>> 0ad604af38a3349f58f35e8e8e911c4eb2961e3c
         self._magnetization = check_format_input_vector(
             mag,
             dims=(1,),
@@ -229,7 +233,11 @@ def current(self):
 
     @current.setter
     def current(self, current):
+<<<<<<< HEAD
+        """Set current value, scalar, unit (A)."""
+=======
         """Set current value, scalar, unit A."""
+>>>>>>> 0ad604af38a3349f58f35e8e8e911c4eb2961e3c
         # input type and init check
         self._current = check_format_input_scalar(
             current,

magpylib/_src/obj_classes/class_BaseExcitations.py

@@ -152,7 +152,11 @@ def getB(
         Examples
         --------
         Sensors are observers for magnetic field computation. In this example we compute the
+<<<<<<< HEAD
+        B-field (mT) as seen by the sensor in the center of a circular current loop:
+=======
         B-field in units of mT as seen by the sensor in the center of a circular current loop:
+>>>>>>> 0ad604af38a3349f58f35e8e8e911c4eb2961e3c
 
         >>> import magpylib as magpy
         >>> sens = magpy.Sensor()
@@ -227,7 +231,11 @@ def getH(
         Examples
         --------
         Sensors are observers for magnetic field computation. In this example we compute the
+<<<<<<< HEAD
+        H-field (kA/m) as seen by the sensor in the center of a circular current loop:
+=======
         H-field in kA/m as seen by the sensor in the center of a circular current loop:
+>>>>>>> 0ad604af38a3349f58f35e8e8e911c4eb2961e3c
 
         >>> import magpylib as magpy
         >>> sens = magpy.Sensor()

magpylib/_src/obj_classes/class_Sensor.py

@@ -45,7 +45,11 @@ class Line(BaseCurrent):
 
     Examples
     --------
+<<<<<<< HEAD
+    `Line` objects are magnetic field sources. In this example we compute the H-field (kA/m)
+=======
     `Line` objects are magnetic field sources. In this example we compute the H-field kA/m
+>>>>>>> 0ad604af38a3349f58f35e8e8e911c4eb2961e3c
     of a square-shaped line-current with 1 A current at the observer position (1,1,1) given in
     units of mm:
 
@@ -118,5 +122,9 @@ def vertices(self):
 
     @vertices.setter
     def vertices(self, vert):
+<<<<<<< HEAD
+        """Set Line vertices, array_like, (mm)."""
+=======
         """Set Line vertices, array_like, mm."""
+>>>>>>> 0ad604af38a3349f58f35e8e8e911c4eb2961e3c
         self._vertices = check_format_input_vertices(vert)

magpylib/_src/obj_classes/class_current_Line.py

@@ -44,7 +44,11 @@ class Loop(BaseCurrent):
 
     Examples
     --------
+<<<<<<< HEAD
+    `Loop` objects are magnetic field sources. In this example we compute the H-field (kA/m)
+=======
     `Loop` objects are magnetic field sources. In this example we compute the H-field kA/m
+>>>>>>> 0ad604af38a3349f58f35e8e8e911c4eb2961e3c
     of such a current loop with 100 A current and a diameter of 2 mm at the observer position
     (1,1,1) given in units of mm:
 
@@ -104,7 +108,11 @@ def diameter(self):
 
     @diameter.setter
     def diameter(self, dia):
+<<<<<<< HEAD
+        """Set Loop loop diameter, float, (mm)."""
+=======
         """Set Loop loop diameter, float, mm."""
+>>>>>>> 0ad604af38a3349f58f35e8e8e911c4eb2961e3c
         self._diameter = check_format_input_scalar(
             dia,
             sig_name="diameter",

magpylib/_src/obj_classes/class_current_Loop.py

@@ -45,7 +45,11 @@ class Cuboid(BaseMagnet):
 
     Examples
     --------
+<<<<<<< HEAD
+    `Cuboid` magnets are magnetic field sources. Below we compute the H-field (kA/m) of a
+=======
     `Cuboid` magnets are magnetic field sources. Below we compute the H-field in kA/m of a
+>>>>>>> 0ad604af38a3349f58f35e8e8e911c4eb2961e3c
     cubical magnet with magnetization (100,200,300) in units of mT and 1 mm sides
     at the observer position (1,1,1) given in units of mm:
 

magpylib/_src/obj_classes/class_magnet_Cuboid.py

@@ -45,7 +45,11 @@ class Cylinder(BaseMagnet):
 
     Examples
     --------
+<<<<<<< HEAD
+    `Cylinder` magnets are magnetic field sources. Below we compute the H-field (kA/m) of a
+=======
     `Cylinder` magnets are magnetic field sources. Below we compute the H-field in kA/m of a
+>>>>>>> 0ad604af38a3349f58f35e8e8e911c4eb2961e3c
     cylinder magnet with magnetization (100,200,300) in units of mT and 1 mm diameter and height
     at the observer position (1,1,1) given in units of mm:
 

magpylib/_src/obj_classes/class_magnet_Cylinder.py

@@ -58,7 +58,11 @@ class CylinderSegment(BaseMagnet):
     Examples
     --------
     `CylinderSegment` magnets are magnetic field sources. In this example we compute the
+<<<<<<< HEAD
+    H-field (kA/m) of such a cylinder segment magnet with magnetization (100,200,300)
+=======
     H-field kA/m of such a cylinder segment magnet with magnetization (100,200,300)
+>>>>>>> 0ad604af38a3349f58f35e8e8e911c4eb2961e3c
     in units of mT, inner radius 1 mm, outer radius 2 mm, height 1 mm, and
     section angles 0 and 45 deg at the observer position (2,2,2) in units of mm:
 

magpylib/_src/obj_classes/class_magnet_CylinderSegment.py

@@ -45,7 +45,11 @@ class Sphere(BaseMagnet):
 
     Examples
     --------
+<<<<<<< HEAD
+    `Sphere` objects are magnetic field sources. In this example we compute the H-field (kA/m)
+=======
     `Sphere` objects are magnetic field sources. In this example we compute the H-field kA/m
+>>>>>>> 0ad604af38a3349f58f35e8e8e911c4eb2961e3c
     of a spherical magnet with magnetization (100,200,300) in units of mT and diameter
     of 1 mm at the observer position (1,1,1) given in units of mm:
 
@@ -105,7 +109,11 @@ def diameter(self):
 
     @diameter.setter
     def diameter(self, dia):
+<<<<<<< HEAD
+        """Set Sphere diameter, float, (mm)."""
+=======
         """Set Sphere diameter, float, mm."""
+>>>>>>> 0ad604af38a3349f58f35e8e8e911c4eb2961e3c
         self._diameter = check_format_input_scalar(
             dia,
             sig_name="diameter",

magpylib/_src/obj_classes/class_magnet_Sphere.py

@@ -54,10 +54,17 @@ class Tetrahedron(BaseMagnet):
 
     Examples
     --------
+<<<<<<< HEAD
+    `Tetrahedron` magnets are magnetic field sources. Below we compute the H-field (kA/m) of a
+    tetrahedron magnet with magnetization (100,200,300) in units of mT dimensions defined
+    through the vertices (0,0,0), (1,0,0), (0,1,0) and (0,0,1) in units of mm at the
+    observer position (1,1,1) given in units of m:
+=======
     `Tetrahedron` magnets are magnetic field sources. Below we compute the H-field in kA/m of a
     tetrahedron magnet with magnetization (100,200,300) in units of mT dimensions defined
     through the vertices (0,0,0), (1,0,0), (0,1,0) and (0,0,1) in units of mm at the
     observer position (1,1,1) given in units of mm:
+>>>>>>> 0ad604af38a3349f58f35e8e8e911c4eb2961e3c
 
     >>> import magpylib as magpy
     >>> verts = [(0,0,0), (1,0,0), (0,1,0), (0,0,1)]
@@ -117,7 +124,11 @@ def vertices(self):
 
     @vertices.setter
     def vertices(self, dim):
+<<<<<<< HEAD
+        """Set Tetrahedron vertices (a,b,c), shape (3,), mm."""
+=======
         """Set Tetrahedron vertices (a,b,c), shape (3,), (mm)."""
+>>>>>>> 0ad604af38a3349f58f35e8e8e911c4eb2961e3c
         self._vertices = check_format_input_vector(
             dim,
             dims=(2,),

magpylib/_src/obj_classes/class_magnet_Tetrahedron.py

@@ -38,7 +38,11 @@ class TriangularMesh(BaseMagnet):
         the local object coordinates (rotates with object).
 
     vertices: ndarray, shape (n,3)
+<<<<<<< HEAD
+        A set of points in units of m in the local object coordinates from which the
+=======
         A set of points in units of mm in the local object coordinates from which the
+>>>>>>> 0ad604af38a3349f58f35e8e8e911c4eb2961e3c
         triangular faces of the mesh are constructed by the additional `faces`input.
 
     faces: ndarray, shape (n,3)

magpylib/_src/obj_classes/class_magnet_TriangularMesh.py

@@ -43,9 +43,15 @@ class Dipole(BaseSource):
 
     Examples
     --------
+<<<<<<< HEAD
+    `Dipole` objects are magnetic field sources. In this example we compute the H-field (kA/m)
+    of such a magnetic dipole with a moment of (100,100,100) mT*mm^2 at an observer position
+    (1,1,1) given in units of mm:
+=======
     `Dipole` objects are magnetic field sources. In this example we compute the H-field kA/m
     of such a magnetic dipole with a moment of (100,100,100) in units of mT*mm^2 at an
     observer position (1,1,1) given in units of mm:
+>>>>>>> 0ad604af38a3349f58f35e8e8e911c4eb2961e3c
 
     >>> import magpylib as magpy
     >>> src = magpy.misc.Dipole(moment=(100,100,100))

magpylib/_src/obj_classes/class_misc_Dipole.py

@@ -55,8 +55,13 @@ class Triangle(BaseMagnet):
 
     Examples
     --------
+<<<<<<< HEAD
+    `Triangle` objects are magnetic field sources. Below we compute the H-field (kA/m) of a
+    Triangle object with magnetization (100,200,300) in units of mT dimensions defined
+=======
     `Triangle` objects are magnetic field sources. Below we compute the H-field in kA/m of a
     Triangle object with magnetization (100,200,300) in units of mT, dimensions defined
+>>>>>>> 0ad604af38a3349f58f35e8e8e911c4eb2961e3c
     through the vertices (0,0,0), (1,0,0) and (0,1,0) in units of mm at the
     observer position (1,1,1) given in units of mm:
 
@@ -118,7 +123,11 @@ def vertices(self):
 
     @vertices.setter
     def vertices(self, val):
+<<<<<<< HEAD
+        """Set face vertices (a,b,c), shape (3,3), (mm)."""
+=======
         """Set face vertices (a,b,c), shape (3,3), mm."""
+>>>>>>> 0ad604af38a3349f58f35e8e8e911c4eb2961e3c
         self._vertices = check_format_input_vector(
             val,
             dims=(2,),