odeanalysis 0.1.0__py3-none-any.whl

odeanalysis/parameter_wkb.py

@@ -0,0 +1,92 @@
+"""Certified parameter strata for turning-point and uniform-WKB structure."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import sympy as sp
+from semialg import parametric_cad
+
+from .operator import LinearDifferentialOperator, _coerce_linear_operator
+from .transition_loci import turning_loci
+from .turning import analyze_turning_points
+
+
+@dataclass(frozen=True)
+class ParameterizedTurningStratum:
+    condition: sp.Expr
+    sample: tuple[tuple[sp.Symbol, sp.Expr], ...]
+    finite_multiplicities: tuple[int, ...]
+    turning_kinds: tuple[str, ...]
+    uniform_families: tuple[str | None, ...]
+    certified: bool
+
+
+@dataclass(frozen=True)
+class ParameterizedTurningAnalysis:
+    parameters: tuple[sp.Symbol, ...]
+    transition_polynomials: tuple[sp.Expr, ...]
+    strata: tuple[ParameterizedTurningStratum, ...]
+    exhaustive: bool
+
+
+def parameterized_turning_analysis(
+    ode: sp.Expr | sp.Equality | LinearDifferentialOperator,
+    function: sp.FunctionClass | sp.Expr | None = None,
+    variable: sp.Symbol | None = None,
+    *,
+    parameters: tuple[sp.Symbol, ...],
+    assumptions: sp.Expr | bool = True,
+) -> ParameterizedTurningAnalysis:
+    """Stratify parameter space where finite turning multiplicities are constant.
+
+    The discriminant/degree-loss loci are computed symbolically; each CAD cell
+    is checked by exact specialization and turning-point analysis.  This is the
+    parameter geometry needed to choose Airy versus degenerate Weber local
+    uniformization without crossing a confluence locus.
+    """
+    op = _coerce_linear_operator(ode, function, variable)
+    loci = tuple(dict.fromkeys(turning_loci(op)))
+    marker = sp.Ne(sp.prod(loci), 0, evaluate=False) if loci else sp.S.true
+    geometry = parametric_cad(
+        marker,
+        (),
+        parameters=parameters,
+        assumptions=sp.sympify(assumptions),
+        output="result",
+    )
+    strata: list[ParameterizedTurningStratum] = []
+    for case in geometry.cases:
+        sample = dict(case.sample)
+        specialized = LinearDifferentialOperator(
+            op.variable,
+            op.function,
+            tuple(sp.cancel(sp.sympify(c).subs(sample)) for c in op.coefficients),
+            sp.cancel(sp.sympify(op.inhomogeneous).subs(sample)),
+        )
+        analysis = analyze_turning_points(specialized)
+        finite = tuple(tp for tp in analysis.points if tp.point != sp.oo)
+        strata.append(
+            ParameterizedTurningStratum(
+                case.condition,
+                tuple(
+                    sorted(
+                        sample.items(), key=lambda item: sp.default_sort_key(item[0])
+                    )
+                ),
+                tuple(tp.multiplicity for tp in finite),
+                tuple(tp.kind.value for tp in finite),
+                tuple(
+                    "airy"
+                    if tp.multiplicity == 1
+                    else "weber"
+                    if tp.multiplicity == 2
+                    else None
+                    for tp in finite
+                ),
+                geometry.status == "complete",
+            )
+        )
+    return ParameterizedTurningAnalysis(
+        parameters, loci, tuple(strata), geometry.status == "complete"
+    )

odeanalysis/series.py

@@ -0,0 +1,199 @@
+"""Small sparse Laurent-series representation for formal local calculations.
+
+Powers are integral in a chosen uniformizing parameter ``t``.  A Puiseux
+series in a local coordinate ``h`` is therefore represented after choosing
+``h = t**r``.  The class provides only the operations needed by
+formal ODE recurrences: addition, multiplication, truncation, and the ramified
+local derivative ``D_h``.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+
+import sympy as sp
+
+
+@dataclass(frozen=True)
+class SparseLaurentSeries:
+    """Finite sparse Laurent series in an integral-power uniformizer."""
+
+    variable: sp.Symbol
+    terms: tuple[tuple[int, sp.Expr], ...]
+
+    def __post_init__(self) -> None:
+        combined: dict[int, sp.Expr] = {}
+        for power, coefficient in self.terms:
+            if not isinstance(power, int):
+                raise TypeError("Laurent powers must be integers")
+            coefficient = sp.sympify(coefficient)
+            if coefficient == 0:
+                continue
+            combined[power] = sp.expand(combined.get(power, sp.S.Zero) + coefficient)
+        cleaned = tuple(
+            (power, coefficient)
+            for power, coefficient in sorted(combined.items())
+            if coefficient != 0
+        )
+        object.__setattr__(self, "terms", cleaned)
+
+    @classmethod
+    def zero(cls, variable: sp.Symbol) -> SparseLaurentSeries:
+        return cls(variable, ())
+
+    @classmethod
+    def one(cls, variable: sp.Symbol) -> SparseLaurentSeries:
+        return cls(variable, ((0, sp.S.One),))
+
+    @classmethod
+    def from_mapping(
+        cls,
+        variable: sp.Symbol,
+        coefficients: Mapping[int, sp.Expr],
+    ) -> SparseLaurentSeries:
+        return cls(variable, tuple(coefficients.items()))
+
+    @classmethod
+    def from_expr(
+        cls,
+        expression: sp.Expr,
+        variable: sp.Symbol,
+    ) -> SparseLaurentSeries:
+        """Create a finite Laurent series from an expanded Laurent polynomial."""
+
+        expression = sp.expand(sp.sympify(expression))
+        if expression == 0:
+            return cls.zero(variable)
+
+        terms: list[tuple[int, sp.Expr]] = []
+        for term in sp.Add.make_args(expression):
+            coefficient, power = term.as_coeff_exponent(variable)
+            power = sp.sympify(power)
+            if not power.is_Integer:
+                raise ValueError(
+                    "expression is not a finite Laurent polynomial with integral powers"
+                )
+            # as_coeff_exponent leaves non-monomial dependence in the coefficient.
+            if coefficient.has(variable):
+                raise ValueError(
+                    "expression is not a finite Laurent polynomial in the requested variable"
+                )
+            terms.append((int(power), coefficient))
+        return cls(variable, tuple(terms))
+
+    @property
+    def is_zero(self) -> bool:
+        return not self.terms
+
+    @property
+    def min_power(self) -> int | None:
+        return None if not self.terms else self.terms[0][0]
+
+    @property
+    def max_power(self) -> int | None:
+        return None if not self.terms else self.terms[-1][0]
+
+    def as_dict(self) -> dict[int, sp.Expr]:
+        return dict(self.terms)
+
+    def to_expr(self) -> sp.Expr:
+        return sp.Add(
+            *(coefficient * self.variable**power for power, coefficient in self.terms)
+        )
+
+    def truncate(
+        self,
+        *,
+        min_power: int | None = None,
+        max_power: int | None = None,
+    ) -> SparseLaurentSeries:
+        if min_power is not None and max_power is not None and min_power > max_power:
+            return self.zero(self.variable)
+        return SparseLaurentSeries(
+            self.variable,
+            tuple(
+                (power, coefficient)
+                for power, coefficient in self.terms
+                if (min_power is None or power >= min_power)
+                and (max_power is None or power <= max_power)
+            ),
+        )
+
+    def scale(self, scalar: sp.Expr) -> SparseLaurentSeries:
+        scalar = sp.sympify(scalar)
+        if scalar == 0:
+            return self.zero(self.variable)
+        return SparseLaurentSeries(
+            self.variable,
+            tuple((power, scalar * coefficient) for power, coefficient in self.terms),
+        )
+
+    def add(
+        self,
+        other: SparseLaurentSeries,
+        *,
+        min_power: int | None = None,
+        max_power: int | None = None,
+    ) -> SparseLaurentSeries:
+        self._check_variable(other)
+        coefficients = self.as_dict()
+        for power, coefficient in other.terms:
+            coefficients[power] = coefficients.get(power, sp.S.Zero) + coefficient
+        return SparseLaurentSeries.from_mapping(self.variable, coefficients).truncate(
+            min_power=min_power,
+            max_power=max_power,
+        )
+
+    def multiply(
+        self,
+        other: SparseLaurentSeries,
+        *,
+        min_power: int | None = None,
+        max_power: int | None = None,
+    ) -> SparseLaurentSeries:
+        self._check_variable(other)
+        coefficients: dict[int, sp.Expr] = {}
+        for left_power, left_coefficient in self.terms:
+            for right_power, right_coefficient in other.terms:
+                power = left_power + right_power
+                if min_power is not None and power < min_power:
+                    continue
+                if max_power is not None and power > max_power:
+                    continue
+                coefficients[power] = (
+                    coefficients.get(power, sp.S.Zero)
+                    + left_coefficient * right_coefficient
+                )
+        return SparseLaurentSeries.from_mapping(self.variable, coefficients)
+
+    def derivative(
+        self,
+        *,
+        ramification_index: int = 1,
+        min_power: int | None = None,
+        max_power: int | None = None,
+    ) -> SparseLaurentSeries:
+        r"""Differentiate with respect to ``h`` when ``h=t**r``.
+
+        ``D_h(c*t**p) = (p/r) c*t**(p-r)``.
+        """
+
+        if ramification_index < 1:
+            raise ValueError("ramification_index must be positive")
+        result = SparseLaurentSeries(
+            self.variable,
+            tuple(
+                (
+                    power - ramification_index,
+                    sp.Rational(power, ramification_index) * coefficient,
+                )
+                for power, coefficient in self.terms
+                if power != 0
+            ),
+        )
+        return result.truncate(min_power=min_power, max_power=max_power)
+
+    def _check_variable(self, other: SparseLaurentSeries) -> None:
+        if self.variable != other.variable:
+            raise ValueError("Laurent series use different uniformizing variables")

odeanalysis/singularities.py

@@ -0,0 +1,279 @@
+"""Singularity analysis for scalar linear ordinary differential equations."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import StrEnum
+
+import sympy as sp
+from funcprops import normalize_assumptions
+
+from ._assumptions import assumption_substitutions
+from ._local import linear_ode_data
+from ._local import pole_order as _pole_order
+from ._local import pole_order_upper_bound as _pole_order_upper_bound
+from ._symbolic_errors import SYMBOLIC_FAILURES
+from .operator import (
+    LinearDifferentialOperator,
+    _coerce_linear_operator,
+    as_ode_expression,
+    function_class,
+)
+
+
+class ODESingularityKind(StrEnum):
+    """Local classification of a scalar linear ODE."""
+
+    ORDINARY = "ordinary"
+    REGULAR = "regular_singular"
+    IRREGULAR = "irregular_singular"
+    UNKNOWN = "unknown"
+
+
+@dataclass(frozen=True)
+class ODESingularity:
+    """Local singularity data for a scalar linear ODE."""
+
+    point: sp.Expr
+    kind: ODESingularityKind
+    order: int
+    normalized_coefficients: tuple[sp.Expr, ...]
+    pole_orders: tuple[int | None, ...]
+    indicial_polynomial: sp.Expr | None = None
+    indicial_roots: tuple[sp.Expr, ...] = ()
+    transformed_equation: sp.Expr | None = None
+
+    @property
+    def regular(self) -> bool:
+        return self.kind in {ODESingularityKind.ORDINARY, ODESingularityKind.REGULAR}
+
+
+@dataclass(frozen=True)
+class ODESingularityAnalysis:
+    """Singularity analysis of a scalar linear ODE."""
+
+    equation: sp.Expr
+    function: sp.FunctionClass
+    variable: sp.Symbol
+    order: int
+    finite: tuple[ODESingularity, ...]
+    infinity: ODESingularity | None = None
+    operator: LinearDifferentialOperator | None = None
+
+    @property
+    def singular_points(self) -> tuple[sp.Expr, ...]:
+        points = tuple(
+            item.point
+            for item in self.finite
+            if item.kind is not ODESingularityKind.ORDINARY
+        )
+        if (
+            self.infinity is not None
+            and self.infinity.kind is not ODESingularityKind.ORDINARY
+        ):
+            points += (sp.oo,)
+        return points
+
+
+def _finite_singular_candidates(
+    normalized: tuple[sp.Expr, ...], variable: sp.Symbol
+) -> tuple[sp.Expr, ...]:
+    points: set[sp.Expr] = set()
+    for coeff in normalized[:-1]:
+        try:
+            singular = sp.singularities(coeff, variable)
+        except (NotImplementedError, ValueError):
+            continue
+        if isinstance(singular, sp.FiniteSet):
+            points.update(singular)
+    return tuple(sorted(points, key=sp.default_sort_key))
+
+
+def _indicial_data(
+    normalized: tuple[sp.Expr, ...],
+    order: int,
+    variable: sp.Symbol,
+    point: sp.Expr,
+) -> tuple[sp.Expr | None, tuple[sp.Expr, ...]]:
+    r = sp.Symbol("r")
+    poly = sp.ff(r, order)
+    for j in range(order):
+        scale = (variable - point) ** (order - j)
+        try:
+            b = sp.simplify(sp.limit(scale * normalized[j], variable, point))
+        except SYMBOLIC_FAILURES:
+            return None, ()
+        if b.has(sp.oo, -sp.oo, sp.zoo, sp.nan):
+            return None, ()
+        poly += b * sp.ff(r, j)
+    poly = sp.factor(sp.expand(poly))
+    roots: tuple[sp.Expr, ...] = ()
+    try:
+        root_dict = sp.roots(poly, r)
+        if root_dict:
+            roots = tuple(
+                root
+                for root, multiplicity in root_dict.items()
+                for _ in range(multiplicity)
+            )
+    except SYMBOLIC_FAILURES:
+        pass
+    return poly, roots
+
+
+def classify_ode_point(
+    ode: sp.Expr | sp.Equality | LinearDifferentialOperator,
+    function: sp.FunctionClass | sp.Expr | None = None,
+    variable: sp.Symbol | None = None,
+    point: sp.Expr = 0,
+    *,
+    assumptions: sp.Expr | bool = True,
+) -> ODESingularity:
+    """Classify one finite point of a scalar linear ODE or operator."""
+
+    data = linear_ode_data(ode, function, variable)
+    operator = data.operator
+    normalized = data.normalized_coefficients
+    x = operator.variable
+    order = operator.order
+    point = sp.sympify(point)
+    assumptions = normalize_assumptions(assumptions)
+    substitutions = assumption_substitutions(assumptions)
+    if substitutions:
+        normalized = tuple(sp.cancel(c.subs(substitutions)) for c in normalized)
+    pole_orders = (
+        *tuple(
+            _pole_order(
+                normalized[j],
+                x,
+                point,
+                assumptions=sp.S.true
+                if (_pole_order_upper_bound(normalized[j], x, point) or 0) <= order - j
+                else assumptions,
+            )
+            for j in range(order)
+        ),
+        0,
+    )
+    known = pole_orders[:-1]
+    if all(value == 0 for value in known):
+        kind = ODESingularityKind.ORDINARY
+    elif all(
+        (value is not None and value <= order - j)
+        or (
+            value is None
+            and (_pole_order_upper_bound(normalized[j], x, point) or 0) <= order - j
+        )
+        for j, value in enumerate(known)
+    ):
+        kind = ODESingularityKind.REGULAR
+    elif any(value is None for value in known):
+        kind = ODESingularityKind.UNKNOWN
+    else:
+        kind = ODESingularityKind.IRREGULAR
+
+    indicial = None
+    roots: tuple[sp.Expr, ...] = ()
+    if kind is ODESingularityKind.REGULAR:
+        indicial, roots = _indicial_data(normalized, order, x, point)
+    return ODESingularity(
+        point=point,
+        kind=kind,
+        order=order,
+        normalized_coefficients=normalized,
+        pole_orders=pole_orders,
+        indicial_polynomial=indicial,
+        indicial_roots=roots,
+    )
+
+
+def change_ode_variable_reciprocal(
+    ode: sp.Expr | sp.Equality | LinearDifferentialOperator,
+    function: sp.FunctionClass | sp.Expr | None = None,
+    variable: sp.Symbol | None = None,
+    new_function: sp.FunctionClass | sp.Expr | None = None,
+    new_variable: sp.Symbol | None = None,
+) -> sp.Expr:
+    """Transform an ODE under ``variable = 1/new_variable``."""
+
+    operator = _coerce_linear_operator(ode, function, variable)
+    if new_function is None or new_variable is None:
+        raise TypeError("new_function and new_variable are required")
+    transformed = operator.reciprocal_transform(new_function, new_variable)
+    return sp.factor(sp.together(transformed.expression))
+
+
+def analyze_ode_singularities(
+    ode: sp.Expr | sp.Equality | LinearDifferentialOperator,
+    function: sp.FunctionClass | sp.Expr | None = None,
+    variable: sp.Symbol | None = None,
+    *,
+    include_infinity: bool = True,
+    assumptions: sp.Expr | bool = True,
+) -> ODESingularityAnalysis:
+    """Find and classify singular points of a scalar linear ODE."""
+
+    operator = _coerce_linear_operator(ode, function, variable)
+    assumptions = normalize_assumptions(assumptions)
+    normalized = operator.normalized().coefficients
+    finite = tuple(
+        classify_ode_point(operator, point=p, assumptions=assumptions)
+        for p in _finite_singular_candidates(normalized, operator.variable)
+    )
+
+    infinity: ODESingularity | None = None
+    if include_infinity:
+        t = sp.Dummy("t", positive=True)
+        u = sp.Function("_u")
+        transformed_operator = operator.reciprocal_transform(u, t)
+        local = classify_ode_point(
+            transformed_operator, point=sp.S.Zero, assumptions=assumptions
+        )
+        infinity = 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=transformed_operator.expression,
+        )
+
+    return ODESingularityAnalysis(
+        equation=operator.expression,
+        function=operator.function,
+        variable=operator.variable,
+        order=operator.order,
+        finite=finite,
+        infinity=infinity,
+        operator=operator,
+    )
+
+
+def ode_singular_points(
+    ode: sp.Expr | sp.Equality | LinearDifferentialOperator,
+    function: sp.FunctionClass | sp.Expr | None = None,
+    variable: sp.Symbol | None = None,
+    *,
+    include_infinity: bool = True,
+    assumptions: sp.Expr | bool = True,
+) -> tuple[tuple[sp.Expr, ODESingularityKind], ...]:
+    """Compact ``(point, classification)`` view of singularity analysis."""
+
+    analysis = analyze_ode_singularities(
+        ode,
+        function,
+        variable,
+        include_infinity=include_infinity,
+        assumptions=assumptions,
+    )
+    result = tuple((item.point, item.kind) for item in analysis.finite)
+    if analysis.infinity is not None:
+        result += ((sp.oo, analysis.infinity.kind),)
+    return result
+
+
+# Backward-compatible aliases for helpers that were private in 0.1.0.
+_as_expression = as_ode_expression
+_function_class = function_class