Source code for physicsnemo.mesh.projections._extrude

# SPDX-FileCopyrightText: Copyright (c) 2023 - 2026 NVIDIA CORPORATION & AFFILIATES.
# SPDX-FileCopyrightText: All rights reserved.
# SPDX-License-Identifier: Apache-2.0
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

"""Extrusion operations for generating higher-dimensional meshes."""

from collections.abc import Sequence

import torch
from jaxtyping import Float
from tensordict import TensorDict

from physicsnemo.mesh.calculus.measure import (
    EFFECTIVE_MEASURE_KEY,
    _transfer_cell_measures,
    point_measure_dimension,
)
from physicsnemo.mesh.mesh import Mesh
from physicsnemo.mesh.projections._embed import embed
from physicsnemo.utils._small_linalg import small_det


[docs] def extrude( mesh: Mesh, vector: Float[torch.Tensor, " n_spatial_dims"] | Sequence[float] | None = None, capping: bool = False, allow_new_spatial_dims: bool = False, ) -> Mesh: """Extrude an N-dimensional mesh into an (N+1)-dimensional mesh. Extrusion sweeps a mesh along a direction to produce a mesh one manifold dimension higher - analogous to pushing a 2D cookie-cutter shape through space to create a solid 3D object. Each N-simplex in the input is swept into a prism and then tessellated into (N+1) child (N+1)-simplices. Common use cases: - **3D text and shapes**: extrude a 2D triangulated outline to create a solid tetrahedral volume (used by ``text_3d_3d`` in this library). - **Boundary layer meshing**: sweep a surface mesh along its normals to create a thin volumetric layer for near-wall CFD resolution. - **Space-time meshes**: extrude a spatial mesh along a time axis for space-time finite element discretizations. - **Structured mesh generation**: create 3D meshes from 2D cross-sections (e.g., a pipe from a circle, a channel from a rectangle). Dimensional behavior: - [N, M] -> [N+1, M]: Default case where M >= N+1 (e.g., 2D surface in 3D -> 3D volume in 3D) - [N, M] -> [N+1, N+1]: When M < N+1 and ``allow_new_spatial_dims=True``, spatial dimensions are extended automatically. Parameters ---------- mesh : Mesh Input mesh to extrude. Can be any manifold dimension N in any spatial dimension M >= N. vector : torch.Tensor | list | tuple | None, optional Extrusion direction and magnitude, shape ``(n_spatial_dims,)`` or broadcastable. If ``None``, defaults to a unit vector along the last spatial dimension: ``[0, 0, ..., 0, 1]``. For meshes where N+1 > M and ``allow_new_spatial_dims=True``, the default vector has shape ``(N+1,)`` with the last component set to 1. capping : bool, optional If True, cap the top and bottom of the extrusion to create a closed volume. Currently not implemented. allow_new_spatial_dims : bool, optional If True, allows extrusion to add new spatial dimensions when ``n_manifold_dims + 1 > n_spatial_dims``. The point coordinates are padded with zeros in the new dimensions (via :func:`embed`). If False (default), raises ``ValueError`` when spatial dimensions are insufficient. Returns ------- Mesh Extruded mesh with: - ``n_manifold_dims = original_n_manifold_dims + 1`` - ``n_spatial_dims = max(original_n_spatial_dims, n_manifold_dims)`` if ``allow_new_spatial_dims=True``, else ``original_n_spatial_dims`` - ``n_points = 2 * original_n_points`` (original + extruded copies) - ``n_cells = (original_n_manifold_dims + 1) * original_n_cells`` Raises ------ ValueError If ``n_manifold_dims + 1 > n_spatial_dims`` and ``allow_new_spatial_dims=False``, or if the mesh has dimensional point measures, which cannot be copied to the extruded points. NotImplementedError If ``capping=True`` (not yet implemented). Examples -------- >>> import torch >>> from physicsnemo.mesh import Mesh >>> # Extrude a triangle (2D) in 3D space to create a triangular prism >>> # tessellated into 3 tetrahedra >>> points = torch.tensor([[0., 0., 0.], [1., 0., 0.], [0., 1., 0.]]) >>> cells = torch.tensor([[0, 1, 2]]) >>> mesh = Mesh(points=points, cells=cells) >>> extruded = extrude(mesh, vector=[0., 0., 1.]) >>> assert extruded.n_manifold_dims == 3 # tetrahedra >>> assert extruded.n_cells == 3 # one triangle -> three tetrahedra >>> >>> # Extrude an edge (1D) in 2D space to create triangles >>> points = torch.tensor([[0., 0.], [1., 0.]]) >>> cells = torch.tensor([[0, 1]]) >>> mesh = Mesh(points=points, cells=cells) >>> extruded = extrude(mesh, vector=[0., 1.]) >>> assert extruded.n_manifold_dims == 2 # triangles >>> assert extruded.n_cells == 2 # one edge -> two triangles >>> >>> # Extrude a 2D surface in 2D space into 3D (auto-extending spatial dims) >>> points_2d = torch.tensor([[0., 0.], [1., 0.], [0., 1.]]) >>> triangles = torch.tensor([[0, 1, 2]]) >>> mesh_2d = Mesh(points_2d, triangles) # [2, 2] mesh >>> extruded = extrude(mesh_2d, allow_new_spatial_dims=True) >>> assert extruded.n_spatial_dims == 3 # new dimension added Notes ----- Before tessellating, the vertices of each parent simplex are sorted into a consistent global (ascending-index) order. With that ordering, the tessellation pattern for an N-simplex with (sorted) vertices [v0, v1, ..., vN] creates (N+1) child (N+1)-simplices: - Child i has vertices: [v0', v1', ..., vi', vi, vi+1, ..., vN] where primed vertices (v') are the extruded copies (offset by the extrusion vector). Sorting the vertices is the Freudenthal-Kuhn subdivision: prisms that share a face split it along the same diagonal, so the output is a *conforming* simplicial complex (no cracks / non-manifold facets). Orientation depends on the codimension of the output: - Codimension 0 (``target_manifold_dims == target_spatial_dims``): the raw Kuhn children alternate in orientation, so the last two vertices of any inverted cell are swapped to give every cell a positive signed volume. The result is a consistently oriented complex. - A 2D surface in 3D (e.g. extruding a curve): orientation is not enforced here; pass the result through :func:`physicsnemo.mesh.repair.fix_orientation`, which handles exactly this case. - Any other positive codimension: signed volume is undefined, so no orientation is enforced. """ ### Validate inputs if capping: raise NotImplementedError("Capping is not yet implemented. Use capping=False.") # Counting measures carry over to the copied points, but copying # dimensional ones would double every integral. if EFFECTIVE_MEASURE_KEY in mesh.point_data and bool( point_measure_dimension(mesh) != 0 ): raise ValueError( "Extrusion cannot copy dimensional point measures to the extruded " "points; remove them before extruding and set replacement measures " "on the result" ) ### Determine target spatial dimensions and construct extrusion vector n_manifold_dims = mesh.n_manifold_dims n_spatial_dims = mesh.n_spatial_dims target_manifold_dims = n_manifold_dims + 1 # Check if we have enough spatial dimensions for the extruded manifold if target_manifold_dims > n_spatial_dims: if not allow_new_spatial_dims: raise ValueError( f"Cannot extrude {n_manifold_dims=}-dimensional manifold in {n_spatial_dims=}-dimensional space " f"to {target_manifold_dims=}-dimensional manifold without increasing spatial dimensions.\n" f"Set allow_new_spatial_dims=True to add new spatial dimensions." ) # Extend spatial dimensions to accommodate extruded manifold target_spatial_dims = target_manifold_dims else: target_spatial_dims = n_spatial_dims # Construct or validate extrusion vector if vector is None: # Default: [0, 0, ..., 0, 1] in target spatial dimensions vector_tensor = torch.zeros( target_spatial_dims, dtype=mesh.points.dtype, device=mesh.points.device, ) vector_tensor[-1] = 1.0 else: # Convert to tensor if needed (torch.as_tensor avoids copies when possible) vector_tensor = torch.as_tensor( vector, dtype=mesh.points.dtype, device=mesh.points.device, ) # Validate vector shape if vector_tensor.ndim != 1: raise ValueError( f"Extrusion vector must be 1D, got {vector_tensor.ndim=} with {vector_tensor.shape=}" ) ### Pad mesh spatial dimensions if needed (delegate to embed) if target_spatial_dims > n_spatial_dims: mesh = embed(mesh, target_spatial_dims) original_points = mesh.points # Ensure vector has correct shape for broadcasting if vector_tensor.shape[0] != target_spatial_dims: if vector_tensor.shape[0] < target_spatial_dims: # Pad vector with zeros padding_width = target_spatial_dims - vector_tensor.shape[0] vector_tensor = torch.nn.functional.pad( vector_tensor, (0, padding_width), mode="constant", value=0.0, ) else: raise ValueError( f"Extrusion vector has {vector_tensor.shape[0]} dimensions but " f"target spatial dimensions are {target_spatial_dims}" ) ### Create extruded points extruded_points = original_points + vector_tensor.unsqueeze(0) # Concatenate: [original_points, extruded_points] all_points = torch.cat([original_points, extruded_points], dim=0) ### Tessellate cells # Each N-simplex becomes (N+1) child (N+1)-simplices # For parent cell with vertices [v0, v1, ..., vN]: # Child i: [v0', v1', ..., vi', vi, vi+1, ..., vN] # where vi' = vi + n_original_points (extruded vertex index) n_original_points = mesh.n_points n_original_cells = mesh.n_cells n_vertices_per_parent = n_manifold_dims + 1 # N+1 vertices in N-simplex n_children_per_parent = n_manifold_dims + 1 # N+1 children from each parent n_vertices_per_child = target_manifold_dims + 1 # (N+1)+1 vertices in (N+1)-simplex if n_original_cells == 0: # Empty mesh: no cells to extrude extruded_cells = torch.empty( (0, n_vertices_per_child), dtype=mesh.cells.dtype, device=mesh.cells.device, ) else: # Preallocate child cells array extruded_cells = torch.zeros( (n_original_cells * n_children_per_parent, n_vertices_per_child), dtype=mesh.cells.dtype, device=mesh.cells.device, ) # Vectorized tessellation # For each parent cell, generate all children simultaneously. # # Freudenthal-Kuhn: sort each parent simplex's vertices into a consistent # global (ascending-index) order before tessellating. A shared face is # then seen with the same vertex order by both incident prisms, so they # split it along the SAME diagonal and the result is a *conforming* # (crack-free) simplicial complex. Without the sort, neighbouring cells # that list a shared edge's endpoints in different local orders split the # shared quad face along opposite diagonals, producing a non-manifold # boundary (interior crack faces then leak into get_boundary_mesh). parent_cells = torch.sort( mesh.cells, dim=1 ).values # (n_cells, n_verts_per_parent) # NOTE: This loop iterates over child indices (bounded by simplex # dimension, not mesh size), so the iteration count is small (e.g. 3 # for triangles -> tetrahedra). For higher performance on very high- # dimensional simplices, this could be vectorized using a precomputed # tessellation pattern + torch.gather, similar to generate_child_cells # in subdivision/_topology.py. for child_idx in range(n_children_per_parent): # Child i has vertices: [v0', v1', ..., vi', vi, vi+1, ..., vN] # Extruded part: v0', v1', ..., vi' (child_idx + 1 vertices) # Original part: vi, vi+1, ..., vN (n_vertices_per_parent - child_idx vertices) child_vertices = [] # Add extruded vertices [v0', v1', ..., vi'] for j in range(child_idx + 1): extruded_vertex_indices = parent_cells[:, j] + n_original_points child_vertices.append(extruded_vertex_indices) # Add original vertices [vi, vi+1, ..., vN] for j in range(child_idx, n_vertices_per_parent): original_vertex_indices = parent_cells[:, j] child_vertices.append(original_vertex_indices) # Stack to form child cells: (n_cells, n_vertices_per_child) child_cells = torch.stack(child_vertices, dim=1) # Place in output array start_idx = child_idx * n_original_cells end_idx = (child_idx + 1) * n_original_cells extruded_cells[start_idx:end_idx] = child_cells ### Orient codim-0 cells consistently (positive signed volume) # Signed volume (an n-simplex determinant) is only defined when the output is # full-dimensional (target_manifold_dims == target_spatial_dims). The # Freudenthal-Kuhn children alternate in orientation, so ~half are inverted; # swap the last two vertices of those (one transposition negates the # determinant) so every cell has positive signed volume. Conformity, |volume|, # and propagated data are unaffected (only per-cell vertex order changes); # degenerate (zero-volume) cells are left untouched. if extruded_cells.shape[0] > 0 and target_manifold_dims == target_spatial_dims: cell_points = all_points[extruded_cells] # (n_cells, D+1, D) edge_vectors = cell_points[:, 1:] - cell_points[:, :1] # (n_cells, D, D) inverted = small_det(edge_vectors) < 0 # (n_cells,) swapped = extruded_cells[inverted, -2].clone() extruded_cells[inverted, -2] = extruded_cells[inverted, -1] extruded_cells[inverted, -1] = swapped ### Propagate data (excluding cached properties, which depend on geometry) # Explicit cell measures are not copied as data; they are transferred below. filtered_point_data = mesh.point_data filtered_cell_data = mesh.cell_data.exclude(EFFECTIVE_MEASURE_KEY) # Point data: concatenate original and copy for extruded points if len(filtered_point_data.keys()) > 0: extruded_point_data = TensorDict.cat( [filtered_point_data, filtered_point_data.clone()], dim=0, ) else: extruded_point_data = TensorDict( {}, batch_size=torch.Size([all_points.shape[0]]), device=all_points.device, ) # Cell data: replicate each parent cell's data (N+1) times. # Cells are ordered child-major: [c0_parent0, c0_parent1, ..., c1_parent0, ...], # so the parent index for cell i is i % n_original_cells. Using .repeat() # tiles the entire parent block N+1 times, producing the correct ordering. if len(filtered_cell_data.keys()) > 0: extruded_cell_data = filtered_cell_data.apply( lambda t: t.repeat(n_children_per_parent, *([1] * (t.ndim - 1))), batch_size=torch.Size([extruded_cells.shape[0]]), ) else: extruded_cell_data = TensorDict( {}, batch_size=torch.Size([extruded_cells.shape[0]]), device=extruded_cells.device, ) # Global data: preserve unchanged extruded_global_data = mesh.global_data ### Create and return extruded mesh extruded = Mesh( points=all_points, cells=extruded_cells, point_data=extruded_point_data, cell_data=extruded_cell_data, global_data=extruded_global_data, ) if EFFECTIVE_MEASURE_KEY in mesh.cell_data: # Each child keeps its parent's ratio of explicit to geometric measure. parents = torch.arange(n_original_cells, device=mesh.cells.device) _transfer_cell_measures(mesh, extruded, parents.repeat(n_children_per_parent)) return extruded