Boundary-Layer 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¶

Boundary layers are anisotropic element refinement near selected object surfaces/edges. In Fullmag you author them through recipe fields (boundary_layer_count/thickness/stretching) or an explicit MeshOperation(kind="boundary_layers", params=...) in an advanced recipe.

When to use it:

• strong field/energy gradients at surfaces (EASA, surface anisotropy, interface layers),

• normal-to-wall resolution without global refinement.

Impact on the simulation: layers improve normal resolution at controlled cost; excessive stretching degrades Jacobian quality and can harm convergence.

2. Physical and mathematical explanation¶

This page introduces no equation of its own; it controls discretization anisotropy. A typical layer thickness distribution is geometric:

where \(t_i\) — thickness of the \(i\)-th layer (\(\mathrm{m}\)), \(s\) — stretching ratio (\(1\), usually \(1{<}s{\le}2\)), \(T\) — total package thickness (\(\mathrm{m}\)), \(N\) — layer count (\(1\)).

3. Example — complete Python script¶

# %% Boundary layers on a film surface via advanced recipe fields
import fullmag as fm

nm = 1.0e-9

study = fm.study("boundary_layer_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,
    order=1,
    boundary_layer_count=2,
    boundary_layer_thickness=1.0 * nm,
    boundary_layer_stretching=1.5,
)

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¶

Two equivalent authoring levels:

Recipe fields (object.mesh(...) / PerObjectMeshRecipe):

Ordered operation: MeshOperation(kind="boundary_layers", params=...) inside PerObjectMeshRecipe.operations; params keys cover count, total thickness, stretching, and the same selectors/tags.

Prefer semantic selectors: numeric Gmsh tags are not stable across geometry rebuilds.

Failure behavior: non-positive count/thickness, stretching outside \((1,2]\) → ValueError; unknown params keys → operation validation error.

ProblemIR mapping: fields land in the object recipe (PerObjectMeshRecipe) and in the ordered mesh-operation list.

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 Backend Mesh Parameters group holds the boundary-layer fields; the Advanced JSON group accepts the full canonical recipe payload (including operations). 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¶

• Numeric Gmsh tags are unstable across geometry rebuilds — use semantic selectors.

• Stretching close to \(2\) can produce poor-Jacobian elements; check quality statistics after the build.

8. Scientific bibliography¶

1. C. Geuzaine and J.-F. Remacle, “Gmsh,” Int. J. Numer. Methods Eng. 79, 1309–1331 (2009).

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.