Exchange interaction¶

Executable user workflow: study and stages¶

The normal user script declares one study and appends its execution stages. The physical model is captured by each stage; the sequence is not represented by manually constructing a flat canonical stage workflow. This is the form used by the public script loader and by the stage tests.

The following block is both a regular Python script and a Jupyter-compatible sequence of # %% cells. It builds an exchange-only study with relaxation followed by a physical-time run. Exchange is active by default. The material assignment body.Aex = ... supplies the stiffness; it does not need a matching study.exchange(). An intentional exchange-free model must call study.disable_exchange().

# %% Imports and SI constants
import fullmag as fm

nm = 1.0e-9

study = fm.study("exchange_only")
study.engine("fdm")
study.objects.mesh.defaults(cell_size=(2 * nm, 2 * nm, 1 * nm))

# %% Geometry and material
body = study.geometry(fm.Box(40 * nm, 20 * nm, 5 * nm), name="film")
body.Ms = 800.0e3       # A/m
body.Aex = 13.0e-12     # J/m
body.alpha = 0.01       # dimensionless
body.m = fm.texture.uniform(1.0, 0.0, 0.0)

# %% Ordered execution pipeline
study.stages.add_relax(
    stage_id="relax",
    tolT=1.0e-6,
    dt=1.0e-15,
    max_steps=50_000,
)
study.stages.add_run(stage_id="run", until=1.0e-9)

study.stages is the public execution pipeline. relax and run are separate stages with different stopping variables and provenance. The selected solver, device, precision, mesh, and resolved outputs are determined by the planner/runtime; the Python stage declarations preserve the requested intent.

Interaction and material lowering¶

The stage-first script above is the only public simulation workflow. The JSON below records the canonical interaction and material normalization without introducing a second Python authoring workflow. The stage builder owns the complete physical request; the planner resolves its backend policy, installed capabilities, and execution context after the ordered stages are captured.

Object-level interaction fragment¶

Use this small fragment when inspecting the canonical interaction and material records without constructing a second simulation workflow:

# %% Inspect exchange and its material coefficients
import fullmag as fm

study = fm.study("exchange_object_inspection")
study.engine("fdm")
inspection_body = study.geometry(fm.Box(1.0e-9, 1.0e-9, 1.0e-9), name="inspection")
inspection_body.Ms = 800.0e3
inspection_body.Aex = 13.0e-12
study.stages.add_run(stage_id="inspection", until=1.0e-12)

exchange = fm.Exchange()
material = fm.Material(
    name="Permalloy",
    Ms=800.0e3,
    A=13.0e-12,
    alpha=0.01,
)
assert exchange.to_ir() == {"kind": "exchange"}
print(material.to_ir())

Exchange-facing parameter reference¶

Exchange observables¶

FDM boundary controls relevant to Exchange¶

Supporting Python API¶

The constructors used by the executable example are documented in their canonical owner pages: Magnetic material, Geometry primitives, Ferromagnet, Uniform Texture, Time Evolution, LLG, Fields And Scalars, Discretization Hints, FDM, FEM discretization and mesh authoring, and Problem. General lowering and canonical-model framing live in Problem IR.

Canonical ProblemIR excerpt¶

The example lowers the Exchange-relevant sections exactly as follows (JSON numbers are SI):

{
  "materials": [
    {
      "name": "Permalloy",
      "saturation_magnetisation": 800000.0,
      "exchange_stiffness": 1.3e-11,
      "damping": 0.01,
      "ms_field": null,
      "a_field": null
    }
  ],
  "energy_terms": [
    {"kind": "exchange"}
  ],
  "study": {
    "kind": "time_evolution",
    "dynamics": {
      "kind": "llg",
      "gyromagnetic_ratio": 221100.0,
      "integrator": "auto",
      "fixed_timestep": null
    },
    "sampling": {
      "outputs": [
        {"kind": "field", "name": "H_ex", "every_seconds": 1e-12},
        {"kind": "scalar", "name": "E_ex", "every_seconds": 1e-12}
      ]
    }
  },
  "backend_policy": {
    "requested_backend": "auto",
    "execution_precision": "double",
    "discretization_hints": {
      "fdm": {"cell": [2e-9, 2e-9, 1e-9], "default_cell": [2e-9, 2e-9, 1e-9]},
      "fem": {"order": 1, "hmax": 2e-9, "mesh": null},
      "hybrid": null
    }
  },
  "validation_profile": {"execution_mode": "strict"}
}

The excerpt intentionally omits unrelated null material fields and geometry detail; it is not a replacement schema. The complete object printed by the Python block is the authoritative payload.

Python-to-IR mapping and failure semantics¶

Python normalization preserves requested intent in ProblemIR. Backend, device, precision, and the concrete exchange realization are resolved later and must appear as resolved execution in provenance. Constructor and lowering validation errors are raised before planning; capability validation then rejects unsupported combinations instead of rewriting the authored model. There is no silent CPU fallback promised by Exchange(): an unsupported requested combination is an error. Likewise, adding A without Exchange() stores a material property but does not enable or output exchange physics.

FDM / CPU — double-precision reference lane¶

This lane is CpuReference; it is executable and useful as an oracle, but it is not FullMag’s production FDM backend. The persistent runtime path uses a structure-of-arrays, six-neighbor, uniform-material stencil:

Open or inactive neighbors are replaced by the center magnetization, which yields zero normal exchange flux. Enabled periodic axes wrap the neighbor index. The hot runtime stencil uses f64. The production reference path is crates/fullmag-engine/src/fdm/cpu/fields.rs — exchange_field_add_into_soa; the richer allocating comparison path is the same file — cell_exchange_field.

The allocating reference accessor also contains a heterogeneous link form

That accessor does not establish heterogeneous production stepping: the persistent SoA path uses the scalar material values and does not consume explicit inter-region pair overrides. This is a documented implementation limitation, not a promised fallback.

FDM / GPU — native CUDA production implementation¶

The standard FP64 and FP32 kernels implement

The realized pair coefficient comes from the native exchange lookup table. A caller-supplied table is copied as supplied; FullMag does not infer a heterogeneous harmonic mean from per-region values inside the CUDA kernel. Open boundaries clamp to the center; periodic axes wrap for the standard stencil. FP64 uses double state and arithmetic. FP32 uses float state/field arithmetic while the energy reduction accumulates in FP64.

Each positive Cartesian link is counted once in the standard discrete energy:

FEM / CPU — native MFEM implementation¶

FullMag uses one scalar continuous P1 H1 space for each Cartesian component and assembles the positive-semidefinite diffusion operator

Current production assembly is MFEM AssemblyLevel::LEGACY: a fully assembled sparse matrix, not partial assembly and not a libCEED exchange operator. The default lumped projection is

The CPU-only consistent-mass option solves

The consistent solve uses MFEM conjugate gradients with relative tolerance \(10^{-10}\), zero absolute tolerance, and at most 200 iterations. Forms are restricted to magnetic elements; air-only nodes are zeroed. Periodicity is imposed by aggregating residual and mass over reduced-node equivalence classes and lifting the field back to full nodes. Assembly is implemented by backends/fem/cpu/mfem/interactions/exchange_operator.cpp — initialize_exchange_operator_mfem; field/energy evaluation is in exchange_field.cpp — compute_exchange_for_magnetization, and the optional consistent projection is in exchange_mass_projection.cpp — apply_exchange_component_mass_projection.

FEM / GPU — MFEM assembly plus FullMag CUDA CSR kernels¶

FEM GPU Exchange is FP64. Setup assembles the legacy sparse operator through MFEM on the host, canonicalizes it as a symmetric graph Laplacian, and uploads CSR and mass data once. Accepted RK stages apply the operator with FullMag CUDA kernels:

The device energy is equivalent to the assembled quadratic form

The stage path is device-resident after setup and records exchange-specific transfer counters. Consistent-mass projection is not a GPU realization. libCEED can be present in the runtime bundle, but it is not the Exchange hot path. The CUDA operator is backends/fem/gpu/cuda/exchange/exchange_kernels.cu — legacy_sparse_exchange_kernel; RK-stage dispatch is backends/fem/gpu/cuda/integrators/rk/rk_exchange_dispatch.cu — gpu_rk_compute_legacy_sparse_exchange.