ConformalLabpp/CHANGELOG.md

Changelog

All notable changes to conformallab++ are recorded here. Format follows Keep a Changelog; the project uses Semantic Versioning.

---

[0.10.0] — 2026-05-26

The "reviewer-ready" release. Three PRs (#17 + #18 + #19, 13 thematic commits total) landed: a 100 %-Doxygen-covered public API, a 14-gate structural quality suite (4 of them required CI), a researcher-targeted reviewer materials package, the output_uv_map named parameter extended to four of the five DCE solvers, six new roadmap phases from a full Java-library scan, thirteen new Tier-1/2 literature citations, three RESEARCH-only phases with acceptance criteria, and a six-mode compile-time workflow matrix.

Added — reviewer materials (PR #19)

• doc/reviewer/{briefing,questions,agenda,README}.md — one-page reviewer briefing + seven scoped questions (Q1–Q2 research-track alignment; Q3–Q4 porting decisions; Q5–Q6 process; Q7 the "no" question) + internal meeting agenda + landing index.
• doc/reviewer/hub.html — hand-curated reviewer landing page, in-repo so the publish URL survives every merge.
• code/deps/THIRD-PARTY-LICENSES.md — per-vendored-dep SPDX with MIT-compatibility analysis (CGAL LGPL §3 vs §4 distinction).
• doc/architecture/dependencies.md — required vs optional deps; standalone-verification recipe.

Added — new roadmap content (PR #19)

• Six new phases from full Java-library scan: Phase 9d (cones), 9d.4 (variational Möbius centring), 9e (circle-pattern layout), 10d (Koebe circle-domain), 10e (quasi-isothermic, ~800 lines, 6 classes), 10f (Koebe polyhedra), 10g (cyclic-symmetry quotients).
• Three RESEARCH phases with acceptance criteria: 9d.2 (non-Euclidean cone extensions), 9f (polygon Laplacian on non-triangular meshes, no Java parent), 10c′ (Koebe polyhedron rigidity).
• 13 new Tier-1/Tier-2 citations in doc/math/references.md.

Added — compile-time workflow matrix (PR #19)

• PCH + Unity Build defaults: CGAL test wall-time 78 s → 55 s (−30 %), CPU time 676 s → 167 s (−75 %).
• Five new opt-in workflow modes (BUILD_TESTING=OFF, CONFORMALLAB_HEADERS_CHECK, CONFORMALLAB_DEV_BUILD, CONFORMALLAB_FAST_TEST_BUILD, CONFORMALLAB_USE_CCACHE).
• doc/architecture/compile-time.md — full measurement + workflow matrix + macOS-vs-Linux honesty notes.
• .gitea/workflows/perf-compile-time.yml — Linux CI bench.

Added — output_uv_map covers 4 of 5 DCE entries (PR #19)

• CGAL::discrete_inversive_distance_map honours output_uv_map via Bowers-Stephenson edge-length reconstruction.
• CGAL::discrete_circle_packing_euclidean rejects output_uv_map with a clear std::runtime_error (face-based DOFs, Phase 9c).

Added — structural quality gates (PR #18)

Four scripts promoted to required CI: license-headers.sh, cgal-conventions.py, codespell.sh, shellcheck.sh --strict. Seven additional local-only gates: clang-format, cmake-format, cppcheck, sanitizers (ASan + UBSan), clang-tidy, multi-compiler, reproducible-build, CGAL-version-matrix.

Added — Doxygen 100 % public-API coverage (PR #17)

• Doxygen coverage: 24 % → 100 % (396/396 public symbols).
• Fixed EXCLUDE_PATTERNS bug that previously silently excluded every .hpp/.h — pre-fix HTML had ~0 % API surface.
• MathJax + CGAL \cgalParam* aliases.
• New scripts: scripts/doxygen-coverage.sh (CI-gateable), scripts/gen-headers-md.py (auto-regenerates doc/api/headers.md).

Changed

• Three headers <Eigen/Dense> → <Eigen/Core> (none use Eigen decompositions): projective_math.hpp, hyper_ideal_visualization_utility.hpp, mesh_utils.hpp.
• doc/api/tests.md — CGAL suite 234 → 236 tests.
• code/.gitignore — un-ignore code/deps/THIRD-PARTY-LICENSES.md.

Numbers at release

• 259 / 259 tests pass, 0 skipped.
• 100 % Doxygen coverage on public API, 0 warnings.
• 14 / 15 quality gates green, 1 SKIP (no CGAL tarballs locally).
• CI build wall: ~55 s on Apple M1 (−30 % vs v0.9.0).
• 13 Tier-1 / Tier-2 literature citations integrated.

---

[0.9.0] — 2026-05-22

The “DCE-complete + CGAL-surface-complete” release. Two new discrete- conformal models, the analytic-Hessian optimisation for HyperIdeal, the CGAL public API surface for all five models, and a full documentation audit that corrects four pre-existing port-vs-research mis-labels.

Added — new functionals (Phase 9a)

• code/include/cp_euclidean_functional.hpp — CP-Euclidean functional (face-based circle packing), Bobenko-Pinkall-Springborn 2010. Direct port of CPEuclideanFunctional.java (260 Java lines + 88-line test). Analytic 2×2-per-edge Hessian h_jk = sin θ / (cosh Δρ − cos θ).
• code/include/inversive_distance_functional.hpp — Inversive-Distance functional (vertex-based, Luo 2004 + Glickenstein 2011). No Java original — implemented from the literature with Bowers-Stephenson 2004 initialisation. Cross-validated against the Euclidean functional at the natural initial geometry (Glickenstein §5).

Added — Newton solvers (Phase 9a-Newton)

• newton_cp_euclidean() — uses the analytic Hessian.
• newton_inversive_distance() — uses FD Hessian; analytic via Glickenstein 2011 eq. (4.6) tracked in research-track.md as Phase 9a.2-analytic.

Added — Hessian optimisation (Phase 9b)

• hyper_ideal_hessian_block_fd() — per-face 6×6 block-local Hessian for HyperIdeal. 96.5× speed-up measured on a 200-face mesh (V=202, 603 DOFs), full-FD 226 ms → block-FD 2.3 ms.
• Java parity note: HyperIdealFunctional.java:295-298 declares hasHessian() == false; both FD variants are conformallab++ research extensions beyond the Java port.

Added — CGAL public API surface (Phase 8b-Lite)

• <CGAL/Discrete_conformal_map.h> extended with discrete_conformal_map_spherical() and discrete_conformal_map_hyper_ideal().
• <CGAL/Discrete_circle_packing.h> — Default_cp_euclidean_traits + discrete_circle_packing_euclidean().
• <CGAL/Discrete_inversive_distance.h> — Default_inversive_distance_traits
  • discrete_inversive_distance_map().
• <CGAL/Conformal_layout.h> — thin CGAL-namespace re-exports of euclidean_layout, spherical_layout, hyper_ideal_layout.

All five DCE models are now reachable from a single #include <CGAL/Discrete_*.h>.

Added — documentation

• doc/roadmap/research-track.md — new consolidated catalogue of every conformallab++ item that goes beyond the Java port, with full literature citations and acceptance criteria. Includes the Phase 9b-analytic plan (Schläfli 1858 + Springborn 2020 §4 + Cho-Kim 1999 + Glickenstein 2011 §4).
• doc/architecture/phase-9a-validation.md — line-by-line mapping CPEuclideanFunctional.java ↔ C++ port, plus three special-case verifications of Luo’s edge-length formula.
• doc/roadmap/phases.md — Phase 9 split into 9a.1 (Java port) / 9a.2 (research) / 9b (research); new Phase 11+ section with optional Schottky uniformisation and Riemann-map sub-packages.
• doc/math/references.md — five new primary literature entries (Bowers-Stephenson 2004, Glickenstein 2011, BPS 2010, Schläfli 1858/60, plus a reframed Luo 2004 entry).

Changed

• Four port-vs-research mis-labels corrected (full audit documented in research-track.md):
  • InversiveDistanceFunctional.java does not exist in the Java repo; the C++ implementation is research, not a port.
  • HyperIdeal Hessian: Java has hasHessian()==false; C++ Hessians are research, not ports.
  • add-inversive-distance.md tutorial rewritten end-to-end.
  • references.md and java-parity.md reframed.
• Discrete_conformal_map.h (Phase 8a MVP wrapper) now deduces the kernel from TriangleMesh::Point via CGAL::Kernel_traits rather than hard-coding Simple_cartesian<double>. Regression-guarded by KernelIsDeducedFromMeshPointType test.

Removed

• Three stale stub test files in code/tests/ (15 GTEST_SKIPs total):
  • test_spherical_functional.cpp
  • test_hyper_ideal_functional.cpp
  • test_hyper_ideal_hyperelliptic_utility.cpp They referenced a "HDS port (Phase 4)" that never happened — CoHDS was intentionally replaced by CGAL::Surface_mesh, and the functional tests live in code/tests/cgal/test_*_functional.cpp.

CI / Infrastructure

• .gitea/workflows/cpp-tests.yml — test-cgal memory fixed (1400→1600 MB, -j2 → -j1). Addresses OOM on ARM64 runner.
• .gitea/workflows/doc-build.yaml — soft-fail Doxygen job (no merge-blocking).
• Doxyfile + CMake doc target — cmake --build build --target doc.
• 12 macOS Finder-duplicate files removed from code/include/.

Test counts

v0.7.0:  176 CGAL + 36 non-CGAL = 212 total,  13 skipped (HDS stubs)
v0.9.0:  227 CGAL + 23 non-CGAL = 250 total,   0 skipped   (+38 net, +51 CGAL)

Non-CGAL count dropped from 36 → 23 because three stale HDS-port stubs were removed (see "Removed" above) — the functionality is fully covered in the CGAL test suite where it actually lives.

Five test suites added: CGALConformalTraits, CGALDiscreteConformalMap, CPEuclideanFunctional, InversiveDistanceFunctional, HyperIdealHessian, NewtonPhase9a, CGALPhase8bLite.

---

[0.7.0] — 2026-05-18

The “mathematician-ready” release. See the v0.7.0 announcement in README.md (legacy) or CITATION.cff for the corresponding citation entry. Phases 1–7 complete: three DCE geometry modes (Euclidean / Spherical / HyperIdeal), Newton solver, BFS-trilateration layout, Gauss-Bonnet, tree-cotree cut graph, Möbius holonomy, period matrix for genus 1, fundamental domain (genus 1), texture atlas.

---

How to update this file

Every new release adds a new top-level section above the previous one. For non-trivial PRs that don't trigger a release, add an entry under an [Unreleased] section at the top; promote it to the next release header at tag time.

Categories (Keep-A-Changelog convention):

• Added — new features / files / public APIs.
• Changed — behaviour-altering changes to existing features.
• Deprecated — features still present but slated for removal.
• Removed — deleted features / files.
• Fixed — bug fixes.
• Security — security-relevant fixes.