Shared-domain assembly and conformity¶

Problem statement¶

The OCC route creates magnetic and air volumes, fragments them together, then extracts one shared-domain mesh with component and interface provenance.

Governing equations¶

Symbols and SI units¶

Assumptions and validity¶

The union states the OCC assembly domain. Conformity follows the source’s occ.fragment realization, not merely the value of a compatibility policy.

Python API¶

# %%
import fullmag as fm

# %%
nm = 1.0e-9
study = fm.study("assembly_contract")
study.engine("fem")
study.device("cpu", precision="double")
study.mode("strict")
study.universe(
    mode="manual",
    size=(320 * nm, 200 * nm, 120 * nm),
    center=(0.0, 0.0, 0.0),
    padding=(0.0, 0.0, 0.0),
)
study.universe.mesh(maximum_element_size=40 * nm, minimum_element_size=5 * nm, maximum_element_growth_rate=1.4)
film = study.geometry(fm.Box(size=(100 * nm, 50 * nm, 5 * nm), name="film"), name="film")
film.mesh(maximum_element_size=8 * nm, minimum_element_size=4 * nm)
film.Ms = 800.0e3
film.Aex = 13.0e-12
film.alpha = 0.02
film.m = fm.texture.uniform(1.0, 0.0, 0.0)
study.exchange()
study.demag(realization="poisson_robin")
study.stages.add_relax(stage_id="equilibrium", dt=5.0e-13, max_steps=1)

ProblemIR¶

Geometry, universe airbox and mesh policy lower as requested intent. Component volume tags, interface surface tags and final cell blocks are realized artifacts produced after OCC fragmentation.

Round-trip and failure semantics¶

Requested intent contains geometries, airbox and regions. Resolved execution contains OCC tags and extracted topology. Validation errors include empty geometry, missing airbox, invalid region identity/owner and non-contained conformal region. Unsupported combinations fail before extraction; they are not represented as conformal success.

Discrete realization¶

The builder creates an FEM mesh artifact for CPU or capability-gated GPU solver lanes. FDM CPU/GPU are not applicable.

Implementation mapping¶

StudyUniverseHandle and GeometryMeshHandle own authored intent; _build_problem and Problem.to_ir lower metadata and assets; generate_shared_domain_mesh_via_occ owns OCC fragmentation; the domain asset pipeline records build provenance; planner/runtime consume the resulting topology under separate compatibility and execution gates.

Validation¶

Inspect final region/interface tags, non-empty volumes and conformity diagnostics. Runtime solver/device execution remains unverified by source inspection.

Limitations¶

The source map documents OCC assembly, not a general nonconforming coupling path.

Scientific bibliography¶

Geuzaine and Remacle, IJNME 79 (2009), doi:10.1002/nme.2579.

Contract source-code index¶

Last changes: 12:31 24.08.2026

A conforming shared mesh represents each physical interface once, with common facet nodes referenced by adjacent regions. This is the default contract for coupled FEM operators in Fullmag.

Scope and purpose¶

Use this page when two materials touch, a magnet is embedded in an airbox, or several geometry objects participate in one FEM solve. The objective is a partition—not overlapping meshes and not two independently meshed surfaces that merely occupy the same coordinates.

Scientific and numerical model¶

Selection guide¶

Parameters¶

Python API¶

Complete Python example

import fullmag as fm

nm = 1.0e-9
study = fm.study("shared_domain_reference")
study.engine("fem")
study.device("cpu", precision="double")
study.mode("strict")
study.universe(
    mode="manual",
    size=(700 * nm, 500 * nm, 260 * nm),
    center=(0.0, 0.0, 0.0),
    padding=(0.0, 0.0, 0.0),
)
study.universe.mesh(
    minimum_element_size=12 * nm,
    maximum_element_size=90 * nm,
    maximum_element_growth_rate=1.5,
    grading="geometric",
)

left = study.geometry(
    fm.Box(size=(180 * nm, 80 * nm, 10 * nm), name="left_geom").translate(
        (-120 * nm, 0.0, 0.0)
    ),
    name="left",
)
right = study.geometry(
    fm.Box(size=(180 * nm, 80 * nm, 10 * nm), name="right_geom").translate(
        (120 * nm, 0.0, 0.0)
    ),
    name="right",
)
for body, direction in ((left, (1.0, 0.0, 0.0)), (right, (0.0, 1.0, 0.0))):
    body.mesh(
        mesh_strategy="free_tetrahedral",
        minimum_element_size=4 * nm,
        maximum_element_size=8 * nm,
        interface_maximum_element_size=6 * nm,
        interface_thickness=15 * nm,
        transition_distance="airbox_boundary",
        transition_growth=1.4,
        order=1,
        compute_quality=True,
    )
    body.Ms = 800.0e3
    body.Aex = 13.0e-12
    body.alpha = 0.02
    body.m = fm.texture.uniform(*direction)

study.exchange()
study.demag(realization="poisson_robin")
study.build_domain_mesh()
study.stages.add_relax(
    stage_id="equilibrium",
    algorithm="llg_overdamped",
    dt=5.0e-13,
    tolA=1.0e-4,
    max_steps=20_000,
)

Control Room workflow¶

1. Apply every object mesh policy and the Universe airbox policy.

2. Use Apply & Build Shared-Domain Mesh rather than relying on object previews.

3. In Mesh Details, inspect region inventory, interface inventory and facet-role counts.

4. Check conformity/orphan/nonmanifold diagnostics and the scoped quality report for each side of every interface.

5. Confirm that material and physics selections resolve to the intended region markers before run.

Conformity certificate¶

Require a complete cell-to-facet adjacency, exactly one geometric interface role per intended pair, zero unmatched/coincident duplicates, positive cell Jacobians and complete region ownership. For an interface field, compare traces/normals from both sides. For demag, check continuity of the scalar-potential representation and the expected normal-flux jump from magnetization.

Verification, quality and provenance¶

After every build, inspect the realized resource rather than assuming that the authored request was applied. The production check is:

• geometry and mesh revisions match the current model;

• requested and realized discretization/topology/order are recorded;

• node, element and boundary-facet counts are nonzero for every required region;

• region and boundary markers cover the complete topology;

• inverted and degenerate element counts are zero;

• interface diagnostics report no orphan, coincident, nonmanifold or unmatched facets;

• local size distributions are consistent with the intended edge/interface/core grading;

• any fallback or degradation has an explicit reason and an actual method;

• a mesh-refinement sequence demonstrates convergence of the scientific observable.

MeshQualityReport exposes signed inverse condition number (SICN), gamma/radius quality, volume statistics and optional per-element arrays. The source constants gamma_min=0.08 and SICN p05=0.1 are implementation gates for named report paths; they are not universal physical acceptance thresholds for every element family or study.

Diagnostics and failure semantics¶

• Adjacency degree 0 indicates an orphan facet; >2 indicates a nonmanifold facet unless explicitly modeled.

• Two facets with different nodes but coincident coordinates are duplicate/nonconforming.

• Boolean fragmentation can split one authored surface into several entities; semantic recovery must retain ownership.

• Overlapping volume cells or ambiguous region markers are blocking.

• A valid object mesh can become invalid after shared boolean assembly; inspect the final mesh.

Where this is implemented¶

Implementation map reviewed against commit 5db00ccf0113b9756fec2d46feb36ade762b12c2 on 2026-08-24.

Related documentation¶

• Build modes and fallbacks

• Selectors and attributes

References¶

• C. Geuzaine and J.-F. Remacle, “Gmsh: a three-dimensional finite element mesh generator with built-in pre- and post-processing facilities,” International Journal for Numerical Methods in Engineering 79 (2009), 1309–1331, doi:10.1002/nme.2579.

• C. Abert, “Micromagnetics and spintronics: models and numerical methods,” European Physical Journal B 92, 120 (2019), doi:10.1140/epjb/e2019-90599-6.

• Gmsh reference manual, mesh algorithms, size fields, extrusion and physical groups: gmsh.info/doc/texinfo.

Source-code index¶

• Python contract source: packages/fullmag-py/src/fullmag/model/discretization.py and packages/fullmag-py/src/fullmag/world.py, where applicable. Runtime realization is owned by the relevant backends/fdm or backends/fem implementation; the page must not claim a symbol not named in its implementation mapping.