docs: restructure documentation into focused files
README.md: reduced from 703 to ~75 lines — what/why, status, quick start, minimal usage example, navigation table to doc/ files. doc/architecture/overall_pipeline.md: trimmed — roadmap, extension points, declarative pipeline YAML, and references sections removed (each now has its own dedicated file). Replaced with a link table. New files: doc/getting-started.md — build modes, single-test invocation, CLI doc/api/pipeline.md — full pipeline API with code for all 3 geometries doc/api/extending.md — new functionals, geometry modes, Java porting guide doc/api/contracts.md — processing unit preconditions/provides table doc/api/cgal-package.md — Phase 8 CGAL package design + YAML pipeline (TODO) doc/math/geometry-modes.md — Euclidean/Spherical/HyperIdeal comparison doc/math/references.md — all papers by module doc/roadmap/phases.md — Phases 1–10 with porting/research boundary doc/roadmap/java-parity.md — Java vs C++ feature parity table doc/contributing.md — language policy, test standards, release flow Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
Tarik Moussa
86
doc/roadmap/java-parity.md
Normal file
86
doc/roadmap/java-parity.md
Normal file
@@ -0,0 +1,86 @@
|
||||
# Java ConformalLab vs. conformallab++ — Feature Parity
|
||||
|
||||
Reference: [github.com/varylab/conformallab](https://github.com/varylab/conformallab)
|
||||
Java package root: `de.varylab.discreteconformal`
|
||||
|
||||
When porting a Java class, locate the original in the Java repository and use it
|
||||
as the reference implementation for expected behaviour, edge cases, and test cases.
|
||||
|
||||
---
|
||||
|
||||
## Algorithm parity
|
||||
|
||||
| Mathematical layer | Java ConformalLab | conformallab++ | Notes |
|
||||
|---|---|---|---|
|
||||
| Euclidean functional — energy, gradient | ✅ | ✅ | |
|
||||
| Spherical functional — energy, gradient, gauge-fix | ✅ | ✅ | |
|
||||
| HyperIdeal functional — energy, gradient | ✅ | ✅ | |
|
||||
| Inversive-distance functional (Luo 2004) | ✅ | ❌ Phase 9a | `InversiveDistanceFunctional.java` |
|
||||
| Euclidean Hessian — cotangent Laplacian | ✅ analytic | ✅ analytic | Pinkall–Polthier (1993) |
|
||||
| Spherical Hessian — ∂α/∂u via law of cosines | ✅ analytic | ✅ analytic | |
|
||||
| HyperIdeal Hessian — ζ → lᵢⱼ → β/α chain | ✅ analytic | ⚠️ symmetric FD | Phase 9b |
|
||||
| Newton solver | ✅ | ✅ | |
|
||||
| SparseQR fallback for gauge modes | unknown | ✅ | New in C++ |
|
||||
| Cone metrics — prescribed Θᵥ ≠ 2π | ✅ fully | ⚠️ data structure only | |
|
||||
| Layout / embedding — ℝ² / H² / S² | ✅ | ✅ priority-BFS all three | |
|
||||
| Exact hyperbolic trilateration | ✅ Möbius | ✅ Möbius + law of cosines | |
|
||||
| halfedge_uv — seam-aware UV (texture atlas) | ✅ | ✅ | |
|
||||
| Gauss–Bonnet consistency check | ✅ | ✅ | |
|
||||
| Tree-cotree cut graph (2g edges) | ✅ | ✅ Erickson–Whittlesey (2005) | |
|
||||
| Holonomy — Euclidean (translations) | ✅ | ✅ | |
|
||||
| Holonomy — Hyperbolic (SU(1,1) Möbius maps) | ✅ | ✅ | |
|
||||
| Period matrix τ — genus 1, SL(2,ℤ)-reduced | ✅ | ✅ | |
|
||||
| Fundamental domain — genus 1 | ✅ | ✅ CCW parallelogram | |
|
||||
| 4g-polygon boundary walk — genus g > 1 | ✅ | ❌ Phase 9c | `FundamentalDomainUtility.java` |
|
||||
| Siegel period matrix Ω — genus g ≥ 2 | ✅ | ❌ Phase 10b | |
|
||||
| Global uniformization — genus g ≥ 2 | ✅ | ❌ Phase 10c | |
|
||||
| Clausen / Lobachevsky / ImLi₂ | ✅ | ✅ | |
|
||||
| Poincaré disk / Lorentz boost visualisation | ✅ | ✅ | |
|
||||
| Mesh I/O + serialisation | ✅ XML/CoHDS | ✅ OFF/OBJ/PLY + JSON/XML | |
|
||||
| Interactive viewer | ✅ jReality | ✅ libigl/GLFW | |
|
||||
|
||||
---
|
||||
|
||||
## Java utility classes not yet ported
|
||||
|
||||
These exist in `de.varylab.discreteconformal.util` in the Java library.
|
||||
They are candidates for Phase 9 or Phase 10.
|
||||
|
||||
| Java class | Description | Phase |
|
||||
|---|---|---|
|
||||
| `InversiveDistanceFunctional` | Inversive-distance conformal energy | 9a |
|
||||
| `DiscreteHarmonicFormUtility` | Discrete harmonic 1-forms | 10a prerequisite |
|
||||
| `DiscreteHolomorphicFormUtility` | Holomorphic differentials on discrete surfaces | 10a |
|
||||
| `DiscreteRiemannUtility` | Discrete Riemann surfaces | 10 |
|
||||
| `CanonicalBasisUtility` | Canonical homology basis for genus g | 9c / 10 |
|
||||
| `HomologyUtility` | Homology computation | 9c |
|
||||
| `HomotopyUtility` | Homotopy generators | 9c |
|
||||
| `SpanningTreeUtility` | Spanning tree algorithms | 8 / infrastructure |
|
||||
| `SurgeryUtility` | Mesh surgery (cut/glue) | — |
|
||||
| `StitchingUtility` | Seam stitching | — |
|
||||
| `CuttingUtility` | Advanced cutting (beyond tree-cotree) | 9c |
|
||||
| `HyperellipticUtility` | Hyperelliptic surfaces | 10 |
|
||||
| `LaplaceUtility` | Discrete Laplace operators | 9 / infrastructure |
|
||||
| `ConformalStructureUtility` | Conformal structure extraction | 10 |
|
||||
|
||||
---
|
||||
|
||||
## HyperIdeal Hessian: FD vs. analytic
|
||||
|
||||
The Java library computes the HyperIdeal Hessian analytically through the chain:
|
||||
|
||||
```
|
||||
(bᵢ, aₑ) → lᵢⱼ → ζ₁₃/ζ₁₄/ζ₁₅ → αᵢⱼ / βᵢ
|
||||
```
|
||||
|
||||
conformallab++ uses a **symmetric finite-difference approximation**:
|
||||
|
||||
```
|
||||
H[i,j] = ( G(x + ε·eⱼ)[i] − G(x − ε·eⱼ)[i] ) / (2ε), ε = 1e-5
|
||||
```
|
||||
|
||||
Accuracy: O(ε²) ≈ 10⁻¹⁰ relative error. PSD guaranteed by strict convexity (Springborn 2020).
|
||||
Cost: n extra gradient evaluations per Newton step.
|
||||
Impact: negligible for meshes < 500 DOFs; measurable for larger meshes.
|
||||
|
||||
The analytic Hessian is deferred to Phase 9b.
|
||||
116
doc/roadmap/phases.md
Normal file
116
doc/roadmap/phases.md
Normal file
@@ -0,0 +1,116 @@
|
||||
# Development Roadmap
|
||||
|
||||
> **Legend:** ✅ complete · 🔲 planned
|
||||
>
|
||||
> **Porting / research boundary:**
|
||||
> Phases 1–7 are direct ports of the Java original and its dissertation.
|
||||
> From Phase 8 onwards the work goes beyond the scope of the Java library.
|
||||
> Phase 8 (CGAL package) is infrastructure. Phase 9 is porting of remaining Java features.
|
||||
> Phase 10+ is independent research with no direct Java reference implementation.
|
||||
|
||||
---
|
||||
|
||||
## ◼ Porting complete — Phases 1–7
|
||||
|
||||
```
|
||||
Phase 1 Clausen / Lobachevsky / ImLi₂ special functions ✅
|
||||
Phase 2 Hyper-ideal geometry (ζ, lᵢⱼ, αᵢⱼ, σᵢ, σᵢⱼ) ✅
|
||||
Phase 3 CGAL Surface_mesh infrastructure + all three functionals
|
||||
(Euclidean, Spherical, HyperIdeal) + analytical Hessians ✅
|
||||
Phase 4 Newton solver (SimplicialLDLT + SparseQR fallback)
|
||||
+ Mesh I/O (OFF/OBJ/PLY) + example programs ✅ 68 tests
|
||||
Phase 5 Priority-BFS layout + CLI app + JSON/XML serialisation ✅ 95 tests
|
||||
Phase 6 Gauss–Bonnet check/enforce, tree-cotree cut graph (2g),
|
||||
exact hyperbolic trilateration, layout normalisation ✅ 121 tests
|
||||
Phase 7 MobiusMap, halfedge_uv, Möbius holonomy (SU(1,1)),
|
||||
period matrix τ∈ℍ + SL(2,ℤ) reduction,
|
||||
fundamental domain parallelogram + tiling ✅ 158 tests
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## ◼ Infrastructure — Phase 8: CGAL Package
|
||||
|
||||
Goal: conformallab++ as a standalone CGAL package, submission-ready, fulfilling all
|
||||
CGAL package conventions with a traits-class design compatible with any CGAL-conforming
|
||||
mesh type.
|
||||
|
||||
```
|
||||
8a Traits class & concepts
|
||||
→ include/CGAL/Conformal_map_traits.h
|
||||
Separates MeshType, KernelType, ScalarType from the algorithm.
|
||||
Enables use with any CGAL-compatible mesh, not just Surface_mesh.
|
||||
→ Concept checks via static_assert / CGAL_concept_check
|
||||
|
||||
8b Public CGAL header hierarchy
|
||||
→ include/CGAL/Discrete_conformal_map.h (user-facing entry header)
|
||||
→ include/CGAL/Conformal_newton_solver.h
|
||||
→ include/CGAL/Conformal_layout.h
|
||||
→ include/CGAL/Conformal_cut_graph.h
|
||||
All existing include/conformallab/*.hpp remain as implementation details.
|
||||
|
||||
8c CGAL-style documentation
|
||||
→ doc/Conformal_map/PackageDescription.txt
|
||||
→ doc/Conformal_map/fig/ (pipeline diagrams)
|
||||
→ Doxygen comments on all public concepts and functions
|
||||
→ User_manual.md + Reference_manual.md
|
||||
|
||||
8d CGAL test format
|
||||
→ test/Conformal_map/CMakeLists.txt (CGAL-style CMake)
|
||||
Existing GTest tests remain; CGAL-format tests are added alongside.
|
||||
|
||||
8e Declarative YAML pipeline
|
||||
→ Lightweight YAML format for reproducible experiments
|
||||
(specification in doc/api/cgal-package.md)
|
||||
→ Validator: checks require/provide tokens before execution
|
||||
→ CLI integration: conformallab_core --pipeline experiment.yml
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## ◼ Remaining porting — Phase 9
|
||||
|
||||
Java features from `de.varylab.discreteconformal` not yet in C++:
|
||||
|
||||
```
|
||||
9a Inversive-distance functional (Luo 2004 / Bowers–Stephenson)
|
||||
→ inversive_distance_functional.hpp
|
||||
Follows the exact same pattern as the three existing functionals.
|
||||
→ newton_inversive_distance()
|
||||
→ New test suite: test_inversive_distance.cpp
|
||||
|
||||
9b Analytic HyperIdeal Hessian
|
||||
→ Replace FD Hessian in hyper_ideal_hessian.hpp
|
||||
Direct differentiation through the chain:
|
||||
(bᵢ, aₑ) → lᵢⱼ → ζ₁₃/ζ₁₄/ζ₁₅ → αᵢⱼ / βᵢ
|
||||
Relevant for meshes > 500 DOFs (current FD Hessian is slow there).
|
||||
|
||||
9c 4g-polygon boundary walk (genus g > 1)
|
||||
→ Extend compute_fundamental_domain() beyond genus 1
|
||||
Algorithm outline already in fundamental_domain.hpp as TODO(Phase 9).
|
||||
Java reference: FundamentalDomainUtility.java
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## ◼ New research — Phase 10+
|
||||
|
||||
No direct Java reference implementation exists for these items.
|
||||
|
||||
```
|
||||
Phase 10 Global uniformization for genus g ≥ 2
|
||||
|
||||
10a Discrete holomorphic differentials
|
||||
Integrate basis 1-forms ωᵢ along b-cycles of the cut graph.
|
||||
Mathematical basis: Bobenko–Springborn (2004), §6.
|
||||
Java partial reference: DiscreteHolomorphicFormUtility.java
|
||||
|
||||
10b Siegel period matrix Ω ∈ H_g (g×g complex symmetric, Im(Ω) > 0)
|
||||
Ωᵢⱼ = ∫_{bⱼ} ωᵢ
|
||||
Reduction to Siegel fundamental domain via Sp(2g,ℤ).
|
||||
Requires: 10a
|
||||
|
||||
10c Full uniformization for genus g ≥ 2
|
||||
Embedding as H²/Γ with Γ ⊂ PSL(2,ℝ) a Fuchsian group.
|
||||
Requires: 10a + 10b + stable cut graph for g ≥ 2 (Phase 9c)
|
||||
```
|
||||
Reference in New Issue
Block a user