nmag-python-3 0.0.5__tar.gz → 0.0.7__tar.gz

{nmag_python_3-0.0.5/src/nmag_python_3.egg-info → nmag_python_3-0.0.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nmag-python-3
-Version: 0.0.5
+Version: 0.0.7
 Summary: Standalone Python 3 implementation of the Nmag micromagnetic simulation interface
 Author-email: TriMagnetix <info@trimagnetix.com>
 Classifier: Programming Language :: Python :: 3
@@ -24,8 +24,8 @@ Requires-Dist: maturin<2,>=1.14; extra == "rust"
 Provides-Extra: docs
 Requires-Dist: mkdocs==1.6.1; extra == "docs"
 Requires-Dist: mkdocs-material==9.7.7; extra == "docs"
-Requires-Dist: mkdocstrings==1.0.6; extra == "docs"
-Requires-Dist: mkdocstrings-python==2.0.8; extra == "docs"
+Requires-Dist: mkdocstrings==1.0.8; extra == "docs"
+Requires-Dist: mkdocstrings-python==2.0.10; extra == "docs"
 Provides-Extra: dev
 Requires-Dist: maturin<2,>=1.14; extra == "dev"
 Requires-Dist: h5py-stubs<0.2,>=0.1.2; extra == "dev"

{nmag_python_3-0.0.5 → nmag_python_3-0.0.7}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "nmag-python-3"
-version = "0.0.5"
+version = "0.0.7"
 authors = [{ name = "TriMagnetix", email = "info@trimagnetix.com" }]
 description = "Standalone Python 3 implementation of the Nmag micromagnetic simulation interface"
 readme = "README.md"
@@ -32,8 +32,8 @@ rust = ["maturin>=1.14,<2"]
 docs = [
   "mkdocs==1.6.1",
   "mkdocs-material==9.7.7",
-  "mkdocstrings==1.0.6",
-  "mkdocstrings-python==2.0.8",
+  "mkdocstrings==1.0.8",
+  "mkdocstrings-python==2.0.10",
 ]
 dev = [
   "maturin>=1.14,<2",

{nmag_python_3-0.0.5 → nmag_python_3-0.0.7}/src/mag_material/mag_material.py

@@ -131,18 +131,85 @@ class MagMaterial:
 
         self.su_anisotropy = self.anisotropy
         self._derived_su_constants: dict[str, MaterialScalar] | None = None
+        self._derived_su_token: tuple[int, ...] | None = None
 
         self.extended_print = False
+        self._initialized = True
         if log.isEnabledFor(logging.INFO):
             log.info("Created new Material:\n %s", self)
 
+    def _sync_llg_coeffs(self) -> None:
+        gilbert_to_ll = 1.0 / (1.0 + self.su_llg_damping**2)
+        base_coeff1 = -self.su_llg_gamma_G * gilbert_to_ll
+        object.__setattr__(self, "su_llg_coeff2", base_coeff1 * self.su_llg_damping)
+        object.__setattr__(
+            self,
+            "su_llg_coeff1",
+            0.0 if not self.do_precession else base_coeff1,
+        )
+
+    def __setattr__(self, name: str, value: Any) -> None:
+        object.__setattr__(self, name, value)
+        if not getattr(self, "_initialized", False):
+            return
+        if name == "Ms":
+            object.__setattr__(self, "su_Ms", value)
+        elif name == "llg_gamma_G":
+            object.__setattr__(self, "su_llg_gamma_G", value)
+            self._sync_llg_coeffs()
+        elif name == "llg_damping":
+            object.__setattr__(self, "su_llg_damping", value)
+            self._sync_llg_coeffs()
+        elif name in {"su_llg_gamma_G", "su_llg_damping", "do_precession"}:
+            self._sync_llg_coeffs()
+        elif name == "llg_normalisationfactor":
+            object.__setattr__(self, "su_llg_normalisationfactor", value)
+        elif name == "exchange_coupling":
+            object.__setattr__(self, "su_exchange_coupling", value)
+        elif name == "anisotropy":
+            object.__setattr__(self, "su_anisotropy", value)
+        if not name.startswith("_"):
+            object.__setattr__(self, "_derived_su_constants", None)
+            object.__setattr__(self, "_derived_su_token", None)
+
     def _derived_su_values(self) -> dict[str, MaterialScalar]:
-        if self._derived_su_constants is None:
+        token = (
+            id(self.Ms),
+            id(self.llg_damping),
+            id(self.su_llg_damping),
+            id(self.llg_gamma_G),
+            id(self.su_llg_gamma_G),
+            id(self.llg_normalisationfactor),
+            id(self.su_llg_normalisationfactor),
+            id(self.llg_polarisation),
+            id(self.llg_xi),
+            id(self.exchange_coupling),
+            id(self.su_exchange_coupling),
+            id(self.su_Ms),
+            bool(self.do_precession),
+            id(self.anisotropy),
+            id(self.su_anisotropy),
+        )
+        if self._derived_su_constants is None or self._derived_su_token != token:
             constants = _si_constants()
-            thermal_factor = (2.0 * constants.boltzmann_constant * self.llg_damping) / (
-                -constants.gamma0 * constants.mu0 * self.Ms
+            ms = self.Ms.in_units_of(SI("A/m"))
+            su_ms = self.su_Ms.in_units_of(SI("A/m"))
+            thermal_factor = (
+                (
+                    (2.0 * constants.boltzmann_constant * self.llg_damping)
+                    / (-constants.gamma0 * constants.mu0 * SI(1.0, "A/m"))
+                )
+                * 0.0
+                if ms == 0.0
+                else (2.0 * constants.boltzmann_constant * self.llg_damping)
+                / (-constants.gamma0 * constants.mu0 * self.Ms)
+            )
+            damping = (
+                self.su_llg_damping.in_units_of(SI(1))
+                if isinstance(self.su_llg_damping, SI)
+                else float(self.su_llg_damping)
             )
-            gilbert_to_ll = 1.0 / (1.0 + self.su_llg_damping**2)
+            gilbert_to_ll = 1.0 / (1.0 + damping * damping)
             polarisation = (
                 self.llg_polarisation.in_units_of(SI(1))
                 if isinstance(self.llg_polarisation, SI)
@@ -153,7 +220,6 @@ class MagMaterial:
                 cast(Any, 1.0 * constants.bohr_magneton).to("J/T").magnitude
             )
             charge = float(cast(Any, 1.0 * constants.positron_charge).to("C").magnitude)
-            ms = self.Ms.in_units_of(SI("A/m"))
             su_f = (
                 SI(0.0, "m^3/A/s")
                 if ms == 0.0
@@ -165,16 +231,20 @@ class MagMaterial:
                     "m^3/A/s",
                 )
             )
+            su_exch_prefactor = (
+                (2.0 * self.su_exchange_coupling / (constants.mu0 * SI(1.0, "A/m"))) * 0.0
+                if su_ms == 0.0
+                else 2.0 * self.su_exchange_coupling / (constants.mu0 * self.su_Ms)
+            )
             self._derived_su_constants = {
                 "thermal_factor": thermal_factor,
                 "su_thermal_factor": thermal_factor,
                 "su_llg_stt_prefactor": 0.0 if su_f == 0.0 else 1.0,
-                "su_llg_stt_nadiab": su_f * (xi - self.su_llg_damping),
-                "su_llg_stt_adiab": su_f * (1.0 + self.su_llg_damping * xi),
-                "su_exch_prefactor": (
-                    2.0 * self.su_exchange_coupling / (constants.mu0 * self.su_Ms)
-                ),
+                "su_llg_stt_nadiab": su_f * (xi - damping),
+                "su_llg_stt_adiab": su_f * (1.0 + damping * xi),
+                "su_exch_prefactor": su_exch_prefactor,
             }
+            self._derived_su_token = token
         return self._derived_su_constants
 
     @property

{nmag_python_3-0.0.5 → nmag_python_3-0.0.7}/src/nmag/demag/linear.py

@@ -11,6 +11,7 @@ import numpy as np
 
 from ..backends import (
     DEMAG_DENSE_MAX_POINTS_ENV,
+    DEMAG_FEM_MATRIX_BACKEND_ENV,
     LEAST_SQUARES_RELATIVE_RESIDUAL_TOLERANCE,
     _demag_solve_condition_diagnostics_enabled,
     _selected_demag_linear_solver_backend,
@@ -20,41 +21,267 @@ LOGGER = logging.getLogger(__name__)
 _scipy_linalg_cache: Any | None = None
 
 
+_SPARSE_FACTORIZATION_MIN_POINTS = 64
+_SPARSE_FACTORIZATION_MAX_DENSITY = 0.25
+
+
+def _allow_sparse_factorization() -> bool:
+    return os.environ.get(DEMAG_FEM_MATRIX_BACKEND_ENV, "auto").strip().lower() != "dense"
+
+
 @dataclass(frozen=True, slots=True)
 class ScipyLUFactorization:
-    """Reusable LU factorization for a geometry-dependent dense system."""
+    """Reusable LU factorization for a geometry-dependent linear system."""
 
     lu: np.ndarray
     pivots: np.ndarray
+    splu: Any | None = None
+    gauge_fixed: bool = False
+    matrix: np.ndarray | None = None
+    constraint_scale: float = 1.0
 
     def solve(self, rhs: np.ndarray) -> np.ndarray:
-        return np.asarray(
+        rhs_array = np.asarray(rhs, dtype=float)
+        if not np.all(np.isfinite(rhs_array)):
+            raise np.linalg.LinAlgError("Cannot solve linear system with non-finite RHS.")
+        if self.splu is not None:
+            if self.gauge_fixed:
+                n = rhs_array.shape[0] - 1
+                if n < 0:
+                    raise ValueError(f"Expected rhs of length >= 1, got {rhs_array.shape}.")
+                rhs_body = rhs_array[:n]
+                rhs_gauge = rhs_array[n]
+                if n == 0 and np.any(rhs_gauge != 0.0):
+                    raise np.linalg.LinAlgError(
+                        "Singular gauge-fixed system with non-zero constraint RHS."
+                    )
+                lam = np.mean(rhs_body, axis=0) if n > 0 else np.zeros_like(rhs_gauge)
+                rhs_centered = rhs_body - lam
+                out = np.zeros_like(rhs_array, dtype=float)
+                if n > 1:
+                    out[1:n] = self.splu.solve(rhs_centered[1:])
+                if n > 0:
+                    out[:n] += rhs_gauge / n - np.mean(out[:n], axis=0)
+                out[n] = lam
+                if not np.all(np.isfinite(out)):
+                    raise np.linalg.LinAlgError("Sparse gauge-fixed LU solve produced non-finite values.")
+                return out
+            out = np.asarray(self.splu.solve(rhs_array), dtype=float)
+            if not np.all(np.isfinite(out)):
+                raise np.linalg.LinAlgError("Sparse LU solve produced non-finite values.")
+            return out
+        solve_rhs = rhs_array
+        if self.gauge_fixed and self.constraint_scale != 1.0 and rhs_array.shape[0] > 0:
+            solve_rhs = rhs_array.copy()
+            solve_rhs[-1] *= self.constraint_scale
+        if self.matrix is not None:
+            linalg = _scipy_linalg()
+            out = _validated_least_squares_solution(
+                self.matrix,
+                solve_rhs,
+                np.asarray(linalg.lstsq(self.matrix, solve_rhs, check_finite=False)[0], dtype=float),
+            )
+            if self.gauge_fixed and self.constraint_scale != 1.0 and out.shape[0] > 0:
+                out = out.copy()
+                out[-1] *= self.constraint_scale
+            return out
+        out = np.asarray(
             _scipy_linalg().lu_solve(
                 (self.lu, self.pivots),
-                np.asarray(rhs, dtype=float),
+                solve_rhs,
                 check_finite=False,
             ),
             dtype=float,
         )
+        if not np.all(np.isfinite(out)):
+            raise np.linalg.LinAlgError("Dense LU solve produced non-finite values.")
+        if self.gauge_fixed and self.constraint_scale != 1.0 and out.shape[0] > 0:
+            out = out.copy()
+            out[-1] *= self.constraint_scale
+        return out
+
+    def solve_gauge(self, divergence: np.ndarray) -> np.ndarray:
+        div_array = np.asarray(divergence, dtype=float)
+        if not np.all(np.isfinite(div_array)):
+            raise np.linalg.LinAlgError("Cannot solve gauge-fixed system with non-finite RHS.")
+        if self.splu is not None and self.gauge_fixed:
+            n = div_array.shape[0]
+            if n <= 1:
+                return np.zeros_like(div_array, dtype=float)
+            rhs_centered = div_array - np.mean(div_array, axis=0)
+            phi = np.zeros_like(div_array, dtype=float)
+            phi[1:] = self.splu.solve(rhs_centered[1:])
+            phi -= np.mean(phi, axis=0)
+            if not np.all(np.isfinite(phi)):
+                raise np.linalg.LinAlgError("Sparse gauge-fixed LU solve produced non-finite values.")
+            return phi
+        augmented_shape = (div_array.shape[0] + 1, *div_array.shape[1:])
+        augmented_rhs = np.zeros(augmented_shape, dtype=float)
+        augmented_rhs[:-1] = div_array
+        return self.solve(augmented_rhs)[:-1]
+
+
+def _is_well_conditioned_splu(splu: Any, matrix_scale: float) -> bool:
+    if matrix_scale <= np.finfo(float).tiny or not np.isfinite(matrix_scale):
+        return False
+    u_diag = np.asarray(splu.U.diagonal(), dtype=float)
+    if u_diag.size == 0 or not np.all(np.isfinite(u_diag)):
+        return False
+    if not np.all(np.isfinite(splu.U.data)) or not np.all(np.isfinite(splu.L.data)):
+        return False
+    max_u = max(float(np.max(np.abs(splu.U.data))) if splu.U.nnz else 0.0, matrix_scale)
+    pivot_tol = 100.0 * np.finfo(float).eps * max_u
+    return bool(np.all(np.abs(u_diag) > pivot_tol))
+
+
+def _factorize_dense_scipy(matrix_array: np.ndarray) -> ScipyLUFactorization:
+    import warnings
+
+    if not np.all(np.isfinite(matrix_array)):
+        raise np.linalg.LinAlgError("Cannot factorize a matrix with non-finite entries.")
+
+    linalg = _scipy_linalg()
+    with warnings.catch_warnings():
+        warnings.simplefilter("ignore", getattr(linalg, "LinAlgWarning", Warning))
+        lu, pivots = linalg.lu_factor(
+            matrix_array,
+            check_finite=False,
+        )
+    lu_array = np.asarray(lu, dtype=float)
+    pivots_array = np.asarray(pivots, dtype=int)
+    finite_lu = bool(np.all(np.isfinite(lu_array)))
+    max_entry = float(np.max(np.abs(lu_array))) if (lu_array.size and finite_lu) else 0.0
+    retained_matrix = (
+        matrix_array
+        if (
+            lu_array.size == 0
+            or not finite_lu
+            or max_entry <= np.finfo(float).tiny
+            or np.any(np.abs(np.diag(lu_array)) <= 100.0 * np.finfo(float).eps * max_entry)
+        )
+        else None
+    )
+    return ScipyLUFactorization(
+        lu_array,
+        pivots_array,
+        matrix=retained_matrix,
+    )
 
 
 def _factorize_scipy(matrix: np.ndarray) -> ScipyLUFactorization:
-    lu, pivots = _scipy_linalg().lu_factor(
-        np.asarray(matrix, dtype=float),
-        check_finite=False,
-    )
-    return ScipyLUFactorization(np.asarray(lu, dtype=float), np.asarray(pivots, dtype=int))
+    matrix_array = np.asarray(matrix, dtype=float)
+    if (
+        _allow_sparse_factorization()
+        and matrix_array.ndim == 2
+        and matrix_array.shape[0] == matrix_array.shape[1]
+        and matrix_array.shape[0] >= _SPARSE_FACTORIZATION_MIN_POINTS
+        and np.all(np.isfinite(matrix_array))
+    ):
+        sparse, sparse_linalg = _scipy_sparse_modules()
+        csc = sparse.csc_matrix(matrix_array)
+        max_abs = float(np.max(np.abs(csc.data))) if csc.nnz else 0.0
+        if (
+            max_abs > np.finfo(float).tiny
+            and csc.nnz <= _SPARSE_FACTORIZATION_MAX_DENSITY * matrix_array.size
+        ):
+            try:
+                splu = sparse_linalg.splu(csc)
+                if _is_well_conditioned_splu(splu, max_abs):
+                    return ScipyLUFactorization(
+                        np.empty((0, 0), dtype=float),
+                        np.empty(0, dtype=int),
+                        splu=splu,
+                        gauge_fixed=False,
+                    )
+            except (RuntimeError, np.linalg.LinAlgError):
+                LOGGER.debug(
+                    "Sparse LU factorization failed; falling back to dense LU.",
+                    exc_info=True,
+                )
+    return _factorize_dense_scipy(matrix_array)
+
+
+def _gauge_constraint_scale(matrix: np.ndarray) -> float:
+    if matrix.size == 0 or not np.all(np.isfinite(matrix)):
+        return 1.0
+    if matrix.ndim == 2 and matrix.shape[0] == matrix.shape[1]:
+        diag_max = float(np.max(np.abs(np.diag(matrix))))
+        if diag_max > np.finfo(float).tiny:
+            return diag_max
+    entry_max = float(np.max(np.abs(matrix)))
+    if entry_max > np.finfo(float).tiny:
+        return entry_max
+    return 1.0
 
 
 def _factorize_gauge_fixed(matrix: np.ndarray) -> ScipyLUFactorization:
-    constraint = np.ones(matrix.shape[0], dtype=float)
+    matrix_array = np.asarray(matrix, dtype=float)
+    n = matrix_array.shape[0]
+    if (
+        _allow_sparse_factorization()
+        and matrix_array.ndim == 2
+        and matrix_array.shape[1] == n
+        and n >= _SPARSE_FACTORIZATION_MIN_POINTS
+        and np.all(np.isfinite(matrix_array))
+    ):
+        sparse, sparse_linalg = _scipy_sparse_modules()
+        csc = sparse.csc_matrix(matrix_array)
+        max_abs = float(np.max(np.abs(csc.data))) if csc.nnz else 0.0
+        if (
+            max_abs > np.finfo(float).tiny
+            and csc.nnz <= _SPARSE_FACTORIZATION_MAX_DENSITY * matrix_array.size
+        ):
+            n_components = sparse.csgraph.connected_components(
+                csc,
+                directed=False,
+                return_labels=False,
+            )
+            row_col_tol = 100.0 * np.finfo(float).eps * max_abs
+            if (
+                n_components == 1
+                and np.allclose(
+                    np.asarray(csc.sum(axis=1)).ravel(),
+                    0.0,
+                    atol=row_col_tol,
+                    rtol=0.0,
+                )
+                and np.allclose(
+                    np.asarray(csc.sum(axis=0)).ravel(),
+                    0.0,
+                    atol=row_col_tol,
+                    rtol=0.0,
+                )
+            ):
+                try:
+                    splu = sparse_linalg.splu(csc[1:, 1:])
+                    if _is_well_conditioned_splu(splu, max_abs):
+                        return ScipyLUFactorization(
+                            np.empty((0, 0), dtype=float),
+                            np.empty(0, dtype=int),
+                            splu=splu,
+                            gauge_fixed=True,
+                        )
+                except (RuntimeError, np.linalg.LinAlgError):
+                    LOGGER.debug(
+                        "Sparse gauge-fixed LU factorization failed; falling back to dense LU.",
+                        exc_info=True,
+                    )
+    constraint_scale = _gauge_constraint_scale(matrix_array)
+    constraint = np.full(n, constraint_scale, dtype=float)
     augmented = np.block(
         [
-            [matrix, constraint[:, np.newaxis]],
+            [matrix_array, constraint[:, np.newaxis]],
             [constraint[np.newaxis, :], np.zeros((1, 1), dtype=float)],
         ]
     )
-    return _factorize_scipy(augmented)
+    dense = _factorize_dense_scipy(augmented)
+    return ScipyLUFactorization(
+        dense.lu,
+        dense.pivots,
+        matrix=dense.matrix,
+        gauge_fixed=True,
+        constraint_scale=constraint_scale,
+    )
 
 
 def __getattr__(name: str) -> Any:
@@ -304,10 +531,12 @@ def _gauge_augmented_system(
 ) -> tuple[np.ndarray, np.ndarray]:
     started = time.perf_counter()
     try:
-        constraint = np.ones(len(rhs), dtype=float)
+        matrix_array = np.asarray(matrix, dtype=float)
+        constraint_scale = _gauge_constraint_scale(matrix_array)
+        constraint = np.full(len(rhs), constraint_scale, dtype=float)
         augmented = np.block(
             [
-                [matrix, constraint[:, np.newaxis]],
+                [matrix_array, constraint[:, np.newaxis]],
                 [constraint[np.newaxis, :], np.zeros((1, 1), dtype=float)],
             ]
         )
@@ -337,17 +566,29 @@ def _solve_dense_scipy(
     record_timing: Callable[[str, float], None] | None,
     timing_prefix: str,
 ) -> np.ndarray:
+    import warnings
+
     started = time.perf_counter()
     linalg = _scipy_linalg()
     if record_timing is not None:
         record_timing(f"{timing_prefix}:scipy_import", time.perf_counter() - started)
     started = time.perf_counter()
     try:
-        result = linalg.solve(matrix, rhs, assume_a="sym", check_finite=False)
+        with warnings.catch_warnings():
+            warnings.simplefilter("error", getattr(linalg, "LinAlgWarning", Warning))
+            result = np.asarray(
+                linalg.solve(matrix, rhs, assume_a="sym", check_finite=False),
+                dtype=float,
+            )
+        if not np.all(np.isfinite(result)) or (
+            _safe_relative_residual(matrix @ result - rhs, rhs)
+            > LEAST_SQUARES_RELATIVE_RESIDUAL_TOLERANCE
+        ):
+            raise np.linalg.LinAlgError("Direct SciPy solve failed residual validation.")
         if record_timing is not None:
             record_timing(f"{timing_prefix}:scipy_solve", time.perf_counter() - started)
         return result
-    except np.linalg.LinAlgError:
+    except (np.linalg.LinAlgError, Warning):
         if record_timing is not None:
             record_timing(
                 f"{timing_prefix}:scipy_solve_failed",
@@ -387,7 +628,12 @@ def _solve_dense_numpy(
 ) -> np.ndarray:
     started = time.perf_counter()
     try:
-        result = np.linalg.solve(matrix, rhs)
+        result = np.asarray(np.linalg.solve(matrix, rhs), dtype=float)
+        if not np.all(np.isfinite(result)) or (
+            _safe_relative_residual(matrix @ result - rhs, rhs)
+            > LEAST_SQUARES_RELATIVE_RESIDUAL_TOLERANCE
+        ):
+            raise np.linalg.LinAlgError("Direct NumPy solve failed residual validation.")
         if record_timing is not None:
             record_timing(f"{timing_prefix}:numpy_solve", time.perf_counter() - started)
         return result
@@ -470,7 +716,8 @@ def _demag_solve_diagnostics(
         if _is_sparse_matrix(stiffness):
             diagnostics["condition_numbers_skipped_for_sparse_storage"] = 1
         else:
-            constraint = np.ones(len(divergence), dtype=float)
+            constraint_scale = _gauge_constraint_scale(np.asarray(stiffness, dtype=float))
+            constraint = np.full(len(divergence), constraint_scale, dtype=float)
             augmented_stiffness = np.block(
                 [
                     [stiffness, constraint[:, np.newaxis]],

{nmag_python_3-0.0.5 → nmag_python_3-0.0.7}/src/nmag/simulation/__init__.py

@@ -145,7 +145,11 @@ class Simulation(
         self.last_probe_timings_seconds: dict[str, float] = {}
         self.last_subfield_average_timings_seconds: dict[str, float] = {}
         self.last_maxangle_timings_seconds: dict[str, float] = {}
-        self.last_demag_solve_diagnostics: dict[str, float | int] = {}
+        self._last_demag_solve_diagnostics: dict[str, float | int] | None = {}
+        self._last_demag_solve_diagnostics_inputs: (
+            tuple[Any, np.ndarray, np.ndarray, np.ndarray, np.ndarray, np.ndarray, np.ndarray]
+            | None
+        ) = None
         self._last_bem_operator_stats: BemOperatorStats | None = None
         self.last_demag_internal_vectors: dict[str, np.ndarray] = {}
         self._active_subfield_array_timings: dict[str, float] | None = None
@@ -159,45 +163,78 @@ class Simulation(
         self.mat_of_mat_name: dict[str, Any] = {}
         self.materials: list[Any] = []
         self._fields: dict[str, Any] = {}
-        self._demag_cache_token: tuple[int, int] | None = None
+        self._demag_cache_token: tuple[int, ...] | None = None
         self._demag_dipoles: tuple[np.ndarray, np.ndarray, float] | None = None
         self._demag_nodal_cache: np.ndarray | None = None
-        self._demag_cell_cache_token: tuple[int, int] | None = None
+        self._demag_cell_cache_token: tuple[int, ...] | None = None
         self._demag_cell_field_cache: tuple[np.ndarray, np.ndarray] | None = None
         self._demag_geometry_cache_token: int | None = None
         self._demag_boundary_faces_cache: list[tuple[int, tuple[int, int, int]]] | None = None
         self._demag_bem_cache: tuple[str, np.ndarray, Any, BemOperatorStats] | None = None
-        self._demag_fem_geometry_cache: tuple[str, Any, np.ndarray, np.ndarray] | None = None
+        self._demag_bem_env_cache: tuple[Any, ...] | None = None
+        self._demag_fem_geometry_cache: (
+            tuple[str, np.ndarray, np.ndarray, Any, np.ndarray, np.ndarray] | None
+        ) = None
+        self._demag_fem_env_cache: tuple[Any, ...] | None = None
         self._demag_gauge_factorization_cache: ScipyLUFactorization | None = None
         self._demag_dirichlet_factorization_cache: (
-            tuple[np.ndarray, np.ndarray, ScipyLUFactorization] | None
+            tuple[np.ndarray, np.ndarray, Any, ScipyLUFactorization] | None
+        ) = None
+        self._demag_nodal_recovery_operator_cache: (
+            tuple[np.ndarray, np.ndarray, np.ndarray, int, Any] | None
         ) = None
-        self._demag_ms_values_cache: tuple[int, np.ndarray] | None = None
-        self._demag_volume_charge_scales_cache: tuple[int, np.ndarray] | None = None
-        self._nodal_ms_values_cache: tuple[int, np.ndarray] | None = None
-        self._demag_aux_cache_token: tuple[int, int] | None = None
+        self._demag_fem_divergence_operator_cache: (
+            tuple[np.ndarray, np.ndarray, np.ndarray, np.ndarray, int, Any] | None
+        ) = None
+        self._demag_cell_gradient_inputs_cache: (
+            tuple[
+                np.ndarray,
+                np.ndarray,
+                np.ndarray,
+                np.ndarray,
+                np.ndarray,
+                np.ndarray,
+                np.ndarray,
+                np.ndarray,
+                np.ndarray,
+                np.ndarray,
+            ]
+            | None
+        ) = None
+        self._demag_ms_values_cache: tuple[int, int, Any, np.ndarray, np.ndarray] | None = None
+        self._demag_volume_charge_scales_cache: (
+            tuple[int, int, Any, np.ndarray, np.ndarray] | None
+        ) = None
+        self._nodal_ms_values_cache: tuple[tuple[int, int], np.ndarray] | None = None
+        self._demag_aux_cache_token: tuple[int, ...] | None = None
         self._demag_phi_cache: np.ndarray | None = None
         self._demag_rho_cache: np.ndarray | None = None
         self._demag_volumes_cache: np.ndarray | None = None
-        self._mesh_points_cache: tuple[int, np.ndarray] | None = None
+        self._mesh_points_cache: tuple[int, Any, int, np.ndarray] | None = None
+        self._mesh_simplices_cache: tuple[int, Any, int, np.ndarray] | None = None
         self._mesh_bounds_cache: tuple[int, np.ndarray, np.ndarray, np.ndarray] | None = None
         self._mesh_edge_cache: tuple[int, np.ndarray] | None = None
         self._simplex_volume_cache: tuple[int, np.ndarray, np.ndarray] | None = None
         self._volume_average_node_weights_cache: tuple[int, int, np.ndarray] | None = None
         self._incident_cell_volume_sums_cache: tuple[int, int, int, np.ndarray] | None = None
-        self._exchange_cache_token: tuple[int, int] | None = None
+        self._exchange_cache_token: tuple[int, ...] | None = None
         self._exchange_nodal_cache: np.ndarray | None = None
+        self._exchange_operator_cache: (
+            tuple[int, Any, np.ndarray, Any, Any, np.ndarray, bool, np.ndarray] | None
+        ) = None
         self._exchange_spectral_bound_cache: tuple[int, float] | None = None
-        self._nodal_material_coefficients_cache: tuple[int, NodalMaterialCoefficients] | None = None
+        self._nodal_material_coefficients_cache: (
+            tuple[tuple[int, int], NodalMaterialCoefficients] | None
+        ) = None
         self._nodal_anisotropy_groups_cache: (
-            tuple[int, tuple[NodalAnisotropyGroup, ...]] | None
+            tuple[tuple[int, int], tuple[NodalAnisotropyGroup, ...]] | None
         ) = None
         self._anisotropy_fields_cache: tuple[
-            tuple[int, int],
+            tuple[int, int, int],
             np.ndarray,
             np.ndarray,
         ] | None = None
-        self._llg_affine_operator_cache: tuple[int, np.ndarray] | None = None
+        self._llg_affine_operator_cache: tuple[tuple[int, int, bool], np.ndarray] | None = None
         self._probe_geometry_cache_token: int | None = None
         self._probe_tetrahedral_cache: (
             tuple[
@@ -264,7 +301,8 @@ class Simulation(
         Args:
             filename: Legacy Nmesh or Meshio-supported mesh file.
             region_names_and_mag_mats: ``(region_name, material)`` pairs in
-                ascending mesh-region order, starting at region 1.
+                ascending mesh-region order. Mesh region IDs do not need to be
+                contiguous or start at region 1.
             unit_length: Physical length represented by one mesh coordinate
                 unit.
             do_reorder: Request legacy node reordering. Reordering is currently
@@ -298,21 +336,24 @@ class Simulation(
         if manual_distribution is not None:
             self.mesh.set_vertex_distribution(manual_distribution)
 
-        self.region_name_list = [name for name, _ in region_names_and_mag_mats]
-        self.region_name_of_id = {
-            index: name for index, name in enumerate(self.region_name_list, start=1)
-        }
-        self.region_id_of_name = {name: index for index, name in self.region_name_of_id.items()}
-
-        mesh_region_ids = {int(region_id) for region_id in self.mesh.regions}
-        configured_region_ids = set(self.region_name_of_id)
-        if mesh_region_ids != configured_region_ids:
+        mesh_region_ids = sorted({int(region_id) for region_id in self.mesh.regions})
+        if len(mesh_region_ids) != len(region_names_and_mag_mats):
+            configured_names = [name for name, _ in region_names_and_mag_mats]
             raise ValueError(
                 "Mesh material regions do not match the configured region list: "
-                f"mesh={sorted(mesh_region_ids)}, configured={sorted(configured_region_ids)}. "
-                "Materials must be supplied in ascending mesh-region order."
+                f"mesh={mesh_region_ids}, configured={configured_names}. "
+                "Supply one material per mesh region, in ascending mesh-region order."
             )
 
+        self.region_name_list = [name for name, _ in region_names_and_mag_mats]
+        self.region_name_of_id = {
+            region_id: name
+            for region_id, name in zip(mesh_region_ids, self.region_name_list, strict=True)
+        }
+        self.region_id_of_name = {
+            name: region_id for region_id, name in self.region_name_of_id.items()
+        }
+
         self.mats_of_region_name = {}
         self.mat_of_mat_name = {}
         for name, materials in region_names_and_mag_mats: