Metrics¶

Create an isotropic metric field from scalar sizing values.

Parameters¶

h : float or array_like Desired element size(s). If scalar, same size at all vertices. If array, must have shape (n_vertices,) or (n_vertices, 1). n_vertices : int, optional Number of vertices. Required if h is a scalar. dim : int, optional Mesh dimension (2 or 3). Default is 3.

Returns¶

NDArray[np.float64] Metric tensor array with shape (n_vertices, n_components) where n_components is 6 for 3D and 3 for 2D.

Raises¶

ValueError If dim is not 2 or 3, n_vertices is missing when h is a scalar, or h does not flatten to a 1D array.

Examples¶

metric = create_isotropic_metric(0.1, n_vertices=100, dim=3) metric.shape (100, 6)

sizes = np.linspace(0.1, 0.5, 100) metric = create_isotropic_metric(sizes, dim=3) metric.shape (100, 6)

Create an anisotropic metric tensor from principal sizes and directions.

The metric tensor M is constructed as: M = R @ D @ R.T where D is diagonal with D[i,i] = 1/sizes[i]^2 and R contains the principal direction vectors as columns.

Parameters¶

sizes : array_like Principal element sizes. Shape (3,) for 3D, (2,) for 2D. Can also be (n_vertices, 3) or (n_vertices, 2) for per-vertex sizes. directions : array_like, optional Principal direction vectors. Shape (3, 3) or (2, 2) for single metric, or (n_vertices, 3, 3) or (n_vertices, 2, 2) for per-vertex directions. Columns are eigenvectors. If None, uses identity (coordinate-aligned).

Returns¶

NDArray[np.float64] Metric tensor(s). Shape (6,) for single 3D metric, (3,) for single 2D, or (n_vertices, 6) / (n_vertices, 3) for per-vertex metrics.

Raises¶

ValueError If sizes is not 1D / 2D, the dimension is not 2 or 3, or directions does not match the expected shape.

Examples¶

Create a metric with 10x stretch in x-direction:

sizes = np.array([0.1, 1.0, 1.0]) # Small in x, large in y,z metric = create_anisotropic_metric(sizes) metric array([100., 0., 0., 1., 0., 1.])

Create a rotated metric:

import numpy as np theta = np.pi / 4 # 45 degrees R = np.array([[np.cos(theta), -np.sin(theta), 0], ... [np.sin(theta), np.cos(theta), 0], ... [0, 0, 1]]) sizes = np.array([0.1, 1.0, 1.0]) metric = create_anisotropic_metric(sizes, R)

Create metric tensor from Hessian matrix for interpolation error control.

Given a Hessian H of a solution field, constructs a metric M such that the interpolation error is bounded by target_error. This is used for solution-adaptive mesh refinement.

The metric eigenvalues are: lambda_i = c * |hessian_eigenvalue_i| / target_error where c is a constant depending on the interpolation order.

Parameters¶

hessian : array_like Hessian tensor(s). Shape (6,) or (n, 6) for 3D, (3,) or (n, 3) for 2D. Components: [H11, H12, H13, H22, H23, H33] for 3D. target_error : float, optional Target interpolation error. Default is 1e-3. hmin : float, optional Minimum element size. Limits maximum metric eigenvalues. hmax : float, optional Maximum element size. Limits minimum metric eigenvalues.

Returns¶

NDArray[np.float64] Metric tensor(s) for adaptive remeshing.

Notes¶

For P1 interpolation, the interpolation error is bounded by: e <= (1/8) * h^2 * |d²u/ds²|_max

This function computes the metric that achieves a specified error bound.

Compute the Hessian of a scalar field on a mesh via least-squares recovery.

Uses a patch-based least-squares approach: for each vertex, a quadratic polynomial is fitted to the field values at neighboring vertices, and the second-order coefficients give the Hessian components.

This is the missing piece for solution-adaptive remeshing: compute a solution field with your FE solver, pass it here to get the Hessian, then use :func:create_metric_from_hessian to build an adaptation metric.

Parameters¶

vertices : ndarray Nx2 or Nx3 array of vertex coordinates. elements : ndarray Mx(nodes_per_element) array of element connectivity. field : ndarray N array of scalar field values at vertices.

Returns¶

ndarray Hessian tensor array. Shape (N, 3) for 2D [H11, H12, H22] or (N, 6) for 3D [H11, H12, H13, H22, H23, H33].

Raises¶

ValueError If field does not have one value per vertex.

Compute the intersection of two metric tensors.

The intersection produces a metric that is at least as refined as both input metrics in all directions. This is useful for combining metrics from different sources (e.g., boundary layer + feature-based).

The intersection is computed via simultaneous diagonalization: M_intersect = M1^(1/2) @ N @ M1^(1/2) where N is diagonal with max eigenvalues of M1^(-1/2) @ M2 @ M1^(-1/2).

Parameters¶

m1, m2 : array_like Metric tensors to intersect. Must have same shape. Shape (6,) or (n, 6) for 3D, (3,) or (n, 3) for 2D. dim : int, optional Dimension (2 or 3). Inferred from tensor shape if not provided.

Returns¶

NDArray[np.float64] Intersected metric tensor(s), same shape as inputs.

Raises¶

ValueError If m1 and m2 do not share the same shape.

Extract principal sizes and directions from metric tensor(s).

Parameters¶

tensor : array_like Metric tensor(s). Shape (6,) or (n, 6) for 3D, (3,) or (n, 3) for 2D. dim : int, optional Dimension (2 or 3). Inferred from tensor shape if not provided.

Returns¶

tuple[NDArray, NDArray] (sizes, directions) where: - sizes: Principal element sizes, shape (3,) or (n, 3) for 3D - directions: Eigenvector matrices, shape (3, 3) or (n, 3, 3) for 3D Columns are eigenvectors corresponding to sizes.

Examples¶

tensor = np.array([100., 0., 0., 1., 0., 1.]) # 10x stretch in x sizes, directions = compute_metric_eigenpairs(tensor) sizes array([0.1, 1. , 1. ])

Convert tensor storage format to full symmetric matrix.

Parameters¶

tensor : array_like Tensor in storage format. Shape (6,) or (n, 6) for 3D, (3,) or (n, 3) for 2D. dim : int, optional Dimension (2 or 3). Inferred from tensor shape if not provided.

Returns¶

NDArray[np.float64] Full symmetric matrix. Shape (3, 3) or (n, 3, 3) for 3D, (2, 2) or (n, 2, 2) for 2D.

Convert full symmetric matrix to tensor storage format.

Parameters¶

matrix : array_like Full symmetric matrix. Shape (3, 3) or (n, 3, 3) for 3D, (2, 2) or (n, 2, 2) for 2D.

Returns¶

NDArray[np.float64] Tensor in storage format. Shape (6,) or (n, 6) for 3D, (3,) or (n, 3) for 2D.

Validate that metric tensor(s) are positive-definite.

A valid metric tensor must be symmetric positive-definite, meaning all eigenvalues must be strictly positive.

Parameters¶

tensor : array_like Tensor(s) to validate. Shape (6,) or (n, 6) for 3D, (3,) or (n, 3) for 2D. dim : int, optional Dimension (2 or 3). Inferred from tensor shape if not provided. raise_on_invalid : bool, optional If True, raises ValueError on invalid tensors. Default is True.

Returns¶

tuple[bool, str] (is_valid, message) tuple.

Raises¶

ValueError If raise_on_invalid is True and tensor is not valid.

Examples¶

valid_tensor = np.array([1.0, 0.0, 0.0, 1.0, 0.0, 1.0]) validate_metric_tensor(valid_tensor) (True, 'Valid positive-definite metric tensor')

invalid_tensor = np.array([-1.0, 0.0, 0.0, 1.0, 0.0, 1.0]) validate_metric_tensor(invalid_tensor, raise_on_invalid=False) (False, 'Tensor has non-positive eigenvalues...')