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

anisotropy/__init__.py

@@ -0,0 +1,28 @@
+from .evaluation import (
+    anisotropy_signature_values,
+    evaluate_energy_and_gradient,
+    evaluate_energy_density,
+    evaluate_energy_gradient,
+)
+from .model import (
+    AnisotropyModel,
+    EnergyDensity,
+    EnergyFunction,
+    PredefinedAnisotropy,
+    want_anisotropy,
+)
+from .predefined import cubic_anisotropy, uniaxial_anisotropy
+
+__all__ = [
+    "AnisotropyModel",
+    "EnergyDensity",
+    "EnergyFunction",
+    "PredefinedAnisotropy",
+    "anisotropy_signature_values",
+    "cubic_anisotropy",
+    "evaluate_energy_density",
+    "evaluate_energy_and_gradient",
+    "evaluate_energy_gradient",
+    "uniaxial_anisotropy",
+    "want_anisotropy",
+]

anisotropy/anisotropy.py

@@ -0,0 +1,13 @@
+"""Compatibility exports for the focused anisotropy modules."""
+
+from .model import PredefinedAnisotropy, want_anisotropy
+from .predefined import cubic_anisotropy, uniaxial_anisotropy
+from .values import _normalize
+
+__all__ = [
+    "PredefinedAnisotropy",
+    "_normalize",
+    "cubic_anisotropy",
+    "uniaxial_anisotropy",
+    "want_anisotropy",
+]

anisotropy/evaluation.py

@@ -0,0 +1,70 @@
+"""Evaluate arbitrary anisotropy models and build compatibility samples."""
+
+from __future__ import annotations
+
+import numpy as np
+
+from .model import AnisotropyModel, FloatArray, PredefinedAnisotropy
+from .values import (
+    ArrayLike,
+    _callable_energy,
+    _finite_difference_gradient,
+    _magnetisation_array,
+    _normalize,
+)
+
+
+def evaluate_energy_density(model: AnisotropyModel, magnetisation: ArrayLike) -> FloatArray:
+    values, _scalar = _magnetisation_array(magnetisation)
+    if model is None:
+        return np.zeros(len(values), dtype=np.float64)
+    if isinstance(model, PredefinedAnisotropy):
+        return np.asarray(model.energy_density(values), dtype=np.float64)
+    return _callable_energy(model, values)
+
+
+def evaluate_energy_gradient(model: AnisotropyModel, magnetisation: ArrayLike) -> FloatArray:
+    values, _scalar = _magnetisation_array(magnetisation)
+    if model is None:
+        return np.zeros_like(values)
+    if isinstance(model, PredefinedAnisotropy):
+        return np.asarray(model.energy_gradient(values), dtype=np.float64)
+    return _finite_difference_gradient(model, values)
+
+
+def evaluate_energy_and_gradient(
+    model: AnisotropyModel,
+    magnetisation: ArrayLike,
+) -> tuple[FloatArray, FloatArray]:
+    values, _scalar = _magnetisation_array(magnetisation)
+    if model is None:
+        return np.zeros(len(values), dtype=np.float64), np.zeros_like(values)
+    if isinstance(model, PredefinedAnisotropy):
+        return model.energy_and_gradient(values)
+    return _callable_energy(model, values), _finite_difference_gradient(model, values)
+
+
+def anisotropy_signature_values(
+    model: AnisotropyModel,
+    order: int | None,
+) -> FloatArray:
+    if model is None:
+        return np.asarray([0.0], dtype=np.float64)
+    probes = np.asarray(
+        [
+            [1.0, 0.0, 0.0],
+            [0.0, 1.0, 0.0],
+            [0.0, 0.0, 1.0],
+            _normalize([1.0, 1.0, 1.0]),
+            _normalize([1.0, 2.0, 3.0]),
+        ],
+        dtype=np.float64,
+    )
+    energy, gradient = evaluate_energy_and_gradient(model, probes)
+    return np.concatenate(
+        (
+            np.asarray([float(order or 0)], dtype=np.float64),
+            energy,
+            np.ravel(gradient),
+        )
+    )

anisotropy/model.py

@@ -0,0 +1,200 @@
+"""Typed anisotropy models and numerical evaluation helpers."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from typing import TypeAlias, cast
+
+import numpy as np
+
+from si.physical import SI
+
+from .values import (
+    ArrayLike,
+    FloatArray,
+    _callable_energy,
+    _finite_difference_gradient,
+    _magnetisation_array,
+)
+
+EnergyDensity: TypeAlias = float | SI
+EnergyFunction: TypeAlias = Callable[[ArrayLike], EnergyDensity]
+GradientFunction: TypeAlias = Callable[[FloatArray], FloatArray]
+VectorizedEnergyFunction: TypeAlias = Callable[[FloatArray], FloatArray]
+EnergyGradientFunction: TypeAlias = Callable[[FloatArray], tuple[FloatArray, FloatArray]]
+AnisotropyStringifier: TypeAlias = Callable[["PredefinedAnisotropy"], str]
+AnisotropyModel: TypeAlias = "PredefinedAnisotropy | EnergyFunction | None"
+
+
+@dataclass(frozen=True, slots=True)
+class PredefinedAnisotropy:
+    """An anisotropy energy model with optional analytic vectorized evaluation.
+
+    Instances returned by :func:`uniaxial_anisotropy` and
+    :func:`cubic_anisotropy` can be added, subtracted, negated, and multiplied by
+    scalar coefficients before being assigned to :class:`nmag.MagMaterial`.
+    """
+
+    function: EnergyFunction | None = None
+    order: int | None = None
+    anis_type: str = "functional"
+    axis1: ArrayLike | None = None
+    axis2: ArrayLike | None = None
+    axis3: ArrayLike | None = None
+    K1: EnergyDensity | None = None
+    K2: EnergyDensity | None = None
+    K3: EnergyDensity | None = None
+    stringifier: AnisotropyStringifier | None = field(default=None, repr=False)
+    _vectorized_energy: VectorizedEnergyFunction | None = field(
+        default=None,
+        repr=False,
+        compare=False,
+    )
+    _vectorized_gradient: GradientFunction | None = field(
+        default=None,
+        repr=False,
+        compare=False,
+    )
+    _vectorized_energy_gradient: EnergyGradientFunction | None = field(
+        default=None,
+        repr=False,
+        compare=False,
+    )
+
+    def __post_init__(self) -> None:
+        if self.function is None and self.order is None:
+            raise ValueError("PredefinedAnisotropy requires either a 'function' or an 'order'.")
+        if self.function is not None and not callable(self.function):
+            raise TypeError("Anisotropy function must be callable.")
+        order = cast(object, self.order)
+        if order is not None and (type(order) is bool or not isinstance(order, int) or order <= 0):
+            raise ValueError("Anisotropy order must be a positive integer.")
+        for name in ("axis1", "axis2", "axis3"):
+            axis = getattr(self, name)
+            if axis is not None:
+                frozen_axis = np.array(axis, dtype=np.float64, copy=True)
+                frozen_axis.setflags(write=False)
+                object.__setattr__(self, name, frozen_axis)
+
+    def has_function(self) -> bool:
+        return self.function is not None
+
+    def energy_density(self, magnetisation: ArrayLike) -> FloatArray | float:
+        values, scalar = _magnetisation_array(magnetisation)
+        if self._vectorized_energy is not None:
+            result = np.asarray(self._vectorized_energy(values), dtype=np.float64)
+        elif self.function is not None:
+            result = _callable_energy(self.function, values)
+        else:
+            raise ValueError("This anisotropy model has no energy function.")
+        if result.shape != (len(values),) or not np.all(np.isfinite(result)):
+            raise ValueError("Anisotropy energy evaluation returned invalid values.")
+        return float(result[0]) if scalar else result
+
+    def energy_gradient(self, magnetisation: ArrayLike) -> FloatArray:
+        values, scalar = _magnetisation_array(magnetisation)
+        if self._vectorized_gradient is not None:
+            result = np.asarray(self._vectorized_gradient(values), dtype=np.float64)
+        elif self.function is not None:
+            result = _finite_difference_gradient(self.function, values)
+        else:
+            raise ValueError("This anisotropy model has no energy function.")
+        if result.shape != values.shape or not np.all(np.isfinite(result)):
+            raise ValueError("Anisotropy gradient evaluation returned invalid values.")
+        return result[0] if scalar else result
+
+    def energy_and_gradient(self, magnetisation: ArrayLike) -> tuple[FloatArray, FloatArray]:
+        values, _scalar = _magnetisation_array(magnetisation)
+        if self._vectorized_energy_gradient is not None:
+            energy, gradient = self._vectorized_energy_gradient(values)
+            energy = np.asarray(energy, dtype=np.float64)
+            gradient = np.asarray(gradient, dtype=np.float64)
+        else:
+            energy = np.asarray(self.energy_density(values), dtype=np.float64)
+            gradient = np.asarray(self.energy_gradient(values), dtype=np.float64)
+        if energy.shape != (len(values),) or gradient.shape != values.shape:
+            raise ValueError("Anisotropy energy/gradient evaluation returned invalid shapes.")
+        if not np.all(np.isfinite(energy)) or not np.all(np.isfinite(gradient)):
+            raise ValueError("Anisotropy energy/gradient evaluation returned non-finite values.")
+        return energy, gradient
+
+    def __str__(self) -> str:
+        suffix = f", {self.stringifier(self)}" if self.stringifier else ""
+        return f"<PredefinedAnisotropy:{self.anis_type}{suffix}>"
+
+    def __repr__(self) -> str:
+        details = self.stringifier(self) if self.stringifier else "?"
+        return f'PredefinedAnisotropy(anis_type="{self.anis_type}", {details})'
+
+    def __neg__(self) -> PredefinedAnisotropy:
+        want_anisotropy(self)
+        return _combine_anisotropy(self, None, -1.0)
+
+    def __pos__(self) -> PredefinedAnisotropy:
+        return self
+
+    def __add__(self, other: object) -> PredefinedAnisotropy:
+        want_anisotropy(other)
+        assert isinstance(other, PredefinedAnisotropy)
+        return _combine_anisotropy(self, other, 1.0)
+
+    def __sub__(self, other: object) -> PredefinedAnisotropy:
+        want_anisotropy(other)
+        assert isinstance(other, PredefinedAnisotropy)
+        return _combine_anisotropy(self, other, -1.0)
+
+
+def _combine_anisotropy(
+    left: PredefinedAnisotropy,
+    right: PredefinedAnisotropy | None,
+    right_scale: float,
+) -> PredefinedAnisotropy:
+    def vectorized_energy_gradient(values: FloatArray) -> tuple[FloatArray, FloatArray]:
+        left_energy, left_gradient = left.energy_and_gradient(values)
+        if right is None:
+            return right_scale * left_energy, right_scale * left_gradient
+        right_energy, right_gradient = right.energy_and_gradient(values)
+        return (
+            left_energy + right_scale * right_energy,
+            left_gradient + right_scale * right_gradient,
+        )
+
+    def vectorized_energy(values: FloatArray) -> FloatArray:
+        left_energy = np.asarray(left.energy_density(values), dtype=np.float64)
+        if right is None:
+            return right_scale * left_energy
+        return left_energy + right_scale * np.asarray(
+            right.energy_density(values), dtype=np.float64
+        )
+
+    def vectorized_gradient(values: FloatArray) -> FloatArray:
+        left_gradient = np.asarray(left.energy_gradient(values), dtype=np.float64)
+        if right is None:
+            return right_scale * left_gradient
+        return left_gradient + right_scale * np.asarray(
+            right.energy_gradient(values),
+            dtype=np.float64,
+        )
+
+    def scalar_energy(values: ArrayLike) -> float:
+        array, _scalar = _magnetisation_array(values)
+        return float(vectorized_energy(array)[0])
+
+    order = left.order if right is None else max(left.order or 0, right.order or 0)
+    return PredefinedAnisotropy(
+        function=scalar_energy,
+        order=order or None,
+        _vectorized_energy=vectorized_energy,
+        _vectorized_gradient=vectorized_gradient,
+        _vectorized_energy_gradient=vectorized_energy_gradient,
+    )
+
+
+def want_anisotropy(value: object, want_function: bool = True) -> None:
+    if not isinstance(value, PredefinedAnisotropy):
+        raise TypeError(
+            f"Operand must be a PredefinedAnisotropy object, not {type(value).__name__}"
+        )
+    if want_function and not value.has_function():
+        raise ValueError("Cannot operate on an anisotropy object that lacks an energy function.")

anisotropy/predefined.py

@@ -0,0 +1,202 @@
+"""Vectorized predefined magnetic anisotropy models."""
+
+from __future__ import annotations
+
+import numpy as np
+
+from .model import EnergyDensity, PredefinedAnisotropy
+from .values import ArrayLike, FloatArray, _normalize, energy_density_value
+
+
+def _constant(value: EnergyDensity, name: str) -> float:
+    try:
+        return energy_density_value(value)
+    except (TypeError, ValueError) as exc:
+        raise TypeError(f"{name} must be an energy density compatible with J/m^3.") from exc
+
+
+def uniaxial_anisotropy(
+    axis: ArrayLike,
+    K1: EnergyDensity,
+    K2: EnergyDensity = 0.0,
+) -> PredefinedAnisotropy:
+    """Create a uniaxial anisotropy energy model.
+
+    The energy density is ``-K1 (axis·m)^2 - K2 (axis·m)^4``.
+
+    Args:
+        axis: Three-component easy-axis direction; normalized internally.
+        K1: Second-order coefficient as J/m³ or a compatible SI quantity.
+        K2: Fourth-order coefficient as J/m³ or a compatible SI quantity.
+
+    Returns:
+        Vectorized predefined anisotropy with analytic gradient evaluation.
+
+    Raises:
+        ValueError: If the axis is zero or a coefficient is non-finite.
+    """
+
+    normalized_axis = _normalize(axis)
+    k1 = _constant(K1, "K1")
+    k2 = _constant(K2, "K2")
+
+    def energy(values: FloatArray) -> FloatArray:
+        projection = values @ normalized_axis
+        return -k1 * projection**2 - k2 * projection**4
+
+    def gradient(values: FloatArray) -> FloatArray:
+        projection = values @ normalized_axis
+        factors = -2.0 * k1 * projection - 4.0 * k2 * projection**3
+        return factors[:, np.newaxis] * normalized_axis
+
+    def energy_gradient(values: FloatArray) -> tuple[FloatArray, FloatArray]:
+        projection = values @ normalized_axis
+        energy_values = -k1 * projection**2 - k2 * projection**4
+        factors = -2.0 * k1 * projection - 4.0 * k2 * projection**3
+        return energy_values, factors[:, np.newaxis] * normalized_axis
+
+    def scalar_energy(values: ArrayLike) -> float:
+        vector = np.asarray(values, dtype=np.float64)
+        return float(energy(vector[np.newaxis, :])[0])
+
+    def stringifier(model: PredefinedAnisotropy) -> str:
+        assert model.axis1 is not None
+        axis_values = np.asarray(model.axis1, dtype=np.float64).tolist()
+        result = f"axis={axis_values}, K1={model.K1}"
+        if k2 != 0.0:
+            result += f", K2={model.K2}"
+        return result
+
+    return PredefinedAnisotropy(
+        anis_type="uniaxial",
+        function=scalar_energy,
+        order=4 if k2 != 0.0 else 2,
+        axis1=normalized_axis,
+        K1=K1,
+        K2=K2,
+        stringifier=stringifier,
+        _vectorized_energy=energy,
+        _vectorized_gradient=gradient,
+        _vectorized_energy_gradient=energy_gradient,
+    )
+
+
+def cubic_anisotropy(
+    axis1: ArrayLike,
+    axis2: ArrayLike,
+    K1: EnergyDensity,
+    K2: EnergyDensity = 0.0,
+    K3: EnergyDensity = 0.0,
+) -> PredefinedAnisotropy:
+    """Create conventional fourth-, sixth-, and eighth-order cubic anisotropy.
+
+    Args:
+        axis1: First crystalline axis; normalized internally.
+        axis2: Second crystalline axis, required to be orthogonal to ``axis1``.
+        K1: Fourth-order coefficient as J/m³ or a compatible SI quantity.
+        K2: Sixth-order coefficient as J/m³ or a compatible SI quantity.
+        K3: Eighth-order coefficient as J/m³ or a compatible SI quantity.
+
+    Returns:
+        Vectorized predefined anisotropy with analytic gradient evaluation.
+
+    Raises:
+        ValueError: If axes are invalid or coefficients are non-finite.
+    """
+
+    first = _normalize(axis1)
+    raw_second = np.asarray(axis2, dtype=np.float64)
+    third = _normalize(np.cross(first, raw_second))
+    second = _normalize(np.cross(third, first))
+    axes: FloatArray = np.asarray((first, second, third), dtype=np.float64)
+    axes_transpose: FloatArray = np.ascontiguousarray(np.transpose(axes))
+    k1, k2, k3 = (_constant(value, name) for value, name in ((K1, "K1"), (K2, "K2"), (K3, "K3")))
+
+    def energy(values: FloatArray) -> FloatArray:
+        projections: FloatArray = np.asarray(values @ axes_transpose, dtype=np.float64)
+        squared: FloatArray = projections**2
+        fourth: FloatArray = squared**2
+        pair2 = (
+            squared[:, 0] * squared[:, 1]
+            + squared[:, 0] * squared[:, 2]
+            + squared[:, 1] * squared[:, 2]
+        )
+        triple2 = squared[:, 0] * squared[:, 1] * squared[:, 2]
+        pair4 = (
+            fourth[:, 0] * fourth[:, 1] + fourth[:, 0] * fourth[:, 2] + fourth[:, 1] * fourth[:, 2]
+        )
+        return k1 * pair2 + k2 * triple2 + k3 * pair4
+
+    def gradient(values: FloatArray) -> FloatArray:
+        projections: FloatArray = np.asarray(values @ axes_transpose, dtype=np.float64)
+        squared: FloatArray = projections**2
+        fourth: FloatArray = squared**2
+        derivatives: FloatArray = np.empty_like(projections)
+        for axis in range(3):
+            other = [index for index in range(3) if index != axis]
+            derivatives[:, axis] = (
+                2.0 * k1 * projections[:, axis] * (squared[:, other[0]] + squared[:, other[1]])
+                + 2.0 * k2 * projections[:, axis] * squared[:, other[0]] * squared[:, other[1]]
+                + 4.0 * k3 * projections[:, axis] ** 3 * (fourth[:, other[0]] + fourth[:, other[1]])
+            )
+        return derivatives @ axes
+
+    def energy_gradient(values: FloatArray) -> tuple[FloatArray, FloatArray]:
+        projections: FloatArray = np.asarray(values @ axes_transpose, dtype=np.float64)
+        squared: FloatArray = projections**2
+        fourth: FloatArray = squared**2
+        pair2 = (
+            squared[:, 0] * squared[:, 1]
+            + squared[:, 0] * squared[:, 2]
+            + squared[:, 1] * squared[:, 2]
+        )
+        energy_values = (
+            k1 * pair2
+            + k2 * squared[:, 0] * squared[:, 1] * squared[:, 2]
+            + k3
+            * (
+                fourth[:, 0] * fourth[:, 1]
+                + fourth[:, 0] * fourth[:, 2]
+                + fourth[:, 1] * fourth[:, 2]
+            )
+        )
+        derivatives: FloatArray = np.empty_like(projections)
+        for axis in range(3):
+            other = [index for index in range(3) if index != axis]
+            derivatives[:, axis] = (
+                2.0 * k1 * projections[:, axis] * (squared[:, other[0]] + squared[:, other[1]])
+                + 2.0 * k2 * projections[:, axis] * squared[:, other[0]] * squared[:, other[1]]
+                + 4.0 * k3 * projections[:, axis] ** 3 * (fourth[:, other[0]] + fourth[:, other[1]])
+            )
+        return energy_values, derivatives @ axes
+
+    def scalar_energy(values: ArrayLike) -> float:
+        vector = np.asarray(values, dtype=np.float64)
+        return float(energy(vector[np.newaxis, :])[0])
+
+    def stringifier(model: PredefinedAnisotropy) -> str:
+        assert model.axis1 is not None and model.axis2 is not None
+        first_values = np.asarray(model.axis1, dtype=np.float64).tolist()
+        second_values = np.asarray(model.axis2, dtype=np.float64).tolist()
+        result = f"axis1={first_values}, axis2={second_values}, K1={model.K1}"
+        if k2 != 0.0:
+            result += f", K2={model.K2}"
+        if k3 != 0.0:
+            result += f", K3={model.K3}"
+        return result
+
+    return PredefinedAnisotropy(
+        anis_type="cubic",
+        function=scalar_energy,
+        order=8 if k3 != 0.0 else 6 if k2 != 0.0 else 4,
+        axis1=first,
+        axis2=second,
+        axis3=third,
+        K1=K1,
+        K2=K2,
+        K3=K3,
+        stringifier=stringifier,
+        _vectorized_energy=energy,
+        _vectorized_gradient=gradient,
+        _vectorized_energy_gradient=energy_gradient,
+    )

anisotropy/py.typed

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

anisotropy/values.py

@@ -0,0 +1,84 @@
+"""Validation and scalar conversion helpers for anisotropy models."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any, TypeAlias, cast
+
+import numpy as np
+from numpy.typing import NDArray
+
+from si.physical import SI
+
+FloatArray = NDArray[np.float64]
+# NumPy's ArrayLike alias is intentionally broad, but recent NumPy stubs expose
+# unresolved type variables through it under strict Pyright checking. These
+# inputs are normalized immediately with np.asarray, so Any is intentional at
+# this runtime-validation boundary.
+ArrayLike: TypeAlias = Any
+RawEnergyFunction = Callable[[ArrayLike], object]
+
+_ENERGY_DENSITY_UNIT = SI(1.0, "J/m^3")
+_FINITE_DIFFERENCE_STEP = float(np.cbrt(np.finfo(np.float64).eps))
+
+
+def _normalize(values: ArrayLike) -> FloatArray:
+    vector = np.asarray(values, dtype=np.float64)
+    if vector.shape != (3,):
+        raise ValueError(f"Anisotropy axes must be 3-vectors, got shape {vector.shape}.")
+    if not np.all(np.isfinite(vector)):
+        raise ValueError("Anisotropy axes must contain only finite values.")
+    norm = float(np.linalg.norm(vector))
+    if norm == 0.0:
+        raise ValueError("Cannot normalize a zero vector.")
+    return vector / norm
+
+
+def energy_density_value(value: object) -> float:
+    result = (
+        value.in_units_of(_ENERGY_DENSITY_UNIT)
+        if isinstance(value, SI)
+        else float(cast(Any, value))
+    )
+    if not np.isfinite(result):
+        raise ValueError("Anisotropy energy density must be finite.")
+    return result
+
+
+def _magnetisation_array(values: ArrayLike) -> tuple[FloatArray, bool]:
+    array = np.asarray(values, dtype=np.float64)
+    scalar = array.ndim == 1
+    if scalar:
+        array = array[np.newaxis, :]
+    if array.ndim != 2 or array.shape[1] != 3:
+        raise ValueError(f"Magnetisation must have shape (3,) or (n, 3), got {array.shape}.")
+    if not np.all(np.isfinite(array)):
+        raise ValueError("Magnetisation must contain only finite values.")
+    return np.ascontiguousarray(array), scalar
+
+
+def _callable_energy(function: RawEnergyFunction, magnetisation: FloatArray) -> FloatArray:
+    return np.asarray(
+        [energy_density_value(function(vector)) for vector in magnetisation],
+        dtype=np.float64,
+    )
+
+
+def _finite_difference_gradient(
+    function: RawEnergyFunction,
+    magnetisation: FloatArray,
+) -> FloatArray:
+    gradient = np.empty_like(magnetisation)
+    for row, vector in enumerate(magnetisation):
+        for component in range(3):
+            step = _FINITE_DIFFERENCE_STEP * max(1.0, abs(float(vector[component])))
+            plus = np.array(vector, copy=True)
+            minus = np.array(vector, copy=True)
+            plus[component] += step
+            minus[component] -= step
+            gradient[row, component] = (
+                energy_density_value(function(plus)) - energy_density_value(function(minus))
+            ) / (2.0 * step)
+    if not np.all(np.isfinite(gradient)):
+        raise ValueError("Anisotropy energy gradient must be finite.")
+    return gradient

mag_material/__init__.py

@@ -0,0 +1,3 @@
+from .mag_material import MagMaterial
+
+__all__ = ["MagMaterial"]