Mixed-element FEM meshes¶
Last changes: Documentation changelog
Physical problem¶
This FEM contract carries linear tet4, prism6, pyramid5, and imported hex8 cells explicitly. A family is solver input, not display metadata; preserving hex8 at ingress does not qualify an executable swept-hex solver.
Governing equations¶
Variable-arity connectivity is stored in typed CSR form:
Symbols and SI units¶
Symbol |
Meaning |
SI unit |
|---|---|---|
\(c\) |
Volume-cell ordinal |
\(1\) |
\(o_c\) |
Start offset of cell \(c\) |
\(1\) |
\(t_c\) |
Canonical cell family of cell \(c\) |
\(1\) |
\(a(t_c)\) |
Family node arity |
\(1\) |
\(K_c\) |
Local node-index sequence |
\(1\) |
Assumptions and validity¶
The carrier is linear typed topology: 4, 6, 5, and 8 nodes for tet4, prism6, pyramid5, and hex8. pyramid5 is a prism–tet transition family, not a prism replacement. Mixed compatibility views fail rather than converting to tetrahedra.
Python API¶
# %%
import fullmag as fm
nm = 1e-9
study = fm.study("mixed_film")
study.engine("fem")
study.device("cpu", precision="double")
study.mode("strict")
study.universe(mode="manual", size=(100 * nm, 80 * nm, 65 * nm), center=(0.0, 0.0, 0.0))
study.universe.mesh(maximum_element_size=40 * nm, minimum_element_size=15 * nm, growth_rate=1.3, grading="geometric")
# %%
film = study.geometry(fm.Box(size=(24 * nm, 12 * nm, 1 * nm), name="film"), name="film")
film.mesh.thin_film(
maximum_element_size=3 * nm,
minimum_element_size=1 * nm,
layers=1,
topology="prismatic",
exact_layers=True,
transition="pyramid_to_tetrahedra",
order=1,
)
film.Ms = 800e3
film.Aex = 13e-12
film.m = fm.texture.uniform(1.0, 1e-4, 0.0)
study.exchange()
study.demag(realization="poisson_robin")
study.build_domain_mesh()
study.stages.add_relax(stage_id="equilibrium", algorithm="llg_overdamped", tolA=1e-4, max_steps=20_000, dt=1e-13)
GeometryMeshHandle.thin_film is the supported public authoring callable for this strict route:
Python |
Type |
Default |
SI unit |
Validation |
Meaning |
Backend support |
ProblemIR |
|---|---|---|---|---|---|---|---|
|
|
|
\(\mathrm{m}\) |
positive finite number or |
Compatibility maximum-size alias |
FEM capability-gated; FDM N/A |
|
|
|
|
\(\mathrm{m}\) |
positive; overridden by |
Compatibility minimum-size alias |
FEM capability-gated; FDM N/A |
|
|
|
|
\(\mathrm{m}\) |
positive finite number or |
In-plane size ceiling |
FEM capability-gated; FDM N/A |
|
|
|
|
\(\mathrm{m}\) |
positive; takes precedence over |
Lower size bound |
FEM capability-gated; FDM N/A |
|
|
|
|
\(1\) |
prismatic topology accepts only |
FEM polynomial order |
FEM capability-gated; FDM N/A |
|
|
|
|
\(1\) |
float-convertible; downstream recipe requires a positive value when set |
Curvature-refinement strength |
FEM capability-gated; FDM N/A |
|
|
|
|
\(1\) |
float-convertible; downstream recipe requires a positive value when set |
Narrow-region refinement strength |
FEM capability-gated; FDM N/A |
|
|
|
|
\(1\) |
bool rejected; integer at least 1 |
Requested element-layer count |
FEM capability-gated; FDM N/A |
|
|
|
|
\(1\) |
one of |
Thin-film topology |
FEM capability-gated; FDM N/A |
|
|
|
|
\(1\) |
Boolean; only valid with prismatic topology; strict prismatic rejects |
Strict layer-count intent |
FEM capability-gated; FDM N/A |
|
|
|
|
\(1\) |
only valid with prismatic topology; prismatic resolves or requires |
Shared-domain transition |
FEM capability-gated; FDM N/A |
|
|
|
|
\(\mathrm{m}\) |
positive; used unless |
Interface size ceiling |
FEM capability-gated; FDM N/A |
|
|
|
|
\(\mathrm{m}\) |
positive; takes precedence over |
Surface alias for interface size |
FEM capability-gated; FDM N/A |
|
|
|
|
\(\mathrm{m}\) |
positive; used unless |
Interface refinement-shell thickness |
FEM capability-gated; FDM N/A |
|
|
|
|
\(\mathrm{m}\) |
positive; takes precedence over |
Surface alias for interface shell |
FEM capability-gated; FDM N/A |
|
|
|
|
\(\mathrm{m}\) |
number at least 0 or |
Interface-to-core transition distance |
FEM capability-gated; FDM N/A |
|
|
|
|
\(\mathrm{m}\) |
number at least 0 or |
Surface alias for transition distance |
FEM capability-gated; FDM N/A |
|
|
|
|
\(\mathrm{m}\) |
positive; must be paired with |
Edge size ceiling |
FEM capability-gated; FDM N/A |
|
|
|
|
\(\mathrm{m}\) |
positive; paired with |
Edge refinement-shell thickness |
FEM capability-gated; FDM N/A |
|
|
|
|
\(\mathrm{m}\) |
positive number or |
Edge-to-core transition distance |
FEM capability-gated; FDM N/A |
|
|
|
|
\(\mathrm{m}\) |
positive; paired with |
Corner size ceiling |
FEM capability-gated; FDM N/A |
|
|
|
|
\(\mathrm{m}\) |
positive; paired with |
Corner refinement extent |
FEM capability-gated; FDM N/A |
|
|
|
|
\(\mathrm{m}\) |
positive number or |
Corner-to-core transition distance |
FEM capability-gated; FDM N/A |
|
ProblemIR¶
For topology="prismatic", thin_film() lowers the request to mesh_strategy="swept_prism", through_thickness_elements=layers, through_thickness_distribution="fixed", through_thickness_symmetric=False, sweep_face_meshing="triangular", sweep_direction="auto", element_family="prism", transition_policy="pyramid_to_tetrahedra", exact_layer_count=True, and order=1. The underlying PerObjectMeshRecipe accepts through_thickness_distribution values None, fixed, linear, or exponential, and sweep_direction values None, auto, x, y, or z; those broader values are not additional arguments to thin_film().
All four transition-distance arguments accept the sentinels airbox_boundary, airbox-boundary, and auto_boundary; lowering canonicalizes each to airbox_boundary. Perimeter validation also enforces corner_hmax <= edge_hmax when both are active and, for a Box (including translated boxes), requires edge_thickness and corner_extent to be strictly smaller than half the shorter in-plane dimension.
Round-trip and failure semantics¶
Requested intent is the thin_film() call and lowered object policy. Resolved execution is the typed MeshData and realization report. Validation errors reject invalid CSR arity, invalid recipe distribution/direction, and any prismatic request whose transition is not pyramid_to_tetrahedra. That transition is mandatory because topology="prismatic"; it is not an unconditional rule for every policy whose family happens to be prism. Unsupported combinations include a solver/device lacking a realized family. No prism6, pyramid5, or hex8 is silently replaced by tet4.
Discrete realization¶
_MESHIO_VOLUME_TYPES maps tetra, wedge/prism, pyramid, and hexahedron to canonical types; _CELL_LOCAL_FACETS supplies the local tri3/quad4 faces.
Solver |
Device |
Status |
Reason |
|---|---|---|---|
FEM |
CPU |
source-backed, capability-gated |
Active execution must accept every realized family. |
FEM |
GPU |
source-backed, capability-gated |
No GPU runtime or parity evidence is claimed. |
FDM |
CPU |
not applicable |
FEM mesh topology. |
FDM |
GPU |
not applicable |
FEM mesh topology. |
Implementation mapping¶
GeometryMeshHandle.thin_film is the public authoring callable. PerObjectMeshRecipe owns the lowered policy. MeshData owns canonical typed variable-arity CSR, while the extraction maps preserve typed volume and facet families. test_mesh_data_accepts_canonical_mixed_typed_csr asserts typed mixed CSR and rejects tetra-only compatibility access.
Validation¶
Focused tests cover typed CSR, arity, offsets, node indices, facets, and Gmsh prism ordering. This is source/test evidence, not an executed CPU/GPU solver qualification.
Limitations¶
Imported hex8 preservation does not establish hex assembly, a qualified transition, CPU/GPU execution, or observable convergence.
Scientific bibliography¶
C. Geuzaine and J.-F. Remacle, “Gmsh,” International Journal for Numerical Methods in Engineering 79 (2009), doi:10.1002/nme.2579.
C. Abert, “Micromagnetics and spintronics,” European Physical Journal B 92 (2019), doi:10.1140/epjb/e2019-90599-6.
Source-code index¶
Path |
Stable symbol |
Responsibility |
|---|---|---|
Public prismatic authoring and lowering |
||
Lowered recipe validation and IR |
||
Canonical typed variable-arity CSR |
||
Canonical volume families |
||
Typed local facets |
||
No coercion regression |