ConformalLabpp/CHANGELOG.md

# 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.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.