Python Geom Module - Mesh Reader Guide¶

This document describes how to use the DNDSR Python Geom module for reading and manipulating computational meshes.

Overview¶

The DNDSR.Geom module provides Python bindings to the C++ geometry library, enabling:

Reading CGNS mesh files
Mesh partitioning and distribution
Order elevation (O1 → O2)
Mesh bisection for h-refinement
Boundary mesh extraction
VTK output generation
Wall distance computation
CUDA device offloading

Setup¶

Import the module and initialize MPI:

from DNDSR import Geom, DNDS

MPI is initialized automatically when DNDSR.DNDS is imported (via MPI.Init_thread). If you need to control MPI initialization yourself (e.g., to set the thread level), import and initialize mpi4py before importing DNDSR.DNDS.

Core Classes¶

UnstructuredMesh¶

The main mesh container class.

from DNDSR import Geom, DNDS

mpi = DNDS.MPIInfo()
mpi.setWorld()
mesh = Geom.UnstructuredMesh(mpi, dim=3)

Key Methods:

Method	Description
`NumCell()`	Number of local cells
`NumCellGlobal()`	Global cell count (collective)
`NumNode()`	Number of local nodes
`NumNodeGlobal()`	Global node count (collective)
`NumFace()`	Number of local faces
`NumFaceGlobal()`	Global face count (collective)
`NumBnd()`	Number of local boundary faces
`NumBndGlobal()`	Global boundary face count (collective)
`NumCellGhost()`	Number of ghost cells
`NumNodeGhost()`	Number of ghost nodes
`NumFaceGhost()`	Number of ghost faces
`NumBndGhost()`	Number of ghost boundary faces
`getDim()`	Mesh dimension (2 or 3)
`getMPI()`	Return the `MPIInfo` object
`RecoverNode2CellAndNode2Bnd()`	Build node connectivity
`RecoverCell2CellAndBnd2Cell()`	Build cell/boundary connectivity
`BuildGhostPrimary()`	Build ghost cell communication
`AdjGlobal2LocalPrimary()`	Convert global indices to local
`AdjLocal2GlobalPrimary()`	Convert local indices to global
`AdjGlobal2LocalPrimaryForBnd()`	Global→local for boundary mesh
`AdjLocal2GlobalPrimaryForBnd()`	Local→global for boundary mesh
`AdjGlobal2LocalN2CB()`	Global→local for node-to-cell/bnd
`AdjLocal2GlobalN2CB()`	Local→global for node-to-cell/bnd
`BuildGhostN2CB()`	Build ghost node-to-cell/bnd comm
`InterpolateFace()`	Build face interpolation data
`AssertOnFaces()`	Validate face data
`BuildVTKConnectivity()`	Prepare for VTK output
`RecreatePeriodicNodes()`	Reconstruct periodic node mapping
`ConstructBndMesh(bndMesh)`	Extract (dim-1) boundary mesh
`ReorderLocalCells(nParts, nPartsInner)`	Reorder cells for cache locality
`BuildO2FromO1Elevation(meshO1)`	Elevate O1→O2 in-place
`BuildBisectO1FormO2(meshO2)`	Bisect O2→O1 sub-mesh in-place
`BuildNodeWallDist(fBndIsWall, options)`	Compute wall distance field
`to_device(backend)`	Offload arrays to device (`"CUDA"`)
`to_host()`	Pull arrays back to host
`getArrayBytes()`	Total memory used by arrays

Key Read-Only Members:

Member	Type	Description
`coords`	coordinate pair	Node coordinates
`cell2node`	adjacency pair	Cell-to-node connectivity
`bnd2node`	adjacency pair	Boundary-to-node connectivity
`bnd2cell`	adjacency pair	Boundary-to-cell connectivity
`cell2cell`	adjacency pair	Cell-to-cell connectivity
`cellElemInfo`	ElemInfo pair	Per-cell element type and zone
`bndElemInfo`	ElemInfo pair	Per-bnd element type and zone
`cell2face`	adjacency pair	Cell-to-face (after `InterpolateFace`)
`face2cell`	adjacency pair	Face-to-cell (after `InterpolateFace`)
`face2node`	adjacency pair	Face-to-node (after `InterpolateFace`)
`faceElemInfo`	ElemInfo pair	Per-face element type and zone

Note: GetCellElement(), GetBndElement(), IsO1(), and IsO2() are C++ methods that are not exposed in the Python bindings. To query element types from Python, use mesh.cellElemInfo[iCell][0].getElemType() which returns a Geom.Elem.ElemType enum value.

ElemInfo¶

Per-element metadata, accessible via mesh.cellElemInfo and mesh.bndElemInfo.

info = mesh.cellElemInfo[iCell][0]
elem_type = info.getElemType()   # returns Geom.Elem.ElemType enum
zone = info.zone                 # zone index

UnstructuredMeshSerialRW¶

Serial mesh reader/writer for CGNS files.

reader = Geom.UnstructuredMeshSerialRW(mesh, 0)
name2ID = reader.ReadFromCGNSSerial("mesh.cgns")

Key Methods:

Method	Description
`ReadFromCGNSSerial(path)`	Read CGNS file; returns `AutoAppendName2ID`
`Deduplicate1to1Periodic(tol)`	Merge periodic 1-to-1 connections
`BuildCell2Cell()`	Build serial cell-to-cell adjacency
`MeshPartitionCell2Cell(options)`	Partition with Metis
`PartitionReorderToMeshCell2Cell()`	Reorder to match partition
`BuildSerialOut()`	Prepare serial output data

Key Members:

Member	Access	Description
`mesh`	read/write	The `UnstructuredMesh` object
`dataIsSerialOut`	read-only	Whether serial output is built
`dataIsSerialIn`	read-only	Whether serial input is ready

AutoAppendName2ID¶

Returned by ReadFromCGNSSerial. Maps boundary/zone names to integer IDs.

name2ID = reader.ReadFromCGNSSerial(meshFile)
n2id = name2ID.n2id_map   # dict-like: name → ID

ElemType Enum¶

Available as Geom.Elem.ElemType:

Value	Description
`UnknownElem`	Unknown / uninitialized
`Line2`, `Line3`	1D line elements
`Tri3`, `Tri6`	Triangle elements
`Quad4`, `Quad9`	Quadrilateral elements
`Tet4`, `Tet10`	Tetrahedron elements
`Hex8`, `Hex27`	Hexahedron elements
`Prism6`, `Prism18`	Prism elements
`Pyramid5`, `Pyramid14`	Pyramid elements

Note: The C++ Elem::Element struct (with methods GetDim(), GetOrder(), GetNumNodes(), IsO1(), GetParamSpace(), etc.) is not exposed in the Python bindings. Only the ElemType enum is available.

WallDistOptions¶

Nested class UnstructuredMesh.WallDistOptions for configuring wall distance computation:

opts = Geom.UnstructuredMesh.WallDistOptions()
opts.method = 1
opts.subdivide_quad = 5
opts.verbose = 10
opts.wallDistExecution = 4
opts.minWallDist = 1e-10
mesh.BuildNodeWallDist(lambda bnd_id: bnd_id == wall_id, opts)

Mesh Reading Workflow¶

Using the High-Level API (Recommended)¶

The recommended API uses read_mesh + prepare_mesh from DNDSR.Geom.utils:

from DNDSR.Geom.utils import read_mesh, prepare_mesh
from DNDSR import DNDS

mpi = DNDS.MPIInfo()
mpi.setWorld()

result = read_mesh(
    "data/mesh/UniformSquare_10.cgns",
    mpi=mpi,
    dim=2,
)
prepare_mesh(result.mesh, result.reader)
mesh = result.mesh

read_mesh returns a MeshReadResult dataclass with mesh, reader, and name_to_id fields. prepare_mesh mutates the mesh in-place (cell reorder, face interpolation, ghost N2CB, serial output, periodic nodes, VTK connectivity).

The legacy create_mesh_from_CGNS function is still available as a backward-compatible wrapper:

from DNDSR.Geom.utils import create_mesh_from_CGNS
from DNDSR import DNDS

mpi = DNDS.MPIInfo()
mpi.setWorld()

mesh, reader, name2ID = create_mesh_from_CGNS(
    meshFile="data/mesh/UniformSquare_10.cgns",
    mpi=mpi,
    dim=2,
)

read_mesh parameter list:

Parameter	Type	Default	Description
`mesh_file`	`str`	required	Path to CGNS or H5 mesh file
`mpi`	`MPIInfo`	required	MPI context
`dim`	`int`	`2`	Mesh dimension (2 or 3)
`periodic_geometry`	`dict`	see below	Periodic transform parameters
`periodic_tolerance`	`float`	`1e-9`	Tolerance for periodic dedup
`read_mode`	`str`	auto	`"cgns"` or `"h5"` (auto-detected from extension)
`partition_options`	`dict`	Metis defaults	Metis/ParMetis partitioning options
`elevation`	`str`	`""`	`""` or `"O2"` for quadratic elevation
`bisect`	`int`	`0`	Number of bisection levels (0-4)
`serializer_factory`	`SerializerFactory`	H5 factory	For H5 read modes

prepare_mesh parameter list:

Parameter	Type	Default	Description
`mesh`	`UnstructuredMesh`	required	Mesh to prepare (mutated in-place)
`reader`	`UnstructuredMeshSerialRW`	required	Reader from `read_mesh`
`reorder_parts`	`int`	`1`	Cell reordering partitions
`reorder_inner_parts`	`int`	`1`	Second-level reordering partitions
`build_serial_out`	`bool`	`True`	Build serial output data
`wall_dist_predicate`	`callable`	`None`	`f(bnd_id) -> bool` for wall distance
`wall_dist_options`	`WallDistOptions`	`None`	Wall distance settings
`coord_scale`	`float`	`None`	Scale coordinates
`coord_rot_z_deg`	`float`	`None`	Rotate coordinates around Z axis
`rectify_near_plane`	`str`	`None`	Rectify near-plane coords (`"x"`, `"y"`, `"z"`)
`rectify_threshold`	`float`	`1e-10`	Threshold for rectification

Periodic geometry default:

periodic_geometry={
    "translation1": [1, 0, 0],
    "rotationCenter1": [0, 0, 0],
    "eulerAngles1": [0, 0, 0],
    "translation2": [0, 1, 0],
    "rotationCenter2": [0, 0, 0],
    "eulerAngles2": [0, 0, 0],
    "translation3": [0, 0, 1],
    "rotationCenter3": [0, 0, 0],
    "eulerAngles3": [0, 0, 0],
}

These are passed directly to mesh.SetPeriodicGeometry(), which accepts up to three periodic direction triples (translation, rotationCenter, eulerAngle).

Read Mode Options¶

read_mesh auto-detects the mode from the file extension (.cgns -> CGNS serial read, .h5 -> H5 distributed read). Override with the read_mode parameter:

Mode	Extension	Description
`"cgns"`	`.cgns`	Read CGNS on rank 0, partition with Metis, distribute. Returns `name_to_id`.
`"h5"`	`.h5`	Read H5 with even-split + ParMetis repartition. Works with any MPI rank count.

Warning: In H5 mode, name_to_id (boundary name mapping) is not read from the serializer and will be None. Only CGNS mode returns a valid AutoAppendName2ID.

Common Usage Patterns¶

from DNDSR.Geom.utils import read_mesh, prepare_mesh

# Basic read
result = read_mesh("data/mesh/UniformSquare_10.cgns", mpi=mpi, dim=2)
prepare_mesh(result.mesh, result.reader)

# With order elevation (O1 → O2)
result = read_mesh(
    "data/mesh/UniformSquare_10.cgns", mpi=mpi, dim=2,
    elevation="O2",
)
prepare_mesh(result.mesh, result.reader)

# With bisection (h-refinement)
result = read_mesh(
    "data/mesh/UniformSquare_10.cgns", mpi=mpi, dim=2,
    bisect=1,
)
prepare_mesh(result.mesh, result.reader)

# Combined elevation + bisection
result = read_mesh(
    "data/mesh/UniformSquare_10.cgns", mpi=mpi, dim=2,
    elevation="O2", bisect=2,
)
prepare_mesh(result.mesh, result.reader)

# With cell reordering for cache locality
result = read_mesh("data/mesh/UniformSquare_10.cgns", mpi=mpi, dim=2)
prepare_mesh(result.mesh, result.reader, reorder_parts=4, reorder_inner_parts=4)

# H5 distributed read with auto-repartitioning
result = read_mesh("mesh.dnds.h5", mpi=mpi, dim=3)
prepare_mesh(result.mesh, result.reader)

Legacy API (backward-compatible)¶

from DNDSR.Geom.utils import create_mesh_from_CGNS

# create_mesh_from_CGNS wraps read_mesh + prepare_mesh
mesh, reader, name2ID = create_mesh_from_CGNS(
    meshFile="data/mesh/UniformSquare_10.cgns",
    mpi=mpi, dim=2,
    meshElevation="O2",
    meshDirectBisect=1,
    readMeshMode="Serial",
)

What the Pipeline Does¶

read_mesh + prepare_mesh run the complete mesh pipeline so you do not need to call these steps manually. For reference, the CGNS-mode pipeline is:

read_mesh (CGNS mode):

reader.ReadFromCGNSSerial(meshFile) — read CGNS on rank 0
reader.Deduplicate1to1Periodic(tolerance) — merge periodic connections
reader.BuildCell2Cell() — build serial cell adjacency
reader.MeshPartitionCell2Cell({...}) — partition with Metis
reader.PartitionReorderToMeshCell2Cell() — reorder to match partition
Ghost + connectivity build (RecoverN2C, RecoverC2C, BuildGhostPrimary, G2L)
(If elevation == "O2") Build O2 mesh and swap
(If bisect > 0) Elevate→bisect loop

prepare_mesh:

mesh.ReorderLocalCells(nParts, nPartsInner) — cell reordering
mesh.InterpolateFace() — build face data
mesh.AssertOnFaces() — validate faces
AdjLocal2GlobalN2CB() / BuildGhostN2CB() / AdjGlobal2LocalN2CB()
(If build_serial_out) Build serial output
mesh.RecreatePeriodicNodes() — reconstruct periodic mapping
mesh.BuildVTKConnectivity() — prepare VTK output
(If wall_dist_predicate) Compute wall distances
(If coord transforms specified) Apply scale/rotation/rectification

Low-Level Serial Read (Manual Pipeline)¶

If you need fine-grained control, you can run the pipeline manually:

from DNDSR import Geom, DNDS
import os

mpi = DNDS.MPIInfo()
mpi.setWorld()

mesh = Geom.UnstructuredMesh(mpi, dim=2)
reader = Geom.UnstructuredMeshSerialRW(mesh, 0)

meshFile = "path/to/mesh.cgns"
assert os.path.isfile(meshFile)
name2ID = reader.ReadFromCGNSSerial(meshFile)

reader.Deduplicate1to1Periodic(1e-9)
reader.BuildCell2Cell()
reader.MeshPartitionCell2Cell({
    "metisType": "KWAY",
    "metisUfactor": 5,
    "metisSeed": 0,
    "metisNcuts": 3,
})
reader.PartitionReorderToMeshCell2Cell()

mesh.RecoverNode2CellAndNode2Bnd()
mesh.RecoverCell2CellAndBnd2Cell()
mesh.BuildGhostPrimary()
mesh.AdjGlobal2LocalPrimary()
mesh.AdjGlobal2LocalN2CB()

Order Elevation (O1 → O2)¶

Elevation converts linear elements to quadratic elements:

Quad4 → Quad9
Tri3 → Tri6
Hex8 → Hex27
Tet4 → Tet10
Prism6 → Prism18
Pyramid5 → Pyramid14

meshO2 = Geom.UnstructuredMesh(mpi, dim)
meshO2.BuildO2FromO1Elevation(meshO1)

meshO2.RecoverNode2CellAndNode2Bnd()
meshO2.RecoverCell2CellAndBnd2Cell()
meshO2.BuildGhostPrimary()
meshO2.AdjGlobal2LocalPrimary()
meshO2.AdjGlobal2LocalN2CB()

Node count increase for UniformSquare_10 (10×10 Quad4):

O1: 121 nodes (11×11 grid)
O2: 441 nodes (+320 new nodes)
- 220 edge midpoints (110 horizontal + 110 vertical)
- 100 cell centers

Mesh Bisection (h-refinement)¶

Bisection splits O2 elements into O1 sub-elements:

O2 Element	Sub-elements	O1 Type
Quad9	4	Quad4
Tri6	4	Tri3
Hex27	8	Hex8
Tet10	8	Tet4
Prism18	8	Prism6
Pyramid14	12	Pyramid5

meshO2 = Geom.UnstructuredMesh(mpi, dim)
meshO2.BuildO2FromO1Elevation(meshO1)

meshO2.RecoverNode2CellAndNode2Bnd()
meshO2.RecoverCell2CellAndBnd2Cell()
meshO2.BuildGhostPrimary()

meshO1B = Geom.UnstructuredMesh(mpi, dim)
meshO1B.BuildBisectO1FormO2(meshO2)

meshO1B.RecoverNode2CellAndNode2Bnd()
meshO1B.RecoverCell2CellAndBnd2Cell()
meshO1B.BuildGhostPrimary()
meshO1B.AdjGlobal2LocalPrimary()
meshO1B.AdjGlobal2LocalN2CB()

Cell count progression for UniformSquare_10:

Original: 100 Quad4 cells
Elevated: 100 Quad9 cells
Bisected: 400 Quad4 cells (100 × 4)

Periodic Meshes¶

For meshes with periodic boundaries:

mesh, reader, name2ID = create_mesh_from_CGNS(
    meshFile="IV10_10.cgns",
    mpi=mpi,
    dim=2,
    periodic_geometry={
        "translation1": [10, 0, 0],
        "rotationCenter1": [0, 0, 0],
        "eulerAngles1": [0, 0, 0],
    },
    periodic_tolerance=1e-9,
)

SetPeriodicGeometry accepts up to three periodic direction triples: translation1/rotationCenter1/eulerAngles1 through translation3/rotationCenter3/eulerAngles3.

Boundary Mesh Extraction¶

from DNDSR.Geom.utils import build_bnd_mesh

bnd = build_bnd_mesh(mesh)
meshBnd = bnd.mesh_bnd
readerBnd = bnd.reader_bnd

# Legacy wrapper (backward-compatible):
# from DNDSR.Geom.utils import create_bnd_mesh
# meshBnd, readerBnd = create_bnd_mesh(mesh)

# Access boundary information
n2id = name2ID.n2id_map
id2name = {v: k for k, v in n2id.items()}

for iBnd in range(mesh.NumBnd()):
    elem_type = mesh.bndElemInfo[iBnd][0].getElemType()
    zone = mesh.bndElemInfo[iBnd][0].zone
    print(f"Boundary {iBnd}: type={elem_type}, zone={zone}")

Wall Distance Computation¶

# Identify wall boundaries by name
n2id = name2ID.n2id_map
id2name = {v: k for k, v in n2id.items()}

def id_is_wall(bnd_id):
    if bnd_id in id2name:
        name = id2name[bnd_id].upper()
        return "WALL" in name
    return False

opts = Geom.UnstructuredMesh.WallDistOptions()
opts.method = 1
opts.subdivide_quad = 5
opts.verbose = 10
opts.wallDistExecution = 4
mesh.BuildNodeWallDist(id_is_wall, opts)

CUDA Device Offloading¶

mesh.coords.to_device("CUDA")
mesh.to_device("CUDA")

# ... GPU computation ...

mesh.to_host()

VTK Output¶

VTK connectivity is built automatically by create_mesh_from_CGNS. For manual control:

mesh.BuildVTKConnectivity()

# For serial output
mesh.AdjLocal2GlobalPrimary()
reader.BuildSerialOut()
mesh.AdjGlobal2LocalPrimary()

Querying Mesh State¶

Element Information¶

# Get element type for a cell
elem_type = mesh.cellElemInfo[iCell][0].getElemType()  # Geom.Elem.ElemType enum

# Compare with known types
if elem_type == Geom.Elem.Quad4:
    print("Linear quad")
elif elem_type == Geom.Elem.Quad9:
    print("Quadratic quad")

# Get zone index
zone = mesh.cellElemInfo[iCell][0].zone

Mesh Properties¶

# Global counts
nCellGlobal = mesh.NumCellGlobal()
nNodeGlobal = mesh.NumNodeGlobal()

# Local counts
nCellLocal = mesh.NumCell()
nNodeLocal = mesh.NumNode()
nGhost = mesh.NumCellGhost()

Note: The C++ methods IsO1() and IsO2(), as well as the MeshElevationState enum (Elevation_Untouched, Elevation_O1O2), are not exposed in the Python bindings. To check whether a mesh uses O2 elements, inspect the element types via cellElemInfo[i][0].getElemType().

Note: The MeshAdjState enum is exposed in Python as Geom.MeshAdjState with values Unknown, PointToGlobal, and PointToLocal. Each adjacency member (e.g. mesh.cell2node) is an AdjPairTracked object whose idx member exposes read-only state query methods: state(), isLocal(), isGlobal(), isBuilt(), isWired(). The group state variables (e.g. adjPrimaryState) are still accessible as integers for backward compatibility.

References¶

See test/Geom/test_basic_geom.py for Python usage examples
See python/DNDSR/Geom/utils.py for the Python API implementation
See src/Geom/Mesh/Mesh_bind.hpp for the complete list of Python-exposed methods
See src/Geom/Elements_bind.hpp for the ElemType enum bindings
See docs/architecture/Paradigm.md for overall design philosophy