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

nmag/simulation/fields/averages.py

@@ -0,0 +1,293 @@
+from __future__ import annotations
+
+import time
+from typing import TYPE_CHECKING, Any
+
+import numpy as np
+
+from ..support import (
+    _NO_COMPOSED_AVERAGE,
+    _NO_CONSTANT_AVERAGE,
+    _copy_average_value,
+)
+
+_NO_ARRAY_AVERAGE = object()
+
+
+class SimulationFieldAverageMixin:
+    if TYPE_CHECKING:
+        _active_subfield_array_timings: dict[str, float] | None
+
+        def __getattr__(self, name: str) -> Any: ...
+
+    def get_subfield_average(self, subfieldname: str, mat_name: str | None = None) -> Any:
+        """Return the volume-weighted average of an available field.
+
+        Args:
+            subfieldname: Field name, for example ``m``, ``H_total``, or
+                ``E_demag``.
+            mat_name: Restrict integration to tetrahedra belonging to this
+                material. Omit it for the complete magnetic volume.
+
+        Returns:
+            A scalar or component list, or ``None`` when the requested derived
+            quantity is not available for the current model.
+        """
+        timings: dict[str, float] = {}
+        self.last_subfield_average_timings_seconds = {}
+        total_started = time.perf_counter()
+        cache_key = (subfieldname, mat_name)
+        cached_average = self._cached_subfield_average(cache_key)
+        if cached_average is not _NO_CONSTANT_AVERAGE:
+            timings["cache_hit"] = time.perf_counter() - total_started
+            self._finish_subfield_average_timings(timings, total_started)
+            return _copy_average_value(cached_average)
+
+        started = time.perf_counter()
+        constant_average = self._constant_subfield_average(subfieldname)
+        if constant_average is not _NO_CONSTANT_AVERAGE:
+            timings["constant_average"] = time.perf_counter() - started
+            self._finish_subfield_average_timings(timings, total_started)
+            self._cache_subfield_average(cache_key, constant_average)
+            return constant_average
+
+        if subfieldname == "H_demag":
+            result = self._direct_demag_average(timings)
+            self._finish_subfield_average_timings(timings, total_started)
+            self._cache_subfield_average(cache_key, result)
+            return result
+
+        composed_average = self._try_composed_subfield_average(subfieldname, mat_name, timings)
+        if composed_average is not _NO_COMPOSED_AVERAGE:
+            result = np.asarray(composed_average, dtype=float).tolist()
+            self._finish_subfield_average_timings(timings, total_started)
+            self._cache_subfield_average(cache_key, result)
+            return result
+
+        average = self._array_subfield_average(subfieldname, mat_name, timings)
+        self._finish_subfield_average_timings(timings, total_started)
+        if average is _NO_ARRAY_AVERAGE:
+            return None
+        self._cache_subfield_average(cache_key, average)
+        return average
+
+    def _finish_subfield_average_timings(
+        self,
+        timings: dict[str, float],
+        total_started: float,
+    ) -> None:
+        timings["total"] = time.perf_counter() - total_started
+        self.last_subfield_average_timings_seconds = dict(sorted(timings.items()))
+
+    def _direct_demag_average(self, timings: dict[str, float]) -> list[float]:
+        subfield_timings: dict[str, float] = {}
+        previous_subfield_timings = self._active_subfield_array_timings
+        self._active_subfield_array_timings = subfield_timings
+        try:
+            started = time.perf_counter()
+            average = self._demag_cell_field_average()
+            timings["direct_cell_average"] = time.perf_counter() - started
+        finally:
+            if self._active_subfield_array_timings is subfield_timings:
+                self._active_subfield_array_timings = previous_subfield_timings
+        self._append_subfield_array_timings(timings, subfield_timings)
+        return np.asarray(average, dtype=float).tolist()
+
+    def _try_composed_subfield_average(
+        self,
+        subfieldname: str,
+        mat_name: str | None,
+        timings: dict[str, float],
+    ) -> object:
+        composed_timings: dict[str, float] = {}
+        subfield_timings: dict[str, float] = {}
+        previous_subfield_timings = self._active_subfield_array_timings
+        self._active_subfield_array_timings = subfield_timings
+        try:
+            started = time.perf_counter()
+            try:
+                average = self._composed_subfield_average(
+                    subfieldname,
+                    composed_timings,
+                    mat_name=mat_name,
+                )
+            except KeyError:
+                average = _NO_COMPOSED_AVERAGE
+            timings["composed_average"] = time.perf_counter() - started
+        finally:
+            if self._active_subfield_array_timings is subfield_timings:
+                self._active_subfield_array_timings = previous_subfield_timings
+        if average is _NO_COMPOSED_AVERAGE:
+            timings.pop("composed_average")
+            return average
+        timings.update(composed_timings)
+        self._append_subfield_array_timings(timings, subfield_timings)
+        return average
+
+    def _array_subfield_average(
+        self,
+        subfieldname: str,
+        mat_name: str | None,
+        timings: dict[str, float],
+    ) -> Any | object:
+        subfield_timings: dict[str, float] = {}
+        previous_subfield_timings = self._active_subfield_array_timings
+        self._active_subfield_array_timings = subfield_timings
+        data: np.ndarray | None
+        try:
+            try:
+                started = time.perf_counter()
+                data = self._subfield_array(subfieldname)
+                timings["array"] = time.perf_counter() - started
+            except KeyError:
+                data = None
+        finally:
+            if self._active_subfield_array_timings is subfield_timings:
+                self._active_subfield_array_timings = previous_subfield_timings
+        self._append_subfield_array_timings(timings, subfield_timings)
+        if data is None or data.size == 0:
+            return _NO_ARRAY_AVERAGE
+        started = time.perf_counter()
+        average_value = self._field_average(data, mat_name=mat_name)
+        average = (
+            average_value.tolist()
+            if isinstance(average_value, np.ndarray)
+            else float(average_value)
+        )
+        timings["field_average"] = time.perf_counter() - started
+        return average
+
+    def _append_subfield_array_timings(
+        self,
+        timings: dict[str, float],
+        subfield_timings: dict[str, float],
+    ) -> None:
+        timings.update(
+            (f"subfield_array:{name}", seconds)
+            for name, seconds in sorted(subfield_timings.items())
+        )
+
+    def _constant_subfield_average(self, subfieldname: str) -> object:
+        if subfieldname == "H_ext":
+            return self._constant_h_ext_average()
+        if self.mesh is None:
+            return _NO_CONSTANT_AVERAGE
+        handlers = {
+            "pin": self._constant_pin_average,
+            "H_anis": self._constant_h_anis_average,
+            "E_anis": self._constant_e_anis_average,
+            "H_exch": self._constant_h_exch_average,
+            "E_exch": self._constant_e_exch_average,
+        }
+        handler = handlers.get(subfieldname)
+        return _NO_CONSTANT_AVERAGE if handler is None else handler()
+
+    def _constant_h_ext_average(self) -> object:
+        h_ext = np.asarray(self._fields.get("H_ext", np.zeros(3)), dtype=float)
+        return h_ext.tolist() if h_ext.shape == (3,) else _NO_CONSTANT_AVERAGE
+
+    def _constant_pin_average(self) -> object:
+        pin = self._fields.get("pin")
+        if pin is None:
+            return 1.0
+        pin_values = np.asarray(pin, dtype=float)
+        if pin_values.size > 0 and np.all(pin_values == pin_values[0]):
+            return float(pin_values[0])
+        return _NO_CONSTANT_AVERAGE
+
+    def _constant_h_anis_average(self) -> object:
+        return self._constant_anisotropy_average([0.0, 0.0, 0.0])
+
+    def _constant_e_anis_average(self) -> object:
+        return self._constant_anisotropy_average(0.0)
+
+    def _constant_anisotropy_average(self, zero_value: object) -> object:
+        if "m" not in self._fields or not self._anisotropy_is_zero_by_construction():
+            return _NO_CONSTANT_AVERAGE
+        return zero_value
+
+    def _constant_h_exch_average(self) -> object:
+        return [0.0, 0.0, 0.0] if self._exchange_is_zero_by_construction() else _NO_CONSTANT_AVERAGE
+
+    def _constant_e_exch_average(self) -> object:
+        return 0.0 if self._exchange_is_zero_by_construction() else _NO_CONSTANT_AVERAGE
+
+    def _composed_subfield_average(
+        self,
+        subfieldname: str,
+        timings: dict[str, float],
+        *,
+        mat_name: str | None = None,
+    ) -> object:
+        if subfieldname != "H_total":
+            return _NO_COMPOSED_AVERAGE
+        if self.mesh is None or "m" not in self._fields:
+            return _NO_COMPOSED_AVERAGE
+
+        total = np.asarray(
+            self._average_component_for_composition("H_ext", timings),
+            dtype=float,
+        )
+        if self.do_demag:
+            total = total + np.asarray(
+                self._average_component_for_composition("H_demag", timings),
+                dtype=float,
+            )
+        total = total + np.asarray(
+            self._average_component_for_composition(
+                "H_anis",
+                timings,
+                mat_name=mat_name,
+            ),
+            dtype=float,
+        )
+        total = total + np.asarray(
+            self._average_component_for_composition(
+                "H_exch",
+                timings,
+                mat_name=mat_name,
+            ),
+            dtype=float,
+        )
+        return total
+
+    def _average_component_for_composition(
+        self,
+        subfieldname: str,
+        timings: dict[str, float],
+        *,
+        mat_name: str | None = None,
+    ) -> np.ndarray:
+        cache_key = (subfieldname, mat_name)
+        cached_average = self._cached_subfield_average(cache_key)
+        if cached_average is not _NO_CONSTANT_AVERAGE:
+            timings[f"component_average:{subfieldname}:cache_hit"] = 0.0
+            return np.asarray(cached_average, dtype=float)
+
+        started = time.perf_counter()
+        constant_average = self._constant_subfield_average(subfieldname)
+        if constant_average is not _NO_CONSTANT_AVERAGE:
+            timings[f"component_average:{subfieldname}:constant"] = time.perf_counter() - started
+            self._cache_subfield_average(cache_key, constant_average)
+            return np.asarray(constant_average, dtype=float)
+
+        if subfieldname == "H_demag":
+            started = time.perf_counter()
+            average = self._demag_cell_field_average()
+            timings[f"component_average:{subfieldname}:direct_cell_average"] = (
+                time.perf_counter() - started
+            )
+            self._cache_subfield_average(cache_key, average)
+            return np.asarray(average, dtype=float)
+
+        started = time.perf_counter()
+        data = self._subfield_array(subfieldname)
+        timings[f"component_average:{subfieldname}:array"] = time.perf_counter() - started
+        if data.size == 0:
+            raise KeyError(f"Component field '{subfieldname}' is empty.")
+
+        started = time.perf_counter()
+        average = self._field_average(data, mat_name=mat_name)
+        timings[f"component_average:{subfieldname}:field_average"] = time.perf_counter() - started
+        self._cache_subfield_average(cache_key, average)
+        return np.asarray(average, dtype=float)

nmag/simulation/fields/derived.py

@@ -0,0 +1,164 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+import numpy as np
+
+from ...backends import _selected_llg_backend
+from ..support import (
+    LEGACY_DMDT_MAGNETISATION_SCALE,
+    MU0,
+    _simulation_compatibility_binding,
+)
+
+
+class SimulationFieldDerivedMixin:
+    if TYPE_CHECKING:
+
+        def __getattr__(self, name: str) -> Any: ...
+
+    def _derived_subfield_array(self, subfieldname: str) -> np.ndarray:
+        if self.mesh is None:
+            raise KeyError(f"Derived field '{subfieldname}' requires a mesh.")
+        point_count = len(self.mesh.points)
+        if subfieldname == "pin":
+            return self._derived_pin(point_count)
+        if "m" not in self._fields:
+            raise KeyError(f"Derived field '{subfieldname}' requires magnetisation.")
+
+        resolvers = {
+            "phi": self._derived_phi,
+            "rho": self._derived_rho,
+            "H_anis": self._derived_h_anis,
+            "H_exch": self._derived_h_exch,
+            "dm_dcurrent": self._derived_dm_dcurrent,
+            "dmdt": self._derived_dmdt,
+            "M": self._derived_magnetisation,
+            "H_total": self._derived_h_total,
+            "E_anis": self._derived_e_anis,
+            "E_exch": self._derived_e_exch,
+            "E_ext": self._derived_e_ext,
+            "E_demag": self._derived_e_demag,
+            "E_total": self._derived_e_total,
+        }
+        resolver = resolvers.get(subfieldname)
+        if resolver is None:
+            raise KeyError(f"Unknown or unset subfield '{subfieldname}'.") from None
+        return resolver(point_count)
+
+    def _derived_pin(self, point_count: int) -> np.ndarray:
+        return np.asarray(
+            self._fields.get("pin", np.ones(point_count, dtype=float)),
+            dtype=float,
+        )
+
+    def _derived_phi(self, point_count: int) -> np.ndarray:
+        if not self.do_demag:
+            return np.zeros(point_count, dtype=float)
+        phi, _rho, _volumes = self._get_demag_auxiliary_fields()
+        return phi
+
+    def _derived_rho(self, point_count: int) -> np.ndarray:
+        if not self.do_demag:
+            return np.zeros(point_count, dtype=float)
+        _phi, rho, _volumes = self._get_demag_auxiliary_fields()
+        return rho
+
+    def _derived_h_anis(self, point_count: int) -> np.ndarray:
+        field, _energy = self._get_anisotropy_fields()
+        return field
+
+    def _derived_h_exch(self, _point_count: int) -> np.ndarray:
+        return self._get_exchange_nodal_field()
+
+    def _derived_dm_dcurrent(self, _point_count: int) -> np.ndarray:
+        return self._get_dm_dcurrent()
+
+    def _derived_dmdt(self, _point_count: int) -> np.ndarray:
+        coefficients = self._nodal_material_coefficients()
+        m = np.asarray(self._fields["m"], dtype=float)
+        dmdt_scale_values = np.full(len(m), LEGACY_DMDT_MAGNETISATION_SCALE, dtype=float)
+        dm_dcurrent = (
+            self._subfield_array("dm_dcurrent") if "current_density" in self._fields else None
+        )
+        backend = self._llg_backend(len(m))
+        rhs = self._llg_rhs_rust if backend == "rust" else self._llg_rhs_python
+        with self._record_active_subfield_array_timing_block(f"dmdt_detail:llg_rhs:{backend}"):
+            return rhs(
+                m,
+                self._subfield_array("H_total"),
+                self._subfield_array("pin"),
+                dmdt_scale_values,
+                coefficients.precession,
+                coefficients.damping,
+                coefficients.normalisation,
+                dm_dcurrent,
+                coefficients.stt_adiabatic,
+                coefficients.stt_nonadiabatic,
+            )
+
+    def _llg_backend(self, point_count: int) -> str:
+        return _simulation_compatibility_binding("_selected_llg_backend", _selected_llg_backend)(
+            point_count, getattr(self, "config", None)
+        )
+
+    def _derived_magnetisation(self, _point_count: int) -> np.ndarray:
+        return np.asarray(self._fields["m"], dtype=float) * self._nodal_ms_values()[:, np.newaxis]
+
+    def _derived_h_total(self, _point_count: int) -> np.ndarray:
+        h_total = np.asarray(self._subfield_array("H_ext"), dtype=float)
+        if self.do_demag:
+            h_total = h_total + np.asarray(self._subfield_array("H_demag"), dtype=float)
+        return h_total + self._subfield_array("H_anis") + self._subfield_array("H_exch")
+
+    def _derived_e_anis(self, point_count: int) -> np.ndarray:
+        _field, energy = self._get_anisotropy_fields()
+        return energy
+
+    def _derived_e_exch(self, _point_count: int) -> np.ndarray:
+        return (
+            -0.5
+            * MU0
+            * self._nodal_ms_values()
+            * np.einsum(
+                "ij,ij->i",
+                self._subfield_array("H_exch"),
+                np.asarray(self._fields["m"], dtype=float),
+            )
+        )
+
+    def _derived_e_ext(self, _point_count: int) -> np.ndarray:
+        return -MU0 * np.einsum(
+            "ij,ij->i",
+            self._subfield_array("M"),
+            self._subfield_array("H_ext"),
+        )
+
+    def _derived_e_demag(self, point_count: int) -> np.ndarray:
+        if not self.do_demag:
+            return np.zeros(point_count, dtype=float)
+        return (
+            -0.5
+            * MU0
+            * np.einsum(
+                "ij,ij->i",
+                self._subfield_array("M"),
+                self._subfield_array("H_demag"),
+            )
+        )
+
+    def _derived_e_total(self, _point_count: int) -> np.ndarray:
+        return (
+            self._subfield_array("E_ext")
+            + self._subfield_array("E_anis")
+            + self._subfield_array("E_exch")
+            + self._subfield_array("E_demag")
+        )
+
+    def _exchange_is_zero_by_construction(self) -> bool:
+        if "m" not in self._fields:
+            return False
+        m = np.asarray(self._fields["m"], dtype=float)
+        if m.ndim != 2 or len(m) == 0:
+            return False
+        return bool(np.allclose(m, m[0], rtol=0.0, atol=1.0e-12))

nmag/simulation/fields/maxangle.py

@@ -0,0 +1,163 @@
+from __future__ import annotations
+
+import time
+from typing import TYPE_CHECKING, Any
+
+import numpy as np
+
+from ...backends import (
+    _load_rust_accelerator,
+    _selected_maxangle_backend,
+)
+from ...demag import _normalised
+from ..support import _simulation_compatibility_binding
+
+
+class SimulationFieldMaxangleMixin:
+    if TYPE_CHECKING:
+
+        def __getattr__(self, name: str) -> Any: ...
+
+    def get_maxangle_average(self, field_name: str) -> float | None:
+        """Return the maximum neighboring magnetization angle in degrees.
+
+        Args:
+            field_name: Currently only ``"m"`` is supported.
+
+        Returns:
+            Maximum angle across mesh edges, or ``None`` when magnetization or
+            a suitable mesh is unavailable.
+        """
+        timings: dict[str, float] = {}
+        total_started = time.perf_counter()
+        self.last_maxangle_timings_seconds = {}
+        inputs = self._maxangle_inputs(field_name, timings)
+        if inputs is None:
+            return self._finish_maxangle(timings, total_started, None)
+        m, simplices = inputs
+        if self._is_uniform_magnetisation(m, timings):
+            return self._finish_maxangle(timings, total_started, 0.0)
+        backend = _simulation_compatibility_binding(
+            "_selected_maxangle_backend", _selected_maxangle_backend
+        )(getattr(self, "config", None))
+        if backend == "rust":
+            return self._finish_maxangle(
+                timings,
+                total_started,
+                self._timed_rust_maxangle(m, simplices, timings),
+            )
+        return self._finish_maxangle(
+            timings,
+            total_started,
+            self._timed_python_maxangle(m, timings),
+        )
+
+    def _finish_maxangle(
+        self,
+        timings: dict[str, float],
+        total_started: float,
+        value: float | None,
+    ) -> float | None:
+        timings["total"] = time.perf_counter() - total_started
+        self.last_maxangle_timings_seconds = dict(sorted(timings.items()))
+        return value
+
+    def _maxangle_inputs(
+        self,
+        field_name: str,
+        timings: dict[str, float] | None,
+    ) -> tuple[np.ndarray, np.ndarray] | None:
+        if field_name != "m" or "m" not in self._fields or self.mesh is None:
+            return None
+        started = time.perf_counter()
+        m = np.asarray(self._fields["m"], dtype=float)
+        simplices = np.asarray(self._require_mesh().simplices, dtype=int)
+        if timings is not None:
+            timings["input_arrays"] = time.perf_counter() - started
+        if m.ndim != 2 or m.shape[1] != 3 or simplices.ndim != 2 or simplices.shape[1] < 2:
+            return None
+        return (m, simplices) if len(m) > 0 else None
+
+    def _is_uniform_magnetisation(self, m: np.ndarray, timings: dict[str, float]) -> bool:
+        started = time.perf_counter()
+        is_uniform = bool(np.all(m == m[0]))
+        timings["uniform_check"] = time.perf_counter() - started
+        return is_uniform
+
+    def _timed_rust_maxangle(
+        self,
+        m: np.ndarray,
+        simplices: np.ndarray,
+        timings: dict[str, float],
+    ) -> float:
+        started = time.perf_counter()
+        maxangle = self._maxangle_average_rust(m, simplices)
+        timings["mesh_edges_and_angles:rust"] = time.perf_counter() - started
+        return maxangle
+
+    def _timed_python_maxangle(self, m: np.ndarray, timings: dict[str, float]) -> float:
+        started = time.perf_counter()
+        edges = self._mesh_edges()
+        timings["mesh_edges"] = time.perf_counter() - started
+        if len(edges) == 0:
+            return 0.0
+
+        started = time.perf_counter()
+        # set_m normalises stored magnetisation vectors, so maxangle can use
+        # the cached nodal rows directly instead of renormalising every edge.
+        edge_values = m[edges]
+        dots = np.einsum("ij,ij->i", edge_values[:, 0, :], edge_values[:, 1, :])
+        if dots.size == 0:
+            timings["edge_angles"] = time.perf_counter() - started
+            return 0.0
+        bounded_dots = np.minimum(np.maximum(dots, -1.0), 1.0)
+        maxangle = float(np.max(np.arccos(bounded_dots))) * 180.0 / np.pi
+        timings["edge_angles"] = time.perf_counter() - started
+        return maxangle
+
+    def _maxangle_average_rust(self, m: np.ndarray, simplices: np.ndarray) -> float:
+        rust_accel = _simulation_compatibility_binding(
+            "_load_rust_accelerator", _load_rust_accelerator
+        )("NmagConfig.accelerator['maxangle']")
+        try:
+            return float(rust_accel.maxangle_between_edges(m, simplices))
+        except AttributeError as exc:
+            raise RuntimeError(
+                "NmagConfig.accelerator['maxangle']='rust' requires an nmag_accel build with "
+                "maxangle_between_edges. Rebuild it with "
+                "`maturin develop --release --manifest-path rust/nmag_accel/Cargo.toml`."
+            ) from exc
+
+    def _maxangle_average_reference(self, field_name: str) -> float | None:
+        inputs = self._maxangle_inputs(field_name, None)
+        if inputs is None:
+            return None
+        m, simplices = inputs
+        if np.all(m == m[0]):
+            return 0.0
+        return self._reference_maxangle_from_simplices(m, simplices)
+
+    def _reference_maxangle_from_simplices(
+        self,
+        m: np.ndarray,
+        simplices: np.ndarray,
+    ) -> float:
+        max_angle = 0.0
+        seen_edges: set[tuple[int, int]] = set()
+        for simplex in simplices:
+            for left_position, left in enumerate(simplex):
+                for right in simplex[left_position + 1 :]:
+                    edge = (min(int(left), int(right)), max(int(left), int(right)))
+                    if edge in seen_edges:
+                        continue
+                    seen_edges.add(edge)
+                    left_m = _simulation_compatibility_binding("_normalised", _normalised)(
+                        m[edge[0]]
+                    )
+                    right_m = _simulation_compatibility_binding("_normalised", _normalised)(
+                        m[edge[1]]
+                    )
+                    raw_dot = float(np.sum(left_m * right_m))
+                    dot = min(1.0, max(-1.0, raw_dot))
+                    max_angle = max(max_angle, float(np.arccos(dot)))
+        return max_angle * 180.0 / np.pi