Materials and units API

SI quantities

nmag.SI and nmag.Physical are aliases for the same dimensional quantity class. Prefer nmag.SI in simulation scripts.

Physical

Physical(value: Any, dimensions: Any | None = None)

Represent a numeric value with checked physical dimensions.

nmag.SI is an alias for this class and is the preferred spelling in simulation scripts. Common units use a lightweight internal representation; other units are delegated to Pint without changing the public behavior.

Parameters:

Name	Type	Description	Default
value	Any	Numeric magnitude, another compatible quantity, a unit string such as "A/m", or a complete quantity string.	required
dimensions	Any | None	Unit string, legacy [unit, power, ...] list, or None.	None

Raises:

Type	Description
TypeError	If the value or dimensions form is unsupported.
ValueError	If a legacy dimensions list is malformed.

Create a dimensionally checked quantity.

magnitude property

magnitude: Any

Return the numeric magnitude in the quantity's stored unit.

dens_str

dens_str() -> str

Return a compact legacy-compatible representation such as <A/m>.

in_units_of

in_units_of(unit_quantity: object) -> float

Return the magnitude expressed in multiples of another quantity.

Parameters:

Name	Type	Description	Default
unit_quantity	object	A :class:Physical representing one requested unit, for example nmag.SI(1, "A/m").	required

Returns:

Type	Description
float	Numeric magnitude in the requested unit.

Raises:

Type	Description
TypeError	If unit_quantity is not a :class:Physical.
DimensionalityError	If the dimensions are incompatible.

Magnetic materials

MagMaterial

MagMaterial(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)

Define the physical parameters assigned to a magnetic mesh region.

Parameters:

Name	Type	Description	Default
name	str	Unique material name used in field and output labels.	required
Ms	SI | None	Saturation magnetization, compatible with A/m.	None
llg_damping	MaterialScalar	Dimensionless Gilbert damping coefficient.	0.5
llg_gamma_G	SI | None	Gyromagnetic ratio used by the LLG equation.	None
llg_normalisationfactor	SI | None	Coefficient for numerical norm correction.	None
llg_xi	MaterialScalar	Dimensionless nonadiabatic Zhang-Li coefficient.	0.0
llg_polarisation	MaterialScalar	Dimensionless spin-current polarization.	0.0
do_precession	bool	Include the precessional LLG term when true.	True
exchange_coupling	SI | None	Exchange constant, compatible with J/m.	None
anisotropy	PredefinedAnisotropy | AnisotropyFunction | None	Predefined anisotropy or custom energy callable.	None
anisotropy_order	int | None	Polynomial order required for a custom callable.	None
properties	list[str] | None	Compatibility property labels. Most users should omit this.	None
scale_volume_charges	float	Multiplier for interior demagnetization volume charge. Boundary surface charges remain physical and unscaled.	1.0

Raises:

Type	Description
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.

Initialize a material after validating units and physical values.

Anisotropy

uniaxial_anisotropy

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.

Parameters:

Name	Type	Description	Default
axis	ArrayLike	Three-component easy-axis direction; normalized internally.	required
K1	EnergyDensity	Second-order coefficient as J/m³ or a compatible SI quantity.	required
K2	EnergyDensity	Fourth-order coefficient as J/m³ or a compatible SI quantity.	0.0

Returns:

Type	Description
PredefinedAnisotropy	Vectorized predefined anisotropy with analytic gradient evaluation.

Raises:

Type	Description
ValueError	If the axis is zero or a coefficient is non-finite.

cubic_anisotropy

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.

Parameters:

Name	Type	Description	Default
axis1	ArrayLike	First crystalline axis; normalized internally.	required
axis2	ArrayLike	Second crystalline axis, required to be orthogonal to axis1.	required
K1	EnergyDensity	Fourth-order coefficient as J/m³ or a compatible SI quantity.	required
K2	EnergyDensity	Sixth-order coefficient as J/m³ or a compatible SI quantity.	0.0
K3	EnergyDensity	Eighth-order coefficient as J/m³ or a compatible SI quantity.	0.0

Returns:

Type	Description
PredefinedAnisotropy	Vectorized predefined anisotropy with analytic gradient evaluation.

Raises:

Type	Description
ValueError	If axes are invalid or coefficients are non-finite.

PredefinedAnisotropy dataclass

PredefinedAnisotropy(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 = None, _vectorized_energy: VectorizedEnergyFunction | None = None, _vectorized_gradient: GradientFunction | None = None, _vectorized_energy_gradient: EnergyGradientFunction | None = None)

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.