Meshing¶

Bases: ConfigArea

How the geometry is discretized for the gmsh backend: the STEP source, domain-wide element size, and typed gmsh knobs.

Config:

• extra: forbid

Fields:

• step (str)
• global_mesh_size (float)
• gmsh_options (GmshOptions)
• deterministic (bool)

step: str = 'data/geometry.step'

global_mesh_size: float = 0.001

gmsh_options: GmshOptions

deterministic: bool = False

resolved_gmsh_options() -> GmshOptions

30
31
32
33
34

def resolved_gmsh_options(self) -> GmshOptions:
    """The options the mesher applies: ``gmsh_options``, thread-pinned to 1 when ``deterministic``."""
    if not self.deterministic:
        return self.gmsh_options
    return self.gmsh_options.model_copy(update={"num_threads": 1})

Bases: Protocol

The config surface the gmsh Mesher requires, which SimulationConfig satisfies structurally.

Attributes:

• frame (Frame) –

  The solve frame, whose model_dim is the body dimension of the STEP.

• mesh (MeshConfig) –

  The gmsh mesh settings (STEP source, element size, gmsh options).

• domain (DomainConfig) –

  The materials + per-region tags the mesher matches STEP entities against.

frame: Frame

mesh: MeshConfig

domain: DomainConfig

Bases: BaseModel

Typed gmsh meshing options; a knob left at None keeps gmsh's own default.

Config:

• validate_assignment: True
• use_attribute_docstrings: True

Fields:

• import_labels (bool)
• terminal_output (bool)
• algorithm_2d (MeshAlgorithm2D)
• algorithm_3d (MeshAlgorithm3D)
• recombine_all (bool)
• mesh_size_min (float | None)
• mesh_size_max (float | None)
• optimize (bool)
• smoothing (int | None)
• num_threads (int | None)
• target_units (str | None)

import_labels: bool = True

terminal_output: bool = False

algorithm_2d: MeshAlgorithm2D = MeshAlgorithm2D.FRONTAL_DELAUNAY

algorithm_3d: MeshAlgorithm3D = MeshAlgorithm3D.HXT

recombine_all: bool = False

mesh_size_min: float | None = None

mesh_size_max: float | None = None

optimize: bool = True

smoothing: int | None = None

num_threads: int | None

target_units: str | None = 'M'

apply(set_number: Callable[[str, float], None] | None = None, set_string: Callable[[str, str], None] | None = None) -> None

114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133

def apply(
    self,
    set_number: Callable[[str, float], None] | None = None,
    set_string: Callable[[str, str], None] | None = None,
) -> None:
    """Set each option that is not None under its ``Map(...)`` name, through ``set_number`` and ``set_string`` when given, else on the live gmsh option store."""
    # Imported here so loguru stays off the import path of every config.
    from femforge.common.log import log

    emit_number: Callable[[str, float], None] = _gmsh_set_number if set_number is None else set_number
    emit_string: Callable[[str, str], None] = _gmsh_set_string if set_string is None else set_string

    for option_name, value in mapped_items(self):
        # A str option (the OCC target unit) goes through setString; bool / IntEnum / int / float are all setNumber.
        if isinstance(value, str):
            log.bind(option=option_name, value=value).debug("Setting gmsh option.")
            emit_string(option_name, value)
        elif isinstance(value, (int, float)):
            log.bind(option=option_name, value=value).debug("Setting gmsh option.")
            emit_number(option_name, float(value))

Bases: IntEnum

A gmsh 2D meshing algorithm, valued as the integer Mesh.Algorithm takes.

Attributes:

• MESH_ADAPT –

  MeshAdapt, the most robust on complex curved surfaces.

• AUTOMATIC –

  Delaunay on plane surfaces and MeshAdapt on the rest.

• DELAUNAY –

  Delaunay, the fastest on large plane surfaces.

• FRONTAL_DELAUNAY –

  Frontal-Delaunay, gmsh's own default and the choice for high element quality.

MESH_ADAPT = 1

AUTOMATIC = 2

DELAUNAY = 5

FRONTAL_DELAUNAY = 6

Bases: IntEnum

A gmsh 3D meshing algorithm, valued as the integer Mesh.Algorithm3D takes.

Attributes:

• DELAUNAY –

  Delaunay, gmsh's own default and its most robust 3D mesher.

• FRONTAL –

  Frontal, Netgen's advancing-front tetrahedral mesher.

• MMG3D –

  MMG3D, for anisotropic tetrahedral meshes.

• HXT –

  HXT, a parallel reimplementation of Delaunay that spreads over the meshing threads.

DELAUNAY = 1

FRONTAL = 4

MMG3D = 7

HXT = 10

Bases: Protocol

Meshes a job into a gmsh .msh plus its group records; each backend decides where gmsh runs.

Methods:

• mesh –

  Mesh job into out_dir, raising MeshError when meshing fails.

mesh(job: MeshJob, out_dir: Path) -> MeshReport

101
102
103

def mesh(self, job: MeshJob, out_dir: Path) -> MeshReport:
    """Mesh ``job`` into ``out_dir``, raising [`MeshError`][femforge.meshing.backend.MeshError] when meshing fails."""
    ...

Bases: BaseModel

One meshing request as plain data: the mesh spec, the STEP to read, and the .msh to write.

Config:

• use_attribute_docstrings: True

Fields:

• spec (MeshSpec)
• step (str)
• msh (str)

spec: MeshSpec

step: str

msh: str = BundleFile.GEOMETRY_MSH

Bases: BaseModel

What one meshing job left: the .msh, its group records, and the gmsh release that wrote it.

Config:

• use_attribute_docstrings: True

Fields:

• msh (str)
• groups (MeshGroupsFile)
• gmsh_version (str)
• duration_s (float)

msh: str

groups: MeshGroupsFile

gmsh_version: str

duration_s: float

Bases: RuntimeError

Meshing failed: the STEP's bodies could not be grouped or meshed, or the mesh worker crashed or ran out of time.

The config surface a mesher reads, rebuilt from a MeshJob alone.

Attributes:

• frame (Frame) –

  A frame of the job's body dimension.

• mesh (MeshConfig) –

  The job's STEP and mesh settings.

• domain (DomainConfig) –

  Bare materials named by their tags, and the tag selectors with their element sizes.

frame: Frame

mesh: MeshConfig

domain: DomainConfig

Bases: MeshBackend

Meshes in this process with gmsh, which loads on the first job and is finalized after every one.

Methods:

• mesh –

  Mesh job into out_dir with gmsh in this process.

mesh(job: MeshJob, out_dir: Path) -> MeshReport

139
140
141
142
143

def mesh(self, job: MeshJob, out_dir: Path) -> MeshReport:
    """Mesh ``job`` into ``out_dir`` with gmsh in this process."""
    from femforge.meshing.gmsh_backend import mesh_with_gmsh

    return mesh_with_gmsh(job, out_dir)

Bases: MeshBackend

Meshes in a child Python process, so gmsh, its license and its crashes stay out of this one.

Parameters:

• python (str, default: executable ) –

  The interpreter that runs the worker.

• module (str, default: WORKER_MODULE ) –

  The worker module.

• timeout_s (float | None, default: None ) –

  Seconds before a job is stopped; None waits for it.

Methods:

• mesh –

  Mesh job into out_dir in a worker process, raising MeshError when the worker fails or leaves no outcome.

207
208
209
210
211
212
213
214
215
216
217

def __init__(self, *, python: str = sys.executable, module: str = WORKER_MODULE, timeout_s: float | None = None) -> None:
    """Mesh each job with ``python -m module``, stopped after ``timeout_s`` seconds when given.

    Args:
        python: The interpreter that runs the worker.
        module: The worker module.
        timeout_s: Seconds before a job is stopped; None waits for it.
    """
    self.python: str = python
    self.module: str = module
    self.timeout_s: float | None = timeout_s

mesh(job: MeshJob, out_dir: Path) -> MeshReport

219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253

def mesh(self, job: MeshJob, out_dir: Path) -> MeshReport:
    """Mesh ``job`` into ``out_dir`` in a worker process, raising [`MeshError`][femforge.meshing.backend.MeshError] when the worker fails or leaves no outcome."""
    from femforge.common.log import TELEMETRY_ENV, relay_record
    from femforge.execution.streaming import CommandResult, log_tail, run_streaming

    out_dir.mkdir(parents=True, exist_ok=True)
    # The worker meshes into the directory of an absolute msh, so the job file carries everything it needs.
    placed: MeshJob = job.model_copy(update={"step": str(Path(job.step).resolve()), "msh": str((out_dir / job.msh).resolve())})
    env: dict[str, str] = {name: value for name, value in os.environ.items() if name != TELEMETRY_ENV}
    env["PYTHONUTF8"] = "1"

    with tempfile.TemporaryDirectory(prefix="femforge-mesh-") as scratch:
        folder = Path(scratch)
        job_file: Path = folder / WORKER_JOB
        outcome_file: Path = folder / WORKER_OUTCOME
        _ = job_file.write_text(placed.model_dump_json(), encoding="utf-8")

        result: CommandResult = run_streaming(
            [self.python, "-m", self.module, str(job_file), str(outcome_file)],
            cwd=folder,
            log_path=folder / WORKER_LOG,
            on_line=functools.partial(relay_record, worker=WORKER_ROLE),
            timeout_s=self.timeout_s,
            env=env,
        )
        if not outcome_file.is_file():
            stopped: str = f"ran past its {self.timeout_s} s" if result.timed_out else f"exited with code {result.returncode}"
            raise MeshError(f"The mesh worker {stopped} without an outcome.\n{log_tail(result.log_path)}")

        outcome: MeshDone | MeshFailed = mesh_outcomes().validate_json(outcome_file.read_text(encoding="utf-8"))

    if isinstance(outcome, MeshFailed):
        raise MeshError(f"{outcome.error}: {outcome.message}")

    return outcome.report

Bases: BaseModel

Everything that decides the Elmer mesh files and their group names, and nothing that only decides the solve.

Config:

• use_attribute_docstrings: True

Fields:

• step_key (str)
• model_dim (Literal[2, 3])
• global_mesh_size (float)
• gmsh_options (GmshOptions)
• deterministic (bool)
• tags (list[TagSelectorSpec])
• materials (list[str])

step_key: str

model_dim: Literal[2, 3]

global_mesh_size: float

gmsh_options: GmshOptions

deterministic: bool

tags: list[TagSelectorSpec]

materials: list[str]

Bases: BaseModel

The grouping-relevant half of an EntityTag: its selector and per-region size, never its conditions.

Config:

• use_attribute_docstrings: True

Fields:

• selector (TagDict)
• mesh_size (float | None)

selector: TagDict

mesh_size: float | None = None

A single gmsh physical group plus the metadata to reconstruct the matching Elmer body; both sides share the same name and integer id.

Parameters:

• dim (int) –

  Topological dimension of the group.

• gmsh_id (int) –

  The gmsh physical-group tag.

• name (str) –

  The group name shared verbatim with Elmer.

• material (MaterialProperties) –

  The material of every entity in the group.

• tags (list[EntityTag]) –

  The EntityTag objects the group matched.

• entity_tags (list[int]) –

  The gmsh entity tags in the group.

• authored (str | None, default: None ) –

  The Name tag the entities were authored with, or None when the name is composed.

Methods:

• physical_group_name –

  The stable name the mesher and the sif writer both reference this region by, as MeshGroupSource requires.

Attributes:

• dim –

  Topological dimension of the group (3 = volume in a 3D model, 2 = surface in a 2D one).

• id –

  The integer the sif targets this region by: the gmsh tag until reconcile_ids sets the id ElmerGrid assigned.

• name –

  The authored part name, else the compound MATERIAL_TAG1_TAG2 name; shared verbatim with Elmer.

• authored –

  The Name tag the group's entities were authored with, or None when the name is composed.

• material –

  The material of every entity in the group.

• tags –

  EntityTag objects matched to this group (carry per-region overrides: fixed temperature, heat flux, magnetization direction).

• entity_tags –

  The gmsh entity tags (volumes in 3D, surfaces in 2D) that make up this group.

21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52

def __init__(self, dim: int, gmsh_id: int, name: str, material: MaterialProperties, tags: list[EntityTag], entity_tags: list[int], authored: str | None = None) -> None:
    """Record one body group.

    Args:
        dim: Topological dimension of the group.
        gmsh_id: The gmsh physical-group tag.
        name: The group name shared verbatim with Elmer.
        material: The material of every entity in the group.
        tags: The ``EntityTag`` objects the group matched.
        entity_tags: The gmsh entity tags in the group.
        authored: The ``Name`` tag the entities were authored with, or None when the name is composed.
    """
    self.dim = dim
    """Topological dimension of the group (3 = volume in a 3D model, 2 = surface in a 2D one)."""

    self.id = gmsh_id
    """The integer the sif targets this region by: the gmsh tag until [`reconcile_ids`][femforge.elmer.mesh_names.reconcile_ids] sets the id ElmerGrid assigned."""

    self.name = name
    """The authored part name, else the compound MATERIAL_TAG1_TAG2 name; shared verbatim with Elmer."""

    self.authored = authored
    """The ``Name`` tag the group's entities were authored with, or None when the name is composed."""

    self.material = material
    """The material of every entity in the group."""

    self.tags = tags
    """EntityTag objects matched to this group (carry per-region overrides: fixed temperature, heat flux, magnetization direction)."""

    self.entity_tags = entity_tags
    """The gmsh entity tags (volumes in 3D, surfaces in 2D) that make up this group."""

dim = dim

id = gmsh_id

name = name

authored = authored

material = material

tags = tags

entity_tags = entity_tags

physical_group_name() -> str

57
58
59

def physical_group_name(self) -> str:
    """The stable name the mesher and the sif writer both reference this region by, as [`MeshGroupSource`][femforge.common.protocols.MeshGroupSource] requires."""
    return self.name

Bases: BaseModel

groups.json: the group records and element count a mesh artifact carries beside ElmerGrid's files.

Config:

• use_attribute_docstrings: True

Fields:

• bodies (list[BodyGroupRecord])
• boundaries (list[BoundaryGroupRecord])
• element_count (int)

bodies: list[BodyGroupRecord]

boundaries: list[BoundaryGroupRecord]

element_count: int = 0

capture(physical_groups: Iterable[_BodySource], boundary_groups: Iterable[_BoundarySource], element_count: int) -> MeshGroupsFile

215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247

@classmethod
def capture(cls, physical_groups: Iterable[_BodySource], boundary_groups: Iterable[_BoundarySource], element_count: int) -> MeshGroupsFile:
    """Record the mesher's groups.

    Args:
        physical_groups: The body groups, in mesher order.
        boundary_groups: The boundary groups, in mesher order.
        element_count: Elements of the body dimension in the mesh.
    """
    return cls(
        bodies=[
            BodyGroupRecord(
                dim=group.dim,
                name=group.name,
                material=group.material.tag,
                selectors=[dict(tag.selector) for tag in group.tags],
                entity_tags=list(group.entity_tags),
                authored=group.authored,
            )
            for group in physical_groups
        ],
        boundaries=[
            BoundaryGroupRecord(
                dim=group.dim,
                name=group.name,
                bodies=tuple(group.bodies),
                face_tags=list(group.entity_tags),
                on_axis=group.on_axis,
            )
            for group in boundary_groups
        ],
        element_count=element_count,
    )

load(sim_dir: str | Path) -> MeshGroupsFile

249
250
251
252

@classmethod
def load(cls, sim_dir: str | Path) -> MeshGroupsFile:
    """Read ``groups.json`` from ``sim_dir``."""
    return cls.model_validate_json((Path(sim_dir) / BundleFile.GROUPS).read_text(encoding="utf-8"))

write(sim_dir: str | Path) -> Path

254
255
256
257
258

def write(self, sim_dir: str | Path) -> Path:
    """Write ``groups.json`` into ``sim_dir`` and return its path."""
    path: Path = Path(sim_dir) / BundleFile.GROUPS
    _ = path.write_text(self.model_dump_json(indent=2), encoding="utf-8")
    return path

Bases: BaseModel

One body group of a cached mesh: what it takes to rebuild its PhysicalGroup against a config.

Config:

• use_attribute_docstrings: True

Fields:

• dim (int)
• name (str)
• material (str)
• selectors (list[TagDict])
• entity_tags (list[int])
• authored (str | None)

dim: int

name: str

material: str

selectors: list[TagDict]

entity_tags: list[int]

authored: str | None = None

Bases: BaseModel

One boundary group of a cached mesh.

Config:

• use_attribute_docstrings: True

Fields:

• dim (int)
• name (str)
• bodies (tuple[str, ...])
• face_tags (list[int])
• on_axis (bool)

dim: int

name: str

bodies: tuple[str, ...] = ()

face_tags: list[int]

on_axis: bool = False

A single gmsh boundary physical group derived from body adjacency — the one-dimension-down sibling of PhysicalGroup, targeted by Elmer as Target Boundaries.

Names encode the bordering bodies: <BODYA>__<BODYB> (interface), <BODY>__EXT (external shell), or <BODY>__AXIS (symmetry axis).

Parameters:

• gmsh_id (int) –

  The gmsh physical-group tag.

• name (str) –

  The compound name shared verbatim with Elmer.

• bodies (tuple[str, ...]) –

  The one or two body group names the group borders.

• face_tags (list[int]) –

  The gmsh entity tags in the group.

• dim (int, default: 2 ) –

  Topological dimension of the group.

• on_axis (bool, default: False ) –

  Whether every entity lies on the symmetry axis of a 2D axisymmetric model.

Methods:

• physical_group_name –

  The stable name the mesher and the sif writer both reference this boundary by, as MeshGroupSource requires.

Attributes:

• dim –

  Topological dimension of the group -- one below the bodies it separates (2 = surface in a 3D model, 1 = curve in a 2D one), mirroring PhysicalGroup.dim.

• id –

  The integer the sif targets this boundary by: the gmsh tag until reconcile_ids sets the id ElmerGrid assigned.

• name –

  The compound BODYA__BODYB, BODY__EXT or BODY__AXIS name, shared verbatim with Elmer.

• bodies –

  The 1 (external or axis) or 2 (interface) body group names this boundary borders.

• entity_tags –

  The gmsh entity tags (surfaces in 3D, curves in 2D) that make up this group, mirroring PhysicalGroup.entity_tags.

• on_axis –

  True when every entity of this single-body group lies on the x=0 symmetry axis of a 2D axisymmetric model.

• is_external (bool) –

  True when this is a body's true external (far-field) shell: bordered by exactly one body and not on the symmetry axis.

• is_axis (bool) –

  True when this is a body's symmetry-axis boundary (the <BODY>__AXIS group of a 2D axisymmetric model).

34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61

def __init__(self, gmsh_id: int, name: str, bodies: tuple[str, ...], face_tags: list[int], dim: int = 2, on_axis: bool = False):
    """Record one boundary group.

    Args:
        gmsh_id: The gmsh physical-group tag.
        name: The compound name shared verbatim with Elmer.
        bodies: The one or two body group names the group borders.
        face_tags: The gmsh entity tags in the group.
        dim: Topological dimension of the group.
        on_axis: Whether every entity lies on the symmetry axis of a 2D axisymmetric model.
    """
    self.dim = dim
    """Topological dimension of the group -- one below the bodies it separates (2 = surface in a 3D model, 1 = curve in a 2D one), mirroring ``PhysicalGroup.dim``."""

    self.id = gmsh_id
    """The integer the sif targets this boundary by: the gmsh tag until [`reconcile_ids`][femforge.elmer.mesh_names.reconcile_ids] sets the id ElmerGrid assigned."""

    self.name = name
    """The compound ``BODYA__BODYB``, ``BODY__EXT`` or ``BODY__AXIS`` name, shared verbatim with Elmer."""

    self.bodies = bodies
    """The 1 (external or axis) or 2 (interface) body group names this boundary borders."""

    self.entity_tags = face_tags
    """The gmsh entity tags (surfaces in 3D, curves in 2D) that make up this group, mirroring ``PhysicalGroup.entity_tags``."""

    self.on_axis = on_axis
    """True when every entity of this single-body group lies on the x=0 symmetry axis of a 2D axisymmetric model."""

dim = dim

id = gmsh_id

name = name

bodies = bodies

entity_tags = face_tags

on_axis = on_axis

is_external: bool

is_axis: bool

physical_group_name() -> str

76
77
78

def physical_group_name(self) -> str:
    """The stable name the mesher and the sif writer both reference this boundary by, as [`MeshGroupSource`][femforge.common.protocols.MeshGroupSource] requires."""
    return self.name

One planned boundary group: the output of the pure adjacency partition, before gmsh assigns it a physical-group id.

Attributes:

• name (str) –

  The group name: A__B for an interface, A__EXT for an external shell, A__AXIS for a symmetry-axis boundary.

• bodies (tuple[str, ...]) –

  The one or two body group names the faces border, sorted.

• face_tags (tuple[int, ...]) –

  The boundary entity tags in the group, sorted.

• on_axis (bool) –

  Whether the group is a single body's boundary on the symmetry axis.

name: str

bodies: tuple[str, ...]

face_tags: tuple[int, ...]

on_axis: bool = False

A resolved per-region target element size and the volume tags it applies to.

Attributes:

• volume_tags (tuple[int, ...]) –

  The gmsh tags of the region's bodies (volumes in 3D, surfaces in 2D).

• size (float) –

  h [m]: Target element size.

volume_tags: tuple[int, ...]

size: float

Axis-aligned bounding box, center of mass and volume of one gmsh entity.

Attributes:

• dim (int) –

  Topological dimension of the entity.

• tag (int) –

  The gmsh entity tag.

• bbox_min (tuple[float, float, float]) –

  [m]: Lower corner of the axis-aligned bounding box.

• bbox_max (tuple[float, float, float]) –

  [m]: Upper corner of the axis-aligned bounding box.

• center_of_mass (tuple[float, float, float]) –

  [m]: Center of mass.

• volume (float) –

  V [?]: Volume, area or length of the entity by dim, in m³, m² or m.

• extent (tuple[float, float, float]) –

  [m]: Size of the bounding box along each axis.

dim: int

tag: int

bbox_min: tuple[float, float, float]

bbox_max: tuple[float, float, float]

center_of_mass: tuple[float, float, float]

volume: float

extent: tuple[float, float, float]