odeanalysis 0.1.0__py3-none-any.whl

odeanalysis/_spectral.py

@@ -0,0 +1,215 @@
+"""Exact spectral classification and verification for formal block reduction."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import sympy as sp
+
+from ._block_common import BlockDecompositionError, is_scalar_matrix
+from ._symbolic_errors import SYMBOLIC_FAILURES
+from .matrix_series import MatrixLaurentSeries
+
+
+@dataclass(frozen=True)
+class IrregularSpectralData:
+    """First nonscalar irregular coefficient and its exact spectral data."""
+
+    power: int
+    coefficient: sp.ImmutableMatrix
+    eigenvalues: tuple[tuple[sp.Expr, int], ...]
+    nilpotent_rank: int | None
+
+    @property
+    def distinct(self) -> bool:
+        return len(self.eigenvalues) >= 2
+
+    @property
+    def single_eigenvalue(self) -> sp.Expr | None:
+        if len(self.eigenvalues) != 1:
+            return None
+        return self.eigenvalues[0][0]
+
+
+@dataclass(frozen=True)
+class SpectralSplitVerification:
+    """Evidence for an exact decomposition into generalized eigenspaces."""
+
+    coefficient: sp.ImmutableMatrix
+    eigenvalues: tuple[sp.Expr, ...]
+    dimensions: tuple[int, ...]
+    projectors: tuple[sp.ImmutableMatrix, ...]
+
+    def verify(self) -> bool:
+        """Verify projector partition, dimensions, and spectral invariance."""
+
+        matrix = sp.Matrix(self.coefficient)
+        if matrix.rows != matrix.cols:
+            return False
+        if len(self.eigenvalues) != len(self.dimensions):
+            return False
+        if len(self.projectors) != len(self.dimensions):
+            return False
+        if sum(self.dimensions) != matrix.rows:
+            return False
+        identity = sp.eye(matrix.rows)
+        total = sp.zeros(matrix.rows)
+        for i, (value, dimension, projector_imm) in enumerate(
+            zip(self.eigenvalues, self.dimensions, self.projectors, strict=True)
+        ):
+            projector = sp.Matrix(projector_imm)
+            if projector.shape != matrix.shape or int(projector.rank()) != dimension:
+                return False
+            if any(
+                sp.simplify(entry) != 0 for entry in projector * projector - projector
+            ):
+                return False
+            if any(
+                sp.simplify(entry) != 0
+                for entry in matrix * projector - projector * matrix
+            ):
+                return False
+            generalized = (matrix - value * identity) ** matrix.rows
+            if any(sp.simplify(entry) != 0 for entry in generalized * projector):
+                return False
+            for other in self.projectors[i + 1 :]:
+                if any(
+                    sp.simplify(entry) != 0 for entry in projector * sp.Matrix(other)
+                ):
+                    return False
+            total += projector
+        return all(sp.simplify(entry) == 0 for entry in total - identity)
+
+
+@dataclass(frozen=True)
+class FormalSpectralSplit:
+    """One exact spectral split encountered during recursive reduction."""
+
+    pivot_power: int
+    eigenvalues: tuple[sp.Expr, ...]
+    dimensions: tuple[int, ...]
+    projectors: tuple[sp.ImmutableMatrix, ...]
+    verification: SpectralSplitVerification
+
+    def verify(self) -> bool:
+        """Verify the retained generalized-eigenspace decomposition."""
+
+        return self.verification.verify()
+
+
+def first_irregular_spectral_data(
+    connection: MatrixLaurentSeries,
+) -> IrregularSpectralData | None:
+    """Classify the first nonscalar irregular coefficient with one eigen solve."""
+
+    for power, coefficient_imm in connection.terms:
+        if power >= -1:
+            break
+        coefficient = sp.Matrix(coefficient_imm)
+        scalar, _ = is_scalar_matrix(coefficient)
+        if scalar:
+            continue
+        try:
+            eigenvalues = coefficient.eigenvals()
+        except SYMBOLIC_FAILURES as exc:
+            raise BlockDecompositionError(
+                f"could not determine eigenvalues at Laurent order {power}"
+            ) from exc
+        if sum(int(mult) for mult in eigenvalues.values()) != coefficient.rows:
+            raise BlockDecompositionError(
+                f"characteristic polynomial did not split at Laurent order {power}"
+            )
+        ordered = tuple(
+            (value, int(mult))
+            for value, mult in sorted(
+                eigenvalues.items(), key=lambda item: sp.default_sort_key(item[0])
+            )
+        )
+        rank: int | None = None
+        if len(ordered) == 1:
+            raw_value, multiplicity = ordered[0]
+            value = sp.simplify(raw_value)
+            ordered = ((value, multiplicity),)
+            if multiplicity != coefficient.rows:
+                raise BlockDecompositionError(
+                    f"single-eigenvalue multiplicity is incomplete at Laurent order {power}"
+                )
+            rank = int((coefficient - value * sp.eye(coefficient.rows)).rank())
+        return IrregularSpectralData(
+            power=power,
+            coefficient=sp.ImmutableMatrix(coefficient),
+            eigenvalues=ordered,
+            nilpotent_rank=rank,
+        )
+    return None
+
+
+def generalized_eigenbasis(
+    matrix: sp.MatrixBase,
+) -> tuple[
+    sp.ImmutableMatrix,
+    tuple[int, ...],
+    tuple[sp.Expr, ...],
+    tuple[sp.ImmutableMatrix, ...],
+]:
+    """Return a generalized-eigenspace basis and exact spectral projectors."""
+
+    matrix = sp.Matrix(matrix)
+    if matrix.rows != matrix.cols:
+        raise BlockDecompositionError(
+            "spectral splitting requires a square coefficient"
+        )
+    n = matrix.rows
+    try:
+        eigenvalues = matrix.eigenvals()
+    except SYMBOLIC_FAILURES as exc:  # pragma: no cover
+        raise BlockDecompositionError(
+            "could not compute exact leading eigenvalues"
+        ) from exc
+    if sum(int(mult) for mult in eigenvalues.values()) != n:
+        raise BlockDecompositionError(
+            "leading characteristic polynomial did not split completely"
+        )
+    ordered = sorted(eigenvalues.items(), key=lambda item: sp.default_sort_key(item[0]))
+    if len(ordered) < 2:
+        raise BlockDecompositionError("coefficient has no distinct spectral groups")
+
+    columns: list[sp.Matrix] = []
+    dimensions: list[int] = []
+    values: list[sp.Expr] = []
+    for eigenvalue, multiplicity_expr in ordered:
+        multiplicity = int(multiplicity_expr)
+        generalized = (matrix - eigenvalue * sp.eye(n)) ** n
+        basis = generalized.nullspace()
+        if len(basis) != multiplicity:
+            raise BlockDecompositionError(
+                "could not construct the complete generalized eigenspace "
+                f"for eigenvalue {eigenvalue!s}"
+            )
+        columns.extend(basis)
+        dimensions.append(multiplicity)
+        values.append(sp.simplify(eigenvalue))
+
+    change = sp.Matrix.hstack(*columns)
+    if change.rank() != n:
+        raise BlockDecompositionError(
+            "generalized eigenspaces did not form a full basis"
+        )
+    inverse = change.inv()
+    projectors: list[sp.ImmutableMatrix] = []
+    offset = 0
+    for dimension in dimensions:
+        selector = sp.zeros(n)
+        for index in range(offset, offset + dimension):
+            selector[index, index] = 1
+        projector = change * selector * inverse
+        projectors.append(
+            sp.ImmutableMatrix(projector.applyfunc(lambda entry: sp.simplify(entry)))
+        )
+        offset += dimension
+    return (
+        sp.ImmutableMatrix(change),
+        tuple(dimensions),
+        tuple(values),
+        tuple(projectors),
+    )

odeanalysis/_symbolic_compare.py

@@ -0,0 +1,16 @@
+"""Small exact-comparison helpers shared by structural algorithms."""
+
+from __future__ import annotations
+
+import sympy as sp
+
+
+def expressions_equal(left: sp.Expr, right: sp.Expr) -> bool:
+    """Return whether two expressions simplify to the same exact value."""
+
+    if left == right:
+        return True
+    difference = sp.simplify(left - right)
+    if difference == 0:
+        return True
+    return sp.simplify(sp.expand(difference)) == 0

odeanalysis/_symbolic_errors.py

@@ -0,0 +1,19 @@
+"""Exception groups for recoverable symbolic-backend failures."""
+
+from sympy.core.function import PoleError
+from sympy.matrices.exceptions import MatrixError
+from sympy.polys.polyerrors import CoercionFailed, GeneratorsNeeded, PolynomialError
+
+SYMBOLIC_FAILURES = (
+    TypeError,
+    ValueError,
+    NotImplementedError,
+    ArithmeticError,
+    PoleError,
+    MatrixError,
+    PolynomialError,
+    CoercionFailed,
+    GeneratorsNeeded,
+)
+
+NUMERIC_CONVERSION_FAILURES = (TypeError, ValueError, OverflowError)

odeanalysis/_zero.py

@@ -0,0 +1,28 @@
+"""Conservative exact zero classification for certification boundaries."""
+
+from __future__ import annotations
+
+from enum import Enum
+
+import sympy as sp
+
+
+class ZeroStatus(Enum):
+    ZERO = "zero"
+    NONZERO = "nonzero"
+    UNKNOWN = "unknown"
+
+
+def exact_zero_status(expression: sp.Expr) -> ZeroStatus:
+    """Classify exact zero/nonzero without assuming generic parameter values."""
+    expression = sp.sympify(expression)
+    if expression.is_zero is True:
+        return ZeroStatus.ZERO
+    if expression.is_zero is False:
+        return ZeroStatus.NONZERO
+    simplified = sp.cancel(sp.together(expression))
+    if simplified.is_zero is True or simplified == 0:
+        return ZeroStatus.ZERO
+    if simplified.is_zero is False:
+        return ZeroStatus.NONZERO
+    return ZeroStatus.UNKNOWN

odeanalysis/analytic_continuation.py

@@ -0,0 +1,343 @@
+"""Exact analytic-continuation data for supported canonical equations.
+
+The implementation keeps Gamma-function coefficients factored and
+verifies matrix relations structurally.  It does not feed large symbolic
+connection matrices to ``sympy.simplify``; that is both unnecessary and a
+source of severe order-dependent test-suite degradation.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+
+import sympy as sp
+
+
+class CanonicalBasis(Enum):
+    """Named canonical local/sectorial bases."""
+
+    HYPERGEOMETRIC_ZERO = "hypergeometric_zero"
+    HYPERGEOMETRIC_ONE = "hypergeometric_one"
+    HYPERGEOMETRIC_INFINITY = "hypergeometric_infinity"
+    KUMMER_INFINITY_PLUS = "kummer_infinity_plus"
+    KUMMER_INFINITY_MINUS = "kummer_infinity_minus"
+    AIRY_WKB = "airy_wkb"
+    EULER_ZERO = "euler_zero"
+
+
+@dataclass(frozen=True)
+class ConnectionMatrix:
+    """Connection ``C_{target<-source}`` with ``F_source = F_target*C``.
+
+    Consequently coefficient columns transport as ``v_target = C*v_source``.
+    """
+
+    source: CanonicalBasis
+    target: CanonicalBasis
+    matrix: sp.ImmutableMatrix
+    exact: bool = True
+
+    def inverse(self) -> ConnectionMatrix:
+        """Reverse a nonsingular rank-two connection matrix explicitly."""
+
+        if self.matrix.shape != (2, 2):
+            raise ValueError("connection matrix must be 2-by-2")
+        a, b = self.matrix[0, 0], self.matrix[0, 1]
+        c, d = self.matrix[1, 0], self.matrix[1, 1]
+        det = a * d - b * c
+        if det.is_zero is True:
+            raise ValueError("connection matrix is singular")
+        inv = sp.ImmutableMatrix(((d / det, -b / det), (-c / det, a / det)))
+        return ConnectionMatrix(self.target, self.source, inv, self.exact)
+
+    def then(self, other: ConnectionMatrix) -> ConnectionMatrix:
+        """Compose ``C_{B<-A}`` then ``C_{C<-B}`` as ``C_{C<-A}``."""
+
+        if self.target is not other.source:
+            raise ValueError("connection bases do not compose")
+        # Y_A=Y_B C_AB and Y_B=Y_C C_BC => C_AC=C_BC*C_AB.
+        return ConnectionMatrix(
+            self.source,
+            other.target,
+            other.matrix * self.matrix,
+            self.exact and other.exact,
+        )
+
+    def verify(self) -> bool:
+        """Check the inexpensive structural invariants of the stored connection."""
+
+        if self.matrix.shape != (2, 2):
+            return False
+        if self.source is self.target:
+            return self.matrix == sp.ImmutableMatrix.eye(2)
+        return True
+
+
+@dataclass(frozen=True)
+class StokesMatrix:
+    """Exact Stokes jump in a fixed canonical formal normalization."""
+
+    family: str
+    ray_index: int
+    matrix: sp.ImmutableMatrix
+    exact: bool = True
+
+    def verify(self) -> bool:
+        """A normalized rank-two Stokes factor is unitriangular."""
+
+        if self.matrix.shape != (2, 2):
+            return False
+        return (
+            self.matrix.det() == 1 and self.matrix[0, 0] == 1 and self.matrix[1, 1] == 1
+        )
+
+
+@dataclass(frozen=True)
+class LocalMonodromy:
+    """Actual monodromy for one positive circuit in the stated local coordinate.
+
+    At a finite point the local coordinate is ``t=x-x0``.  At infinity it is
+    ``t=1/x``; a positive counterclockwise circuit in ``t`` is therefore a
+    clockwise circuit in the global ``x``-plane.
+    """
+
+    family: str
+    point: sp.Expr
+    basis: str
+    matrix: sp.ImmutableMatrix
+    formal_matrix: sp.ImmutableMatrix
+    stokes_factors: tuple[StokesMatrix, ...] = ()
+
+    def verify(self) -> bool:
+        """Replay the ordered formal/Stokes product without global simplify."""
+
+        product = self.formal_matrix
+        for factor in self.stokes_factors:
+            product = factor.matrix * product
+        return product == self.matrix
+
+
+def _gamma(x: sp.Expr) -> sp.Expr:
+    return sp.gamma(x)
+
+
+def hypergeometric_connection_matrix(
+    a: sp.Expr,
+    b: sp.Expr,
+    c: sp.Expr,
+    source: CanonicalBasis = CanonicalBasis.HYPERGEOMETRIC_ZERO,
+    target: CanonicalBasis = CanonicalBasis.HYPERGEOMETRIC_ONE,
+) -> ConnectionMatrix:
+    """Return an exact nonresonant Gauss-hypergeometric connection matrix.
+
+    Primitive formulae are retained in factored Gamma form.  Other directions
+    are obtained by cheap 2-by-2 inversion/composition, never ``simplify``.
+    """
+
+    a, b, c = map(sp.sympify, (a, b, c))
+    allowed = {
+        CanonicalBasis.HYPERGEOMETRIC_ZERO,
+        CanonicalBasis.HYPERGEOMETRIC_ONE,
+        CanonicalBasis.HYPERGEOMETRIC_INFINITY,
+    }
+    if source not in allowed or target not in allowed:
+        raise ValueError(
+            "source and target must be Gauss-hypergeometric canonical bases"
+        )
+    zero_one = sp.ImmutableMatrix(
+        (
+            (
+                _gamma(c) * _gamma(c - a - b) / (_gamma(c - a) * _gamma(c - b)),
+                _gamma(2 - c) * _gamma(c - a - b) / (_gamma(1 - a) * _gamma(1 - b)),
+            ),
+            (
+                _gamma(c) * _gamma(a + b - c) / (_gamma(a) * _gamma(b)),
+                _gamma(2 - c)
+                * _gamma(a + b - c)
+                / (_gamma(a - c + 1) * _gamma(b - c + 1)),
+            ),
+        )
+    )
+    # Infinity basis is chosen so the two standard continuation coefficients
+    # are the columns below; this absorbs the fixed branch phases of the
+    # second zero solution into the basis normalization.
+    zero_inf = sp.ImmutableMatrix(
+        (
+            (
+                _gamma(c) * _gamma(b - a) / (_gamma(b) * _gamma(c - a)),
+                _gamma(2 - c) * _gamma(b - a) / (_gamma(b - c + 1) * _gamma(1 - a)),
+            ),
+            (
+                _gamma(c) * _gamma(a - b) / (_gamma(a) * _gamma(c - b)),
+                _gamma(2 - c) * _gamma(a - b) / (_gamma(a - c + 1) * _gamma(1 - b)),
+            ),
+        )
+    )
+    c01 = ConnectionMatrix(
+        CanonicalBasis.HYPERGEOMETRIC_ZERO, CanonicalBasis.HYPERGEOMETRIC_ONE, zero_one
+    )
+    c0i = ConnectionMatrix(
+        CanonicalBasis.HYPERGEOMETRIC_ZERO,
+        CanonicalBasis.HYPERGEOMETRIC_INFINITY,
+        zero_inf,
+    )
+    if source is target:
+        return ConnectionMatrix(source, target, sp.ImmutableMatrix.eye(2))
+    primitive = {(c01.source, c01.target): c01, (c0i.source, c0i.target): c0i}
+    if (source, target) in primitive:
+        return primitive[(source, target)]
+    if (target, source) in primitive:
+        return primitive[(target, source)].inverse()
+    # Only remaining nontrivial pair is 1 <-> infinity.
+    one_zero = c01.inverse()
+    one_inf = one_zero.then(c0i)
+    if (
+        source is CanonicalBasis.HYPERGEOMETRIC_ONE
+        and target is CanonicalBasis.HYPERGEOMETRIC_INFINITY
+    ):
+        return one_inf
+    if (
+        source is CanonicalBasis.HYPERGEOMETRIC_INFINITY
+        and target is CanonicalBasis.HYPERGEOMETRIC_ONE
+    ):
+        return one_inf.inverse()
+    raise ValueError("unsupported hypergeometric basis")
+
+
+def connection_matrix(
+    family: str,
+    source: CanonicalBasis,
+    target: CanonicalBasis,
+    **params: sp.Expr,
+) -> ConnectionMatrix:
+    """Return an exact canonical connection matrix when implemented."""
+
+    name = family.lower()
+    if name in {"hypergeometric", "gauss"}:
+        return hypergeometric_connection_matrix(
+            params["a"], params["b"], params["c"], source, target
+        )
+    if name in {"kummer", "confluent_hypergeometric"}:
+        plus, minus = kummer_connection_matrices(params["a"], params["c"])
+        for candidate in (plus, minus):
+            if candidate.source is source and candidate.target is target:
+                return candidate
+            if candidate.target is source and candidate.source is target:
+                return candidate.inverse()
+        raise ValueError("unsupported Kummer basis pair")
+    raise ValueError(f"exact connection matrices are not implemented for {family!r}")
+
+
+def kummer_connection_matrices(
+    a: sp.Expr, c: sp.Expr
+) -> tuple[ConnectionMatrix, ConnectionMatrix]:
+    """Return the two exact lateral Kummer connection matrices at infinity."""
+
+    a, c = map(sp.sympify, (a, c))
+    # A compact formal normalization: only the branch-sensitive algebraic
+    # coefficient changes laterally.  Keeping the common Gamma factors
+    # factored is essential for predictable symbolic cost.
+    algebraic = _gamma(c) / _gamma(c - a)
+    exponential = _gamma(c) / _gamma(a)
+    phase = sp.exp(sp.I * sp.pi * a)
+    plus = sp.ImmutableMatrix(((algebraic * phase, 0), (exponential, 1)))
+    minus = sp.ImmutableMatrix(((algebraic / phase, 0), (exponential, 1)))
+    return (
+        ConnectionMatrix(
+            CanonicalBasis.HYPERGEOMETRIC_ZERO,
+            CanonicalBasis.KUMMER_INFINITY_PLUS,
+            plus,
+        ),
+        ConnectionMatrix(
+            CanonicalBasis.HYPERGEOMETRIC_ZERO,
+            CanonicalBasis.KUMMER_INFINITY_MINUS,
+            minus,
+        ),
+    )
+
+
+def stokes_matrices(family: str, **params: sp.Expr) -> tuple[StokesMatrix, ...]:
+    """Return exact normalized Stokes factors for supported canonical families."""
+
+    name = family.lower()
+    if name == "airy":
+        i = sp.I
+        return (
+            StokesMatrix("airy", 0, sp.ImmutableMatrix(((1, i), (0, 1)))),
+            StokesMatrix("airy", 1, sp.ImmutableMatrix(((1, 0), (i, 1)))),
+            StokesMatrix("airy", 2, sp.ImmutableMatrix(((1, i), (0, 1)))),
+        )
+    if name in {"hypergeometric", "gauss"}:
+        return ()
+    if name in {"kummer", "confluent_hypergeometric"}:
+        a = sp.sympify(params["a"])
+        c = sp.sympify(params["c"])
+        # Standard formal normalization.  These multipliers stay factored;
+        # no Gamma reflection simplification is performed here.
+        upper = (
+            2
+            * sp.pi
+            * sp.I
+            * sp.exp(sp.I * sp.pi * (c - a))
+            / (_gamma(a) * _gamma(1 + a - c))
+        )
+        lower = (
+            2
+            * sp.pi
+            * sp.I
+            * sp.exp(sp.I * sp.pi * a)
+            / (_gamma(c - a) * _gamma(1 - a))
+        )
+        return (
+            StokesMatrix("kummer", 0, sp.ImmutableMatrix(((1, upper), (0, 1)))),
+            StokesMatrix("kummer", 1, sp.ImmutableMatrix(((1, 0), (lower, 1)))),
+        )
+    raise ValueError(f"exact Stokes matrices are not implemented for {family!r}")
+
+
+def local_monodromy(family: str, point: sp.Expr, **params: sp.Expr) -> LocalMonodromy:
+    """Return actual monodromy for a positive circuit in the local coordinate.
+
+    Infinity uses ``t=1/x``.  Thus an infinity basis with powers ``x**(-a)``
+    and ``x**(-b)`` has local multipliers ``exp(2*pi*I*a)`` and
+    ``exp(2*pi*I*b)``.
+    """
+
+    name = family.lower()
+    point = sp.sympify(point)
+    if name in {"euler", "euler_cauchy"}:
+        if point != 0:
+            raise ValueError("Euler--Cauchy monodromy is implemented at the origin")
+        alpha, beta = map(sp.sympify, (params["alpha"], params["beta"]))
+        discriminant = sp.sqrt((alpha - 1) ** 2 - 4 * beta)
+        rho_plus = sp.simplify((1 - alpha + discriminant) / 2)
+        rho_minus = sp.simplify((1 - alpha - discriminant) / 2)
+        matrix = sp.ImmutableMatrix.diag(
+            sp.exp(2 * sp.pi * sp.I * rho_plus),
+            sp.exp(2 * sp.pi * sp.I * rho_minus),
+        )
+        return LocalMonodromy("euler", point, "power", matrix, matrix)
+    if name in {"hypergeometric", "gauss"}:
+        a, b, c = map(sp.sympify, (params["a"], params["b"], params["c"]))
+        if point == 0:
+            matrix = sp.ImmutableMatrix.diag(1, sp.exp(2 * sp.pi * sp.I * (1 - c)))
+        elif point == 1:
+            matrix = sp.ImmutableMatrix.diag(1, sp.exp(2 * sp.pi * sp.I * (c - a - b)))
+        elif point == sp.oo:
+            matrix = sp.ImmutableMatrix.diag(
+                sp.exp(2 * sp.pi * sp.I * a), sp.exp(2 * sp.pi * sp.I * b)
+            )
+        else:
+            raise ValueError("Gauss monodromy point must be 0, 1, or infinity")
+        return LocalMonodromy("hypergeometric", point, "frobenius", matrix, matrix)
+    if name == "airy" and point == sp.oo:
+        factors = stokes_matrices("airy")
+        formal = sp.ImmutableMatrix(((0, -sp.I), (-sp.I, 0)))
+        product = formal
+        for factor in factors:
+            product = factor.matrix * product
+        return LocalMonodromy("airy", point, "exact_wkb", product, formal, factors)
+    raise ValueError(
+        f"actual local monodromy is not implemented for {family!r} at {point}"
+    )