refactor/api-naming-a1-a3
9 Commits
| Author | SHA1 | Message | Date | |
|---|---|---|---|---|
Tarik Moussa
|
330515ea90 |
docs(java-parity): P2/Matrix jReality notes + Phase 9c dependency warning
All checks were successful
C++ Tests / test-fast (pull_request) Successful in 2m20s
API Docs / doc-build (pull_request) Successful in 52s
Markdown link check / check (pull_request) Successful in 1m1s
C++ Tests / test-cgal (pull_request) Has been skipped
C++ Tests / quality-gates (pull_request) Successful in 2m24s
- Infrastructure table: add Matrix (→ Eigen inline, done) and P2 rows. P2 marked "port inline with Phase 9c" — almost exclusively consumed by FundamentalPolygon/CanonicalForm/SurfaceCurve (all Phase 9c), so building p2_geometry.hpp as a standalone ahead of 9c would be dead weight. - Phase 9c rows in the utility table: ⚠️ annotation listing the exact P2.* methods needed (makeDirectIsometryFromFrames, projectP3ToP2, imbedMatrixP2InP3) plus the P2Big/cpp_dec_float_50 high-precision prerequisite for the group-relation product ∏gᵢ = Id. Ensures a future Phase 9c session starts with full context and does not discover the jReality/precision dependencies mid-port. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> |
||
|
Tarik Moussa
|
149da15c64 |
feat(geometry): pn_geometry.hpp — Pn projective-metric substrate (jReality port)
Ports the small but pervasive de.jreality.math.Pn surface that the Java
algorithmic core uses across every not-yet-ported geometric phase:
HyperbolicLayout, SphericalLayout, FundamentalPolygon (9c), KoebePolyhedron
(10c'), quasi-isothermic (10e), hyperelliptic theta, CircleDomain (11c).
Porting it once unblocks all downstream consumers instead of re-deriving
the metric ad hoc per phase.
pn_geometry.hpp — header-only, Eigen, ~120 LOC:
PnMetric { EUCLIDEAN=0, ELLIPTIC=+1, HYPERBOLIC=-1 } matching jReality.
pn_inner_product — bilinear form per signature.
pn_norm / pn_dehomogenize / pn_set_to_length / pn_normalize.
pn_distance_between — Euclidean (spatial), elliptic (acos), hyperbolic (acosh).
pn_linear_interpolation — affine (E) and slerp (S/H constant-speed geodesic).
HYPERBOLIC uses the timelike-positive ("upper-sheet") convention, identical to
the already-verified projective_math.hpp::hyperbolicDistance; pn_distance_between
is regression-anchored against it in the tests.
test_pn_geometry.cpp — 6 tests, all GREEN:
InnerProductSignatures, EuclideanDistance, EllipticDistanceIsAngle,
HyperbolicDistanceClosedFormAndAnchor (+ projective_math.hpp anchor),
NormAndScaling, LinearInterpolationGeodesic.
doc/roadmap/java-parity.md — new "Infrastructure / support layers" section:
de.jreality.math.Pn → pn_geometry.hpp (partial, 6 fns covering core usage)
de.jreality.math.Rn → Eigen (no separate port needed)
MatrixBuilder → not yet (only needed for hyperelliptic theta)
conformallab XML types → not planned (GUI persistence, not algorithmic)
246/246 cgal tests pass.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
|
||
|
Tarik Moussa
|
ca936b7652 |
docs: note high-precision requirement for Phase 9c/10 uniformization
Some checks failed
C++ Tests / test-fast (pull_request) Successful in 2m0s
API Docs / doc-build (pull_request) Successful in 53s
Markdown link check / check (pull_request) Successful in 54s
C++ Tests / test-cgal (pull_request) Has been skipped
C++ Tests / quality-gates (pull_request) Failing after 2m14s
The Java uniformization classes (FundamentalPolygonUtility, CanonicalFormUtility) rely on the *Big arbitrary-precision geometry (MathContext(50)) because products of hyperbolic isometry generators grow exponentially and double fails to verify the group relation ∏gᵢ = Id. Record this planning-relevant prerequisite and resolve the contradiction in java-parity.md, which previously listed *Big as permanently out of scope. - CLAUDE.md: † note on the Phase-9 not-yet-ported table - java-parity.md: *Big exception (localized high-precision substrate for 9c/10) - phases.md: precision prerequisite as 9c sub-task + effort estimate - design-decisions.md: new "Scalar type: double, with one localized exception" Core flattening (Newton/energy/Eigen solver) stays double; the substrate (cpp_dec_float_50 / mpreal) is localized to the uniformization module only. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com> |
||
|
Tarik Moussa
|
1ff5382c8b |
docs: record 2026-05-28 full-library scan findings in roadmap
Some checks failed
C++ Tests / test-fast (pull_request) Successful in 1m55s
API Docs / doc-build (pull_request) Successful in 53s
Markdown link check / check (pull_request) Successful in 1m1s
C++ Tests / test-cgal (pull_request) Has been skipped
C++ Tests / quality-gates (pull_request) Failing after 2m3s
Cross-referenced all 232 Java classes against the roadmap. New plan entries for genuinely-useful, previously-unplanned items: - 9g.1 conformal quality measures (Isothermicity, ConformalEquivalence, FlippedTriangles, LengthCrossRatio + ConvergenceUtility metrics) - 9g.2 optional period-matrix convergence experiment (method only; Java harness depends on Mathematica/JLink + jReality, not ported) - DEC operator layer (heds/dec/) noted as a 10a prerequisite - HomotopyUtility -> 10a (explicit generator cycles; not covered by cut_graph.hpp, which yields only the 2g cut edges) - SurfaceCurveUtility -> 9c; MercatorTextureProjection -> 9d.3 companion Documented as deliberately out-of-scope: SpanningTreeUtility (subsumed by cut_graph.hpp), convergence/* harness, datasource/* (jReality viewer decoration), *Big arbitrary-precision geometry, jReality GUI, and the MTJ/Tao/PETSc solver bindings. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com> |
||
|
Tarik Moussa
|
068df474b1 |
docs: integrate publication analysis — Alexa, Bobenko, Springborn, Crane, Lutz
Add phases 9d / 9e / 9f and literature citations derived from a systematic
review of the five authors' publication lists (Tier 1 / 2 / 3 analysis).
phases.md:
- Phase 9d: ConesUtility port (9d.1) + non-Euclidean cone extensions
(9d.2, RESEARCH) + StereographicUnwrapper (9d.3)
- Phase 9e: CirclePatternLayout + CirclePatternUtility (Java port)
- Phase 9f: Polygon Laplacian on non-triangular meshes (Alexa 2011/2020,
RESEARCH — no Java equivalent)
- Phase 9b-analytic: add Rivin-Springborn 1999 as Schläfli source
- Phase 10b: add Bobenko-Bücking 2009 + Bobenko-Lutz 2024 IMRN
- Phase 10c: add Lutz 2023 (canonical tessellations) + Bobenko-Lutz 2024
- Phase 10c' KoebePolyhedron: add Bowers-Bowers-Lutz 2026 rigidity result
references.md:
- Crane et al. 2018 Optimal Cone Singularities (Phase 9d.2)
- Bobenko-Lutz 2025 Discrete & Comput. Geom. (Phase 9d.2)
- Bobenko-Lutz 2024 IMRN (Phase 10b/c)
- Lutz 2023 Geom. Dedicata (Phase 10c)
- Lutz PhD thesis TU Berlin 2024 (Phases 9d.2, 10b, 10c)
- Bowers-Bowers-Lutz 2026 (Phase 9b-analytic + 10c')
- Alexa-Wardetzky 2011 + Alexa 2020 (Phase 9f)
- Bobenko-Bücking 2009 (Phase 10b)
- Rivin-Springborn 1999 (Phase 9b-analytic)
research-track.md:
- New entry: Phase 9d.2 non-Euclidean cone extensions (Bobenko-Lutz 2025
+ Crane 2018), with acceptance criteria
- New entry: Phase 9f polygon Laplacian (Alexa-Wardetzky 2011 / Alexa 2020),
with acceptance criteria
java-parity.md:
- Split cone-metrics row into Euclidean (9d.1 port) and non-Euclidean
(9d.2 research) with literature references
- Add ConesUtility to "utility classes not yet ported" table
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
|
||
|
Tarik Moussa
|
8e9ec9eccf |
docs: full Java library scan — new phases 9d/9e/10d–10g + parity table
Complete scan of all de.varylab.discreteconformal packages (functional/, unwrapper/, unwrapper/circlepattern/, unwrapper/koebe/, unwrapper/quasiisothermic/, uniformization/, util/) against the current roadmap. New items added to java-parity.md: - ConesUtility: cone detection, BFS cut, auto-placement, quantization (9d) - MobiusCenteringFunctional: variational Lösung über Lorentz-Geometrie (9d) - ElectrostaticSphereFunctional: Initialisierungsheuristik auf S² (9d) - StereographicUnwrapper + SphereUtility: S²→ℂ atlas für genus-0 (9d) - CirclePatternLayout + CirclePatternUtility + CPEuclideanRotation (9e) - CutAndGlueUtility, StitchingUtility, PathUtility (9c additions) - DualityUtility: Hodge-Stern + dual cycles — prerequisite 10a - HyperellipticUtility + HyperIdealHyperellipticUtility (10b) - CircleDomainUnwrapper: Koebe-Andreev-Thurston (10d) - quasiisothermic/ package: QI maps + DBF + sin-condition (10e) - KoebePolyhedron (10f) - EuclideanCyclicFunctional + HyperbolicCyclicFunctional (10g) - "Do not port" table: ColtIterationReporter, PETSc wrappers, etc. New phases added to phases.md: - Phase 9d: ConesUtility + StereographicUnwrapper + MobiusCenteringFunctional - Phase 9e: CirclePatternLayout (complement to already-ported 9a.1) - Phase 10d: CircleDomainUnwrapper (Koebe-Andreev-Thurston) - Phase 10e: quasi-isothermic maps - Phase 10f: Koebe polyhedra - Phase 10g: cyclic-symmetry functionals Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> |
||
|
Tarik Moussa
|
ff9c9ec11b |
docs: add StereographicUnwrapper + CircleDomainUnwrapper to roadmap
Audit found that 2 of the 4 Java-port candidates from the conformal-
mapping discussion were missing from the documentation:
* StereographicUnwrapper (266 Java LoC) — projects spherical layout
S² → ℂ via stereographic projection + Möbius centring. Closes the
visualisation gap from discrete_conformal_map_spherical() which
currently returns Point_3 on S²; downstream uses typically want a
2-D atlas. Suggested phase: 10b' (alternative methods, parallel
to Hyperbolic / Quasi-isothermic). Effort: small (~3 days).
* CircleDomainUnwrapper (570 Java LoC) — conformal map of a
multiply-connected planar region onto a disk-with-holes (Koebe's
general uniformization theorem 1909). A use-case class
conformallab++ does not currently cover (annulus, slit torus,
fluid flow around obstacles, electrostatics with multiple
conductors). Suggested phase: 11c. Effort: large (~2 weeks).
Added to all three roadmap documents:
* doc/roadmap/java-parity.md — worth-porting table extended
* doc/roadmap/research-track.md — Java-backlog summary extended
* doc/roadmap/phases.md — Phase 10b' bullet + new
Phase 11c block with full math
context (Koebe 1909 reference,
classical complex-analysis use cases).
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
|
||
|
Tarik Moussa
|
4f0a3035e4 |
docs: full audit — fix 4 wrong port/research labels + consolidated research-track
Some checks failed
C++ Tests / test-fast (push) Successful in 2m50s
C++ Tests / test-fast (pull_request) Successful in 2m36s
API Docs / doc-build (pull_request) Successful in 1m10s
C++ Tests / test-cgal (push) Has been skipped
C++ Tests / test-cgal (pull_request) Failing after 10m25s
A full audit of `doc/` plus root-level markdown files (27 files) against
the actual ground truth in the C++ code and the local Java repository at
`/Users/tarikmoussa/Desktop/conformallab/` revealed four pre-existing
mis-labels and a stale test count. All are corrected here.
Audit findings — corrected
─────────────────────────
1. **`InversiveDistanceFunctional` mis-labelled as Java port** (4 doc sites)
Empirical verification:
find /Users/tarikmoussa/Desktop/conformallab -iname "*nversive*"
(zero matches)
The class does NOT exist in `de.varylab.discreteconformal`. The C++
implementation is built from Luo 2004 + Glickenstein 2011 + Bowers-
Stephenson 2004 — new research, not a port.
Fixed in: java-parity.md, references.md, add-inversive-distance.md.
2. **HyperIdeal Hessian mis-labelled as "Java has analytic Hessian"**
Empirical verification: `HyperIdealFunctional.java:295-298`:
public boolean hasHessian() { return false; }
Java has NO Hessian at all. Both the FD (Phase 4a) and the block-FD
(Phase 9b) Hessians in C++ are research beyond the Java port. The
chain rule (b,a) → ℓ → ζ → α/β is the *mathematical formulation*
from Springborn 2020, not something Java implements.
Fixed in: java-parity.md.
3. **Stale test count** README:87 said "28 suites, 170 tests" — current
actual is 35 suites, 176 CGAL + 36 non-CGAL. Fixed.
4. **Tutorial framing** — `add-inversive-distance.md` was framed as
"porting an InversiveDistanceFunctional.java" that does not exist.
Rewritten as "Implementing the Inversive-Distance functional from
Luo 2004" with prominent verification block at top.
New document: `doc/roadmap/research-track.md`
─────────────────────────────────────────────
Consolidates everything in conformallab++ that goes beyond a Java port:
* Items already on `main`: HyperIdeal FD Hessian, period matrix τ
partial-research components, Möbius holonomy storage.
* Items on open PRs: CP-Euclidean (PR #8, port), Inversive-Distance
(PR #8, research), block-FD Hessian (PR #9, research).
* Planned research with full citations:
- **Phase 9b-analytic** — full analytic HyperIdeal Hessian via
Schläfli identity (Schläfli 1858/60) and chain rule through
ζ₁₃/ζ₁₄/ζ₁₅, citing Springborn 2020 §4, Cho-Kim 1999,
Glickenstein 2011 §4. Includes acceptance-criteria checklist
(per-case derivative cross-checks, gauge null space, PSD,
measured ≥ 3× speed-up, LaTeX correctness note).
- **Phase 9a.2-analytic** — analytic inversive-distance Hessian
via Glickenstein 2011 eq. (4.6).
- **Phase 10c** — full uniformization for genus g ≥ 2 (Fuchsian
group representation) — fully new research, no Java reference.
- **geometry-central** GC-1/2/3 exploratory track.
* Java backlog summary: 11 worth-porting Java classes identified by
the parallel survey (FundamentalPolygonUtility, DiscreteHarmonicForm-
Utility, DiscreteHolomorphicFormUtility, CanonicalBasisUtility,
HyperbolicCyclicFunctional, QuasiisothermicUtility, KoebePolyhedron, …).
~6 500 Java lines, ~5 months of porting work, organised by phase.
Updated documents
─────────────────
* CLAUDE.md
- New "Port-vs-research maintenance rule" with empirical verification
command and the four corrected mis-labels.
- Doc map: 23 → 24 documents (research-track.md added).
* README.md
- Test count corrected (170 → 176+36).
* doc/math/references.md
- Luo 2004 entry corrected ("new research" instead of "not yet ported").
- New entries for Bowers-Stephenson 2004, Glickenstein 2011,
Bobenko-Pinkall-Springborn 2010, Schläfli 1858/60.
* doc/roadmap/phases.md
- Phase 9 reorganised: 9a split into 9a.1 (port) / 9a.2 (research),
9b clarified as research (Java has no Hessian), 9c expanded with
Java line counts and effort estimates.
- Phase 10 reorganised: 10a/10b/10c with their Java prerequisites
explicitly listed; 10c flagged as "fully new research".
- Phase 10b' added: parallel research track (hyperbolic functional,
quasi-isothermic, Möbius centering).
- Phase 10c' added: optional Java-port additions (Koebe, circle
patterns, electrostatic sphere).
* doc/roadmap/java-parity.md
- Inversive-distance row: ❌ Java, ❌ C++ (Phase 9a.2) — new research.
- CP-Euclidean row added: ✅ Java, ❌ C++ (Phase 9a.1) — port.
- HyperIdeal Hessian row: ❌ Java, ⚠️ FD + block-FD in C++.
- Worth-porting table replaced with the survey results (12 classes,
Java line counts, suggested phases).
- "HyperIdeal Hessian: FD vs analytic" section rewritten with the
correction notice.
* doc/tutorials/add-inversive-distance.md
- Rewritten end-to-end with prominent verification block at top.
- Now correctly framed as "Implementing the Inversive-Distance
functional from Luo 2004" — research, not port.
- Includes the four required cross-validations:
limit cases, Bowers-Stephenson round-trip, FD-vs-analytic,
cross-validation against euclidean_functional at u=0.
- New "How to know if it's a port or research" closing section
with the empirical verification command.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
|
||
|
Tarik Moussa
|
14134b99ce |
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> |