Periodic FEM airbox mesh¶

Physical problem¶

study.pbc records axes and derives x_faces, y_faces, z_faces mesh IDs. The OCC path pairs matching outer min/max faces. demag="periodic_airbox_k0" is a static FEM request, not FDM image summation or nonzero-\(k\) Floquet demag.

Governing equations¶

Symbols and SI units¶

Assumptions and validity¶

The generator accepts axis-derived IDs only and rejects unknown IDs, zero span, and unmatched min/max faces. PeriodicBoundaryPair is a validated object descriptor, but it is not the direct input to this generator route. OCC owns translation, tolerance and Gmsh pairing realization; the descriptor owns authored validation and to_ir(). Planner acceptance is not runtime parity or convergence evidence.

Python API¶

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

# %%
study.universe.mesh(maximum_element_size=30 * nm, minimum_element_size=5 * nm)
study.pbc(x=True, y=True, z=False, demag="periodic_airbox_k0")
body = study.geometry(fm.Box(size=(200 * nm, 100 * nm, 5 * nm), name="cell"), name="cell")
body.mesh(maximum_element_size=6 * nm, minimum_element_size=3 * 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")
study.build_domain_mesh()
study.stages.add_relax(stage_id="equilibrium", algorithm="llg_overdamped", max_steps=1000)

ProblemIR¶

pbc coerces axes to booleans and synchronizes mesh IDs. With any true axis it constructs FdmPbc; FdmPbc.to_ir() serializes axes as periodic/open, normalized demag text, and optional integer image_counts. With no true axis, raw demag != "open" or non-None images raises before FdmPbc is constructed. PeriodicBoundaryPair.to_ir() independently serializes all required fields, fixed orientation source_to_destination, pairing policy, and optional axis hint. These are distinct lowerings.

Round-trip and failure semantics¶

Requested intent is axes, policy, images, and an optional independent descriptor. Resolved execution is normalized FdmPbc, derived IDs, OCC surface pairs/markers/tolerance, and planner acceptance/rejection. Validation errors include the raw no-axis demag != "open" or non-None images guard, non-open policy without an axis, images with any demag except truncated_images, image length other than three, negative image counts, empty descriptor strings, translation length other than three, non-positive tolerance, unknown OCC ID, zero span, and unmatched faces. Unsupported combinations include silent open fallback, using FDM image semantics as FEM periodic airbox, and nonzero-\(\mathbf{k}\) use of this policy.

The resolved execution is always reported separately from the authored descriptor.

Discrete realization¶

OCC selects candidate boundary surfaces, orders matching min/max faces, derives translation and a span-scaled tolerance, calls setPeriodic, creates dedicated periodic physical markers, and excludes exactly those paired tags from Gamma_out. asset_pipeline preserves extracted periodic_boundary_pairs and node pairs when assembling supported shared-domain assets. Planner periodic-airbox conditions include shared-domain air, demag, periodic constraints, and \(k=0\).

Implementation mapping¶

Validation¶

Inspect one-to-one pairs, translations, markers, extraction, and Gamma_out exclusion; test planner rejection for missing air, constraints, and nonzero \(\mathbf{k}\). Runtime was not run.

Limitations¶

The direct generator input is axis IDs, not descriptors. This is static k=0 semantics, not Floquet/Bloch or GPU parity evidence.

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 periodic FEM airbox meshes. 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 periodic pair identifiers, wave-vector or phase data, and mesh 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.