odeanalysis 0.1.0__py3-none-any.whl

odeanalysis/_formal_gauge.py

@@ -0,0 +1,115 @@
+"""Formal gauge transformations and independently verifiable gauge records."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import sympy as sp
+
+from ._block_common import BlockDecompositionError
+from ._symbolic_errors import SYMBOLIC_FAILURES
+from .matrix_series import MatrixLaurentSeries
+
+
+def constant_series(variable: sp.Symbol, matrix: sp.MatrixBase) -> MatrixLaurentSeries:
+    """Represent a constant matrix as a Laurent matrix series."""
+
+    matrix = sp.Matrix(matrix)
+    return MatrixLaurentSeries.from_mapping(variable, {0: matrix}, shape=matrix.shape)
+
+
+def formal_gauge_transform(
+    connection: MatrixLaurentSeries,
+    gauge: MatrixLaurentSeries,
+    *,
+    max_power: int,
+) -> MatrixLaurentSeries:
+    """Apply ``A -> G^-1 A G - G^-1 G'`` through ``max_power``."""
+
+    if connection.rows != connection.cols or gauge.rows != gauge.cols:
+        raise ValueError("formal gauge transformation requires square series")
+    if connection.shape != gauge.shape:
+        raise ValueError("connection and gauge must have the same shape")
+    if connection.variable != gauge.variable:
+        raise ValueError("connection and gauge use different variables")
+    if connection.is_zero:
+        connection_min = 0
+    else:
+        connection_min = connection.min_power
+        if connection_min is None:
+            raise BlockDecompositionError("nonzero connection has no leading power")
+
+    inverse_order = max(0, max_power - connection_min)
+    try:
+        inverse = gauge.inverse(max_power=inverse_order)
+    except ValueError:
+        variable = connection.variable
+        g = sp.Matrix(gauge.to_matrix())
+        try:
+            ginv = g.inv()
+        except SYMBOLIC_FAILURES as exc:  # pragma: no cover
+            raise BlockDecompositionError(
+                "formal gauge is not Laurent-invertible"
+            ) from exc
+        a = sp.Matrix(connection.to_matrix())
+        transformed = ginv * a * g - ginv * g.diff(variable)
+        expanded = sp.zeros(connection.rows)
+        for i in range(connection.rows):
+            for j in range(connection.cols):
+                try:
+                    expanded[i, j] = (
+                        sp.series(
+                            sp.cancel(sp.together(transformed[i, j])),
+                            variable,
+                            0,
+                            max_power + 1,
+                        )
+                        .removeO()
+                        .expand()
+                    )
+                except SYMBOLIC_FAILURES as exc:
+                    raise BlockDecompositionError(
+                        "could not Laurent-expand a general formal gauge transform"
+                    ) from exc
+        return MatrixLaurentSeries.from_matrix(expanded, variable).truncate(
+            max_power=max_power
+        )
+    ag = connection.multiply(gauge, max_power=max_power)
+    conjugated = inverse.multiply(ag, max_power=max_power)
+    derivative = gauge.derivative(max_power=max_power)
+    correction = inverse.multiply(derivative, max_power=max_power)
+    return conjugated.add(correction.scale(-1), max_power=max_power)
+
+
+def multiply_gauges(
+    left: MatrixLaurentSeries,
+    right: MatrixLaurentSeries,
+    *,
+    max_power: int,
+) -> MatrixLaurentSeries:
+    """Multiply two formal gauges through ``max_power``."""
+
+    return left.multiply(right, max_power=max_power)
+
+
+@dataclass(frozen=True)
+class GaugeTransformationVerification:
+    """Stored data sufficient to verify one truncated formal gauge transform."""
+
+    source: MatrixLaurentSeries
+    gauge: MatrixLaurentSeries
+    transformed: MatrixLaurentSeries
+    max_power: int
+
+    def verify(self) -> bool:
+        """Recompute the stored transform without repeating reduction search."""
+
+        try:
+            expected = formal_gauge_transform(
+                self.source,
+                self.gauge,
+                max_power=self.max_power,
+            )
+        except (ValueError, BlockDecompositionError):
+            return False
+        return expected == self.transformed

odeanalysis/_local.py

@@ -0,0 +1,166 @@
+"""Shared local-coordinate, valuation, and linear-ODE data utilities."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import sympy as sp
+from funcprops import normalize_assumptions
+
+from ._assumptions import zero_status
+from ._power_simplify import analytic_powsimp
+from ._symbolic_errors import SYMBOLIC_FAILURES
+from .operator import LinearDifferentialOperator, _coerce_linear_operator
+
+
+@dataclass(frozen=True)
+class LinearODEData:
+    """Cheap canonical extraction shared by scalar linear-ODE analyses."""
+
+    operator: LinearDifferentialOperator
+    normalized: LinearDifferentialOperator
+
+    @property
+    def variable(self) -> sp.Symbol:
+        return self.operator.variable
+
+    @property
+    def order(self) -> int:
+        return self.operator.order
+
+    @property
+    def coefficients(self) -> tuple[sp.Expr, ...]:
+        return self.operator.coefficients
+
+    @property
+    def normalized_coefficients(self) -> tuple[sp.Expr, ...]:
+        return self.normalized.coefficients
+
+
+def linear_ode_data(
+    ode: sp.Expr | sp.Equality | LinearDifferentialOperator,
+    function: sp.FunctionClass | sp.Expr | None = None,
+    variable: sp.Symbol | None = None,
+) -> LinearODEData:
+    """Return canonical and monic operator data without property queries."""
+    operator = _coerce_linear_operator(ode, function, variable)
+    return LinearODEData(operator, operator.normalized())
+
+
+@dataclass(frozen=True)
+class LocalCoordinate:
+    """Uniform local coordinate at a finite point or infinity."""
+
+    original_operator: LinearDifferentialOperator
+    point: sp.Expr
+    operator: LinearDifferentialOperator
+    variable: sp.Symbol
+
+    @property
+    def is_infinity(self) -> bool:
+        return self.point == sp.oo
+
+    def to_original(self, expression: sp.Expr) -> sp.Expr:
+        x = self.original_operator.variable
+        if self.is_infinity:
+            return sp.simplify(sp.sympify(expression).subs(self.variable, 1 / x))
+        return sp.simplify(sp.sympify(expression).subs(self.variable, x - self.point))
+
+
+def local_coordinate(
+    ode: sp.Expr | sp.Equality | LinearDifferentialOperator,
+    function: sp.FunctionClass | sp.Expr | None = None,
+    variable: sp.Symbol | None = None,
+    *,
+    point: sp.Expr = 0,
+) -> LocalCoordinate:
+    """Localize an operator so the requested point is represented by ``t=0``."""
+    operator = _coerce_linear_operator(ode, function, variable)
+    point = sp.sympify(point)
+    t = sp.Dummy("t", positive=True)
+    u = sp.Function("_u")
+    if point == sp.oo:
+        local = operator.reciprocal_transform(u, t)
+    else:
+        coeffs = tuple(
+            sp.cancel(sp.together(c.subs(operator.variable, point + t)))
+            for c in operator.coefficients
+        )
+        remainder = sp.cancel(
+            sp.together(operator.inhomogeneous.subs(operator.variable, point + t))
+        )
+        local = LinearDifferentialOperator(t, u, coeffs, remainder)
+    return LocalCoordinate(operator, point, local, t)
+
+
+def rational_valuation(
+    expr: sp.Expr,
+    variable: sp.Symbol,
+    point: sp.Expr = 0,
+    *,
+    assumptions: sp.Expr | bool = True,
+) -> int | None:
+    """Return an exact integer local valuation for a rational expression when provable."""
+    assumptions = normalize_assumptions(assumptions)
+    t = sp.Dummy("t", positive=True)
+    try:
+        local = sp.cancel(sp.together(sp.sympify(expr).subs(variable, point + t)))
+        num, den = sp.fraction(local)
+        if zero_status(num, assumptions) is True:
+            return None
+        pn, pd = sp.Poly(num, t), sp.Poly(den, t)
+
+        def valuation(poly: sp.Poly) -> int | None:
+            for k in range(poly.degree() + 1):
+                status = zero_status(poly.nth(k), assumptions)
+                if status is False:
+                    return k
+                if status is None:
+                    return None
+            return None
+
+        vn, vd = valuation(pn), valuation(pd)
+        if vn is not None and vd is not None:
+            return vn - vd
+        return None
+    except (sp.PolynomialError, TypeError, ValueError):
+        pass
+    try:
+        local = sp.cancel(sp.together(sp.sympify(expr).subs(variable, point + t)))
+        lead = analytic_powsimp(local.as_leading_term(t))
+        exponent = sp.sympify(lead.as_powers_dict().get(t, 0))
+        if exponent.is_Integer:
+            return int(exponent)
+    except SYMBOLIC_FAILURES:
+        pass
+    return None
+
+
+def pole_order(
+    expr: sp.Expr,
+    variable: sp.Symbol,
+    point: sp.Expr = 0,
+    *,
+    assumptions: sp.Expr | bool = True,
+) -> int | None:
+    """Return exact pole order, zero for analytic expressions, or ``None``."""
+    expression = sp.cancel(sp.together(sp.sympify(expr)))
+    if zero_status(expression, assumptions) is True:
+        return 0
+    valuation = rational_valuation(expression, variable, point, assumptions=assumptions)
+    return None if valuation is None else max(0, -valuation)
+
+
+def pole_order_upper_bound(
+    expr: sp.Expr, variable: sp.Symbol, point: sp.Expr = 0
+) -> int | None:
+    """Return a rational upper bound on local pole order."""
+    t = sp.Dummy("t")
+    try:
+        local = sp.cancel(sp.together(sp.sympify(expr).subs(variable, point + t)))
+        _, den = sp.fraction(local)
+        poly = sp.Poly(den, t)
+        valuation = next((k for k in range(poly.degree() + 1) if poly.nth(k) != 0), 0)
+        return max(0, valuation)
+    except (sp.PolynomialError, TypeError, ValueError):
+        return None

odeanalysis/_moser.py

@@ -0,0 +1,271 @@
+"""Moser/Newton integer shearing for unresolved irregular blocks."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from itertools import combinations_with_replacement
+
+import sympy as sp
+
+from ._block_common import BlockDecompositionError
+from ._formal_gauge import (
+    GaugeTransformationVerification,
+    constant_series,
+    formal_gauge_transform,
+    multiply_gauges,
+)
+from ._spectral import first_irregular_spectral_data
+from ._symbolic_errors import SYMBOLIC_FAILURES
+from .diagnostics import ReductionDiagnostic
+from .matrix_series import MatrixLaurentSeries
+
+
+class MoserReductionError(BlockDecompositionError):
+    """Raised when a requested Moser/shearing reduction cannot be certified."""
+
+
+@dataclass(frozen=True)
+class MoserShearingStep:
+    """One exact integer shearing used to lower an irregular obstruction."""
+
+    pivot_power: int
+    eigenvalue: sp.Expr
+    nilpotent_rank_before: int
+    exponents: tuple[int, ...]
+    pivot_power_after: int | None
+    nilpotent_rank_after: int
+
+
+@dataclass(frozen=True)
+class MoserReduction:
+    """Result of recursive Moser/Newton integer shearing."""
+
+    original_connection: MatrixLaurentSeries
+    transformed_connection: MatrixLaurentSeries
+    gauge: MatrixLaurentSeries
+    steps: tuple[MoserShearingStep, ...]
+    complete: bool
+    limitation: str | None = None
+    diagnostics: tuple[ReductionDiagnostic, ...] = ()
+    gauge_verification: GaugeTransformationVerification | None = None
+
+    def verify(self) -> bool:
+        """Verify the retained total gauge transformation."""
+
+        return self.gauge_verification is not None and self.gauge_verification.verify()
+
+
+def _single_irregular_data(
+    connection: MatrixLaurentSeries,
+) -> tuple[int, sp.Matrix, sp.Expr, int] | None:
+    data = first_irregular_spectral_data(connection)
+    if data is None or data.distinct:
+        return None
+    eigenvalue = data.single_eigenvalue
+    if eigenvalue is None or data.nilpotent_rank is None:
+        return None
+    return (
+        data.power,
+        sp.Matrix(data.coefficient),
+        eigenvalue,
+        data.nilpotent_rank,
+    )
+
+
+def _candidate_measure(connection: MatrixLaurentSeries) -> tuple[int, int]:
+    """Return the Moser search measure using one eigenspectrum computation."""
+
+    data = first_irregular_spectral_data(connection)
+    if data is None:
+        return (0, 0)
+    if data.distinct:
+        return (0, 1)
+    if data.nilpotent_rank is None:
+        return (0, 0)
+    return (data.power, -data.nilpotent_rank)
+
+
+def _monomial_shear_transform(
+    connection: MatrixLaurentSeries,
+    exponents: tuple[int, ...],
+    *,
+    max_power: int,
+) -> MatrixLaurentSeries:
+    r"""Apply ``G=diag(t**s_i)`` without requiring a unit leading matrix."""
+
+    if len(exponents) != connection.rows:
+        raise ValueError("shearing exponent count must equal the system dimension")
+    variable = connection.variable
+    coefficients: dict[int, sp.Matrix] = {}
+    for power, coefficient_imm in connection.terms:
+        coefficient = sp.Matrix(coefficient_imm)
+        for i in range(connection.rows):
+            for j in range(connection.cols):
+                entry = coefficient[i, j]
+                if entry == 0:
+                    continue
+                shifted_power = power + exponents[j] - exponents[i]
+                if shifted_power > max_power:
+                    continue
+                target = coefficients.setdefault(
+                    shifted_power, sp.zeros(connection.rows, connection.cols)
+                )
+                target[i, j] += entry
+    residue = coefficients.setdefault(-1, sp.zeros(connection.rows, connection.cols))
+    for i, exponent in enumerate(exponents):
+        residue[i, i] -= exponent
+    return MatrixLaurentSeries.from_mapping(
+        variable, coefficients, shape=connection.shape
+    ).truncate(max_power=max_power)
+
+
+def _single_step(
+    connection: MatrixLaurentSeries,
+    *,
+    max_power: int,
+    max_shear: int,
+) -> tuple[MatrixLaurentSeries, MatrixLaurentSeries, MoserShearingStep] | None:
+    """Find one exact Jordan-basis integer shearing that improves Moser measure."""
+
+    data = _single_irregular_data(connection)
+    if data is None:
+        return None
+    pivot_power, coefficient, eigenvalue, rank_before = data
+    nilpotent = coefficient - eigenvalue * sp.eye(connection.rows)
+    if nilpotent.is_zero_matrix:
+        return None
+    try:
+        change, _jordan = nilpotent.jordan_form()
+    except SYMBOLIC_FAILURES as exc:  # pragma: no cover
+        raise MoserReductionError(
+            "could not construct a Jordan basis for Moser reduction"
+        ) from exc
+    if sp.simplify(change.det()) == 0:
+        raise MoserReductionError("Jordan basis for Moser reduction is singular")
+
+    constant = constant_series(connection.variable, change)
+    in_jordan_basis = formal_gauge_transform(connection, constant, max_power=max_power)
+    before = _candidate_measure(in_jordan_basis)
+    best: tuple[tuple[int, int], tuple[int, ...], MatrixLaurentSeries] | None = None
+
+    for weights_tail in combinations_with_replacement(
+        range(max_shear + 1), connection.rows - 1
+    ):
+        weights = (0, *tuple(int(weight) for weight in weights_tail))
+        if all(weight == 0 for weight in weights):
+            continue
+        candidate = _monomial_shear_transform(
+            in_jordan_basis, weights, max_power=max_power
+        )
+        measure = _candidate_measure(candidate)
+        if measure <= before:
+            continue
+        if (
+            best is None
+            or measure > best[0]
+            or (measure == best[0] and sum(weights) < sum(best[1]))
+        ):
+            best = (measure, weights, candidate)
+
+    if best is None:
+        return None
+    _, weights, transformed = best
+    after_data = _single_irregular_data(transformed)
+    if after_data is None:
+        pivot_after = None
+        rank_after = 0
+    else:
+        pivot_after, _, _, rank_after = after_data
+    shear_matrix = sp.diag(*(connection.variable**weight for weight in weights))
+    shear_series = MatrixLaurentSeries.from_matrix(shear_matrix, connection.variable)
+    gauge = multiply_gauges(
+        constant,
+        shear_series,
+        max_power=max_power - (connection.min_power or 0) + max(weights),
+    )
+    step = MoserShearingStep(
+        pivot_power=pivot_power,
+        eigenvalue=eigenvalue,
+        nilpotent_rank_before=rank_before,
+        exponents=weights,
+        pivot_power_after=pivot_after,
+        nilpotent_rank_after=rank_after,
+    )
+    return transformed, gauge, step
+
+
+def moser_reduce(
+    connection: MatrixLaurentSeries,
+    *,
+    max_power: int,
+    max_steps: int = 8,
+    max_shear: int | None = None,
+) -> MoserReduction:
+    """Reduce single-eigenvalue irregular blocks by bounded integer shearing."""
+
+    if connection.rows != connection.cols:
+        raise ValueError("Moser reduction requires a square Laurent connection")
+    if max_steps < 1:
+        raise ValueError("max_steps must be positive")
+    if max_shear is None:
+        max_shear = max(1, connection.rows)
+    if max_shear < 1:
+        raise ValueError("max_shear must be positive")
+
+    original = connection
+    current = connection
+    total_gauge = MatrixLaurentSeries.identity(connection.variable, connection.rows)
+    steps: list[MoserShearingStep] = []
+    limitation = None
+    for _ in range(max_steps):
+        data = first_irregular_spectral_data(current)
+        if data is None or data.distinct:
+            break
+        step_result = _single_step(current, max_power=max_power, max_shear=max_shear)
+        if step_result is None:
+            limitation = (
+                "no certified integer Moser/Newton shearing improved the leading "
+                "single-eigenvalue irregular block"
+            )
+            break
+        current, gauge, step = step_result
+        total_gauge = multiply_gauges(
+            total_gauge,
+            gauge,
+            max_power=max_power - (original.min_power or 0) + max_shear,
+        )
+        steps.append(step)
+    else:
+        limitation = "Moser reduction reached the configured step limit"
+
+    final_data = first_irregular_spectral_data(current)
+    complete = final_data is None or final_data.distinct
+    diagnostics: tuple[ReductionDiagnostic, ...] = ()
+    if complete:
+        limitation = None
+    else:
+        diagnostics = (
+            ReductionDiagnostic(
+                stage="moser",
+                code="unresolved-irregular-block",
+                message=limitation or "Moser reduction remained incomplete",
+                power=final_data.power,
+                rank=final_data.nilpotent_rank,
+            ),
+        )
+    verification = GaugeTransformationVerification(
+        source=original,
+        gauge=total_gauge,
+        transformed=current,
+        max_power=max_power,
+    )
+    return MoserReduction(
+        original_connection=original,
+        transformed_connection=current,
+        gauge=total_gauge,
+        steps=tuple(steps),
+        complete=complete,
+        limitation=limitation,
+        diagnostics=diagnostics,
+        gauge_verification=verification,
+    )

odeanalysis/_power_simplify.py

@@ -0,0 +1,32 @@
+"""Branch-aware power simplification helpers.
+
+``powsimp(..., force=True)`` is PowerExpand-like for unconstrained symbolic
+bases.  ODE coefficients are analytic data even when the local coordinate is a
+formal uniformizer, so whole ODE expressions must use branch-aware power
+simplification.  A separate formal helper is retained only for data structures
+that explicitly define their factors as formal monomials.
+"""
+
+from __future__ import annotations
+
+import sympy as sp
+
+
+def analytic_powsimp(expr: sp.Expr) -> sp.Expr:
+    """Simplify powers without assuming branch identities not proved by SymPy."""
+
+    return sp.powsimp(sp.sympify(expr), force=False)
+
+
+def formal_powsimp(expr: sp.Expr) -> sp.Expr:
+    """Canonicalize an expression known in its entirety to be a formal monomial."""
+
+    return sp.powsimp(sp.sympify(expr), force=True)
+
+
+def mixed_powsimp(coefficient: sp.Expr, monomial: sp.Expr) -> sp.Expr:
+    """Canonicalize a formal monomial without forcing identities in its coefficient."""
+
+    coefficient = analytic_powsimp(coefficient)
+    monomial = formal_powsimp(monomial)
+    return analytic_powsimp(coefficient * monomial)