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

nmag/dynamics/__init__.py

@@ -0,0 +1,255 @@
+from __future__ import annotations
+
+from collections import deque
+from dataclasses import dataclass, field
+from math import isfinite
+from typing import cast
+
+import numpy as np
+from numpy.typing import NDArray
+
+FloatArray = NDArray[np.float64]
+
+DEFAULT_STOPPING_DM_DT = float(np.deg2rad(1.0) * 1.0e9)
+DOP853_EXCHANGE_RESOLUTION_RADIUS = 3.0
+
+
+@dataclass(frozen=True, slots=True)
+class NodalMaterialCoefficients:
+    exchange_prefactor: FloatArray
+    precession: FloatArray
+    damping: FloatArray
+    normalisation: FloatArray
+    stt_adiabatic: FloatArray
+    stt_nonadiabatic: FloatArray
+
+
+@dataclass(slots=True)
+class IntegratorConfig:
+    """Snapshot of effective public DOP853 controls.
+
+    Attributes:
+        relative_tolerance: Relative local-error tolerance.
+        absolute_tolerance: Absolute local-error tolerance.
+        maximum_step_seconds: Configured upper step bound in seconds.
+        exact_tstop: Whether fixed-time requests normally stop exactly.
+    """
+
+    relative_tolerance: float = 1.0e-6
+    absolute_tolerance: float = 1.0e-6
+    maximum_step_seconds: float = 1.0e-12
+    exact_tstop: bool = True
+
+    def validate(self) -> None:
+        for name, value in (
+            ("relative_tolerance", self.relative_tolerance),
+            ("absolute_tolerance", self.absolute_tolerance),
+            ("maximum_step_seconds", self.maximum_step_seconds),
+        ):
+            if not np.isfinite(value) or value <= 0.0:
+                raise ValueError(f"{name} must be a positive finite number, got {value!r}.")
+
+
+@dataclass(frozen=True, slots=True)
+class IntegratorStats:
+    """Measurements from the most recent integration operation.
+
+    Attributes:
+        accepted_steps: Accepted adaptive steps.
+        rhs_evaluations: Landau-Lifshitz-Gilbert right-hand-side evaluations.
+        rejected_steps: Rejected steps when the backend reports them.
+        failed: Whether the operation raised a numerical failure.
+        status: Backend status at completion.
+        last_step_seconds: Size of the final accepted step.
+        simulated_seconds: Physical time advanced by the operation.
+        wall_seconds: Elapsed wall-clock time.
+        jacobian_vector_evaluations: Optional implicit-backend measurement.
+        nonlinear_iterations: Optional implicit-backend Newton iterations.
+        nonlinear_failures: Optional implicit-backend failure count.
+        linear_solver_setups: Optional implicit-backend setup count.
+    """
+
+    accepted_steps: int = 0
+    rhs_evaluations: int = 0
+    rejected_steps: int | None = None
+    failed: bool = False
+    status: str = "not_started"
+    last_step_seconds: float = 0.0
+    simulated_seconds: float = 0.0
+    wall_seconds: float = 0.0
+    jacobian_vector_evaluations: int | None = None
+    nonlinear_iterations: int | None = None
+    nonlinear_failures: int | None = None
+    linear_solver_setups: int | None = None
+
+
+@dataclass(slots=True)
+class ConvergenceTracker:
+    required_checks: int = 2
+    statistics_window: int = 5
+    _remaining_checks: int = field(init=False)
+    _history: deque[tuple[int, float, float, float | None]] = field(
+        default_factory=lambda: deque(maxlen=50),
+        init=False,
+    )
+    _previous_max_dm_dt: float | None = field(default=None, init=False)
+    _window_changes: list[float] = field(default_factory=lambda: list[float](), init=False)
+
+    def __post_init__(self) -> None:
+        if self.required_checks < 1:
+            raise ValueError("required_checks must be at least one.")
+        if self.statistics_window < 1:
+            raise ValueError("statistics_window must be at least one.")
+        self._remaining_checks = self.required_checks
+
+    def reset(self) -> None:
+        self._remaining_checks = self.required_checks
+        self._previous_max_dm_dt = None
+        self._window_changes.clear()
+
+    def check(self, step: int, max_dm_dt: float, stopping_dm_dt: float) -> bool:
+        if max_dm_dt < stopping_dm_dt:
+            self._remaining_checks -= 1
+            if self._remaining_checks == 0:
+                self.reset()
+                return True
+            return False
+
+        self._remaining_checks = self.required_checks
+        quality = self._quality(max_dm_dt)
+        self._history.append((step, max_dm_dt, stopping_dm_dt, quality))
+        return False
+
+    def _quality(self, max_dm_dt: float) -> float | None:
+        if self._previous_max_dm_dt is None:
+            self._previous_max_dm_dt = max_dm_dt
+            return None
+
+        self._window_changes.append(max_dm_dt - self._previous_max_dm_dt)
+        self._previous_max_dm_dt = max_dm_dt
+        if len(self._window_changes) < self.statistics_window:
+            return None
+
+        signed = abs(sum(self._window_changes))
+        absolute = sum(abs(change) for change in self._window_changes)
+        self._window_changes.clear()
+        return signed / absolute if absolute > 0.0 else None
+
+    def get_log(self) -> str:
+        lines = ["# Convergence log", "# step, max dm/dt, stopping dm/dt, quality"]
+        lines.extend(
+            f"{step} {max_dm_dt} {stopping_dm_dt} {quality}"
+            for step, max_dm_dt, stopping_dm_dt, quality in self._history
+        )
+        return "\n".join(lines) + "\n"
+
+    def checkpoint_state(self) -> dict[str, object]:
+        """Return the convergence cadence state without exposing mutable internals."""
+        return {
+            "required_checks": self.required_checks,
+            "statistics_window": self.statistics_window,
+            "remaining_checks": self._remaining_checks,
+            "history": [list(entry) for entry in self._history],
+            "previous_max_dm_dt": self._previous_max_dm_dt,
+            "window_changes": list(self._window_changes),
+        }
+
+    @classmethod
+    def from_checkpoint_state(cls, state: dict[str, object]) -> ConvergenceTracker:
+        cls._validate_checkpoint_keys(state)
+        required_checks, statistics_window, remaining_checks = cls._checkpoint_counters(state)
+        tracker = cls(
+            required_checks=required_checks,
+            statistics_window=statistics_window,
+        )
+        if not 1 <= remaining_checks <= tracker.required_checks:
+            raise ValueError("Checkpoint remaining convergence checks are invalid.")
+        tracker._remaining_checks = remaining_checks
+        tracker._history = cls._checkpoint_history(state["history"])
+        tracker._previous_max_dm_dt = cls._optional_finite_checkpoint_value(
+            state["previous_max_dm_dt"],
+            "Checkpoint previous convergence rate must be finite or null.",
+        )
+        tracker._window_changes = cls._finite_checkpoint_values(
+            state["window_changes"],
+            "Checkpoint convergence window changes must be finite numbers.",
+        )
+        return tracker
+
+    @staticmethod
+    def _validate_checkpoint_keys(state: dict[str, object]) -> None:
+        required = {
+            "required_checks",
+            "statistics_window",
+            "remaining_checks",
+            "history",
+            "previous_max_dm_dt",
+            "window_changes",
+        }
+        missing = sorted(required.difference(state))
+        if missing:
+            raise ValueError(f"Checkpoint convergence state is missing {', '.join(missing)}.")
+
+    @staticmethod
+    def _checkpoint_counters(state: dict[str, object]) -> tuple[int, int, int]:
+        values = tuple(
+            state[name] for name in ("required_checks", "statistics_window", "remaining_checks")
+        )
+        if any(isinstance(value, bool) or not isinstance(value, int) for value in values):
+            raise ValueError("Checkpoint convergence counters must be integers.")
+        return cast(tuple[int, int, int], values)
+
+    @classmethod
+    def _checkpoint_history(cls, value: object) -> deque[tuple[int, float, float, float | None]]:
+        if not isinstance(value, list):
+            raise ValueError("Checkpoint convergence history must be a list.")
+        history: deque[tuple[int, float, float, float | None]] = deque(maxlen=50)
+        for raw_entry in cast(list[object], value):
+            history.append(cls._checkpoint_history_entry(raw_entry))
+        return history
+
+    @classmethod
+    def _checkpoint_history_entry(cls, value: object) -> tuple[int, float, float, float | None]:
+        if not isinstance(value, list):
+            raise ValueError("Checkpoint convergence history entries must have four values.")
+        entry = cast(list[object], value)
+        if len(entry) != 4:
+            raise ValueError("Checkpoint convergence history entries must have four values.")
+        step, maximum, stopping, quality = entry
+        if isinstance(step, bool) or not isinstance(step, int):
+            raise ValueError("Checkpoint convergence history steps must be integers.")
+        rates = cls._finite_checkpoint_values(
+            [maximum, stopping],
+            "Checkpoint convergence history rates must be finite.",
+        )
+        return (
+            step,
+            rates[0],
+            rates[1],
+            cls._optional_finite_checkpoint_value(
+                quality,
+                "Checkpoint convergence history quality must be finite or null.",
+            ),
+        )
+
+    @staticmethod
+    def _optional_finite_checkpoint_value(value: object, message: str) -> float | None:
+        if value is None:
+            return None
+        values = ConvergenceTracker._finite_checkpoint_values([value], message)
+        return values[0]
+
+    @staticmethod
+    def _finite_checkpoint_values(value: object, message: str) -> list[float]:
+        if not isinstance(value, list):
+            raise ValueError(message)
+        parsed: list[float] = []
+        for raw_value in cast(list[object], value):
+            if (
+                isinstance(raw_value, bool)
+                or not isinstance(raw_value, (int, float))
+                or not isfinite(float(raw_value))
+            ):
+                raise ValueError(message)
+            parsed.append(float(raw_value))
+        return parsed

nmag/output.py

@@ -0,0 +1,27 @@
+"""Output-file lifecycle helpers shared by simulation implementations."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from pathlib import Path
+
+from .config import OutputPolicy
+
+
+def prepare_output_files(paths: Iterable[Path], policy: OutputPolicy) -> None:
+    """Create parents and apply an explicit output lifecycle policy."""
+
+    destinations = tuple(paths)
+    for destination in destinations:
+        destination.parent.mkdir(parents=True, exist_ok=True)
+
+    existing = tuple(destination for destination in destinations if destination.exists())
+    if policy == "error" and existing:
+        rendered = ", ".join(str(destination) for destination in existing)
+        raise FileExistsError(
+            f"Output file(s) already exist: {rendered}. "
+            "Use NmagConfig(output_policy='replace' or 'append') explicitly."
+        )
+    if policy == "replace":
+        for destination in existing:
+            destination.unlink()

nmag/parallel.py

@@ -0,0 +1,45 @@
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+
+from .backends import _load_rust_accelerator, _rust_accelerator_available
+
+
+@dataclass(frozen=True, slots=True)
+class ParallelRuntimeInfo:
+    """Shared-memory execution settings visible to the current process.
+
+    Attributes:
+        logical_cpus: Logical processors reported by the operating system.
+        rust_available: Whether a compatible native extension is installed.
+        rust_worker_threads: Rayon worker count when Rust is available.
+        rust_parallel_min_items: Operation-size crossover for parallel kernels.
+    """
+
+    logical_cpus: int
+    rust_available: bool
+    rust_worker_threads: int | None
+    rust_parallel_min_items: int | None
+
+
+def parallel_runtime_info() -> ParallelRuntimeInfo:
+    """Return effective Rust worker and crossover settings without changing them."""
+    logical_cpus = os.cpu_count() or 1
+    if not _rust_accelerator_available():
+        return ParallelRuntimeInfo(logical_cpus, False, None, None)
+
+    accelerator = _load_rust_accelerator("NmagConfig.accelerator")
+    try:
+        worker_threads, minimum_items = accelerator.parallel_runtime_info()
+    except AttributeError as exc:
+        raise RuntimeError(
+            "The installed nmag_accel does not expose parallel runtime metadata. "
+            "Rebuild it with ./scripts/build-accelerator.sh."
+        ) from exc
+    return ParallelRuntimeInfo(
+        logical_cpus=logical_cpus,
+        rust_available=True,
+        rust_worker_threads=int(worker_threads),
+        rust_parallel_min_items=int(minimum_items),
+    )

nmag/py.typed

@@ -0,0 +1 @@
+# Marker for PEP 561 inline type information.

nmag/resources.py

@@ -0,0 +1,38 @@
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+
+def _read_integer(path: Path) -> int | None:
+    try:
+        raw_value = path.read_text(encoding="ascii").strip()
+        return None if raw_value == "max" else int(raw_value)
+    except (OSError, ValueError):
+        return None
+
+
+def available_memory_bytes() -> int | None:
+    """Return the tightest host or cgroup estimate of currently available memory."""
+    candidates: list[int] = []
+    try:
+        page_size = int(os.sysconf("SC_PAGE_SIZE"))
+        available_pages = int(os.sysconf("SC_AVPHYS_PAGES"))
+        if page_size > 0 and available_pages > 0:
+            candidates.append(page_size * available_pages)
+    except (KeyError, OSError, ValueError):
+        pass
+
+    for limit_path, usage_path in (
+        (Path("/sys/fs/cgroup/memory.max"), Path("/sys/fs/cgroup/memory.current")),
+        (
+            Path("/sys/fs/cgroup/memory/memory.limit_in_bytes"),
+            Path("/sys/fs/cgroup/memory/memory.usage_in_bytes"),
+        ),
+    ):
+        limit = _read_integer(limit_path)
+        usage = _read_integer(usage_path)
+        if limit is not None and usage is not None and limit > usage:
+            candidates.append(limit - usage)
+
+    return min(candidates) if candidates else None