funcprops 0.1.0__py3-none-any.whl

funcprops/real_analysis/boundedness.py

@@ -0,0 +1,168 @@
+from __future__ import annotations
+
+import sympy as sp
+from sympy import S
+
+from ..exceptions import SYMBOLIC_QUERY_ERRORS
+from ..results import Boundedness, ConditionalValue, PropertyResult
+from ..stratification import normalize_cases
+from .common import combine_natural_domain_condition, condition_to_set
+from .domain import function_domain
+from .piecewise import (
+    combine_piecewise_boundedness,
+    piecewise_branches,
+)
+from .range import function_range
+
+
+def _boundedness_from_range_condition(cond, y):
+    """Infer two-sided boundedness from an exact range representation.
+
+    Indexed extremum ranges already carry exact endpoint objects, so boundedness
+    depends only on whether either endpoint is infinite; no envelope reduction
+    is required here.
+    """
+    try:
+        from ..transcendental.extrema import ExtremumRange
+
+        if isinstance(cond, ExtremumRange):
+            if not cond.complete:
+                return Boundedness.UNKNOWN
+            lo, hi = cond.lower, cond.upper
+            below = lo is not S.NegativeInfinity and lo != S.NegativeInfinity
+            above = hi is not S.Infinity and hi != S.Infinity
+            if below and above:
+                return Boundedness.BOUNDED
+            if below:
+                return Boundedness.BOUNDED_BELOW
+            if above:
+                return Boundedness.BOUNDED_ABOVE
+            return Boundedness.UNBOUNDED
+    except SYMBOLIC_QUERY_ERRORS:
+        pass
+    # Parameter-dependent endpoints often cannot be converted by SymPy's
+    # ``as_set`` (e.g. 0 < y < gamma(a)).  Infer one-/two-sided boundedness
+    # directly from exact relational structure before falling back to Sets.
+    c = sp.sympify(cond)
+    rels = c.args if isinstance(c, sp.And) else (c,)
+    lower = False
+    upper = False
+    for r in rels:
+        if not isinstance(r, sp.core.relational.Relational):
+            continue
+        try:
+            if r.lhs == y and not r.rhs.has(y):
+                if isinstance(r, (sp.StrictGreaterThan, sp.GreaterThan)):
+                    lower = True
+                elif isinstance(r, (sp.StrictLessThan, sp.LessThan)):
+                    upper = True
+            elif r.rhs == y and not r.lhs.has(y):
+                if isinstance(r, (sp.StrictLessThan, sp.LessThan)):
+                    lower = True
+                elif isinstance(r, (sp.StrictGreaterThan, sp.GreaterThan)):
+                    upper = True
+        except SYMBOLIC_QUERY_ERRORS:
+            pass
+    if lower and upper:
+        return Boundedness.BOUNDED
+    if lower:
+        return Boundedness.BOUNDED_BELOW
+    if upper:
+        return Boundedness.BOUNDED_ABOVE
+    s = condition_to_set(cond, y)
+    if s is None:
+        return Boundedness.UNKNOWN
+    if s is S.EmptySet:
+        # The empty-domain convention is vacuously bounded in both directions.
+        return Boundedness.BOUNDED
+    try:
+        lo = s.inf
+        hi = s.sup
+    except SYMBOLIC_QUERY_ERRORS:
+        return Boundedness.UNKNOWN
+    below = lo != S.NegativeInfinity
+    above = hi != S.Infinity
+    if below and above:
+        return Boundedness.BOUNDED
+    if below:
+        return Boundedness.BOUNDED_BELOW
+    if above:
+        return Boundedness.BOUNDED_ABOVE
+    return Boundedness.UNBOUNDED
+
+
+def _structural_boundedness(expr, var, domain):
+    """Apply cheap closure rules before invoking a full range computation."""
+    if not expr.has(var):
+        return Boundedness.BOUNDED
+    if expr.func in (sp.sin, sp.cos, sp.tanh, sp.atan):
+        return Boundedness.BOUNDED
+    if isinstance(expr, sp.Piecewise):
+        branches = piecewise_branches(expr, var, domain)
+        if branches:
+            values = [
+                function_boundedness(branch.expression, var, domain=branch.condition)
+                for branch in branches
+            ]
+            return combine_piecewise_boundedness(values)
+    if expr.func is sp.Abs:
+        inner = function_boundedness(expr.args[0], var, domain=domain)
+        if inner is Boundedness.BOUNDED:
+            return Boundedness.BOUNDED
+        return Boundedness.BOUNDED_BELOW
+    if expr.func is sp.exp:
+        inner = function_boundedness(expr.args[0], var, domain=domain)
+        if inner in (Boundedness.BOUNDED, Boundedness.BOUNDED_ABOVE):
+            return Boundedness.BOUNDED
+        return Boundedness.BOUNDED_BELOW
+    if expr.is_Add:
+        values = [function_boundedness(a, var, domain=domain) for a in expr.args]
+        if not any(isinstance(v, PropertyResult) for v in values):
+            upper = {Boundedness.BOUNDED, Boundedness.BOUNDED_ABOVE}
+            lower = {Boundedness.BOUNDED, Boundedness.BOUNDED_BELOW}
+            above = all(v in upper for v in values)
+            below = all(v in lower for v in values)
+            if above and below:
+                return Boundedness.BOUNDED
+            if above:
+                return Boundedness.BOUNDED_ABOVE
+            if below:
+                return Boundedness.BOUNDED_BELOW
+    if expr.is_Mul:
+        values = [function_boundedness(a, var, domain=domain) for a in expr.args]
+        if values and all(v is Boundedness.BOUNDED for v in values):
+            return Boundedness.BOUNDED
+    return Boundedness.UNKNOWN
+
+
+def function_boundedness(expr, var, *, domain=True):
+    expr = sp.sympify(expr)
+    var = sp.sympify(var)
+    y = sp.Dummy("_y", real=True)
+    structural = _structural_boundedness(expr, var, domain)
+    if structural is not Boundedness.UNKNOWN:
+        return structural
+    natural = function_domain(expr, var)
+    # function_range owns natural-domain intersection.  Passing an already
+    # combined mixed parameter/domain formula can obscure a simple user domain
+    # (e.g. x>=0) and prevent endpoint-aware special-function rules from firing.
+    constraints = combine_natural_domain_condition(natural, domain, var)
+    try:
+        cond = function_range(expr, var, y, constraints=constraints)
+    except SYMBOLIC_QUERY_ERRORS:
+        return Boundedness.UNKNOWN
+    if isinstance(cond, PropertyResult):
+        out = normalize_cases(
+            (
+                ConditionalValue(
+                    _boundedness_from_range_condition(c.value, y), c.condition
+                )
+                for c in cond.cases
+            ),
+            primary=_boundedness_from_range_condition(cond.primary, y)
+            if cond.primary is not None
+            else None,
+            source="range-boundedness-stratification",
+        )
+        return out if out.cases else Boundedness.UNKNOWN
+    return _boundedness_from_range_condition(cond, y)

funcprops/real_analysis/common.py

@@ -0,0 +1,244 @@
+from __future__ import annotations
+
+import sympy as sp
+from sympy import S
+
+from ..exceptions import SYMBOLIC_QUERY_ERRORS
+
+
+def is_semialgebraic_expression(expr: sp.Expr, var: sp.Symbol) -> bool:
+    """Conservative structural test for the subset handled by semialg.
+
+    Algebraic powers with rational exponent, Abs/Min/Max/Piecewise and ordinary
+    polynomial/rational arithmetic are accepted. Unknown Function heads are not.
+    """
+    expr = sp.sympify(expr)
+    if not expr.has(var):
+        return True
+    if expr.is_Atom:
+        return expr == var or expr.is_number or expr.is_Symbol
+    if expr.func in (sp.Add, sp.Mul):
+        return all(is_semialgebraic_expression(a, var) for a in expr.args)
+    if expr.func is sp.Pow:
+        b, e = expr.args
+        return bool(e.is_Rational) and is_semialgebraic_expression(b, var)
+    if expr.func in (sp.Abs, sp.Min, sp.Max):
+        return all(is_semialgebraic_expression(a, var) for a in expr.args)
+    if isinstance(expr, sp.Piecewise):
+        return all(
+            is_semialgebraic_expression(v, var) and is_semialgebraic_condition(c, var)
+            for v, c in expr.args
+        )
+    return False
+
+
+def is_semialgebraic_condition(cond, var):
+    cond = sp.sympify(cond)
+    if cond in (S.true, S.false):
+        return True
+    if isinstance(cond, (sp.And, sp.Or)):
+        return all(is_semialgebraic_condition(a, var) for a in cond.args)
+    if isinstance(cond, sp.Not):
+        return is_semialgebraic_condition(cond.args[0], var)
+    if isinstance(cond, sp.core.relational.Relational):
+        return is_semialgebraic_expression(
+            cond.lhs, var
+        ) and is_semialgebraic_expression(cond.rhs, var)
+    return False
+
+
+def combine_domain(user_domain, natural_domain):
+    if user_domain is None or user_domain is True or user_domain is S.true:
+        return sp.sympify(natural_domain)
+    if isinstance(user_domain, sp.Set):
+        return sp.And(sp.Contains(sp.Symbol("_fp_dummy"), user_domain), natural_domain)
+    return sp.simplify(sp.And(sp.sympify(user_domain), sp.sympify(natural_domain)))
+
+
+def condition_to_set(condition, var):
+    """Convert ordinary univariate Boolean conditions to a SymPy Set.
+
+    SymPy's ``Relational.as_set()`` can refuse parameterized endpoints such as
+    ``x >= A`` even though the set is exactly ``[A, oo)`` with respect to x.
+    Handle those one-variable affine endpoint relations structurally first.
+    """
+    condition = sp.sympify(condition)
+    var = sp.sympify(var)
+    if condition is S.true:
+        return S.Reals
+    if condition is S.false:
+        return S.EmptySet
+    if (
+        isinstance(condition, sp.Contains)
+        and condition.args[0] == var
+        and isinstance(condition.args[1], sp.Set)
+    ):
+        return condition.args[1]
+    if isinstance(condition, sp.And):
+        pieces = [condition_to_set(a, var) for a in condition.args]
+        if all(isinstance(q, sp.Set) for q in pieces):
+            return sp.Intersection(*pieces)
+    if isinstance(condition, sp.Or):
+        pieces = [condition_to_set(a, var) for a in condition.args]
+        if all(isinstance(q, sp.Set) for q in pieces):
+            return sp.Union(*pieces)
+    if isinstance(condition, sp.core.relational.Relational):
+        lhs, rhs = condition.lhs, condition.rhs
+        if lhs == var and not rhs.has(var):
+            if isinstance(condition, sp.GreaterThan):
+                return sp.Interval(rhs, sp.oo)
+            if isinstance(condition, sp.StrictGreaterThan):
+                return sp.Interval.open(rhs, sp.oo)
+            if isinstance(condition, sp.LessThan):
+                return sp.Interval(-sp.oo, rhs)
+            if isinstance(condition, sp.StrictLessThan):
+                return sp.Interval.open(-sp.oo, rhs)
+            if isinstance(condition, sp.Equality):
+                return sp.FiniteSet(rhs)
+        if rhs == var and not lhs.has(var):
+            if isinstance(condition, sp.GreaterThan):
+                return sp.Interval(-sp.oo, lhs)
+            if isinstance(condition, sp.StrictGreaterThan):
+                return sp.Interval.open(-sp.oo, lhs)
+            if isinstance(condition, sp.LessThan):
+                return sp.Interval(lhs, sp.oo)
+            if isinstance(condition, sp.StrictLessThan):
+                return sp.Interval.open(lhs, sp.oo)
+            if isinstance(condition, sp.Equality):
+                return sp.FiniteSet(lhs)
+    try:
+        if isinstance(
+            condition, (sp.logic.boolalg.Boolean, sp.core.relational.Relational)
+        ):
+            return condition.as_set()
+    except (AttributeError, *SYMBOLIC_QUERY_ERRORS):
+        # Semantic catalogue predicates are BooleanFunction subclasses without
+        # SymPy's optional _eval_as_set implementation.
+        pass
+    return None
+
+
+def set_to_condition(set_, y):
+    """Convert a real Set to a Boolean membership condition in ``y``."""
+    if set_ == S.Reals:
+        return S.true
+    if set_ == S.EmptySet:
+        return S.false
+    if isinstance(set_, sp.Interval):
+        pieces = []
+        if set_.start is not S.NegativeInfinity:
+            pieces.append(y > set_.start if set_.left_open else y >= set_.start)
+        if set_.end is not S.Infinity:
+            pieces.append(y < set_.end if set_.right_open else y <= set_.end)
+        return sp.And(*pieces) if pieces else S.true
+    if isinstance(set_, sp.FiniteSet):
+        return sp.Or(*(sp.Eq(y, v) for v in set_)) if set_ else S.false
+    if isinstance(set_, sp.Union):
+        return sp.Or(*(set_to_condition(a, y) for a in set_.args))
+    if isinstance(set_, sp.Complement):
+        a, b = set_.args
+        return sp.And(set_to_condition(a, y), sp.Not(set_to_condition(b, y)))
+    return sp.Contains(y, set_)
+
+
+def interval_components(condition, var):
+    s = condition_to_set(condition, var)
+    if s is None:
+        return None
+    if isinstance(s, sp.Interval):
+        return (s,)
+    if isinstance(s, sp.Union) and all(isinstance(a, sp.Interval) for a in s.args):
+        return tuple(s.args)
+    if s == S.Reals:
+        return (sp.Interval(-sp.oo, sp.oo),)
+    return None
+
+
+def is_full_natural_domain(requested_domain, natural_domain):
+    if (
+        requested_domain is True
+        or requested_domain is S.true
+        or requested_domain is None
+    ):
+        return True
+    try:
+        # Custom catalogue Boolean predicates must be lowered before generic
+        # SymPy Boolean simplification; otherwise unknown predicate heads can
+        # be simplified unsafely or merely syntactically.
+        from ..stratification import semantic_condition
+
+        req = semantic_condition(requested_domain)
+        nat = semantic_condition(natural_domain)
+        eq = sp.simplify(sp.simplify_logic(sp.Equivalent(req, nat)))
+        return eq is S.true
+    except SYMBOLIC_QUERY_ERRORS:
+        return False
+
+
+def exact_order_real_points(points):
+    """Order exact real points only when every comparison is certified.
+
+    Returns ``None`` rather than using structural or floating-point ordering
+    when a pair cannot be compared exactly.  This helper is shared by sign,
+    monotonic-partition, extrema, and inverse reasoning.
+    """
+    out = []
+    for q in points:
+        q = sp.sympify(q)
+        placed = False
+        for i, r in enumerate(out):
+            d = sp.simplify(q - r)
+            if d.is_negative is True:
+                out.insert(i, q)
+                placed = True
+                break
+            if d.is_positive is True:
+                continue
+            if d.is_zero is True:
+                placed = True
+                break
+            return None
+        if not placed:
+            out.append(q)
+    return tuple(out)
+
+
+def combine_natural_domain_condition(natural_domain, user_domain, var):
+    """Combine a natural-domain result with a requested real domain safely.
+
+    A ``PropertyResult`` means the natural domain was not established as one
+    Boolean condition.  In that case preserve the explicit user restriction,
+    or use all reals when no restriction was supplied; never pass the result
+    object itself into SymPy Boolean simplification.
+    """
+    var = sp.sympify(var)
+    nat = None if hasattr(natural_domain, "primary") else sp.sympify(natural_domain)
+    if user_domain is True or user_domain is None or user_domain is S.true:
+        return S.true if nat is None else nat
+    if isinstance(user_domain, sp.Set):
+        usr = sp.Contains(var, user_domain)
+    else:
+        usr = sp.sympify(user_domain)
+    if nat is None:
+        return usr
+    try:
+        return sp.simplify(sp.And(nat, usr))
+    except SYMBOLIC_QUERY_ERRORS:
+        return sp.And(nat, usr)
+
+
+def normalize_variables(var):
+    """Return a canonical tuple of symbolic variables.
+
+    Public APIs that accept either one variable or a variable collection must
+    not sympify a tuple and then test ``expr.has(tuple)``: SymPy treats the
+    resulting Tuple as one atomic expression. This helper centralizes the
+    scalar/collection distinction without changing scalar call sites.
+    """
+    if isinstance(var, (tuple, list, sp.Tuple)):
+        vv = tuple(sp.sympify(v) for v in var)
+    else:
+        vv = (sp.sympify(var),)
+    if not vv:
+        raise ValueError("at least one variable is required")
+    return vv