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