84258921df
Follow-up to the test-count centralisation + release-policy commit: applies the findings of the parallel doc-audit. Stale claims fixed ────────────────── * CLAUDE.md line 14-17 (phase block summary): expanded from "Phase 1-7 done, 8-9 planned, 10+ research" to reflect that Phase 8a MVP + 8b-Lite + 9a + 9b are now done (v0.9.0), with Phase 9b-analytic + 9c as the next planned milestones. * CLAUDE.md line 251-252 (release state): "v0.7.0 ... Phase 7 next" → "v0.9.0 ... Phase 9c + 9b-analytic next". * CLAUDE.md "Three geometry modes" → "Five DCE models" table. Adds CP-Euclidean and Inversive-Distance rows with their CGAL public entries. DOF-assignment pattern subsection rewritten to cover vertex-only / vertex+edge / face-based assignments. * CLAUDE.md "Newton solver" section: gradient sign and Hessian convention for all five solvers (was: three). Replaces the "Hessian is FD" claim for HyperIdeal with the block-FD note (Phase 9b shipped). * CLAUDE.md "Known quirks": stale GTEST_SKIP entry removed (v0.9.0 cleaned up the HDS-port stubs). * README.md line 86: "all 24 headers with descriptions" → "all public headers with descriptions" (was undercounting). Missing entries added — `doc/api/headers.md` ───────────────────────────────────────────── * New section **"Circle-packing functionals (Phase 9a)"** with `cp_euclidean_functional.hpp` and `inversive_distance_functional.hpp`. * New section **"Math utilities"** documenting four previously- undocumented public helpers: `matrix_utility.hpp`, `projective_math.hpp`, `p2_utility.hpp`, `discrete_elliptic_utility.hpp`. * New section **"CGAL public API (Phase 8b-Lite)"** documenting all six new public headers under `include/CGAL/`. * `newton_solver.hpp` row expanded to list all five Newton functions. Header count summary (before vs after): * Before: 24 headers in 8 sections (missing 6 of the 30 actually present). * After: 30 headers in 11 sections (complete coverage). Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
112 lines
6.9 KiB
Markdown
112 lines
6.9 KiB
Markdown
# Public Headers (`code/include/`)
|
||
|
||
All algorithms are header-only. Include the headers you need directly —
|
||
there is no compiled library to link against (only GTest for tests and
|
||
CGAL/Eigen for the CGAL-dependent headers).
|
||
|
||
## Core mesh type
|
||
|
||
| Header | Description |
|
||
|---|---|
|
||
| `conformal_mesh.hpp` | `ConformalMesh` = `CGAL::Surface_mesh<Point3>`. Property-map naming convention. Index type aliases. `GeometryType` enum. |
|
||
| `constants.hpp` | `conformallab::PI`, `TWO_PI` |
|
||
| `mesh_builder.hpp` | `make_triangle()` / `make_tetrahedron()` / `make_quad_strip()` / `make_fan()` / `make_open_cylinder()` — test mesh factories |
|
||
| `mesh_io.hpp` | `load_mesh()` / `save_mesh()` via `CGAL::IO` (OFF / OBJ / PLY) |
|
||
| `mesh_utils.hpp` | `cgal_to_eigen()` — convert `ConformalMesh` vertex positions to `Eigen::MatrixXd` |
|
||
|
||
## Special functions
|
||
|
||
| Header | Description |
|
||
|---|---|
|
||
| `clausen.hpp` | `clausen_cl2(θ)` (Clausen Cl₂), `lobachevsky(θ)` (Л), `im_li2(θ)` (ImLi₂ = imaginary part of dilogarithm) |
|
||
|
||
## HyperIdeal geometry (H²)
|
||
|
||
| Header | Description |
|
||
|---|---|
|
||
| `hyper_ideal_geometry.hpp` | `ζ₁₃`, `ζ₁₄`, `ζ₁₅` (Springborn 2020), `l_from_zeta()`, `alpha_ij()`, `beta_i()`, `sigma_i()`, `sigma_ij()` |
|
||
| `hyper_ideal_utility.hpp` | Tetrahedron volumes (Meyerhoff formula, Kolpakov–Mednykh) |
|
||
| `hyper_ideal_visualization_utility.hpp` | Poincaré disk projection, circumcircle helpers, Lorentz boost |
|
||
| `hyper_ideal_functional.hpp` | `HyperIdealMaps`, `setup_hyper_ideal_maps()`, `compute_hyper_ideal_lambda0_from_mesh()`, `assign_all_dof_indices()`, `hyper_ideal_gradient()`, `hyper_ideal_energy()` |
|
||
| `hyper_ideal_hessian.hpp` | `hyper_ideal_hessian()` — symmetric FD Hessian (Phase 9b: analytic) |
|
||
|
||
## Spherical geometry (S²)
|
||
|
||
| Header | Description |
|
||
|---|---|
|
||
| `spherical_geometry.hpp` | Spherical arc-length, half-angle formula, spherical law of cosines |
|
||
| `spherical_functional.hpp` | `SphericalMaps`, `setup_spherical_maps()`, `compute_spherical_lambda0_from_mesh()`, `spherical_gradient()`, `spherical_energy()` |
|
||
| `spherical_hessian.hpp` | `spherical_hessian()` — analytic Hessian via ∂α/∂u from law of cosines |
|
||
|
||
## Euclidean geometry (ℝ²)
|
||
|
||
| Header | Description |
|
||
|---|---|
|
||
| `euclidean_geometry.hpp` | Euclidean corner angle (t-value / atan2), edge lengths from DOF vector |
|
||
| `euclidean_functional.hpp` | `EuclideanMaps`, `setup_euclidean_maps()`, `compute_euclidean_lambda0_from_mesh()`, `euclidean_gradient()`, `euclidean_energy()` |
|
||
| `euclidean_hessian.hpp` | `euclidean_hessian()` — cotangent Laplacian (Pinkall–Polthier 1993) |
|
||
|
||
## Circle-packing functionals (Phase 9a)
|
||
|
||
| Header | Description |
|
||
|---|---|
|
||
| `cp_euclidean_functional.hpp` | **Face-based** CP-Euclidean (Bobenko–Pinkall–Springborn 2010), port of Java `CPEuclideanFunctional`. `CPEuclideanMaps`, `setup_cp_euclidean_maps()`, `assign_cp_euclidean_face_dof_indices()`, `cp_euclidean_gradient()`, `cp_euclidean_energy()`, **analytic** `cp_euclidean_hessian()` (2×2-per-edge `h_jk = sin θ / (cosh Δρ − cos θ)`) |
|
||
| `inversive_distance_functional.hpp` | **Vertex-based** inversive-distance (Luo 2004, no Java original). `InversiveDistanceMaps`, `setup_inversive_distance_maps()`, `compute_inversive_distance_init_from_mesh()` (Bowers–Stephenson 2004 init), `inversive_distance_gradient()`, `inversive_distance_energy()` |
|
||
|
||
## Solver
|
||
|
||
| Header | Description |
|
||
|---|---|
|
||
| `newton_solver.hpp` | Five Newton solvers — `newton_euclidean()`, `newton_spherical()`, `newton_hyper_ideal()` (uses block-FD Hessian since Phase 9b), `newton_cp_euclidean()` (analytic Hessian, Phase 9a-Newton), `newton_inversive_distance()` (FD Hessian, Phase 9a-Newton). Plus `solve_linear_system()` (SimplicialLDLT + SparseQR fallback) and the `NewtonResult` struct. |
|
||
|
||
## Preprocessing
|
||
|
||
| Header | Description |
|
||
|---|---|
|
||
| `gauss_bonnet.hpp` | `euler_characteristic()`, `genus()`, `gauss_bonnet_sum()`, `gauss_bonnet_rhs()`, `gauss_bonnet_deficit()`, `check_gauss_bonnet()`, `enforce_gauss_bonnet()` |
|
||
|
||
## Layout and holonomy
|
||
|
||
| Header | Description |
|
||
|---|---|
|
||
| `cut_graph.hpp` | `CutGraph` struct, `compute_cut_graph()` — tree-cotree algorithm (Erickson–Whittlesey 2005), produces 2g seam edges |
|
||
| `layout.hpp` | `euclidean_layout()`, `spherical_layout()`, `hyper_ideal_layout()`, `normalise_{euclidean,hyperbolic,spherical}()`. Structs: `Layout2D`, `Layout3D`, `HolonomyData`. `MobiusMap` (T(z)=(az+b)/(cz+d), `from_three`, `compose`, `inverse`, `apply`). Priority-BFS, `halfedge_uv`. |
|
||
|
||
## Post-processing
|
||
|
||
| Header | Description |
|
||
|---|---|
|
||
| `period_matrix.hpp` | `PeriodData`, `compute_period_matrix()`, `reduce_to_fundamental_domain()`, `is_in_fundamental_domain()` — period ratio τ = ω₂/ω₁ ∈ ℍ, SL(2,ℤ) reduction |
|
||
| `fundamental_domain.hpp` | `FundamentalDomain`, `compute_fundamental_domain()` (genus 1: CCW parallelogram; genus > 1: empty, TODO Phase 9c), `tiling_copy()`, `tiling_neighbourhood()` |
|
||
| `serialization.hpp` | `save_result_json()`, `load_result_json()`, `save_result_xml()`, `load_result_xml()`, `save_layout_off()` |
|
||
|
||
## Math utilities
|
||
|
||
These headers contain pure-math helpers used internally across the
|
||
package. All are also re-exported on the public API so downstream
|
||
consumers (e.g. user code that wants to assemble a custom functional)
|
||
can use them directly.
|
||
|
||
| Header | Description |
|
||
|---|---|
|
||
| `matrix_utility.hpp` | Small linear-algebra helpers used by `period_matrix.hpp` (2×2 determinant, …) |
|
||
| `projective_math.hpp` | Real projective 2-space helpers (point on line, lines through points, dual) |
|
||
| `p2_utility.hpp` | Higher-level P² utilities used by hyper-ideal layout (perpendicular bisectors in Poincaré disk, etc.) |
|
||
| `discrete_elliptic_utility.hpp` | Genus-1 / elliptic-curve helpers — half-period ratio τ from texture coords; bridge to genus-1 fundamental domain |
|
||
|
||
## CGAL public API (Phase 8b-Lite)
|
||
|
||
These headers live under `include/CGAL/` and are the user-facing entry
|
||
points. They are thin wrappers over the implementation in
|
||
`code/include/*.hpp`, exposing the five DCE models through a
|
||
CGAL-conventional interface.
|
||
|
||
| Header | Description |
|
||
|---|---|
|
||
| `CGAL/Conformal_map_traits.h` | `ConformalMapTraits` concept + `Default_conformal_map_traits<TriangleMesh, K>` (Euclidean-flavoured base trait) |
|
||
| `CGAL/Discrete_conformal_map.h` | `discrete_conformal_map_euclidean()`, `discrete_conformal_map_spherical()`, `discrete_conformal_map_hyper_ideal()`. Result types `Conformal_map_result<FT>` and `Hyper_ideal_map_result<FT>` |
|
||
| `CGAL/Discrete_circle_packing.h` | `Default_cp_euclidean_traits` + `discrete_circle_packing_euclidean()`. Result: `Circle_packing_result<FT>` with `rho_per_face` |
|
||
| `CGAL/Discrete_inversive_distance.h` | `Default_inversive_distance_traits` + `discrete_inversive_distance_map()`. Result: `Conformal_map_result<FT>` reused |
|
||
| `CGAL/Conformal_layout.h` | Thin re-export of `euclidean_layout`, `spherical_layout`, `hyper_ideal_layout` into the `CGAL::` namespace |
|
||
| `CGAL/Conformal_map/internal/parameters.h` | (internal) Named-parameter tags for `CGAL::parameters::*` |
|