# 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.
"""Laplacian mesh smoothing with feature preservation.
Implements geometry-aware smoothing using cotangent weights, with options for
preserving boundaries and sharp features.
"""
from typing import TYPE_CHECKING
import torch
from jaxtyping import Bool, Float, Int
from physicsnemo.mesh.boundaries import get_boundary_vertices
from physicsnemo.mesh.boundaries._facet_extraction import extract_candidate_facets
from physicsnemo.mesh.geometry.dual_meshes import compute_cotan_weights_fem
from physicsnemo.mesh.utilities._tolerances import safe_eps
from physicsnemo.mesh.utilities._topology import extract_unique_edges
if TYPE_CHECKING:
from physicsnemo.mesh.mesh import Mesh
[docs]
def smooth_laplacian(
mesh: "Mesh",
n_iter: int = 20,
relaxation_factor: float = 0.01,
convergence: float = 0.0,
feature_angle: float = 45.0,
preserve_boundaries: bool = True,
preserve_features: bool = False,
inplace: bool = False,
) -> "Mesh":
"""Smooth mesh using Laplacian smoothing with cotangent weights.
Applies iterative Laplacian smoothing to adjust point positions, making cells
better shaped and vertices more evenly distributed. Uses geometry-aware
cotangent weights that respect the mesh structure.
Parameters
----------
mesh : Mesh
Input mesh to smooth
n_iter : int, optional
Number of smoothing iterations. More iterations produce smoother
results but take longer. Default: 20
relaxation_factor : float, optional
Controls displacement per iteration. Lower values are
more stable but require more iterations. Range: (0, 1]. Default: 0.01
convergence : float, optional
Convergence criterion relative to bounding box diagonal.
Stops early if max vertex displacement < convergence * bbox_diagonal.
Set to 0.0 to disable early stopping. Default: 0.0
feature_angle : float, optional
Angle threshold (degrees) for sharp edge detection.
Edges with dihedral angle > feature_angle are considered sharp features.
Only used for codimension-1 manifolds. Default: 45.0
preserve_boundaries : bool, optional
If True (default), boundary vertices are fixed and
will not move during smoothing, preserving the original boundary shape.
If False, boundary vertices are smoothed like interior vertices.
preserve_features : bool, optional
If True, vertices on sharp feature edges (with dihedral
angle > feature_angle) are fixed and will not move. If False (default),
feature vertices are smoothed normally.
inplace : bool, optional
If True, modifies mesh in place. If False, creates a copy. Default: False
Returns
-------
Mesh
Smoothed mesh. Same object as input if inplace=True, otherwise a new mesh.
Raises
------
ValueError
If n_iter < 0 or relaxation_factor <= 0
Examples
--------
>>> from physicsnemo.mesh.primitives.surfaces import sphere_icosahedral
>>> mesh = sphere_icosahedral.load(subdivisions=2)
>>> # Basic smoothing
>>> smoothed = smooth_laplacian(mesh, n_iter=10, relaxation_factor=0.1)
>>> assert smoothed.n_points == mesh.n_points
>>> # Preserve boundaries and sharp edges
>>> smoothed = smooth_laplacian(
... mesh,
... n_iter=50,
... feature_angle=45.0,
... preserve_boundaries=True,
... preserve_features=True,
... )
>>>
>>> # With convergence criterion
>>> smoothed = smooth_laplacian(
... mesh,
... n_iter=1000,
... convergence=0.001, # Stop if change < 0.1% of bbox
... )
Notes
-----
- Cotangent weights are used for codimension-1 manifolds of dimension >= 2
- Uniform weights are used for curves, higher codimension, or volumetric meshes
- Feature detection only works for codimension-1 manifolds where normals exist
- Cell connectivity and all data fields are preserved (only points move)
"""
### Validate parameters
if n_iter < 0:
raise ValueError(f"n_iter must be >= 0, got {n_iter=}")
if relaxation_factor <= 0:
raise ValueError(f"relaxation_factor must be > 0, got {relaxation_factor=}")
if convergence < 0:
raise ValueError(f"convergence must be >= 0, got {convergence=}")
### Handle empty mesh or zero iterations
if mesh.n_points == 0 or mesh.n_cells == 0 or n_iter == 0:
if inplace:
return mesh
else:
return mesh.clone()
### Create working copy if not inplace
if not inplace:
mesh = mesh.clone()
device = mesh.points.device
dtype = mesh.points.dtype
n_points = mesh.n_points
n_spatial_dims = mesh.n_spatial_dims
### Compute edge weights (also extracts unique edges)
edge_weights, edges = _compute_edge_weights(mesh) # (n_edges,), (n_edges, 2)
### Save original positions for constrained vertices
original_points = mesh.points.clone()
### Identify constrained vertices (boundaries and features)
constrained_vertices = torch.zeros(n_points, dtype=torch.bool, device=device)
if preserve_boundaries:
# Boundary vertices should not move
boundary_vertex_mask = get_boundary_vertices(mesh)
constrained_vertices |= boundary_vertex_mask
if preserve_features:
# Feature vertices should not move
feature_vertex_mask = _get_feature_vertices(mesh, edges, feature_angle)
constrained_vertices |= feature_vertex_mask
### Compute convergence threshold
convergence_threshold = 0.0
if convergence > 0:
# Threshold relative to bounding box diagonal
bbox_min = mesh.points.min(dim=0).values
bbox_max = mesh.points.max(dim=0).values
bbox_diagonal = torch.norm(bbox_max - bbox_min)
convergence_threshold = convergence * bbox_diagonal
### Total edge weight per vertex: Σ_j w_ij
# The weights come from the initial geometry, so this is fixed across iterations.
weight_sum = torch.zeros(n_points, dtype=dtype, device=device)
weight_sum.scatter_add_(0, edges[:, 0], edge_weights)
weight_sum.scatter_add_(0, edges[:, 1], edge_weights)
weight_sum.clamp_(min=safe_eps(dtype))
### Pre-allocate buffers for iterative smoothing (avoid per-iteration allocation)
laplacian = torch.zeros((n_points, n_spatial_dims), dtype=dtype, device=device)
### Iterative smoothing
for iteration in range(n_iter):
# Save old positions for convergence check
if convergence > 0:
old_points = mesh.points.clone()
### Compute Laplacian at each vertex: L(p_i) = Σ_j w_ij (p_j - p_i)
laplacian.zero_()
# For each edge (i, j) with weight w:
# laplacian[i] += w * (p_j - p_i)
# laplacian[j] += w * (p_i - p_j)
# Edge vectors: p_j - p_i
edge_vectors = mesh.points[edges[:, 1]] - mesh.points[edges[:, 0]]
weighted_vectors = edge_vectors * edge_weights.unsqueeze(-1)
# Accumulate contributions from edges
# For vertex edges[:,0]: add weighted_vectors
laplacian.scatter_add_(
0,
edges[:, 0].unsqueeze(-1).expand(-1, n_spatial_dims),
weighted_vectors,
)
# For vertex edges[:,1]: subtract weighted_vectors
laplacian.scatter_add_(
0,
edges[:, 1].unsqueeze(-1).expand(-1, n_spatial_dims),
-weighted_vectors,
)
### Normalize by total weight per vertex (in place, to actually reuse the
# pre-allocated buffer across iterations rather than reallocating each step).
laplacian /= weight_sum.unsqueeze(-1)
### Apply relaxation, keeping constrained vertices at their original positions
# torch.where instead of boolean-mask indexing, which would synchronize the
# device twice per iteration (and break a torch.compile graph).
mesh.points = torch.where(
constrained_vertices.unsqueeze(-1),
original_points,
mesh.points + relaxation_factor * laplacian,
)
### Check convergence
if convergence > 0:
max_displacement = torch.norm(mesh.points - old_points, dim=-1).max()
if max_displacement < convergence_threshold:
break
### The loop mutated mesh.points in place, so geometry caches derived from
### point positions (cell_areas / cell_normals / cell_centroids, point_normals,
### curvature, ...) are now stale. Invalidate them so callers recompute from the
### smoothed geometry. Topology/adjacency caches depend only on `cells` (which
### smoothing does not change), so they remain valid and are preserved.
mesh._cache["cell"] = mesh._cache["cell"].empty()
mesh._cache["point"] = mesh._cache["point"].empty()
return mesh
def _compute_edge_weights(
mesh: "Mesh",
) -> tuple[Float[torch.Tensor, " n_edges"], Int[torch.Tensor, "n_edges 2"]]:
"""Compute weights for each edge based on mesh geometry.
For codimension-1 manifolds with n_manifold_dims >= 2: uses cotangent weights
Otherwise: uses uniform weights
Parameters
----------
mesh : Mesh
Input mesh
Returns
-------
tuple[torch.Tensor, torch.Tensor]
Tuple of (edge_weights, edges) where edge_weights has shape (n_edges,)
and edges has shape (n_edges, 2).
"""
device = mesh.points.device
dtype = mesh.points.dtype
if mesh.codimension == 1 and mesh.n_manifold_dims >= 2:
### Use cotangent weights (geometry-aware) via FEM stiffness matrix
weights, edges = compute_cotan_weights_fem(mesh)
### Clamp weights for numerical stability
# Negative cotangents occur for obtuse angles - treat as zero (no contribution)
# Very large cotangents occur for nearly degenerate triangles - cap for stability
weights = weights.clamp(min=0.0, max=10.0)
else:
### Use uniform weights for 1D manifolds or higher codimension
edges, _ = extract_unique_edges(mesh)
weights = torch.ones(len(edges), dtype=dtype, device=device)
return weights, edges
def _get_feature_vertices(
mesh: "Mesh",
edges: Int[torch.Tensor, "n_edges 2"],
feature_angle: float,
) -> Bool[torch.Tensor, " n_points"]:
"""Identify vertices on sharp feature edges.
Only applicable for codimension-1 manifolds where normals exist.
Parameters
----------
mesh : Mesh
Input mesh
edges : torch.Tensor
All unique edges, shape (n_edges, 2)
feature_angle : float
Dihedral angle threshold (degrees) for sharp features
Returns
-------
torch.Tensor
Boolean mask, shape (n_points,), True for feature vertices
"""
device = mesh.points.device
n_points = mesh.n_points
# Feature detection only works for codimension-1
if mesh.codimension != 1:
return torch.zeros(n_points, dtype=torch.bool, device=device)
# Detect sharp edges
sharp_edges = _detect_sharp_edges(mesh, edges, feature_angle) # (n_sharp_edges, 2)
if len(sharp_edges) == 0:
return torch.zeros(n_points, dtype=torch.bool, device=device)
# Mark all vertices in sharp edges
feature_mask = torch.zeros(n_points, dtype=torch.bool, device=device)
feature_mask[sharp_edges[:, 0]] = True
feature_mask[sharp_edges[:, 1]] = True
return feature_mask
def _detect_sharp_edges(
mesh: "Mesh",
edges: Int[torch.Tensor, "n_edges 2"],
feature_angle: float,
) -> Int[torch.Tensor, "n_sharp_edges 2"]:
"""Detect edges with dihedral angle exceeding threshold.
Fully vectorized implementation using :func:`find_edges_in_reference`
for O(n log n) edge matching and O(n) memory.
Parameters
----------
mesh : Mesh
Input mesh (must be codimension-1)
edges : torch.Tensor
All unique edges, shape (n_edges, 2)
feature_angle : float
Dihedral angle threshold in degrees
Returns
-------
torch.Tensor
Sharp edges, shape (n_sharp_edges, 2)
"""
from physicsnemo.mesh.utilities._edge_lookup import find_edges_in_reference
device = mesh.points.device
n_manifold_dims = mesh.n_manifold_dims
### Extract candidate edges with parent cell info
candidate_edges, parent_cell_indices = extract_candidate_facets(
mesh.cells,
manifold_codimension=n_manifold_dims - 1,
)
### Map candidate edges to unique edges via searchsorted (O(m log n), O(n) memory)
candidate_to_unique, matched = find_edges_in_reference(
edges,
candidate_edges,
index_bound=mesh.n_points,
)
### Count cells per edge (only matched candidates contribute)
edge_cell_counts = torch.bincount(
candidate_to_unique[matched], minlength=len(edges)
)
### Find interior edges (exactly 2 adjacent cells)
interior_edge_mask = edge_cell_counts == 2
if not torch.any(interior_edge_mask):
return torch.empty((0, 2), dtype=edges.dtype, device=device)
interior_edge_indices = torch.where(interior_edge_mask)[0]
### Collect the two adjacent cells per interior edge
# Sort matched candidates by their unique edge index; within each group of
# size 2, the first element becomes cell_a and the second becomes cell_b.
valid_mask = matched
valid_candidate_to_unique = candidate_to_unique[valid_mask]
valid_parent_cells = parent_cell_indices[valid_mask]
sorted_order = torch.argsort(valid_candidate_to_unique, stable=True)
sorted_edge_ids = valid_candidate_to_unique[sorted_order]
sorted_parent_cells = valid_parent_cells[sorted_order]
# Detect group boundaries (where the edge index changes)
# is_first: True at positions where the edge id differs from the predecessor
is_first_in_group = torch.cat(
[
torch.ones(1, dtype=torch.bool, device=device),
sorted_edge_ids[1:] != sorted_edge_ids[:-1],
]
)
# is_second: True at positions where the edge id equals the predecessor
is_second_in_group = torch.cat(
[
torch.zeros(1, dtype=torch.bool, device=device),
sorted_edge_ids[1:] == sorted_edge_ids[:-1],
]
)
# Build per-edge cell arrays (scatter first/second occurrence to edge index)
edge_first_cell = torch.full((len(edges),), -1, dtype=torch.long, device=device)
edge_second_cell = torch.full((len(edges),), -1, dtype=torch.long, device=device)
edge_first_cell.scatter_(
0, sorted_edge_ids[is_first_in_group], sorted_parent_cells[is_first_in_group]
)
edge_second_cell.scatter_(
0, sorted_edge_ids[is_second_in_group], sorted_parent_cells[is_second_in_group]
)
### Compute dihedral angles for interior edges (vectorized)
interior_first_cells = edge_first_cell[interior_edge_indices]
interior_second_cells = edge_second_cell[interior_edge_indices]
normals_first = mesh.cell_normals[
interior_first_cells
] # (n_interior, n_spatial_dims)
normals_second = mesh.cell_normals[
interior_second_cells
] # (n_interior, n_spatial_dims)
cos_angles = (normals_first * normals_second).sum(dim=-1)
cos_angles = cos_angles.clamp(-1.0, 1.0)
angles_deg = torch.acos(cos_angles) * (180.0 / torch.pi)
### Filter for sharp edges
sharp_mask = angles_deg > feature_angle
sharp_edge_indices = interior_edge_indices[sharp_mask]
if len(sharp_edge_indices) == 0:
return torch.empty((0, 2), dtype=edges.dtype, device=device)
return edges[sharp_edge_indices]