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

mag_material/mag_material.py

@@ -0,0 +1,231 @@
+"""
+Definition of the MagMaterial class, which allows to define a magnetic
+material and all its parameters (saturation magnetisation, exchange coupling,
+etc.)
+"""
+
+import logging
+from typing import Any, Protocol, cast
+
+from anisotropy import PredefinedAnisotropy
+from si.physical import SI
+
+from .parameters import (
+    AnisotropyFunction,
+    MaterialScalar,
+    resolve_material_parameters,
+)
+
+log = logging.getLogger("nmag")
+
+
+class _SIConstants(Protocol):
+    boltzmann_constant: SI
+    gamma0: SI
+    mu0: SI
+    bohr_magneton: SI
+    positron_charge: SI
+
+
+_constants_cache: _SIConstants | None = None
+
+
+def _si_constants() -> _SIConstants:
+    global _constants_cache
+    if _constants_cache is None:
+        from si import constants
+
+        _constants_cache = cast(_SIConstants, constants)
+    return _constants_cache
+
+
+class MagMaterial:
+    """Define the physical parameters assigned to a magnetic mesh region.
+
+    Args:
+        name: Unique material name used in field and output labels.
+        Ms: Saturation magnetization, compatible with A/m.
+        llg_damping: Dimensionless Gilbert damping coefficient.
+        llg_gamma_G: Gyromagnetic ratio used by the LLG equation.
+        llg_normalisationfactor: Coefficient for numerical norm correction.
+        llg_xi: Dimensionless nonadiabatic Zhang-Li coefficient.
+        llg_polarisation: Dimensionless spin-current polarization.
+        do_precession: Include the precessional LLG term when true.
+        exchange_coupling: Exchange constant, compatible with J/m.
+        anisotropy: Predefined anisotropy or custom energy callable.
+        anisotropy_order: Polynomial order required for a custom callable.
+        properties: Compatibility property labels. Most users should omit this.
+        scale_volume_charges: Multiplier for interior demagnetization volume
+            charge. Boundary surface charges remain physical and unscaled.
+
+    Raises:
+        TypeError: If a parameter has an unsupported type or dimensions.
+        ValueError: If a value is non-finite, physically invalid, or a custom
+            anisotropy omits its order.
+    """
+
+    def __init__(
+        self,
+        name: str,
+        Ms: SI | None = None,
+        llg_damping: MaterialScalar = 0.5,
+        llg_gamma_G: SI | None = None,
+        llg_normalisationfactor: SI | None = None,
+        llg_xi: MaterialScalar = 0.0,
+        llg_polarisation: MaterialScalar = 0.0,
+        do_precession: bool = True,
+        exchange_coupling: SI | None = None,
+        anisotropy: PredefinedAnisotropy | AnisotropyFunction | None = None,
+        anisotropy_order: int | None = None,
+        properties: list[str] | None = None,
+        scale_volume_charges: float = 1.0,
+    ) -> None:
+        """Initialize a material after validating units and physical values."""
+        parameters = resolve_material_parameters(
+            name,
+            ms=Ms,
+            damping=llg_damping,
+            gamma=llg_gamma_G,
+            normalisation=llg_normalisationfactor,
+            xi=llg_xi,
+            polarisation=llg_polarisation,
+            do_precession=do_precession,
+            exchange=exchange_coupling,
+            anisotropy=anisotropy,
+            anisotropy_order=anisotropy_order,
+            properties=properties,
+            scale_volume_charges=scale_volume_charges,
+        )
+
+        self.name = name
+        self.Ms = parameters.ms
+        self.llg_gamma_G = parameters.gamma
+        self.llg_damping = parameters.damping
+        self.llg_normalisationfactor = parameters.normalisation
+        self.llg_xi = parameters.xi
+        self.llg_polarisation = parameters.polarisation
+        self.do_precession = parameters.do_precession
+        self.properties = parameters.properties
+        self.exchange_coupling = parameters.exchange
+        self.scale_volume_charges = parameters.scale_volume_charges
+        self.anisotropy = parameters.anisotropy
+        self.anisotropy_order = parameters.anisotropy_order
+
+        # SU units units for backwards compatibility, they used to be stripped
+        # of units, but now we can do calculations with the units attached
+        self.su_Ms = self.Ms
+        self.su_llg_gamma_G = self.llg_gamma_G
+        self.su_llg_damping = self.llg_damping
+        self.su_llg_normalisationfactor = self.llg_normalisationfactor
+        self.su_exchange_coupling = self.exchange_coupling
+
+        gilbert_to_ll = 1.0 / (1.0 + self.su_llg_damping**2)
+        self.su_llg_coeff1 = -self.su_llg_gamma_G * gilbert_to_ll
+        self.su_llg_coeff2 = self.su_llg_coeff1 * self.su_llg_damping
+
+        if not self.do_precession:
+            log.info(
+                "Setting su_llg_coeff1 to zero; thus no precession for material '%s'", self.name
+            )
+            self.su_llg_coeff1 = 0.0
+
+        self.su_anisotropy = self.anisotropy
+        self._derived_su_constants: dict[str, MaterialScalar] | None = None
+
+        self.extended_print = False
+        if log.isEnabledFor(logging.INFO):
+            log.info("Created new Material:\n %s", self)
+
+    def _derived_su_values(self) -> dict[str, MaterialScalar]:
+        if self._derived_su_constants is None:
+            constants = _si_constants()
+            thermal_factor = (2.0 * constants.boltzmann_constant * self.llg_damping) / (
+                -constants.gamma0 * constants.mu0 * self.Ms
+            )
+            gilbert_to_ll = 1.0 / (1.0 + self.su_llg_damping**2)
+            polarisation = (
+                self.llg_polarisation.in_units_of(SI(1))
+                if isinstance(self.llg_polarisation, SI)
+                else float(self.llg_polarisation)
+            )
+            xi = self.llg_xi.in_units_of(SI(1)) if isinstance(self.llg_xi, SI) else float(self.llg_xi)
+            bohr_magneton = float(
+                cast(Any, 1.0 * constants.bohr_magneton).to("J/T").magnitude
+            )
+            charge = float(cast(Any, 1.0 * constants.positron_charge).to("C").magnitude)
+            ms = self.Ms.in_units_of(SI("A/m"))
+            su_f = (
+                SI(0.0, "m^3/A/s")
+                if ms == 0.0
+                else SI(
+                    -gilbert_to_ll
+                    * polarisation
+                    * bohr_magneton
+                    / (charge * ms * (1.0 + xi * xi)),
+                    "m^3/A/s",
+                )
+            )
+            self._derived_su_constants = {
+                "thermal_factor": thermal_factor,
+                "su_thermal_factor": thermal_factor,
+                "su_llg_stt_prefactor": 0.0 if su_f == 0.0 else 1.0,
+                "su_llg_stt_nadiab": su_f * (xi - self.su_llg_damping),
+                "su_llg_stt_adiab": su_f * (1.0 + self.su_llg_damping * xi),
+                "su_exch_prefactor": (
+                    2.0 * self.su_exchange_coupling / (constants.mu0 * self.su_Ms)
+                ),
+            }
+        return self._derived_su_constants
+
+    @property
+    def thermal_factor(self) -> MaterialScalar:
+        return self._derived_su_values()["thermal_factor"]
+
+    @property
+    def su_thermal_factor(self) -> MaterialScalar:
+        return self._derived_su_values()["su_thermal_factor"]
+
+    @property
+    def su_llg_stt_prefactor(self) -> MaterialScalar:
+        return self._derived_su_values()["su_llg_stt_prefactor"]
+
+    @property
+    def su_llg_stt_nadiab(self) -> MaterialScalar:
+        return self._derived_su_values()["su_llg_stt_nadiab"]
+
+    @property
+    def su_llg_stt_adiab(self) -> MaterialScalar:
+        return self._derived_su_values()["su_llg_stt_adiab"]
+
+    @property
+    def su_exch_prefactor(self) -> MaterialScalar:
+        return self._derived_su_values()["su_exch_prefactor"]
+
+    def __str__(self) -> str:
+        repr_str = f"Material '{self.name}'\n"
+
+        attrs = list(filter(lambda a: a[0] != "_", dir(self)))
+
+        if not self.extended_print:
+            attrs = [
+                "name",
+                "Ms",
+                "exchange_coupling",
+                "anisotropy",
+                "anisotropy_order",
+                "llg_gamma_G",
+                "llg_damping",
+                "llg_normalisationfactor",
+                "do_precession",
+                "llg_polarisation",
+                "llg_xi",
+                "thermal_factor",
+                "extended_print",
+            ]
+
+        for attr in attrs:
+            if hasattr(self, attr):
+                value_str = str(getattr(self, attr))
+                repr_str += f" {attr:>25} = {value_str}\n"
+
+        return repr_str

mag_material/parameters.py

@@ -0,0 +1,150 @@
+"""Normalization and validation for :class:`mag_material.MagMaterial` inputs."""
+
+from __future__ import annotations
+
+import math
+from dataclasses import dataclass
+from functools import lru_cache
+from typing import cast
+
+from anisotropy import EnergyFunction, PredefinedAnisotropy
+from si.physical import SI
+
+MaterialScalar = SI | float
+AnisotropyFunction = EnergyFunction
+
+
+@dataclass(slots=True)
+class MaterialParameters:
+    """Fully resolved constructor values for a magnetic material."""
+
+    ms: SI
+    damping: MaterialScalar
+    gamma: SI
+    normalisation: SI
+    xi: MaterialScalar
+    polarisation: MaterialScalar
+    do_precession: bool
+    exchange: SI
+    anisotropy: PredefinedAnisotropy | AnisotropyFunction | None
+    anisotropy_order: int | None
+    properties: list[str]
+    scale_volume_charges: float
+
+
+@lru_cache(maxsize=1)
+def _expected_parameter_units() -> tuple[tuple[str, SI], ...]:
+    one = SI(1)
+    return (
+        ("Ms", SI(1, "A/m")),
+        ("llg_gamma_G", SI(1, "m/A/s")),
+        ("llg_damping", one),
+        ("llg_normalisationfactor", SI(1, "1/s")),
+        ("llg_xi", one),
+        ("llg_polarisation", one),
+        ("exchange_coupling", SI(1, "J/m")),
+    )
+
+
+def _value_by_public_name(parameters: MaterialParameters, name: str) -> MaterialScalar:
+    values: dict[str, MaterialScalar] = {
+        "Ms": parameters.ms,
+        "llg_gamma_G": parameters.gamma,
+        "llg_damping": parameters.damping,
+        "llg_normalisationfactor": parameters.normalisation,
+        "llg_xi": parameters.xi,
+        "llg_polarisation": parameters.polarisation,
+        "exchange_coupling": parameters.exchange,
+    }
+    return values[name]
+
+
+def _validate_units(name: str, parameters: MaterialParameters) -> None:
+    for attribute, expected_unit in _expected_parameter_units():
+        value = _value_by_public_name(parameters, attribute)
+        value_to_check = value._quantity if isinstance(value, SI) else value
+        if not expected_unit._quantity.is_compatible_with(value_to_check):
+            raise TypeError(
+                f"The argument '{attribute}' for material '{name}' requires units compatible "
+                f"with {expected_unit.dens_str()}, but received a value of '{value}'."
+            )
+
+
+def _resolve_anisotropy(
+    anisotropy: PredefinedAnisotropy | AnisotropyFunction | None,
+    anisotropy_order: int | None,
+) -> tuple[PredefinedAnisotropy | AnisotropyFunction | None, int | None]:
+    if isinstance(anisotropy, PredefinedAnisotropy):
+        if anisotropy_order is not None:
+            raise ValueError(
+                "Cannot specify custom 'anisotropy_order' when using a predefined anisotropy."
+            )
+        if not anisotropy.has_function() or anisotropy.order is None:
+            raise ValueError("A material anisotropy must provide an energy function and order.")
+        return anisotropy, anisotropy.order
+    if anisotropy is None:
+        if anisotropy_order is not None:
+            raise ValueError("anisotropy_order requires an anisotropy energy function.")
+        return None, None
+    if not callable(anisotropy):
+        raise TypeError("anisotropy must be a PredefinedAnisotropy, callable, or None.")
+    custom_order = cast(object, anisotropy_order)
+    if (
+        custom_order is None
+        or type(custom_order) is bool
+        or not isinstance(custom_order, int)
+        or custom_order <= 0
+    ):
+        raise ValueError(
+            "You must specify 'anisotropy_order' as a positive integer when using a custom "
+            "anisotropy function."
+        )
+    return anisotropy, anisotropy_order
+
+
+def resolve_material_parameters(
+    name: str,
+    *,
+    ms: SI | None,
+    damping: MaterialScalar,
+    gamma: SI | None,
+    normalisation: SI | None,
+    xi: MaterialScalar,
+    polarisation: MaterialScalar,
+    do_precession: bool,
+    exchange: SI | None,
+    anisotropy: PredefinedAnisotropy | AnisotropyFunction | None,
+    anisotropy_order: int | None,
+    properties: list[str] | None,
+    scale_volume_charges: float,
+) -> MaterialParameters:
+    """Apply legacy defaults and reject invalid material constructor values."""
+    try:
+        resolved_volume_charge_scale = float(scale_volume_charges)
+    except (TypeError, ValueError) as error:
+        raise TypeError("scale_volume_charges must be a finite real number.") from error
+    if not math.isfinite(resolved_volume_charge_scale):
+        raise ValueError("scale_volume_charges must be finite.")
+
+    resolved_anisotropy, resolved_order = _resolve_anisotropy(anisotropy, anisotropy_order)
+    parameters = MaterialParameters(
+        ms=SI(0.86e6, "A/m") if ms is None else ms,
+        damping=damping,
+        gamma=SI(2.210173e5, "m/A/s") if gamma is None else gamma,
+        normalisation=SI(0.1e12, "1/s") if normalisation is None else normalisation,
+        xi=xi,
+        polarisation=polarisation,
+        do_precession=do_precession,
+        exchange=SI(1.3e-11, "J/m") if exchange is None else exchange,
+        anisotropy=resolved_anisotropy,
+        anisotropy_order=resolved_order,
+        properties=["magnetic", "material"] if properties is None else properties,
+        scale_volume_charges=resolved_volume_charge_scale,
+    )
+    _validate_units(name, parameters)
+    if parameters.exchange < 0.0:
+        raise ValueError(
+            "The exchange coupling constant must be positive. For "
+            f"material '{name}', you specified: {parameters.exchange}."
+        )
+    return parameters

mag_material/py.typed

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

nmag/__init__.py

@@ -0,0 +1,36 @@
+"""Public Python 3 entrypoint for the nmag rewrite."""
+
+from anisotropy import (
+    PredefinedAnisotropy,
+    cubic_anisotropy,
+    uniaxial_anisotropy,
+    want_anisotropy,
+)
+from mag_material import MagMaterial
+from si.physical import SI, Physical
+
+from .config import ACCELERATOR_ENV, HierarchicalBemConfig, NmagConfig, RustKernel
+from .demag.bem_operator import BemOperatorStats
+from .dynamics import IntegratorConfig, IntegratorStats
+from .parallel import ParallelRuntimeInfo, parallel_runtime_info
+from .simulation import Simulation
+
+__all__ = [
+    "MagMaterial",
+    "NmagConfig",
+    "HierarchicalBemConfig",
+    "BemOperatorStats",
+    "IntegratorConfig",
+    "IntegratorStats",
+    "ParallelRuntimeInfo",
+    "Physical",
+    "PredefinedAnisotropy",
+    "SI",
+    "Simulation",
+    "RustKernel",
+    "ACCELERATOR_ENV",
+    "cubic_anisotropy",
+    "parallel_runtime_info",
+    "uniaxial_anisotropy",
+    "want_anisotropy",
+]