fluxfem 0.1.4__py3-none-any.whl → 0.2.0__py3-none-any.whl

fluxfem/mesh/supermesh.py

@@ -0,0 +1,316 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+import os
+from typing import Iterable
+
+import numpy as np
+
+from .surface import SurfaceMesh
+
+
+@dataclass(eq=False)
+class SurfaceSupermesh:
+    """Intersection supermesh for two surface meshes."""
+    coords: np.ndarray
+    conn: np.ndarray
+    source_facets_a: np.ndarray
+    source_facets_b: np.ndarray
+
+
+def _polygon_area_2d(pts: np.ndarray) -> float:
+    x = pts[:, 0]
+    y = pts[:, 1]
+    return 0.5 * float(np.sum(x * np.roll(y, -1) - y * np.roll(x, -1)))
+
+
+def _cross2(a: np.ndarray, b: np.ndarray) -> float:
+    return float(a[0] * b[1] - a[1] * b[0])
+
+
+def _line_intersection(p1, p2, p3, p4, *, tol: float):
+    d1 = p2 - p1
+    d2 = p4 - p3
+    denom = _cross2(d1, d2)
+    if abs(denom) < tol:
+        return p2
+    t = _cross2(p3 - p1, d2) / denom
+    return p1 + t * d1
+
+
+def _sutherland_hodgman(subject: list[np.ndarray], clip: list[np.ndarray], *, tol: float):
+    if not subject:
+        return []
+    orient = np.sign(_polygon_area_2d(np.array(clip)))
+    if orient == 0:
+        return []
+
+    def inside(pt, a, b):
+        return orient * _cross2(b - a, pt - a) >= -tol
+
+    output = subject
+    for i in range(len(clip)):
+        input_list = output
+        if not input_list:
+            break
+        output = []
+        cp1 = clip[i]
+        cp2 = clip[(i + 1) % len(clip)]
+        s = input_list[-1]
+        for e in input_list:
+            if inside(e, cp1, cp2):
+                if not inside(s, cp1, cp2):
+                    output.append(_line_intersection(s, e, cp1, cp2, tol=tol))
+                output.append(e)
+            elif inside(s, cp1, cp2):
+                output.append(_line_intersection(s, e, cp1, cp2, tol=tol))
+            s = e
+    return output
+
+
+def _plane_basis(normal: np.ndarray):
+    n = normal / np.linalg.norm(normal)
+    ref = np.array([1.0, 0.0, 0.0], dtype=float)
+    if abs(np.dot(n, ref)) > 0.9:
+        ref = np.array([0.0, 1.0, 0.0], dtype=float)
+    t1 = np.cross(n, ref)
+    t1 = t1 / np.linalg.norm(t1)
+    t2 = np.cross(n, t1)
+    return t1, t2, n
+
+
+def _facet_plane(pts: np.ndarray, *, tol: float):
+    n = None
+    for i in range(len(pts) - 2):
+        v1 = pts[i + 1] - pts[i]
+        v2 = pts[i + 2] - pts[i]
+        n_candidate = np.cross(v1, v2)
+        n_norm = np.linalg.norm(n_candidate)
+        if n_norm > tol:
+            n = n_candidate / n_norm
+            d = -float(np.dot(n, pts[i]))
+            return n, d
+    return None, None
+
+
+def _coplanar(pts_a: np.ndarray, pts_b: np.ndarray, *, tol: float) -> bool:
+    n, d = _facet_plane(pts_a, tol=tol)
+    if n is None:
+        return False
+    n2, d2 = _facet_plane(pts_b, tol=tol)
+    if n2 is None:
+        return False
+    if abs(abs(np.dot(n, n2)) - 1.0) > 1e-4:
+        return False
+    dist_a = np.abs(pts_a @ n + d)
+    dist_b = np.abs(pts_b @ n + d)
+    return np.max(dist_a) <= tol and np.max(dist_b) <= tol
+
+
+def _project(points: np.ndarray, origin: np.ndarray, t1: np.ndarray, t2: np.ndarray):
+    rel = points - origin[None, :]
+    x = rel @ t1
+    y = rel @ t2
+    return np.stack([x, y], axis=1)
+
+
+def _unique_points(points: Iterable[np.ndarray], *, tol: float):
+    scale = 1.0 / tol
+    mapping: dict[tuple[int, int, int], int] = {}
+    coords: list[np.ndarray] = []
+    indices: list[int] = []
+    for p in points:
+        key = tuple(np.round(p * scale).astype(int))
+        idx = mapping.get(key)
+        if idx is None:
+            idx = len(coords)
+            mapping[key] = idx
+            coords.append(p)
+        indices.append(idx)
+    return np.asarray(coords, dtype=float), indices
+
+
+def _facet_polygon_coords(coords: np.ndarray, facet: np.ndarray) -> np.ndarray:
+    n = int(len(facet))
+    if n == 9:
+        corner = [0, 2, 8, 6]
+        return coords[facet][corner]
+    return coords[facet]
+
+
+def _triangle_min_angle(p0: np.ndarray, p1: np.ndarray, p2: np.ndarray) -> float:
+    def angle(a, b, c):
+        v1 = a - b
+        v2 = c - b
+        n1 = np.linalg.norm(v1)
+        n2 = np.linalg.norm(v2)
+        if n1 == 0.0 or n2 == 0.0:
+            return 0.0
+        cosang = np.clip(np.dot(v1, v2) / (n1 * n2), -1.0, 1.0)
+        return float(np.arccos(cosang))
+
+    return min(angle(p1, p0, p2), angle(p0, p1, p2), angle(p0, p2, p1))
+
+
+def _triangulate_polygon(indices: list[int], poly2d: np.ndarray) -> list[tuple[int, int, int]]:
+    n = len(indices)
+    if n < 3:
+        return []
+    if n == 3:
+        return [(indices[0], indices[1], indices[2])]
+    if n == 4:
+        p = poly2d
+        diag_pref = os.getenv("FLUXFEM_SUPERMESH_QUAD_DIAG", "alt").lower()
+        if diag_pref == "alt":
+            return [(indices[0], indices[1], indices[3]), (indices[1], indices[2], indices[3])]
+        if diag_pref == "fan":
+            return [(indices[0], indices[1], indices[2]), (indices[0], indices[2], indices[3])]
+        min_a = min(
+            _triangle_min_angle(p[0], p[1], p[2]),
+            _triangle_min_angle(p[0], p[2], p[3]),
+        )
+        min_b = min(
+            _triangle_min_angle(p[0], p[1], p[3]),
+            _triangle_min_angle(p[1], p[2], p[3]),
+        )
+        if min_b > min_a:
+            return [(indices[0], indices[1], indices[3]), (indices[1], indices[2], indices[3])]
+        return [(indices[0], indices[1], indices[2]), (indices[0], indices[2], indices[3])]
+    tris = []
+    for i in range(1, n - 1):
+        tris.append((indices[0], indices[i], indices[i + 1]))
+    return tris
+
+
+def build_surface_supermesh(
+    surface_a: SurfaceMesh,
+    surface_b: SurfaceMesh,
+    *,
+    tol: float = 1e-8,
+    cache_enabled: bool | None = None,
+    cache_trace: bool | None = None,
+) -> SurfaceSupermesh:
+    from ..solver.bc import facet_normals
+    import hashlib
+
+    if cache_enabled is None:
+        cache_enabled = os.getenv("FLUXFEM_SUPERMESH_CACHE", "0") not in ("0", "", "false", "False")
+    if cache_trace is None:
+        cache_trace = os.getenv("FLUXFEM_SUPERMESH_CACHE_TRACE", "0") not in ("0", "", "false", "False")
+
+    def _array_sig(arr: np.ndarray) -> tuple:
+        arr_c = np.ascontiguousarray(arr)
+        h = hashlib.blake2b(arr_c.view(np.uint8), digest_size=8).hexdigest()
+        return (arr_c.shape, str(arr_c.dtype), h)
+    if cache_enabled:
+        global _SUPERMESH_CACHE
+        try:
+            _SUPERMESH_CACHE
+        except NameError:
+            _SUPERMESH_CACHE = {}
+        key = (
+            _array_sig(np.asarray(surface_a.coords)),
+            _array_sig(np.asarray(surface_a.conn)),
+            _array_sig(np.asarray(surface_b.coords)),
+            _array_sig(np.asarray(surface_b.conn)),
+            float(tol),
+        )
+        cached = _SUPERMESH_CACHE.get(key)
+        if cached is not None:
+            if cache_trace:
+                print(f"[supermesh] cache hit n_tris={int(cached.conn.shape[0])}", flush=True)
+            return cached
+
+    coords_a = np.asarray(surface_a.coords, dtype=float)
+    coords_b = np.asarray(surface_b.coords, dtype=float)
+    facets_a = np.asarray(surface_a.conn, dtype=int)
+    facets_b = np.asarray(surface_b.conn, dtype=int)
+    normals_a = facet_normals(surface_a, outward_from=np.mean(coords_a, axis=0), normalize=True)
+
+    all_coords: list[np.ndarray] = []
+    all_conn: list[tuple[int, int, int]] = []
+    src_a: list[int] = []
+    src_b: list[int] = []
+
+    for ia, fa in enumerate(facets_a):
+        pts_a = _facet_polygon_coords(coords_a, fa)
+        min_a = pts_a.min(axis=0)
+        max_a = pts_a.max(axis=0)
+        for ib, fb in enumerate(facets_b):
+            pts_b = _facet_polygon_coords(coords_b, fb)
+            if np.any(pts_b.max(axis=0) < min_a - tol) or np.any(pts_b.min(axis=0) > max_a + tol):
+                continue
+            if not _coplanar(pts_a, pts_b, tol=tol):
+                continue
+
+            n, _d = _facet_plane(pts_a, tol=tol)
+            if n is not None:
+                n_ref = normals_a[int(ia)]
+                if np.dot(n, n_ref) < 0.0:
+                    n = -n
+            t1, t2, _ = _plane_basis(n)
+            origin = pts_a[0]
+
+            poly_a = _project(pts_a, origin, t1, t2)
+            poly_b = _project(pts_b, origin, t1, t2)
+
+            inter = _sutherland_hodgman(
+                [p.copy() for p in poly_a],
+                [p.copy() for p in poly_b],
+                tol=tol,
+            )
+            if len(inter) < 3:
+                continue
+            inter_np = np.asarray(inter)
+            if abs(_polygon_area_2d(inter_np)) <= tol:
+                continue
+            center = np.mean(inter_np, axis=0)
+            angles = np.arctan2(inter_np[:, 1] - center[1], inter_np[:, 0] - center[0])
+            order = np.argsort(angles)
+            inter_np = inter_np[order]
+
+            inter_3d = origin[None, :] + inter_np[:, 0:1] * t1 + inter_np[:, 1:2] * t2
+            coords_local, idx = _unique_points(inter_3d, tol=tol)
+            base = len(all_coords)
+            for p in coords_local:
+                all_coords.append(p)
+            tris = _triangulate_polygon(idx, inter_np)
+            for a_idx, b_idx, c_idx in tris:
+                a_id = base + a_idx
+                b_id = base + b_idx
+                c_id = base + c_idx
+                if n is not None:
+                    pa = all_coords[a_id]
+                    pb = all_coords[b_id]
+                    pc = all_coords[c_id]
+                    n_tri = np.cross(pb - pa, pc - pa)
+                    if np.dot(n_tri, n) < 0.0:
+                        b_id, c_id = c_id, b_id
+                all_conn.append((a_id, b_id, c_id))
+                src_a.append(ia)
+                src_b.append(ib)
+
+    if not all_conn:
+        sm = SurfaceSupermesh(
+            coords=np.zeros((0, 3), dtype=float),
+            conn=np.zeros((0, 3), dtype=int),
+            source_facets_a=np.zeros((0,), dtype=int),
+            source_facets_b=np.zeros((0,), dtype=int),
+        )
+        if cache_enabled:
+            _SUPERMESH_CACHE[key] = sm
+        return sm
+
+    coords = np.asarray(all_coords, dtype=float)
+    conn = np.asarray(all_conn, dtype=int)
+    sm = SurfaceSupermesh(
+        coords=coords,
+        conn=conn,
+        source_facets_a=np.asarray(src_a, dtype=int),
+        source_facets_b=np.asarray(src_b, dtype=int),
+    )
+    if cache_enabled:
+        _SUPERMESH_CACHE[key] = sm
+        if cache_trace:
+            print(f"[supermesh] cache store n_tris={int(sm.conn.shape[0])}", flush=True)
+    return sm

fluxfem/mesh/surface.py

@@ -4,6 +4,8 @@ from dataclasses import dataclass
 from typing import Optional
 import jax
 import jax.numpy as jnp
+
+from .dtypes import INDEX_DTYPE
 import numpy as np
 
 DTYPE = jnp.float64 if jax.config.read("jax_enable_x64") else jnp.float32
@@ -53,8 +55,8 @@ class SurfaceMesh(BaseMesh):
         node_tags: Optional[jnp.ndarray] = None,
     ) -> "SurfaceMesh":
         coords_j = jnp.asarray(coords, dtype=DTYPE)
-        facets_j = jnp.asarray(facets, dtype=jnp.int32)
-        tags_j = None if facet_tags is None else jnp.asarray(facet_tags, dtype=jnp.int32)
+        facets_j = jnp.asarray(facets, dtype=INDEX_DTYPE)
+        tags_j = None if facet_tags is None else jnp.asarray(facet_tags, dtype=INDEX_DTYPE)
         node_tags_j = None if node_tags is None else jnp.asarray(node_tags)
         return cls(coords=coords_j, conn=facets_j, cell_tags=tags_j, node_tags=node_tags_j, facet_tags=tags_j)
 
@@ -117,6 +119,22 @@ class SurfaceMesh(BaseMesh):
         n_total_nodes = int(getattr(space, "mesh", self).n_nodes)
         return self.assemble_linear_form(form, params, dim=dim, n_total_nodes=n_total_nodes, F0=F0)
 
+
+@dataclass(frozen=True)
+class SurfaceWithElemConn:
+    surface: SurfaceMesh
+    elem_conn: np.ndarray
+
+
+def surface_with_elem_conn(mesh: BaseMesh, facets, *, mode: str = "touching") -> SurfaceWithElemConn:
+    """
+    Build a SurfaceMesh from facets and return it with a matching elem_conn array.
+    """
+    surface = SurfaceMesh.from_facets(mesh.coords, facets, node_tags=mesh.node_tags)
+    elems = mesh.elements_from_facets(facets, mode=mode)
+    elem_conn = np.asarray(mesh.conn, dtype=int)[elems]
+    return SurfaceWithElemConn(surface=surface, elem_conn=elem_conn)
+
     def assemble_traction(
         self,
         traction,
@@ -162,8 +180,8 @@ class SurfaceMeshPytree(BaseMeshPytree):
         node_tags: Optional[jnp.ndarray] = None,
     ) -> "SurfaceMeshPytree":
         coords_j = jnp.asarray(coords, dtype=DTYPE)
-        facets_j = jnp.asarray(facets, dtype=jnp.int32)
-        tags_j = None if facet_tags is None else jnp.asarray(facet_tags, dtype=jnp.int32)
+        facets_j = jnp.asarray(facets, dtype=INDEX_DTYPE)
+        tags_j = None if facet_tags is None else jnp.asarray(facet_tags, dtype=INDEX_DTYPE)
         node_tags_j = None if node_tags is None else jnp.asarray(node_tags)
         return cls(coords=coords_j, conn=facets_j, cell_tags=tags_j, node_tags=node_tags_j, facet_tags=tags_j)
 

fluxfem/mesh/tet.py

@@ -5,6 +5,8 @@ import jax
 import jax.numpy as jnp
 import numpy as np
 
+from .dtypes import NP_INDEX_DTYPE
+
 DTYPE = jnp.float64 if jax.config.read("jax_enable_x64") else jnp.float32
 
 
@@ -58,6 +60,10 @@ class StructuredTetBox:
             J = np.stack([p1 - p0, p2 - p0, p3 - p0], axis=1)
             if np.linalg.det(J) < 0:
                 tet[[1, 2]] = tet[[2, 1]]  # swap corner1/corner2
+                if tet.shape[0] == 10:
+                    # keep edge-node ordering consistent with corner swap
+                    tet[[4, 6]] = tet[[6, 4]]  # edges (0-1) <-> (0-2)
+                    tet[[8, 9]] = tet[[9, 8]]  # edges (1-3) <-> (2-3)
                 conn[idx] = tet
         return conn
 
@@ -115,10 +121,10 @@ class StructuredTetBox:
                         n12 = add_node(mid(p1, p2))
                         n13 = add_node(mid(p1, p3))
                         n23 = add_node(mid(p2, p3))
-                        conn_list.append([n0, n1, n2, n3, n01, n02, n03, n12, n13, n23])
+                        conn_list.append([n0, n1, n2, n3, n01, n12, n02, n03, n13, n23])
 
         coords = np.asarray(coords_list, dtype=DTYPE)
-        conn = np.asarray(conn_list, dtype=np.int32)
+        conn = np.asarray(conn_list, dtype=NP_INDEX_DTYPE)
         conn = self._fix_orientation(coords, conn)
         return TetMesh(coords=jnp.array(coords), conn=jnp.array(conn))
 
@@ -169,7 +175,7 @@ class StructuredTetBox:
                             [v010, v001, v011, v111],
                         ]
                     )
-        conn = np.asarray(conn_list, dtype=np.int32)
+        conn = np.asarray(conn_list, dtype=NP_INDEX_DTYPE)
         conn = self._fix_orientation(coords, conn)
         return TetMesh(coords=jnp.array(coords), conn=jnp.array(conn))
 
@@ -241,6 +247,6 @@ class StructuredTetTensorBox:
         T[:, (5 * ne):] = t[[0, 3, 6, 7]]
 
         coords = p.T.astype(DTYPE, copy=False)
-        conn = T.T.astype(np.int32, copy=False)
+        conn = T.T.astype(NP_INDEX_DTYPE, copy=False)
         conn = self._fix_orientation(coords, conn)
         return TetMesh(coords=jnp.array(coords), conn=jnp.array(conn))

fluxfem/physics/diffusion.py

@@ -15,4 +15,7 @@ def diffusion_form(ctx: FormContext, kappa: float) -> jnp.ndarray:
     return kappa * G
 
 
+diffusion_form._ff_kind = "bilinear"
+diffusion_form._ff_domain = "volume"
+
 __all__ = ["diffusion_form"]

fluxfem/physics/elasticity/hyperelastic.py

@@ -78,6 +78,9 @@ def neo_hookean_residual_form(ctx: FormContext, u_elem: jnp.ndarray, params) ->
     return jnp.einsum("qik,qk->qi", BT, S_voigt)   # (n_q, n_ldofs)
 
 
+neo_hookean_residual_form._ff_kind = "residual"
+neo_hookean_residual_form._ff_domain = "volume"
+
 __all__ = [
     "right_cauchy_green",
     "green_lagrange_strain",

fluxfem/physics/elasticity/linear.py

@@ -1,6 +1,5 @@
 import jax.numpy as jnp
 
-from ...core.assembly import assemble_linear_form
 from ...core.forms import FormContext, vector_load_form
 from ...core.basis import build_B_matrices
 from ...physics.operators import sym_grad
@@ -26,21 +25,29 @@ def linear_elasticity_form(ctx: FormContext, D: jnp.ndarray) -> jnp.ndarray:
     symmetric-gradient operator for the test/trial fields.
     """
     Bu = sym_grad(ctx.trial)                 # (n_q, 6, ndofs_e)
-    Bv = sym_grad(ctx.test)                  # (n_q, 6, ndofs_e)
+    Bv = Bu if ctx.test is ctx.trial else sym_grad(ctx.test)
     return jnp.einsum("qik,kl,qlm->qim", jnp.swapaxes(Bv, 1, 2), D, Bu)
 
 
+linear_elasticity_form._ff_kind = "bilinear"
+linear_elasticity_form._ff_domain = "volume"
+
+
 def vector_body_force_form(ctx: FormContext, load_vec: jnp.ndarray) -> jnp.ndarray:
     """Linear form for 3D vector body force f (constant in space)."""
     return vector_load_form(ctx.test, load_vec)
 
 
+vector_body_force_form._ff_kind = "linear"
+vector_body_force_form._ff_domain = "volume"
+
 def assemble_constant_body_force(space, gravity_vec, density: float, *, sparse: bool = False):
     """
     Convenience: assemble body force from density * gravity vector.
     gravity_vec: length-3 array-like (direction and magnitude of g)
     density: scalar density (consistent with unit system)
     """
+    from ...core.assembly import assemble_linear_form
     g = jnp.asarray(gravity_vec)
     f_vec = density * g
     return assemble_linear_form(space, vector_body_force_form, params=f_vec, sparse=sparse)

fluxfem/solver/__init__.py

@@ -1,13 +1,30 @@
-from .sparse import SparsityPattern, FluxSparseMatrix
+from .sparse import (
+    SparsityPattern,
+    FluxSparseMatrix,
+    coalesce_coo,
+    concat_flux,
+    block_diag_flux,
+)
 from .dirichlet import (
+    DirichletBC,
     enforce_dirichlet_dense,
+    enforce_dirichlet_dense_jax,
+    enforce_dirichlet_fluxsparse,
     enforce_dirichlet_sparse,
     free_dofs,
+    split_dirichlet_matrix,
+    restrict_flux_to_free,
+    condense_dirichlet_system,
+    enforce_dirichlet_system,
     condense_dirichlet_fluxsparse,
+    condense_dirichlet_fluxsparse_coo,
     condense_dirichlet_dense,
     expand_dirichlet_solution,
 )
-from .cg import cg_solve, cg_solve_jax
+from .cg import cg_solve, cg_solve_jax, build_cg_operator, CGOperator
+from .preconditioner import make_block_jacobi_preconditioner
+from .block_system import build_block_system, split_block_matrix, BlockSystem
+from .block_matrix import diag as block_diag, make as make_block_matrix
 from .newton import newton_solve
 from .solve_runner import (
     NonlinearAnalysis,
@@ -21,18 +38,38 @@ from .solve_runner import (
     LinearSolveRunner,
 )
 from .solver import LinearSolver, NonlinearSolver
+from .petsc import petsc_solve, petsc_shell_solve, petsc_is_available
 
 __all__ = [
     "SparsityPattern",
     "FluxSparseMatrix",
+    "coalesce_coo",
+    "concat_flux",
+    "block_diag_flux",
+    "DirichletBC",
     "enforce_dirichlet_dense",
+    "enforce_dirichlet_dense_jax",
+    "enforce_dirichlet_fluxsparse",
     "enforce_dirichlet_sparse",
+    "split_dirichlet_matrix",
+    "enforce_dirichlet_system",
     "free_dofs",
+    "restrict_flux_to_free",
+    "condense_dirichlet_system",
     "condense_dirichlet_fluxsparse",
+    "condense_dirichlet_fluxsparse_coo",
     "condense_dirichlet_dense",
     "expand_dirichlet_solution",
     "cg_solve",
     "cg_solve_jax",
+    "build_cg_operator",
+    "CGOperator",
+    "make_block_jacobi_preconditioner",
+    "build_block_system",
+    "split_block_matrix",
+    "BlockSystem",
+    "block_diag",
+    "make_block_matrix",
     "newton_solve",
     "LinearAnalysis",
     "LinearSolveConfig",
@@ -44,4 +81,7 @@ __all__ = [
     "solve_nonlinear",
     "LinearSolver",
     "NonlinearSolver",
+    "petsc_solve",
+    "petsc_shell_solve",
+    "petsc_is_available",
 ]

fluxfem/solver/bc.py

@@ -107,6 +107,10 @@ def vector_surface_load_form(ctx: SurfaceFormContext, load: npt.ArrayLike) -> np
     return np.asarray(vector_load_form(ctx.v, load_arr))
 
 
+vector_surface_load_form._ff_kind = "linear"
+vector_surface_load_form._ff_domain = "surface"
+
+
 def make_vector_surface_load_form(load_fn):
     """
     Build a vector surface load form from a callable f(x_q) -> (n_q, dim).
@@ -115,9 +119,32 @@ def make_vector_surface_load_form(load_fn):
         load_q = load_fn(ctx.x_q)
         return vector_surface_load_form(ctx, load_q)
 
+    _form._ff_kind = "linear"
+    _form._ff_domain = "surface"
     return _form
 
 
+def traction_vector(traction, traction_dir: str) -> np.ndarray:
+    """
+    Resolve traction magnitude and direction string into a vector.
+    """
+    dir_map = {
+        "x": (1.0, 0.0, 0.0),
+        "xpos": (1.0, 0.0, 0.0),
+        "xneg": (-1.0, 0.0, 0.0),
+        "y": (0.0, 1.0, 0.0),
+        "ypos": (0.0, 1.0, 0.0),
+        "yneg": (0.0, -1.0, 0.0),
+        "z": (0.0, 0.0, 1.0),
+        "zpos": (0.0, 0.0, 1.0),
+        "zneg": (0.0, 0.0, -1.0),
+    }
+    key = traction_dir.strip().lower()
+    if key not in dir_map:
+        raise ValueError("TRACTION_DIR must be one of x/xpos/xneg/y/ypos/yneg/z/zpos/zneg")
+    return float(traction) * np.asarray(dir_map[key], dtype=float)
+
+
 def _surface_quadrature(node_coords: np.ndarray):
     m = node_coords.shape[0]
     if m == 4:
@@ -404,8 +431,17 @@ def facet_normals(surface: SurfaceMesh, *, outward_from: npt.ArrayLike | None =
     for i, facet in enumerate(facets):
         if len(facet) < 3:
             continue
-        p0, p1, p2 = coords[facet[0]], coords[facet[1]], coords[facet[2]]
-        n = np.cross(p1 - p0, p2 - p0)
+        n = None
+        p0 = coords[facet[0]]
+        for j in range(1, len(facet) - 1):
+            p1 = coords[facet[j]]
+            p2 = coords[facet[j + 1]]
+            n_candidate = np.cross(p1 - p0, p2 - p0)
+            if np.linalg.norm(n_candidate) > 0.0:
+                n = n_candidate
+                break
+        if n is None:
+            continue
         if normalize:
             norm = np.linalg.norm(n)
             n = n / norm if norm != 0.0 else n