API: Types

CurveMesh{T}

Closed or open 2-D polygonal curve.

CurveMesh{T <: AbstractFloat}
  points :: Vector{SVector{2,T}}    # vertex coordinates (2-D)
  edges  :: Vector{Tuple{Int,Int}}  # ordered edge list
  closed :: Bool                    # whether the last edge closes to vertex 1

Constructor: Load from file or build analytically via sample_circle.

SurfaceMesh{T}

Triangulated surface in $\mathbb{R}^3$.

SurfaceMesh{T <: AbstractFloat}
  points :: Vector{SVector{3,T}}          # vertex positions
  faces  :: Vector{Tuple{Int,Int,Int}}    # triangle indices (1-based)

PointFront1D{T}

Minimal 1-D front on a line (standalone from mesh/DEC machinery).

PointFront1D{T <: Real}
  x                  :: Vector{T}  # marker positions (length 1 or 2)
  interval_is_inside :: Bool

Semantics:

• length(x) == 1:
  • interval_is_inside=true: inside is to the right (x >= xΓ)
  • interval_is_inside=false: inside is to the left (x <= xΓ)
• length(x) == 2 with strict ordering x[1] < x[2]:
  • interval_is_inside=true: inside is [x[1], x[2]]
  • interval_is_inside=false: inside is the exterior of [x[1], x[2]]

Invariants are validated at construction (1 or 2 markers only, finite coordinates, strict ordering for two markers).

CurveGeometry{T}

Pre-computed intrinsic geometry of a CurveMesh.

CurveGeometry{T}
  edge_lengths         :: Vector{T}
  edge_tangents        :: Vector{SVector{2,T}}
  vertex_dual_lengths  :: Vector{T}
  vertex_normals       :: Vector{SVector{2,T}}
  signed_curvature     :: Vector{T}

Build with compute_geometry(mesh::CurveMesh).

SurfaceGeometry{T}

Pre-computed intrinsic geometry of a SurfaceMesh.

SurfaceGeometry{T}
  face_normals          :: Vector{SVector{3,T}}
  face_areas            :: Vector{T}
  edge_lengths          :: Vector{T}
  vertex_dual_areas     :: Vector{T}
  vertex_normals        :: Vector{SVector{3,T}}
  mean_curvature        :: Vector{T}      # filled by compute_curvature!
  gaussian_curvature    :: Vector{T}      # filled by compute_curvature!
  dual_area_method      :: Symbol         # :barycentric or :mixed

Build with compute_geometry(mesh::SurfaceMesh; dual_area=:barycentric).

CurveDEC{T}

Assembled DEC operators for a CurveMesh.

CurveDEC{T}
  d0         :: SparseMatrixCSC   # N_E × N_V  coboundary
  star0      :: SparseMatrixCSC   # N_V × N_V  diagonal (dual lengths)
  star1      :: SparseMatrixCSC   # N_E × N_E  diagonal (edge/dual-length ratio)
  laplacian  :: SparseMatrixCSC   # N_V × N_V  Laplace–Beltrami (= -Δ)

Build with build_dec(mesh::CurveMesh, geom::CurveGeometry).

SurfaceDEC{T}

Assembled DEC operators for a SurfaceMesh.

SurfaceDEC{T}
  d0         :: SparseMatrixCSC   # N_E × N_V
  d1         :: SparseMatrixCSC   # N_F × N_E
  star0      :: SparseMatrixCSC   # N_V × N_V  diagonal (dual areas)
  star1      :: SparseMatrixCSC   # N_E × N_E  diagonal (cotan weights)
  star2      :: SparseMatrixCSC   # N_F × N_F  diagonal (inverse face areas)
  laplacian  :: SparseMatrixCSC   # N_V × N_V  Laplace–Beltrami

Build with build_dec(mesh::SurfaceMesh, geom::SurfaceGeometry; laplace=:dec).

MeshTopology

Topological adjacency lists derived from a SurfaceMesh.

MeshTopology
  edges            :: Vector{Tuple{Int,Int}}    # canonical (i<j) edge list
  edge_index       :: Dict{Tuple{Int,Int},Int}  # fast lookup
  face_edges       :: Vector{Vector{Int}}       # face → 3 edge indices
  face_edge_signs  :: Vector{Vector{Int}}       # ±1 orientation signs
  vertex_faces     :: Vector{Vector{Int}}       # vertex → adjacent faces
  vertex_edges     :: Vector{Vector{Int}}       # vertex → adjacent edges
  edge_faces       :: Vector{Vector{Int}}       # edge → 1 or 2 faces

Build with build_topology(mesh::SurfaceMesh).

SurfacePDECache{T}

Pre-assembled PDE operators and factorizations for fast repeated solves.

SurfacePDECache{T}
  dec          :: SurfaceDEC
  mass         :: SparseMatrixCSC   # M = star0
  laplacian    :: SparseMatrixCSC   # L
  system       :: SparseMatrixCSC   # (M + dt θ μ L)
  factorization                     # sparse LU or Cholesky
  μ            :: T
  dt           :: T
  θ            :: T

Build with build_pde_cache(mesh, geom, dec; μ, dt, θ).

SurfaceDiffusionBuffers{T} and SurfaceRDBuffers{T}

Pre-allocated scratch buffers for zero-allocation time steps.

SurfaceDiffusionBuffers{T}
  rhs :: Vector{T}
  tmp :: Vector{T}

SurfaceRDBuffers{T}
  rhs      :: Vector{T}
  reaction :: Vector{T}
  tmp      :: Vector{T}

Build with alloc_diffusion_buffers(nv) or alloc_rd_buffers(nv).

FEEC types (v0.6)

Whitney0Space, Whitney1Space, Whitney2Space

Lightweight descriptors for lowest-order Whitney spaces (vertex/edge/face DOFs).

Fields:

• mesh
• geom
• ndofs
• degree
• element_type (:curve_edge or :surface_triangle)

WhitneyComplex

Explicit lowest-order complex container:

0 -> Λh0 --d0--> Λh1 --d1--> Λh2 -> 0

Fields:

• V0, V1, V2
• d0, d1
• M0, M1, M2

Built with build_whitney_complex(mesh, geom).

See also

• Mesh types (math)
• Discrete exterior calculus (math)
• Caching and performance (math)

Ambient signed-distance API (v0.5)

build_signed_distance_cache

build_signed_distance_cache(mesh; leafsize=8) -> SignedDistanceCache

Builds an exact nearest-primitive acceleration cache (AABB tree + sign data) for CurveMesh and SurfaceMesh.

signed_distance (batched)

signed_distance(points, mesh_or_cache;
                sign_mode=:auto,
                lower_bound=0.0,
                upper_bound=Inf,
                return_normals=true)

Accepted points formats:

• Vector{SVector{N,T}}
• Matrix{T} with shape (N,np) or (np,N)

Returns (S, I, C, N):

• S: signed distances,
• I: closest primitive ids,
• C: closest points,
• N: signing normals (pseudonormal mode).

signed_distance (scalar)

signed_distance(point::SVector{N,T}, mesh_or_cache; sign_mode=:auto)

Returns named tuple (distance, primitive, closest, normal).

unsigned_distance

unsigned_distance(points, mesh_or_cache)

Convenience wrapper for signed_distance(...; sign_mode=:unsigned).

winding_number

winding_number(point, mesh_or_cache)

• Closed 2D curve: integer winding number.
• Closed 3D oriented surface: normalized solid-angle winding number.

is_closed_curve and is_closed_surface

is_closed_curve(mesh::CurveMesh) -> Bool
is_closed_surface(mesh::SurfaceMesh) -> Bool

Closure predicates used by sign_mode=:auto.

1-D point-front signed distance

signed_distance(front::PointFront1D, x::Real)
signed_distance(front::PointFront1D, xs::AbstractVector)
rebuild_signed_distance(front::PointFront1D, xnodes::AbstractVector)
interface_normals(front::PointFront1D)

Sign convention is the same: negative inside, positive outside, zero on marker(s).

Open-mesh sign semantics

• Closed meshes with sign_mode=:winding provide inside/outside sign.
• Open meshes with sign_mode=:pseudonormal provide oriented side sign.
• Open meshes do not define a global inside/outside region.
• In :pseudonormal mode, points on the front return distance 0.
• Near ambiguous configurations (signing dot-product within tolerance), the sign can evaluate to 0.

Short examples

Closed 2D curve:

mesh = sample_circle(1.0, 128)
cache = build_signed_distance_cache(mesh)
r_in  = signed_distance(SVector(0.0, 0.0), cache; sign_mode=:winding)
r_out = signed_distance(SVector(2.0, 0.0), cache; sign_mode=:winding)
# r_in.distance < 0, r_out.distance > 0

Open 2D curve:

mesh = load_curve_points([SVector(-1.0, 0.0), SVector(1.0, 0.0)]; closed=false)
cache = build_signed_distance_cache(mesh)
r_up = signed_distance(SVector(0.0, 0.5), cache; sign_mode=:pseudonormal)
r_dn = signed_distance(SVector(0.0, -0.5), cache; sign_mode=:pseudonormal)
# opposite signs across the oriented curve

Closed 3D surface:

mesh = generate_icosphere(1.0, 2)
cache = build_signed_distance_cache(mesh)
r_in  = signed_distance(SVector(0.0, 0.0, 0.0), cache; sign_mode=:winding)
r_out = signed_distance(SVector(2.0, 0.0, 0.0), cache; sign_mode=:winding)
# r_in.distance < 0, r_out.distance > 0

Open 3D patch:

pts = [SVector(0.0,0.0,0.0), SVector(1.0,0.0,0.0), SVector(1.0,1.0,0.0), SVector(0.0,1.0,0.0)]
faces = [SVector(1,2,3), SVector(1,3,4)]
mesh = SurfaceMesh{Float64}(pts, faces)
cache = build_signed_distance_cache(mesh)
r_top = signed_distance(SVector(0.5,0.5,0.3), cache; sign_mode=:pseudonormal)
r_bot = signed_distance(SVector(0.5,0.5,-0.3), cache; sign_mode=:pseudonormal)
# opposite signs across the oriented sheet