0
# Built-in Geometry Operations
1

2
The built-in geometry kernel (`pygmsh.geo`) provides traditional CAD-style geometric modeling with parametric shapes, extrusions, revolutions, and structured mesh generation. This kernel excels at engineering applications requiring precise control over mesh topology and structured meshing approaches.
3

4
## Capabilities
5

6
### Circle Operations
7

8
Create circular geometries with optional hole patterns and surface generation. Supports compound circles for complex topologies and configurable mesh sizing.
9

10
```python { .api }
11
def add_circle(x0, radius, mesh_size=None, R=None, compound=False, 
12
               num_sections=3, holes=None, make_surface=True):
13
    """
14
    Create a circle with optional holes and surface.
15
    
16
    Parameters:
17
    - x0: list[float], center point coordinates [x, y, z]
18
    - radius: float, circle radius
19
    - mesh_size: float, optional mesh size at circle boundary
20
    - R: array, optional rotation matrix for circle orientation
21
    - compound: bool, create compound circle for complex topologies
22
    - num_sections: int, number of sections for circle discretization (default: 3)
23
    - holes: list, optional holes to subtract from circle surface
24
    - make_surface: bool, create surface from circle curve (default: True)
25
    
26
    Returns:
27
    Circle object with attributes: x0, radius, R, compound, num_sections, 
28
    holes, curve_loop, plane_surface, mesh_size
29
    """
30
```
31

32
### Rectangular Shapes
33

34
Create rectangular surfaces with precise boundary control and optional hole patterns. Ideal for domain decomposition and structured mesh generation.
35

36
```python { .api }
37
def add_rectangle(xmin, xmax, ymin, ymax, z, mesh_size=None, holes=None, make_surface=True):
38
    """
39
    Create a rectangle in the XY plane at specified Z coordinate.
40
    
41
    Parameters:
42
    - xmin, xmax: float, X-direction bounds  
43
    - ymin, ymax: float, Y-direction bounds
44
    - z: float, Z coordinate of rectangle plane
45
    - mesh_size: float, optional mesh size at rectangle boundary
46
    - holes: list, optional holes to subtract from rectangle surface
47
    - make_surface: bool, create surface from rectangle boundary (default: True)
48
    
49
    Returns:
50
    Rectangle surface object
51
    """
52
```
53

54
### Ellipsoidal Shapes
55

56
Create ellipsoids and spheres with configurable radii and volume generation. Supports both surface-only and volumetric representations.
57

58
```python { .api }
59
def add_ellipsoid(x0, radii, mesh_size=None, with_volume=True, holes=None):
60
    """
61
    Create an ellipsoid with specified radii in each direction.
62
    
63
    Parameters:
64
    - x0: list[float], center point coordinates [x, y, z]
65
    - radii: list[float], radii in [x, y, z] directions
66
    - mesh_size: float, optional mesh size at ellipsoid surface
67
    - with_volume: bool, create volume (True) or surface only (False)
68
    - holes: list, optional holes to subtract from ellipsoid volume
69
    
70
    Returns:
71
    Ellipsoid object (surface or volume based on with_volume parameter)
72
    """
73

74
def add_ball(x0, radius, **kwargs):
75
    """
76
    Create a sphere (special case of ellipsoid with equal radii).
77
    
78
    Parameters:
79
    - x0: list[float], center point coordinates [x, y, z]  
80
    - radius: float, sphere radius
81
    - **kwargs: additional arguments passed to add_ellipsoid
82
    
83
    Returns:
84
    Sphere object
85
    """
86
```
87

88
### Box Geometries
89

90
Create rectangular boxes with precise dimensional control and volume generation capabilities.
91

92
```python { .api }
93
def add_box(x0, x1, y0, y1, z0, z1, mesh_size=None, with_volume=True, holes=None):
94
    """
95
    Create a rectangular box defined by coordinate bounds.
96
    
97
    Parameters:
98
    - x0, x1: float, X-direction bounds
99
    - y0, y1: float, Y-direction bounds  
100
    - z0, z1: float, Z-direction bounds
101
    - mesh_size: float, optional mesh size at box surfaces
102
    - with_volume: bool, create volume (True) or surface only (False)
103
    - holes: list, optional holes to subtract from box volume
104
    
105
    Returns:
106
    Box object (surface or volume based on with_volume parameter)
107
    """
108
```
109

110
### Toroidal Shapes
111

112
Create torus geometries with inner and outer radii, supporting multiple construction variants for different meshing strategies.
113

114
```python { .api }
115
def add_torus(irad, orad, mesh_size=None, R=np.eye(3), x0=np.array([0,0,0]), 
116
              variant="extrude_lines"):
117
    """
118
    Create a torus with inner and outer radii.
119
    
120
    Parameters:
121
    - irad: float, inner radius (minor radius)
122
    - orad: float, outer radius (major radius)
123
    - mesh_size: float, optional mesh size at torus surface
124
    - R: array, rotation matrix for torus orientation (default: identity)
125
    - x0: array, center point coordinates (default: origin)
126
    - variant: str, construction method ("extrude_lines" or other variants)
127
    
128
    Returns:
129
    Torus object
130
    """
131
```
132

133
### Pipe Geometries
134

135
Create hollow cylindrical pipes with configurable wall thickness and construction variants.
136

137
```python { .api }
138
def add_pipe(outer_radius, inner_radius, length, R=np.eye(3), x0=np.array([0,0,0]), 
139
             mesh_size=None, variant="rectangle_rotation"):
140
    """
141
    Create a hollow cylindrical pipe.
142
    
143
    Parameters:
144
    - outer_radius: float, pipe outer radius
145
    - inner_radius: float, pipe inner radius (wall thickness = outer - inner)
146
    - length: float, pipe length
147
    - R: array, rotation matrix for pipe orientation (default: identity)
148
    - x0: array, center point coordinates (default: origin)
149
    - mesh_size: float, optional mesh size at pipe surfaces
150
    - variant: str, construction method ("rectangle_rotation" or other variants)
151
    
152
    Returns:
153
    Pipe object with hollow cylindrical volume
154
    """
155
```
156

157
### Revolution Operations
158

159
Create surfaces and volumes by revolving curves and surfaces around specified axes with angle constraints.
160

161
```python { .api }
162
def revolve(*args, **kwargs):
163
    """
164
    Revolve entity around axis to create surfaces or volumes.
165
    
166
    Note: For geo kernel, revolution angle must be < π (180 degrees).
167
    
168
    Parameters depend on input entity type:
169
    - input_entity: curve, surface, or volume to revolve
170
    - point_on_axis: point on revolution axis
171
    - axis_direction: revolution axis direction vector
172
    - angle: revolution angle in radians (must be < π)
173
    
174
    Returns:
175
    Revolved entity (surface from curve, volume from surface)
176
    """
177
```
178

179
### Twist Extrusion
180

181
Create complex geometries by extruding entities along a path with simultaneous rotation, enabling helical and twisted shapes.
182

183
```python { .api }
184
def twist(input_entity, translation_axis, rotation_axis, point_on_axis, angle, 
185
          num_layers=None, heights=None, recombine=False):
186
    """
187
    Create twisted extrusion of entity with simultaneous translation and rotation.
188
    
189
    Parameters:
190
    - input_entity: curve or surface to twist
191
    - translation_axis: translation direction vector
192
    - rotation_axis: rotation axis direction vector  
193
    - point_on_axis: point on rotation axis
194
    - angle: total rotation angle in radians
195
    - num_layers: int, number of extrusion layers for structured meshing
196
    - heights: list[float], layer heights for non-uniform extrusion
197
    - recombine: bool, recombine tetrahedra into hexahedra where possible
198
    
199
    Returns:
200
    Twisted entity (surface from curve, volume from surface)
201
    """
202
```
203

204
### Embedding Operations
205

206
Embed geometric entities within higher-dimensional entities for mesh generation control and physical group management.
207

208
```python { .api }
209
def in_surface(input_entity, surface):
210
    """
211
    Embed entity in surface for mesh generation.
212
    
213
    Embedded entities constrain mesh generation without creating physical boundaries.
214
    
215
    Parameters:
216
    - input_entity: point or curve to embed
217
    - surface: target surface for embedding
218
    
219
    Returns:
220
    None (modifies geometry in-place)
221
    """
222

223
def in_volume(input_entity, volume):
224
    """
225
    Embed entity in volume for mesh generation.
226
    
227
    Embedded entities constrain mesh generation without creating physical boundaries.
228
    
229
    Parameters:
230
    - input_entity: point, curve, or surface to embed
231
    - volume: target volume for embedding
232
    
233
    Returns:
234
    None (modifies geometry in-place)
235
    """
236
```
237

238
## Usage Examples
239

240
### Creating a Meshed Circle with Holes
241

242
```python
243
import pygmsh
244
import numpy as np
245

246
with pygmsh.geo.Geometry() as geom:
247
    # Create main circle
248
    outer_circle = geom.add_circle([0, 0, 0], radius=2.0, mesh_size=0.2)
249
    
250
    # Create holes
251
    hole1 = geom.add_circle([-0.8, 0, 0], radius=0.3, mesh_size=0.1, make_surface=False)
252
    hole2 = geom.add_circle([0.8, 0, 0], radius=0.3, mesh_size=0.1, make_surface=False)
253
    
254
    # Subtract holes from main circle
255
    surface_with_holes = geom.add_circle(
256
        [0, 0, 0], radius=2.0, mesh_size=0.2, 
257
        holes=[hole1.curve_loop, hole2.curve_loop]
258
    )
259
    
260
    mesh = geom.generate_mesh(dim=2)
261
```
262

263
### Creating a Revolved Surface
264

265
```python
266
import pygmsh
267
import numpy as np
268

269
with pygmsh.geo.Geometry() as geom:
270
    # Create profile curve
271
    points = [
272
        geom.add_point([1.0, 0.0, 0.0]),
273
        geom.add_point([1.5, 0.5, 0.0]),
274
        geom.add_point([1.2, 1.0, 0.0]),
275
        geom.add_point([1.0, 1.0, 0.0])
276
    ]
277
    
278
    lines = [
279
        geom.add_line(points[i], points[i+1]) 
280
        for i in range(len(points)-1)
281
    ]
282
    
283
    # Revolve around Z-axis (angle < π for geo kernel)
284
    revolved_surface = geom.revolve(
285
        lines, 
286
        point_on_axis=[0, 0, 0],
287
        axis_direction=[0, 0, 1], 
288
        angle=np.pi * 0.8  # Must be < π
289
    )
290
    
291
    mesh = geom.generate_mesh(dim=3)
292
```
293

294
### Creating a Twisted Extrusion
295

296
```python  
297
import pygmsh
298
import numpy as np
299

300
with pygmsh.geo.Geometry() as geom:
301
    # Create base rectangle
302
    rectangle = geom.add_rectangle(-0.5, 0.5, -0.3, 0.3, z=0.0, make_surface=False)
303
    
304
    # Twist extrude along Z-axis with rotation around Z
305
    twisted_volume = geom.twist(
306
        rectangle.curve_loop,
307
        translation_axis=[0, 0, 1],    # Extrude in Z
308
        rotation_axis=[0, 0, 1],       # Rotate around Z  
309
        point_on_axis=[0, 0, 0],
310
        angle=np.pi/2,                 # 90 degree twist
311
        num_layers=10,
312
        heights=[0.1] * 10             # Uniform layer heights
313
    )
314
    
315
    mesh = geom.generate_mesh(dim=3)
316
```
317

318
## Geometric Entity Classes
319

320
### Circle Class
321

322
```python { .api }
323
class Circle:
324
    """Result object from add_circle() containing circle geometry and mesh data."""
325
    
326
    def __init__(self, x0, radius, mesh_size, R, compound, num_sections, 
327
                 holes, curve_loop, plane_surface):
328
        """
329
        Initialize circle object.
330
        
331
        Attributes:
332
        - x0: list[float], center coordinates
333
        - radius: float, circle radius
334
        - mesh_size: float, mesh size at boundary
335
        - R: array, rotation matrix  
336
        - compound: bool, compound circle flag
337
        - num_sections: int, discretization sections
338
        - holes: list, hole curve loops
339
        - curve_loop: CurveLoop, circle boundary
340
        - plane_surface: PlaneSurface, circle surface (if created)
341
        """
342
```