FrontIntrinsicOps.jl — Documentation

FrontIntrinsicOps.jl is a static-surface PDE toolkit for triangulated front meshes. It implements intrinsic geometry, discrete exterior calculus (DEC), and a full suite of PDE solvers — all working directly on the surface without embedding into a bulk domain.

Release summary for ambient signed distance is available in CHANGELOG.md (v0.5 section).

Contents

Mathematical Background

Detailed derivations and formulas for every module:

API Reference

Concise function signatures and descriptions:

Tutorials

Step-by-step worked examples:

Quick reference

using FrontIntrinsicOps

# ── Build mesh ──────────────────────────────────────────────────────────────
mesh = generate_icosphere(1.0, 3)          # level-3 icosphere (~640 verts)
geom = compute_geometry(mesh)              # intrinsic geometry
dec  = build_dec(mesh, geom)               # DEC operators

# ── Geometry diagnostics ────────────────────────────────────────────────────
println("Area   = ", measure(mesh, geom))
println("χ      = ", euler_characteristic(mesh))
println("GB res = ", gauss_bonnet_residual(mesh, geom))

# ── Surface diffusion ───────────────────────────────────────────────────────
u, fac = step_surface_diffusion_backward_euler(mesh, geom, dec, u0, dt, μ)

# ── Reaction–diffusion (Fisher–KPP) ─────────────────────────────────────────
cache = build_pde_cache(mesh, geom, dec; μ=0.1, dt=1e-3, θ=1.0)
reaction = fisher_kpp_reaction(2.0)
for _ in 1:200; step_diffusion_cached!(u, cache, reaction, t); end

# ── Hodge decomposition ──────────────────────────────────────────────────────
α = dec.d0 * u
result = hodge_decompose_1form(mesh, geom, dec, α)
# result.exact  result.coexact  result.harmonic

# ── High-resolution transport ────────────────────────────────────────────────
T_new = step_surface_transport_limited(mesh, geom, dec, topo, T, vel, dt;
                                       limiter=:van_leer, method=:ssprk2)

Design principles

1. Discrete exterior calculus first — all operators derive from the primal cochain complex $\Omega^0 \xrightarrow{d_0} \Omega^1 \xrightarrow{d_1} \Omega^2$.
2. No bulk-solver coupling — purely intrinsic; coupling lives in a separate package.
3. Sparse matrices throughout — every global operator is a SparseMatrixCSC.
4. Reuse factorizations — linear solves are the bottleneck; the cache layer amortizes factorization cost across many time steps.
5. Float64 default — parameterised on T<:AbstractFloat; Float32 meshes work.

License

MIT