funcprops 0.1.0__py3-none-any.whl

funcprops/real_analysis/oscillation.py

@@ -0,0 +1,151 @@
+from __future__ import annotations
+
+import contextlib
+from dataclasses import dataclass
+
+import sympy as sp
+from sympy import S
+
+from ..exceptions import SYMBOLIC_QUERY_ERRORS
+from ..results import Oscillation
+from ..stratification import evaluate_parameter_strata
+from ..transcendental.periodic import positive_period
+from .common import combine_natural_domain_condition, condition_to_set
+from .domain import function_domain
+from .monotonic_certificates import MonotonicPartition, monotonic_partition
+
+
+@dataclass(frozen=True)
+class OscillationCertificate:
+    classification: Oscillation
+    domain: sp.Set
+    partition: MonotonicPartition | None = None
+    turning_count: object = None
+    source: str = ""
+    evidence: tuple = ()
+
+
+def function_oscillation(
+    expr,
+    var,
+    *,
+    domain=True,
+    details=False,
+    partition=None,
+    _domain_ready=False,
+):
+    """Classify real oscillation from the shared monotonic partition.
+
+    ``OSCILLATORY`` means a certified infinite sequence of monotonicity
+    reversals (or a nonconstant exact periodic function on an unbounded
+    interval). ``FINITELY_OSCILLATORY`` means a complete finite partition with
+    at least one direction reversal.
+    """
+    expr = sp.sympify(expr)
+    var = sp.sympify(var)
+    natural = function_domain(expr, var)
+    cond = (
+        sp.sympify(domain)
+        if _domain_ready
+        else combine_natural_domain_condition(natural, domain, var)
+    )
+    with contextlib.suppress(SYMBOLIC_QUERY_ERRORS):
+        cond = sp.simplify(cond)
+    if not _domain_ready:
+        split = evaluate_parameter_strata(
+            cond,
+            var,
+            lambda branch_domain: function_oscillation(
+                expr,
+                var,
+                domain=branch_domain,
+                details=details,
+                partition=None,
+                _domain_ready=True,
+            ),
+            source="oscillation-parameter-stratification",
+        )
+        if split is not None:
+            return split
+    ds = condition_to_set(cond, var)
+    if not isinstance(ds, sp.Set):
+        out = OscillationCertificate(
+            Oscillation.UNKNOWN, S.Reals, None, None, "unknown-domain"
+        )
+        return out if details else out.classification
+    if not expr.has(var):
+        out = OscillationCertificate(
+            Oscillation.NONOSCILLATORY, ds, None, 0, "constant"
+        )
+        return out if details else out.classification
+    part = (
+        partition
+        if partition is not None and getattr(partition, "domain", None) == ds
+        else monotonic_partition(expr, var, domain=ds)
+    )
+    if part.indexed is not None and part.indexed.boundary_geometry:
+        try:
+            from ..transcendental.zero_geometry import geometry_support_inside_domain
+
+            infinite_inside = any(
+                g.count is sp.oo and geometry_support_inside_domain(g, ds)
+                for g in part.indexed.boundary_geometry
+            )
+        except SYMBOLIC_QUERY_ERRORS:
+            infinite_inside = False
+        if infinite_inside:
+            out = OscillationCertificate(
+                Oscillation.OSCILLATORY,
+                ds,
+                part,
+                sp.oo,
+                "indexed-monotonic-partition",
+                (part,),
+            )
+            return out if details else out.classification
+    if part.complete and part.cells:
+        turns = part.direction_changes
+        cls = Oscillation.FINITELY_OSCILLATORY if turns else Oscillation.NONOSCILLATORY
+        out = OscillationCertificate(
+            cls, ds, part, turns, "finite-monotonic-partition", (part,)
+        )
+        return out if details else out.classification
+    # A certified global monotonic classification is a cheap exact proof of
+    # nonoscillation when critical-point partitioning itself is incomplete.
+    try:
+        from ..results import Monotonicity
+        from .monotonicity import function_monotonicity
+
+        m = function_monotonicity(expr, var, domain=cond, partition=part)
+        if m in (
+            Monotonicity.STRICTLY_INCREASING,
+            Monotonicity.NONDECREASING,
+            Monotonicity.CONSTANT,
+            Monotonicity.NONINCREASING,
+            Monotonicity.STRICTLY_DECREASING,
+        ):
+            out = OscillationCertificate(
+                Oscillation.NONOSCILLATORY,
+                ds,
+                part,
+                0,
+                "global-monotonicity",
+                (m, part),
+            )
+            return out if details else out.classification
+    except SYMBOLIC_QUERY_ERRORS:
+        pass
+    p = positive_period(expr, var)
+    if (
+        p is not None
+        and isinstance(ds, sp.Interval)
+        and (ds.start is -sp.oo or ds.end is sp.oo)
+    ):
+        out = OscillationCertificate(
+            Oscillation.OSCILLATORY, ds, part, sp.oo, "exact-periodicity", (p, part)
+        )
+        return out if details else out.classification
+    out = OscillationCertificate(
+        Oscillation.UNKNOWN, ds, part, None, "incomplete-monotonic-partition", (part,)
+    )
+    return out if details else out.classification

funcprops/real_analysis/piecewise.py

@@ -0,0 +1,174 @@
+"""Shared branch-domain analysis for real piecewise expressions.
+
+Property engines use the same effective-branch construction so branch guards,
+user domains, and earlier Piecewise conditions are interpreted consistently.
+The module contains only cheap exact combination rules; properties that need
+interface derivatives or global image geometry remain responsible for those
+additional proofs.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from itertools import pairwise
+
+import sympy as sp
+from sympy import S
+
+from ..exceptions import SYMBOLIC_QUERY_ERRORS
+from ..results import Boundedness, Monotonicity, Sign
+from .common import condition_to_set
+
+
+@dataclass(frozen=True)
+class PiecewiseBranch:
+    """One expression branch together with its effective requested domain."""
+
+    expression: sp.Expr
+    condition: sp.Basic
+    domain: sp.Set | None
+
+
+def piecewise_branches(expr, var, domain=S.true):
+    """Return nonempty effective branches of a ``Piecewise`` expression."""
+    expr = sp.sympify(expr)
+    var = sp.sympify(var)
+    if not isinstance(expr, sp.Piecewise):
+        return ()
+    covered = S.false
+    branches = []
+    for value, condition in expr.args:
+        try:
+            effective = sp.simplify_logic(
+                sp.And(sp.sympify(domain), condition, sp.Not(covered))
+            )
+        except SYMBOLIC_QUERY_ERRORS:
+            effective = sp.And(sp.sympify(domain), condition, sp.Not(covered))
+        covered = sp.Or(covered, condition)
+        if effective is S.false:
+            continue
+        domain_set = condition_to_set(effective, var)
+        if domain_set is S.EmptySet:
+            continue
+        branches.append(PiecewiseBranch(sp.sympify(value), effective, domain_set))
+    return tuple(branches)
+
+
+def _scalar_value(result):
+    """Return an unconditional scalar result, or ``None`` for conditional data."""
+    from ..results import PropertyResult
+
+    if isinstance(result, PropertyResult):
+        if result.primary is not None:
+            return result.primary
+        return None
+    return result
+
+
+def combine_piecewise_sign(values):
+    """Combine exact branch sign classifications into a global sign class."""
+    vals = tuple(_scalar_value(v) for v in values)
+    if not vals or any(v is None or v is Sign.UNKNOWN for v in vals):
+        return Sign.UNKNOWN
+    if all(v is Sign.ZERO for v in vals):
+        return Sign.ZERO
+    if all(v is Sign.POSITIVE for v in vals):
+        return Sign.POSITIVE
+    if all(v is Sign.NEGATIVE for v in vals):
+        return Sign.NEGATIVE
+    nonneg = {Sign.POSITIVE, Sign.NONNEGATIVE, Sign.ZERO}
+    nonpos = {Sign.NEGATIVE, Sign.NONPOSITIVE, Sign.ZERO}
+    if all(v in nonneg for v in vals):
+        return Sign.NONNEGATIVE
+    if all(v in nonpos for v in vals):
+        return Sign.NONPOSITIVE
+    if any(v in {Sign.POSITIVE, Sign.NONNEGATIVE} for v in vals) and any(
+        v in {Sign.NEGATIVE, Sign.NONPOSITIVE} for v in vals
+    ):
+        return Sign.SIGN_CHANGING
+    return Sign.UNKNOWN
+
+
+def combine_piecewise_boundedness(values):
+    """Combine exact branch boundedness classes over a finite branch union."""
+    vals = tuple(_scalar_value(v) for v in values)
+    if not vals or any(v is None or v is Boundedness.UNKNOWN for v in vals):
+        return Boundedness.UNKNOWN
+    upper = {Boundedness.BOUNDED, Boundedness.BOUNDED_ABOVE}
+    lower = {Boundedness.BOUNDED, Boundedness.BOUNDED_BELOW}
+    above = all(v in upper for v in vals)
+    below = all(v in lower for v in vals)
+    if above and below:
+        return Boundedness.BOUNDED
+    if above:
+        return Boundedness.BOUNDED_ABOVE
+    if below:
+        return Boundedness.BOUNDED_BELOW
+    return Boundedness.UNBOUNDED
+
+
+def combine_piecewise_monotonicity(values):
+    """Combine branch directions before interface ordering is checked.
+
+    A non-``UNKNOWN`` answer here means only that every branch has a compatible
+    direction.  The caller must still prove that values do not jump in the
+    opposite direction at branch interfaces.
+    """
+    vals = tuple(_scalar_value(v) for v in values)
+    if not vals or any(v is None for v in vals):
+        return Monotonicity.UNKNOWN
+    inc = {Monotonicity.STRICTLY_INCREASING, Monotonicity.NONDECREASING}
+    dec = {Monotonicity.STRICTLY_DECREASING, Monotonicity.NONINCREASING}
+    if all(v is Monotonicity.CONSTANT for v in vals):
+        return Monotonicity.CONSTANT
+    if all(v in inc | {Monotonicity.CONSTANT} for v in vals):
+        return Monotonicity.NONDECREASING
+    if all(v in dec | {Monotonicity.CONSTANT} for v in vals):
+        return Monotonicity.NONINCREASING
+    if any(v in inc for v in vals) and any(v in dec for v in vals):
+        return Monotonicity.NOT_MONOTONE
+    return Monotonicity.UNKNOWN
+
+
+def piecewise_interface_limits(branches, var, *, derivative_order=0):
+    """Return exact one-sided values at contiguous branch interfaces.
+
+    ``None`` is returned when branch domains are not ordered intervals, are not
+    contiguous, or an endpoint limit cannot be computed exactly.
+    """
+    if not branches or any(not isinstance(b.domain, sp.Interval) for b in branches):
+        return None
+    ordered = tuple(sorted(branches, key=lambda b: sp.default_sort_key(b.domain.start)))
+    from ..proof_cache import cached_derivative, cached_endpoint_limit
+
+    out = []
+    for left, right in pairwise(ordered):
+        boundary = left.domain.end
+        if sp.simplify(boundary - right.domain.start) != 0:
+            return None
+        left_expr = left.expression
+        right_expr = right.expression
+        if derivative_order:
+            try:
+                left_expr = cached_derivative(left_expr, var, order=derivative_order)
+                right_expr = cached_derivative(right_expr, var, order=derivative_order)
+            except SYMBOLIC_QUERY_ERRORS:
+                return None
+        left_value = cached_endpoint_limit(
+            left_expr,
+            var,
+            boundary,
+            direction="-",
+            attained=not left.domain.right_open,
+        )
+        right_value = cached_endpoint_limit(
+            right_expr,
+            var,
+            boundary,
+            direction="+",
+            attained=not right.domain.left_open,
+        )
+        if left_value is None or right_value is None:
+            return None
+        out.append((boundary, left_value, right_value))
+    return tuple(out)