process-geometry 0.0.3__py3-none-any.whl

aeg_shakespeare/families.py

@@ -0,0 +1,31 @@
+"""Compatibility shim for the pre-refactor finite-family module path.
+
+New code should import from ``aeg_shakespeare.process.finite``.  The
+implementation now physically lives under that semantic namespace.
+"""
+
+from .process.finite.families import (
+    CharacterVerification,
+    FamilyAction,
+    FamilyActionVerification,
+    FamilyStep,
+    ProcessCharacter,
+    ProcessFamily,
+    character_invariance_residual,
+    transport_process_character,
+    verify_family_action,
+    verify_process_character,
+)
+
+__all__ = [
+    "ProcessFamily",
+    "FamilyStep",
+    "ProcessCharacter",
+    "CharacterVerification",
+    "verify_process_character",
+    "FamilyAction",
+    "FamilyActionVerification",
+    "verify_family_action",
+    "transport_process_character",
+    "character_invariance_residual",
+]

aeg_shakespeare/frame.py

@@ -0,0 +1,5 @@
+"""Compatibility shim for the pre-refactor local process-frame module path."""
+
+from .process.local.frame import ProcessFrame
+
+__all__ = ["ProcessFrame"]

aeg_shakespeare/function_theory/__init__.py

@@ -0,0 +1,100 @@
+"""Optional process-generated function-theory layers.
+
+Addition/Multiplication (A/M) is the first concrete arithmetic theory.
+Algebraic quotient profiles provide a second route for processes whose reduced
+geometry forces elliptic/Abelian or higher-genus function languages. The
+Abelian layer then exposes canonical holomorphic differentials, history lifts,
+cycle intersections, branch-cut cycle constructions, period data, and finally
+normalized history coordinates modulo the measured period lattice.
+"""
+
+from .abel_jacobi import (
+    AbelJacobiHistoryIncrement,
+    NormalizedAbelianTorus,
+    abel_jacobi_history_increment,
+    normalized_abelian_torus,
+)
+from .abelian import (
+    AbelianIntegralProfile,
+    HyperellipticDifferential,
+    abelian_integral_profile,
+    holomorphic_differential_basis,
+)
+from .algebraic import HyperellipticProfile, hyperelliptic_profile
+from .am import (
+    AMFunctionTheory,
+    AMPathFlow,
+    AMPowerWeight,
+    AMPrimitive,
+    AMState,
+    affine_am_frame,
+)
+from .intersection import (
+    LiftedCycleIntersection,
+    SampledIntersectionForm,
+    SampledRiemannProfile,
+    canonical_symplectic_form,
+    lifted_path_intersections,
+    sampled_intersection_form,
+    sampled_intersection_number,
+    sampled_riemann_profile,
+)
+from .module import ProcessFunctionModule, polynomial_am_module
+from .period_matrix import AbelianCycleSystem, AbelianPeriodMatrix, compute_period_matrix
+from .periods import (
+    GenusOneLattice,
+    LiftedSquareRootPath,
+    integrate_lifted_differential,
+    lift_square_root_path,
+)
+from .real_branch_cycles import (
+    ConstructedRealBranchCycles,
+    RealBranchCutPresentation,
+    RealBranchCycleSpec,
+    construct_real_branch_cycles,
+    real_branch_cut_presentation,
+)
+from .weierstrass import WeierstrassCubicProfile, weierstrass_cubic_profile
+
+__all__ = [
+    "AbelJacobiHistoryIncrement",
+    "NormalizedAbelianTorus",
+    "abel_jacobi_history_increment",
+    "normalized_abelian_torus",
+    "AbelianIntegralProfile",
+    "HyperellipticDifferential",
+    "abelian_integral_profile",
+    "holomorphic_differential_basis",
+    "HyperellipticProfile",
+    "hyperelliptic_profile",
+    "AMFunctionTheory",
+    "AMPathFlow",
+    "AMPowerWeight",
+    "AMPrimitive",
+    "AMState",
+    "affine_am_frame",
+    "LiftedCycleIntersection",
+    "SampledIntersectionForm",
+    "SampledRiemannProfile",
+    "canonical_symplectic_form",
+    "lifted_path_intersections",
+    "sampled_intersection_form",
+    "sampled_intersection_number",
+    "sampled_riemann_profile",
+    "ProcessFunctionModule",
+    "polynomial_am_module",
+    "AbelianCycleSystem",
+    "AbelianPeriodMatrix",
+    "compute_period_matrix",
+    "GenusOneLattice",
+    "LiftedSquareRootPath",
+    "integrate_lifted_differential",
+    "lift_square_root_path",
+    "ConstructedRealBranchCycles",
+    "RealBranchCutPresentation",
+    "RealBranchCycleSpec",
+    "construct_real_branch_cycles",
+    "real_branch_cut_presentation",
+    "WeierstrassCubicProfile",
+    "weierstrass_cubic_profile",
+]

aeg_shakespeare/function_theory/abel_jacobi.py

@@ -0,0 +1,246 @@
+"""Normalized Abelian history coordinates and the period-lattice quotient.
+
+Primitive question
+------------------
+Once a process quotient has emitted canonical holomorphic differentials, a
+symplectic cycle system, and a Riemann-shaped period matrix, what does a lifted
+history *measure* globally?
+
+For a path ``gamma`` on a genus-``g`` curve the vector
+
+    u(gamma) = (integral_gamma omega_1, ..., integral_gamma omega_g)
+
+records the Abelian-integral increment carried by that history.  If ``A`` is
+the A-period block, the normalized increment is
+
+    u_hat = A^{-1} u.
+
+Closed A- and B-cycle histories then shift the normalized coordinate by
+
+    e_j                 and                 tau[:, j],
+
+respectively.  Thus the residual ambiguity after quotienting closed histories
+is the lattice
+
+    Z^g + tau Z^g  subset C^g.
+
+Classical lineage
+-----------------
+This is the analytic construction underlying the Abel--Jacobi map and the
+Jacobian of a compact Riemann surface.  Choosing a base point and integrating a
+basis of holomorphic one-forms sends points/divisors to ``C^g`` modulo the
+period lattice.  With A-normalized differentials the Jacobian has the standard
+presentation
+
+    C^g / (Z^g + tau Z^g).
+
+See Farkas--Kra, Forster, and Mumford in ``docs/REFERENCES.md``.  Historically,
+Abel's theorem and Jacobi inversion are the higher-genus continuation of the
+elliptic-integral inversion story; Baker is retained in the bibliography as a
+classical historical source.
+
+Shakespeare reconstruction
+---------------------------
+The package does not insert a ``Jacobian`` object merely because the curve has
+genus ``g``.  This module is enabled only after earlier executable layers have
+produced:
+
+1. actual lifted histories;
+2. their period matrix;
+3. a sampled canonical symplectic intersection form; and
+4. the Riemann symmetry/positive-imaginary-part checks.
+
+``NormalizedAbelianTorus`` therefore accepts a *passing* ``SampledRiemannProfile``.
+It is a numerical period-lattice presentation, not a claim that Shakespeare has
+implemented divisor arithmetic or an algebraic Jacobian model.
+
+``AbelJacobiHistoryIncrement`` likewise represents the integral accumulated by
+one lifted path.  A genuine point-valued Abel--Jacobi map additionally requires
+a chosen base point and a path from that base point.  Keeping the object as a
+history increment makes the dependence on path history explicit rather than
+silently hiding it modulo periods.
+
+Executable contract
+-------------------
+``abel_jacobi_history_increment`` integrates the canonical differential basis
+along a lifted path and normalizes by the measured A-period block.  For the
+cycle system that generated the period matrix:
+
+    A_j -> e_j,
+    B_j -> tau[:,j].
+
+``NormalizedAbelianTorus.lattice_shift(m,n)`` returns ``m + tau n`` for integer
+vectors ``m,n``.  ``matches_lattice_shift`` checks a *declared* lattice
+relation; it deliberately does not solve the hard inverse problem of deciding
+an arbitrary nearest/exact period relation.
+
+Boundary
+--------
+All data inherit the numerical/sampling limitations of the current continuation,
+intersection, and quadrature layers.  The class is not a full Jacobian: it has
+no divisor classes, theta functions, polarization machinery beyond the already
+checked cycle pairing, algebraic group law, or Jacobi inversion solver.  The
+name ``NormalizedAbelianTorus`` is intentional.  The classical identification
+with the Jacobian is the shadow when the supplied Riemann-surface data are
+mathematically valid.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Sequence
+
+import sympy as sp
+
+from .abelian import holomorphic_differential_basis
+from .intersection import SampledRiemannProfile
+from .period_matrix import AbelianPeriodMatrix
+from .periods import LiftedSquareRootPath, integrate_lifted_differential
+
+ComplexVector = tuple[complex, ...]
+
+
+def _complex_matrix(rows: Sequence[Sequence[complex]]) -> sp.Matrix:
+    return sp.Matrix([[complex(value) for value in row] for row in rows])
+
+
+def _complex_vector(values: Sequence[complex]) -> sp.Matrix:
+    return sp.Matrix([complex(value) for value in values])
+
+
+def _as_complex_tuple(column: sp.Matrix) -> ComplexVector:
+    return tuple(complex(sp.N(column[index], 30)) for index in range(column.rows))
+
+
+@dataclass(frozen=True)
+class AbelJacobiHistoryIncrement:
+    """Raw and A-normalized Abelian-integral increment of one lifted history."""
+
+    periods: AbelianPeriodMatrix
+    path: LiftedSquareRootPath
+    raw: ComplexVector
+    normalized: ComplexVector
+
+    @property
+    def dimension(self) -> int:
+        return len(self.normalized)
+
+
+@dataclass(frozen=True)
+class NormalizedAbelianTorus:
+    """Numerical normalized lattice ``C^g / (Z^g + tau Z^g)``.
+
+    Construction is intentionally gated by a passing sampled Riemann profile so
+    callers cannot turn an arbitrary complex matrix into a Shakespeare
+    ``Jacobian-like`` representation without the currently available topology
+    and Riemann-shape evidence.
+    """
+
+    riemann: SampledRiemannProfile
+
+    def __post_init__(self) -> None:
+        if not self.riemann.passes:
+            raise ValueError("normalized Abelian torus requires a passing Riemann profile")
+
+    @property
+    def periods(self) -> AbelianPeriodMatrix:
+        return self.riemann.periods
+
+    @property
+    def dimension(self) -> int:
+        return self.periods.genus
+
+    @property
+    def tau(self) -> tuple[tuple[complex, ...], ...]:
+        return self.periods.tau
+
+    def a_shift(self, index: int) -> ComplexVector:
+        """Return the normalized lattice shift generated by A_index."""
+
+        if not 0 <= index < self.dimension:
+            raise IndexError("A-cycle index out of range")
+        return tuple(1.0 + 0j if row == index else 0j for row in range(self.dimension))
+
+    def b_shift(self, index: int) -> ComplexVector:
+        """Return the normalized lattice shift generated by B_index."""
+
+        if not 0 <= index < self.dimension:
+            raise IndexError("B-cycle index out of range")
+        return tuple(self.tau[row][index] for row in range(self.dimension))
+
+    def lattice_shift(
+        self,
+        a_coefficients: Sequence[int],
+        b_coefficients: Sequence[int],
+    ) -> ComplexVector:
+        """Return ``m + tau*n`` for integer coefficient vectors ``m,n``."""
+
+        if len(a_coefficients) != self.dimension or len(b_coefficients) != self.dimension:
+            raise ValueError("lattice coefficient vectors must have length g")
+        if any(not isinstance(value, int) for value in tuple(a_coefficients) + tuple(b_coefficients)):
+            raise TypeError("lattice coefficients must be integers")
+
+        return tuple(
+            complex(a_coefficients[row])
+            + sum(
+                self.tau[row][column] * b_coefficients[column]
+                for column in range(self.dimension)
+            )
+            for row in range(self.dimension)
+        )
+
+    def matches_lattice_shift(
+        self,
+        left: Sequence[complex],
+        right: Sequence[complex],
+        a_coefficients: Sequence[int],
+        b_coefficients: Sequence[int],
+        *,
+        tolerance: float = 1e-8,
+    ) -> bool:
+        """Check ``right-left = m+tau*n`` for caller-declared integer vectors."""
+
+        if tolerance <= 0:
+            raise ValueError("tolerance must be positive")
+        if len(left) != self.dimension or len(right) != self.dimension:
+            raise ValueError("torus coordinates must have length g")
+        shift = self.lattice_shift(a_coefficients, b_coefficients)
+        return max(
+            abs((complex(right[index]) - complex(left[index])) - shift[index])
+            for index in range(self.dimension)
+        ) <= tolerance
+
+
+def normalized_abelian_torus(riemann: SampledRiemannProfile) -> NormalizedAbelianTorus:
+    """Construct the normalized period-lattice quotient from checked Riemann data."""
+
+    return NormalizedAbelianTorus(riemann=riemann)
+
+
+def abel_jacobi_history_increment(
+    path: LiftedSquareRootPath,
+    periods: AbelianPeriodMatrix,
+) -> AbelJacobiHistoryIncrement:
+    """Integrate and A-normalize the canonical differential vector on ``path``."""
+
+    if path.curve != periods.cycles.curve:
+        raise ValueError("history path and period matrix must belong to the same curve")
+
+    differentials = holomorphic_differential_basis(path.curve)
+    raw = tuple(
+        integrate_lifted_differential(path, differential)
+        for differential in differentials
+    )
+
+    a_matrix = _complex_matrix(periods.a_periods)
+    if a_matrix.rows != len(raw) or a_matrix.cols != len(raw):
+        raise ValueError("A-period block and Abelian history dimension disagree")
+    normalized_column = a_matrix.inv() * _complex_vector(raw)
+    normalized = _as_complex_tuple(normalized_column)
+
+    return AbelJacobiHistoryIncrement(
+        periods=periods,
+        path=path,
+        raw=tuple(complex(value) for value in raw),
+        normalized=normalized,
+    )

aeg_shakespeare/function_theory/abelian.py

@@ -0,0 +1,129 @@
+"""Abelian-integral structure emitted by a hyperelliptic process quotient.
+
+Mathematical lineage
+--------------------
+Once an algebraic curve ``y^2 = P(x)`` has appeared, classical analysis does
+not stop at its genus.  One studies holomorphic differentials, integrates them
+along paths, and compares the values after continuation around closed cycles.
+For a genus-``g`` hyperelliptic curve a standard holomorphic basis is
+
+    dx/y, x dx/y, ..., x^(g-1) dx/y.
+
+The first homology has rank ``2g``; integrating the ``g`` differentials over a
+homology basis produces the period data behind the Jacobian.  In genus one the
+same construction gives the two-period lattice of elliptic-function theory.
+See Forster, *Lectures on Riemann Surfaces*, and Farkas--Kra, *Riemann
+Surfaces*.  For an explicit hyperelliptic differential basis see also the
+references collected in ``docs/REFERENCES.md``.
+
+Shakespeare reconstruction
+---------------------------
+The process-first order is deliberately the reverse of a named special-function
+solver.  A process first emits an algebraic quotient.  This module then asks
+which canonical differentials the quotient itself carries and how many global
+cycle directions can contribute history residuals.
+
+A ``HyperellipticDifferential`` is intentionally represented as a coefficient
+of ``dx`` rather than as a SymPy differential object.  This keeps the algebraic
+backend simple while retaining the exact mathematical form ``x^k dx/y``.  Its
+``pullback_coefficient`` method asks what the differential becomes along a
+chosen process ``dx/dt``.  For example, if a reduced process satisfies
+``dx/dt = y``, then ``dx/y`` pulls back to ``dt`` exactly.
+
+Boundary
+--------
+This module does not choose homology cycles, analytically continue square-root
+branches, compute period matrices, prove uniformization, or construct a
+Jacobian as a complex torus.  ``homology_rank = 2g`` is topological structure;
+it is not a numerically computed period lattice.  Concrete cycle integrals
+belong in cited calibration tests until a genuinely reusable period engine is
+forced by more than one example.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import sympy as sp
+
+from .algebraic import HyperellipticProfile
+
+
+@dataclass(frozen=True)
+class HyperellipticDifferential:
+    """One canonical differential ``x^power dx / y`` on a hyperelliptic curve."""
+
+    curve: HyperellipticProfile
+    power: int
+
+    def __post_init__(self) -> None:
+        if self.power < 0:
+            raise ValueError("differential power must be non-negative")
+
+    @property
+    def numerator(self) -> sp.Expr:
+        return self.curve.x ** self.power
+
+    @property
+    def coefficient(self) -> sp.Expr:
+        """Return the coefficient of ``dx`` in ``x^power dx/y``."""
+
+        return self.numerator / self.curve.y
+
+    def pullback_coefficient(self, dx_dt: sp.Expr) -> sp.Expr:
+        """Return the coefficient of ``dt`` after substituting ``dx=dx_dt*dt``."""
+
+        return sp.cancel(sp.sympify(dx_dt) * self.numerator / self.curve.y)
+
+
+@dataclass(frozen=True)
+class AbelianIntegralProfile:
+    """Canonical differential/homology profile of a generic smooth quotient.
+
+    ``abelian_dimension`` is the genus ``g`` and hence the number of independent
+    holomorphic differentials.  ``homology_rank`` is ``2g``.  These two numbers
+    are the dimensions that later enter the Abel--Jacobi/Jacobian construction;
+    no period values are claimed here.
+    """
+
+    curve: HyperellipticProfile
+    differentials: tuple[HyperellipticDifferential, ...]
+    abelian_dimension: int
+    homology_rank: int
+
+    def pullback_coefficients(self, dx_dt: sp.Expr) -> tuple[sp.Expr, ...]:
+        """Pull every canonical differential back along one reduced process."""
+
+        return tuple(
+            differential.pullback_coefficient(dx_dt)
+            for differential in self.differentials
+        )
+
+
+def holomorphic_differential_basis(
+    curve: HyperellipticProfile,
+) -> tuple[HyperellipticDifferential, ...]:
+    """Return ``dx/y, x dx/y, ..., x^(g-1) dx/y`` for generic genus ``g``.
+
+    The routine requires the curve profile to have a generic smooth genus.  For
+    genus zero the returned basis is empty.
+    """
+
+    genus = curve.generic_genus
+    if genus is None:
+        raise ValueError("holomorphic basis requires a generically smooth curve")
+    return tuple(HyperellipticDifferential(curve, power) for power in range(genus))
+
+
+def abelian_integral_profile(curve: HyperellipticProfile) -> AbelianIntegralProfile:
+    """Attach canonical differential and first-homology dimensions to a curve."""
+
+    basis = holomorphic_differential_basis(curve)
+    genus = curve.generic_genus
+    assert genus is not None
+    return AbelianIntegralProfile(
+        curve=curve,
+        differentials=basis,
+        abelian_dimension=genus,
+        homology_rank=2 * genus,
+    )

aeg_shakespeare/function_theory/algebraic.py

@@ -0,0 +1,105 @@
+"""Algebraic-curve profiles for process quotients.
+
+Mathematical lineage
+--------------------
+Elliptic and Abelian function theory historically did not begin as a catalogue
+of special functions.  Elliptic integrals led to inversion; inversion exposed
+periods; periods produced complex tori; and the resulting function theory was
+then algebraized by relations such as the Weierstrass cubic.  Riemann surfaces,
+algebraic curves, Abelian integrals, and Jacobians grew from this analytic and
+geometric circle of ideas.
+
+Shakespeare uses the same history in reverse as a calibration principle.  A
+primitive process may first force a constraint/invariant quotient.  Only after
+that quotient is visible do we ask what geometry and what function language are
+adequate.  Thus a relation ``y**2 = P(x)`` is not introduced because we already
+know the answer is elliptic or hyperelliptic; it is an algebraic shadow emitted
+by the process reduction.
+
+Implementation
+--------------
+This module deliberately implements only a small, exact observable:
+``HyperellipticProfile`` records degree, discriminant, generic genus, and the
+degeneration condition for ``y**2 = P(x)``.  That is enough for classical tests
+to distinguish genus-zero, genus-one, and higher-genus quotient regimes without
+preloading the corresponding named function theory.
+
+Boundary
+--------
+Genus is not a complete process normal form, and this module is not a general
+algebraic-geometry engine.  Period lattices, Abel-Jacobi maps, Jacobians, and
+function-field compression belong to later layers and should be derived when a
+calibration actually requires them.
+
+See ``docs/08-function-theory-genus-hierarchy.md`` and
+``docs/09-literate-programming-and-mathematical-lineage.md``.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import sympy as sp
+
+
+@dataclass(frozen=True)
+class HyperellipticProfile:
+    """Exact profile of ``y**2 = polynomial(x)`` over symbolic parameters."""
+
+    x: sp.Symbol
+    y: sp.Symbol
+    polynomial: sp.Expr
+    degree: int
+    discriminant: sp.Expr
+    generic_genus: int | None
+
+    @property
+    def relation(self) -> sp.Expr:
+        return sp.expand(self.y**2 - self.polynomial)
+
+    @property
+    def generically_smooth(self) -> bool:
+        """Whether the discriminant is not identically zero."""
+
+        return sp.simplify(self.discriminant) != 0
+
+    @property
+    def degeneration_condition(self) -> sp.Expr:
+        """Parameter expression whose vanishing marks repeated branch points."""
+
+        return sp.factor(self.discriminant)
+
+
+def hyperelliptic_profile(
+    x: sp.Symbol,
+    y: sp.Symbol,
+    polynomial: sp.Expr,
+) -> HyperellipticProfile:
+    """Analyze a process quotient in hyperelliptic form ``y**2 = P(x)``.
+
+    For square-free ``P`` of degree ``d >= 1``, the smooth projective
+    hyperelliptic curve has genus ``floor((d-1)/2)``.  With symbolic parameters,
+    a nonzero discriminant means that this is the *generic* genus away from the
+    displayed degeneration locus.
+    """
+
+    polynomial = sp.expand(sp.sympify(polynomial))
+    try:
+        poly = sp.Poly(polynomial, x)
+    except sp.PolynomialError as exc:
+        raise ValueError("hyperelliptic polynomial must be polynomial in x") from exc
+
+    degree = int(poly.degree())
+    if degree < 1:
+        raise ValueError("hyperelliptic polynomial must have positive degree")
+    discriminant = sp.factor(sp.discriminant(poly.as_expr(), x))
+    generic_genus = (degree - 1) // 2 if discriminant != 0 else None
+
+    return HyperellipticProfile(
+        x=x,
+        y=y,
+        polynomial=polynomial,
+        degree=degree,
+        discriminant=discriminant,
+        generic_genus=generic_genus,
+    )