nmag-python-3 0.0.2__py3-none-any.whl

nmag/simulation/demag/fem/assembly.py

@@ -0,0 +1,114 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+import numpy as np
+
+from ....backends import (
+    _load_rust_accelerator,
+    _selected_demag_fem_assembly_backend,
+)
+from ...support import _simulation_compatibility_binding
+from .charges import volume_charge_scaling_correction
+
+
+class SimulationDemagFemAssemblyMixin:
+    if TYPE_CHECKING:
+
+        def __getattr__(self, name: str) -> Any: ...
+
+    def _assemble_demag_fem_system(
+        self,
+        points: np.ndarray,
+        simplices: np.ndarray,
+        m: np.ndarray,
+        ms_values: np.ndarray,
+        volume_charge_scales: np.ndarray,
+    ) -> tuple[Any, np.ndarray, np.ndarray]:
+        point_count = len(points)
+        stiffness, gradients_by_cell, volumes = self._demag_fem_geometry_for_mesh(
+            points,
+            simplices,
+        )
+        assembly_backend = _selected_demag_fem_assembly_backend(
+            len(simplices), getattr(self, "config", None)
+        )
+        with self._record_active_subfield_array_timing_block(
+            f"demag_auxiliary:assemble_fem:divergence:{assembly_backend}",
+        ):
+            if assembly_backend == "rust":
+                divergence = self._assemble_demag_fem_divergence_rust(
+                    simplices,
+                    gradients_by_cell,
+                    volumes,
+                    m,
+                    ms_values,
+                    point_count,
+                )
+            else:
+                divergence = self._assemble_demag_fem_divergence_python(
+                    simplices,
+                    gradients_by_cell,
+                    volumes,
+                    m,
+                    ms_values,
+                    point_count,
+                )
+            divergence += volume_charge_scaling_correction(
+                simplices,
+                gradients_by_cell,
+                volumes,
+                m,
+                ms_values,
+                volume_charge_scales,
+                point_count,
+            )
+        return stiffness, divergence, volumes
+
+    def _assemble_demag_fem_divergence_python(
+        self,
+        simplices: np.ndarray,
+        gradients_by_cell: np.ndarray,
+        volumes: np.ndarray,
+        m: np.ndarray,
+        ms_values: np.ndarray,
+        point_count: int,
+    ) -> np.ndarray:
+        divergence = np.zeros(point_count, dtype=float)
+        if len(simplices) == 0:
+            return divergence
+
+        cell_m = m[simplices] * ms_values[:, np.newaxis, np.newaxis]
+        average_m = np.mean(cell_m, axis=1)
+        cell_divergence = volumes[:, np.newaxis] * np.einsum(
+            "cij,cj->ci",
+            gradients_by_cell,
+            average_m,
+        )
+        np.add.at(divergence, simplices, cell_divergence)
+        return divergence
+
+    def _assemble_demag_fem_divergence_rust(
+        self,
+        simplices: np.ndarray,
+        gradients_by_cell: np.ndarray,
+        volumes: np.ndarray,
+        m: np.ndarray,
+        ms_values: np.ndarray,
+        point_count: int,
+    ) -> np.ndarray:
+        rust_accel = _simulation_compatibility_binding(
+            "_load_rust_accelerator",
+            _load_rust_accelerator,
+        )("NmagConfig.accelerator['fem_assembly']")
+        return np.asarray(
+            rust_accel.build_demag_fem_divergence(
+                np.asarray(simplices, dtype=np.int64),
+                np.asarray(gradients_by_cell, dtype=np.float64),
+                np.asarray(volumes, dtype=np.float64),
+                np.asarray(m, dtype=np.float64),
+                np.asarray(ms_values, dtype=np.float64),
+                int(point_count),
+            ),
+            dtype=float,
+        )

nmag/simulation/demag/fem/charges.py

@@ -0,0 +1,38 @@
+"""Finite-element separation of demagnetization volume charges."""
+
+from __future__ import annotations
+
+import numpy as np
+
+
+def volume_charge_scaling_correction(
+    simplices: np.ndarray,
+    gradients_by_cell: np.ndarray,
+    volumes: np.ndarray,
+    m: np.ndarray,
+    ms_values: np.ndarray,
+    volume_charge_scales: np.ndarray,
+    point_count: int,
+) -> np.ndarray:
+    """Return the weak-source correction for material volume-charge scales.
+
+    The standard FEM assembly is the combined surface and volume source
+    ``integral(grad(test) . M)``. Integration by parts identifies the volume
+    part on a linear tetrahedron as ``-volume * div(M) / 4`` at every local
+    node. Scaling that term separately preserves the unscaled surface charge.
+    """
+    correction = np.zeros(point_count, dtype=float)
+    if len(simplices) == 0 or np.all(volume_charge_scales == 1.0):
+        return correction
+
+    cell_m = m[simplices] * ms_values[:, np.newaxis, np.newaxis]
+    cell_divergence = np.einsum("cij,cij->c", gradients_by_cell, cell_m)
+    local_correction = (
+        -(volume_charge_scales - 1.0) * volumes * cell_divergence / simplices.shape[1]
+    )
+    np.add.at(
+        correction,
+        simplices,
+        np.broadcast_to(local_correction[:, np.newaxis], simplices.shape),
+    )
+    return correction

nmag/simulation/demag/fem/geometry.py

@@ -0,0 +1,261 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+import numpy as np
+
+from ....backends import (
+    _load_rust_accelerator,
+    _selected_demag_boundary_face_backend,
+    _selected_demag_fem_geometry_backend,
+    _selected_demag_fem_matrix_backend,
+)
+from ....demag import (
+    _oriented_boundary_faces,
+    _validate_dense_demag_size,
+    _validate_tetrahedral_cells,
+)
+from ...support import _simulation_compatibility_binding
+
+
+class SimulationDemagFemGeometryMixin:
+    if TYPE_CHECKING:
+        _demag_fem_geometry_cache: Any | None
+        _demag_boundary_faces_cache: Any | None
+
+        def __getattr__(self, name: str) -> Any: ...
+
+    def _demag_fem_geometry_for_mesh(
+        self,
+        points: np.ndarray,
+        simplices: np.ndarray,
+    ) -> tuple[Any, np.ndarray, np.ndarray]:
+        token = self._mesh_geometry_token()
+        self._ensure_demag_geometry_cache_token(token)
+        matrix_backend = _selected_demag_fem_matrix_backend(len(points))
+        if self._demag_fem_geometry_cache is not None:
+            cached_backend, stiffness, gradients, volumes = self._demag_fem_geometry_cache
+            if cached_backend == matrix_backend:
+                return stiffness, gradients, volumes
+
+        if matrix_backend == "sparse":
+            stiffness, gradients, volumes = self._demag_fem_geometry_for_mesh_sparse(
+                points,
+                simplices,
+            )
+            self._demag_fem_geometry_cache = (
+                matrix_backend,
+                stiffness,
+                gradients,
+                volumes,
+            )
+            return stiffness, gradients, volumes
+
+        backend = _selected_demag_fem_geometry_backend(
+            len(simplices), getattr(self, "config", None)
+        )
+        with self._record_active_subfield_array_timing_block(
+            f"demag_auxiliary:assemble_fem:geometry:{backend}",
+        ):
+            if backend == "rust":
+                geometry = self._demag_fem_geometry_for_mesh_rust(
+                    points,
+                    simplices,
+                )
+            else:
+                geometry = self._demag_fem_geometry_for_mesh_python(
+                    points,
+                    simplices,
+                )
+        stiffness, gradients, volumes = geometry
+        self._demag_fem_geometry_cache = (matrix_backend, stiffness, gradients, volumes)
+        return stiffness, gradients, volumes
+
+    def _demag_fem_geometry_for_mesh_sparse(
+        self,
+        points: np.ndarray,
+        simplices: np.ndarray,
+    ) -> tuple[Any, np.ndarray, np.ndarray]:
+        from scipy import sparse
+
+        _validate_tetrahedral_cells(points, simplices)
+        point_count = len(points)
+        if len(simplices) == 0:
+            return (
+                sparse.csr_matrix((point_count, point_count), dtype=float),
+                np.empty((0, 4, 3), dtype=float),
+                np.empty(0, dtype=float),
+            )
+
+        cell_points = points[simplices]
+        matrices = np.concatenate(
+            [np.ones((len(simplices), 4, 1), dtype=float), cell_points],
+            axis=2,
+        )
+        inverses = np.linalg.inv(matrices)
+        gradients = np.transpose(inverses[:, 1:, :], (0, 2, 1))
+        volumes = np.abs(np.linalg.det(cell_points[:, 1:] - cell_points[:, [0]])) / 6.0
+        local_stiffness = volumes[:, np.newaxis, np.newaxis] * np.einsum(
+            "cik,cjk->cij",
+            gradients,
+            gradients,
+        )
+        rows = np.broadcast_to(simplices[:, :, np.newaxis], local_stiffness.shape).ravel()
+        columns = np.broadcast_to(simplices[:, np.newaxis, :], local_stiffness.shape).ravel()
+        stiffness = sparse.coo_matrix(
+            (local_stiffness.ravel(), (rows, columns)),
+            shape=(point_count, point_count),
+        ).tocsr()
+        stiffness.sum_duplicates()
+        return stiffness, gradients, volumes
+
+    def _demag_fem_geometry_for_mesh_python(
+        self,
+        points: np.ndarray,
+        simplices: np.ndarray,
+    ) -> tuple[np.ndarray, np.ndarray, np.ndarray]:
+        point_count = len(points)
+        _validate_dense_demag_size(point_count)
+        _validate_tetrahedral_cells(points, simplices)
+        stiffness = np.zeros((point_count, point_count), dtype=float)
+        gradients_by_cell = np.zeros((len(simplices), 4, 3), dtype=float)
+        volumes = np.zeros(len(simplices), dtype=float)
+
+        if len(simplices) == 0:
+            return stiffness, gradients_by_cell, volumes
+
+        cell_points = points[simplices]
+        matrices = np.concatenate(
+            [
+                np.ones((len(simplices), 4, 1), dtype=float),
+                cell_points,
+            ],
+            axis=2,
+        )
+        try:
+            inverses = np.linalg.inv(matrices)
+        except np.linalg.LinAlgError:
+            return self._demag_fem_geometry_for_mesh_loop(
+                points,
+                simplices,
+                stiffness,
+                gradients_by_cell,
+                volumes,
+            )
+
+        gradients_by_cell[:] = np.transpose(inverses[:, 1:, :], (0, 2, 1))
+        volumes[:] = np.abs(np.linalg.det(cell_points[:, 1:] - cell_points[:, [0]])) / 6.0
+        positive = volumes > 0.0
+        if np.any(positive):
+            local_stiffness = volumes[positive, np.newaxis, np.newaxis] * np.einsum(
+                "cik,cjk->cij",
+                gradients_by_cell[positive],
+                gradients_by_cell[positive],
+            )
+            positive_simplices = simplices[positive]
+            np.add.at(
+                stiffness,
+                (
+                    positive_simplices[:, :, np.newaxis],
+                    positive_simplices[:, np.newaxis, :],
+                ),
+                local_stiffness,
+            )
+
+        return stiffness, gradients_by_cell, volumes
+
+    def _demag_fem_geometry_for_mesh_rust(
+        self,
+        points: np.ndarray,
+        simplices: np.ndarray,
+    ) -> tuple[np.ndarray, np.ndarray, np.ndarray]:
+        _validate_dense_demag_size(len(points))
+        _validate_tetrahedral_cells(points, simplices)
+        rust_accel = _simulation_compatibility_binding(
+            "_load_rust_accelerator",
+            _load_rust_accelerator,
+        )("NmagConfig.accelerator['fem_geometry']")
+        stiffness, gradients_by_cell, volumes = rust_accel.build_demag_fem_geometry(
+            np.asarray(points, dtype=np.float64),
+            np.asarray(simplices, dtype=np.int64),
+        )
+        return (
+            np.asarray(stiffness, dtype=float),
+            np.asarray(gradients_by_cell, dtype=float),
+            np.asarray(volumes, dtype=float),
+        )
+
+    def _demag_fem_geometry_for_mesh_loop(
+        self,
+        points: np.ndarray,
+        simplices: np.ndarray,
+        stiffness: np.ndarray,
+        gradients_by_cell: np.ndarray,
+        volumes: np.ndarray,
+    ) -> tuple[np.ndarray, np.ndarray, np.ndarray]:
+        for cell_index, simplex in enumerate(simplices):
+            cell_points = points[simplex]
+            matrix = np.column_stack([np.ones(4), cell_points])
+            try:
+                inverse = np.asarray(np.linalg.inv(matrix), dtype=float)
+            except np.linalg.LinAlgError as error:
+                raise ValueError(f"Demag FEM cell {cell_index} is singular.") from error
+            gradients = np.transpose(inverse[1:, :])
+            volume = abs(float(np.linalg.det(cell_points[1:] - cell_points[[0]]))) / 6.0
+            if volume <= 0.0:
+                raise ValueError(f"Demag FEM cell {cell_index} has zero volume.")
+            volumes[cell_index] = volume
+            gradients_by_cell[cell_index] = gradients
+            stiffness[np.ix_(simplex, simplex)] += volume * (gradients @ np.transpose(gradients))
+
+        return stiffness, gradients_by_cell, volumes
+
+    def _boundary_faces_for_demag_mesh(
+        self,
+        points: np.ndarray,
+        simplices: np.ndarray,
+    ) -> list[tuple[int, tuple[int, int, int]]]:
+        token = self._mesh_geometry_token()
+        self._ensure_demag_geometry_cache_token(token)
+        if self._demag_boundary_faces_cache is not None:
+            return self._demag_boundary_faces_cache
+
+        backend = _selected_demag_boundary_face_backend(getattr(self, "config", None))
+        with self._record_active_subfield_array_timing_block(
+            f"demag_auxiliary:boundary_faces:{backend}",
+        ):
+            if backend == "rust":
+                boundary_faces = self._boundary_faces_for_demag_mesh_rust(
+                    points,
+                    simplices,
+                )
+            else:
+                boundary_faces = _simulation_compatibility_binding(
+                    "_oriented_boundary_faces",
+                    _oriented_boundary_faces,
+                )(points, simplices)
+        self._demag_boundary_faces_cache = boundary_faces
+        self._demag_bem_cache = None
+        self._last_bem_operator_stats = None
+        return boundary_faces
+
+    def _boundary_faces_for_demag_mesh_rust(
+        self,
+        points: np.ndarray,
+        simplices: np.ndarray,
+    ) -> list[tuple[int, tuple[int, int, int]]]:
+        rust_accel = _simulation_compatibility_binding(
+            "_load_rust_accelerator",
+            _load_rust_accelerator,
+        )("NmagConfig.accelerator['boundary_faces']")
+        owners, faces = rust_accel.build_oriented_boundary_faces(
+            np.asarray(points, dtype=np.float64),
+            np.asarray(simplices, dtype=np.int64),
+        )
+        owner_array = np.asarray(owners, dtype=int).flatten()
+        face_values = np.asarray(faces, dtype=int).flatten()
+        face_array = np.column_stack((face_values[0::3], face_values[1::3], face_values[2::3]))
+        return [
+            (int(owner), (int(face[0]), int(face[1]), int(face[2])))
+            for owner, face in zip(owner_array, face_array, strict=True)
+        ]

nmag/simulation/demag/fields/__init__.py

@@ -0,0 +1,11 @@
+"""Demag field compatibility façade composed from recovery and auxiliary mixins."""
+
+from .auxiliary import SimulationDemagAuxiliaryMixin
+from .recovery import SimulationDemagRecoveryMixin
+
+
+class SimulationDemagFieldsMixin(
+    SimulationDemagRecoveryMixin,
+    SimulationDemagAuxiliaryMixin,
+):
+    """Provide recovered demag fields and FEM/BEM scalar-potential solves."""

nmag/simulation/demag/fields/auxiliary.py

@@ -0,0 +1,186 @@
+from __future__ import annotations
+
+import time
+from typing import TYPE_CHECKING, Any
+
+import numpy as np
+
+from ....backends import (
+    _demag_internal_trace_enabled,
+    _selected_demag_linear_solver_backend,
+)
+from ....demag import _demag_solve_diagnostics, _solve_gauge_fixed
+from ....demag.linear import _factorize_gauge_fixed, _is_sparse_matrix, _solve_sparse_gauge_fixed
+from ...support import LEGACY_RHO_BOXED_VOLUME_M3
+
+
+class SimulationDemagAuxiliaryMixin:
+    if TYPE_CHECKING:
+        _demag_phi_cache: Any | None
+        _demag_rho_cache: Any | None
+        _demag_volumes_cache: Any | None
+        _demag_gauge_factorization_cache: Any | None
+
+        def __getattr__(self, name: str) -> Any: ...
+
+    def _get_demag_auxiliary_fields(self) -> tuple[np.ndarray, np.ndarray, np.ndarray]:
+        cache_started = time.perf_counter()
+        token = self._demag_token()
+        if (
+            self._demag_aux_cache_token == token
+            and self._demag_phi_cache is not None
+            and self._demag_rho_cache is not None
+            and self._demag_volumes_cache is not None
+        ):
+            self._record_active_subfield_array_timing(
+                "demag_auxiliary:cache_hit",
+                time.perf_counter() - cache_started,
+            )
+            return self._demag_phi_cache, self._demag_rho_cache, self._demag_volumes_cache
+
+        with self._record_active_subfield_array_timing_block(
+            "demag_auxiliary:mesh_inputs",
+        ):
+            points = self._mesh_points()
+            simplices = np.asarray(self._require_mesh().simplices, dtype=int)
+        if simplices.size == 0:
+            phi = np.zeros(len(points), dtype=float)
+            rho = np.zeros(len(points), dtype=float)
+            volumes = np.zeros(0, dtype=float)
+        else:
+            if simplices.ndim != 2 or simplices.shape[1] != 4:
+                raise NotImplementedError("The demag MVP currently supports tetrahedral 3D meshes.")
+            with self._record_active_subfield_array_timing_block(
+                "demag_auxiliary:boundary_faces",
+            ):
+                boundary_faces = self._boundary_faces_for_demag_mesh(points, simplices)
+            if not boundary_faces:
+                phi = np.zeros(len(points), dtype=float)
+                rho = np.zeros(len(points), dtype=float)
+                volumes = np.zeros(len(simplices), dtype=float)
+            else:
+                with self._record_active_subfield_array_timing_block(
+                    "demag_auxiliary:material_inputs",
+                ):
+                    m = np.asarray(self._fields["m"], dtype=float)
+                    regions = list(self._require_mesh().regions or [1] * len(simplices))
+                    ms_values = self._simplex_material_ms_values(regions)
+                    volume_charge_scales = self._simplex_volume_charge_scales(regions)
+                with self._record_active_subfield_array_timing_block(
+                    "demag_auxiliary:fem_bem_total",
+                ):
+                    phi, rho, volumes = self._fem_bem_auxiliary_at_nodes(
+                        points,
+                        simplices,
+                        boundary_faces,
+                        m,
+                        ms_values,
+                        volume_charge_scales,
+                    )
+
+        self._demag_aux_cache_token = token
+        self._demag_phi_cache = phi
+        self._demag_rho_cache = rho
+        self._demag_volumes_cache = volumes
+        return phi, rho, volumes
+
+    def _fem_bem_auxiliary_at_nodes(
+        self,
+        points: np.ndarray,
+        simplices: np.ndarray,
+        boundary_faces: list[tuple[int, tuple[int, int, int]]],
+        m: np.ndarray,
+        ms_values: np.ndarray,
+        volume_charge_scales: np.ndarray,
+    ) -> tuple[np.ndarray, np.ndarray, np.ndarray]:
+        with self._record_active_subfield_array_timing_block(
+            "demag_auxiliary:assemble_fem",
+        ):
+            stiffness, divergence, volumes = self._assemble_demag_fem_system(
+                points,
+                simplices,
+                m,
+                ms_values,
+                volume_charge_scales,
+            )
+        with self._record_active_subfield_array_timing_block("demag_auxiliary:rho_box"):
+            rho = self._scalar_cofield_to_legacy_boxed_field(
+                divergence,
+                len(points),
+            )
+        with self._record_active_subfield_array_timing_block(
+            "demag_auxiliary:gauge_solve",
+        ):
+            if _is_sparse_matrix(stiffness):
+                phi1 = _solve_sparse_gauge_fixed(
+                    stiffness,
+                    divergence,
+                    record_timing=self._record_active_subfield_array_timing,
+                    timing_prefix="demag_auxiliary:gauge_solve",
+                )
+            elif _selected_demag_linear_solver_backend(stiffness.shape[0]) == "scipy":
+                if self._demag_gauge_factorization_cache is None:
+                    self._demag_gauge_factorization_cache = _factorize_gauge_fixed(stiffness)
+                augmented_rhs = np.concatenate([divergence, [0.0]])
+                phi1 = self._demag_gauge_factorization_cache.solve(augmented_rhs)[:-1]
+            else:
+                phi1 = _solve_gauge_fixed(
+                    stiffness,
+                    divergence,
+                    record_timing=self._record_active_subfield_array_timing,
+                    timing_prefix="demag_auxiliary:gauge_solve",
+                )
+        with self._record_active_subfield_array_timing_block(
+            "demag_auxiliary:lindholm_bem",
+        ):
+            boundary_nodes, bem = self._lindholm_bem_for_demag_mesh(
+                points,
+                simplices,
+                boundary_faces,
+            )
+        phi2 = np.zeros(len(points), dtype=float)
+        phi2_boundary = np.zeros(len(boundary_nodes), dtype=float)
+        if len(boundary_nodes) > 0:
+            with self._record_active_subfield_array_timing_block(
+                "demag_auxiliary:bem_multiply",
+            ):
+                phi2_boundary = bem @ phi1[boundary_nodes]
+            with self._record_active_subfield_array_timing_block(
+                "demag_auxiliary:dirichlet_extension",
+            ):
+                phi2 = self._dirichlet_extension_from_boundary(
+                    stiffness,
+                    boundary_nodes,
+                    phi2_boundary,
+                )
+        self.last_demag_solve_diagnostics = _demag_solve_diagnostics(
+            stiffness,
+            divergence,
+            boundary_nodes,
+            phi1,
+            phi2_boundary,
+            phi2,
+            phi1 + phi2,
+        )
+        if _demag_internal_trace_enabled():
+            self.last_demag_internal_vectors = {
+                "rho": np.array(rho, copy=True),
+                "phi1": np.array(phi1, copy=True),
+                "phi2": np.array(phi2, copy=True),
+                "phi": np.array(phi1 + phi2, copy=True),
+            }
+        return phi1 + phi2, rho, volumes
+
+    def _scalar_cofield_to_legacy_boxed_field(
+        self,
+        cofield: np.ndarray,
+        point_count: int,
+    ) -> np.ndarray:
+        if cofield.size == 0:
+            return np.zeros(point_count, dtype=float)
+
+        nodal = np.zeros(point_count, dtype=float)
+        # Legacy Nmag's simulation unit system always boxes rho with the
+        # fixed 1 nm base volume, rather than the loaded mesh's unit_length.
+        nodal[: len(cofield)] = cofield / LEGACY_RHO_BOXED_VOLUME_M3
+        return nodal

nmag/simulation/demag/fields/probe.py

@@ -0,0 +1,77 @@
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import TYPE_CHECKING, Any
+
+import numpy as np
+
+from ....demag import _mean_edge_length, _simplex_volumes
+from ...support import MU0_OVER_4PI, _simulation_compatibility_binding
+
+
+class SimulationDemagProbeMixin:
+    if TYPE_CHECKING:
+        _demag_dipoles: tuple[np.ndarray, np.ndarray, float] | None
+
+        def __getattr__(self, name: str) -> Any: ...
+
+    def _cell_demag_from_potential(
+        self,
+        points: np.ndarray,
+        simplices: np.ndarray,
+        phi: np.ndarray,
+    ) -> np.ndarray:
+        _, gradients_by_cell, _ = self._demag_fem_geometry_for_mesh(points, simplices)
+        return -np.einsum(
+            "ci,cij->cj",
+            phi[simplices],
+            gradients_by_cell,
+        )
+
+    def _build_demag_dipoles(self) -> tuple[np.ndarray, np.ndarray, float]:
+        if "m" not in self._fields:
+            raise RuntimeError("Magnetisation must be set before using demag fields.")
+
+        points = self._mesh_points()
+        mesh = self._require_mesh()
+        simplices = np.asarray(mesh.simplices, dtype=int)
+        if simplices.size == 0:
+            return np.empty((0, 3)), np.empty((0, 3)), 1.0
+        if simplices.ndim != 2 or simplices.shape[1] != 4:
+            raise NotImplementedError("The demag MVP currently supports tetrahedral 3D meshes.")
+
+        token = (id(mesh.raw_mesh), id(self._fields["m"]))
+        if self._demag_cache_token == token and self._demag_dipoles is not None:
+            return self._demag_dipoles
+
+        m = np.asarray(self._fields["m"], dtype=float)
+        centroids = np.mean(points[simplices], axis=1)
+        volumes = _simulation_compatibility_binding(
+            "_simplex_volumes",
+            _simplex_volumes,
+        )(points, simplices)
+        regions = list(mesh.regions or [1] * len(simplices))
+        ms_values = np.asarray(
+            [self._simplex_material_ms(region) for region in regions], dtype=float
+        )
+        cell_m = np.mean(m[simplices], axis=1)
+        dipole_moments = cell_m * (ms_values * volumes)[:, np.newaxis]
+        softening = 0.25 * _mean_edge_length(points, simplices)
+        self._demag_cache_token = token
+        self._demag_dipoles = (centroids, dipole_moments, softening)
+        return self._demag_dipoles
+
+    def _probe_demag_at(self, pos: Sequence[float]) -> np.ndarray:
+        centroids, dipole_moments, softening = self._build_demag_dipoles()
+        if len(centroids) == 0:
+            return np.zeros(3, dtype=float)
+
+        r = np.asarray(pos, dtype=float) - centroids
+        r2 = np.sum(r * r, axis=1) + softening * softening
+        r3 = r2**1.5
+        r5 = r2**2.5
+        mdotr = np.sum(dipole_moments * r, axis=1)
+        terms = (3.0 * r * mdotr[:, np.newaxis] / r5[:, np.newaxis]) - (
+            dipole_moments / r3[:, np.newaxis]
+        )
+        return MU0_OVER_4PI * np.sum(terms, axis=0)