0
# PyGMSH
1

2
PyGMSH is a comprehensive Python frontend for Gmsh, providing intuitive abstractions for creating complex geometric models and generating high-quality meshes programmatically. It enables developers and researchers to create sophisticated 3D finite element meshes through two powerful geometry engines: the built-in geo module for traditional CAD-style operations and the occ module for OpenCASCADE-based modeling with advanced geometric operations.
3

4
## Package Information
5

6
- **Package Name**: pygmsh
7
- **Language**: Python
8
- **Installation**: `pip install pygmsh`
9
- **Dependencies**: gmsh, meshio, numpy
10
- **License**: GPL-3.0-or-later
11

12
## Core Imports
13

14
```python
15
import pygmsh
16
```
17

18
For built-in geometry kernel:
19

20
```python
21
import pygmsh.geo
22
```
23

24
For OpenCASCADE geometry kernel:
25

26
```python
27
import pygmsh.occ
28
```
29

30
For utility functions:
31

32
```python
33
from pygmsh import write, optimize, rotation_matrix, orient_lines
34
```
35

36
## Basic Usage
37

38
### Built-in Geometry Kernel
39

40
```python
41
import pygmsh
42

43
# Create geometry using built-in kernel
44
with pygmsh.geo.Geometry() as geom:
45
    # Add basic shapes
46
    circle = geom.add_circle([0.0, 0.0, 0.0], 1.0, mesh_size=0.1)
47
    rectangle = geom.add_rectangle(
48
        xmin=-2.0, xmax=2.0, ymin=-1.0, ymax=1.0, z=0.0, mesh_size=0.2
49
    )
50
    
51
    # Generate mesh
52
    mesh = geom.generate_mesh(dim=2)
53

54
# Write mesh to file
55
pygmsh.write("output.msh")
56
```
57

58
### OpenCASCADE Geometry Kernel
59

60
```python
61
import pygmsh
62

63
# Create geometry using OpenCASCADE kernel  
64
with pygmsh.occ.Geometry() as geom:
65
    # Add primitive shapes
66
    ball = geom.add_ball([0, 0, 0], 1.0)
67
    box = geom.add_box([1, 1, 1], [2, 2, 2])
68
    
69
    # Perform boolean operations
70
    result = geom.boolean_union([ball, box])
71
    
72
    # Generate mesh
73
    mesh = geom.generate_mesh(dim=3)
74

75
# Optimize mesh quality
76
optimized_mesh = pygmsh.optimize(mesh)
77
```
78

79
## Architecture
80

81
PyGMSH provides a dual-kernel architecture enabling flexible geometric modeling approaches:
82

83
### Geometry Kernels
84

85
- **geo kernel** (`pygmsh.geo`): Built-in Gmsh geometry kernel for traditional CAD-style modeling with parametric shapes, extrusions, and revolutions
86
- **occ kernel** (`pygmsh.occ`): OpenCASCADE-based kernel enabling advanced solid modeling with boolean operations, BREP import/export, and complex surface operations
87
- **common base** (`pygmsh.common`): Shared functionality including mesh generation, transformations, physical groups, and size field management
88

89
### Design Patterns
90

91
- **Context managers**: All geometry operations use `with` statements for proper resource management
92
- **Method chaining**: Geometry entities can be transformed and combined using fluent interfaces  
93
- **Mesh integration**: Seamless integration with meshio for data processing and format conversion
94
- **Size control**: Comprehensive mesh sizing through point-based sizing, size fields, and callback functions
95

96
This architecture supports maximum reusability across scientific computing applications, finite element analysis, computational fluid dynamics, and any domain requiring mesh generation.
97

98
## Capabilities
99

100
### Built-in Geometry Operations
101

102
Traditional CAD-style geometric modeling with parametric shapes, extrusions, revolutions, and structured mesh generation. Ideal for engineering applications requiring precise control over mesh topology.
103

104
```python { .api }
105
class Geometry(CommonGeometry):
106
    def add_circle(self, x0, radius, mesh_size=None, R=None, compound=False, 
107
                   num_sections=3, holes=None, make_surface=True): ...
108
    def add_rectangle(self, xmin, xmax, ymin, ymax, z, mesh_size=None, 
109
                      holes=None, make_surface=True): ...
110
    def add_ellipsoid(self, x0, radii, mesh_size=None, with_volume=True, holes=None): ...
111
    def add_ball(self, x0, radius, **kwargs): ...
112
    def add_box(self, x0, x1, y0, y1, z0, z1, mesh_size=None, with_volume=True, holes=None): ...
113
    def add_torus(self, irad, orad, mesh_size=None, R=np.eye(3), x0=np.array([0,0,0]), 
114
                  variant="extrude_lines"): ...
115
    def add_pipe(self, outer_radius, inner_radius, length, R=np.eye(3), x0=np.array([0,0,0]), 
116
                 mesh_size=None, variant="rectangle_rotation"): ...
117
    def revolve(self, *args, **kwargs): ...  # angle < π constraint
118
    def twist(self, input_entity, translation_axis, rotation_axis, point_on_axis, 
119
              angle, num_layers=None, heights=None, recombine=False): ...
120
    def in_surface(self, input_entity, surface): ...
121
    def in_volume(self, input_entity, volume): ...
122
```
123

124
[Built-in Geometry Operations](./geo-geometry.md)
125

126
### OpenCASCADE Solid Modeling
127

128
Advanced solid modeling capabilities with boolean operations, primitive shapes, BREP operations, and CAD file import/export. Provides the full power of OpenCASCADE for complex geometric operations.
129

130
```python { .api }
131
class Geometry(CommonGeometry):
132
    # Properties
133
    characteristic_length_min: float
134
    characteristic_length_max: float
135
    
136
    # Shape creation
137
    def add_ball(self, *args, mesh_size=None, **kwargs): ...
138
    def add_box(self, *args, mesh_size=None, **kwargs): ...
139
    def add_cone(self, *args, mesh_size=None, **kwargs): ...
140
    def add_cylinder(self, *args, mesh_size=None, **kwargs): ...
141
    def add_disk(self, *args, mesh_size=None, **kwargs): ...
142
    def add_ellipsoid(self, center, radii, mesh_size=None): ...
143
    def add_rectangle(self, *args, mesh_size=None, **kwargs): ...
144
    def add_torus(self, *args, mesh_size=None, **kwargs): ...
145
    def add_wedge(self, *args, mesh_size=None, **kwargs): ...
146
    
147
    # Boolean operations
148
    def boolean_intersection(self, entities, delete_first=True, delete_other=True): ...
149
    def boolean_union(self, entities, delete_first=True, delete_other=True): ...
150
    def boolean_difference(self, d0, d1, delete_first=True, delete_other=True): ...
151
    def boolean_fragments(self, d0, d1, delete_first=True, delete_other=True): ...
152
    
153
    # Import/export and transformations
154
    def import_shapes(self, filename): ...
155
    def revolve(self, *args, **kwargs): ...  # angle < 2π constraint
156
    def force_outward_normals(self, tag): ...
157
```
158

159
[OpenCASCADE Solid Modeling](./occ-geometry.md)
160

161
### Helper Functions and Utilities
162

163
Essential utility functions for mesh processing, geometric transformations, file I/O, and mesh optimization that complement the core geometry operations.
164

165
```python { .api }
166
# File I/O operations
167
def write(filename: str): ...
168

169
# Geometric transformations
170
def rotation_matrix(u, theta): ...
171
def orient_lines(lines): ...
172

173
# Mesh optimization
174
def optimize(mesh, method="", verbose=False): ...
175
def extract_to_meshio(): ...
176

177
# Command line interface
178
def optimize_cli(argv=None): ...
179
```
180

181
[Helper Functions and Utilities](./helpers-and-utilities.md)
182

183
### Mesh Control and Size Fields
184

185
Advanced mesh generation control with size fields, boundary layers, transfinite meshing, and callback-based sizing for precise mesh quality management.
186

187
```python { .api }
188
# Size field management
189
def set_mesh_size_callback(fun, ignore_other_mesh_sizes=True): ...
190
def add_boundary_layer(*args, **kwargs): ...
191
def set_background_mesh(fields, operator): ...
192

193
# Transfinite meshing
194
def set_transfinite_curve(curve, num_nodes, mesh_type, coeff): ...
195
def set_transfinite_surface(surface, arrangement, corner_pts): ...
196
def set_transfinite_volume(volume, corner_pts): ...
197
def set_recombined_surfaces(surfaces): ...
198
```
199

200
[Mesh Control and Size Fields](./mesh-control.md)
201

202
## Common Base Types
203

204
```python { .api }
205
class CommonGeometry:
206
    """Base class providing fundamental geometry operations for both kernels."""
207
    
208
    # Basic shape creation
209
    def add_point(self, x, mesh_size=None): ...
210
    def add_line(self, p0, p1): ...
211
    def add_circle_arc(self, *args, **kwargs): ...
212
    def add_ellipse_arc(self, *args, **kwargs): ...
213
    def add_spline(self, *args, **kwargs): ...
214
    def add_bspline(self, *args, **kwargs): ...
215
    def add_bezier(self, *args, **kwargs): ...
216
    def add_curve_loop(self, *args, **kwargs): ...
217
    def add_plane_surface(self, *args, **kwargs): ...
218
    def add_surface(self, *args, **kwargs): ...
219
    def add_surface_loop(self, *args, **kwargs): ...
220
    def add_volume(self, *args, **kwargs): ...
221
    def add_polygon(self, *args, **kwargs): ...
222
    
223
    # Physical groups and properties
224
    def add_physical(self, entities, label=None): ...
225
    
226
    # Mesh generation and control
227
    def generate_mesh(self, dim=3, order=None, algorithm=None, verbose=False): ...
228
    def set_mesh_size_callback(self, fun, ignore_other_mesh_sizes=True): ...
229
    def add_boundary_layer(self, *args, **kwargs): ...
230
    def set_background_mesh(self, *args, **kwargs): ...
231
    
232
    # Transformations
233
    def extrude(self, input_entity, translation_axis, num_layers=None, 
234
                heights=None, recombine=False): ...
235
    def translate(self, obj, vector): ...
236
    def rotate(self, obj, point, angle, axis): ...
237
    def copy(self, obj): ...
238
    def symmetrize(self, obj, coefficients): ...
239
    def dilate(self, obj, x0, abc): ...
240
    def mirror(self, obj, abcd): ...
241
    def remove(self, obj, recursive=False): ...
242
    
243
    # Transfinite meshing
244
    def set_transfinite_curve(self, curve, num_nodes, mesh_type, coeff): ...
245
    def set_transfinite_surface(self, surface, arrangement, corner_pts): ...
246
    def set_transfinite_volume(self, volume, corner_pts): ...
247
    def set_recombined_surfaces(self, surfaces): ...
248
    
249
    # Embedding operations
250
    def in_surface(self, input_entity, surface): ...
251
    def in_volume(self, input_entity, volume): ...
252
    
253
    # Context manager
254
    def __enter__(self): ...
255
    def __exit__(self, *args): ...
256
    def synchronize(self): ...
257
    def save_geometry(self, filename): ...
258

259
class Point:
260
    """Elementary point in 3D space."""
261
    def __init__(self, env, x, mesh_size=None): ...
262
    # Common attributes: x, dim=0, _id, dim_tag, dim_tags
263

264
class Line:
265
    """Line segment between two points."""
266
    def __init__(self, env, p0, p1): ...
267
    # Common attributes: points, dim=1, _id, dim_tag, dim_tags
268

269
class Polygon:
270
    """Polygon with optional holes and surface generation."""
271
    def __init__(self, host, points, mesh_size=None, holes=None, make_surface=True): ...
272
    # Common attributes: points, curves, lines, curve_loop, surface, dim=2, _id, dim_tag, dim_tags
273

274
class Surface:
275
    """Surface generated from curve loop."""  
276
    def __init__(self, env, curve_loop): ...
277
    # Common attributes: dim=2, _id, dim_tag, dim_tags
278

279
class Volume:
280
    """Volume from surface loop."""
281
    def __init__(self, env, surface_loop): ...
282
    # Common attributes: dim=3, _id, dim_tag, dim_tags
283

284
# Size field classes
285
class BoundaryLayer:
286
    """Boundary layer size field for mesh refinement near surfaces."""
287
    def __init__(self, lcmin, lcmax, distmin, distmax, edges_list=None, 
288
                 faces_list=None, nodes_list=None, num_points_per_curve=None): ...
289

290
class SetBackgroundMesh:
291
    """Background mesh configuration with multiple size fields."""
292
    def __init__(self, fields, operator): ...
293
```
294

295
## Shape Classes and Entity Types
296

297
Comprehensive documentation of all shape classes used in pygmsh, covering both geometric entities and primitive shape classes with their constructors and attributes.
298

299
```python { .api }
300
# Basic geometric entities
301
class Point:
302
    def __init__(self, env, x, mesh_size=None): ...
303
    # Common attributes: x, dim=0, _id, dim_tag, dim_tags
304

305
class Line:
306
    def __init__(self, env, p0, p1): ...
307
    # Common attributes: points, dim=1, _id, dim_tag, dim_tags
308

309
class Polygon:
310
    def __init__(self, host, points, mesh_size=None, holes=None, make_surface=True): ...
311
    # Common attributes: points, curves, curve_loop, surface, dim, _id, dim_tags
312

313
# OpenCASCADE primitive shapes
314
class Ball:
315
    def __init__(self, center, radius, angle1=-π/2, angle2=π/2, angle3=2π): ...
316

317
class Box:
318
    def __init__(self, x0, extents, char_length=None): ...
319

320
class Cylinder:
321
    def __init__(self, x0, axis, radius, angle=2π): ...
322

323
class Cone:
324
    def __init__(self, center, axis, radius0, radius1, angle=2π): ...
325

326
class Disk:
327
    def __init__(self, x0, radius0, radius1=None): ...
328

329
class Torus:
330
    def __init__(self, center, radius0, radius1, alpha=2π): ...
331

332
class Wedge:
333
    def __init__(self, x0, extents, top_extent=None): ...
334

335
class Rectangle:
336
    def __init__(self, x0, a, b, corner_radius=None): ...
337
```
338

339
[Shape Classes and Entity Types](./shape-classes.md)