adding dipole_moment property

magpylib · OrtnerMichael · Sep 24, 2025 · Jul 21, 2025 · Jul 21, 2025 · Jul 21, 2025
commit 7c969fea59058de83352cdc01195c755e6069706
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,6 +1,6 @@
 # Changelog
 
-## [Unreleased] - YYYY-MM-DD
+## [5.2.0] - 2024-MM-DD
 
 - Documentation update ([#876](https://github.com/magpylib/magpylib/issues/876))
 - Adding force computation `magpylib.getFT()` to the library.
@@ -10,11 +10,15 @@
 - Added the `current_sheet_Hfield` core computation function, and the classes
   `TriangleStrip` and `TriangleSheet` enabling current sheets in the object
   oriented interface. ([#788](https://github.com/magpylib/magpylib/issues/788))
-- Adding the `centroid` property to all Magpylib objects. This gives the same as
-  the `barycenter` property for the objects that have it.
-  ([#864](https://github.com/magpylib/magpylib/issues/864))
-- Adding the `volume` property to all Magpylib objects
-  ([#864](https://github.com/magpylib/magpylib/issues/864))
+- Adding new objects properties
+  - `centroid`: computes and returns object centroid. Gives the same as
+    `barycenter` for the objects that have it.
+    ([#864](https://github.com/magpylib/magpylib/issues/864))
+  - `volume` computes and returns magnet volumes
+    ([#864](https://github.com/magpylib/magpylib/issues/864))
+  - `dipole_moment` computes and returns object dipole moment (magnets and
+    closed currents only)
+    ([#886](https://github.com/magpylib/magpylib/issues/886))
 - 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.

diff --git a/src/magpylib/_src/obj_classes/class_BaseGeo.py b/src/magpylib/_src/obj_classes/class_BaseGeo.py
@@ -49,6 +49,7 @@ class BaseGeo(BaseTransform, ABC):
     - orientation
     - volume
     - centroid
+    - moment
     - style
 
     Methods of BaseGeo
@@ -181,6 +182,19 @@ def _get_centroid(self, squeeze=True):
             Centroid coordinates [(x, y, z), ...] in m.
         """
 
+    @abstractmethod
+    def _get_dipole_moment(self):
+        """
+        Calculate and return the magnetic moment of the object in units Am² in the local object coordinates.
+
+        This method must be implemented by all subclasses.
+
+        Returns
+        -------
+        numpy.ndarray, shape (n,3) when there is a path, or squeeze(1,3) when not
+            Centroid coordinates [(x, y, z), ...] in m.
+        """
+
     # properties ----------------------------------------------------
     @property
     def parent(self):
@@ -304,6 +318,11 @@ def _centroid(self):
         """Centroid of object in units of m."""
         return self._get_centroid(squeeze=False)
 
+    @property
+    def dipole_moment(self):
+        """Magnetic moment of object in units of Am²."""
+        return self._get_dipole_moment()
+
     @property
     def style(self):
         """

diff --git a/src/magpylib/_src/obj_classes/class_Collection.py b/src/magpylib/_src/obj_classes/class_Collection.py
@@ -886,6 +886,10 @@ class Collection(BaseGeo, BaseCollection):
         Read-only. Collection centroid in units of m computed via the volume-weighted average of
         all child centroids.
 
+    dipole_moment: np.ndarray, shape (3,)
+        Read-only. Total Collection dipole moment in units of A*m² computes from the sum of all
+        child dipole moments.
+
     override_parent: bool, default=False
         If False thrown an error when an attempt is made to add an object that
         has already a parent to a Collection. If True, allow adding the object
@@ -988,7 +992,7 @@ def __init__(
     # Abstract methods implementation
     def _get_volume(self):
         """Volume of all objects in units of m³."""
-        return sum(child.volume for child in self.children_all)
+        return sum([child.volume for child in self.children_all])  # pylint: disable=consider-using-generator
 
     def _get_centroid(self):
         """Centroid of collection weighted by children volumes in units of m."""
@@ -1005,3 +1009,7 @@ def _get_centroid(self):
         if total_volume > 0:
             return weighted_centroid / total_volume
         return self.position
+
+    def _get_dipole_moment(self):
+        """Magnetic moment of object in units Am²."""
+        return np.sum([child.dipole_moment for child in self.children_all], axis=0)
diff --git a/src/magpylib/_src/obj_classes/class_Sensor.py b/src/magpylib/_src/obj_classes/class_Sensor.py
@@ -531,6 +531,10 @@ def _get_volume(self):
         """Volume of object in units of m³."""
         return 0.0
 
+    def _get_dipole_moment(self):
+        """Magnetic moment of object in units Am²."""
+        return np.zeros(3)
+
     def _get_centroid(self):
         """Centroid of object in units of m."""
         if self.pixel is not None:

diff --git a/src/magpylib/_src/obj_classes/class_current_Circle.py b/src/magpylib/_src/obj_classes/class_current_Circle.py
@@ -3,6 +3,8 @@
 import warnings
 from typing import ClassVar
 
+import numpy as np
+
 from magpylib._src.display.traces_core import make_Circle
 from magpylib._src.exceptions import MagpylibDeprecationWarning
 from magpylib._src.fields.field_BH_circle import BHJM_circle
@@ -53,6 +55,9 @@ class Circle(BaseCurrent, BaseTarget):
     centroid: np.ndarray, shape (3,) or (m,3)
         Read-only. Object centroid in units of m.
 
+    dipole_moment: np.ndarray, shape (3,)
+        Read-only. Object dipole moment in units of A*m² in the local object coordinates.
+
     parent: `Collection` object or `None`
         The object is a child of it's parent collection.
 
@@ -139,6 +144,14 @@ def _get_centroid(self, squeeze=True):
             return self.position
         return self._position
 
+    def _get_dipole_moment(self):
+        """Magnetic moment of object in units Am²."""
+        # test init
+        if self.diameter is None or self.current is None:
+            return np.array((0.0, 0.0, 0.0))
+
+        return self.diameter**2 / 4 * np.pi * self.current * np.array((0, 0, 1))
+
     def _generate_mesh(self):
         """Generate mesh for force computation."""
         return target_mesh_circle(self.diameter / 2, self.meshing, self.current)

diff --git a/src/magpylib/_src/obj_classes/class_current_Polyline.py b/src/magpylib/_src/obj_classes/class_current_Polyline.py
@@ -59,6 +59,9 @@ class Polyline(BaseCurrent, BaseTarget):
     centroid: np.ndarray, shape (3,) or (m,3)
         Read-only. Object centroid in units of m - set to mean of vertices for this class.
 
+    dipole_moment: np.ndarray, shape (3,)
+        Read-only. Object dipole moment in units of A*m² in the local object coordinates.
+
     parent: `Collection` object or `None`
         The object is a child of it's parent collection.
 
@@ -154,6 +157,24 @@ def _get_centroid(self, squeeze=True):
             return np.mean(self.vertices, axis=0) + self._position
         return self._position
 
+    def _get_dipole_moment(self):
+        """Magnetic moment of object in units Am²."""
+        # test init
+        if self.vertices is None or self.current is None:
+            return np.array((0.0, 0.0, 0.0))
+        # test for closed polyline
+        if (len(self.vertices) > 1) and (np.all(self.vertices[0] == self.vertices[-1])):
+            return (
+                self.current
+                / 2
+                * np.sum(np.cross(self.vertices[:-1], self.vertices[1:]), axis=0)
+            )
+        msg = (
+            f"Cannot compute dipole moment of {self}. Dipole moment is only defined for closed "
+            "Polylines (first and last vertex must be identical)."
+        )
+        raise ValueError(msg)
+
     def _generate_mesh(self):
         """Generate mesh for force computation."""
         # Tests in getFT ensure that meshing, dimension and excitation are set

diff --git a/src/magpylib/_src/obj_classes/class_current_TriangleSheet.py b/src/magpylib/_src/obj_classes/class_current_TriangleSheet.py
@@ -4,6 +4,7 @@
 
 from __future__ import annotations
 
+import warnings
 from typing import ClassVar
 
 import numpy as np
@@ -195,6 +196,14 @@ def _get_centroid(self, squeeze=True):
             return np.squeeze(centr)
         return centr
 
+    def _get_dipole_moment(self):
+        """Magnetic moment of object in units Am²."""
+        warnings.warn(
+            "Magnetic moment is not implemented for TriangleSheet. Return 0.",
+            stacklevel=1,
+        )
+        return np.zeros(3)
+
     def _generate_mesh(self):
         """Generate mesh for force computation."""
         return target_mesh_triangle_current(

diff --git a/src/magpylib/_src/obj_classes/class_current_TriangleStrip.py b/src/magpylib/_src/obj_classes/class_current_TriangleStrip.py
@@ -67,6 +67,9 @@ class TriangleStrip(BaseCurrent, BaseTarget):
         Read-only. Object centroid in units of m given by mean of vertices.
         m is the path length.
 
+    dipole_moment: np.ndarray, shape (3,)
+        Read-only. Object dipole moment in units of A*m² in the local object coordinates.
+
     parent: `Collection` object or `None`
         The object is a child of it's parent collection.
 
@@ -158,6 +161,53 @@ def _get_centroid(self, squeeze=True):
             return np.squeeze(centr)
         return centr
 
+    def _get_dipole_moment(self):
+        """Magnetic moment of object in units Am²."""
+        # test init
+        if self.vertices is None or self.current is None:
+            return np.array((0.0, 0.0, 0.0))
+        # test closed
+        if not np.allclose(self.vertices[:2], self.vertices[-2:]):
+            msg = (
+                f"Cannot compute dipole moment of {self}. Dipole moment is only defined for closed "
+                "CurrentStrips (first two and last two vertices must be identical)."
+            )
+            raise ValueError(msg)
+
+        # number of triangles
+        no_tris = len(self.vertices) - 2
+
+        # create triangles
+        trias = np.array([self.vertices[:-2], self.vertices[1:-1], self.vertices[2:]])
+        trias = np.swapaxes(trias, 0, 1)
+
+        centroids = np.array([(t[0] + t[1] + t[2]) / 3 for t in trias])
+        areas = 0.5 * np.linalg.norm(
+            np.cross(trias[:, 1] - trias[:, 0], trias[:, 2] - trias[:, 0]), axis=1
+        )
+
+        # create current density input
+        v1 = trias[:, 1] - trias[:, 0]
+        v2 = trias[:, 2] - trias[:, 0]
+        v1v1 = np.sum(v1 * v1, axis=1)
+        v2v2 = np.sum(v2 * v2, axis=1)
+        v1v2 = np.sum(v1 * v2, axis=1)
+
+        curr_densities = np.zeros((no_tris, 3), dtype=float)
+        # catch two times the same vertex in one triangle, and set CD to zero there
+        mask = (v2v2 != 0) * (v1v1 != 0)
+        h = np.sqrt(v1v1[mask] - (v1v2[mask] ** 2 / v2v2[mask]))
+        curr_densities[mask] = (
+            v2[mask]
+            / (
+                np.sqrt(v2v2[mask]) * h / np.repeat(self.current, no_tris, axis=0)[mask]
+            )[:, np.newaxis]
+        )
+        # moment of one triangle: A / 2 * cent x curr_density
+        return np.sum(
+            areas[:, np.newaxis] / 2 * np.cross(centroids, curr_densities), axis=0
+        )
+
     def _generate_mesh(self):
         """Generate mesh for force computation."""
         triangles = np.array(

diff --git a/src/magpylib/_src/obj_classes/class_magnet_Cuboid.py b/src/magpylib/_src/obj_classes/class_magnet_Cuboid.py
@@ -62,6 +62,9 @@ class Cuboid(BaseMagnet, BaseTarget):
     centroid: np.ndarray, shape (3,) or (m,3)
         Read-only. Object centroid in units of m.
 
+    dipole_moment: np.ndarray, shape (3,)
+        Read-only. Object dipole moment in units of A*m² in the local object coordinates.
+
     parent: `Collection` object or `None`
         The object is a child of it's parent collection.
 
@@ -158,6 +161,13 @@ def _get_centroid(self, squeeze=True):
             return self.position
         return self._position
 
+    def _get_dipole_moment(self):
+        """Magnetic moment of object in units Am²."""
+        # test init
+        if self.magnetization is None or self.dimension is None:
+            return np.array((0.0, 0.0, 0.0))
+        return self.magnetization * self.volume
+
     def _generate_mesh(self):
         """Generate mesh for force computation."""
         return target_mesh_cuboid(self.meshing, self.dimension, self.magnetization)

diff --git a/src/magpylib/_src/obj_classes/class_magnet_Cylinder.py b/src/magpylib/_src/obj_classes/class_magnet_Cylinder.py
@@ -59,6 +59,9 @@ class Cylinder(BaseMagnet, BaseTarget):
     centroid: np.ndarray, shape (3,) or (m,3)
         Read-only. Object centroid in units of m.
 
+    dipole_moment: np.ndarray, shape (3,)
+        Read-only. Object dipole moment in units of A*m² in the local object coordinates.
+
     parent: `Collection` object or `None`
         The object is a child of it's parent collection.
 
@@ -157,6 +160,13 @@ def _get_centroid(self, squeeze=True):
             return self.position
         return self._position
 
+    def _get_dipole_moment(self):
+        """Magnetic moment of object in units Am²."""
+        # test init
+        if self.magnetization is None or self.dimension is None:
+            return np.array((0.0, 0.0, 0.0))
+        return self.magnetization * self.volume
+
     def _generate_mesh(self):
         """Generate mesh for force computation."""
         # Tests in getFT ensure that meshing, dimension and excitation are set

diff --git a/src/magpylib/_src/obj_classes/class_magnet_CylinderSegment.py b/src/magpylib/_src/obj_classes/class_magnet_CylinderSegment.py
@@ -65,6 +65,9 @@ class CylinderSegment(BaseMagnet, BaseTarget):
     centroid: np.ndarray, shape (3,) or (m,3)
         Read-only. Object centroid in units of m.
 
+    dipole_moment: np.ndarray, shape (3,)
+        Read-only. Object dipole moment in units of A*m² in the local object coordinates.
+
     parent: `Collection` object or `None`
         The object is a child of it's parent collection.
 
@@ -177,6 +180,13 @@ def _get_centroid(self, squeeze=True):
             return self.barycenter
         return self._barycenter
 
+    def _get_dipole_moment(self):
+        """Magnetic moment of object in units Am²."""
+        # test init
+        if self.magnetization is None or self.dimension is None:
+            return np.array((0.0, 0.0, 0.0))
+        return self.magnetization * self.volume
+
     def _generate_mesh(self):
         """Generate mesh for force computation."""
         # Tests in getFT ensure that meshing, dimension and excitation are set

diff --git a/src/magpylib/_src/obj_classes/class_magnet_Sphere.py b/src/magpylib/_src/obj_classes/class_magnet_Sphere.py
@@ -52,6 +52,9 @@ class Sphere(BaseMagnet):
     centroid: np.ndarray, shape (3,) or (m,3)
         Read-only. Object centroid in units of m.
 
+    dipole_moment: np.ndarray, shape (3,)
+        Read-only. Object dipole moment in units of A*m² in the local object coordinates.
+
     parent: `Collection` object or `None`
         The object is a child of it's parent collection.
 
@@ -143,6 +146,13 @@ def _get_centroid(self, squeeze=True):
             return self.position
         return self._position
 
+    def _get_dipole_moment(self):
+        """Magnetic moment of object in units Am²."""
+        # test init
+        if self.magnetization is None or self.diameter is None:
+            return np.array((0.0, 0.0, 0.0))
+        return self.magnetization * self.volume
+
     def _generate_mesh(self):
         """Generate mesh for force computation."""
         points = np.array([(0, 0, 0)])

diff --git a/src/magpylib/_src/obj_classes/class_magnet_Tetrahedron.py b/src/magpylib/_src/obj_classes/class_magnet_Tetrahedron.py
@@ -61,6 +61,9 @@ class Tetrahedron(BaseMagnet, BaseTarget):
     centroid: np.ndarray, shape (3,) or (m,3)
         Read-only. Object centroid in units of m.
 
+    dipole_moment: np.ndarray, shape (3,)
+        Read-only. Object dipole moment in units of A*m² in the local object coordinates.
+
     parent: `Collection` object or `None`
         The object is a child of it's parent collection.
 
@@ -183,6 +186,13 @@ def _get_centroid(self, squeeze=True):
             return self.barycenter
         return self._barycenter
 
+    def _get_dipole_moment(self):
+        """Magnetic moment of object in units Am²."""
+        # test init
+        if self.magnetization is None or self.vertices is None:
+            return np.array((0.0, 0.0, 0.0))
+        return self.magnetization * self.volume
+
     def _generate_mesh(self):
         """Generate mesh for force computation."""
         return target_mesh_tetrahedron(self.meshing, self.vertices, self.magnetization)