Materials

Last changes: Documentation changelog

Changed in version development: Added a decision guide for scalar materials, spatial parameter fields, elastic materials, and magnetostriction laws.

Materials assign constitutive parameters to magnetic and mechanical bodies. This family separates four contracts that should not be conflated:

  • a base magnetic material record supplies object-wide scalar values and optional mesh-aligned compatibility arrays;

  • a spatial parameter field overrides one parameter over an object or an object-owned region;

  • an elastic material supplies stiffness, density, and mechanical damping;

  • a magnetostriction law supplies the magnetic–mechanical coupling coefficients.

Which page owns my input?

Goal

Canonical page

Key boundary

Assign uniform Ms, Aex, damping, anisotropy, or DMI to one magnet

Magnetic material

one base value per owned parameter before regional overrides

Define a gradient, radial profile, sampled map, or region-local override

Spatial Parameter Fields

typed serializable field plus explicit ownership and conflict policy

Describe an elastic body

Elastic materials

mechanical constitutive parameters, density, and frame

Couple strain and magnetization through cubic coefficients

Magnetostriction laws

coupling law; mechanics execution remains a separate capability

Precedence model

A spatial field or region override replaces the corresponding base value only on its declared support. It is not added to the base scalar. Overlap is resolved by explicit priority and conflict policy, not authoring order. The planner then materializes the requested value onto the selected FDM or FEM representation and records the realized array or coefficient field in provenance.

Material authoring, numerical materialization, and scientific qualification are distinct:

  1. Python validates typed values and serializable identities.

  2. ProblemIR preserves units, frames, object/region references, and field definitions.

  3. The planner checks parameter/location/device capability.

  4. The runtime builds or uploads the mesh-aligned representation.

  5. Interaction-specific validation establishes whether the resolved field is scientifically adequate for the requested observable.

Common failure modes

  • supplying non-SI values to spatial fields: their constructors preserve a non-empty unit string as metadata but do not validate parameter dimensions or convert units, so authors must provide SI-valued numbers;

  • interpreting a linear gradient as having the same unit as its value rather than value per metre;

  • using a region override to model an interlayer coupling;

  • assuming a sampled cell field can be consumed as a nodal or quadrature field without an explicit projection contract;

  • treating successful serialization as proof of GPU support;

  • leaving equal-priority overlapping assignments to insertion order.

Use the detailed pages above for exact constructor fields, ProblemIR destinations, backend boundaries, and validation requirements.

Control Room crosswalk

Use Model Explorer -> Objects -> <object> -> Material for supported scalar material fields. Spatial fields, elastic laws, magnetostriction, and other parameters not exposed by ObjectMaterialPanel are TODO: frontend support. See Control Room capability register.

API and source scope

The category index introduces the precedence model but no standalone constructor. Child pages provide exact Python fields, units, realization semantics, limitations, bibliography, and source-code references.

Source-code index

This is a navigation page and introduces no standalone implementation symbol. The exact source-code index is maintained by the selected terminal page.