Transformations and Projections#

Geometric Transformations#

Linear and affine transformations on mesh geometry. Each function returns a new Mesh with transformed point coordinates and appropriately invalidated caches. (Any cached quantities, such as normals and areas, are automatically recomputed on next access.)

All transformations are also available as methods on Mesh.

import numpy as np
from physicsnemo.mesh.primitives.surfaces import sphere_icosahedral

mesh = sphere_icosahedral.load(subdivisions=2)

# Via Mesh methods
translated = mesh.translate([1.0, 0.0, 0.0])
rotated = mesh.rotate(axis=[0, 0, 1], angle=np.pi / 4)
scaled = mesh.scale(2.0)
scaled_aniso = mesh.scale([2.0, 1.0, 0.5])

# Arbitrary linear transform
import torch
matrix = torch.eye(3) * 2
transformed = mesh.transform(matrix)

Geometric transformations for simplicial meshes.

This module implements linear and affine transformations with intelligent cache handling. By default, all caches are invalidated; transformations explicitly opt-in to preserve/transform specific cache fields.

Cached fields handled: - areas: point_data and cell_data - normals: point_data and cell_data - centroids: cell_data only

Rotate the mesh about an axis by a specified angle.

Parameters:

mesh (Mesh) – Input mesh to rotate.
angle (float) – Rotation angle in radians (counterclockwise, right-hand rule).
axis (torch.Tensor or list or tuple or {"x", "y", "z"} or None) – Rotation axis vector. None for 2D, shape (3,) for 3D. String literals “x”, “y”, “z” are converted to unit vectors (1,0,0), (0,1,0), (0,0,1) respectively.
center (torch.Tensor or list or tuple or None) – Center point for rotation. If None, rotates about the origin.
transform_point_data (bool) – If True, rotate vector/tensor fields in point_data.
transform_cell_data (bool) – If True, rotate vector/tensor fields in cell_data.
transform_global_data (bool) – If True, rotate vector/tensor fields in global_data.

Returns:

New Mesh with rotated geometry.

Return type:

Mesh

Notes

Cache Handling:

areas: Unchanged (rotation preserves volumes)
centroids: Rotated
normals: Rotated

Scale the mesh by specified factor(s).

Parameters:

mesh (Mesh) – Input mesh to scale.
factor (float or torch.Tensor or list or tuple) – Scale factor(s). Scalar for uniform, vector for non-uniform.
center (torch.Tensor or list or tuple or None) – Center point for scaling. If None, scales about the origin.
transform_point_data (bool) – If True, scale vector/tensor fields in point_data.
transform_cell_data (bool) – If True, scale vector/tensor fields in cell_data.
transform_global_data (bool) – If True, scale vector/tensor fields in global_data.
assume_invertible (bool or None) – Controls cache propagation: - True: Assume all factors are non-zero, propagate caches (compile-safe) - False: Assume some factor is zero, skip cache propagation (compile-safe) - None: Check determinant at runtime (may cause graph breaks under torch.compile)

Returns:

New Mesh with scaled geometry.

Return type:

Mesh

Notes

Cache Handling:

areas: Scaled correctly. For non-isotropic transforms of codimension-1
embedded manifolds, per-element scaling is computed using normals.
centroids: Scaled
normals: Transformed by inverse-transpose (direction adjusted, magnitude normalized)

physicsnemo.mesh.transformations.geometric.transform( mesh: Mesh, matrix: Tensor, transform_point_data: bool = False, transform_cell_data: bool = False, transform_global_data: bool = False, assume_invertible: bool | None = None, ) → Mesh[source]#

Apply a linear transformation to the mesh.

Parameters:

mesh (Mesh) – Input mesh to transform.
matrix (torch.Tensor) – Transformation matrix, shape (new_n_spatial_dims, n_spatial_dims).
transform_point_data (bool) – If True, transform vector/tensor fields in point_data.
transform_cell_data (bool) – If True, transform vector/tensor fields in cell_data.
transform_global_data (bool) – If True, transform vector/tensor fields in global_data.
assume_invertible (bool or None) – Controls cache propagation for square matrices: - True: Assume matrix is invertible, propagate caches (compile-safe) - False: Assume matrix is singular, skip cache propagation (compile-safe) - None: Check determinant at runtime (may cause graph breaks under torch.compile)

Returns:

New Mesh with transformed geometry and appropriately updated caches.

Return type:

Mesh

Notes

Cache Handling:

areas: For square invertible matrices:
- Full-dimensional meshes: scaled by |det|
- Codimension-1 manifolds: per-element scaling using |det| × ||M^{-T} n||
- Higher codimension: invalidated
centroids: Always transformed
normals: For square invertible matrices, transformed by inverse-transpose

physicsnemo.mesh.transformations.geometric.translate(mesh: Mesh, offset: Tensor | list | tuple) → Mesh[source]#

Apply a translation to the mesh.

Translation only affects point positions and centroids. Vector/tensor fields are unchanged by translation (they represent directions, not positions).

Parameters:

mesh (Mesh) – Input mesh to translate.
offset (torch.Tensor or list or tuple) – Translation vector, shape (n_spatial_dims,).

Returns:

New Mesh with translated geometry.

Return type:

Mesh

Notes

Cache Handling:

areas: Unchanged
centroids: Translated
normals: Unchanged

Projections#

Spatial dimension manipulation – changing the embedding dimension of a mesh without altering its manifold dimension.

embed() – add spatial dimensions (non-destructive; for example, 2D mesh to 3D by appending zero coordinates)
extrude() – sweep a manifold to create a mesh one dimension higher (for example, a triangle mesh extruded to a prism mesh)
project() – reduce spatial dimensions (lossy; drops coordinate axes)

Projection operations for mesh extrusion, embedding, and spatial dimension manipulation.

This module provides functionality for: - Embedding meshes in higher-dimensional spaces (non-destructive) - Projecting meshes to lower-dimensional spaces (lossy) - Extruding manifolds to higher dimensions