docstrings to SI

magpylib · Alexboiboi · Dec 25, 2023 · Dec 26, 2023 · Dec 26, 2023 · Dec 27, 2023
commit fe2952f6f02df167efd634e5f1f2797280400337
diff --git a/magpylib/_src/obj_classes/class_Sensor.py b/magpylib/_src/obj_classes/class_Sensor.py
@@ -19,7 +19,10 @@ class Sensor(BaseGeo, BaseDisplayRepr):
     When `position=(0,0,0)` and `orientation=None` local object coordinates
     coincide with the global coordinate system.
 
-    A sensor is made up of pixel (sensing elements) where the magnetic field is evaluated.
+    A sensor is made up of pixel (sensing elements / positions) where the magnetic
+    field is evaluated.
+
+    SI units are used for all inputs and outputs.
 
     Parameters
     ----------
@@ -140,7 +143,7 @@ def handedness(self, val):
     def getB(
         self, *sources, sumup=False, squeeze=True, pixel_agg=None, output="ndarray"
     ):
-        """Compute the B-field in units of tesla as seen by the sensor.
+        """Compute the B-field in units of T as seen by the sensor.
 
         Parameters
         ----------
@@ -168,14 +171,14 @@ def getB(
         Returns
         -------
         B-field: ndarray, shape squeeze(l, m, n1, n2, ..., 3) or DataFrame
-            B-field of each source (l) at each path position (m) and each sensor pixel
-            position (n1,n2,...) in units of tesla. Paths of objects that are shorter than
-            m will be considered as static beyond their end.
+            B-field of each source (index l) at each path position (index m) and each sensor pixel
+            position (indices n1,n2,...) in units of T. Paths of objects that are shorter than
+            index m are considered as static beyond their end.
 
         Examples
         --------
         Sensors are observers for magnetic field computation. In this example we compute the
-        B-field in units of tesla as seen by the sensor in the center of a circular current loop:
+        B-field in T as seen by the sensor in the center of a circular current loop:
 
         >>> import magpylib as magpy
         >>> sens = magpy.Sensor()
@@ -243,14 +246,14 @@ def getH(
         Returns
         -------
         H-field: ndarray, shape squeeze(l, m, n1, n2, ..., 3) or DataFrame
-            H-field of each source (l) at each path position (m) and each sensor pixel
-            position (n1,n2,...) in units of A/m. Paths of objects that are shorter than
-            m will be considered as static beyond their end.
+            H-field of each source (index l) at each path position (index m) and each sensor pixel
+            position (indices n1,n2,...) in units of A/m. Paths of objects that are shorter than
+            index m are considered as static beyond their end.
 
         Examples
         --------
         Sensors are observers for magnetic field computation. In this example we compute the
-        B-field in units of tesla as seen by the sensor in the center of a circular current loop:
+        B-field in T as seen by the sensor in the center of a circular current loop:
 
         >>> import magpylib as magpy
         >>> sens = magpy.Sensor()

diff --git a/magpylib/_src/obj_classes/class_current_Polyline.py b/magpylib/_src/obj_classes/class_current_Polyline.py
@@ -10,13 +10,15 @@
 
 
 class Polyline(BaseCurrent):
-    """Current flowing in straight lines from vertex to vertex.
+    """Line current flowing in straight paths from vertex to vertex.
 
     Can be used as `sources` input for magnetic field computation.
 
     The vertex positions are defined in the local object coordinates (rotate with object).
     When `position=(0,0,0)` and `orientation=None` global and local coordinates coincide.
 
+    SI units are used for all inputs and outputs.
+
     Parameters
     ----------
     current: float, default=`None`
@@ -49,7 +51,7 @@ class Polyline(BaseCurrent):
 
     Examples
     --------
-    `Polyline` objects are magnetic field sources. In this example we compute the H-field A/m
+    `Polyline` objects are magnetic field sources. In this example we compute the H-field in A/m
     of a square-shaped line-current with 1 A current at the observer position (1,1,1) given in
     units of meter:
 

diff --git a/magpylib/_src/obj_classes/class_magnet_Cuboid.py b/magpylib/_src/obj_classes/class_magnet_Cuboid.py
@@ -15,12 +15,12 @@ class Cuboid(BaseMagnet):
     to the global coordinate basis vectors and the geometric center of the Cuboid
     is located in the origin.
 
-    Units .... Min = Bout, Jin = Hout, length units arbitrary
+    SI units are used for all inputs and outputs.
 
     Parameters
     ----------
     position: array_like, shape (3,) or (m,3), default=`(0,0,0)`
-        Object position(s) in the global coordinates in meter.
+        Object position(s) in the global coordinates in units of meter.
         For m>1, the `position` and `orientation` attributes together
         represent an object path.
 
@@ -54,8 +54,8 @@ class Cuboid(BaseMagnet):
     Examples
     --------
     `Cuboid` magnets are magnetic field sources. Below we compute the H-field in A/m of a
-    cubical magnet with magnetic polarization of (0.5,0.6,0.7) in units of tesla and 0.01 m sides
-    at the observer position (0.01,0.01,0.01) given in units of meter:
+    cubical magnet with magnetic polarization of (0.5,0.6,0.7) in units of tesla and
+    0.01 meter sides at the observer position (0.01,0.01,0.01) given in units of meter:
 
     >>> import magpylib as magpy
     >>> src = magpy.magnet.Cuboid(polarization=(.5,.6,.7), dimension=(.01,.01,.01))

diff --git a/magpylib/_src/obj_classes/class_magnet_Cylinder.py b/magpylib/_src/obj_classes/class_magnet_Cylinder.py
@@ -15,6 +15,8 @@ class Cylinder(BaseMagnet):
     cylinder lies in the origin of the global coordinate system and
     the cylinder axis coincides with the global z-axis.
 
+    SI units are used for all inputs and outputs.
+
     Parameters
     ----------
     position: array_like, shape (3,) or (m,3), default=`(0,0,0)`

diff --git a/magpylib/_src/obj_classes/class_magnet_CylinderSegment.py b/magpylib/_src/obj_classes/class_magnet_CylinderSegment.py
@@ -20,6 +20,8 @@ class CylinderSegment(BaseMagnet):
     the cylinder axis coincides with the global z-axis. Section angle 0
     corresponds to an x-z plane section of the cylinder.
 
+    SI units are used for all inputs and outputs.
+
     Parameters
     ----------
     position: array_like, shape (3,) or (m,3), default=`(0,0,0)`
@@ -65,8 +67,8 @@ class CylinderSegment(BaseMagnet):
     Examples
     --------
     `CylinderSegment` magnets are magnetic field sources. In this example we compute the
-    H-field A/m of such a cylinder segment magnet with polarization (.1,.2,.3)
-    in units of tesla, inner radius 0.01 meter, outer radius 0.02 m, height 0.01 meter, and
+    H-field in A/m of such a cylinder segment magnet with polarization (.1,.2,.3)
+    in units of tesla, inner radius 0.01 meter, outer radius 0.02 meter, height 0.01 meter, and
     section angles 0 and 45 deg at the observer position (0.02,0.02,0.02) in units of meter:
 
     >>> import magpylib as magpy

diff --git a/magpylib/_src/obj_classes/class_magnet_Sphere.py b/magpylib/_src/obj_classes/class_magnet_Sphere.py
@@ -14,6 +14,8 @@ class Sphere(BaseMagnet):
     When `position=(0,0,0)` and `orientation=None` the sphere center is located
     in the origin of the global coordinate system.
 
+    SI units are used for all inputs and outputs.
+
     Parameters
     ----------
     position: array_like, shape (3,) or (m,3), default=`(0,0,0)`
@@ -50,7 +52,7 @@ class Sphere(BaseMagnet):
 
     Examples
     --------
-    `Sphere` objects are magnetic field sources. In this example we compute the H-field A/m
+    `Sphere` objects are magnetic field sources. In this example we compute the H-field in A/m
     of a spherical magnet with polarization (0.1,0.2,0.3) in units of tesla and diameter
     of 0.01 meter at the observer position (0.01,0.01,0.01) given in units of meter:
 

diff --git a/magpylib/_src/obj_classes/class_magnet_Tetrahedron.py b/magpylib/_src/obj_classes/class_magnet_Tetrahedron.py
@@ -17,6 +17,8 @@ class Tetrahedron(BaseMagnet):
     is determined by its vertices and. It is not necessarily located in the origin an can
     be computed with the barycenter property.
 
+    SI units are used for all inputs and outputs.
+
     Parameters
     ----------
     position: array_like, shape (3,) or (m,3)

diff --git a/magpylib/_src/obj_classes/class_magnet_TriangularMesh.py b/magpylib/_src/obj_classes/class_magnet_TriangularMesh.py
@@ -28,9 +28,12 @@
 class TriangularMesh(BaseMagnet):
     """Magnet with homogeneous magnetization defined by triangular surface mesh.
     Can be used as `sources` input for magnetic field computation.
+
     When `position=(0,0,0)` and `orientation=None` the TriangularMesh vertices
     are the same as in the global coordinate system.
 
+    SI units are used for all inputs and outputs.
+
     Parameters
     ----------
     position: array_like, shape (3,) or (m,3), default=`(0,0,0)`
@@ -99,8 +102,8 @@ class TriangularMesh(BaseMagnet):
 
     Examples
     --------
-    We compute the B-field in units of tesla of a triangular mesh (4 vertices, 4 faces)
-    with polarization (0.1,0.2,0.3) in units of tesla at the observer position
+    We compute the B-field in units of T of a triangular mesh (4 vertices, 4 faces)
+    with polarization (0.1,0.2,0.3) in units of T at the observer position
     (0.01,0.01,0.01) given in units of meter:
 
     >>> import magpylib as magpy
@@ -538,6 +541,8 @@ def from_ConvexHull(
     ):
         """Create a TriangularMesh magnet from a point cloud via its convex hull.
 
+        SI units are used for all inputs and outputs.
+
         Parameters
         ----------
         position: array_like, shape (3,) or (m,3)
@@ -629,6 +634,8 @@ def from_pyvista(
     ):
         """Create a TriangularMesh magnet from a pyvista PolyData mesh object.
 
+        SI units are used for all inputs and outputs.
+
         Parameters
         ----------
         position: array_like, shape (3,) or (m,3)
@@ -737,6 +744,8 @@ def from_triangles(
     ):
         """Create a TriangularMesh magnet from a list or Collection of Triangle objects.
 
+        SI units are used for all inputs and outputs.
+
         Parameters
         ----------
         position: array_like, shape (3,) or (m,3)
@@ -843,6 +852,8 @@ def from_mesh(
     ):
         """Create a TriangularMesh magnet from a mesh input.
 
+        SI units are used for all inputs and outputs.
+
         Parameters
         ----------
         position: array_like, shape (3,) or (m,3)

diff --git a/magpylib/_src/obj_classes/class_misc_CustomSource.py b/magpylib/_src/obj_classes/class_misc_CustomSource.py
@@ -10,12 +10,14 @@ class CustomSource(BaseSource):
     When `position=(0,0,0)` and `orientation=None` local object coordinates
     coincide with the global coordinate system.
 
+    SI units are used for all inputs and outputs.
+
     Parameters
     ----------
     field_func: callable, default=`None`
         The function for B- and H-field computation must have the two positional arguments
         `field` and `observers`. With `field='B'` or `field='H'` the B- or H-field in units
-        of  or A/m must be returned respectively. The `observers` argument must
+        of T or A/m must be returned respectively. The `observers` argument must
         accept numpy ndarray inputs of shape (n,3), in which case the returned fields must
         be numpy ndarrays of shape (n,3) themselves.
 
@@ -44,7 +46,7 @@ class CustomSource(BaseSource):
     With version 4 `CustomSource` objects enable users to define their own source
     objects, and to embedded them in the Magpylib object oriented interface. In this example
     we create a source that generates a constant field and evaluate the field at observer
-    position (0.01,0.01,0.01) given in meter:
+    position (0.01,0.01,0.01) given in meters:
 
     >>> import numpy as np
     >>> import magpylib as magpy

diff --git a/magpylib/_src/obj_classes/class_misc_Dipole.py b/magpylib/_src/obj_classes/class_misc_Dipole.py
@@ -17,6 +17,8 @@ class Dipole(BaseSource):
     When `position=(0,0,0)` and `orientation=None` the dipole is located in the origin of
     global coordinate system.
 
+    SI units are used for all inputs and outputs.
+
     Parameters
     ----------
     position: array_like, shape (3,) or (m,3), default=`(0,0,0)`
@@ -30,8 +32,8 @@ class Dipole(BaseSource):
 
     moment: array_like, shape (3,), unit A・m², default=`None`
         Magnetic dipole moment in units of A・m² given in the local object coordinates.
-        For homogeneous magnets the relation moment=magnetization*volume holds. The dipole
-        moment of a Circle object is pi**2/10*diameter**2*current.
+        For homogeneous magnets the relation moment=magnetization*volume holds. For
+        current loops the relation moment = current*loop_surface holds.
 
     parent: `Collection` object or `None`
         The object is a child of it's parent collection.
@@ -46,7 +48,7 @@ class Dipole(BaseSource):
 
     Examples
     --------
-    `Dipole` objects are magnetic field sources. In this example we compute the H-field A/m
+    `Dipole` objects are magnetic field sources. In this example we compute the H-field in A/m
     of such a magnetic dipole with a moment of (100,100,100) in units of A・m² at an
     observer position (.01,.01,.01) given in units of meter:
 

diff --git a/magpylib/_src/obj_classes/class_misc_Triangle.py b/magpylib/_src/obj_classes/class_misc_Triangle.py
@@ -18,6 +18,8 @@ class Triangle(BaseMagnet):
     Triangle vertices coincide with the global coordinate system. The geometric
     center of the Triangle is determined by its vertices.
 
+    SI units are used for all inputs and outputs.
+
     Parameters
     ----------
     position: array_like, shape (3,) or (m,3)