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

nmag/simulation/mesh/materials.py

@@ -0,0 +1,299 @@
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import TYPE_CHECKING, Any, cast
+
+import numpy as np
+
+from ...demag import _simplex_volumes
+from ..support import _si_unit, _simulation_compatibility_binding
+
+
+class SimulationMeshMaterialMixin:
+    if TYPE_CHECKING:
+        _simplex_volume_cache: Any | None
+        _volume_average_node_weights_cache: Any | None
+        _incident_cell_volume_sums_cache: Any | None
+        _demag_ms_values_cache: Any | None
+        _demag_volume_charge_scales_cache: Any | None
+        _nodal_ms_values_cache: Any | None
+
+        def __getattr__(self, name: str) -> Any: ...
+
+    def _material_region_ids(self, material_name: str) -> np.ndarray:
+        region_ids = [
+            self.region_id_of_name[region_name]
+            for region_name, materials in self.mats_of_region_name.items()
+            if any(material.name == material_name for material in materials)
+        ]
+        if not region_ids:
+            raise KeyError(f"Unknown material '{material_name}'.")
+        return np.asarray(region_ids, dtype=int)
+
+    def _field_average(
+        self,
+        data: np.ndarray,
+        *,
+        mat_name: str | None = None,
+    ) -> np.ndarray | float:
+        if self.mesh is None:
+            return np.mean(data, axis=0)
+        if data.ndim == 1:
+            return self._scalar_field_average(data, mat_name=mat_name)
+        if data.ndim != 2:
+            return np.mean(data, axis=0)
+        if len(data) > 0 and np.all(data == data[0]):
+            return np.asarray(data[0], dtype=float)
+
+        simplices = np.asarray(self._require_mesh().simplices, dtype=int)
+        points = self._mesh_points()
+        if (
+            len(data) != len(points)
+            or simplices.ndim != 2
+            or simplices.shape[1] != 4
+            or len(simplices) == 0
+        ):
+            return np.mean(data, axis=0)
+
+        volumes, positive = self._simplex_volume_weights(points, simplices)
+        if mat_name is not None:
+            regions = np.asarray(self._require_mesh().regions, dtype=int)
+            positive = positive & np.isin(regions, self._material_region_ids(mat_name))
+        if not np.any(positive):
+            return np.mean(data, axis=0)
+
+        weights = (
+            self._volume_average_node_weights(points, simplices, len(data))
+            if mat_name is None
+            else None
+        )
+        if weights is None:
+            cell_values = np.mean(data[simplices[positive]], axis=1)
+            return np.sum(cell_values * volumes[positive, np.newaxis], axis=0) / float(
+                np.sum(volumes[positive])
+            )
+        return weights @ data
+
+    def _scalar_field_average(
+        self,
+        data: np.ndarray,
+        *,
+        mat_name: str | None = None,
+    ) -> float:
+        if len(data) > 0 and np.all(data == data[0]):
+            return float(data[0])
+
+        simplices = np.asarray(self._require_mesh().simplices, dtype=int)
+        points = self._mesh_points()
+        if len(data) != len(points) or simplices.ndim != 2 or simplices.shape[1] != 4:
+            return float(np.mean(data))
+
+        volumes, positive = self._simplex_volume_weights(points, simplices)
+        if mat_name is not None:
+            regions = np.asarray(self._require_mesh().regions, dtype=int)
+            positive = positive & np.isin(regions, self._material_region_ids(mat_name))
+        if not np.any(positive):
+            return float(np.mean(data))
+
+        weights = (
+            self._volume_average_node_weights(points, simplices, len(data))
+            if mat_name is None
+            else None
+        )
+        if weights is None:
+            cell_values = np.mean(data[simplices[positive]], axis=1)
+            return float(np.sum(cell_values * volumes[positive]) / float(np.sum(volumes[positive])))
+        return float(weights @ data)
+
+    def _simplex_volume_weights(
+        self,
+        points: np.ndarray,
+        simplices: np.ndarray,
+    ) -> tuple[np.ndarray, np.ndarray]:
+        token = self._mesh_geometry_token()
+        if self._simplex_volume_cache is not None:
+            cached_token, volumes, positive = self._simplex_volume_cache
+            if cached_token == token and len(volumes) == len(simplices):
+                return volumes, positive
+
+        volumes = _simulation_compatibility_binding(
+            "_simplex_volumes",
+            _simplex_volumes,
+        )(points, simplices)
+        positive = volumes > 0.0
+        self._simplex_volume_cache = (token, volumes, positive)
+        return volumes, positive
+
+    def _volume_average_node_weights(
+        self,
+        points: np.ndarray,
+        simplices: np.ndarray,
+        point_count: int,
+    ) -> np.ndarray | None:
+        token = self._mesh_geometry_token()
+        if self._volume_average_node_weights_cache is not None:
+            cached_token, cached_point_count, weights = self._volume_average_node_weights_cache
+            if cached_token == token and cached_point_count == point_count:
+                return weights
+
+        volumes, positive = self._simplex_volume_weights(points, simplices)
+        if not np.any(positive):
+            return None
+
+        weights = np.zeros(point_count, dtype=float)
+        positive_simplices = simplices[positive]
+        positive_volumes = volumes[positive]
+        np.add.at(weights, positive_simplices.flatten(), np.repeat(positive_volumes / 4.0, 4))
+        total_volume = float(np.sum(positive_volumes))
+        if total_volume <= 0.0:
+            return None
+
+        weights /= total_volume
+        self._volume_average_node_weights_cache = (token, point_count, weights)
+        return weights
+
+    def _incident_cell_volume_sums(
+        self,
+        points: np.ndarray,
+        simplices: np.ndarray,
+        volumes: np.ndarray,
+    ) -> np.ndarray:
+        token = self._mesh_geometry_token()
+        point_count = len(points)
+        cell_count = len(simplices)
+        if self._incident_cell_volume_sums_cache is not None:
+            cached_token, cached_point_count, cached_cell_count, weights = (
+                self._incident_cell_volume_sums_cache
+            )
+            if (
+                cached_token == token
+                and cached_point_count == point_count
+                and cached_cell_count == cell_count
+            ):
+                return weights
+
+        weights = np.zeros(point_count, dtype=float)
+        positive = volumes > 0.0
+        if np.any(positive):
+            positive_simplices = simplices[positive]
+            positive_volumes = volumes[positive]
+            for local_index in range(4):
+                np.add.at(
+                    weights,
+                    positive_simplices[:, local_index],
+                    positive_volumes,
+                )
+
+        self._incident_cell_volume_sums_cache = (token, point_count, cell_count, weights)
+        return weights
+
+    def _simplex_material(self, region_id: int) -> Any:
+        region_name = self.region_name_of_id.get(int(region_id))
+        raw_materials: Any = self.mats_of_region_name.get(region_name, []) if region_name else []
+        materials = cast(list[Any], raw_materials)
+        if not materials:
+            raise ValueError(f"Mesh region {region_id} has no configured magnetic material.")
+        if len(materials) != 1:
+            raise NotImplementedError(
+                "Multiple magnetic material subfields in one mesh region are not supported."
+            )
+        return materials[0]
+
+    def _simplex_material_ms(self, region_id: int) -> float:
+        return self._simplex_material(region_id).Ms.in_units_of(_si_unit("A/m"))
+
+    def _simplex_material_ms_values(self, regions: Sequence[int]) -> np.ndarray:
+        token = self._mesh_geometry_token()
+        self._ensure_demag_geometry_cache_token(token)
+        if self._demag_ms_values_cache is not None:
+            cached_token, cached_values = self._demag_ms_values_cache
+            if cached_token == token and len(cached_values) == len(regions):
+                return cached_values
+
+        region_ids = np.asarray(regions, dtype=int)
+        if region_ids.size == 0:
+            ms_values = np.zeros(0, dtype=float)
+            self._demag_ms_values_cache = (token, ms_values)
+            return ms_values
+
+        first_region = int(region_ids[0])
+        if np.all(region_ids == first_region):
+            ms_values = np.full(
+                len(region_ids),
+                self._simplex_material_ms(first_region),
+                dtype=float,
+            )
+            self._demag_ms_values_cache = (token, ms_values)
+            return ms_values
+
+        unique_region_ids, inverse = np.unique(region_ids, return_inverse=True)
+        ms_lookup = np.asarray(
+            [self._simplex_material_ms(int(region)) for region in unique_region_ids],
+            dtype=float,
+        )
+        ms_values = ms_lookup[inverse]
+        self._demag_ms_values_cache = (token, ms_values)
+        return ms_values
+
+    def _simplex_volume_charge_scales(self, regions: Sequence[int]) -> np.ndarray:
+        token = self._mesh_geometry_token()
+        self._ensure_demag_geometry_cache_token(token)
+        if self._demag_volume_charge_scales_cache is not None:
+            cached_token, cached_values = self._demag_volume_charge_scales_cache
+            if cached_token == token and len(cached_values) == len(regions):
+                return cached_values
+
+        region_ids = np.asarray(regions, dtype=int)
+        if region_ids.size == 0:
+            scales = np.zeros(0, dtype=float)
+        else:
+            unique_region_ids, inverse = np.unique(region_ids, return_inverse=True)
+            scale_lookup = np.asarray(
+                [
+                    float(self._simplex_material(int(region)).scale_volume_charges)
+                    for region in unique_region_ids
+                ],
+                dtype=float,
+            )
+            scales = scale_lookup[inverse]
+
+        self._demag_volume_charge_scales_cache = (token, scales)
+        return scales
+
+    def _nodal_ms_values(self) -> np.ndarray:
+        if self.mesh is None:
+            raise RuntimeError("A mesh must be loaded before using material fields.")
+
+        token = self._mesh_geometry_token()
+        if self._nodal_ms_values_cache is not None:
+            cached_token, cached_values = self._nodal_ms_values_cache
+            if cached_token == token:
+                return cached_values
+
+        points = self._mesh_points()
+        simplices = np.asarray(self.mesh.simplices, dtype=int)
+        if simplices.size == 0 or simplices.ndim != 2 or simplices.shape[1] != 4:
+            default_ms = (
+                self.materials[0].Ms.in_units_of(_si_unit("A/m")) if self.materials else 0.0
+            )
+            nodal_ms = np.full(len(points), default_ms, dtype=float)
+            self._nodal_ms_values_cache = (token, nodal_ms)
+            return nodal_ms
+
+        regions = list(self.mesh.regions or [1] * len(simplices))
+        simplex_ms = self._simplex_material_ms_values(regions)
+        volumes, positive = self._simplex_volume_weights(points, simplices)
+        nodal_ms = np.zeros(len(points), dtype=float)
+        weights = self._incident_cell_volume_sums(points, simplices, volumes)
+        if np.any(positive):
+            positive_simplices = simplices[positive]
+            weighted_ms = simplex_ms[positive] * volumes[positive]
+            for local_index in range(4):
+                np.add.at(nodal_ms, positive_simplices[:, local_index], weighted_ms)
+
+        present = weights > 0.0
+        nodal_ms[present] /= weights[present]
+        if np.any(~present):
+            nodal_ms[~present] = simplex_ms[positive][0] if np.any(positive) else 0.0
+        self._nodal_ms_values_cache = (token, nodal_ms)
+        return nodal_ms

nmag/simulation/mesh/probe.py

@@ -0,0 +1,234 @@
+from __future__ import annotations
+
+import time
+from collections.abc import Sequence
+from typing import TYPE_CHECKING, Any
+
+import numpy as np
+
+from ...backends import (
+    _load_rust_accelerator,
+    _selected_probe_geometry_backend,
+)
+from ...demag import _tetrahedral_barycentric_coordinates
+from ..support import _simulation_compatibility_binding
+
+
+class SimulationMeshProbeMixin:
+    if TYPE_CHECKING:
+        _probe_geometry_cache_token: Any | None
+        _probe_tetrahedral_cache: Any | None
+
+        def __getattr__(self, name: str) -> Any: ...
+
+    def _probe_is_within_mesh_bounds(self, pos: Sequence[float]) -> bool:
+        probe = np.asarray(pos, dtype=float)
+        if probe.shape != (3,):
+            raise ValueError(f"Probe position must be a 3-vector, got shape {probe.shape}.")
+
+        lower, upper, span = self._mesh_bounds()
+        tolerance = 1.0e-12 * span
+        return bool(np.all(probe >= lower - tolerance) and np.all(probe <= upper + tolerance))
+
+    def _probe_is_legacy_null_vertex(self, probe: np.ndarray, points: np.ndarray) -> bool:
+        """Legacy nmag can return None at exact boundary mesh vertex 0."""
+        if len(points) == 0 or not np.array_equal(probe, points[0]):
+            return False
+        simplices = np.asarray(self._require_mesh().simplices, dtype=int)
+        boundary_nodes = {
+            point_index
+            for _owner, face in self._boundary_faces_for_demag_mesh(points, simplices)
+            for point_index in face
+        }
+        return 0 in boundary_nodes
+
+    def _probe_tetrahedral_field(
+        self,
+        probe: np.ndarray,
+        nodal_values: np.ndarray,
+    ) -> list[float] | None:
+        simplices, origins, inverse_matrices, lower, upper = self._probe_tetrahedral_geometry()
+        if len(simplices) == 0:
+            return None
+        tolerance = 1.0e-12
+        started = time.perf_counter()
+        candidate_indices = np.flatnonzero(
+            np.all(probe >= lower - tolerance, axis=1) & np.all(probe <= upper + tolerance, axis=1)
+        )
+        self._record_probe_timing(
+            "tetrahedral_candidate_search",
+            time.perf_counter() - started,
+        )
+        if len(candidate_indices) == 0:
+            return None
+
+        started = time.perf_counter()
+        offsets = probe - origins[candidate_indices]
+        local = np.einsum(
+            "nij,nj->ni",
+            inverse_matrices[candidate_indices],
+            offsets,
+        )
+        barycentric = np.column_stack(
+            [
+                1.0 - np.sum(local, axis=1),
+                local,
+            ]
+        )
+        inside = np.all(barycentric >= -tolerance, axis=1) & np.all(
+            barycentric <= 1.0 + tolerance,
+            axis=1,
+        )
+        self._record_probe_timing(
+            "tetrahedral_barycentric",
+            time.perf_counter() - started,
+        )
+        if not np.any(inside):
+            return None
+
+        started = time.perf_counter()
+        candidate_position = int(np.flatnonzero(inside)[0])
+        cache_index = int(candidate_indices[candidate_position])
+        simplex = simplices[cache_index]
+        clipped = np.minimum(np.maximum(barycentric[candidate_position], 0.0), 1.0)
+        result = (clipped @ nodal_values[simplex]).tolist()
+        self._record_probe_timing(
+            "tetrahedral_value_interpolation",
+            time.perf_counter() - started,
+        )
+        return result
+
+    def _probe_tetrahedral_geometry(
+        self,
+    ) -> tuple[np.ndarray, np.ndarray, np.ndarray, np.ndarray, np.ndarray]:
+        total_started = time.perf_counter()
+        token = self._mesh_geometry_token()
+        if self._probe_geometry_cache_token == token and self._probe_tetrahedral_cache is not None:
+            self._record_probe_timing("tetrahedral_geometry_cache_hit", 0.0)
+            self._record_probe_timing(
+                "tetrahedral_geometry",
+                time.perf_counter() - total_started,
+            )
+            return self._probe_tetrahedral_cache
+
+        build_started = time.perf_counter()
+        backend = _selected_probe_geometry_backend(getattr(self, "config", None))
+        self._probe_tetrahedral_cache = (
+            self._probe_tetrahedral_geometry_rust()
+            if backend == "rust"
+            else self._probe_tetrahedral_geometry_python()
+        )
+        self._probe_geometry_cache_token = token
+        self._record_probe_timing(
+            f"tetrahedral_geometry_build:{backend}",
+            time.perf_counter() - build_started,
+        )
+        self._record_probe_timing(
+            "tetrahedral_geometry_build",
+            time.perf_counter() - build_started,
+        )
+        self._record_probe_timing(
+            "tetrahedral_geometry",
+            time.perf_counter() - total_started,
+        )
+        return self._probe_tetrahedral_cache
+
+    def _probe_tetrahedral_geometry_python(
+        self,
+    ) -> tuple[np.ndarray, np.ndarray, np.ndarray, np.ndarray, np.ndarray]:
+        points = self._mesh_points()
+        simplices = np.asarray(self._require_mesh().simplices, dtype=int)
+        if simplices.size == 0:
+            empty_simplices = np.zeros((0, 4), dtype=int)
+            empty_vectors = np.zeros((0, 3), dtype=float)
+            empty_matrices = np.zeros((0, 3, 3), dtype=float)
+            return (
+                empty_simplices,
+                empty_vectors,
+                empty_matrices,
+                empty_vectors,
+                empty_vectors,
+            )
+
+        valid_simplices: list[np.ndarray] = []
+        origins: list[np.ndarray] = []
+        inverse_matrices: list[np.ndarray] = []
+        lower: list[np.ndarray] = []
+        upper: list[np.ndarray] = []
+        for simplex in simplices:
+            tetrahedron = points[simplex]
+            matrix = np.column_stack(
+                [
+                    tetrahedron[1] - tetrahedron[0],
+                    tetrahedron[2] - tetrahedron[0],
+                    tetrahedron[3] - tetrahedron[0],
+                ]
+            )
+            try:
+                inverse = np.linalg.inv(matrix)
+            except np.linalg.LinAlgError:
+                continue
+            valid_simplices.append(simplex)
+            origins.append(tetrahedron[0])
+            inverse_matrices.append(inverse)
+            lower.append(np.min(tetrahedron, axis=0))
+            upper.append(np.max(tetrahedron, axis=0))
+
+        if not valid_simplices:
+            empty_vectors = np.empty((0, 3), dtype=float)
+            return (
+                np.empty((0, 4), dtype=int),
+                empty_vectors,
+                np.empty((0, 3, 3), dtype=float),
+                empty_vectors,
+                empty_vectors,
+            )
+        return (
+            np.asarray(valid_simplices, dtype=int),
+            np.asarray(origins, dtype=float),
+            np.asarray(inverse_matrices, dtype=float),
+            np.asarray(lower, dtype=float),
+            np.asarray(upper, dtype=float),
+        )
+
+    def _probe_tetrahedral_geometry_rust(
+        self,
+    ) -> tuple[np.ndarray, np.ndarray, np.ndarray, np.ndarray, np.ndarray]:
+        rust_accel = _simulation_compatibility_binding(
+            "_load_rust_accelerator",
+            _load_rust_accelerator,
+        )("NmagConfig.accelerator['probe_geometry']")
+        geometry = rust_accel.build_probe_tetrahedral_geometry(
+            np.asarray(self._mesh_points(), dtype=np.float64),
+            np.asarray(self._require_mesh().simplices, dtype=np.int64),
+        )
+        valid_simplices, origins, inverse_matrices, lower, upper = geometry
+        return (
+            np.asarray(valid_simplices, dtype=int),
+            np.asarray(origins, dtype=float),
+            np.asarray(inverse_matrices, dtype=float),
+            np.asarray(lower, dtype=float),
+            np.asarray(upper, dtype=float),
+        )
+
+    def _probe_tetrahedral_field_reference(
+        self,
+        probe: np.ndarray,
+        nodal_values: np.ndarray,
+    ) -> list[float] | None:
+        """Scalar reference path for checking cached probe interpolation."""
+        if self.mesh is None:
+            raise RuntimeError("A mesh must be loaded before probing fields.")
+        simplices = np.asarray(self._require_mesh().simplices, dtype=int)
+        if simplices.size == 0:
+            return None
+        points = self._mesh_points()
+        for simplex in simplices:
+            barycentric = _tetrahedral_barycentric_coordinates(
+                points[simplex],
+                probe,
+            )
+            if barycentric is None:
+                continue
+            return (barycentric @ nodal_values[simplex]).tolist()
+        return None

nmag/simulation/restart.py

@@ -0,0 +1,103 @@
+from __future__ import annotations
+
+import time
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+import numpy as np
+
+from si.physical import SI
+
+from ..checkpoint import read_checkpoint, runtime_state, save_checkpoint, validate_mesh
+from ..dynamics import IntegratorStats
+
+
+class SimulationRestartMixin:
+    if TYPE_CHECKING:
+
+        def __getattr__(self, name: str) -> Any: ...
+
+    def get_restart_file_name(self) -> Path:
+        """Return the default native checkpoint path beside simulation output."""
+        return self.writer.h5_filename.with_name(f"{self.name}_restart.h5")
+
+    def save_restart_file(self, filename: str | Path | None = None) -> Path:
+        """Atomically save a complete native checkpoint.
+
+        Args:
+            filename: Destination path, or ``None`` for the simulation's default
+                restart filename.
+
+        Returns:
+            The checkpoint path.
+
+        Raises:
+            RuntimeError: If mesh or magnetization state is incomplete.
+        """
+        destination = self.get_restart_file_name() if filename is None else Path(filename)
+        return save_checkpoint(self, destination)
+
+    def load_m_from_h5file(self, filename: str | Path) -> None:
+        """Load only checkpoint magnetization into the configured simulation.
+
+        Args:
+            filename: Native checkpoint created for the same mesh.
+
+        Raises:
+            ValueError: If the checkpoint or mesh is incompatible.
+        """
+        point_count = len(self._mesh_points())
+        contents = read_checkpoint(Path(filename), point_count)
+        validate_mesh(self, contents)
+        self._fields["m"] = np.array(contents.magnetisation, dtype=float, copy=True)
+        self._invalidate_after_checkpoint_restore()
+
+    def load_restart_file(self, filename: str | Path | None = None) -> None:
+        """Restore complete native state into a compatible loaded simulation.
+
+        The target simulation must already have the same mesh and compatible
+        materials. Magnetization, pinning, current density, applied field,
+        clock, integrator controls, and convergence state are restored.
+
+        Args:
+            filename: Source path, or ``None`` for the default restart filename.
+
+        Raises:
+            ValueError: If checkpoint schema, mesh, materials, or dimensions are
+                incompatible.
+        """
+        source = self.get_restart_file_name() if filename is None else Path(filename)
+        point_count = len(self._mesh_points())
+        contents = read_checkpoint(source, point_count)
+        runtime = runtime_state(self, contents)
+
+        self._fields["m"] = np.array(contents.magnetisation, dtype=float, copy=True)
+        self._fields["pin"] = np.array(contents.pinning, dtype=float, copy=True)
+        self._fields["H_ext"] = np.array(contents.external_field, dtype=float, copy=True)
+        if contents.current_density is None:
+            self._fields.pop("current_density", None)
+        else:
+            self._fields["current_density"] = np.array(
+                contents.current_density,
+                dtype=float,
+                copy=True,
+            )
+        self.clock = runtime.clock
+        self._integrator_config = runtime.integrator_config
+        self.stopping_dm_dt = runtime.stopping_dm_dt
+        self.max_time_reached = SI(runtime.maximum_time_seconds, "s")
+        self.max_dm_dt = runtime.maximum_dm_dt
+        self.convergence = runtime.convergence
+        self._restarting = False
+        self._invalidate_after_checkpoint_restore()
+
+    def _invalidate_after_checkpoint_restore(self) -> None:
+        self._invalidate_demag()
+        self._subfield_array_cache = None
+        self._subfield_average_cache = None
+        self._integrator = None
+        self._integrator_is_stale = True
+        self._integrator_rhs_evaluations = 0
+        self._integrator_effective_max_step_seconds = self._integrator_config.maximum_step_seconds
+        self._last_integrator_stats = IntegratorStats(status="restarted")
+        self._stage_wall_started = time.perf_counter()