Uniaxial magnetocrystalline anisotropy¶

Solver and backend realizations¶

Implementation status is not equivalent to qualification for every precision, mesh, material-field shape, or device. Resolved provenance must retain requested constants and axis, normalized axis, resolved scalar/spatial material data, solver, device, precision, and output legality.

Physical problem¶

Let \(\Omega_m\) be the magnetic domain, \(\mathbf m=\mathbf M/M_s\) the reduced magnetization, \(\mathbf u\) the normalized easy-axis direction, and

The sign of Ku1 has a physical meaning: positive Ku1 favors \(|q|=1\) (alignment with the axis), while negative Ku1 favors \(q=0\) (the plane normal to the axis). Ku2 adds a fourth-power angular contribution and is not silently absorbed into Ku1.

Governing equations¶

The exact implemented continuum density and total energy are

With positive \(M_s\), the effective field obtained from the FullMag convention is

For an admissible variation \(\boldsymbol\eta\), the directional derivative is

The field is parallel to the local easy axis. It is not a demagnetizing field, does not require a Poisson solve, and has no boundary condition of its own. The LLG torque and magnetization normalization are owned by the dynamics contract.

Symbols and SI units¶

Assumptions and validity¶

• Ku1 and Ku2 are SI energy-density constants in J/m^3. They are not exchange stiffnesses and are not supplied in J/m.

• The configured axis is required to be a finite non-zero direction for an active realization. Native paths normalize it; the stored public tuple is not silently treated as unit length.

• The reduced magnetization is expected to satisfy the surrounding dynamics normalization contract.

• Ms must be finite and positive. The field scales as \(1/M_s\); the energy does not contain an additional hidden \(\mu_0\) factor.

• Spatial Ku_field and Ku2_field override scalar material values only where the corresponding backend supports their cardinality and interpolation. They are not arbitrary-length arrays.

• The absolute energy uses the negative-power convention stated above. Comparing to a shifted publication convention requires adding the known constant before claiming equality.

Python authoring and canonical ProblemIR¶

The interaction-facing parameter matrix is:

# %% Copyable Python/Jupyter stage workflow
import fullmag as fm

nm = 1.0e-9
study = fm.study("uniaxial-anisotropy")
study.engine("fdm")
study.device("cpu", precision="double")
study.mode("strict")
study.exchange()
study.objects.mesh.defaults(cell_size=(2 * nm, 2 * nm, 1 * nm))
body = study.geometry(fm.Box(40 * nm, 20 * nm, 5 * nm), name="film")
body.Ms = 800.0e3
body.Aex = 13.0e-12
body.alpha = 0.01
body.Ku1 = 0.5e6
body.Ku2 = 0.05e6
body.anisU = (0.0, 0.0, 1.0)
body.m = fm.init.UniformMagnetization((1.0, 0.0, 0.0))
study.stages.add_relax(
    stage_id="relax",
    algorithm="nonlinear_cg",
    max_steps=50_000,
    tolT=1.0e-6,
)

The anisotropy values belong to the material/geometry handle and the stage pipeline is the executable user workflow. The compatibility constructor is documented separately as a lowering inspection fixture, not as a way to launch a simulation.

The compatibility object is requested intent. The resolved IR is material-owned. Supplying both conflicting legacy values and existing Material values raises a validation error rather than silently choosing one.

ProblemIR and planner contract¶

The canonical material fragment is:

{
  "uniaxial_anisotropy": 500000.0,
  "uniaxial_anisotropy_k2": 50000.0,
  "anisotropy_axis": [0.0, 0.0, 1.0]
}

FDM and FEM planners copy the material values into their native plan structures. FEM additionally promotes heterogeneous region values to resolved fields and validates an active axis. A planner may reject unsupported material-field shape or incompatible multi-region semantics; it must not drop the anisotropy while reporting a successful resolved execution.

Round-trip and failure semantics¶

Canonical export preserves requested intent in the source model and material IR. Resolved execution must additionally record normalized axis, scalar versus spatial coefficient realization, solver, device, precision, and output decisions.

Validation errors include malformed vectors, non-finite constants, a zero active axis, conflicting legacy and material values, incompatible region material promotion, and unsupported output requests. Unsupported combinations are planner errors, not silent fallbacks.

Discrete realization¶

Implementation mapping¶

The adjacent uniaxial.source-map.json records stable path-plus-symbol citations. Ownership is split deliberately:

• Python UniaxialAnisotropy and _migrate_legacy_anisotropy_energy_terms own public migration.

• Material owns canonical values and serialization.

• plan_fdm and plan_fem own native resolution and legality.

• FDM CPU owns local projection and energy density.

• FDM CUDA owns precision-specific kernels and reductions.

• FEM CPU owns nodal/quadrature field and energy evaluation.

• FEM CUDA owns device field/energy kernels and reductions.

Line numbers are intentionally not the citation identity because source edits move them. Use the stable symbol and inspect the current line range when reviewing a particular revision.

Validation and qualification¶

For \(\mathbf m=\mathbf u\), verify \(q=1\) and \(\mathbf H_{\mathrm u}=(2K_{u1}+4K_{u2})\mathbf u/(\mu_0M_s)\). For \(\mathbf m\perp\mathbf u\), verify zero field and zero FullMag density. Reverse Ku1 and verify the easy-axis/easy-plane behavior. Compare finite differences of the reported energy with the analytic field.

Repeat with scalar and spatial coefficients on FDM CPU, qualified CUDA, FEM CPU, and FEM CUDA. Compare H_ani, E_ani, and eden_ani; report precision and reduction order. Source or static contract tests alone do not prove executed-device parity.

Limitations and deferred work¶

• Public axis fields are material-level vectors; arbitrary public per-node axis fields are not part of this contract.

• The compatibility energy object is restricted to a single material target during migration.

• The absolute energy convention intentionally retains the implementation’s constant offset.

• GPU production qualification remains dependent on current executed-device evidence.

Scientific bibliography¶

• Brown, W. F., Micromagnetics, Wiley, 1963.

• FullMag internal source of truth: docs/physics/0402-uniaxial-anisotropy.md.

• FullMag material and compatibility implementation: packages/fullmag-py/src/fullmag/model/structure.py and packages/fullmag-py/src/fullmag/model/energy.py.

Control Room crosswalk¶

Use Model Explorer -> Objects -> <object> -> Physics when PhysicsInteractionPanel exposes the interaction. Status: partial. frontend support is not implemented applies to physical parameters without a matching control. See {doc}/frontend/capability-register; do not infer UI support from backend or Python availability.

Python/API crosswalk¶

The linked Python API page is authoritative for exact functions, arguments, units, and failure semantics. If this page is a foundation or category overview, runnable Python is ot applicable here and must be taken from the terminal API page.

Bibliography and source scope¶

Use the scientific bibliography and source-code index on the linked terminal page. This block adds no new equation or unverified implementation claim.

Source-code index¶