Swept-Hex 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¶

mesh_strategy="swept_hex" represents a swept hexahedral mesh: quadrilateral source faces and the hex element family in an object recipe.

When to use it: never in production today. Python representability is not a production qualification — Control Room exposes this option as unsupported, and the prism-to-pyramid combination is contradictory and rejected.

This page documents the API boundary: what is representable, what validation accepts, and what realization does not guarantee.

2. Physical and mathematical explanation¶

No physical model of its own; this page describes only the topological contract of the recipe. The contradictory contract (pyramid→tetrahedra transition for hexes) is rejected by validation — no correct realization of that transition exists in the current shared-domain mesh pipeline.

3. Example — complete Python script¶

No working production example exists. Recipe-level representation:

# %% NOT PRODUCTION: representable recipe only; UI exposes this as unsupported
# PerObjectMeshRecipe(
#     mesh_strategy="swept_hex",
#     sweep_face_meshing="quadrilateral",
#     element_family="hex",
# )

For real thin-film scenarios use Swept-Prism API.

4. Exact API¶

Failure behavior: transition_policy="pyramid_to_tetrahedra" together with swept_hex → ValueError (contradictory combination).

ProblemIR mapping: fields land in the object recipe; no qualified backend realization exists.

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
└── Objects
    └── <object>
        └── Mesh            → selection kind: object.mesh

The Object Mesh Policy inspector: the swept_hex option appears as unsupported/disabled — the UI gate refuses to save it. Full panel description: FEM Object Mesh Panel.

6. Backend support¶

Validation¶

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

7. Limitations and known pitfalls¶

• Do not assume “Python accepted it, so it works”: representability ≠ production qualification.

• Bypassing through advanced recipe JSON ends in a validation error or an explicit fallback recorded in the build report.

8. Scientific bibliography¶

No physical claims on this page.

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.