Airbox geometry and enclosure¶

Physical problem¶

The FEM airbox is the finite auxiliary domain around magnetic bodies. study.universe(...) authors it; it neither creates a mesh nor selects a demagnetization boundary condition. mode="manual" requires size; mode="auto" retains automatic-universe intent.

Governing equations¶

For manual rectangular input, the authored bounds are:

For mode="auto" with positive per-axis padding, asset_pipeline._study_universe_airbox_options resolves the aggregate object bounds exactly as

Symbols and SI units¶

Assumptions and validity¶

padding is validated and serialized. With no declared size, the asset pipeline uses the two auto equations above when at least one padding component is positive; otherwise it returns no airbox options. A declared size is authoritative in either manual or auto mode and is checked against aggregate geometry bounds with a scale-aware tolerance. AirboxOptions(shape="sphere") exists below this API; component-aware and concatenated-STL paths can report a bbox degradation. Mesh and outer-distance convergence remain separate scientific work.

Python API¶

# %%
import fullmag as fm
nm = 1e-9
study = fm.study("manual_airbox")
study.engine("fem")
study.device("cpu", precision="double")
study.mode("strict")

# %%
study.universe(mode="manual", size=(600 * nm, 400 * nm, 200 * nm), center=(0.0, 0.0, 0.0), padding=(0.0, 0.0, 0.0))
study.universe.mesh(maximum_element_size=80 * nm, minimum_element_size=10 * nm)
body = study.geometry(fm.Box(size=(200 * nm, 100 * nm, 10 * nm), name="film"), name="film")
body.mesh(maximum_element_size=8 * nm, minimum_element_size=4 * nm, order=1)
body.Ms = 800e3
body.Aex = 13e-12
body.m = fm.texture.uniform(1.0, 0.0, 0.0)

# %%
study.exchange()
study.demag(model="airbox", variant="robin")
study.build_domain_mesh()
study.stages.add_relax(stage_id="equilibrium", algorithm="llg_overdamped", max_steps=1000)

ProblemIR¶

StudyUniverseConfig.to_ir writes mode, size, center, padding, airbox_hmax, airbox_hmin, airbox_growth_rate, and airbox_grading. The table rows map one-to-one to the first four keys. _study_universe_airbox_options lowers explicit bounds or computes auto bounds and returns AirboxOptions(size=..., center=...); this resolved mesher input remains distinct from observed mesh coordinates.

Round-trip and failure semantics¶

Requested intent is StudyUniverseConfig. Resolved execution first includes the explicit or auto AirboxOptions produced by asset_pipeline, then the shared-domain mesh/report after study.build_domain_mesh(). Validation errors include invalid mode, non-positive size, negative padding, manual mode without size, and explicit bounds that do not contain all geometry. Unsupported combinations include treating the FEM airbox as an FDM grid or assuming a requested sphere is always realized.

Discrete realization¶

_study_universe_airbox_options owns conversion of authored universe metadata into AirboxOptions. _rectangular_airbox_bounds_from_options then resolves rectangular min/max bounds from center and size. build_domain_mesh materializes the shared-domain FEM mesh.

Implementation mapping¶

Validation¶

Reject invalid authoring inputs, then inspect realized bounds, air elements, markers, boundary facets, and operation statuses. Vary outer distance independently from mesh controls for physics convergence. Runtime and device evidence are not supplied here.

Limitations¶

The padding expansion and bbox center are source-backed, but they do not provide an open-boundary error estimate, Robin coefficient, mesh-convergence receipt, or GPU qualification.

Scientific bibliography¶

• C. Geuzaine and J.-F. Remacle, International Journal for Numerical Methods in Engineering 79 (2009), doi:10.1002/nme.2579.

Source-code index¶

Scope and purpose¶

This page defines the public contract for FEM airbox geometry. It is an authoring and implementation reference: the Python example, the serialized ProblemIR description, the implementation mapping, and the adjacent source map are the source-backed contract. A capability marked partial or not evaluated is not presented as a production guarantee.

Scientific and numerical model¶

The mesh or grid is a discrete approximation of the continuous domain. For a Cartesian partition, each spacing satisfies Delta_i = L_i / N_i; for a geometry-dependent FEM mesh, the requested local target is bounded by the active bulk, interface, boundary, and topology constraints. In compact form, h_target(x) = min(h_bulk(x), h_interface(x), h_boundary(x)). Length quantities use SI metres (m); counts, orders, and topology labels are dimensionless.

The equations and assumptions in the earlier physical-problem and governing-equations sections state the model-specific specialization. This section does not introduce a conversion from FEM to FDM, a hidden topology conversion, or a silent CPU fallback.

Parameters¶

The exact callable and argument names are the ones shown in the ## Python API section above. For this page the parameter family is geometry extents, padding, and mesh target. Use the documented defaults, validation rules, and ProblemIR lowering exactly as shown; do not replace a canonical argument with an unlisted alias. Numerical lengths must be supplied in metres, and invalid positive-length, count, order, periodicity, or topology constraints must fail closed rather than being silently repaired.

Control Room workflow¶

In Control Room, select the engine and mesh workflow, enter the same values as the Python authoring example, inspect the planned mesh or grid report, and only then submit the run. The UI is a projection of the public contract: a missing control is not evidence that the backend accepts the option, and a visible control is not evidence that a production lane is enabled. When the page or capability register marks a field partial or not evaluated, keep the workflow explicitly bounded to the implemented path.

Diagnostics and failure semantics¶

A valid request must preserve the declared geometry, units, element or cell topology, and backend lane. Reject non-finite or non-positive lengths, invalid counts and orders, incompatible periodic or shared-boundary data, and unsupported topology combinations at the owning validation layer. Reports should retain requested and resolved values, source identity, and any capability gate. No diagnostic may hide a failed mesh realization by substituting another discretization.

Where this is implemented¶

The existing implementation-mapping and source-code-index sections identify the exact public authoring, ProblemIR, planner, realization, and runtime owners for this topic. The adjacent .source-map.json file is the machine-readable source of truth for those paths, symbols, responsibilities, backend matrix, and reviewed revision. Claims in this page must be updated together with that map when an owner moves.