From 1ff5382c8bd06d4c282e8e631b5366eba0eac5a8 Mon Sep 17 00:00:00 2001 From: Tarik Moussa Date: Thu, 28 May 2026 06:53:09 +0200 Subject: [PATCH] docs: record 2026-05-28 full-library scan findings in roadmap 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 --- doc/roadmap/java-parity.md | 24 ++++++++++++ doc/roadmap/phases.md | 79 +++++++++++++++++++++++++++++++++++++- 2 files changed, 102 insertions(+), 1 deletion(-) diff --git a/doc/roadmap/java-parity.md b/doc/roadmap/java-parity.md index d7beaaa..dd357f7 100644 --- a/doc/roadmap/java-parity.md +++ b/doc/roadmap/java-parity.md @@ -58,6 +58,7 @@ They are candidates for Phase 9 or Phase 10. | `DiscreteHarmonicFormUtility` (657 lines) | Discrete harmonic 1-forms via cotangent Laplacian (Hodge theory) | 10a prerequisite | | `DiscreteHolomorphicFormUtility` (285 lines) | Holomorphic differentials via Mercat complex structure | 10a (Bobenko-Springborn 2004 §6) | | `CanonicalBasisUtility` (337 lines) | Symplectic homology basis with intersection-form normalisation | 10a prerequisite | +| `HomotopyUtility` (57 lines) | Reconstructs explicit generator cycles (bridge + tree path) — NOT covered by `cut_graph.hpp` (which gives only the 2g cut edges). Verified 2026-05-28. | 10a | | `DiscreteRiemannUtility` (186 lines) | Period matrix τ, Siegel reduction (genus g) | 10b | | `DualityUtility` (308 lines), `HomologyUtility` (122 lines) | Primal/dual cohomology, cycle generators | 10a support | | `HyperbolicCyclicFunctional` (530 lines) | Discrete hyperbolic conformal energy (analogue of Euclidean) — completes the geometry suite | 10b–c | @@ -66,10 +67,30 @@ They are candidates for Phase 9 or Phase 10. | `StereographicUnwrapper` (266 lines) | Stereographic projection S²→ℂ + Möbius centring — converts the Spherical-DCE output into a 2-D atlas | 10b' (Sphere visualisation) | | `CircleDomainUnwrapper` (570 lines) | Conformal map of a multiply-connected planar region onto a disk-with-holes — classical complex-analysis use case | 11+ (new use-case class) | | `ElectrostaticSphereFunctional`, `MobiusCenteringFunctional` | Sphere-domain pre-processing functionals | 10c (optional) | +| `IsothermicityMeasure` (113), `DiscreteConformalEquivalencemMeasure` (82), `FlippedTriangles` (17), `LengthCrossRatio` (12) | Quantitative conformal-quality / embedding-validity measures (math is GUI-independent) | **9g** (added 2026-05-28) | +| `DEC`, `AbstractDECOperator`, `DECPairing`, `DualChain`, `DualForm` (`heds/dec/`) | Discrete-exterior-calculus operator layer (d / ⋆ / pairing) — foundation the Phase-10a form utilities sit on | **10a prerequisite** (added 2026-05-28) | +| `SurfaceCurveUtility` (360) | Curve operations on the surface (cut-path tracing) — supports 9c polygon construction | **9c** (added 2026-05-28) | Note: items marked as *new research* (e.g. Inversive Distance, HyperIdeal Hessian variants) are tracked separately in `doc/roadmap/research-track.md`. +### 2026-05-28 scan — valuable items that had been in *no* phase + +A class-by-class cross-reference of all 232 Java production classes against the +roadmap found that the "big math" (Schottky 11a, Koebe 10c′/10f, quasi-isothermic +10e, circle-pattern layout 9e) is all already planned. Three genuinely useful +items were unrecorded and have now been added above: +1. **Conformal-quality measures** → new **Phase 9g** (small, no dependencies; raises + validation coverage for the already-shipped pipeline). +2. **DEC operator layer** (`heds/dec/`) → noted as a **Phase 10a prerequisite** (the + form utilities assume these primitives exist). +3. **`SurfaceCurveUtility`** → folded into the **Phase 9c** source list. + +Everything else unmentioned is intentionally out of scope: the `plugin/*` jReality +Swing GUI, the `MTJ*`/`Tao*`/`*PETSc` solver bindings (replaced by Eigen), the +convergence/`*Series` test harness, and the `*Big` arbitrary-precision geometry +(`P2Big`/`PnBig`/`RnBig` — deliberately dropped in favour of `Simple_cartesian`). + --- ## Java packages not yet in the roadmap — 2026 full-library scan @@ -154,6 +175,9 @@ Entirely absent from the current roadmap. | `EuclideanUnwrapperPETSc` / `SphericalNormalizerPETSc` | PETSc solver binding — replaced by Eigen | | `Search` | CoHDS-specific graph search — replaced by CGAL halfedge iteration | | `SparseUtility` | Colt sparse matrix utils — replaced by Eigen | +| `SpanningTreeUtility` | Primal + dual spanning tree — already implemented inline in `cut_graph.hpp` (tree-cotree Steps 1+2). Verified 2026-05-28. | +| `convergence/*` harness (CLI driver, ~1400 lines) | The driver depends on Mathematica (JLink) + jReality OBJ reader + LoopLinear. Do not port the harness — only its math: quality measures → 9g.1, study method → 9g.2 (optional). Verified 2026-05-28. | +| `datasource/*` (`ConicalEdgesDataSource`, `CylinderEdgesDataSource`) | jReality SceneGraph viewer decoration (draws cone/cylinder edge arcs) — NOT example geometry; nothing to harvest. Verified 2026-05-28. | --- diff --git a/doc/roadmap/phases.md b/doc/roadmap/phases.md index 0f991cd..ae311f1 100644 --- a/doc/roadmap/phases.md +++ b/doc/roadmap/phases.md @@ -124,6 +124,10 @@ mesh type. Java sources: FundamentalPolygonUtility.java (698 lines) + CanonicalFormUtility.java (532 lines) + CuttingUtility / SurgeryUtility (~800 lines) + + SurfaceCurveUtility.java (360 lines, 2026-05-28 + scan) — curve operations on the surface (cut-path + tracing / fundamental-domain boundary); supporting + infrastructure for the polygon construction. Mathematical source: Poincaré 1882 + Sechelmann 2016 §5 Research component: bridging to conformallab++ cut_graph.hpp + holonomy infrastructure. @@ -164,6 +168,15 @@ mesh type. Stereographic projection S²→ℂ∪{∞} + Möbius centering for genus-0 surfaces. Converts spherical DCE output to a flat 2-D atlas. Java reference: unwrapper/StereographicUnwrapper.java (266 lines) + Note (2026-05-28 visualisation scan): plugin/algorithm/ + StereographicTextureProjection.java (88 lines) is the texture + front-end of this same math — no separate item. The supporting + math/CP1 + ComplexUtility.stereographic are deliberately NOT + ported (redundant with std::complex + the existing MobiusMap, + see porting-status.md). + Optional companion: MercatorTextureProjection.java (47 lines) — + a distinct cylindrical conformal display projection; small + nice-to-have for the sphere-visualisation bucket, not required. 9d.4 MobiusCenteringFunctional (Java port, optional upgrade) → integrate into layout.hpp normalise_hyperbolic() @@ -210,6 +223,59 @@ mesh type. Replaces euclidean_hessian.hpp for non-triangular inputs. Status: 🔲 planned (pure research, no Java source) Effort: medium (~2 weeks core + tests; +1 week Newton integration). + +9g — Conformal quality measures (Java port — 2026-05-28 scan) +────────────────────────────────────────────────────────────────── + +9g.1 Quantitative correctness metrics for a computed conformal map + → conformal_quality.hpp + Lifts the measure math out of the jReality plugin + convergence + layers (the math is GUI-independent). High value / low effort: + these directly strengthen the validation story for the already- + shipped genus-0/1 pipeline (doc/math/validation.md). + - IsothermicityMeasure (113 lines) — pointwise deviation + from conformality (anisotropy of the induced metric). + - DiscreteConformalEquivalencemMeasure (82 lines) — per-edge + length-cross-ratio residual vs. the conformal-equivalence + condition. + - FlippedTriangles (17 lines) — detects inverted / + degenerate triangles in a 2-D layout (embedding-validity check). + - LengthCrossRatio (12 lines) — the discrete conformal + invariant itself (per-edge), shared input for the two measures. + - ConvergenceUtility measures (~110 lines, math/float only — no + Mathematica/jReality deps): getMaxMeanSumCrossRatio + (q=(a·c)/(b·d), qfun=(q+1/q)/2−1), getMaxMeanSumMultiRatio + (per-face product, =1 iff conformal), and + getMaxMeanSumScaleInvariantCircumRadius (R/√A, scale-invariant + mesh-quality). The operational counterpart of LengthCrossRatio. + Java references: + plugin/visualizer/IsothermicityMeasure.java + plugin/visualizer/DiscreteConformalEquivalencemMeasure.java + plugin/visualizer/FlippedTriangles.java + heds/adapter/types/LengthCrossRatio.java + convergence/ConvergenceUtility.java + Mathematical reference: Springborn-Schröder-Pinkall 2008 + (length cross-ratio = discrete conformal invariant). + Status: 🔲 planned (Java port; no new theory). + Effort: small (~3 days incl. gradient-free tests). No + dependencies — can land before 9a–9f. + +9g.2 Period-matrix convergence study (validation experiment — optional) + → tests/cgal/test_period_matrix_convergence.cpp (experiment, not + a library feature) + Empirical validation for the already-shipped period_matrix.hpp + + discrete_elliptic_utility.hpp: generate a genus-1 elliptic mesh + with a known analytic τ, then refine / subdivide / add Gaussian + vertex noise and plot |τ_computed − τ_expected| → 0. + Java reference: convergence/* (~1400 lines) — a CLI harness + (joptsimple) that drives the same study. Do NOT port the + harness: it depends on Mathematica via JLink and on jReality's + OBJ reader + LoopLinear subdivision. Port only the *method*: + - subdivision → igl::loop (libigl already available) + - noise → trivial (vᵢ += σ·N(0,1)) + - error metric → the 9g.1 quality measures + τ residual + Status: 🔲 optional (raises empirical confidence in genus-1 τ; + no new library surface). Effort: small (~2–3 days). ``` --- @@ -332,10 +398,21 @@ Phase 10 Global uniformization for genus g ≥ 2 Java sources (partial, port-with-research): CanonicalBasisUtility.java 337 lines (homology basis) HomologyUtility.java 122 lines + HomotopyUtility.java 57 lines (2026-05-28 scan) — + reconstructs the explicit generator *cycles* (bridge edge + + tree path via HomologyUtility.findCycle). NOT covered by + cut_graph.hpp, which yields only the 2g cut *edges*; the closed + loops are needed to integrate 1-forms along b-cycles. DualityUtility.java 308 lines DiscreteHarmonicFormUtility.java 657 lines DiscreteHolomorphicFormUtility.java 285 lines - Effort: ~6 weeks net (4 utility ports + 1 integration). + Prerequisite — DEC operator layer (2026-05-28 scan, previously + unrecorded): the four utilities above are built on the discrete- + exterior-calculus primitives in heds/dec/ (DEC.java 76 lines, + AbstractDECOperator, DECPairing, DualChain, DualForm — the d / ⋆ / + primal-dual pairing operators). Port this thin operator layer + first; the form utilities assume it exists. Effort: ~3 days. + Effort: ~6 weeks net (1 DEC layer + 4 utility ports + 1 integration). 10b Siegel period matrix Ω ∈ H_g (g×g complex symmetric, Im(Ω) > 0) → Ωᵢⱼ = ∫_{bⱼ} ωᵢ