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

nmag/simulation/fields/probes.py

@@ -0,0 +1,106 @@
+from __future__ import annotations
+
+import time
+from collections.abc import Sequence
+from typing import TYPE_CHECKING, Any
+
+import numpy as np
+
+from si.physical import SI
+
+
+class SimulationFieldProbeMixin:
+    if TYPE_CHECKING:
+
+        def __getattr__(self, name: str) -> Any: ...
+
+    def probe_subfield_siv(
+        self,
+        subfieldname: str,
+        pos: Sequence[float],
+        unit: SI | None = None,
+    ) -> Any:
+        """Probe a field at a position expressed in metres.
+
+        Demagnetization fields are linearly interpolated in the containing
+        tetrahedron. Magnetization uses the nearest mesh node, and a homogeneous
+        applied field is returned directly.
+
+        Args:
+            subfieldname: ``H_demag``, ``H_ext``, or ``m``.
+            pos: Three physical coordinates in metres.
+            unit: Reserved compatibility argument. Returned values use the
+                field's standard SI representation.
+
+        Returns:
+            Ordinary numeric components in SI, or ``None`` outside the mesh.
+
+        Raises:
+            KeyError: If the field name is not supported by this probe API.
+        """
+        if subfieldname == "H_demag":
+            total_started = time.perf_counter()
+            try:
+                started = time.perf_counter()
+                within_bounds = self._probe_is_within_mesh_bounds(pos)
+                self._record_probe_timing(
+                    "bounds_check",
+                    time.perf_counter() - started,
+                )
+                if not within_bounds:
+                    return None
+
+                started = time.perf_counter()
+                points = self._mesh_points()
+                probe = np.asarray(pos, dtype=float)
+                self._record_probe_timing(
+                    "prepare_probe",
+                    time.perf_counter() - started,
+                )
+
+                started = time.perf_counter()
+                legacy_null_vertex = self._probe_is_legacy_null_vertex(probe, points)
+                self._record_probe_timing(
+                    "legacy_null_vertex_check",
+                    time.perf_counter() - started,
+                )
+                if legacy_null_vertex:
+                    return None
+
+                started = time.perf_counter()
+                nodal_field = self._get_demag_nodal_field()
+                self._record_probe_timing(
+                    "demag_nodal_field",
+                    time.perf_counter() - started,
+                )
+
+                started = time.perf_counter()
+                result = self._probe_tetrahedral_field(probe, nodal_field)
+                self._record_probe_timing(
+                    "tetrahedral_interpolation",
+                    time.perf_counter() - started,
+                )
+                return result
+            finally:
+                self._record_probe_timing(
+                    "total",
+                    time.perf_counter() - total_started,
+                )
+        if subfieldname == "H_ext":
+            return self._fields.get("H_ext", np.zeros(3)).tolist()
+        if subfieldname != "m":
+            raise KeyError(f"Unknown or unset subfield '{subfieldname}'.")
+        if self.mesh is None or "m" not in self._fields:
+            return None
+
+        points = np.asarray(self.mesh.points, dtype=float)
+        if points.size == 0:
+            return None
+        probe = np.asarray(pos, dtype=float)
+        nearest_index = int(np.argmin(np.linalg.norm(points - probe, axis=1)))
+        return np.asarray(self._fields["m"][nearest_index], dtype=float).tolist()
+
+    def _record_probe_timing(self, name: str, value: float) -> None:
+        self.last_probe_timings_seconds[name] = (
+            self.last_probe_timings_seconds.get(name, 0.0) + value
+        )

nmag/simulation/implicit_dynamics.py

@@ -0,0 +1,221 @@
+from __future__ import annotations
+
+import math
+import os
+import time
+from typing import Any, Protocol
+
+import numpy as np
+from numpy.typing import NDArray
+
+from ..backends import _load_rust_accelerator
+from ..dynamics import IntegratorStats
+from ..resources import available_memory_bytes as _available_memory_bytes
+from .support import _si_unit, _simulation_compatibility_binding
+
+FloatArray = NDArray[np.float64]
+DIFFSOL_DENSE_MEMORY_LIMIT_ENV = "NMAG_DIFFSOL_DENSE_MEMORY_LIMIT_GIB"
+DIFFSOL_DENSE_MATRIX_COPIES_ESTIMATE = 6
+DIFFSOL_AVAILABLE_MEMORY_FRACTION = 0.8
+DEFAULT_BDF_INITIAL_STEP_SECONDS = 1.0e-15
+DEFAULT_BDF_MAXIMUM_STEPS = 1_000_000
+
+
+class _BdfResult(Protocol):
+    state: list[float]
+    reached_time: float
+    accepted_steps: int
+    rejected_steps: int
+    rhs_evaluations: int
+    jacobian_vector_evaluations: int
+    nonlinear_iterations: int
+    nonlinear_failures: int
+    linear_solver_setups: int
+    last_step: float
+    max_dm_dt: float
+    converged: bool
+
+
+def _estimated_dense_bdf_peak_bytes(state_size: int) -> int:
+    if state_size < 1:
+        raise ValueError("state_size must be positive.")
+    matrix_bytes = state_size * state_size * np.dtype(np.float64).itemsize
+    return DIFFSOL_DENSE_MATRIX_COPIES_ESTIMATE * matrix_bytes
+
+
+def _diffsol_dense_memory_budget() -> tuple[int | None, str]:
+    configured = os.environ.get(DIFFSOL_DENSE_MEMORY_LIMIT_ENV)
+    if configured is not None:
+        value = configured.strip().lower()
+        if value == "unlimited":
+            return None, "explicit unlimited override"
+        try:
+            gibibytes = float(value)
+        except ValueError as error:
+            raise ValueError(
+                f"{DIFFSOL_DENSE_MEMORY_LIMIT_ENV} must be a positive number of GiB "
+                f"or 'unlimited', got {configured!r}."
+            ) from error
+        if not math.isfinite(gibibytes) or gibibytes <= 0.0:
+            raise ValueError(
+                f"{DIFFSOL_DENSE_MEMORY_LIMIT_ENV} must be a positive number of GiB "
+                f"or 'unlimited', got {configured!r}."
+            )
+        return int(gibibytes * 1024**3), "explicit environment budget"
+
+    available = _available_memory_bytes()
+    if available is None:
+        return None, "available memory could not be determined"
+    return int(available * DIFFSOL_AVAILABLE_MEMORY_FRACTION), "80% of available memory"
+
+
+def _validate_diffsol_dense_memory(state_size: int) -> None:
+    estimated_bytes = _estimated_dense_bdf_peak_bytes(state_size)
+    budget_bytes, budget_source = _diffsol_dense_memory_budget()
+    if budget_bytes is None or estimated_bytes <= budget_bytes:
+        return
+
+    estimated_gib = estimated_bytes / 1024**3
+    budget_gib = budget_bytes / 1024**3
+    raise MemoryError(
+        f"The dense Diffsol solve for {state_size} state values is estimated to require "
+        f"approximately {estimated_gib:.2f} GiB, exceeding the {budget_gib:.2f} GiB "
+        f"budget ({budget_source}). Set {DIFFSOL_DENSE_MEMORY_LIMIT_ENV} to a reviewed "
+        "GiB budget or 'unlimited' to proceed. There is no fixed state-count limit."
+    )
+
+
+def build_affine_field_operator(simulation: Any) -> FloatArray:
+    """Build the dense linear map from nodal m to demag plus exchange field."""
+    mesh_token = simulation._mesh_geometry_token()
+    cached = simulation._llg_affine_operator_cache
+    if cached is not None and cached[0] == mesh_token:
+        return cached[1]
+
+    original_m = np.asarray(simulation._fields["m"], dtype=np.float64)
+    state_size = int(original_m.size)
+    _validate_diffsol_dense_memory(state_size)
+
+    def linear_field(state: FloatArray) -> FloatArray:
+        simulation._fields["m"] = np.reshape(state, (-1, 3))
+        simulation._invalidate_demag()
+        field = np.asarray(simulation._get_exchange_nodal_field(), dtype=np.float64)
+        if simulation.do_demag:
+            field = field + np.asarray(simulation._get_demag_nodal_field(), dtype=np.float64)
+        return np.ravel(field)
+
+    try:
+        zero = np.zeros(state_size, dtype=np.float64)
+        baseline = linear_field(zero)
+        operator = np.empty((state_size, state_size), dtype=np.float64)
+        basis = np.zeros(state_size, dtype=np.float64)
+        for column in range(state_size):
+            basis[column] = 1.0
+            operator[:, column] = linear_field(basis) - baseline
+            basis[column] = 0.0
+    finally:
+        simulation._fields["m"] = np.array(original_m, copy=True)
+        simulation._invalidate_demag()
+
+    operator = np.ascontiguousarray(operator)
+    simulation._llg_affine_operator_cache = (mesh_token, operator)
+    return operator
+
+
+def relax_with_diffsol(simulation: Any, H_applied: Any = None) -> None:
+    if simulation.mesh is None or "m" not in simulation._fields:
+        raise RuntimeError("A mesh and magnetisation are required before relaxation.")
+    if not simulation._anisotropy_is_zero_by_construction():
+        raise NotImplementedError(
+            "The experimental Diffsol backend does not support dynamic anisotropy."
+        )
+
+    simulation.do_next_stage(stage=simulation.clock.stage)
+    simulation.clock.stage_end = False
+    if H_applied is not None:
+        simulation.set_H_ext(H_applied)
+
+    started = time.perf_counter()
+    try:
+        operator = build_affine_field_operator(simulation)
+        point_count = len(simulation._fields["m"])
+        h_ext = np.asarray(simulation._fields.get("H_ext", np.zeros(3)), dtype=np.float64)
+        constant_field = np.ascontiguousarray(np.tile(h_ext, point_count))
+        pin = np.ascontiguousarray(simulation._subfield_array("pin"), dtype=np.float64)
+        c1, c2, c3 = simulation._llg_coefficients()
+        config = simulation.integrator_config
+        rust_accel = _simulation_compatibility_binding(
+            "_load_rust_accelerator", _load_rust_accelerator
+        )("NmagConfig(integrator_backend='diffsol')")
+        try:
+            integrate_llg_bdf = rust_accel.integrate_llg_bdf
+        except AttributeError as exc:
+            raise RuntimeError(
+                "NmagConfig(integrator_backend='diffsol') requires an nmag_accel build with the "
+                "Diffsol backend. Rebuild it with `./scripts/build-accelerator.sh --release`."
+            ) from exc
+
+        result: _BdfResult = integrate_llg_bdf(
+            np.ascontiguousarray(np.ravel(simulation._fields["m"]), dtype=np.float64),
+            operator,
+            constant_field,
+            pin,
+            c1,
+            c2,
+            c3,
+            0.0,
+            simulation.max_time_reached.in_units_of(_si_unit("s")),
+            config.relative_tolerance,
+            config.absolute_tolerance,
+            min(DEFAULT_BDF_INITIAL_STEP_SECONDS, config.maximum_step_seconds),
+            config.maximum_step_seconds,
+            simulation.stopping_dm_dt,
+            5,
+            simulation.convergence.required_checks,
+            DEFAULT_BDF_MAXIMUM_STEPS,
+        )
+    except Exception:
+        simulation._last_integrator_stats = IntegratorStats(
+            failed=True,
+            status="failed",
+            wall_seconds=time.perf_counter() - started,
+        )
+        raise
+    wall_seconds = time.perf_counter() - started
+    accepted_state = np.asarray(result.state, dtype=np.float64)
+    if not np.all(np.isfinite(accepted_state)):
+        raise FloatingPointError("Diffsol returned a non-finite magnetisation state.")
+
+    simulation._fields["m"] = np.reshape(accepted_state, (-1, 3))
+    simulation._invalidate_demag()
+    simulation._invalidate_integrator()
+    simulation.max_dm_dt = float(result.max_dm_dt)
+    simulation.clock.record_advance(
+        stage_time_seconds=float(result.reached_time),
+        accepted_steps=int(result.accepted_steps),
+        last_step_seconds=float(result.last_step),
+        wall_seconds=wall_seconds,
+    )
+    simulation.clock.convergence = bool(result.converged)
+    simulation.clock.stage_end = bool(result.converged)
+    simulation._last_integrator_stats = IntegratorStats(
+        accepted_steps=int(result.accepted_steps),
+        rhs_evaluations=int(result.rhs_evaluations),
+        rejected_steps=int(result.rejected_steps),
+        failed=False,
+        status="converged" if result.converged else "maximum_time_reached",
+        last_step_seconds=float(result.last_step),
+        simulated_seconds=float(result.reached_time),
+        wall_seconds=wall_seconds,
+        jacobian_vector_evaluations=int(result.jacobian_vector_evaluations),
+        nonlinear_iterations=int(result.nonlinear_iterations),
+        nonlinear_failures=int(result.nonlinear_failures),
+        linear_solver_setups=int(result.linear_solver_setups),
+    )
+    if not result.converged:
+        raise RuntimeError(
+            f"Diffsol reached {simulation.max_time_reached} without satisfying convergence."
+        )
+
+    simulation.save_data()
+    simulation.save_data(fields="all")

nmag/simulation/mesh/__init__.py

@@ -0,0 +1,13 @@
+"""Mesh-operation compatibility façade composed from focused mixins."""
+
+from .geometry import SimulationMeshGeometryMixin
+from .materials import SimulationMeshMaterialMixin
+from .probe import SimulationMeshProbeMixin
+
+
+class SimulationMeshMixin(
+    SimulationMeshGeometryMixin,
+    SimulationMeshProbeMixin,
+    SimulationMeshMaterialMixin,
+):
+    """Provide mesh caches, probing, and material-aware averaging."""

nmag/simulation/mesh/geometry.py

@@ -0,0 +1,153 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+import numpy as np
+
+from ..support import _MESH_EDGE_SET_THRESHOLD
+
+
+class SimulationMeshGeometryMixin:
+    if TYPE_CHECKING:
+
+        def __getattr__(self, name: str) -> Any: ...
+
+    def _invalidate_demag(self, *, clear_geometry: bool = False) -> None:
+        self._demag_cache_token = None
+        self._demag_dipoles = None
+        self._demag_nodal_cache = None
+        self._demag_cell_cache_token = None
+        self._demag_cell_field_cache = None
+        self._demag_aux_cache_token = None
+        self._demag_phi_cache = None
+        self._demag_rho_cache = None
+        self._demag_volumes_cache = None
+        self.last_demag_solve_diagnostics = {}
+        self.last_demag_internal_vectors = {}
+        self._exchange_cache_token = None
+        self._exchange_nodal_cache = None
+        self._anisotropy_fields_cache = None
+        if clear_geometry:
+            self._demag_geometry_cache_token = None
+            self._demag_boundary_faces_cache = None
+            self._demag_bem_cache = None
+            self._last_bem_operator_stats = None
+            self._demag_fem_geometry_cache = None
+            self._demag_gauge_factorization_cache = None
+            self._demag_dirichlet_factorization_cache = None
+            self._demag_ms_values_cache = None
+            self._demag_volume_charge_scales_cache = None
+            self._nodal_ms_values_cache = None
+            self._mesh_points_cache = None
+            self._mesh_bounds_cache = None
+            self._mesh_edge_cache = None
+            self._simplex_volume_cache = None
+            self._volume_average_node_weights_cache = None
+            self._incident_cell_volume_sums_cache = None
+            self._exchange_spectral_bound_cache = None
+            self._nodal_material_coefficients_cache = None
+            self._nodal_anisotropy_groups_cache = None
+            self._anisotropy_fields_cache = None
+            self._llg_affine_operator_cache = None
+            self._probe_geometry_cache_token = None
+            self._probe_tetrahedral_cache = None
+
+    def _mesh_points(self) -> np.ndarray:
+        token = self._mesh_geometry_token()
+        if self._mesh_points_cache is not None:
+            cached_token, cached_points = self._mesh_points_cache
+            if cached_token == token:
+                return cached_points
+
+        points = np.asarray(self._require_mesh().points, dtype=float)
+        if points.ndim != 2 or points.shape[1] != 3:
+            raise NotImplementedError("The demag MVP currently supports only 3D meshes.")
+        self._mesh_points_cache = (token, points)
+        return points
+
+    def _mesh_bounds(self) -> tuple[np.ndarray, np.ndarray, np.ndarray]:
+        token = self._mesh_geometry_token()
+        if self._mesh_bounds_cache is not None:
+            cached_token, lower, upper, span = self._mesh_bounds_cache
+            if cached_token == token:
+                return lower, upper, span
+
+        points = self._mesh_points()
+        lower = np.min(points, axis=0)
+        upper = np.max(points, axis=0)
+        span = np.maximum(upper - lower, np.ones(3))
+        self._mesh_bounds_cache = (token, lower, upper, span)
+        return lower, upper, span
+
+    def _mesh_edges(self) -> np.ndarray:
+        token = self._mesh_geometry_token()
+        if self._mesh_edge_cache is not None:
+            cached_token, cached_edges = self._mesh_edge_cache
+            if cached_token == token:
+                return cached_edges
+
+        mesh = self._require_mesh()
+        simplices = np.asarray(mesh.simplices, dtype=int)
+        if simplices.ndim != 2 or simplices.shape[1] < 2 or len(simplices) == 0:
+            edges = np.zeros((0, 2), dtype=int)
+        else:
+            local_pairs = np.asarray(
+                [
+                    (left, right)
+                    for left in range(simplices.shape[1])
+                    for right in range(left + 1, simplices.shape[1])
+                ],
+                dtype=int,
+            )
+            candidate_edge_count = len(simplices) * len(local_pairs)
+            if candidate_edge_count <= _MESH_EDGE_SET_THRESHOLD:
+                seen_edges: set[tuple[int, int]] = set()
+                for simplex in simplices:
+                    for left_position, left in enumerate(simplex):
+                        left_index = int(left)
+                        for right in simplex[left_position + 1 :]:
+                            right_index = int(right)
+                            if left_index <= right_index:
+                                seen_edges.add((left_index, right_index))
+                            else:
+                                seen_edges.add((right_index, left_index))
+                edges = np.asarray(sorted(seen_edges), dtype=int)
+            else:
+                expanded_edges = np.asarray(simplices[:, local_pairs], dtype=np.int64)
+                flat_edges = expanded_edges.flatten()
+                edges = np.column_stack((flat_edges[0::2], flat_edges[1::2]))
+                edges.sort(axis=1)
+                node_count = max(int(np.max(simplices)) + 1, len(mesh.points))
+                edge_codes = edges[:, 0].astype(np.int64, copy=False) * node_count + edges[
+                    :, 1
+                ].astype(np.int64, copy=False)
+                unique_codes = np.unique(edge_codes)
+                edges = np.empty((len(unique_codes), 2), dtype=int)
+                edges[:, 0] = unique_codes // node_count
+                edges[:, 1] = unique_codes % node_count
+
+        self._mesh_edge_cache = (token, edges)
+        return edges
+
+    def _mesh_geometry_token(self) -> int:
+        return id(self._require_mesh().raw_mesh)
+
+    def _require_mesh(self) -> Any:
+        if self.mesh is None:
+            raise RuntimeError("A mesh must be loaded before using simulation fields.")
+        return self.mesh
+
+    def _ensure_demag_geometry_cache_token(self, token: int) -> None:
+        if self._demag_geometry_cache_token == token:
+            return
+        self._demag_geometry_cache_token = token
+        self._demag_boundary_faces_cache = None
+        self._demag_bem_cache = None
+        self._last_bem_operator_stats = None
+        self._demag_fem_geometry_cache = None
+        self._demag_ms_values_cache = None
+        self._demag_volume_charge_scales_cache = None
+        self._nodal_ms_values_cache = None
+        self._nodal_material_coefficients_cache = None
+        self._nodal_anisotropy_groups_cache = None
+        self._anisotropy_fields_cache = None