palace-toolkit 0.1.0__py3-none-any.whl

palace_toolkit-0.1.0.dist-info/METADATA

@@ -0,0 +1,29 @@
+Metadata-Version: 2.4
+Name: palace-toolkit
+Version: 0.1.0
+Summary: PALACE electromagnetic simulation course materials
+Requires-Python: >=3.8
+Requires-Dist: gmsh
+Requires-Dist: numpy
+Requires-Dist: scipy
+Requires-Dist: meshio
+Requires-Dist: mfem
+Requires-Dist: pyvista
+Requires-Dist: enlighten
+Requires-Dist: pint
+Provides-Extra: plot
+Requires-Dist: pandas; extra == "plot"
+Requires-Dist: matplotlib; extra == "plot"
+Provides-Extra: palace-cpu
+Requires-Dist: palacetoolkit-palace-cpu>=0.1.0; extra == "palace-cpu"
+Provides-Extra: docs
+Requires-Dist: mkdocs; extra == "docs"
+Requires-Dist: mkdocs-material; extra == "docs"
+Requires-Dist: mkdocs-jupyter; extra == "docs"
+Requires-Dist: pyvista[jupyter]; extra == "docs"
+Requires-Dist: nbconvert; extra == "docs"
+Requires-Dist: ipykernel; extra == "docs"
+Requires-Dist: papermill; extra == "docs"
+Requires-Dist: pytest; extra == "docs"
+Requires-Dist: nb-clean; extra == "docs"
+Requires-Dist: pre-commit; extra == "docs"

palace_toolkit-0.1.0.dist-info/RECORD

@@ -0,0 +1,16 @@
+palacetoolkit/__init__.py,sha256=LIoHyIWZYLD3Z6ttthkp1xMb2Xbpmj7hLzEK_wKVwmg,1008
+palacetoolkit/analytic.py,sha256=5EWEfOOpO4i4Ag_vkNV9sqn_eNA10Ip1S-Z0njERPAo,1821
+palacetoolkit/geometry.py,sha256=due6wyFo8v2a0YLXfS5fyo0L8ML_X1a4B92mbUlZHkM,1353
+palacetoolkit/mesh.py,sha256=s63qoFD6o3POcoxs7u8BeX0ziK8_t2CsseZ6MpXJKzA,18627
+palacetoolkit/mode_solver.py,sha256=7epK5U7tmRPLd84ystXUA_4JBX66FjivGIVO3q0S3f8,34406
+palacetoolkit/palace_runtime.py,sha256=olMBIgLAlGQLSOEFAobktZ1_QlBL1MNjR4CoLse6VBk,1249
+palacetoolkit/plot_farfield.py,sha256=xNBZNe6N1veYjhgP1N0k1pZqAIe08FllJ9npOvqxYHo,10544
+palacetoolkit/s_plot.py,sha256=Fx4Q1dTeYH-QDfj-jJiQ3k5DN2zYYY9abBih2O6wNDQ,902
+palacetoolkit/simulation.py,sha256=G_KLAqXypkN_m_7fk4uvpJm90EwPps_7VuS25mEB2es,16545
+palacetoolkit/utils.py,sha256=BjcbXMmfX63Y_oAqXDHK7SNTtJRo6IpGjIGp590Pe98,15334
+palacetoolkit/verify_topology.py,sha256=ulU4fXknKMmVHIwV0YlHekXwq-y4mFj-csoMZXlmbtc,34348
+palacetoolkit/viz.py,sha256=oKZs6ck3blTGlDmJ2z9mNw34xNY3KEPIvdklJhk7GFA,35640
+palace_toolkit-0.1.0.dist-info/METADATA,sha256=QH4zbRG64Sxu3aAi9wntXGMSoVw1ytStoNizIza2bJg,966
+palace_toolkit-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+palace_toolkit-0.1.0.dist-info/top_level.txt,sha256=3xE5XaV7aN2_Hf6IHJ3OJGEV1pSO9fkvLW2b2j4U7e8,14
+palace_toolkit-0.1.0.dist-info/RECORD,,

palace_toolkit-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

palace_toolkit-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+palacetoolkit

palacetoolkit/__init__.py

@@ -0,0 +1,31 @@
+"""PalaceToolkit — utilities for Palace electromagnetic simulations.
+
+Import as::
+
+    from palacetoolkit.analytic import cpw_impedance
+    from palacetoolkit.mesh import Entity, run_meshing_pipeline
+    from palacetoolkit.simulation import run_palace, generate_palace_config
+    from palacetoolkit.viz import view_mesh
+    from palacetoolkit.verify_topology import analyse_mesh
+"""
+
+from palacetoolkit.analytic import *          # noqa: F401,F403
+from palacetoolkit.mesh import *              # noqa: F401,F403
+from palacetoolkit.simulation import *         # noqa: F401,F403
+from palacetoolkit.verify_topology import *   # noqa: F401,F403
+
+# Optional submodules — silently skip when extra deps are missing
+try:
+    from palacetoolkit.s_plot import *        # noqa: F401,F403
+except ImportError:
+    pass
+
+try:
+    from palacetoolkit.viz import *           # noqa: F401,F403
+except ImportError:
+    pass
+
+try:
+    from palacetoolkit.utils import *         # noqa: F401,F403
+except ImportError:
+    pass

palacetoolkit/analytic.py

@@ -0,0 +1,60 @@
+"""Analytic closed-form expressions for transmission line parameters."""
+
+import numpy as np
+
+def _K_over_Kp(k: float, kp: float) -> float:
+    """Approximate ratio K(k)/K(k') using the Hilberg formula."""
+    def _s(x: float) -> float:
+        return np.log(
+            2 * (np.sqrt(1 + x) + (4 * x) ** 0.25)
+            / (np.sqrt(1 + x) - (4 * x) ** 0.25)
+        )
+
+    if k >= 1.0 / np.sqrt(2):
+        return _s(k) / (2 * np.pi)
+    else:
+        return 2 * np.pi / _s(kp)
+
+def cpw_impedance(w: float, s: float, h: float, eps_r: float) -> float:
+    """Compute the characteristic impedance of a CPW line.
+
+    Uses the conformal mapping approach with elliptic integral ratios K(k)/K(k').
+
+    Args:
+        w:     Centre conductor width.
+        s:     Gap between centre conductor and ground.
+        h:     Substrate thickness.
+        eps_r: Relative permittivity of the substrate.
+
+    Returns:
+        Z0: Characteristic impedance in Ohms.
+    """
+    k  = w / (w + 2 * s)
+    k1 = np.sinh(np.pi * w / (4 * h)) / np.sinh(np.pi * (w + 2 * s) / (4 * h))
+
+    kp  = np.sqrt(1 - k ** 2)
+    k1p = np.sqrt(1 - k1 ** 2)
+
+    kok  = _K_over_Kp(k,  kp)
+    k1ok = _K_over_Kp(k1, k1p)
+
+    eps_eff = 1 + ((eps_r - 1) / 2) * k1ok / kok
+    Z0 = 30 * np.pi / (kok * np.sqrt(eps_eff))
+    return Z0
+
+
+def cpw_effective_index(w: float, s: float, h: float, eps_r: float) -> float:
+    """Return the effective refractive index of a CPW line.
+
+    Uses the same conformal-mapping model as :func:`cpw_impedance`.
+    """
+    k  = w / (w + 2 * s)
+    k1 = np.sinh(np.pi * w / (4 * h)) / np.sinh(np.pi * (w + 2 * s) / (4 * h))
+
+    kp  = np.sqrt(1 - k ** 2)
+    k1p = np.sqrt(1 - k1 ** 2)
+    kok  = _K_over_Kp(k,  kp)
+    k1ok = _K_over_Kp(k1, k1p)
+
+    eps_eff = 1 + ((eps_r - 1) / 2) * k1ok / kok
+    return np.sqrt(eps_eff)

palacetoolkit/geometry.py

@@ -0,0 +1,48 @@
+import gmsh
+
+def extract_tag(obj):
+    """
+    Extract the Gmsh tag from an object.
+
+    If object contains only one tag, return it as an integer, otherwise, preserve its
+    container.
+
+    Most gmsh functions return list of tuples like [(2, 5), (2, 8), (2, 10), ...], where the
+    first number is dimensionality and the second is the integer tag associated to that object.
+
+    Examples
+    --------
+    >>> extract_tag((3, 6))
+    6
+
+    >>> entities = [(2, 5), (2, 8), (2, 10)]
+    >>> [extract_tag(e) for e in entities]
+    [5, 8, 10]
+    """
+
+    if isinstance(obj, list) and len(obj) == 1:
+        return extract_tag(obj[0])
+    elif isinstance(obj, tuple):
+        return obj[1]
+    else:
+        raise ValueError("Expected a tuple or single-element list")
+
+
+# Convenience functions to extract extrema of the bounding box of an entity
+def xmin(dimtag):
+    return gmsh.model.occ.getBoundingBox(dimtag[0], dimtag[1])[0]
+
+def ymin(dimtag):
+    return gmsh.model.occ.getBoundingBox(dimtag[0], dimtag[1])[1]
+
+def zmin(dimtag):
+    return gmsh.model.occ.getBoundingBox(dimtag[0], dimtag[1])[2]
+
+def xmax(dimtag):
+    return gmsh.model.occ.getBoundingBox(dimtag[0], dimtag[1])[3]
+
+def ymax(dimtag):
+    return gmsh.model.occ.getBoundingBox(dimtag[0], dimtag[1])[4]
+
+def zmax(dimtag):
+    return gmsh.model.occ.getBoundingBox(dimtag[0], dimtag[1])[5]

palacetoolkit/mesh.py

@@ -0,0 +1,468 @@
+"""Gmsh utilities: boolean pipeline, mesh generation helpers."""
+
+import gmsh
+
+
+# ---------------------------------------------------------------------------
+# Minimalistic meshwell-style entity + pipeline
+# ---------------------------------------------------------------------------
+
+class Entity:
+    """A named geometric entity with priority (mesh_order) and tracked dimtags."""
+
+    def __init__(self, name: str, dim: int, mesh_order: int, tags: list[int]):
+        self.name = name
+        self.dim = dim
+        self.mesh_order = mesh_order
+        self.dimtags = [(dim, t) for t in tags]
+
+    def __repr__(self):
+        return f"Entity({self.name!r}, dim={self.dim}, order={self.mesh_order}, tags={[t for _, t in self.dimtags]})"
+
+
+def run_meshing_pipeline(entities: list[Entity]):
+    """
+    Meshwell-style boolean pipeline (minimalistic).
+
+    1. Group entities by dimension (descending: 3 -> 0).
+    2. Within each dimension, sort by mesh_order (ascending = higher priority).
+    3. Priority cuts: each entity is cut by all previously processed entities
+       in the same dimension (removeObject=True, removeTool=False).
+    4. Fragment current dimension against all higher-dimension entities
+       already processed, then update tags via the returned mapping.
+    5. Accumulate processed entities for the next (lower) dimension.
+    """
+    gmsh.model.occ.synchronize()
+
+    # Group by dimension
+    dim_groups: dict[int, list[Entity]] = {3: [], 2: [], 1: [], 0: []}
+    for e in entities:
+        dim_groups[e.dim].append(e)
+
+    # Sort each group by mesh_order (ascending = higher priority first)
+    for dim in dim_groups:
+        dim_groups[dim].sort(key=lambda e: e.mesh_order)
+
+    processed_higher_dims: list[Entity] = []
+
+    for dim in (3, 2, 1, 0):
+        current_group = dim_groups[dim]
+        if not current_group:
+            continue
+
+        # Move the fragment-against-higher-dims step to run BEFORE priority cuts so that all surface tags are refreshed from the fragment output map before any cut is attempted.
+
+        # --- A. Priority cuts within same dimension ---
+        processed_in_dim: list[Entity] = []
+        for entity in current_group:
+            # Collect tool dimtags from all previously processed entities in this dim
+            tool_dimtags = [dt for prev in processed_in_dim for dt in prev.dimtags]
+
+            if tool_dimtags and entity.dimtags:
+                cut_result, _ = gmsh.model.occ.cut(
+                    entity.dimtags,
+                    tool_dimtags,
+                    removeObject=True,
+                    removeTool=False,
+                )
+                gmsh.model.occ.synchronize()
+                entity.dimtags = list(set(cut_result))
+
+            if entity.dimtags:
+                processed_in_dim.append(entity)
+
+        # --- B. Fragment against higher dimensions ---
+        if processed_higher_dims and processed_in_dim:
+            object_dimtags = [dt for e in processed_in_dim for dt in e.dimtags]
+            tool_dimtags = [dt for e in processed_higher_dims for dt in e.dimtags]
+
+            _, out_map = gmsh.model.occ.fragment(
+                object_dimtags,
+                tool_dimtags,
+                removeObject=True,
+                removeTool=True,
+            )
+            gmsh.model.occ.synchronize()
+
+            # Update tags using the mapping (order: objects first, then tools)
+            idx = 0
+            for entity in processed_in_dim:
+                new_dimtags = []
+                for _ in entity.dimtags:
+                    new_dimtags.extend(out_map[idx])
+                    idx += 1
+                entity.dimtags = list(set(new_dimtags))
+
+            for entity in processed_higher_dims:
+                new_dimtags = []
+                for _ in entity.dimtags:
+                    new_dimtags.extend(out_map[idx])
+                    idx += 1
+                entity.dimtags = list(set(new_dimtags))
+
+        processed_higher_dims.extend(processed_in_dim)
+
+    # --- Assign physical groups ---
+
+    # 1. Volume physical groups (dim=3 only; dim=2 handled in step 3)
+    for entity in entities:
+        if entity.dim == 3 and entity.dimtags:
+            tags = [t for d, t in entity.dimtags if d == 3]
+            if tags:
+                pg_tag = gmsh.model.addPhysicalGroup(3, tags, name=entity.name)
+                print(f"  Physical group '{entity.name}' (dim=3): pg={pg_tag}, tags={tags}")
+
+    # 2. Surface physical groups from volume boundaries
+    #    Build a map: surface_tag -> list of volume entity names that own it
+    vol_entities = [e for e in entities if e.dim == 3 and e.dimtags]
+    surf_to_names: dict[int, list[str]] = {}
+    for entity in vol_entities:
+        for dt in entity.dimtags:
+            boundary = gmsh.model.getBoundary(
+                [dt], combined=False, oriented=False, recursive=False
+            )
+            for bdim, btag in boundary:
+                if bdim == 2:
+                    btag = abs(btag) 
+                    surf_to_names.setdefault(btag, [])
+                    if entity.name not in surf_to_names[btag]:
+                        surf_to_names[btag].append(entity.name)
+
+    # 3. 2D entities keep their own name as the physical group
+    surf_entities = [e for e in entities if e.dim == 2 and e.dimtags]
+    assigned_surfs: set[int] = set()
+    for entity in surf_entities:
+        tags = [t for d, t in entity.dimtags if d == 2]
+        if tags:
+            pg_tag = gmsh.model.addPhysicalGroup(2, tags, name=entity.name)
+            print(f"  Physical group '{entity.name}' (dim=2): pg={pg_tag}, tags={tags}")
+            assigned_surfs.update(abs(t) for t in tags) 
+
+    # 4. Group remaining surfaces by their sorted owner name combination
+    name_combo_to_surfs: dict[str, list[int]] = {}
+    for stag, names in surf_to_names.items():
+        if stag in assigned_surfs:
+            continue
+        if len(names) == 1:
+            label = f"{names[0]}__None"
+        else:
+            label = "__".join(sorted(names))
+        name_combo_to_surfs.setdefault(label, []).append(stag)
+
+    for label, stags in name_combo_to_surfs.items():
+        pg_tag = gmsh.model.addPhysicalGroup(2, stags, name=label)
+        print(f"  Physical group '{label}' (dim=2): pg={pg_tag}, tags={stags}")
+
+    # Build pg_map by reading back from gmsh (authoritative source for .msh tags)
+    pg_map: dict[str, int] = {}
+    for dim, pg_tag in gmsh.model.getPhysicalGroups():
+        name = gmsh.model.getPhysicalName(dim, pg_tag)
+        if name:
+            pg_map[name] = pg_tag
+
+    return pg_map
+
+
+# ---------------------------------------------------------------------------
+# 3D mesh + Palace config helpers
+# ---------------------------------------------------------------------------
+
+def generate_3d_mesh(
+    entities: list[Entity],
+    mesh_sizes: dict[str, float],
+    output_file: str,
+    optimize: bool = True,
+) -> None:
+    """Set mesh sizes, generate and write a 3D mesh.
+
+    Args:
+        entities:    list of Entity objects with ``.name`` and ``.dimtags``.
+        mesh_sizes:  mapping from entity name → characteristic length.
+        output_file: path for the output .msh file.
+        optimize:    whether to run Netgen optimisation (disable for complex
+                     imported CAD to avoid segfaults in thin-volume meshes).
+    """
+
+
+    def _apply_point_sizes(*, use_entity_tags: bool = True) -> int:
+        applied = 0
+        for entity in entities:
+            lc = mesh_sizes.get(entity.name)
+            if lc is None:
+                continue
+            if use_entity_tags:
+                dimtags = entity.dimtags
+            else:
+                dimtags = []
+                for dim, pg_tag in gmsh.model.getPhysicalGroups(entity.dim):
+                    pg_name = gmsh.model.getPhysicalName(dim, pg_tag)
+                    if pg_name == entity.name:
+                        dimtags.extend((entity.dim, t) for t in gmsh.model.getEntitiesForPhysicalGroup(dim, pg_tag))
+
+            if not dimtags:
+                continue
+
+            try:
+                pts = gmsh.model.getBoundary(
+                    dimtags, combined=False, oriented=False, recursive=True
+                )
+            except Exception:
+                continue
+
+            point_dimtags = [(d, t) for d, t in pts if d == 0]
+            if point_dimtags:
+                gmsh.model.mesh.setSize(point_dimtags, lc)
+                applied += 1
+
+        return applied
+
+    _apply_point_sizes(use_entity_tags=True)
+
+
+    try:
+        gmsh.model.mesh.generate(3)
+    except Exception as exc:
+        msg = str(exc).lower()
+        if "invalid boundary mesh" not in msg and "overlapping facets" not in msg:
+            raise
+
+        print("  Meshing failed with overlapping facets; attempting OCC repair + retry...")
+        gmsh.model.mesh.clear()
+        try:
+            gmsh.model.occ.removeAllDuplicates()
+        except Exception:
+            pass
+        try:
+            gmsh.model.occ.healShapes()
+        except Exception:
+            pass
+        gmsh.model.occ.synchronize()
+
+        applied = _apply_point_sizes(use_entity_tags=False)
+        if applied == 0 and mesh_sizes:
+            # Last-resort sizing when entity tags are no longer valid after repair.
+            gmsh.model.mesh.setSize(gmsh.model.getEntities(0), min(mesh_sizes.values()))
+
+        gmsh.model.mesh.generate(3)
+
+    if optimize:
+            gmsh.model.mesh.optimize("Netgen") 
+    gmsh.option.setNumber("Mesh.MshFileVersion", 2.2)
+    gmsh.write(output_file)
+    print(f"Mesh saved to {output_file}")
+    print(f"  Nodes: {len(gmsh.model.mesh.getNodes()[0])}")
+    elems = gmsh.model.mesh.getElements()
+    print(f"  Elements: {sum(len(e) for e in elems[1])}")
+
+
+def refine_near_surfaces(
+    surface_dimtags: list[tuple[int, int]],
+    wavelength: float,
+    ppw_near: int = 20,
+    ppw_far: int = 5,
+    transition_distance: float | None = None,
+    set_as_background: bool = True,
+    local_refinements: dict[tuple[int, int], int] | None = None,
+    # e.g. {(2, port_tag): 40, (2, other_tag): 60}
+) -> int:
+    """Set up mesh refinement that clusters elements near conductor boundary curves.
+
+    Creates Distance + Threshold background mesh fields so that elements are
+    finest (``wavelength / ppw_near``) right at the boundary curves of the
+    given surfaces and grade quickly to the coarse size
+    (``wavelength / ppw_far``) over ``transition_distance``.
+
+    Additional per-surface local refinements can be injected via
+    ``local_refinements``. Each entry adds its own Distance+Threshold field
+    pair and all fields (global + local) are merged with a ``Min`` field so
+    the finest size always wins at every point.
+
+    When *set_as_background* is True (default), the final Min field is
+    immediately installed as the background mesh and meshing options are
+    configured. Set it to False to compose multiple fields with a ``Min``
+    field before calling :func:`set_mesh_field_as_background` yourself.
+
+    Args:
+        surface_dimtags:     List of ``(dim, tag)`` pairs for the surfaces whose
+                             boundary curves drive the global refinement (typically
+                             PEC and port surfaces).
+        wavelength:          Operating wavelength in model units.
+        ppw_near:            Points per wavelength on the conductor boundary curves.
+        ppw_far:             Points per wavelength far from conductors.
+        transition_distance: Distance over which the mesh size grades from fine
+                             to coarse. Defaults to ``wavelength / 4``.
+        set_as_background:   If True, install the final field as the background
+                             mesh and configure meshing options.
+        local_refinements:   Optional dict mapping ``(dim, tag)`` → ``ppw_local``
+                             for surfaces that need finer resolution than the
+                             global ``ppw_near``. Each gets its own
+                             Distance+Threshold pair with the same
+                             ``transition_distance`` and ``ppw_far``.
+
+    Returns:
+        The gmsh field ID of the final (Min or Threshold) field that was
+        installed as background (or would be, if set_as_background=False).
+    """
+    if transition_distance is None:
+        transition_distance = 0.25 * wavelength
+
+    lc_near = wavelength / ppw_near
+    lc_far  = wavelength / ppw_far
+
+    # ── helper: build one Distance+Threshold pair for a set of dimtags ──
+    def _make_threshold(
+        dimtags: list[tuple[int, int]],
+        size_min: float,
+        label: str = "",
+    ) -> int:
+        edge_set: set[int] = set()
+        for dt in dimtags:
+            for _, et in gmsh.model.getBoundary(
+                [dt], combined=False, oriented=False, recursive=False
+            ):
+                edge_set.add(abs(et))
+        edge_list = sorted(edge_set)
+        print(f"  {label}: {len(edge_list)} curves, SizeMin={size_min:.4f}")
+
+        dist = gmsh.model.mesh.field.add("Distance")
+        gmsh.model.mesh.field.setNumbers(dist, "CurvesList", edge_list)
+        gmsh.model.mesh.field.setNumber(dist, "Sampling", 200)
+
+        thresh = gmsh.model.mesh.field.add("Threshold")
+        gmsh.model.mesh.field.setNumber(thresh, "InField",  dist)
+        gmsh.model.mesh.field.setNumber(thresh, "SizeMin",  size_min)
+        gmsh.model.mesh.field.setNumber(thresh, "SizeMax",  lc_far)
+        gmsh.model.mesh.field.setNumber(thresh, "DistMin",  0.0)
+        gmsh.model.mesh.field.setNumber(thresh, "DistMax",  transition_distance)
+        return thresh
+
+    # ── 1. Global field ──────────────────────────────────────────────
+    print(f"  ppw_near={ppw_near}  ppw_far={ppw_far}")
+    print(f"  SizeMax={lc_far:.4f}  transition={transition_distance:.4f}")
+
+    field_ids = [
+        _make_threshold(surface_dimtags, lc_near, label="global")
+    ]
+
+    # ── 2. Local override fields ─────────────────────────────────────
+    # Each runs AFTER the global field so a finer ppw_local always wins
+    # once merged by the Min field below.
+    if local_refinements:
+        for dimtag, ppw_local in local_refinements.items():
+            lc_local = wavelength / ppw_local
+            field_ids.append(
+                _make_threshold([dimtag], lc_local, label=f"local {dimtag}")
+            )
+
+    # ── 3. Merge all fields with Min ─────────────────────────────────
+    # Min field takes the smallest lc at every point in space, so local
+    # overrides never conflict — they only ever refine, never coarsen.
+    if len(field_ids) > 1:
+        min_field = gmsh.model.mesh.field.add("Min")
+        gmsh.model.mesh.field.setNumbers(min_field, "FieldsList", field_ids)
+        final_field = min_field
+        print(f"  Merged {len(field_ids)} fields with Min → field {final_field}")
+    else:
+        final_field = field_ids[0]
+
+    if set_as_background:
+        set_mesh_field_as_background(final_field)
+
+    return final_field
+
+
+def set_mesh_field_as_background(field_id: int) -> None:
+    """Install a gmsh mesh field as the background mesh and configure options.
+
+    Disables point / curvature / boundary-extension sizing so that the
+    background field has full control over element sizes.
+    """
+    gmsh.model.mesh.field.setAsBackgroundMesh(field_id)
+    gmsh.option.setNumber("Mesh.MeshSizeExtendFromBoundary", 0)
+    gmsh.option.setNumber("Mesh.MeshSizeFromPoints", 0)
+    gmsh.option.setNumber("Mesh.MeshSizeFromCurvature", 0)
+    gmsh.option.setNumber("Mesh.Algorithm", 1)    # MeshAdapt
+    gmsh.option.setNumber("Mesh.Algorithm3D", 1)  # Delaunay
+
+
+def generate_2d_mesh(
+    name_to_surfs: dict[str, list[int]],
+    mesh_sizes: dict[str, float],
+    output_file: str,
+) -> None:
+    """Set mesh sizes, generate and write a 2D mesh.
+
+    Args:
+        name_to_surfs: mapping from area name → list of surface tags.
+        mesh_sizes:    mapping from area name → characteristic length.
+        output_file:   path for the output .msh file.
+    """
+    # Process regions from coarsest → finest so that fine mesh sizes on shared
+    # boundary points always override coarser ones.
+    sorted_names = sorted(
+        name_to_surfs.keys(),
+        key=lambda n: mesh_sizes.get(n, 0.0),
+        reverse=True,
+    )
+    for name in sorted_names:
+        stags = name_to_surfs[name]
+        lc = mesh_sizes.get(name)
+        if lc is None:
+            continue
+        for stag in stags:
+            pts = gmsh.model.getBoundary(
+                [(2, stag)], combined=False, oriented=False, recursive=True
+            )
+            gmsh.model.mesh.setSize([(d, t) for d, t in pts if d == 0], lc)
+
+    gmsh.model.mesh.generate(2)
+    gmsh.option.setNumber("Mesh.MshFileVersion", 2.2)
+    gmsh.write(output_file)
+    print(f"  Cross-section saved to {output_file}")
+    print(f"    Nodes: {len(gmsh.model.mesh.getNodes()[0])}")
+    elems = gmsh.model.mesh.getElements()
+    print(f"    Elements: {sum(len(e) for e in elems[1])}")
+
+
+def make_xz_rect(x0: float, x1: float, y: float, z0: float, z1: float) -> int:
+    """Create a rectangular surface in the XZ plane at given y coordinate."""
+    return make_rect(
+        (x0, y, z0), (x1, y, z0), (x1, y, z1), (x0, y, z1),
+    )
+
+
+def make_yz_rect(x: float, y0: float, y1: float, z0: float, z1: float) -> int:
+    """Create a rectangular surface in the YZ plane at given x coordinate."""
+    return make_rect(
+        (x, y0, z0), (x, y1, z0), (x, y1, z1), (x, y0, z1),
+    )
+
+
+def make_rect(
+    c0: tuple[float, float, float],
+    c1: tuple[float, float, float],
+    c2: tuple[float, float, float],
+    c3: tuple[float, float, float],
+) -> int:
+    """Create a planar rectangular surface from four corner points.
+
+    The corners must be given in order (either CW or CCW) so that
+    consecutive corners share an edge.
+
+    Args:
+        c0, c1, c2, c3: (x, y, z) coordinates of the four corners.
+
+    Returns:
+        The Gmsh OCC surface tag.
+    """
+    p1 = gmsh.model.occ.addPoint(*c0)
+    p2 = gmsh.model.occ.addPoint(*c1)
+    p3 = gmsh.model.occ.addPoint(*c2)
+    p4 = gmsh.model.occ.addPoint(*c3)
+    loop = gmsh.model.occ.addCurveLoop([
+        gmsh.model.occ.addLine(p1, p2),
+        gmsh.model.occ.addLine(p2, p3),
+        gmsh.model.occ.addLine(p3, p4),
+        gmsh.model.occ.addLine(p4, p1),
+    ])
+    return gmsh.model.occ.addPlaneSurface([loop])