odeanalysis 0.1.0__py3-none-any.whl

odeanalysis/local_analysis.py

@@ -0,0 +1,386 @@
+"""Parameter-aware local analysis of scalar linear ODEs."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import sympy as sp
+from funcprops import normalize_assumptions
+from semialg import implies, is_satisfiable, parametric_cad
+
+from ._assumptions import assumption_substitutions
+from .frobenius import FrobeniusAnalysis, frobenius_analysis
+from .operator import LinearDifferentialOperator, _coerce_linear_operator
+from .singularities import ODESingularity, ODESingularityKind, classify_ode_point
+
+
+@dataclass(frozen=True)
+class LocalAnalysisStratum:
+    """One parameter region with a stable local ODE classification."""
+
+    condition: sp.Expr
+    singularity: ODESingularity
+    frobenius: FrobeniusAnalysis | None = None
+
+
+@dataclass(frozen=True)
+class ResonanceStratum:
+    """Finite resonance condition for a quadratic indicial family."""
+
+    condition: sp.Expr
+    difference: int | None
+    resonant: bool | None
+
+
+@dataclass(frozen=True)
+class ParameterizedLocalAnalysis:
+    """Finite stratification of parameter-dependent local behavior."""
+
+    point: sp.Expr
+    assumptions: sp.Expr
+    strata: tuple[LocalAnalysisStratum, ...]
+    exhaustive: bool
+    resonance_conditions: tuple[sp.Expr, ...] = ()
+    resonance_strata: tuple[ResonanceStratum, ...] = ()
+
+    def select(self, assumptions: sp.Expr | bool = True) -> LocalAnalysisStratum | None:
+        query = normalize_assumptions(sp.And(self.assumptions, assumptions))
+        parameters = tuple(sorted(query.free_symbols, key=sp.default_sort_key))
+        matches = [
+            stratum
+            for stratum in self.strata
+            if implies(query, stratum.condition, parameters)
+        ]
+        return matches[0] if len(matches) == 1 else None
+
+
+def _local_operator(
+    operator: LinearDifferentialOperator, point: sp.Expr
+) -> tuple[LinearDifferentialOperator, sp.Expr]:
+    if point != sp.oo:
+        return operator, point
+    t = sp.Dummy("t", positive=True)
+    u = sp.Function("_u")
+    return operator.reciprocal_transform(u, t), sp.S.Zero
+
+
+def _valuation_atoms(
+    operator: LinearDifferentialOperator, point: sp.Expr
+) -> tuple[sp.Expr, ...]:
+    """Return parameter expressions whose vanishing can change pole orders."""
+    op, local_point = _local_operator(operator, point)
+    x = op.variable
+    h = sp.Dummy("h")
+    atoms: set[sp.Expr] = set()
+    normalized = op.normalized().coefficients
+    for j, coeff in enumerate(normalized[:-1]):
+        try:
+            local = sp.cancel(sp.together(coeff.subs(x, local_point + h)))
+            num, den = sp.fraction(local)
+            den_poly = sp.Poly(den, h)
+            den_val = next(
+                (k for k in range(den_poly.degree() + 1) if den_poly.nth(k) != 0), 0
+            )
+            # A cancellation matters to ordinary/regular/irregular classification
+            # only when the generic denominator order exceeds the Fuchs bound.
+            if den_val <= op.order - j:
+                continue
+            for poly_expr in (num,):
+                poly = sp.Poly(poly_expr, h)
+                # Only coefficients before the first structurally nonzero term
+                # can alter the local valuation.
+                for k in range(poly.degree() + 1):
+                    c = sp.factor(poly.nth(k))
+                    if c == 0:
+                        continue
+                    params = c.free_symbols - {x, h}
+                    if params:
+                        atoms.add(c)
+                    if not params:
+                        break
+        except (sp.PolynomialError, TypeError, ValueError):
+            continue
+    return tuple(sorted(atoms, key=sp.default_sort_key))
+
+
+def _indicial_atoms(
+    operator: LinearDifferentialOperator,
+    point: sp.Expr,
+    assumptions: sp.Expr,
+) -> tuple[sp.Expr, ...]:
+    op, local_point = _local_operator(operator, point)
+    local = classify_ode_point(op, point=local_point, assumptions=assumptions)
+    poly = local.indicial_polynomial
+    if (
+        local.kind is not ODESingularityKind.REGULAR
+        or poly is None
+        or operator.order != 2
+    ):
+        return ()
+    r = sp.Symbol("r")
+    try:
+        p = sp.Poly(poly, r)
+        disc = sp.factor(sp.discriminant(p.as_expr(), r))
+    except (sp.PolynomialError, TypeError, ValueError):
+        return ()
+    return (disc,) if disc.free_symbols else ()
+
+
+@dataclass(frozen=True)
+class _ParameterCase:
+    condition: sp.Expr
+    signature: tuple[bool | None, ...]
+
+
+def _transition_signature(
+    premise: sp.Expr,
+    transition_polynomials: tuple[sp.Expr, ...],
+    parameters: tuple[sp.Symbol, ...],
+) -> tuple[bool | None, ...]:
+    """Return certified zero/nonzero facts for one semialgebraic cell."""
+    signature: list[bool | None] = []
+    for polynomial in transition_polynomials:
+        zero = sp.Eq(polynomial, 0, evaluate=False)
+        if implies(premise, zero, parameters):
+            signature.append(True)
+        elif implies(premise, sp.Ne(polynomial, 0, evaluate=False), parameters):
+            signature.append(False)
+        else:
+            signature.append(None)
+    return tuple(signature)
+
+
+def _parameter_cases(
+    transition_polynomials: tuple[sp.Expr, ...],
+    assumptions: sp.Expr,
+) -> tuple[tuple[_ParameterCase, ...], bool]:
+    """Return ODE-signature-grouped semialgebraic cells."""
+    parameters = tuple(
+        sorted(
+            set().union(
+                *(poly.free_symbols for poly in transition_polynomials),
+                assumptions.free_symbols,
+            ),
+            key=sp.default_sort_key,
+        )
+    )
+    if not parameters:
+        cases = (
+            (_ParameterCase(sp.S.true, ()),) if is_satisfiable(assumptions, ()) else ()
+        )
+        return cases, True
+
+    marker = (
+        sp.Ne(sp.prod(transition_polynomials), 0, evaluate=False)
+        if transition_polynomials
+        else sp.S.true
+    )
+    geometry = parametric_cad(
+        marker,
+        (),
+        parameters=parameters,
+        assumptions=assumptions,
+        output="result",
+    )
+    groups: dict[tuple[bool | None, ...], list[sp.Expr]] = {}
+    for case in geometry.cases:
+        premise = sp.And(assumptions, case.condition)
+        if not is_satisfiable(premise, parameters):
+            continue
+        signature = _transition_signature(premise, transition_polynomials, parameters)
+        groups.setdefault(signature, []).append(case.condition)
+    cases = tuple(
+        _ParameterCase(sp.Or(*cells), signature) for signature, cells in groups.items()
+    )
+    # A complete semialg result already certifies coverage of the supplied
+    # parameter domain; re-proving the disjunction with equivalent() is both
+    # redundant and substantially more expensive on larger decompositions.
+    return cases, geometry.status == "complete"
+
+
+def _case_assumptions(
+    case: _ParameterCase,
+    assumptions: sp.Expr,
+    transition_polynomials: tuple[sp.Expr, ...],
+) -> sp.Expr:
+    """Materialize the zero/nonzero facts already certified for a grouped cell."""
+    facts: list[sp.Expr] = [assumptions]
+    for polynomial, state in zip(transition_polynomials, case.signature, strict=True):
+        if state is True:
+            facts.append(sp.Eq(polynomial, 0, evaluate=False))
+        elif state is False:
+            facts.append(sp.Ne(polynomial, 0, evaluate=False))
+    return normalize_assumptions(sp.And(*facts))
+
+
+@dataclass(frozen=True)
+class _LocalContext:
+    operator: LinearDifferentialOperator
+    point: sp.Expr
+    display_point: sp.Expr
+
+    @classmethod
+    def build(
+        cls, operator: LinearDifferentialOperator, point: sp.Expr
+    ) -> _LocalContext:
+        local_operator, local_point = _local_operator(operator, point)
+        return cls(local_operator, local_point, point)
+
+    def classify(self, assumptions: sp.Expr) -> ODESingularity:
+        local = classify_ode_point(
+            self.operator, point=self.point, assumptions=assumptions
+        )
+        if self.display_point != sp.oo:
+            return local
+        return ODESingularity(
+            point=sp.oo,
+            kind=local.kind,
+            order=local.order,
+            normalized_coefficients=local.normalized_coefficients,
+            pole_orders=local.pole_orders,
+            indicial_polynomial=local.indicial_polynomial,
+            indicial_roots=local.indicial_roots,
+            transformed_equation=self.operator.expression,
+        )
+
+    def frobenius(self, assumptions: sp.Expr, terms: int) -> FrobeniusAnalysis | None:
+        substitutions = assumption_substitutions(assumptions)
+        operator = self.operator
+        if substitutions:
+            operator = LinearDifferentialOperator(
+                operator.variable,
+                operator.function,
+                tuple(c.subs(substitutions) for c in operator.coefficients),
+                operator.inhomogeneous.subs(substitutions),
+            )
+        try:
+            return frobenius_analysis(
+                operator, point=self.point, terms=terms, assumptions=assumptions
+            )
+        except (ValueError, NotImplementedError):
+            return None
+
+
+def _finite_resonance_strata(
+    discriminant: sp.Expr | None,
+    assumptions: sp.Expr,
+    max_order: int,
+) -> tuple[ResonanceStratum, ...]:
+    if discriminant is None or not discriminant.free_symbols:
+        return ()
+    parameters = tuple(
+        sorted(
+            set().union(discriminant.free_symbols, assumptions.free_symbols),
+            key=sp.default_sort_key,
+        )
+    )
+    equations = tuple(
+        sp.Eq(discriminant, n * n, evaluate=False) for n in range(1, max_order + 1)
+    )
+    strata = [
+        ResonanceStratum(sp.And(assumptions, equation), n, True)
+        for n, equation in enumerate(equations, 1)
+        if is_satisfiable(sp.And(assumptions, equation), parameters)
+    ]
+    if equations:
+        complement = sp.And(
+            assumptions,
+            *(
+                sp.Ne(discriminant, n * n, evaluate=False)
+                for n in range(1, max_order + 1)
+            ),
+        )
+        if is_satisfiable(complement, parameters):
+            strata.append(ResonanceStratum(complement, None, None))
+    return tuple(strata)
+
+
+def local_parameter_analysis(
+    ode: sp.Expr | sp.Equality | LinearDifferentialOperator,
+    function: sp.FunctionClass | sp.Expr | None = None,
+    variable: sp.Symbol | None = None,
+    point: sp.Expr = 0,
+    *,
+    terms: int = 6,
+    assumptions: sp.Expr | bool = True,
+    max_resonance_order: int = 4,
+) -> ParameterizedLocalAnalysis:
+    """Classify local behavior on finite parameter strata.
+
+    Strata are generated only from algebraic conditions that can change local
+    coefficient valuations or the multiplicity of a quadratic indicial
+    polynomial.  Unresolved transcendental/integer resonances remain explicit
+    conditions rather than being guessed.
+    """
+    operator = _coerce_linear_operator(ode, function, variable)
+    assumptions = normalize_assumptions(assumptions)
+    if max_resonance_order < 0:
+        raise ValueError("max_resonance_order must be nonnegative")
+    point = sp.sympify(point)
+    atoms = _valuation_atoms(operator, point)
+    atoms += tuple(
+        a for a in _indicial_atoms(operator, point, assumptions) if a not in atoms
+    )
+    # Resonance hypersurfaces are part of the same parameter geometry as
+    # valuation and repeated-root transitions.
+    op0, p0 = _local_operator(operator, point)
+    local0 = classify_ode_point(op0, point=p0, assumptions=assumptions)
+    discriminant = None
+    if (
+        local0.kind is ODESingularityKind.REGULAR
+        and local0.indicial_polynomial is not None
+        and operator.order == 2
+    ):
+        r = sp.Symbol("r")
+        try:
+            discriminant = sp.factor(
+                sp.discriminant(sp.Poly(local0.indicial_polynomial, r).as_expr(), r)
+            )
+        except (sp.PolynomialError, TypeError, ValueError):
+            discriminant = None
+    transition_polynomials = tuple(dict.fromkeys(atoms))
+    cases, geometry_certified = _parameter_cases(transition_polynomials, assumptions)
+    strata: list[LocalAnalysisStratum] = []
+    context = _LocalContext.build(operator, point)
+    for case in cases:
+        local_assumptions = _case_assumptions(case, assumptions, transition_polynomials)
+        local = context.classify(local_assumptions)
+        frob = (
+            context.frobenius(local_assumptions, terms)
+            if local.kind is ODESingularityKind.REGULAR
+            else None
+        )
+        candidate = LocalAnalysisStratum(case.condition, local, frob)
+        for index, existing in enumerate(strata):
+            if (
+                existing.singularity == candidate.singularity
+                and existing.frobenius == candidate.frobenius
+            ):
+                strata[index] = LocalAnalysisStratum(
+                    sp.Or(existing.condition, case.condition), local, frob
+                )
+                break
+        else:
+            strata.append(candidate)
+
+    # Merge strata with identical local signatures only when no Frobenius
+    # degeneracy distinction would be lost.
+    resonance: list[sp.Expr] = []
+    for stratum in strata:
+        f = stratum.frobenius
+        if f is None or len(f.root_multiplicities) != 2:
+            continue
+        a, b = (root for root, _ in f.root_multiplicities)
+        resonance.append(sp.Contains(sp.simplify(a - b), sp.S.Integers))
+    resonance_strata = _finite_resonance_strata(
+        discriminant, assumptions, max_resonance_order
+    )
+
+    return ParameterizedLocalAnalysis(
+        point=point,
+        assumptions=assumptions,
+        strata=tuple(strata),
+        exhaustive=geometry_certified,
+        resonance_conditions=tuple(dict.fromkeys(resonance)),
+        resonance_strata=resonance_strata,
+    )

odeanalysis/local_structure.py

@@ -0,0 +1,290 @@
+"""Unified local singularity structure for scalar linear ODEs."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, replace
+
+import sympy as sp
+from funcprops import normalize_assumptions
+
+from ._assumptions import zero_status
+from ._local import LocalCoordinate, local_coordinate
+from .formal_basis import (
+    FormalBasisError,
+    formal_monodromy,
+    logarithmic_frobenius_basis,
+)
+from .frobenius import FrobeniusAnalysis, frobenius_analysis
+from .fuchsian import ApparentSingularityAnalysis, apparent_singularity_analysis
+from .operator import LinearDifferentialOperator, _coerce_linear_operator
+from .singularities import ODESingularity, ODESingularityKind, analyze_ode_singularities
+
+
+@dataclass(frozen=True)
+class FrobeniusConvergence:
+    """Convergence geometry certified from singularities of the ODE coefficients.
+
+    ``radius`` is the coefficient-analyticity radius.  It is not
+    presented as a maximal continuation radius for every solution: apparent
+    singularities or special solutions may continue farther.
+    """
+
+    point: sp.Expr
+    radius: sp.Expr | None
+    nearest_singularities: tuple[sp.Expr, ...]
+    domain: sp.Expr | None
+    certified: bool
+    coordinate: sp.Symbol
+    solution_continuation_radius: sp.Expr | None = None
+    solution_continuation_certified: bool = False
+
+    @property
+    def coefficient_radius(self) -> sp.Expr | None:
+        return self.radius
+
+    @property
+    def coefficient_domain(self) -> sp.Expr | None:
+        return self.domain
+
+
+@dataclass(frozen=True)
+class FrobeniusLocalMonodromy:
+    """Local monodromy derived from completed Frobenius data."""
+
+    point: sp.Expr
+    matrix: sp.ImmutableMatrix | None
+    certified: bool
+    logarithmic: bool | None
+    reason: str
+
+
+@dataclass(frozen=True)
+class SingularityPointStructure:
+    """Unified evidence attached to one singular point."""
+
+    singularity: ODESingularity
+    frobenius: FrobeniusAnalysis | None
+    convergence: FrobeniusConvergence | None
+    apparent: ApparentSingularityAnalysis | None
+    monodromy: FrobeniusLocalMonodromy | None
+    local_coordinate: LocalCoordinate | None = None
+
+
+@dataclass(frozen=True)
+class SingularityStructure:
+    """Unified finite/infinite singularity structure of a scalar linear ODE."""
+
+    operator: LinearDifferentialOperator
+    assumptions: sp.Expr
+    points: tuple[SingularityPointStructure, ...]
+
+    def at(self, point: sp.Expr) -> SingularityPointStructure | None:
+        point = sp.sympify(point)
+        return next(
+            (item for item in self.points if item.singularity.point == point), None
+        )
+
+
+def _coefficient_singularities(
+    operator: LinearDifferentialOperator,
+) -> tuple[tuple[sp.Expr, ...], bool]:
+    """Return finite coefficient singularities and whether the list is exhaustive."""
+    x = operator.variable
+    points: set[sp.Expr] = set()
+    exhaustive = True
+    for coeff in operator.normalized().coefficients[:-1]:
+        expr = sp.cancel(sp.together(coeff))
+        _, den = sp.fraction(expr)
+        try:
+            poly = sp.Poly(den, x)
+        except (sp.PolynomialError, TypeError, ValueError):
+            exhaustive = False
+            try:
+                singular = sp.singularities(expr, x)
+            except (NotImplementedError, ValueError):
+                continue
+            if isinstance(singular, sp.FiniteSet):
+                points.update(singular)
+            continue
+        if poly.degree() <= 0:
+            continue
+        try:
+            roots = sp.roots(poly.as_expr(), x, cubics=False, quartics=False)
+        except (NotImplementedError, TypeError, ValueError, sp.PolynomialError):
+            roots = {}
+        if roots and sum(int(m) for m in roots.values()) == poly.degree():
+            points.update(roots)
+            continue
+        try:
+            all_roots = poly.all_roots()
+        except (NotImplementedError, TypeError, ValueError, sp.PolynomialError):
+            exhaustive = False
+        else:
+            if len(all_roots) == poly.degree():
+                points.update(all_roots)
+            else:
+                exhaustive = False
+    return tuple(sorted(points, key=sp.default_sort_key)), exhaustive
+
+
+def frobenius_convergence(
+    analysis: FrobeniusAnalysis,
+    *,
+    singular_points: tuple[sp.Expr, ...] | None = None,
+) -> FrobeniusConvergence:
+    """Return the coefficient-analyticity disk controlling a Frobenius series."""
+    operator = analysis.operator
+    x = operator.variable
+    point = analysis.point
+    if point == sp.oo:
+        return FrobeniusConvergence(point, None, (), None, False, x)
+    if singular_points is None:
+        points, exhaustive = _coefficient_singularities(operator)
+    else:
+        points, exhaustive = tuple(singular_points), True
+    others = tuple(p for p in points if zero_status(p - point) is not True)
+    if not others:
+        radius = sp.oo if exhaustive else None
+        domain = sp.S.true if radius is sp.oo else None
+        return FrobeniusConvergence(point, radius, (), domain, exhaustive, x)
+    distances = tuple(sp.simplify(sp.Abs(p - point)) for p in others)
+    radius = distances[0] if len(distances) == 1 else sp.Min(*distances)
+    nearest = tuple(
+        p
+        for p, distance in zip(others, distances, strict=True)
+        if zero_status(distance - radius) is True
+    )
+    domain = sp.Abs(x - point) < radius
+    return FrobeniusConvergence(point, radius, nearest, domain, exhaustive, x)
+
+
+def frobenius_local_monodromy(analysis: FrobeniusAnalysis) -> FrobeniusLocalMonodromy:
+    """Derive local monodromy from a completed Frobenius analysis."""
+    if (
+        not analysis.root_multiplicities
+        or len(analysis.roots) != analysis.operator.order
+    ):
+        return FrobeniusLocalMonodromy(
+            analysis.point, None, False, None, "indicial roots are incomplete"
+        )
+    if not analysis.logarithm_may_be_required:
+        diag = [sp.exp(2 * sp.pi * sp.I * root) for root in analysis.roots]
+        return FrobeniusLocalMonodromy(
+            analysis.point,
+            sp.ImmutableMatrix(sp.diag(*diag)),
+            True,
+            False,
+            "pure-power Frobenius basis gives diagonal local monodromy",
+        )
+    try:
+        basis = logarithmic_frobenius_basis(
+            analysis.operator, point=analysis.point, terms=max(analysis.terms, 8)
+        )
+        if not basis.complete or basis.dimension != analysis.operator.order:
+            raise FormalBasisError("incomplete logarithmic Frobenius basis")
+        monodromy = formal_monodromy(basis)
+    except (FormalBasisError, NotImplementedError, ValueError):
+        return FrobeniusLocalMonodromy(
+            analysis.point,
+            None,
+            False,
+            analysis.logarithm_required,
+            "a complete logarithmic Frobenius basis could not be certified",
+        )
+    matrix = monodromy.local_matrix
+    if matrix is None:
+        return FrobeniusLocalMonodromy(
+            analysis.point,
+            None,
+            False,
+            basis.has_logarithms,
+            "physical one-turn monodromy is unavailable on the ramified cover",
+        )
+    return FrobeniusLocalMonodromy(
+        analysis.point,
+        sp.ImmutableMatrix(matrix),
+        True,
+        basis.has_logarithms,
+        "completed logarithmic Frobenius basis determines local monodromy",
+    )
+
+
+def _regular_point_structure(
+    original: LinearDifferentialOperator,
+    singularity: ODESingularity,
+    assumptions: sp.Expr,
+    terms: int,
+    finite_points: tuple[sp.Expr, ...],
+    finite_points_certified: bool,
+) -> SingularityPointStructure:
+    point = singularity.point
+    coordinate = local_coordinate(original, point=point)
+    local_operator = coordinate.operator if point == sp.oo else original
+    local_point = sp.S.Zero if point == sp.oo else point
+    try:
+        frob = frobenius_analysis(
+            local_operator, point=local_point, terms=terms, assumptions=assumptions
+        )
+    except (NotImplementedError, ValueError):
+        return SingularityPointStructure(
+            singularity, None, None, None, None, coordinate
+        )
+    monodromy = frobenius_local_monodromy(frob)
+    if point == sp.oo:
+        local_points, exhaustive = _coefficient_singularities(local_operator)
+        convergence = frobenius_convergence(frob, singular_points=local_points)
+        convergence = replace(
+            convergence, point=sp.oo, certified=convergence.certified and exhaustive
+        )
+        monodromy = replace(monodromy, point=sp.oo)
+    else:
+        convergence = frobenius_convergence(frob, singular_points=finite_points)
+        if not finite_points_certified:
+            convergence = replace(convergence, certified=False)
+    apparent = apparent_singularity_analysis(
+        original,
+        point=point,
+        assumptions=assumptions,
+        frobenius=frob,
+        monodromy=monodromy,
+    )
+    return SingularityPointStructure(
+        singularity, frob, convergence, apparent, monodromy, coordinate
+    )
+
+
+def singularity_structure(
+    ode: sp.Expr | sp.Equality | LinearDifferentialOperator,
+    function: sp.FunctionClass | sp.Expr | None = None,
+    variable: sp.Symbol | None = None,
+    *,
+    assumptions: sp.Expr | bool = True,
+    terms: int = 8,
+    include_infinity: bool = True,
+) -> SingularityStructure:
+    """Build one coherent local-analysis object for every singular point."""
+    operator = _coerce_linear_operator(ode, function, variable)
+    assumptions = normalize_assumptions(assumptions)
+    global_data = analyze_ode_singularities(
+        operator, include_infinity=include_infinity, assumptions=assumptions
+    )
+    singularities = list(global_data.finite)
+    if global_data.infinity is not None:
+        singularities.append(global_data.infinity)
+    finite_points, finite_points_certified = _coefficient_singularities(operator)
+    items: list[SingularityPointStructure] = []
+    for singularity in singularities:
+        if singularity.kind is ODESingularityKind.REGULAR:
+            items.append(
+                _regular_point_structure(
+                    operator,
+                    singularity,
+                    assumptions,
+                    terms,
+                    finite_points,
+                    finite_points_certified,
+                )
+            )
+        else:
+            items.append(SingularityPointStructure(singularity, None, None, None, None))
+    return SingularityStructure(operator, assumptions, tuple(items))