Meshwell Pipeline

Meshwell Pipeline#

Meshwell provides a streamlined workflow for generating high-quality meshes from geometric definitions. The typical pipeline consists of three stages:

flowchart LR
    Self-contained inputs --> CAD["CAD\n(Geometry)"] --> MESH["Mesh\n(Initial)"] --> REMESH["Remesh\n(Adaptive)"]

Feature highlights#

A quick map of everything meshwell can do; each item links to a dedicated page below.

Geometry (CAD)

1D/2D/3D entities — PolyLine, PolySurface, and PolyPrism built straight from Shapely.
Arbitrary OCC shapes — drop in any OpenCASCADE construction when polygons aren’t enough.
Arc identification — identify_arcs=True recovers true circular boundaries from point-sampled polygons.
Multi-entity models — combine OCC entities, polysurfaces, and prisms in one model.
mesh_order ownership — painter’s-algorithm resolution of overlapping entities (lower order wins); see Usage Approaches.

Meshing

2D & 3D meshing — planes, cross-sections, surfaces of 3D objects, or full volumes.
Resolution control — global sizing plus per-entity ThresholdField distance-based refinement.
Direct size specification — prescribe the mesh-size field explicitly over space.
Structured meshing — wedge (prism) elements through a layer’s thickness, conformal with the surrounding unstructured tets.
Mesh quality analysis — MeshQualityAnalyzer reports element quality before you simulate.

Remeshing

Adaptive remeshing — drive mesh size from a computed field via RemeshingStrategy, with GMSH and MMG backends.

Integrations

GDS import — load .gds layers as Shapely polygons ready to mesh.
gdswell — turn a gdswell layout Stackup into a 3D mesh and 2D cross-sections.

1. Polygons (and more) –> CAD#

The first step is to define your geometry using built-in meshwell entity classes or arbitrary OCC shapes. Meshwell entities are built from polygons (using Shapely) and can be:

PolyLine: 1D lines defined by LineStrings
PolySurface: 2D surfaces defined by polygons
PolyPrism: 3D volumes created by extruding polygons along the z-axis — with z-dependent buffers, the footprint can grow or shrink with height to make tapered or slanted sidewalls

Beyond these, geometry can also come from arbitrary OCC entities. Assemblies of entities can form multi-entity models.

Key concepts:

physical_name: A label for the entity, used for the GMSH physical group
mesh_order: Controls how overlapping entities of the same dimension interact (lower order takes precedence)

The geometry is processed by OCC via cad_occ() and written to a .xao file using write_xao().

import shapely

from meshwell.cad_occ import cad_occ
from meshwell.occ_xao_writer import write_xao
from meshwell.polysurface import PolySurface

polygon = shapely.Polygon([[-5, -5], [5, -5], [5, 5], [-5, 5]])
entity = PolySurface(polygons=polygon, physical_name="my_surface", mesh_order=1)

write_xao(cad_occ([entity]), "geometry.xao")

For more details on the CAD options, see:

OCC entities, which can be arbitrarily complex
Polysurfaces
Prisms
Arc identification
Models

2. CAD –> mesh#

The mesh() function takes the geometry from the CAD stage and generates an initial mesh. You can control:

default_characteristic_length: The base mesh size
resolution_specs: Fine-grained control over mesh size per entity or globally
dim: Dimension of the mesh – 2D (planes, or surfaces of 3D objects) or full 3D

from meshwell.mesh import mesh

initial_mesh = mesh(
    dim=2,
    input_file="geometry.xao",
    output_file="mesh.msh",
    default_characteristic_length=1.0,
)

Meshwell offers three ways to drive this: the functional helpers shown above, an object-oriented Model that shares a single GMSH session between CAD and meshing, and the generate_mesh orchestrator that runs the whole pipeline in one call.

A few meshing features worth calling out:

Resolution fields — combine a global size with per-entity refinement such as ThresholdField (mesh size grows with distance from an entity). See Resolution Basics and Resolution Advanced.
Direct size specification — prescribe the size field explicitly over space when you already know where you want resolution: Direct Size Specification.
Structured meshing — fill a layer with wedge (triangular-prism) elements through its thickness while staying conformal with the surrounding unstructured tetrahedra: Structured meshing.
Quality analysis — inspect element quality with the MeshQualityAnalyzer before using the mesh downstream: Mesh Quality.

3. mesh –> (re)mesh#

DirectSizeSpecification allows fine grained control of mesh sizing over space. Often, however, we want this process to be guided by some data field we have computed over an existing mesh. The remeshing utilities are here for that (in case your solver does not have a native way to do this, which is preferred!).

Remeshing is controlled by RemeshingStrategy objects that define how mesh sizes should change. Generic strategies have the following attributes:

Attribute	Description
`refinement_data`	(N, 4) array of points `(x, y, z, data)` where data is a solution field, error estimator, etc.
`func`	Optional callable to transform the data (e.g., compute gradients, differences)
`threshold_func`	Maps transformed data to new mesh sizes
`min_size`	Minimum allowed mesh size
`max_size`	Maximum allowed mesh size

Note that while refinement_data is often specified at the existing mesh nodes, it can actually be any set of points in space.

For example, here is a simple pre-implemented strategy that refines the mesh by some factor where data exceeds a threshold:

from meshwell.remesh import BinaryScalingStrategy

strategy = BinaryScalingStrategy(
    refinement_data=data,  # (N, 4) array
    threshold=0.5,         # Consider nodes where data > 0.5
    factor=0.2,            # Make new mesh size 20% of original where data > threshold
    min_size=0.05,
    max_size=2.0,
)

Meshwell supports two remeshing backends:

GMSH (remesh_gmsh): Uses GMSH for remeshing (by transforming the strategy into the appropriate DirectSizeSpecification), can reuse the original CAD file
MMG (remesh_mmg): Uses MMG library, often produces higher quality meshes

See the detailed examples:

Integrations#

Meshwell is the meshing backend for higher-level layout tools:

gdswell — convert a gdswell layout Stackup (the 3D extension of a 2D layout) into a watertight 3D mesh, and slice 2D cross-sections at a cell’s ports. meshwell’s mesh_order reproduces gdswell’s painter’s-order cutting for free.