Merge pull request #12: release v0.9.0 finalisation

2026-05-22 02:29:19 +00:00
parent b26368924b 540f71a629
commit e67ccd6b9d
13 changed files with 180 additions and 125 deletions
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -0,0 +1,153 @@
+# Changelog
+
+All notable changes to **conformallab++** are recorded here.  Format
+follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); the
+project uses [Semantic Versioning](https://semver.org).
+
+---
+
+## [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.
--- a/CITATION.cff
+++ b/CITATION.cff
@@ -7,8 +7,8 @@ authors:
    email: Tarik.moussa95@gmail.com

 title: "conformallab++"
-version: 0.7.0
-date-released: 2026-05-18
+version: 0.9.0
+date-released: 2026-05-22
 url: "https://codeberg.org/TMoussa/ConformalLabpp"
 repository-code: "https://codeberg.org/TMoussa/ConformalLabpp"
 license: MIT
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -244,7 +244,7 @@ Two jobs in `.gitea/workflows/cpp-tests.yml`:

 Runner: `eulernest` — self-hosted Raspberry Pi, ARM64, Ubuntu 22.04. Docker image: `git.eulernest.eu/conformallab/ci-cpp:latest`. `test-cgal` needs `test-fast` to pass first (`needs: test-fast`).

-Expected results: **36 non-CGAL tests pass**, **176 CGAL tests pass, 0 skipped**.
+Expected results: **23 non-CGAL tests pass**, **227 CGAL tests pass, 0 skipped**.

 ## Release state

@@ -349,7 +349,7 @@ follow the empirical verification rule above before any new claim.
 | Full pipeline API for all three geometries | `doc/api/pipeline.md` |
 | What does each processing unit require/provide (contracts)? | `doc/api/contracts.md` |
 | How to add a new functional / geometry mode / port from Java | `doc/api/extending.md` |
-| All 35 test suites, 176+36 tests, individual counts | `doc/api/tests.md` |
+| All 39 test suites, 227+23 tests, individual counts | `doc/api/tests.md` |
 | Phase 8 CGAL package design + Declarative YAML pipeline spec | `doc/api/cgal-package.md` |

 ### Concepts & specs
--- a/README.md
+++ b/README.md
@@ -13,7 +13,7 @@ Algorithmic foundation:
 > DOI: [10.14279/depositonce-5415](https://depositonce.tu-berlin.de/items/8e2988b2-d991-45b5-aad5-9fb7988f3b2f) · CC BY-SA 4.0 ·
 > [Java original](https://github.com/varylab/conformallab) · [sechel.de](https://sechel.de/)

-**Status:** Phase 7 complete. Newton solver for all three geometries (Euclidean / Spherical / HyperIdeal), priority-BFS layout in ℝ²/S²/Poincaré disk, Gauss–Bonnet, tree-cotree cut graph, Möbius holonomy, period matrix (genus 1), fundamental domain, halfedge_uv texture atlas, JSON/XML serialisation, CLI app. **176 CGAL tests + 36 non-CGAL tests.**
+**Status:** v0.9.0 — Phases 1–9a complete, Phase 8b-Lite CGAL API surface. Newton solvers for **five** DCE models (Euclidean / Spherical / HyperIdeal / CP-Euclidean / Inversive-Distance), priority-BFS layout in ℝ²/S²/Poincaré disk, Gauss–Bonnet, tree-cotree cut graph, Möbius holonomy, period matrix (genus 1), fundamental domain, halfedge_uv texture atlas, JSON/XML serialisation, CLI app. **227 CGAL tests + 23 non-CGAL tests, 0 skipped.**

 ---

@@ -84,7 +84,7 @@ Layout2D layout = euclidean_layout(mesh, res.x, maps);
 | **Getting started** — build modes, single-test invocation, CLI, Docker | [doc/getting-started.md](doc/getting-started.md) |
 | **Pipeline API** — all three geometries, holonomy, serialisation | [doc/api/pipeline.md](doc/api/pipeline.md) |
 | **Public headers** — all 24 headers with descriptions | [doc/api/headers.md](doc/api/headers.md) |
-| **Test suites** — 35 suites, 176+36 tests, individual counts | [doc/api/tests.md](doc/api/tests.md) |
+| **Test suites** — 39 suites, 227+23 tests, individual counts | [doc/api/tests.md](doc/api/tests.md) |
 | **Extending** — new functionals, geometry modes, porting from Java | [doc/api/extending.md](doc/api/extending.md) |
 | **Processing unit contracts** — preconditions / provides table | [doc/api/contracts.md](doc/api/contracts.md) |
 | **CGAL package design** — Phase 8 target, YAML pipeline | [doc/api/cgal-package.md](doc/api/cgal-package.md) |
--- a/code/tests/CMakeLists.txt
+++ b/code/tests/CMakeLists.txt
@@ -1,5 +1,5 @@
 add_executable(conformallab_tests
-    # ── Fully ported (pure math, no HDS) ────────────────────────────────────
+    # ── Pure-math test suite (no CGAL, no mesh — runs on every branch) ─────
    test_clausen.cpp
    test_hyper_ideal_utility.cpp
    test_matrix_utility.cpp
@@ -7,12 +7,14 @@ add_executable(conformallab_tests
    test_discrete_elliptic_utility.cpp
    test_p2_utility.cpp
    test_hyper_ideal_visualization_utility.cpp
-
-    # ── Stubs: blocked until HDS port (Phase 4) ──────────────────────────────
-    # All tests call GTEST_SKIP() with a clear explanation.
-    test_hyper_ideal_functional.cpp
-    test_hyper_ideal_hyperelliptic_utility.cpp
-    test_spherical_functional.cpp
+    #
+    # Stale stub files were removed in v0.9.0:
+    #   test_hyper_ideal_functional.cpp
+    #   test_hyper_ideal_hyperelliptic_utility.cpp
+    #   test_spherical_functional.cpp
+    # They referenced a "HDS port (Phase 4)" that never happened —
+    # CoHDS was intentionally replaced by CGAL::Surface_mesh, and the
+    # functionals + tests live in code/tests/cgal/test_*_functional.cpp.
 )

 target_include_directories(conformallab_tests SYSTEM PRIVATE
--- a/code/tests/test_hyper_ideal_functional.cpp
+++ b/code/tests/test_hyper_ideal_functional.cpp
@@ -1,37 +0,0 @@
-// Stub for de.varylab.discreteconformal.functional.HyperIdealFunctionalTest (Java/JUnit).
-//
-// STATUS: BLOCKED – requires HDS port (Phase 4).
-//
-// These tests evaluate gradient and Hessian of the HyperIdealFunctional on
-// actual mesh data (CoHDS + HyperIdealGenerator).  They cannot be ported
-// until the HalfEdge data structure (CoHDS), the functional evaluation
-// framework, and the mesh generators are available in C++.
-//
-// Java tests and their status:
-//   testHessian()                           – @Ignore in Java (skipped here too)
-//   testGradientWithHyperIdealAndIdealPoints – blocked: needs HDS
-//   testGradientInTheExtendedDomain          – blocked: needs HDS
-//   testGradientWithHyperellipticCurve       – blocked: needs HDS
-//   testFunctionalAtNaNValue                 – blocked: needs HDS
-
-#include <gtest/gtest.h>
-
-TEST(HyperIdealFunctionalTest, TestHessian_IgnoredInJava) {
-    GTEST_SKIP() << "@Ignore in Java – skipped here too";
-}
-
-TEST(HyperIdealFunctionalTest, GradientWithHyperIdealAndIdealPoints) {
-    GTEST_SKIP() << "Blocked: requires HDS port (CoHDS + HyperIdealFunctional)";
-}
-
-TEST(HyperIdealFunctionalTest, GradientInTheExtendedDomain) {
-    GTEST_SKIP() << "Blocked: requires HDS port (CoHDS + HyperIdealFunctional)";
-}
-
-TEST(HyperIdealFunctionalTest, GradientWithHyperellipticCurve) {
-    GTEST_SKIP() << "Blocked: requires HDS port (CoHDS + HyperIdealFunctional)";
-}
-
-TEST(HyperIdealFunctionalTest, FunctionalAtNaNValue) {
-    GTEST_SKIP() << "Blocked: requires HDS port (CoHDS + HyperIdealFunctional)";
-}
--- a/code/tests/test_hyper_ideal_hyperelliptic_utility.cpp
+++ b/code/tests/test_hyper_ideal_hyperelliptic_utility.cpp
@@ -1,26 +0,0 @@
-// Stub for de.varylab.discreteconformal.functional.HyperIdealHyperellipticUtilityTest.
-//
-// STATUS: BLOCKED – requires HDS port (Phase 4).
-//
-// Tests compute intersection angles of circles associated with hyper-ideal
-// vertices using CoHDS + HalfEdgeUtils.  All three tests operate on mesh
-// data structures that are not yet available in C++.
-//
-// Java tests and their status:
-//   testCalculateCircleIntersections         – blocked: needs CoHDS + HalfEdgeUtils
-//   testCalculateCircleIntersectionsInfinite – blocked: needs CoHDS + HalfEdgeUtils
-//   testLawsonHyperellipticAngles            – blocked: needs CoHDS + HyperIdealGenerator
-
-#include <gtest/gtest.h>
-
-TEST(HyperIdealHyperellipticUtilityTest, CalculateCircleIntersections) {
-    GTEST_SKIP() << "Blocked: requires HDS port (CoHDS + HalfEdgeUtils)";
-}
-
-TEST(HyperIdealHyperellipticUtilityTest, CalculateCircleIntersectionsInfinite) {
-    GTEST_SKIP() << "Blocked: requires HDS port (CoHDS + HalfEdgeUtils)";
-}
-
-TEST(HyperIdealHyperellipticUtilityTest, LawsonHyperellipticAngles) {
-    GTEST_SKIP() << "Blocked: requires HDS port (CoHDS + HyperIdealGenerator)";
-}
--- a/code/tests/test_spherical_functional.cpp
+++ b/code/tests/test_spherical_functional.cpp
@@ -1,37 +0,0 @@
-// Stub for de.varylab.discreteconformal.functional.SphericalFunctionalTest (Java/JUnit).
-//
-// STATUS: BLOCKED – requires HDS port (Phase 4).
-//
-// Tests evaluate gradient and Hessian of the SphericalFunctional on meshes
-// built via CoHDS + ConvexHull, and check that a regular spherical metric
-// is a critical point of the functional.  All tests require the HalfEdge
-// data structure and the functional evaluation framework in C++.
-//
-// Java tests and their status:
-//   testReducedGradient   – blocked: needs CoHDS + SphericalFunctional
-//   testReducedHessian    – blocked: needs CoHDS + SphericalFunctional
-//   testGradient          – blocked: needs CoHDS + SphericalFunctional
-//   testHessian           – blocked: needs CoHDS + SphericalFunctional
-//   testCriticalPoint     – blocked: needs CoHDS + ConvexHull + SphericalFunctional
-
-#include <gtest/gtest.h>
-
-TEST(SphericalFunctionalTest, ReducedGradient) {
-    GTEST_SKIP() << "Blocked: requires HDS port (CoHDS + SphericalFunctional)";
-}
-
-TEST(SphericalFunctionalTest, ReducedHessian) {
-    GTEST_SKIP() << "Blocked: requires HDS port (CoHDS + SphericalFunctional)";
-}
-
-TEST(SphericalFunctionalTest, Gradient) {
-    GTEST_SKIP() << "Blocked: requires HDS port (CoHDS + SphericalFunctional)";
-}
-
-TEST(SphericalFunctionalTest, Hessian) {
-    GTEST_SKIP() << "Blocked: requires HDS port (CoHDS + SphericalFunctional)";
-}
-
-TEST(SphericalFunctionalTest, CriticalPoint) {
-    GTEST_SKIP() << "Blocked: requires HDS port (CoHDS + ConvexHull + SphericalFunctional)";
-}
--- a/doc/api/tests.md
+++ b/doc/api/tests.md
@@ -14,7 +14,7 @@ Pure-math tests, only Eigen required. Covers Java utilities ported in Phase 1–
 | `test_p2_utility.cpp` | P2 projective utilities |
 | `test_hyper_ideal_visualization_utility.cpp` | Poincaré disk projection, circumcircle |

-**Total: 36 tests, 0 skipped.**
+**Total: 23 tests, 0 skipped.**

 ---

@@ -59,7 +59,7 @@ All tests have CTest prefix `cgal.` (set via `TEST_PREFIX "cgal."` in CMakeLists
 | `HomologyGenerators` | `test_geometry_utils.cpp` | 1 | Genus-2 cut graph: χ = −2, 4 cut edges (`brezel2.obj`) |
 | `SmokeEuclidean` | `test_scalability_smoke.cpp` | 3 | Smoke tests on real meshes: CatHead (open), Brezel genus-1, Brezel2 genus-2 |

-**Total: 176 tests, 0 skipped.**
+**Total: 227 tests, 0 skipped.**

 ---

--- a/doc/contributing.md
+++ b/doc/contributing.md
@@ -29,8 +29,8 @@ Two jobs run on push to `dev`/`main` or on pull requests:

 | Job | What it tests | Trigger |
 |---|---|---|
-| `test-fast` | 36 non-CGAL tests, no Boost | all branches |
-| `test-cgal` | 176 CGAL tests, 0 skipped | `main`, `dev`, PRs only |
+| `test-fast` | 23 non-CGAL tests, no Boost | all branches |
+| `test-cgal` | 227 CGAL tests, 0 skipped | `main`, `dev`, PRs only |

 A PR is ready to merge when both jobs pass.

@@ -51,7 +51,7 @@ Every new algorithm needs:

 3. **Registration** — add the `.cpp` file to `code/tests/cgal/CMakeLists.txt`.

-Expected CI result: **36 + 176 tests pass, 0 skipped**.
+Expected CI result: **23 + 227 tests pass, 0 skipped**.

 ---

--- a/doc/getting-started.md
+++ b/doc/getting-started.md
@@ -48,7 +48,7 @@ cmake --build build --target conformallab_tests -j$(nproc)
 ctest --test-dir build --output-on-failure
 ```

-Expected: **36 tests pass**.
+Expected: **23 tests pass**.

 ### Mode 2 — CGAL tests, headless (recommended for CI and development)

@@ -60,7 +60,7 @@ cmake --build build --target conformallab_cgal_tests -j$(nproc)
 ctest --test-dir build -R "^cgal\." --output-on-failure
 ```

-Expected: **176 tests pass, 0 skipped**.
+Expected: **227 tests pass, 0 skipped**.

 ### Mode 3 — Full local build (CLI app + interactive viewer)

@@ -146,7 +146,7 @@ sets x* = 0, so a small perturbation (-0.05) needs only one Newton step.
 bash scripts/try_it.sh
 ```
 This clones nothing (run from inside the repo), builds the CGAL test suite, runs
-all 176+36 tests, and prints a summary.  See `scripts/try_it.sh` for details.
+all 227+23 tests, and prints a summary.  See `scripts/try_it.sh` for details.

 ---

--- a/doc/math/validation.md
+++ b/doc/math/validation.md
@@ -14,7 +14,7 @@ cmake --build build --target conformallab_cgal_tests
 ctest --test-dir build -R cgal --output-on-failure
 ```

-All 176 tests pass, 0 skipped (see `doc/api/tests.md`).
+All 227 tests pass, 0 skipped (see `doc/api/tests.md`).

 ---

@@ -252,7 +252,7 @@ implemented in conformallab++ (→ GC-2 in the phase roadmap).

 Run these in order to validate the implementation:

- [ ] `ctest --test-dir build -R cgal --output-on-failure` → 176 tests pass, 0 skipped
+- [ ] `ctest --test-dir build -R cgal --output-on-failure` → 227 tests pass, 0 skipped
 - [ ] `cgal.GaussBonnet.*` all pass → topology is correctly read from mesh
 - [ ] `cgal.EuclideanFunctional.GradientCheck_*` pass → energy = integral of gradient
 - [ ] `cgal.PeriodMatrix.TauInFundamentalDomain_*` pass → SL(2,ℤ) reduction correct
--- a/scripts/try_it.sh
+++ b/scripts/try_it.sh
@@ -10,8 +10,8 @@
 #   bash scripts/try_it.sh
 #
 # Expected output (last lines):
-#   [PASS]  176 CGAL tests pass, 0 skipped
-#   [PASS]  36  non-CGAL tests pass
+#   [PASS]  227 CGAL tests pass, 0 skipped
+#   [PASS]  23  non-CGAL tests pass
 #   [EXAMPLE] Converged in N iterations. ||G||_inf < 1e-9

 set -euo pipefail