Airbox mesh grading¶

Physical problem¶

study.universe.mesh(...) is the requested resolution of the FEM auxiliary airbox. It is not the magnetic-body mesh and it does not establish an observable error bound.

Governing equations¶

Symbols and SI units¶

Assumptions and validity¶

Controls are input constraints, not a quality or convergence certificate. The public validator accepts a finite growth rate only when \(0<g\leq2.5\); despite the error text naming the practical range 1.0-2.5, the code does not reject values in \((0,1)\). asset_pipeline lowers authored airbox_grading="auto" to the realized AirboxOptions.grading_mode="geometric". Gmsh narrow-region fields restrict body-surface/body-volume refinement so outer airbox faces are not treated as magnetic narrow-region walls.

Python API¶

# %%
import fullmag as fm
nm = 1e-9
study = fm.study("airbox_grading")
study.engine("fem")
study.device("cpu", precision="double")
study.mode("strict")
study.universe(mode="manual", size=(600 * nm, 400 * nm, 200 * nm))

# %%
study.universe.mesh(maximum_element_size=80 * nm, minimum_element_size=10 * nm, maximum_element_growth_rate=1.3, grading="geometric")
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¶

The facade resolves each canonical name over its alias, validates values, and StudyUniverseConfig.to_ir stores airbox_hmax, airbox_hmin, airbox_growth_rate, and airbox_grading. cell_size takes the separate FDM branch and writes _state._common_fdm_cell_size. The asset pipeline maps auto grading to geometric and passes the resolved values to AirboxOptions; these remain requested/effective controls, not measured edge lengths.

Round-trip and failure semantics¶

Requested intent is the full eight-parameter call. Resolved execution separates the FDM cell_size branch from normalized FEM controls, then records effective AirboxOptions, Gmsh field plan, and elements. Validation errors include non-positive sizes, non-finite growth, growth above 2.5, hmin > hmax, invalid grading, and the documented same-call and prior-state conflict branches for cell_size and FEM controls. Unsupported combinations include retaining a prior common FDM cell_size while configuring FEM universe controls or treating growth as a guaranteed layer sequence.

Discrete realization¶

Gmsh receives mesh options after shared-domain assembly. The narrow-region field confines body refinement to component surfaces/volumes; inspect the realized field plan, size statistics, and operation status.

Implementation mapping¶

Validation¶

Test rejection first, then record requested controls, realized field plan, size distribution, quality, and solver iterations. Refine one control at a time. No runtime receipt is provided.

Limitations¶

Current code bounds g and resolves the grading vocabulary, but has no universal formula from g to every realized element and no universal physics error estimator or runtime 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 mesh grading. 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 cell_size, grading factors, and size-transition controls. 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.