Spatial Parameter Fields¶

Contract¶

Spatial parameter fields replace a single material scalar by a deterministic field defined over a magnetic object or one of its object-owned regions. They are authored as typed data, not arbitrary Python callbacks, so the request can be serialized, validated, reproduced, and materialized by FDM or FEM planners.

A field assignment has five independent pieces of intent:

1. the owning magnetic object;

2. the optional object-region restriction;

3. the material parameter being replaced;

4. the typed field definition;

5. priority and conflict policy when assignments overlap.

The field is an override of the corresponding base material value. It is not added to the scalar and it does not implicitly create another magnetic object, interface coupling, or exchange break.

Governing equations¶

For a scalar material parameter \(p\), the base material supplies \(p_0\). An active field assignment \(a\) supplies \(p_a(\mathbf x)\). After ownership, region membership, priority, and conflict resolution, the realized value is

Here \(w_{a_*}=0\) when no assignment owns the point. A sharp transition has binary weight \(w_{a_*}\in\{0,1\}\); a weighted transition blends the winning field with the base value. For Ms and Aex, omitting material_transition resolves to mesh_relative(cells=3, scope="boundary"), so the default boundary width is three local mesh spacings and points on both sides of the boundary can have \(0<w_{a_*}<1\).

The built-in analytic field families are:

where \(\mathbf x_f\) is evaluated in the authored object or world frame. A sampled field instead references an immutable asset and declares its component count, mesh location, and unit metadata; sampled material-field materialization is currently authoring-only and is rejected by the planner.

Symbols and SI units¶

For example, an Ms field has values in \(\mathrm{A\,m^{-1}}\), while its linear gradient has units \(\mathrm{A\,m^{-2}}\). Aex values use \(\mathrm{J\,m^{-1}}\) and their spatial gradients use \(\mathrm{J\,m^{-2}}\). The unit string records the authored value-unit metadata without checking its dimensional consistency; the gradient unit follows from the spatial derivative and is not a second free choice.

Assumptions and validity¶

• Field values must be finite. The unit string is preserved as non-empty metadata when supplied; the Python factories do not check parameter-specific dimensions or convert units. Authors must provide SI-valued numbers according to the parameter table, while planner/runtime validation remains responsible for lane-specific legality.

• frame is exactly object or world. Object-frame fields move with the object; world-frame fields remain fixed in laboratory coordinates.

• Scalar parameters use scalar fields. Directional parameters such as AnisotropyAxis require a three-component constant or sampled representation supported by the selected lane.

• sampled fields require a non-empty asset identity, component_count >= 1, an explicit location from cell, node, element, or quadrature, and a non-empty unit. They are currently authoring-only: evaluate_parameter_field rejects sampled values before materialization.

• Region membership is evaluated before conflict resolution. A region-local assignment does not affect points outside that region.

• Equal-precedence overlaps with conflict_policy="error" fail closed. They are not resolved by insertion order.

• Mesh cardinality, interpolation, discontinuity handling, and device support are planner/runtime responsibilities and remain separate from successful Python construction.

Python API¶

# %% Build a stage-first FEM study with one region-scoped Ms field
import fullmag as fm

study = fm.study("region_owned_gradient_ms")
study.engine("fem")
study.device("cpu", precision="double")
study.mode("strict")
study.universe(
    mode="auto",
    size=(300e-9, 180e-9, 120e-9),
    center=(0.0, 0.0, 0.0),
    padding=(0.0, 0.0, 0.0),
)
study.universe.mesh(minimum_element_size=5e-9, maximum_element_size=80e-9)

track = study.geometry(
    fm.Box(size=(200e-9, 80e-9, 5e-9), name="permalloy_track"),
    name="permalloy_track",
)
track.Ms = 800e3
track.Aex = 13e-12
track.alpha = 0.02
track.m = fm.texture.uniform(1.0, 0.0, 0.0)

gradient_window = track.add_region(
    "gradient_window",
    fm.Box(size=(120e-9, 50e-9, 5e-9)),
    priority=10,
)
track.set_material_field(
    "Ms",
    fm.MaterialParameterField.linear(
        base=760e3,
        gradient=(0.0, 1.5e11, 0.0),
        frame="object",
        unit="A/m",
    ),
    region=gradient_window,
    assignment_id="permalloy_track_gradient_window_ms",
    priority=10,
    conflict_policy="error",
)

study.exchange()
study.stages.add_run(stage_id="inspect_material_field", until=1.0e-15)

ProblemIR¶

The field remains typed in material_parameter_fields; it is not flattened to mesh arrays before planning. The example above lowers conceptually to:

{
  "assignment_id": "permalloy_track_gradient_window_ms",
  "owner_object": "permalloy_track",
  "region_id": "permalloy_track:gradient_window",
  "parameter": "ms",
  "value": {
    "kind": "linear",
    "base": 760000.0,
    "gradient": [0.0, 150000000000.0, 0.0],
    "frame": "object",
    "unit": "A/m"
  },
  "priority": 10,
  "conflict_policy": "error"
}

Requested field identity, frame, region, units, and conflict policy remain visible after serialization. The resolved mesh-aligned array belongs to execution provenance, not requested intent.

Round-trip and failure semantics¶

Requested intent preserves the factory kind, authored values, coordinate frame, asset identity, object/region ownership, priority, conflict policy, and assignment ID. Resolved execution adds the concrete mesh location, interpolation/projection rule, normalized field storage, precision, device placement, and any emitted materialization statistics/provenance. No materialization digest is currently part of MaterialParameterAssignmentIR or the resolved field asset contract.

Validation errors reject non-finite data, invalid frames, non-positive radii, unknown parameter names, invalid sampled locations, empty asset identities, malformed component counts, and unresolved references. Asset existence and sampled-value loading are not performed by the current factories. Unsupported combinations fail capability checks explicitly; FullMag does not silently replace a sampled field by a scalar, move a world-frame field into object coordinates, or fall back from GPU to CPU in strict mode.

Changing geometry, region membership, mesh topology, sampled asset content, or field definition invalidates the corresponding resolved field provenance. Reusing an old materialized array after such a change is not a legal round-trip.

Discrete realization¶

A field being representable in Python and ProblemIR is not proof that every parameter, location, interpolation, or device combination is executable. The planner’s capability decision is authoritative for the requested slice.

Implementation mapping¶

• MaterialParameterField owns constant, linear, radial, and sampled field payloads.

• MaterialParameterAssignment owns object/region scope, canonical parameter name, identity, priority, and conflict policy.

• ObjectRegion owns local overrides and optional material-transition intent.

• The Ferromagnet material_parameter_fields collection carries assignments through canonical problem lowering.

• FDM/FEM planners and runners own mesh-specific materialization and capability decisions.

• crates/fullmag-plan/src/material.rs owns analytic evaluation, transition weighting, and the fail-closed sampled-field boundary.

• crates/fullmag-plan/src/material_transition.rs resolves the default Ms/Aex transition.

Validation¶

The minimum validation suite is:

1. analytic value checks for constant, linear, and radial factories in object and world frames;

2. exact normalization of parameter aliases to canonical ProblemIR names;

3. region support tests at inside, outside, and boundary points;

4. deterministic overlap tests for every conflict policy and equal-priority failure;

5. sampled asset identity, component-count, location, and mesh-cardinality checks (materialization remains unsupported until the asset-loading path exists);

6. scalar-versus-vector compatibility tests;

7. round-trip preservation of IDs, units, frames, priorities, and region references;

8. FDM/FEM refinement tests that separate field interpolation error from operator error;

9. CPU/GPU comparison of materialized arrays before comparing solver trajectories;

10. stale-provenance rejection after geometry, mesh, region, or asset revision changes.

Construction and serialization tests validate authoring. Scientific qualification additionally requires interaction-specific observables, convergence, and device evidence.

Limitations¶

• Arbitrary Python callables are intentionally not serializable field definitions.

• The current analytic family is constant, linear, and radial; more complex profiles require a sampled asset or a separately versioned typed field.

• Sampled-field interpolation is not globally interchangeable between cell, node, element, and quadrature locations.

• Object-region v1 supports a bounded set of canonical shapes and realization policies.

• Conflict resolution cannot repair physically inconsistent overlapping material definitions.

• A smooth authored parameter field does not guarantee that the mesh resolves its shortest spatial scale; convergence remains the user’s and validator’s responsibility.

Scientific bibliography¶

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

• A. Hubert and R. Schäfer, Magnetic Domains, Springer, 1998.

• O. C. Zienkiewicz, R. L. Taylor, and J. Z. Zhu, The Finite Element Method: Its Basis and Fundamentals, 7th ed., Butterworth-Heinemann, 2013.

Control Room crosswalk¶

Status: Scalar magnetic fields are partial; spatial fields and material-law-specific parameters remain not implemented.

frontend support is not implemented for spatial material fields and every parameter not rendered by ObjectMaterialPanel. See Control Room capability register for the support matrix and not implemented policy. Frontend source owner: apps/control-room/src/modules/inspector/panels/ObjectMaterialPanel.tsx (ObjectMaterialPanel).

Source-code index¶