Airbox Build API¶

Python API¶

The complete runnable example is in the numbered example section below; the exact callable fields and arguments are in the numbered API section. These values are copied from the current Python contract, not inferred from the UI.

Symbols and SI units¶

All geometric lengths use \(\mathrm{m}\); dimensionless selectors use \(1\).

Assumptions and validity¶

Authoring validation does not prove mesh generation or solver qualification; the realized report is authoritative.

1. What it is and when to use it¶

study.build_domain_mesh() explicitly materializes the shared domain mesh (universe + objects + regions) before the stage graph executes.

When to use it:

• you want to validate the mesh and its quality before paying for a simulation,

• the script saves/loads a mesh artifact (study.mesh.save/load),

• you control invalidation points after geometry/policy edits.

Impact on the simulation: building is not a scientific certificate — success means a mesh was generated; qualification comes from inspecting the report and quality.

2. Physical and mathematical explanation¶

No equation of its own; the operation creates the discrete space shared by all operators. The key invariants are mesh conformity at object/air interfaces and correct region markers. Element quality is assessed through statistics (e.g. SICN/Jacobian measures) recorded in the report.

3. Example — complete Python script¶

# %% Explicit mesh build before stages
import fullmag as fm

nm = 1.0e-9

study = fm.study("airbox_build_example")
study.engine("fem")
study.device("cpu", precision="double")
study.mode("strict")

study.universe(mode="manual", size=(800 * nm, 400 * nm, 300 * nm))
study.universe.mesh(
    minimum_element_size=8 * nm,
    maximum_element_size=100 * nm,
    maximum_element_growth_rate=1.3,
    grading="geometric",
)

film = study.geometry(fm.Box(300 * nm, 100 * nm, 5 * nm), name="film")
film.Ms = 800.0e3
film.Aex = 13.0e-12
film.alpha = 0.02
film.m = fm.texture.uniform(1.0, 0.0, 0.0)
film.mesh(minimum_element_size=2.5 * nm, maximum_element_size=5 * nm,
          compute_quality=True)

study.exchange()
study.demag(model="airbox", variant="robin")

# Materialize the shared-domain mesh now (not lazily at first stage):
study.build_domain_mesh()

# Optional persistence of the realized mesh:
# study.mesh.save("run_output/domain_mesh.fmsh")

study.stages.add_relax(stage_id="equilibrium", tolT=1.0e-6)

4. Exact API¶

Failure behavior / invalidation:

• geometry, object/region policy, or universe changes invalidate the realization,

• study.mesh(...) without a realized mesh → API migration error (pointing to the correct facade),

• topology/authoring fingerprint mismatch on load → MeshConfigurationMismatch with a difference list.

ProblemIR mapping: realization and the build report land in provenance; requested intent stays separate from resolved execution.

ProblemIR¶

The request lowers to the mesh-workflow or discretization subtree; requested intent remains distinct from the resolved mesh asset and provenance report.

Round-trip and failure semantics¶

Requested intent is the Python policy; resolved execution is the realized mesh report. Validation errors identify the violated domain rule, and unsupported combinations fail explicitly without silent fallback.

Discrete realization¶

The backend consumes the realized Cartesian or finite-element asset, including topology, markers, quality, and provenance where available.

5. How to set it in Control Room¶

Model Explorer
└── Universe / Airbox      → selection kinds: airbox.*
    └── Mesh Build          → selection kind: airbox.mesh.build

The Airbox Mesh Build inspector (AirboxMeshBuildLanePanel) runs the build; the Quality/History tabs show the realized report. In the object panel, Build Mesh executes mesh.build-selected. Full build lifecycle description: Mesh Build Lifecycle; reports and quality: Mesh Quality and Reports.

6. Backend support¶

Validation¶

Focused constructor, lowering, and mesh-report tests are the evidence boundary for this page.

7. Limitations and known pitfalls¶

• Build success ≠ scientific qualification: always inspect the report and quality distributions.

• Do not reconstruct the realized mesh from the Python request after the run — retain the generated asset and provenance.

8. Scientific bibliography¶

No page-specific physical claims; airbox physics: FEM Airbox Mesh API.

9. Source-code index¶

Source-code index¶

• Python contract source: packages/fullmag-py/src/fullmag/model/discretization.py and packages/fullmag-py/src/fullmag/world.py, where applicable. Backend realization is in the relevant backends/fdm or backends/fem lane named by the page.