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

nmag/checkpoint.py

@@ -0,0 +1,327 @@
+"""Native HDF5 checkpoints for the supported Python 3 simulation state."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, cast
+
+import h5py
+import numpy as np
+
+from anisotropy import anisotropy_signature_values
+from si.physical import SI
+from simulation.clock import SimulationClock
+
+from .dynamics import ConvergenceTracker, IntegratorConfig
+
+CHECKPOINT_FORMAT = "nmag-python-3-checkpoint"
+CHECKPOINT_VERSION = 1
+
+
+@dataclass(frozen=True, slots=True)
+class CheckpointContents:
+    magnetisation: np.ndarray
+    pinning: np.ndarray
+    external_field: np.ndarray
+    current_density: np.ndarray | None
+    metadata: dict[str, object]
+
+
+@dataclass(frozen=True, slots=True)
+class RestartRuntimeState:
+    clock: SimulationClock
+    integrator_config: IntegratorConfig
+    stopping_dm_dt: float
+    maximum_time_seconds: float
+    maximum_dm_dt: float | None
+    convergence: ConvergenceTracker
+
+
+def _array_fingerprint(digest: Any, label: str, values: object, dtype: Any) -> None:
+    array = np.ascontiguousarray(np.asarray(values, dtype=dtype))
+    digest.update(label.encode("ascii"))
+    digest.update(str(array.shape).encode("ascii"))
+    digest.update(str(array.dtype).encode("ascii"))
+    digest.update(array.tobytes())
+
+
+def mesh_fingerprint(simulation: Any) -> str:
+    """Return a stable hash of the loaded physical mesh and its topology."""
+    mesh = simulation._require_mesh()
+    simplices = np.asarray(mesh.simplices, dtype=np.int64)
+    regions_raw = mesh.regions
+    regions = np.asarray(
+        [1] * len(simplices) if regions_raw is None else regions_raw,
+        dtype=np.int64,
+    )
+    digest = hashlib.sha256()
+    _array_fingerprint(digest, "points", simulation._mesh_points(), np.dtype(np.float64))
+    _array_fingerprint(digest, "simplices", simplices, np.dtype(np.int64))
+    _array_fingerprint(digest, "regions", regions, np.dtype(np.int64))
+    return digest.hexdigest()
+
+
+def material_fingerprint(simulation: Any) -> str:
+    """Hash mesh-region material values that influence supported dynamics.
+
+    Saturation magnetisation is represented per simplex here rather than by
+    volume-averaged nodal recovery. The latter can differ by harmless last-bit
+    geometry-kernel roundoff after a run, which must not make an otherwise
+    compatible checkpoint unloadable.
+    """
+    coefficients = simulation._nodal_material_coefficients()
+    mesh = simulation._require_mesh()
+    regions = np.asarray(mesh.regions or [1] * len(mesh.simplices), dtype=np.int64)
+    digest = hashlib.sha256()
+    for name, values in (
+        ("simplex_ms", simulation._simplex_material_ms_values(regions)),
+        ("volume_charge_scale", simulation._simplex_volume_charge_scales(regions)),
+        ("exchange_prefactor", coefficients.exchange_prefactor),
+        ("precession", coefficients.precession),
+        ("damping", coefficients.damping),
+        ("normalisation", coefficients.normalisation),
+        ("stt_adiabatic", coefficients.stt_adiabatic),
+        ("stt_nonadiabatic", coefficients.stt_nonadiabatic),
+    ):
+        _array_fingerprint(digest, name, values, np.dtype(np.float64))
+    for region in np.unique(regions):
+        material = simulation._simplex_material(int(region))
+        signature = anisotropy_signature_values(
+            material.anisotropy,
+            material.anisotropy_order,
+        )
+        _array_fingerprint(
+            digest,
+            f"anisotropy:{int(region)}",
+            signature,
+            np.dtype(np.float64),
+        )
+    return digest.hexdigest()
+
+
+def _finite_array(name: str, values: object, shape: tuple[int, ...]) -> np.ndarray:
+    array = np.ascontiguousarray(np.asarray(values, dtype=np.float64))
+    if array.shape != shape:
+        raise ValueError(f"Checkpoint {name} must have shape {shape}, got {array.shape}.")
+    if not np.all(np.isfinite(array)):
+        raise ValueError(f"Checkpoint {name} values must be finite.")
+    return array
+
+
+def _finite_number(name: str, value: object, *, positive: bool = False) -> float:
+    if isinstance(value, bool) or not isinstance(value, (int, float)):
+        raise ValueError(f"Checkpoint {name} must be a finite number.")
+    number = float(value)
+    if not np.isfinite(number) or (positive and number <= 0.0):
+        qualifier = "positive finite" if positive else "finite"
+        raise ValueError(f"Checkpoint {name} must be a {qualifier} number.")
+    return number
+
+
+def _snapshot(simulation: Any) -> CheckpointContents:
+    point_count = len(simulation._mesh_points())
+    if "m" not in simulation._fields:
+        raise RuntimeError("Magnetisation must be set before saving a restart checkpoint.")
+
+    magnetisation = _finite_array("magnetisation", simulation._fields["m"], (point_count, 3))
+    pinning = _finite_array(
+        "pinning",
+        simulation._fields.get("pin", np.ones(point_count, dtype=float)),
+        (point_count,),
+    )
+    external_field = _finite_array(
+        "external field",
+        simulation._fields.get("H_ext", np.zeros(3, dtype=float)),
+        (3,),
+    )
+    current_density = None
+    if "current_density" in simulation._fields:
+        current_density = _finite_array(
+            "current density",
+            simulation._fields["current_density"],
+            (point_count, 3),
+        )
+
+    config = simulation.integrator_config
+    config.validate()
+    max_dm_dt = simulation.max_dm_dt
+    if max_dm_dt is not None:
+        max_dm_dt = _finite_number("maximum dm/dt", max_dm_dt)
+    dynamics_state: dict[str, object] = {
+        "relative_tolerance": config.relative_tolerance,
+        "absolute_tolerance": config.absolute_tolerance,
+        "maximum_step_seconds": config.maximum_step_seconds,
+        "exact_tstop": config.exact_tstop,
+        "stopping_dm_dt": _finite_number(
+            "stopping dm/dt", simulation.stopping_dm_dt, positive=True
+        ),
+        "maximum_time_seconds": simulation.max_time_reached.in_units_of(SI(1.0, "s")),
+        "maximum_dm_dt": max_dm_dt,
+        "convergence": simulation.convergence.checkpoint_state(),
+    }
+    _finite_number("maximum time", dynamics_state["maximum_time_seconds"], positive=True)
+    metadata: dict[str, object] = {
+        "mesh_fingerprint": mesh_fingerprint(simulation),
+        "material_fingerprint": material_fingerprint(simulation),
+        "do_demag": bool(simulation.do_demag),
+        "clock": simulation.clock.checkpoint_state(),
+        "dynamics": dynamics_state,
+    }
+    return CheckpointContents(magnetisation, pinning, external_field, current_density, metadata)
+
+
+def save_checkpoint(simulation: Any, destination: Path) -> Path:
+    """Atomically persist a complete native checkpoint and return its path."""
+    contents = _snapshot(simulation)
+    destination = destination.expanduser()
+    temporary = destination.with_name(f".{destination.name}.tmp")
+    try:
+        with h5py.File(str(temporary), "w") as h5:
+            h5.attrs["format"] = CHECKPOINT_FORMAT
+            h5.attrs["version"] = CHECKPOINT_VERSION
+            h5.attrs["metadata"] = json.dumps(contents.metadata, allow_nan=False, sort_keys=True)
+            state = h5.create_group("state")
+            state.create_dataset("m", data=contents.magnetisation, dtype=np.float64)
+            state.create_dataset("pin", data=contents.pinning, dtype=np.float64)
+            state.create_dataset("H_ext", data=contents.external_field, dtype=np.float64)
+            if contents.current_density is not None:
+                state.create_dataset(
+                    "current_density",
+                    data=contents.current_density,
+                    dtype=np.float64,
+                )
+            h5.flush()
+        with temporary.open("rb") as checkpoint_file:
+            os.fsync(checkpoint_file.fileno())
+        os.replace(temporary, destination)
+    except Exception:
+        temporary.unlink(missing_ok=True)
+        raise
+    return destination
+
+
+def _attribute_text(value: object, name: str) -> str:
+    if isinstance(value, bytes):
+        return value.decode("utf-8")
+    if isinstance(value, str):
+        return value
+    raise ValueError(f"Checkpoint {name} attribute must be text.")
+
+
+def read_checkpoint(filename: Path, point_count: int) -> CheckpointContents:
+    """Read and fully validate native checkpoint data without mutating a simulation."""
+    try:
+        with h5py.File(str(filename), "r") as h5:
+            if _attribute_text(h5.attrs.get("format"), "format") != CHECKPOINT_FORMAT:
+                raise ValueError("File is not an nmag-python-3 native checkpoint.")
+            version = cast(object, h5.attrs.get("version"))
+            if isinstance(version, bool) or not isinstance(version, (int, np.integer)):
+                raise ValueError("Checkpoint version must be an integer.")
+            if str(cast(object, version)) != str(CHECKPOINT_VERSION):
+                raise ValueError(
+                    f"Unsupported checkpoint version {version}; expected {CHECKPOINT_VERSION}."
+                )
+            try:
+                decoded_metadata = json.loads(_attribute_text(h5.attrs.get("metadata"), "metadata"))
+            except json.JSONDecodeError as exc:
+                raise ValueError("Checkpoint metadata is not valid JSON.") from exc
+            if not isinstance(decoded_metadata, dict):
+                raise ValueError("Checkpoint metadata must be an object.")
+            metadata = cast(dict[str, object], decoded_metadata)
+            try:
+                state = h5["state"]
+                if not isinstance(state, h5py.Group):
+                    raise ValueError("Checkpoint state must be an HDF5 group.")
+                magnetisation = _finite_array("magnetisation", state["m"], (point_count, 3))
+                pinning = _finite_array("pinning", state["pin"], (point_count,))
+                external_field = _finite_array("external field", state["H_ext"], (3,))
+                current_density = (
+                    _finite_array("current density", state["current_density"], (point_count, 3))
+                    if "current_density" in state
+                    else None
+                )
+            except KeyError as exc:
+                raise ValueError(
+                    f"Checkpoint is missing required state dataset {exc.args[0]!r}."
+                ) from exc
+    except OSError as exc:
+        raise ValueError(f"Unable to read checkpoint {filename}: {exc}") from exc
+    return CheckpointContents(magnetisation, pinning, external_field, current_density, metadata)
+
+
+def validate_mesh(simulation: Any, contents: CheckpointContents) -> None:
+    saved = contents.metadata.get("mesh_fingerprint")
+    if not isinstance(saved, str):
+        raise ValueError("Checkpoint metadata is missing a mesh fingerprint.")
+    if saved != mesh_fingerprint(simulation):
+        raise ValueError("Checkpoint mesh does not match the loaded simulation mesh.")
+
+
+def runtime_state(simulation: Any, contents: CheckpointContents) -> RestartRuntimeState:
+    """Validate full-restart compatibility and parse all non-array runtime state."""
+    validate_mesh(simulation, contents)
+    saved_material = contents.metadata.get("material_fingerprint")
+    if not isinstance(saved_material, str):
+        raise ValueError("Checkpoint metadata is missing a material fingerprint.")
+    if saved_material != material_fingerprint(simulation):
+        raise ValueError("Checkpoint materials do not match the loaded simulation.")
+    saved_demag = contents.metadata.get("do_demag")
+    if not isinstance(saved_demag, bool) or saved_demag != simulation.do_demag:
+        raise ValueError("Checkpoint demagnetization mode does not match the loaded simulation.")
+
+    clock_state = contents.metadata.get("clock")
+    dynamics = contents.metadata.get("dynamics")
+    if not isinstance(clock_state, dict) or not isinstance(dynamics, dict):
+        raise ValueError("Checkpoint metadata is missing clock or dynamics state.")
+    parsed_clock_state = cast(dict[str, object], clock_state)
+    parsed_dynamics = cast(dict[str, object], dynamics)
+    clock = SimulationClock.from_checkpoint_state(parsed_clock_state)
+    try:
+        exact_tstop = parsed_dynamics["exact_tstop"]
+        if not isinstance(exact_tstop, bool):
+            raise ValueError("Checkpoint exact_tstop must be a boolean.")
+        config = IntegratorConfig(
+            relative_tolerance=_finite_number(
+                "relative tolerance", parsed_dynamics["relative_tolerance"], positive=True
+            ),
+            absolute_tolerance=_finite_number(
+                "absolute tolerance", parsed_dynamics["absolute_tolerance"], positive=True
+            ),
+            maximum_step_seconds=_finite_number(
+                "maximum step", parsed_dynamics["maximum_step_seconds"], positive=True
+            ),
+            exact_tstop=exact_tstop,
+        )
+        config.validate()
+        stopping_dm_dt = _finite_number(
+            "stopping dm/dt", parsed_dynamics["stopping_dm_dt"], positive=True
+        )
+        maximum_time = _finite_number(
+            "maximum time", parsed_dynamics["maximum_time_seconds"], positive=True
+        )
+        maximum_dm_dt_raw = parsed_dynamics["maximum_dm_dt"]
+        maximum_dm_dt = (
+            None
+            if maximum_dm_dt_raw is None
+            else _finite_number("maximum dm/dt", maximum_dm_dt_raw)
+        )
+        convergence_state = parsed_dynamics["convergence"]
+    except KeyError as exc:
+        raise ValueError(f"Checkpoint dynamics state is missing {exc.args[0]!r}.") from exc
+    if not isinstance(convergence_state, dict):
+        raise ValueError("Checkpoint convergence state must be an object.")
+    convergence = ConvergenceTracker.from_checkpoint_state(
+        cast(dict[str, object], convergence_state)
+    )
+    return RestartRuntimeState(
+        clock,
+        config,
+        stopping_dm_dt,
+        maximum_time,
+        maximum_dm_dt,
+        convergence,
+    )

nmag/config.py

@@ -0,0 +1,174 @@
+"""Typed runtime configuration for supported Nmag Python workflows."""
+
+from __future__ import annotations
+
+import math
+import os
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from enum import Enum
+from numbers import Real
+from pathlib import Path
+from types import MappingProxyType
+from typing import Literal, cast
+
+AcceleratorMode = Literal["auto", "off", "rust"]
+OutputPolicy = Literal["error", "replace", "append"]
+IntegratorBackend = Literal["scipy", "diffsol"]
+DemagBemStorage = Literal["auto", "dense", "hierarchical", "matrix-free"]
+
+ACCELERATOR_ENV = "NMAG_ACCELERATOR"
+DEMAG_BEM_STORAGE_ENV = "NMAG_DEMAG_BEM_STORAGE_BACKEND"
+
+
+@dataclass(frozen=True, slots=True)
+class HierarchicalBemConfig:
+    """Control accuracy and resources for compressed Lindholm BEM.
+
+    Attributes:
+        relative_tolerance: Requested relative compression/certification error.
+        admissibility_eta: Geometric separation threshold for low-rank blocks.
+        leaf_size: Maximum cluster leaf size.
+        max_rank: Maximum accepted low-rank block rank.
+        validation_vectors: Random vectors used to certify completed action.
+        validation_rows: Exact rows sampled during certification.
+        memory_fraction: Fraction of currently available memory allowed for the
+            completed hierarchy.
+    """
+
+    relative_tolerance: float = 1.0e-6
+    admissibility_eta: float = 2.0
+    leaf_size: int = 32
+    max_rank: int = 128
+    validation_vectors: int = 4
+    validation_rows: int = 64
+    memory_fraction: float = 0.20
+
+    def __post_init__(self) -> None:
+        for name in ("relative_tolerance", "admissibility_eta", "memory_fraction"):
+            raw_value = getattr(self, name)
+            if type(raw_value) is bool or not isinstance(raw_value, Real):
+                raise TypeError(f"{name} must be a real number.")
+            value = float(raw_value)
+            if not math.isfinite(value) or value <= 0.0:
+                raise ValueError(f"{name} must be finite and positive.")
+            object.__setattr__(self, name, value)
+        if self.memory_fraction > 1.0:
+            raise ValueError("memory_fraction must not exceed 1.0.")
+        for name in ("leaf_size", "max_rank", "validation_vectors", "validation_rows"):
+            value = getattr(self, name)
+            if not isinstance(value, int) or isinstance(value, bool) or value <= 0:
+                raise ValueError(f"{name} must be a positive integer.")
+
+
+class RustKernel(str, Enum):
+    """Rust-accelerated calculation families accepted as override keys."""
+
+    LINDHOLM_BEM = "lindholm_bem"
+    PROBE_GEOMETRY = "probe_geometry"
+    FEM_GEOMETRY = "fem_geometry"
+    BOUNDARY_FACES = "boundary_faces"
+    FEM_ASSEMBLY = "fem_assembly"
+    NODAL_RECOVERY = "nodal_recovery"
+    CELL_AVERAGE = "cell_average"
+    LLG = "llg"
+    MAXANGLE = "maxangle"
+
+
+def _validate_mode(value: object, *, field_name: str) -> AcceleratorMode:
+    if not isinstance(value, str):
+        raise TypeError(f"{field_name} must be a string mode.")
+    if value not in {"auto", "off", "rust"}:
+        raise ValueError(f"{field_name} must be one of 'auto', 'off', or 'rust', got {value!r}.")
+    return cast(AcceleratorMode, value)
+
+
+def _empty_overrides() -> Mapping[RustKernel, AcceleratorMode]:
+    return {}
+
+
+@dataclass(frozen=True, slots=True)
+class NmagConfig:
+    """Define immutable output, acceleration, storage, and integrator policy.
+
+    Attributes:
+        default_name: Simulation name used when ``Simulation(name=...)`` is
+            omitted.
+        output_directory: Directory for NDT, HDF5, and default checkpoint files.
+            The directory must exist before output is written.
+        output_policy: ``"error"` protects old output, ``"replace"`` starts it
+            again, and ``"append"`` validates and extends the NDT schema.
+        accelerator: Global ``"auto"``, ``"off"``, or strict ``"rust"`` mode.
+        accelerator_overrides: Per-:class:`RustKernel` mode overrides.
+        integrator_backend: ``"scipy"`` or experimental ``"diffsol"``.
+        demag_bem_storage: ``"auto"``, ``"dense"``, ``"hierarchical"``, or
+            ``"matrix-free"`` boundary-operator storage.
+        hierarchical_bem: Accuracy and resource settings for hierarchy builds.
+    """
+
+    default_name: str = "nmag_simulation"
+    output_directory: Path = Path(".")
+    output_policy: OutputPolicy = "error"
+    accelerator: AcceleratorMode = "auto"
+    accelerator_overrides: Mapping[RustKernel, AcceleratorMode] = field(
+        default_factory=_empty_overrides
+    )
+    integrator_backend: IntegratorBackend = "scipy"
+    demag_bem_storage: DemagBemStorage = "auto"
+    hierarchical_bem: HierarchicalBemConfig = field(default_factory=HierarchicalBemConfig)
+
+    def __post_init__(self) -> None:
+        if not self.default_name:
+            raise ValueError("default_name must not be empty.")
+        if self.output_policy not in {"error", "replace", "append"}:
+            raise ValueError("output_policy must be 'error', 'replace', or 'append'.")
+        if self.integrator_backend not in {"scipy", "diffsol"}:
+            raise ValueError("integrator_backend must be 'scipy' or 'diffsol'.")
+        if self.demag_bem_storage not in {"auto", "dense", "hierarchical", "matrix-free"}:
+            raise ValueError(
+                "demag_bem_storage must be 'auto', 'dense', 'hierarchical', or 'matrix-free'."
+            )
+        if not isinstance(cast(object, self.hierarchical_bem), HierarchicalBemConfig):
+            raise TypeError("hierarchical_bem must be a HierarchicalBemConfig instance.")
+        object.__setattr__(self, "output_directory", Path(self.output_directory).expanduser())
+        object.__setattr__(
+            self,
+            "accelerator",
+            _validate_mode(self.accelerator, field_name="accelerator"),
+        )
+
+        validated_overrides: dict[RustKernel, AcceleratorMode] = {}
+        raw_overrides = cast(Mapping[object, object], self.accelerator_overrides)
+        for raw_kernel, raw_mode in raw_overrides.items():
+            if not isinstance(raw_kernel, RustKernel):
+                raise TypeError("accelerator_overrides keys must be RustKernel values.")
+            validated_overrides[raw_kernel] = _validate_mode(
+                raw_mode,
+                field_name=f"accelerator_overrides[{raw_kernel.value!r}]",
+            )
+        object.__setattr__(
+            self,
+            "accelerator_overrides",
+            MappingProxyType(validated_overrides),
+        )
+
+    @classmethod
+    def from_environment(cls) -> NmagConfig:
+        """Build default configuration from supported process-level selectors.
+
+        Returns:
+            Configuration using ``NMAG_ACCELERATOR`` and
+            ``NMAG_DEMAG_BEM_STORAGE_BACKEND`` when set.
+        """
+
+        accelerator = os.environ.get(ACCELERATOR_ENV, "auto").strip().lower()
+        bem_storage = os.environ.get(DEMAG_BEM_STORAGE_ENV, "auto").strip().lower()
+        return cls(
+            accelerator=_validate_mode(accelerator, field_name=ACCELERATOR_ENV),
+            demag_bem_storage=cast(DemagBemStorage, bem_storage),
+        )
+
+    def accelerator_mode_for(self, kernel: RustKernel) -> AcceleratorMode:
+        """Return a kernel override, falling back to the global accelerator mode."""
+
+        return self.accelerator_overrides.get(kernel, self.accelerator)

nmag/demag/__init__.py

@@ -0,0 +1,39 @@
+from __future__ import annotations
+
+from typing import Any
+
+from . import geometry as _geometry
+from . import lindholm as _lindholm
+from . import lindholm_fast as _fast
+from . import linear as _linear
+
+_HELPER_MODULES = (_geometry, _lindholm, _fast, _linear)
+
+# Preserve the established patch points used by downstream tests and tooling.
+np = _linear.np
+_scipy_linalg = _linear._scipy_linalg
+
+
+def _solve_gauge_fixed(*args: Any, **kwargs: Any) -> Any:
+    """Forward to the solver while preserving facade-level monkeypatches."""
+
+    _linear._scipy_linalg = _scipy_linalg
+    return _linear._solve_gauge_fixed(*args, **kwargs)
+
+
+def _solve_linear_system(*args: Any, **kwargs: Any) -> Any:
+    """Forward to the solver while preserving facade-level monkeypatches."""
+
+    _linear._scipy_linalg = _scipy_linalg
+    return _linear._solve_linear_system(*args, **kwargs)
+
+
+def __getattr__(name: str) -> Any:
+    """Resolve compatibility exports from the focused demag modules."""
+
+    for module in _HELPER_MODULES:
+        try:
+            return getattr(module, name)
+        except AttributeError:
+            continue
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

nmag/demag/bem_operator.py

@@ -0,0 +1,149 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+import numpy as np
+
+from .lindholm_fast import _apply_lindholm_bem_matrix_free_fast
+
+
+@dataclass(frozen=True, slots=True)
+class BemOperatorStats:
+    """Describe construction and storage of the active BEM operator.
+
+    Attributes:
+        requested_backend: Storage mode requested by configuration.
+        effective_backend: Storage implementation actually constructed.
+        fallback_reason: Explanation when construction changed modes.
+        boundary_nodes: Number of boundary degrees of freedom.
+        boundary_faces: Number of oriented surface triangles.
+        setup_seconds: Operator construction time.
+        storage_bytes: Bytes retained by the effective operator.
+        dense_equivalent_bytes: Bytes required by an equivalent dense matrix.
+        dense_blocks: Exact blocks in a hierarchy.
+        low_rank_blocks: Compressed blocks in a hierarchy.
+        maximum_rank: Largest compressed-block rank.
+        mean_rank: Mean compressed-block rank.
+        sampled_relative_error: Certification error measured during setup.
+    """
+
+    requested_backend: str
+    effective_backend: str
+    fallback_reason: str | None
+    boundary_nodes: int
+    boundary_faces: int
+    setup_seconds: float
+    storage_bytes: int
+    dense_equivalent_bytes: int
+    dense_blocks: int = 0
+    low_rank_blocks: int = 0
+    maximum_rank: int = 0
+    mean_rank: float = 0.0
+    sampled_relative_error: float = 0.0
+
+    @property
+    def compression_ratio(self) -> float:
+        if self.dense_equivalent_bytes == 0:
+            return 0.0
+        return self.storage_bytes / self.dense_equivalent_bytes
+
+
+@dataclass(frozen=True, slots=True)
+class MatrixFreeLindholmBemOperator:
+    """Exact Lindholm BEM action without storing the dense boundary matrix."""
+
+    points: np.ndarray
+    simplices: np.ndarray
+    boundary_faces: np.ndarray
+    face_points: np.ndarray
+    zeta_vectors: np.ndarray
+    eta_vectors: np.ndarray
+    edge_lengths: np.ndarray
+    corner_cosines: np.ndarray
+    denominator_factors: np.ndarray
+    boundary_nodes: np.ndarray
+    local_index_by_point: np.ndarray
+    solid_angles: np.ndarray
+    rust_accelerator: Any | None = None
+
+    @property
+    def shape(self) -> tuple[int, int]:
+        size = len(self.boundary_nodes)
+        return size, size
+
+    def __matmul__(self, values: np.ndarray) -> np.ndarray:
+        vector = np.asarray(values, dtype=np.float64)
+        expected = (len(self.boundary_nodes),)
+        if vector.shape != expected:
+            raise ValueError(f"BEM input must have shape {expected}, got {vector.shape}.")
+        if self.rust_accelerator is not None:
+            return np.asarray(
+                self.rust_accelerator.apply_lindholm_bem_matrix_free(
+                    self.points,
+                    self.simplices,
+                    self.boundary_faces,
+                    self.boundary_nodes,
+                    self.local_index_by_point,
+                    vector,
+                ),
+                dtype=float,
+            )
+        return np.asarray(
+            _apply_lindholm_bem_matrix_free_fast(
+                self.points,
+                self.boundary_faces,
+                self.face_points,
+                self.zeta_vectors,
+                self.eta_vectors,
+                self.edge_lengths,
+                self.corner_cosines,
+                self.denominator_factors,
+                self.boundary_nodes,
+                self.local_index_by_point,
+                self.solid_angles,
+                vector,
+            ),
+            dtype=float,
+        )
+
+    @property
+    def storage_bytes(self) -> int:
+        arrays = (
+            self.points,
+            self.simplices,
+            self.boundary_faces,
+            self.face_points,
+            self.zeta_vectors,
+            self.eta_vectors,
+            self.edge_lengths,
+            self.corner_cosines,
+            self.denominator_factors,
+            self.boundary_nodes,
+            self.local_index_by_point,
+            self.solid_angles,
+        )
+        return sum(int(array.nbytes) for array in arrays)
+
+
+@dataclass(frozen=True, slots=True)
+class HierarchicalLindholmBemOperator:
+    """Certified compressed Lindholm operator owned by the Rust extension."""
+
+    rust_operator: Any
+
+    @property
+    def shape(self) -> tuple[int, int]:
+        size = int(self.rust_operator.size)
+        return size, size
+
+    def __matmul__(self, values: np.ndarray) -> np.ndarray:
+        vector = np.asarray(values, dtype=np.float64)
+        expected = (self.shape[1],)
+        if vector.shape != expected:
+            raise ValueError(f"BEM input must have shape {expected}, got {vector.shape}.")
+        return np.asarray(self.rust_operator.matvec(vector), dtype=np.float64)
+
+    @property
+    def storage_bytes(self) -> int:
+        return int(self.rust_operator.storage_bytes)