feat(phase7): Java-parity layout — priority BFS, halfedge_uv, Möbius holonomy, period matrix, fundamental domain — 158 tests
Phase 7 adds seven features ported from the original Java ConformalLab:
layout.hpp
- Priority BFS (min-heap on BFS depth) replaces FIFO queue, minimising
trilateration error accumulation from the root face outward.
- MobiusMap struct: T(z)=(az+b)/(cz+d), identity/inverse/compose,
from_three (3×3 complex least-squares fit), apply(Vector2d).
- halfedge_uv[h.idx()] = UV of source(h) in face(h); seam halfedges
carry the virtual unfolded position, enabling proper GPU texture atlases.
- Hyperbolic holonomy stored as MobiusMap per cut edge (SU(1,1) isometry).
- best_root_face: largest 3-D area face, 1.5× interior bonus.
- normalise_euclidean also transforms halfedge_uv (centroid + PCA).
- Face-area-weighted iterative Möbius centering (Fréchet mean, Phase 7).
period_matrix.hpp (new)
- PeriodData: lattice generators ω_i as complex numbers, τ = ω₂/ω₁ ∈ ℍ.
- reduce_to_fundamental_domain: SL(2,ℤ) reduction via alternating S/T steps.
- is_in_fundamental_domain, compute_period_matrix.
- NOTE: Siegel matrix Ω for genus g>1 intentionally deferred.
fundamental_domain.hpp (new)
- FundamentalDomain: CCW parallelogram {0, ω₁, ω₁+ω₂, ω₂} for genus 1.
- edge_identifications, generators stored.
- 4g-polygon boundary-walk for g>1 marked TODO(Phase 8) with full algorithm
outline and literature references.
- tiling_copy / tiling_neighbourhood for universal cover visualisation.
Tests: 121 → 158 (+37 Phase 7 tests covering all new features).
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
Tarik Moussa
204
code/include/fundamental_domain.hpp
Normal file
204
code/include/fundamental_domain.hpp
Normal file
@@ -0,0 +1,204 @@
|
||||
#pragma once
|
||||
// fundamental_domain.hpp
|
||||
//
|
||||
// Phase 7 — Fundamental domain polygon for closed surfaces.
|
||||
//
|
||||
// For a closed genus-g surface cut open via a CutGraph + Euclidean layout:
|
||||
//
|
||||
// The universal cover is tiled by copies of the cut-open disk.
|
||||
// The fundamental domain is the polygon whose sides are identified in pairs
|
||||
// by the holonomy generators.
|
||||
//
|
||||
// ─── Genus-1 (flat torus) ────────────────────────────────────────────────────
|
||||
//
|
||||
// Parallelogram with vertices 0, ω_1, ω_1 + ω_2, ω_2.
|
||||
// The four edges are identified in pairs:
|
||||
// bottom (0 → ω_1) ≡ top (ω_2 → ω_1 + ω_2) — translation ω_2
|
||||
// left (0 → ω_2) ≡ right (ω_1 → ω_1 + ω_2) — translation ω_1
|
||||
//
|
||||
// ─── Genus g > 1 (general) ──────────────────────────────────────────────────
|
||||
//
|
||||
// The standard 4g-polygon with sides labelled a_1 b_1 a_1^{-1} b_1^{-1} ...
|
||||
// can be recovered from the layout boundary, but requires walking the
|
||||
// boundary of the cut-open mesh — not yet implemented (see note below).
|
||||
//
|
||||
// For now, this file provides the genus-1 parallelogram only.
|
||||
// The polygon vertices for genus-1 are computed from the holonomy generators.
|
||||
//
|
||||
// ─── API ─────────────────────────────────────────────────────────────────────
|
||||
//
|
||||
// FundamentalDomain fd = compute_fundamental_domain_genus1(holonomy);
|
||||
// fd.vertices — 2D polygon corners (size = 4 for genus-1)
|
||||
// fd.edge_identifications — pairs (i, j) meaning edge i is identified with j
|
||||
// fd.is_valid() — true if genus == 1 and data makes sense
|
||||
|
||||
#include "layout.hpp"
|
||||
#include "period_matrix.hpp"
|
||||
#include <vector>
|
||||
#include <utility>
|
||||
|
||||
namespace conformallab {
|
||||
|
||||
// ─────────────────────────────────────────────────────────────────────────────
|
||||
// FundamentalDomain
|
||||
// ─────────────────────────────────────────────────────────────────────────────
|
||||
|
||||
struct FundamentalDomain {
|
||||
/// Polygon corners in order (CCW). Size = 4 for genus-1.
|
||||
std::vector<Eigen::Vector2d> vertices;
|
||||
|
||||
/// edge_identifications[k] = (i, j) means the edge from vertices[i] to
|
||||
/// vertices[(i+1) % n] is identified with the edge from vertices[j] to
|
||||
/// vertices[(j+1) % n] (with matching orientation).
|
||||
std::vector<std::pair<int, int>> edge_identifications;
|
||||
|
||||
/// Holonomy generators (one per identified edge pair).
|
||||
/// For genus-1: generators[0] = ω_1, generators[1] = ω_2.
|
||||
std::vector<Eigen::Vector2d> generators;
|
||||
|
||||
bool is_valid() const { return vertices.size() >= 3; }
|
||||
};
|
||||
|
||||
// ─────────────────────────────────────────────────────────────────────────────
|
||||
// compute_fundamental_domain_genus1
|
||||
//
|
||||
// Builds the parallelogram fundamental domain from Euclidean holonomy data
|
||||
// with exactly 2 generators ω_1, ω_2.
|
||||
//
|
||||
// Vertices (CCW):
|
||||
// v0 = (0, 0)
|
||||
// v1 = ω_1
|
||||
// v2 = ω_1 + ω_2
|
||||
// v3 = ω_2
|
||||
//
|
||||
// Edge identifications:
|
||||
// bottom (v0→v1) ≡ top (v3→v2) by ω_2
|
||||
// left (v3→v0) ≡ right (v2→v1) by ω_1 (reversed convention)
|
||||
// ─────────────────────────────────────────────────────────────────────────────
|
||||
inline FundamentalDomain compute_fundamental_domain_genus1(
|
||||
const HolonomyData& hol)
|
||||
{
|
||||
FundamentalDomain fd;
|
||||
if (hol.translations.size() < 2) return fd;
|
||||
|
||||
Eigen::Vector2d w1 = hol.translations[0];
|
||||
Eigen::Vector2d w2 = hol.translations[1];
|
||||
|
||||
// Ensure CCW orientation: cross product z-component w1 × w2 > 0
|
||||
double cross = w1.x() * w2.y() - w1.y() * w2.x();
|
||||
if (cross < 0.0) std::swap(w1, w2);
|
||||
|
||||
Eigen::Vector2d origin = Eigen::Vector2d::Zero();
|
||||
fd.vertices = { origin, w1, w1 + w2, w2 };
|
||||
|
||||
// Edge 0: v0→v1 (= bottom), Edge 2: v3→v2 (= top, reversed)
|
||||
// Identification: bottom ≡ top translated by w2
|
||||
// Edge 1: v1→v2 (= right), Edge 3: v0→v3... wait let me use standard labeling:
|
||||
// Edges by index: 0: v0→v1, 1: v1→v2, 2: v2→v3, 3: v3→v0
|
||||
// Identifications: 0 ≡ 2 (reversed: bottom ≡ top by w2)
|
||||
// 1 ≡ 3 (reversed: right ≡ left by w1)
|
||||
fd.edge_identifications = { {0, 2}, {1, 3} };
|
||||
fd.generators = { w1, w2 };
|
||||
return fd;
|
||||
}
|
||||
|
||||
// ─────────────────────────────────────────────────────────────────────────────
|
||||
// compute_fundamental_domain
|
||||
//
|
||||
// Dispatcher: for genus-1 uses compute_fundamental_domain_genus1.
|
||||
// For higher genus returns an empty FundamentalDomain (not yet implemented).
|
||||
// ─────────────────────────────────────────────────────────────────────────────
|
||||
//
|
||||
// TODO(Phase 8): Implement the standard 4g-gon fundamental domain for genus g > 1.
|
||||
//
|
||||
// Algorithm outline (boundary-walk method):
|
||||
// ─────────────────────────────────────────
|
||||
// 1. Construct the CutGraph on the cut-open mesh (already done upstream).
|
||||
// This yields 2g cut edges; cutting them converts the closed surface into
|
||||
// a topological disk.
|
||||
//
|
||||
// 2. Walk the boundary of the cut-open disk in CCW order:
|
||||
// Start from any boundary halfedge and follow `next(h)` along the boundary
|
||||
// (i.e. skip to the next boundary halfedge at each vertex). Collect the
|
||||
// 2·(4g) = 8g boundary halfedges in order.
|
||||
// Each halfedge h_k corresponds to a UV vertex `halfedge_uv[h_k.idx()]`.
|
||||
//
|
||||
// 3. Identify paired sides:
|
||||
// The 4g sides of the polygon alternate as a_1 b_1 a_1^{-1} b_1^{-1} …
|
||||
// For each cut edge e_i (i = 1 … 2g) the two sides that are identified
|
||||
// are those whose source/target vertices match under the holonomy generator
|
||||
// ω_i (Euclidean) or T_i (hyperbolic).
|
||||
// Record the identifications as edge_identifications[k] = (i, j).
|
||||
//
|
||||
// 4. Fill FundamentalDomain:
|
||||
// vertices = UV corners from the boundary walk.
|
||||
// edge_identifications = paired-edge list from step 3.
|
||||
// generators = holonomy.translations (Euclidean) or the
|
||||
// fixed points of holonomy.mobius_maps (hyperbolic,
|
||||
// requires computing axis of T_i ∈ SU(1,1)).
|
||||
//
|
||||
// References:
|
||||
// Erickson & Whittlesey, "Greedy optimal homotopy and homology generators"
|
||||
// SODA 2005.
|
||||
// Desbrun, Kanso, Tong, "Discrete Differential Forms for Computational
|
||||
// Modeling", in Discrete Differential Geometry (2008).
|
||||
//
|
||||
// Note: The Siegel period matrix Ω ∈ H_g (g×g complex symmetric, Im Ω > 0)
|
||||
// for genus g > 1 also requires integration of holomorphic differentials —
|
||||
// this is intentionally deferred and NOT implemented here.
|
||||
// See period_matrix.hpp for the genus-1 case (τ = ω_2/ω_1 ∈ ℍ).
|
||||
// ─────────────────────────────────────────────────────────────────────────────
|
||||
inline FundamentalDomain compute_fundamental_domain(
|
||||
const HolonomyData& hol)
|
||||
{
|
||||
int n = static_cast<int>(hol.translations.size());
|
||||
int g = n / 2;
|
||||
if (g == 1) return compute_fundamental_domain_genus1(hol);
|
||||
// Higher genus: boundary-walk 4g-polygon — not yet implemented (see TODO above).
|
||||
return FundamentalDomain{};
|
||||
}
|
||||
|
||||
// ─────────────────────────────────────────────────────────────────────────────
|
||||
// tiling_copy
|
||||
//
|
||||
// Given a Layout2D for the cut-open surface and two lattice generators ω_1, ω_2,
|
||||
// return a translated copy of the layout shifted by m·ω_1 + n·ω_2.
|
||||
// Useful for visualising the tiled universal cover.
|
||||
// ─────────────────────────────────────────────────────────────────────────────
|
||||
inline Layout2D tiling_copy(const Layout2D& layout,
|
||||
const Eigen::Vector2d& w1,
|
||||
const Eigen::Vector2d& w2,
|
||||
int m, int n)
|
||||
{
|
||||
Layout2D copy = layout;
|
||||
Eigen::Vector2d shift = static_cast<double>(m) * w1
|
||||
+ static_cast<double>(n) * w2;
|
||||
for (auto& p : copy.uv) p += shift;
|
||||
return copy;
|
||||
}
|
||||
|
||||
// ─────────────────────────────────────────────────────────────────────────────
|
||||
// tiling_neighbourhood
|
||||
//
|
||||
// Returns a vector of tiling copies for (m, n) with |m| ≤ m_max, |n| ≤ n_max.
|
||||
// The result includes the original (m=0, n=0) at index (m_max)(2*n_max+1)+n_max.
|
||||
// ─────────────────────────────────────────────────────────────────────────────
|
||||
inline std::vector<Layout2D> tiling_neighbourhood(
|
||||
const Layout2D& layout,
|
||||
const HolonomyData& hol,
|
||||
int m_max = 2, int n_max = 2)
|
||||
{
|
||||
std::vector<Layout2D> tiles;
|
||||
if (hol.translations.size() < 2) {
|
||||
tiles.push_back(layout);
|
||||
return tiles;
|
||||
}
|
||||
const Eigen::Vector2d& w1 = hol.translations[0];
|
||||
const Eigen::Vector2d& w2 = hol.translations[1];
|
||||
for (int m = -m_max; m <= m_max; ++m)
|
||||
for (int n = -n_max; n <= n_max; ++n)
|
||||
tiles.push_back(tiling_copy(layout, w1, w2, m, n));
|
||||
return tiles;
|
||||
}
|
||||
|
||||
} // namespace conformallab
|
||||
File diff suppressed because it is too large
Load Diff
152
code/include/period_matrix.hpp
Normal file
152
code/include/period_matrix.hpp
Normal file
@@ -0,0 +1,152 @@
|
||||
#pragma once
|
||||
// period_matrix.hpp
|
||||
//
|
||||
// Phase 7 — Period matrix for closed surfaces with Euclidean (flat) metric.
|
||||
//
|
||||
// For a closed genus-g surface with Euclidean conformal structure the holonomy
|
||||
// group is generated by 2g translations ω_1, ..., ω_{2g} ∈ ℂ ≅ ℝ².
|
||||
//
|
||||
// ─── Genus-1 (flat torus) ────────────────────────────────────────────────────
|
||||
//
|
||||
// The lattice Λ = ℤ·ω_1 ⊕ ℤ·ω_2 determines the conformal type.
|
||||
//
|
||||
// Period ratio: τ = ω_2 / ω_1 (as complex numbers)
|
||||
//
|
||||
// By convention choose ω_1 such that Im(τ) > 0.
|
||||
// The conformal modulus / Teichmüller parameter is the SL(2,ℤ)-orbit of τ.
|
||||
//
|
||||
// Reduction to fundamental domain {|τ| ≥ 1, −½ ≤ Re(τ) < ½, Im(τ) > 0}:
|
||||
// S: τ ↦ −1/τ (inversion)
|
||||
// T: τ ↦ τ + 1 (translation)
|
||||
// Apply S and T repeatedly until τ is in the fundamental domain.
|
||||
//
|
||||
// ─── Genus g > 1 ─────────────────────────────────────────────────────────────
|
||||
//
|
||||
// The full period matrix is a g×g complex symmetric matrix Ω with positive
|
||||
// definite imaginary part (Siegel upper half-space H_g).
|
||||
// Computing Ω from holonomy data requires integration of holomorphic
|
||||
// differentials — not implemented here. For g > 1, this function returns
|
||||
// only the 2×2 block for the first pair of generators.
|
||||
//
|
||||
// ─── API ─────────────────────────────────────────────────────────────────────
|
||||
//
|
||||
// PeriodData pd = compute_period_matrix(holonomy);
|
||||
// pd.tau — complex period ratio τ (genus 1)
|
||||
// pd.omega — holonomy generators as complex numbers (size = 2g)
|
||||
// pd.in_fundamental_domain — whether τ has been reduced
|
||||
//
|
||||
// std::complex<double> reduce_to_fundamental_domain(τ) — apply SL(2,ℤ)
|
||||
|
||||
#include "layout.hpp"
|
||||
#include <complex>
|
||||
#include <cmath>
|
||||
#include <vector>
|
||||
#include <stdexcept>
|
||||
#include <sstream>
|
||||
|
||||
namespace conformallab {
|
||||
|
||||
// ─────────────────────────────────────────────────────────────────────────────
|
||||
// PeriodData
|
||||
// ─────────────────────────────────────────────────────────────────────────────
|
||||
|
||||
struct PeriodData {
|
||||
/// Lattice generators as complex numbers (one per cut edge).
|
||||
/// omega[i] = translations[i].x() + i·translations[i].y()
|
||||
std::vector<std::complex<double>> omega;
|
||||
|
||||
/// Period ratio τ = omega[1] / omega[0] (genus-1 only).
|
||||
/// Undefined (NaN) for genus != 1 or if holonomy has fewer than 2 generators.
|
||||
std::complex<double> tau = std::complex<double>(
|
||||
std::numeric_limits<double>::quiet_NaN(), 0.0);
|
||||
|
||||
/// True if τ has been reduced to the standard fundamental domain.
|
||||
bool in_fundamental_domain = false;
|
||||
|
||||
int genus() const { return static_cast<int>(omega.size()) / 2; }
|
||||
};
|
||||
|
||||
// ─────────────────────────────────────────────────────────────────────────────
|
||||
// reduce_to_fundamental_domain
|
||||
//
|
||||
// Applies SL(2,ℤ) generators S: τ↦−1/τ and T: τ↦τ+1 to bring τ into
|
||||
// F = { τ ∈ ℍ : |τ| ≥ 1, −½ ≤ Re(τ) < ½ }
|
||||
//
|
||||
// Returns the reduced τ. Throws if Im(τ) ≤ 0 (not in upper half-plane).
|
||||
// ─────────────────────────────────────────────────────────────────────────────
|
||||
inline std::complex<double> reduce_to_fundamental_domain(std::complex<double> tau)
|
||||
{
|
||||
if (tau.imag() <= 0.0) {
|
||||
std::ostringstream msg;
|
||||
msg << "period_matrix: τ = " << tau.real() << " + " << tau.imag()
|
||||
<< "i is not in the upper half-plane (Im(τ) must be > 0).";
|
||||
throw std::domain_error(msg.str());
|
||||
}
|
||||
|
||||
// Iterate at most 200 times (convergence is rapid for well-conditioned τ)
|
||||
for (int k = 0; k < 200; ++k) {
|
||||
// T step: shift Re(τ) into [−½, ½)
|
||||
double re = tau.real();
|
||||
long n = static_cast<long>(std::floor(re + 0.5));
|
||||
tau -= std::complex<double>(static_cast<double>(n), 0.0);
|
||||
|
||||
// S step: if |τ| < 1, apply τ ← −1/τ
|
||||
if (std::abs(tau) < 1.0 - 1e-12) {
|
||||
tau = -1.0 / tau;
|
||||
} else {
|
||||
break;
|
||||
}
|
||||
}
|
||||
return tau;
|
||||
}
|
||||
|
||||
// ─────────────────────────────────────────────────────────────────────────────
|
||||
// is_in_fundamental_domain — check membership in F with tolerance tol.
|
||||
// ─────────────────────────────────────────────────────────────────────────────
|
||||
inline bool is_in_fundamental_domain(std::complex<double> tau, double tol = 1e-9)
|
||||
{
|
||||
if (tau.imag() <= 0.0) return false;
|
||||
if (std::abs(tau.real()) > 0.5 + tol) return false;
|
||||
if (std::abs(tau) < 1.0 - tol) return false;
|
||||
return true;
|
||||
}
|
||||
|
||||
// ─────────────────────────────────────────────────────────────────────────────
|
||||
// compute_period_matrix
|
||||
//
|
||||
// Computes the period data from the Euclidean holonomy translations.
|
||||
// For genus-1 surfaces, also reduces τ to the fundamental domain.
|
||||
// ─────────────────────────────────────────────────────────────────────────────
|
||||
inline PeriodData compute_period_matrix(const HolonomyData& hol, bool reduce = true)
|
||||
{
|
||||
PeriodData pd;
|
||||
pd.omega.reserve(hol.translations.size());
|
||||
for (auto& t : hol.translations)
|
||||
pd.omega.push_back(std::complex<double>(t.x(), t.y()));
|
||||
|
||||
if (pd.omega.size() < 2) return pd; // need at least 2 generators
|
||||
|
||||
// τ = ω_2 / ω_1 — choose ω_1 such that Im(τ) > 0
|
||||
std::complex<double> w1 = pd.omega[0];
|
||||
std::complex<double> w2 = pd.omega[1];
|
||||
if (std::abs(w1) < 1e-14) return pd;
|
||||
|
||||
std::complex<double> tau = w2 / w1;
|
||||
if (tau.imag() < 0.0) {
|
||||
tau = std::conj(tau); // swap orientation
|
||||
w1 = std::conj(w1);
|
||||
w2 = std::conj(w2);
|
||||
pd.omega[0] = w1;
|
||||
pd.omega[1] = w2;
|
||||
}
|
||||
if (tau.imag() < 0.0) return pd; // degenerate
|
||||
|
||||
if (reduce) {
|
||||
tau = reduce_to_fundamental_domain(tau);
|
||||
pd.in_fundamental_domain = true;
|
||||
}
|
||||
pd.tau = tau;
|
||||
return pd;
|
||||
}
|
||||
|
||||
} // namespace conformallab
|
||||
Reference in New Issue
Block a user