Python API overview

The top-level cutcells package re-exports the primary C++ bindings and Python mesh utilities. CutResult, MeshPart, EntityTable, EntityRules and EntityQuadrature live in cutcells.part, Condition in cutcells.conditions (re-exported as cutcells.Condition).

Mesh construction

Name	Purpose
MeshView	Background mesh view from coordinates, connectivity, offsets, cell types, and tdim.
mesh_from_pyvista(grid, tdim=None)	Convert a PyVista UnstructuredGrid to MeshView.
rectangle_mesh(x0, y0, x1, y1, nx, ny, cell_type="triangle")	Structured MeshView of a rectangle built with NumPy; nx, ny grid points; "triangle" or "quadrilateral".
box_mesh(x0, y0, z0, x1, y1, z1, nx, ny, nz, cell_type="tetrahedron")	Structured MeshView of a box built with NumPy; "tetrahedron" (conforming, six per grid cube) or "hexahedron".
rectangle_triangle_mesh(...)	PyVista triangular rectangle mesh helper.
rectangle_quad_mesh(...)	PyVista quadrilateral rectangle mesh helper.
box_tetrahedron_mesh(...)	PyVista tetrahedral box mesh helper.
box_hex_mesh(...)	PyVista hexahedral box mesh helper.

Level sets

Name	Purpose
LevelSetFunction	Scalar level-set function object; cut needs it with degree-of-freedom values, an analytic value, or level sets it is made of. name (read-only) gives its name.
LevelSetFunction(value=None, grad=None, nodal_values=None, gdim=0, name=None, level_sets=None, inside=None)	A level set from a callable or an AnalyticLevelSet (value), nodal values, or level sets: with level_sets (LevelSetFunctions of its precision or named AnalyticLevelSets) and inside (a condition on them, or a string with their names), a level set made of level sets; its own value is then optional.
level_set.level_sets, level_set.inside	The level sets it is made of, as given, or []; its inside, or None. Conditions on them select in a cut by their full names (result[cyl < 0] is result["ring.cyl < 0"]).
LevelSetMeshData	Interpolation mesh data for level-set degrees of freedom.
create_level_set_mesh_data(mesh, degree, merge_tol=-1.0)	Build level-set interpolation data.
create_level_set_function(mesh_data, dof_values, name="phi")	Build a named level set from mesh data and values.
create_level_set(mesh, phi, degree, name="phi")	Interpolate a batched callback where X.shape == (gdim, num_dofs).
interpolate_level_set(mesh, phi, degree, name="phi")	Interpolate a batched callback where X.shape == (num_dofs, gdim).
AnalyticLevelSet(value, gradient, box_bounds, taylor_bounds=None, name=None)	Analytic level set from Python callables (slow, for experiments). name (read-only) gives its name, or None.
AnalyticLevelSet.from_capsule(capsule, name=None)	Analytic level set from a capsule holding its C struct (fast, for compiled libraries); level_set.capsule gives one.
analytic_sphere(centre, radius, signed_distance=True, name=None)	Compiled sphere, |x - centre| - radius (a disk in 2D).
analytic_level_set_from_tape(..., name=None)	Analytic level set from the arrays of a ShapeForest tape.
cutcells.shapeforest.analytic_level_set(shape, parameters=None, name=None)	Analytic level set from a ShapeForest shape, expression or tape.

Conditions

Name	Purpose
level_set < 0, level_set > 0, level_set == 0	A Condition, for LevelSetFunction and AnalyticLevelSet; a number other than 0 raises. For a level set made of level sets: its inside, the rest, and its faces.
a & b, a | b	Conditions combined: and, or. Each comparison needs parentheses.
Condition	A selection built from level sets. str(condition) writes it as a selection string with the level sets’ own names, condition.text(names) with names[level_set].
cutcells.conditions.selection_text(selection, level_sets, names, owner=None)	The string of a selection for a cut of level_sets named names: a string as it is, a condition with its level sets matched by identity. For libraries that pass selections on as strings. With owner, the inside of the level set of that name, made of level_sets.

Cutting

Name	Purpose
cut(mesh, level_set, ...)	Classify every cell of a MeshView by one level set; returns a CutResult.
cut(mesh, [level_sets], ...)	The same with several level sets.
ho_cut(...)	Deprecated alias of cut.
cut(cell_type, vertex_coordinates, gdim, ls_values, cut_type_str, ...)	Low-level single-cell cutting API (straight cuts).
higher_order_cut(...)	Low-level single-cell cutting of a second-order cell.
cut_vtk_mesh(...)	Low-level whole-mesh cutting from flat VTK arrays.
locate_cells(...)	Locate parent cells matching a sign or interface selection.

cut(mesh, level_sets, ...) keyword arguments:

Argument	Default	Meaning
names	None	Names of the level sets, in order; by default their own, and phi, or phi1, phi2, … in a list, for analytic ones without a name.
name	None	Name of a single level set (not with names).
max_depth	12	Bisections of a cell before an unproven sign counts as cut.
backend	"quadrays"	Default backend of the selected parts; "lut" (also "straight") gives straight pieces.
options	None	QuadraysOptions or LutOptions for that backend.
triangulate	False	Lookup tables only: split pieces into simplices.
triangulation	"classical"	Lookup tables only: "classical" or "midpoint".
cut_approximation	"auto"	Lookup tables only: template order from the level sets’ degree ("auto"), "linear", or "iso_p1".
cut_approximation_order	1	Lookup tables only: template order for "iso_p1".
degree	None	Lookup tables only: template order for analytic level sets with "auto".

The lookup-table keywords raise when given with another backend.

Cut result objects

CutResult:

Member	Meaning
num_cells	Number of background cells.
num_cut_cells	Number of cells that some level set cuts.
num_level_sets	Number of level sets, a level set made of level sets counted as its own.
level_set_names	Names used in selection strings; the level sets a level set made of level sets is made of are named after it (ring.ball).
insides	The level sets made of level sets, by name, with their insides ({"ring": "ball < 0 and cyl > 0"}).
cut_cells	Cells that some level set cuts, ascending.
domains	Per level set and cell: 0 inside, 1 cut, 2 outside; shape (num_level_sets, num_cells).
entities(dim)	The entities of dimension dim < tdim on which a level set vanishes, an EntityTable (below).
zero_faces	Facets lying in a zero set, (level set, owning cell, facet of the cell in Basix numbering), shape (n, 3): from entities(tdim - 1), one owner each, the cell on the negative side, else the lowest.
backend, options	Backend and options of the parts selected from now on (settable).
result[selection]	Select a MeshPart with a condition (phi < 0, (a > 0) & (b == 0)) or a string ("phi < 0", "a > 0 and b = 0", "(a < 0 or b < 0) and c > 0").

MeshPart:

Member	Meaning
dim	Selected entity dimension.
num_cut_cells	Number of selected cut cells.
num_uncut_cells	Number of cells wholly in a volume part.
cut_cells	Selected cut cells.
uncut_cells	Cells wholly in a volume part.
entities(dim)	The entities of dimension dim the part holds whole: indices into result.entities(dim).
zero_faces	Indices into result.zero_faces: the facets the part holds.
on(*names)	The faces of a surface on the level sets named, such as result[ring == 0].on("cyl"): full or short names, or a level set made of level sets for all its faces.
backend, options	The part’s backend and options.
quadrature(order=3, mode="full", backend=None, options=None, entities="split")	Quadrature rules with positive weights, one per cell; order is the polynomial degree integrated exactly on flat pieces (1 to 10). entities: how the cells sharing a facet, edge or vertex take its rule: "split" (1/n each), "negative", "positive" (the cells on that side), "owner" (the lowest cell) or "exclude" (none).
entity_quadrature(order=3, backend=None, options=None)	The rules on the facets, edges and vertices the part holds, once per entity: an EntityQuadrature.
visualization_mesh(mode="full", backend=None, degree=3, options=None)	QuadraysLeafMesh of Lagrange cells (quadrays) or CutMesh of straight cells (lookup tables).
write_vtu(filename, mode="full", backend=None, degree=3, options=None)	Write the visualisation mesh to a .vtu file.

mode is "full" (cut cells plus whole cells) or "cut_only". backend=None uses the part’s backend.

EntityTable (result.entities(dim)), CSR arrays over entities and their sharing cells:

Member	Meaning
dim, num_entities	Dimension and number of the entities.
types	Per entity, its CellType as an int (point, interval, triangle, quadrilateral).
nodes, node_offsets	The entities’ mesh nodes in chart order (sorted; a quadrilateral’s lowest node, its lower and higher neighbours, the opposite node).
cells, cell_offsets	The cells sharing each entity, ascending.
local_index	The entity’s number in each sharing cell (Basix numbering, basix.topology).
vanishing	Per entity: bit l, level set l vanishes on it.
zero	Per entity: the vanishing level sets that change sign across it (or all, on the mesh boundary).
negative, positive	Per sharing cell: bit l, the cell lies where the vanishing level set l is negative, positive.
boundary	Per entity: 1 on the mesh boundary.

EntityQuadrature (part.entity_quadrature(order)): facets, ridges (codimension 2) and vertices (3D; None in 2D), each an EntityRules; on[dim] gives those of dimension dim. On a mesh of intervals the facets are the vertices.

EntityRules, one rule per entity, CSR arrays:

Member	Meaning
tdim, entity_dim, num_rules	Dimensions of the cells and of the entities; number of rules.
entity_types, entity_nodes, node_offsets	Per rule, the entity’s CellType and its nodes in chart order.
zero	Per rule: bit l, the points lie in level set l’s zero set.
points, weights, offsets	Points in the entity’s reference cell, shape (n, entity_dim); physical weights (1 for a point).
cells, cell_offsets, local_index	Per rule, the cells sharing the entity and its number in each (Basix).
negative, positive	Per sharing cell: its sides of the level sets vanishing on the entity.
cell_points, cell_point_offsets	Per sharing cell, the rule’s points in its reference coordinates, shape (m, tdim).

Backend options

QuadraysOptions() (set attributes after construction):

Attribute	Meaning
margin	Required |d_k psi| / |grad psi| on a box for a height direction, at most 0.9/sqrt(D) on boxes with D free coordinates.
tolerance	Relative accuracy of curved pieces: boxes are bisected while q and q + 1 points per segment disagree by more. 0 (default): the rule’s own rate, (h kappa / 2)^(2q) for cells of size h and curvature kappa; negative: no check.
anchor_folds	n > 0: base segments that end at or within four lengths of a fold of a curved zero set (where it turns back along the height direction) take n q Gauss points in s, x = x_f -+ s^2, anchored at the fold. In 3D cells the same applies to the silhouette of the level set seen along the height direction: on the height lines of the base boxes, and on their base segments where it crosses the lines’ bounds. 1 (default): as moment_tolerance allows, and twice the points on the boxes it does not; 2: polynomials of degree 2q - 1 stay exact everywhere, at twice the points; 0: off.
moment_tolerance	The accuracy check also compares a moment of what a mass matrix sees, a Legendre polynomial squared along each axis of the cell, relative to the piece as the measure is. A box that fails first takes twice the points on its anchored segments, then up to four points more per direction, and is bisected only if that fails too. This is what it asks of six or more points per segment; of fewer, this value to the power q / 6. 1e-8 (default); 0: the measure only.
fold_splits	A box with two free coordinates that no axis certifies is split at the folds of its zero curves (where one turns along the height direction) and where two of them cross, instead of bisected; its height lines take all roots. True (default). With tolerance 0 such boxes must agree with q + 1 points to 1e-12, else they are bisected.
follow_curves	Curve parts in 3D cells follow the curve: arcs between the faces of the cell, split where branches cross and where a further level set vanishes, with Gauss-Legendre points in arc length. True (default); a cell it cannot follow goes by height lines (QuadraysStats.curve_fallbacks).
max_depth, max_bisections	Bisection limits per level and per cell.
points_per_segment	Gauss-Legendre points per segment; 0 chooses them from the order.
diagnose	Record why each bisection happened (QuadraysStats.causes).
prune_bounds, split_bounds, diagonal_frames, rotation_depth, mask_subdivisions, taylor_subdivisions, two_roots_depth	Engine controls; see the docstrings.

LutOptions(template_order=0, triangulate=False, triangulation="classical"):

Attribute	Meaning
template_order	Order k of the Pk-iso-P1 template that subdivides a cut cell, 1 to 4; 0: the highest degree of the level sets that cut the cell, 2 for analytic ones.
triangulate	Split the cut pieces into simplices.

Quadrature

Name	Purpose
QuadratureRules	Flat quadrature storage for points, weights, offsets, and parent cells.
compress_rules(rules, degree, space="tensor")	Rules with at most as many points as the polynomial space has; returns (QuadratureRules, CompressionStats).
make_quadrature(cut_cells, order)	Generate rules for low-level cut cells.
runtime_quadrature(...)	Generate rules directly from VTK-style mesh arrays and level-set values (straight cuts).
physical_points(rules, points, connectivity, offsets, vtk_types)	Map reference quadrature points to physical space.
quadrays_cell_rules(...), quadrays_cell_leaves(...)	quadrays on a single cell.

Output and conversion

Name	Purpose
to_pyvista(mesh)	Convert a MeshView, a CutMesh or a QuadraysLeafMesh (curved Lagrange cells, with the cell array parent) to a PyVista UnstructuredGrid.
cutmesh_to_pyvista(cut_mesh)	Convert a CutCells CutMesh to PyVista.
QuadraysLeafMesh	Lagrange cells of the quadrays decomposition: points, connectivity, offsets, vtk_types, parent, degree.
write_vtk(filename, vertex_coordinates, connectivity, offsets, element_types, gdim)	Low-level VTK/VTU writer for flat arrays.
write_level_set_vtu(filename, level_set, field_name="phi")	Write level-set diagnostics from a LevelSetFunction.
safe_part_name(expr)	Convert a selection expression to a compact file-safe token.

Precision-specific aliases

The binding exports float32 and float64 variants for many native objects, for example MeshView_float64, CutCell_float64, QuadratureRules_float64 and cutcells.part.MeshPart_float64. The unsuffixed aliases such as MeshView, LevelSetFunction and cutcells.part.MeshPart are the recommended default entry points for ordinary Python workflows. The former names HOCutResult and HOMeshPart still work but are deprecated.