Airbox Geometry 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.universe(mode="manual", size=(Lx, Ly, Lz)) defines the exterior universe (airbox) geometry: a box enclosing all magnetic objects.

When to use it: always before building the shared FEM mesh with an airbox. Impact on the simulation: airbox dimensions set the distance of boundary conditions from the bodies — a too-small airbox distorts the stray field and demagnetization; a too-large one adds unnecessary elements.

2. Physical and mathematical explanation¶

The airbox is the magnetostatics solution domain (FEM Airbox Mesh API, section 2). The boundary-approximation error decays with distance \(d\) from the body; in practice, clearances of several to a dozen largest object dimensions are used, and correctness is verified by convergence with respect to \(d\):

where \(\mathbf{H}\) — magnetic field strength (\(\mathrm{A\,m^{-1}}\)), \(\phi\) — scalar potential (\(\mathrm{A}\)).

3. Example — complete Python script¶

# %% Manual universe geometry
import fullmag as fm

nm = 1.0e-9

study = fm.study("airbox_geometry_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(maximum_element_size=100 * nm)

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)

study.exchange()
study.demag(model="airbox", variant="robin")
study.build_domain_mesh()
study.stages.add_relax(stage_id="equilibrium", tolT=1.0e-6)

4. Exact API¶

study.universe(**kwargs) (StudyBuilder.universe, world.py):

Failure behavior: an invalid size vector → ValueError. Realized clearances and shape are recorded in the build report.

ProblemIR mapping: universe policy in mesh workflow metadata; realization in the report/provenance.

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.*

Exterior geometry (size, padding, center) is editable in the universe geometry panels; air sizing lives in Airbox Mesh Parameters (FEM Airbox Mesh Panel). Full panel overview: Meshing UI.

6. Backend support¶

Validation¶

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

7. Limitations and known pitfalls¶

• Changing universe geometry invalidates a built mesh (invalidation).

• Clearances are a physical decision: verify demag convergence with respect to airbox size instead of assuming one “good” size.

8. Scientific bibliography¶

1. J. D. Jackson, Classical Electrodynamics, 3rd ed., Wiley, 1999.

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.