process-geometry 0.0.3__py3-none-any.whl

aeg_shakespeare/function_theory/period_matrix.py

@@ -0,0 +1,155 @@
+"""Cycle systems and candidate normalized period matrices.
+
+Primitive question
+------------------
+A single period is not yet the global object used by Abelian function theory.
+For a genus-g curve one needs g independent holomorphic differentials and 2g
+closed cycles.  Their integrals form two g-by-g blocks conventionally written
+A and B.  When the cycles are a symplectic homology basis and A is invertible,
+the normalized period matrix is
+
+    tau = A^{-1} B.
+
+Classical shadow
+----------------
+For a compact Riemann surface, a normalized period matrix associated with a
+symplectic homology basis is symmetric and has positive-definite imaginary
+part.  These are the Riemann bilinear constraints underlying the Jacobian.
+See Farkas--Kra, Forster, and Mumford in ``docs/REFERENCES.md``.
+
+Shakespeare reconstruction
+---------------------------
+This module deliberately starts one step earlier.  The caller supplies *closed
+lifted histories* already produced by the branch-continuation layer.  We first
+measure every canonical differential on every supplied cycle, then normalize
+the resulting blocks.  Only afterwards do we ask whether the numerical matrix
+has the symmetry/positivity shape expected of genuine Riemann period data.
+
+Crucially, the current engine does not compute intersection numbers.  Passing
+the matrix-shape checks is therefore evidence that a supplied cycle system is
+consistent with a symplectic period presentation, not a proof that the cycles
+form a canonical homology basis.
+
+Boundary
+--------
+No automatic homology basis, intersection pairing, certified quadrature error,
+or Jacobian construction is implemented here.  The positivity test uses the
+Sylvester criterion on the symmetrized numerical imaginary part.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import sympy as sp
+
+from .abelian import holomorphic_differential_basis
+from .algebraic import HyperellipticProfile
+from .periods import LiftedSquareRootPath, integrate_lifted_differential
+
+
+@dataclass(frozen=True)
+class AbelianCycleSystem:
+    """Caller-supplied A/B closed lifted cycles for a genus-g quotient."""
+
+    curve: HyperellipticProfile
+    a_cycles: tuple[LiftedSquareRootPath, ...]
+    b_cycles: tuple[LiftedSquareRootPath, ...]
+
+    def __post_init__(self) -> None:
+        genus = self.curve.generic_genus
+        if genus is None or genus < 1:
+            raise ValueError("cycle system requires a generically smooth positive-genus curve")
+        if len(self.a_cycles) != genus or len(self.b_cycles) != genus:
+            raise ValueError("cycle system requires exactly g A-cycles and g B-cycles")
+        for cycle in self.a_cycles + self.b_cycles:
+            if cycle.curve != self.curve:
+                raise ValueError("all cycles must belong to the declared curve")
+            if not cycle.lifted_closed:
+                raise ValueError("period cycles must be closed on the lifted surface")
+
+
+@dataclass(frozen=True)
+class AbelianPeriodMatrix:
+    """Measured A/B period blocks and normalized candidate ``tau=A^{-1}B``."""
+
+    cycles: AbelianCycleSystem
+    a_periods: tuple[tuple[complex, ...], ...]
+    b_periods: tuple[tuple[complex, ...], ...]
+    tau: tuple[tuple[complex, ...], ...]
+
+    @property
+    def genus(self) -> int:
+        return len(self.tau)
+
+    @property
+    def symmetry_residual(self) -> float:
+        return max(
+            abs(self.tau[i][j] - self.tau[j][i])
+            for i in range(self.genus)
+            for j in range(self.genus)
+        )
+
+    @property
+    def imaginary_part(self) -> tuple[tuple[float, ...], ...]:
+        return tuple(
+            tuple(float(self.tau[i][j].imag) for j in range(self.genus))
+            for i in range(self.genus)
+        )
+
+    def imaginary_part_positive_definite(self, *, tolerance: float = 1e-10) -> bool:
+        """Check positive-definiteness of the symmetrized Im(tau) numerically."""
+
+        imag = self.imaginary_part
+        symmetric = [
+            [0.5 * (imag[i][j] + imag[j][i]) for j in range(self.genus)]
+            for i in range(self.genus)
+        ]
+        for size in range(1, self.genus + 1):
+            determinant = complex(sp.N(sp.Matrix([row[:size] for row in symmetric[:size]]).det(), 30))
+            if abs(determinant.imag) > tolerance or determinant.real <= tolerance:
+                return False
+        return True
+
+    def riemann_shape_passes(self, *, tolerance: float = 1e-8) -> bool:
+        """Check the numerical symmetry/positivity shape required of period data.
+
+        This is not a homology-intersection certificate.  It tests necessary
+        matrix properties assuming the caller's cycles are intended as a
+        symplectic basis.
+        """
+
+        return (
+            self.symmetry_residual <= tolerance
+            and self.imaginary_part_positive_definite(tolerance=tolerance)
+        )
+
+
+def compute_period_matrix(cycles: AbelianCycleSystem) -> AbelianPeriodMatrix:
+    """Integrate the canonical basis over supplied A/B cycles and normalize."""
+
+    differentials = holomorphic_differential_basis(cycles.curve)
+    a_rows = tuple(
+        tuple(integrate_lifted_differential(cycle, differential) for cycle in cycles.a_cycles)
+        for differential in differentials
+    )
+    b_rows = tuple(
+        tuple(integrate_lifted_differential(cycle, differential) for cycle in cycles.b_cycles)
+        for differential in differentials
+    )
+
+    a_matrix = sp.Matrix(a_rows)
+    b_matrix = sp.Matrix(b_rows)
+    if abs(complex(sp.N(a_matrix.det(), 30))) <= 1e-14:
+        raise ValueError("A-period block is numerically singular")
+    tau_matrix = a_matrix.inv() * b_matrix
+    tau = tuple(
+        tuple(complex(sp.N(tau_matrix[i, j], 30)) for j in range(tau_matrix.cols))
+        for i in range(tau_matrix.rows)
+    )
+    return AbelianPeriodMatrix(
+        cycles=cycles,
+        a_periods=a_rows,
+        b_periods=b_rows,
+        tau=tau,
+    )

aeg_shakespeare/function_theory/periods.py

@@ -0,0 +1,216 @@
+"""History lifting, square-root monodromy, and numerical period integration.
+
+Primitive question
+------------------
+Once a process quotient has produced a curve ``y^2=P(x)``, how do we keep track
+of *which sheet* a history occupies while the base coordinate ``x`` moves around
+branch points? Returning to the same base point need not return to the same
+lifted state: analytic continuation around a branch point can change ``y`` to
+``-y``. This is the simplest executable model of the distinction
+
+    state return != history return.
+
+Classical shadow
+----------------
+Classically this is monodromy of the two-sheeted square-root covering. On a
+smooth hyperelliptic curve, periods arise by integrating holomorphic
+differentials along closed lifted cycles. In genus one two independent periods
+form the lattice underlying the complex torus; in higher genus the same idea
+feeds a period matrix and Jacobian. See Forster, Farkas--Kra, and the references
+collected in ``docs/REFERENCES.md``.
+
+Shakespeare reconstruction
+---------------------------
+The library does not jump directly to a named elliptic or Abelian function.
+Instead it makes the history lift executable:
+
+1. a base path in the complex ``x``-plane is sampled;
+2. the square root is continued by choosing, at each step, the sign closest to
+   the previously selected value;
+3. the resulting lifted path records whether a closed base loop closes on the
+   Riemann surface or changes sheet;
+4. a differential ``x^k dx/y`` can then be integrated along the lifted history.
+
+This is deliberately a *bounded numerical continuation engine*. It is useful
+for calibrating topology/period structure, but it is not a certified homology
+solver or a proof of a period matrix.
+
+Executable contract
+-------------------
+``lift_square_root_path`` returns every selected sheet value and an explicit
+``sheet_multiplier`` when the base loop closes. ``integrate_lifted_differential``
+uses a complex trapezoidal rule along the supplied samples. ``GenusOneLattice``
+packages two already-computed periods and their ratio without pretending to
+construct the cycles that produced them.
+
+Boundary
+--------
+The continuation rule assumes sufficiently fine sampling and no sample at a
+branch point. Numerical integration carries discretization error. Arbitrary
+homology-basis construction, adaptive contour refinement, rigorous error bounds,
+Riemann bilinear relations in genus > 1, and Jacobians remain later work.
+"""
+
+from __future__ import annotations
+
+import cmath
+from dataclasses import dataclass
+from typing import Iterable
+
+import sympy as sp
+
+from .abelian import HyperellipticDifferential
+from .algebraic import HyperellipticProfile
+
+
+def _numeric_polynomial_coefficients(
+    expr: sp.Expr,
+    symbol: sp.Symbol,
+    *,
+    digits: int,
+) -> tuple[complex, ...]:
+    expr = sp.sympify(expr)
+    remaining = expr.free_symbols - {symbol}
+    if remaining:
+        raise ValueError(f"numeric continuation requires all parameters fixed: {remaining}")
+    try:
+        polynomial = sp.Poly(expr, symbol)
+    except sp.PolynomialError as exc:
+        raise ValueError("numeric continuation requires a polynomial in the curve variable") from exc
+    return tuple(complex(sp.N(coefficient, digits)) for coefficient in polynomial.all_coeffs())
+
+
+def _horner(coefficients: tuple[complex, ...], value: complex) -> complex:
+    result = 0j
+    for coefficient in coefficients:
+        result = result * value + coefficient
+    return result
+
+
+@dataclass(frozen=True)
+class LiftedSquareRootPath:
+    """A sampled base path together with one continuously chosen square-root lift."""
+
+    curve: HyperellipticProfile
+    x_values: tuple[complex, ...]
+    y_values: tuple[complex, ...]
+
+    @property
+    def base_closed(self) -> bool:
+        if len(self.x_values) < 2:
+            return False
+        scale = max(1.0, abs(self.x_values[0]), abs(self.x_values[-1]))
+        return abs(self.x_values[-1] - self.x_values[0]) <= 1e-10 * scale
+
+    @property
+    def sheet_multiplier(self) -> int | None:
+        """Return +1/-1 for a closed base loop, or ``None`` if not comparable."""
+
+        if not self.base_closed or not self.y_values:
+            return None
+        start = self.y_values[0]
+        end = self.y_values[-1]
+        if abs(start) == 0:
+            return None
+        same = abs(end - start)
+        flipped = abs(end + start)
+        return 1 if same <= flipped else -1
+
+    @property
+    def lifted_closed(self) -> bool:
+        return self.sheet_multiplier == 1
+
+
+def lift_square_root_path(
+    curve: HyperellipticProfile,
+    x_values: Iterable[complex],
+    *,
+    initial_y: complex | None = None,
+    digits: int = 50,
+    branch_tolerance: float = 1e-24,
+) -> LiftedSquareRootPath:
+    """Continue one branch of ``sqrt(P(x))`` along a sampled complex path.
+
+    At each sample the principal square root and its negative are compared with
+    the previously selected lift. The closer one is chosen. This is the
+    discrete analogue of analytic continuation along a path.
+    """
+
+    xs = tuple(complex(value) for value in x_values)
+    if len(xs) < 2:
+        raise ValueError("a lifted path requires at least two base samples")
+
+    coefficients = _numeric_polynomial_coefficients(
+        curve.polynomial,
+        curve.x,
+        digits=digits,
+    )
+    ys: list[complex] = []
+    previous: complex | None = complex(initial_y) if initial_y is not None else None
+
+    for x_value in xs:
+        p_value = _horner(coefficients, x_value)
+        if abs(p_value) <= branch_tolerance:
+            raise ValueError("sample path meets or approaches a branch point too closely")
+        principal = cmath.sqrt(p_value)
+        candidates = (principal, -principal)
+        if previous is None:
+            selected = principal
+        else:
+            selected = min(candidates, key=lambda candidate: abs(candidate - previous))
+        ys.append(selected)
+        previous = selected
+
+    return LiftedSquareRootPath(curve=curve, x_values=xs, y_values=tuple(ys))
+
+
+def integrate_lifted_differential(
+    path: LiftedSquareRootPath,
+    differential: HyperellipticDifferential,
+    *,
+    digits: int = 50,
+) -> complex:
+    """Numerically integrate ``x^k dx/y`` along an already lifted path."""
+
+    del digits  # kept for API symmetry with the continuation routine
+    if differential.curve != path.curve:
+        raise ValueError("differential and lifted path must belong to the same curve")
+
+    values = tuple(
+        (x_value ** differential.power) / y_value
+        for x_value, y_value in zip(path.x_values, path.y_values, strict=True)
+    )
+
+    total = 0j
+    for index in range(len(path.x_values) - 1):
+        dx = path.x_values[index + 1] - path.x_values[index]
+        total += 0.5 * (values[index] + values[index + 1]) * dx
+    return total
+
+
+@dataclass(frozen=True)
+class GenusOneLattice:
+    """Two non-collinear periods of a genus-one quotient.
+
+    The object packages period data supplied by explicit cycle computations or
+    exact symmetries. It does not discover a homology basis by itself.
+    """
+
+    omega_a: complex
+    omega_b: complex
+
+    def __post_init__(self) -> None:
+        if abs(self.omega_a) == 0:
+            raise ValueError("first period must be nonzero")
+        if abs((self.omega_b / self.omega_a).imag) <= 1e-14:
+            raise ValueError("genus-one periods must be non-collinear over R")
+
+    @property
+    def tau(self) -> complex:
+        return self.omega_b / self.omega_a
+
+    @property
+    def oriented_area(self) -> float:
+        """Signed Euclidean area of the period parallelogram."""
+
+        return float((self.omega_a.conjugate() * self.omega_b).imag)

aeg_shakespeare/function_theory/real_branch_cycles.py

@@ -0,0 +1,286 @@
+"""Constructed A/B cycles for real-split hyperelliptic process quotients.
+
+Primitive question
+------------------
+The period and intersection layers can measure cycles once those cycles have
+already been supplied. That still leaves a representation choice outside the
+library: *where did the A/B cycles come from?*
+
+For a real-split even-degree hyperelliptic quotient
+
+    y^2 = c prod_j (x-e_j),       e_1 < ... < e_(2g+2),
+
+there is a classical answer visible directly in the branch-point order. Pair
+adjacent branch points into cuts
+
+    [e_1,e_2], [e_3,e_4], ..., [e_(2g+1),e_(2g+2)].
+
+A standard symplectic presentation may take ``a_i`` around the i-th nonreference
+cut and ``b_i`` around the even branch set beginning at the right end of that
+cut and ending at the left end of the final reference cut. In index notation
+used here,
+
+    a_i encloses e_(2i), ..., e_(2i+1),
+    b_i encloses e_(2i+1), ..., e_(2g),
+
+for ``i=0,...,g-1``. The resulting abstract pairing is
+
+    a_i . a_j = b_i . b_j = 0,
+    a_i . b_j = delta_ij.
+
+This is the familiar branch-cut construction behind hyperelliptic homology and
+period calculations; see Farkas--Kra and Frauendiener--Klein in
+``docs/REFERENCES.md``.
+
+Shakespeare reconstruction
+---------------------------
+The important change is that the cycle basis is no longer an unexplained input.
+The branch-point presentation itself emits:
+
+1. the cut pairing;
+2. exact combinatorial A/B cycle specifications;
+3. the target symplectic intersection matrix forced by that construction;
+4. sampled base contours realizing those specifications;
+5. lifted histories obtained by the existing square-root continuation engine.
+
+The exact combinatorial certificate and the sampled realization are deliberately
+kept separate. Later code can ask whether numerical lifted intersections agree
+with the pairing promised by construction.
+
+Executable contract
+-------------------
+``real_branch_cut_presentation`` validates a supplied ordered list of all
+``2g+2`` real branch points of an even-degree quotient. ``construct_real_branch_cycles``
+turns the canonical interval specifications into nested/transverse ellipses and
+lifts them to the Riemann surface. Under the implementation's fixed convention
+that continuation starts at the rightmost point on the principal square-root
+sheet, nested B-contours alternate their base orientation so that the lifted
+cycles realize ``a_i.b_i=+1``. The function returns both the construction
+metadata and an ``AbelianCycleSystem`` ready for period integration.
+
+Boundary
+--------
+This module handles only the real-split, even-degree case with explicitly
+supplied branch points. It does not discover cuts for arbitrary complex branch
+configurations, prove numerical contour deformation invariance, or replace a
+general Tretkoff--Tretkoff style homology algorithm. The ellipse geometry is a
+sampled realization of a classical branch-cut presentation, not the topology
+itself.
+"""
+
+from __future__ import annotations
+
+import math
+from dataclasses import dataclass
+from typing import Literal
+
+import sympy as sp
+
+from .algebraic import HyperellipticProfile
+from .period_matrix import AbelianCycleSystem
+from .periods import LiftedSquareRootPath, lift_square_root_path
+
+CycleFamily = Literal["A", "B"]
+
+
+@dataclass(frozen=True)
+class RealBranchCycleSpec:
+    """One cycle specified by the consecutive branch points it encloses."""
+
+    family: CycleFamily
+    index: int
+    left_branch_index: int
+    right_branch_index: int
+
+    @property
+    def branch_count(self) -> int:
+        return self.right_branch_index - self.left_branch_index + 1
+
+
+@dataclass(frozen=True)
+class RealBranchCutPresentation:
+    """Classical branch-cut presentation for a real-split even-degree curve."""
+
+    curve: HyperellipticProfile
+    branch_points: tuple[float, ...]
+    a_specs: tuple[RealBranchCycleSpec, ...]
+    b_specs: tuple[RealBranchCycleSpec, ...]
+
+    @property
+    def genus(self) -> int:
+        genus = self.curve.generic_genus
+        assert genus is not None
+        return genus
+
+    @property
+    def reference_cut(self) -> tuple[float, float]:
+        return self.branch_points[-2], self.branch_points[-1]
+
+    @property
+    def construction_intersection_form(self) -> tuple[tuple[int, ...], ...]:
+        """Return the exact target ``[[0,I],[-I,0]]`` in A-then-B order."""
+
+        genus = self.genus
+        size = 2 * genus
+        matrix = [[0 for _ in range(size)] for _ in range(size)]
+        for index in range(genus):
+            matrix[index][genus + index] = 1
+            matrix[genus + index][index] = -1
+        return tuple(tuple(row) for row in matrix)
+
+
+@dataclass(frozen=True)
+class ConstructedRealBranchCycles:
+    """Sampled lifted realization plus its branch-cut construction certificate."""
+
+    presentation: RealBranchCutPresentation
+    a_cycles: tuple[LiftedSquareRootPath, ...]
+    b_cycles: tuple[LiftedSquareRootPath, ...]
+
+    @property
+    def cycle_system(self) -> AbelianCycleSystem:
+        return AbelianCycleSystem(
+            curve=self.presentation.curve,
+            a_cycles=self.a_cycles,
+            b_cycles=self.b_cycles,
+        )
+
+    @property
+    def construction_intersection_form(self) -> tuple[tuple[int, ...], ...]:
+        return self.presentation.construction_intersection_form
+
+
+def real_branch_cut_presentation(
+    curve: HyperellipticProfile,
+    branch_points: tuple[float, ...] | list[float],
+    *,
+    root_tolerance: float = 1e-10,
+) -> RealBranchCutPresentation:
+    """Validate real branch points and emit the canonical interval cycle specs."""
+
+    genus = curve.generic_genus
+    if genus is None or genus < 1:
+        raise ValueError("real branch-cycle presentation requires positive generic genus")
+    if curve.degree != 2 * genus + 2:
+        raise ValueError("real branch-cycle presentation currently requires even degree 2g+2")
+
+    points = tuple(float(value) for value in branch_points)
+    expected = 2 * genus + 2
+    if len(points) != expected:
+        raise ValueError(f"expected exactly {expected} real branch points")
+    if any(not math.isfinite(value) for value in points):
+        raise ValueError("branch points must be finite real numbers")
+    if any(points[index] >= points[index + 1] for index in range(len(points) - 1)):
+        raise ValueError("branch points must be strictly increasing")
+    if root_tolerance <= 0:
+        raise ValueError("root_tolerance must be positive")
+
+    for point in points:
+        value = complex(sp.N(curve.polynomial.subs(curve.x, point), 40))
+        scale = max(1.0, abs(point) ** curve.degree)
+        if abs(value) > root_tolerance * scale:
+            raise ValueError(f"supplied branch point {point} is not a root of the curve polynomial")
+
+    a_specs = tuple(
+        RealBranchCycleSpec("A", index, 2 * index, 2 * index + 1)
+        for index in range(genus)
+    )
+    # The final pair [e_(2g), e_(2g+1)] is the reference cut. b_i surrounds
+    # the even branch set from the right endpoint of a_i to the left endpoint
+    # of that reference cut. Nested B-contours then intersect only their dual A.
+    b_specs = tuple(
+        RealBranchCycleSpec("B", index, 2 * index + 1, 2 * genus)
+        for index in range(genus)
+    )
+    if any(spec.branch_count % 2 for spec in a_specs + b_specs):
+        raise AssertionError("constructed hyperelliptic cycles must enclose even branch sets")
+
+    return RealBranchCutPresentation(
+        curve=curve,
+        branch_points=points,
+        a_specs=a_specs,
+        b_specs=b_specs,
+    )
+
+
+def _ellipse_for_spec(
+    presentation: RealBranchCutPresentation,
+    spec: RealBranchCycleSpec,
+    *,
+    samples: int,
+    padding_fraction: float,
+    height_fraction: float,
+) -> tuple[complex, ...]:
+    points = presentation.branch_points
+    left_index = spec.left_branch_index
+    right_index = spec.right_branch_index
+    left = points[left_index]
+    right = points[right_index]
+    span = right - left
+
+    left_clearance = (
+        left - points[left_index - 1]
+        if left_index > 0
+        else points[1] - points[0]
+    )
+    right_clearance = (
+        points[right_index + 1] - right
+        if right_index + 1 < len(points)
+        else points[-1] - points[-2]
+    )
+    padding = padding_fraction * min(left_clearance, right_clearance)
+    center = 0.5 * (left + right)
+    horizontal_radius = 0.5 * span + padding
+    vertical_radius = height_fraction * horizontal_radius
+
+    contour = tuple(
+        center
+        + horizontal_radius * math.cos(2.0 * math.pi * step / samples)
+        + 1j * vertical_radius * math.sin(2.0 * math.pi * step / samples)
+        for step in range(samples + 1)
+    )
+    # All contours start at their rightmost point.  With the principal-square-root
+    # initial sheet used by lift_square_root_path, successive nested B cycles
+    # acquire alternating lifted orientation.  Reverse the odd-indexed ones so
+    # the realized basis matches the construction convention a_i.b_i=+1.
+    if spec.family == "B" and spec.index % 2 == 1:
+        contour = tuple(reversed(contour))
+    return contour
+
+
+def construct_real_branch_cycles(
+    presentation: RealBranchCutPresentation,
+    *,
+    samples: int = 1024,
+    padding_fraction: float = 0.18,
+    height_fraction: float = 0.35,
+) -> ConstructedRealBranchCycles:
+    """Materialize and lift the A/B contours emitted by a real branch presentation."""
+
+    if samples < 64:
+        raise ValueError("cycle construction requires at least 64 contour samples")
+    if not 0 < padding_fraction < 0.5:
+        raise ValueError("padding_fraction must lie between 0 and 0.5")
+    if height_fraction <= 0:
+        raise ValueError("height_fraction must be positive")
+
+    def lift(spec: RealBranchCycleSpec) -> LiftedSquareRootPath:
+        base_path = _ellipse_for_spec(
+            presentation,
+            spec,
+            samples=samples,
+            padding_fraction=padding_fraction,
+            height_fraction=height_fraction,
+        )
+        path = lift_square_root_path(presentation.curve, base_path)
+        if not path.lifted_closed:
+            raise ValueError(
+                f"constructed {spec.family}{spec.index + 1} contour did not close on the lifted surface"
+            )
+        return path
+
+    return ConstructedRealBranchCycles(
+        presentation=presentation,
+        a_cycles=tuple(lift(spec) for spec in presentation.a_specs),
+        b_cycles=tuple(lift(spec) for spec in presentation.b_specs),
+    )