funcprops 0.1.0__py3-none-any.whl

funcprops/proof_cache.py

@@ -0,0 +1,373 @@
+"""Lazy shared cache for reusable exact property proofs.
+
+`PropertyProofContext` is the single internal entry point for proof primitives.
+Every slot remains lazy: constructing a context does no mathematical work.
+Recursive algorithms still call their uncached implementations where doing so
+avoids cache-key overhead on transient subexpressions.
+"""
+
+from __future__ import annotations
+
+import operator
+from dataclasses import dataclass
+from functools import lru_cache
+
+import sympy as sp
+from sympy import S
+from sympy.core.function import PoleError
+from sympy.core.sympify import SympifyError
+
+
+def _basic(value):
+    if value is True or value is None:
+        return S.true
+    if value is False:
+        return S.false
+    if isinstance(value, sp.Set):
+        return value
+    try:
+        return sp.sympify(value)
+    except (SympifyError, TypeError):
+        return value
+
+
+def _normalize_relation(rel):
+    """Cheap deterministic relation normalization for cache keys only."""
+    if not isinstance(rel, sp.core.relational.Relational):
+        return rel
+    lhs, rhs = rel.lhs, rel.rhs
+    # Prefer a symbol/expression containing symbols on the left and zero or a
+    # simpler constant on the right.  Do not call simplify/QE here.
+    if not lhs.free_symbols and rhs.free_symbols:
+        return rel.reversed
+    return rel
+
+
+def normalize_assumptions(value):
+    """Canonicalize Boolean syntax without expensive logical reasoning."""
+    value = _basic(value)
+    if value in (S.true, S.false) or isinstance(value, sp.Set):
+        return value
+    if isinstance(value, (sp.And, sp.Or)):
+        head = value.func
+        flat = []
+        for arg in value.args:
+            q = normalize_assumptions(arg)
+            if isinstance(q, head):
+                flat.extend(q.args)
+            else:
+                flat.append(q)
+        ident = S.true if head is sp.And else S.false
+        annih = S.false if head is sp.And else S.true
+        if annih in flat:
+            return annih
+        flat = [q for q in flat if q != ident]
+        unique = {q: q for q in flat}
+        ordered = tuple(sorted(unique.values(), key=sp.default_sort_key))
+        if not ordered:
+            return ident
+        return head(*ordered, evaluate=False)
+    if isinstance(value, sp.Not):
+        q = normalize_assumptions(value.args[0])
+        return sp.Not(q, evaluate=False)
+    return _normalize_relation(value)
+
+
+def normalize_domain(value):
+    if isinstance(value, sp.Set):
+        return value
+    return normalize_assumptions(value)
+
+
+@dataclass(frozen=True)
+class PropertyProofKey:
+    expression: sp.Basic
+    variable: sp.Basic
+    domain: object = S.true
+    assumptions: sp.Basic = S.true
+
+
+def proof_key(expr, var, *, domain=S.true, assumptions=S.true):
+    return PropertyProofKey(
+        sp.sympify(expr),
+        sp.sympify(var),
+        normalize_domain(domain),
+        normalize_assumptions(assumptions),
+    )
+
+
+@lru_cache(maxsize=2048)
+def _derivative_cached(expr, var, order):
+    return sp.diff(expr, var, order)
+
+
+@lru_cache(maxsize=1024)
+def _factored_derivative_cached(expr, var, order):
+    return sp.factor(_derivative_cached(expr, var, order))
+
+
+def _derivative_order(order):
+    """Return a concrete nonnegative derivative order without truncation."""
+    if isinstance(order, bool):
+        raise ValueError("order must be a nonnegative integer")
+    try:
+        value = operator.index(order)
+    except TypeError as exc:
+        raise ValueError("order must be a nonnegative integer") from exc
+    if value < 0:
+        raise ValueError("order must be a nonnegative integer")
+    return value
+
+
+def _uncached_after_key_error(cache_fn, args):
+    """Retry an LRU-backed call only when its arguments are unhashable."""
+    try:
+        hash(args)
+    except TypeError:
+        return cache_fn.__wrapped__(*args)
+    raise
+
+
+def cached_derivative(expr, var, *, order=1, factored=False):
+    expr = sp.sympify(expr)
+    var = sp.sympify(var)
+    order = _derivative_order(order)
+    fn = _factored_derivative_cached if factored else _derivative_cached
+    args = (expr, var, order)
+    try:
+        return fn(*args)
+    except TypeError:
+        return _uncached_after_key_error(fn, args)
+
+
+@lru_cache(maxsize=1024)
+def _domain_cached(expr, var, domain_kind, stratified):
+    from .real_analysis.domain import _function_domain_impl
+
+    dom = S.Reals if domain_kind == "real" else S.Complexes
+    return _function_domain_impl(expr, var, domain=dom, stratified=stratified)
+
+
+def cached_domain(expr, var, *, domain=S.Reals, stratified=False):
+    if domain in (S.Reals, "real", "reals", "R", "RR"):
+        kind = "real"
+    elif domain in (S.Complexes, "complex", "complexes", "C", "CC"):
+        kind = "complex"
+    else:
+        raise ValueError("domain must be Reals or Complexes")
+    return _domain_cached(sp.sympify(expr), sp.sympify(var), kind, bool(stratified))
+
+
+@lru_cache(maxsize=1024)
+def _sign_cached(expr, var, domain, strict_inequalities):
+    from .real_analysis.sign import _function_sign_public_impl
+
+    return _function_sign_public_impl(
+        expr, var, domain=domain, strict_inequalities=strict_inequalities
+    )
+
+
+def cached_sign(expr, var, *, domain=S.true, strict_inequalities=True):
+    key = proof_key(expr, var, domain=domain)
+    args = (key.expression, key.variable, key.domain, bool(strict_inequalities))
+    try:
+        return _sign_cached(*args)
+    except TypeError:
+        try:
+            hash(args)
+        except TypeError:
+            from .real_analysis.sign import _function_sign_public_impl
+
+            return _function_sign_public_impl(
+                key.expression,
+                key.variable,
+                domain=key.domain,
+                strict_inequalities=strict_inequalities,
+            )
+        raise
+
+
+@lru_cache(maxsize=1024)
+def _endpoint_limit_cached(expr, var, point, direction, attained):
+    try:
+        if point is S.NegativeInfinity:
+            return sp.limit(expr, var, -sp.oo)
+        if point is S.Infinity:
+            return sp.limit(expr, var, sp.oo)
+        if attained:
+            return sp.simplify(expr.subs(var, point))
+        return sp.limit(expr, var, point, dir=direction)
+    except (PoleError, TypeError, ValueError, NotImplementedError):
+        return None
+
+
+def cached_endpoint_limit(expr, var, point, *, direction="+", attained=False):
+    expression = sp.sympify(expr)
+    variable = sp.sympify(var)
+    point = _basic(point)
+    args = (expression, variable, point, str(direction), bool(attained))
+    try:
+        return _endpoint_limit_cached(*args)
+    except TypeError:
+        return _uncached_after_key_error(_endpoint_limit_cached, args)
+
+
+@lru_cache(maxsize=1024)
+def _zero_geometry_cached(expr, var, derivative_order, domain):
+    from .transcendental.zero_geometry import _zero_geometry_impl
+
+    return _zero_geometry_impl(
+        expr, var, derivative_order=derivative_order, domain=domain
+    )
+
+
+def cached_zero_geometry(
+    expr, var, *, derivative_order=0, domain=S.Reals, assumptions=S.true
+):
+    key = proof_key(expr, var, domain=domain, assumptions=assumptions)
+    order = _derivative_order(derivative_order)
+    args = (key.expression, key.variable, order, key.domain)
+    try:
+        return _zero_geometry_cached(*args)
+    except TypeError:
+        return _uncached_after_key_error(_zero_geometry_cached, args)
+
+
+@lru_cache(maxsize=512)
+def _singularity_cached(expr, var, domain, assumptions, ignore_unknown):
+    from .singularities import _function_singularity_analysis_impl
+
+    return _function_singularity_analysis_impl(
+        expr, var, domain=domain, assumptions=assumptions, ignore_unknown=ignore_unknown
+    )
+
+
+def cached_singularity_analysis(
+    expr, var, *, domain=S.Complexes, assumptions=S.true, ignore_unknown=False
+):
+    key = proof_key(expr, var, domain=domain, assumptions=assumptions)
+    args = (
+        key.expression,
+        key.variable,
+        key.domain,
+        key.assumptions,
+        bool(ignore_unknown),
+    )
+    try:
+        return _singularity_cached(*args)
+    except TypeError:
+        return _uncached_after_key_error(_singularity_cached, args)
+
+
+@lru_cache(maxsize=1024)
+def _proof_context_cached(expr, var, domain, assumptions):
+    return PropertyProofContext(expr, var, domain, assumptions)
+
+
+@dataclass(frozen=True)
+class PropertyProofContext:
+    """Lazy normalized proof context shared by all global property APIs."""
+
+    expression: sp.Basic
+    variable: sp.Basic
+    domain: object = S.true
+    assumptions: sp.Basic = S.true
+
+    def derivative(self, order=1, *, factored=False):
+        return cached_derivative(
+            self.expression, self.variable, order=order, factored=factored
+        )
+
+    def natural_domain(self, *, complex_domain=False, stratified=False):
+        """Return the cached natural real or complex domain."""
+        target = S.Complexes if complex_domain else S.Reals
+        return cached_domain(
+            self.expression,
+            self.variable,
+            domain=target,
+            stratified=stratified,
+        )
+
+    def sign(self, *, domain=None, strict_inequalities=True):
+        return cached_sign(
+            self.expression,
+            self.variable,
+            domain=self.domain if domain is None else domain,
+            strict_inequalities=strict_inequalities,
+        )
+
+    def endpoint_limit(self, point, *, direction="+", attained=False):
+        return cached_endpoint_limit(
+            self.expression,
+            self.variable,
+            point,
+            direction=direction,
+            attained=attained,
+        )
+
+    def zero_geometry(self, *, derivative_order=0, domain=None):
+        return cached_zero_geometry(
+            self.expression,
+            self.variable,
+            derivative_order=derivative_order,
+            domain=self.domain if domain is None else domain,
+            assumptions=self.assumptions,
+        )
+
+    def singularities(self, *, domain=S.Complexes, ignore_unknown=False):
+        return cached_singularity_analysis(
+            self.expression,
+            self.variable,
+            domain=domain,
+            assumptions=self.assumptions,
+            ignore_unknown=ignore_unknown,
+        )
+
+    def monotonic_partition(self, *, domain=None):
+        from .real_analysis.monotonic_certificates import monotonic_partition
+
+        return monotonic_partition(
+            self.expression,
+            self.variable,
+            domain=self.domain if domain is None else domain,
+        )
+
+
+def property_proof_context(expr, var, *, domain=S.true, assumptions=S.true):
+    key = proof_key(expr, var, domain=domain, assumptions=assumptions)
+    args = (key.expression, key.variable, key.domain, key.assumptions)
+    try:
+        return _proof_context_cached(*args)
+    except TypeError:
+        try:
+            hash(args)
+        except TypeError:
+            return PropertyProofContext(*args)
+        raise
+
+
+def clear_property_proof_cache():
+    _derivative_cached.cache_clear()
+    _factored_derivative_cached.cache_clear()
+    _domain_cached.cache_clear()
+    _sign_cached.cache_clear()
+    _endpoint_limit_cached.cache_clear()
+    _zero_geometry_cached.cache_clear()
+    _singularity_cached.cache_clear()
+    _proof_context_cached.cache_clear()
+    from .real_analysis.monotonic_certificates import _monotonic_partition_on_set
+
+    _monotonic_partition_on_set.cache_clear()
+
+
+def property_proof_cache_info():
+    return {
+        "derivative": _derivative_cached.cache_info(),
+        "factored_derivative": _factored_derivative_cached.cache_info(),
+        "domain": _domain_cached.cache_info(),
+        "sign": _sign_cached.cache_info(),
+        "endpoint_limit": _endpoint_limit_cached.cache_info(),
+        "zero_geometry": _zero_geometry_cached.cache_info(),
+        "singularity": _singularity_cached.cache_info(),
+        "context": _proof_context_cached.cache_info(),
+    }

funcprops/real_analysis/__init__.py

@@ -0,0 +1,52 @@
+from .convexity import function_convexity
+from .domain import function_domain
+from .monotonicity import function_monotonicity
+from .range import function_range
+from .sign import function_sign
+
+__all__ = [
+    "InverseSolutionCertificate",
+    "OscillationCertificate",
+    "PartitionRange",
+    "SmoothnessResult",
+    "certified_monotonic_inverse",
+    "clear_monotonic_partition_cache",
+    "function_bijective",
+    "function_boundedness",
+    "function_convexity",
+    "function_domain",
+    "function_injective",
+    "function_monotonicity",
+    "function_oscillation",
+    "function_range",
+    "function_sign",
+    "function_smoothness",
+    "function_surjective",
+    "function_zeros",
+    "injectivity_from_monotonic_partition",
+    "range_from_monotonic_partition",
+    "solve_monotonic_inverse",
+]
+
+from .boundedness import function_boundedness
+from .mapping import function_bijective, function_injective, function_surjective
+from .monotonic_certificates import (
+    IndexedMonotonicPartition,
+    InverseSolutionCertificate,
+    MonotonicDecomposition,
+    MonotonicInterval,
+    MonotonicPartition,
+    NonMonotonicityWitness,
+    PartitionRange,
+    certified_monotonic_inverse,
+    clear_monotonic_partition_cache,
+    injectivity_from_monotonic_partition,
+    monotonic_decomposition,
+    monotonic_partition,
+    quick_nonmonotonicity_witness,
+    range_from_monotonic_partition,
+    solve_monotonic_inverse,
+)
+from .oscillation import OscillationCertificate, function_oscillation
+from .smoothness import SmoothnessResult, function_smoothness
+from .zeros import function_zeros

funcprops/real_analysis/advanced_convexity.py

@@ -0,0 +1,217 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import sympy as sp
+from sympy import S
+
+from ..exceptions import SYMBOLIC_QUERY_ERRORS
+from ..results import ConditionalValue, Convexity, Monotonicity, Sign
+from ..stratification import implication_guard, normalize_cases
+from .common import condition_to_set
+from .monotonicity import function_monotonicity
+from .sign import function_sign
+
+
+@dataclass(frozen=True)
+class ConvexityCertificate:
+    """Replayable evidence for one ordinary convexity classification."""
+
+    classification: Convexity
+    domain: object
+    method: str
+    modulus: sp.Expr | None = None
+    proof: tuple = ()
+
+
+def parameterized_power_convexity(expr, var, domain):
+    """Exact parameter strata for x**a on a positive real domain."""
+    if expr.func is not sp.Pow or expr.base != var:
+        return None
+    a = expr.exp
+    if not (a.free_symbols - {var}) and a.is_number:
+        return None
+    ds = condition_to_set(domain, var)
+    # This stratification is valid only where x>0.
+    positive_domain = False
+    if isinstance(ds, sp.Interval):
+        positive_domain = (ds.start.is_nonnegative is True and ds.start != 0) or (
+            ds.start == 0 and ds.left_open
+        )
+    if not positive_domain:
+        # Rich parameter domains can contain Contains/NotContains predicates,
+        # which SymPy's LRA-backed ask() does not accept.  Use the package's
+        # three-valued implication reducer instead of passing arbitrary domain
+        # formulae into ask().
+        positive_domain = implication_guard(domain, var > 0, var) is S.true
+    if not positive_domain and domain != (var > 0):
+        return None
+    cases = (
+        ConditionalValue(Convexity.STRICTLY_CONVEX, sp.Or(a < 0, a > 1)),
+        ConditionalValue(Convexity.STRICTLY_CONCAVE, sp.And(a > 0, a < 1)),
+        ConditionalValue(Convexity.AFFINE, sp.Or(sp.Eq(a, 0), sp.Eq(a, 1))),
+    )
+    return normalize_cases(cases, source="power-parameter-stratification")
+
+
+def parameterized_exp_convexity(expr, var):
+    if expr.func is not sp.exp:
+        return None
+    g = sp.expand(expr.args[0])
+    try:
+        p = sp.Poly(g, var)
+    except SYMBOLIC_QUERY_ERRORS:
+        return None
+    if p.degree() != 1:
+        return None
+    a = p.coeff_monomial(var)
+    if not a.free_symbols:
+        return None
+    return normalize_cases(
+        (
+            ConditionalValue(Convexity.STRICTLY_CONVEX, sp.Ne(a, 0)),
+            ConditionalValue(Convexity.AFFINE, sp.Eq(a, 0)),
+        ),
+        source="exp-affine-parameter-stratification",
+    )
+
+
+def strong_convexity(expr, var, domain):
+    """Prove strong convexity/concavity by an exact second-derivative bound."""
+    try:
+        from ..proof_cache import cached_derivative
+
+        d2 = sp.simplify(cached_derivative(expr, var, order=2))
+    except SYMBOLIC_QUERY_ERRORS:
+        return None
+    if d2 == 0:
+        return None
+    ds = domain if isinstance(domain, sp.Set) else condition_to_set(domain, var)
+    if not isinstance(ds, sp.Interval):
+        return None
+    # Constant Hessian is the clean exact case.
+    if not d2.has(var):
+        if d2.is_positive is True:
+            return Convexity.STRONGLY_CONVEX, ConvexityCertificate(
+                Convexity.STRONGLY_CONVEX, ds, "second-derivative-bound", d2, (d2,)
+            )
+        if d2.is_negative is True:
+            return Convexity.STRONGLY_CONCAVE, ConvexityCertificate(
+                Convexity.STRONGLY_CONCAVE, ds, "second-derivative-bound", -d2, (d2,)
+            )
+    # Exact infimum/supremum on an interval. Avoid numerical optimization.
+    try:
+        from sympy.calculus.util import maximum, minimum
+
+        lo = minimum(d2, var, ds)
+        if lo is not None and lo is not -sp.oo and sp.ask(sp.Q.positive(lo)) is True:
+            return Convexity.STRONGLY_CONVEX, ConvexityCertificate(
+                Convexity.STRONGLY_CONVEX,
+                ds,
+                "second-derivative-bound",
+                sp.simplify(lo),
+                (d2, lo),
+            )
+        hi = maximum(d2, var, ds)
+        if hi is not None and hi is not sp.oo and sp.ask(sp.Q.negative(hi)) is True:
+            return Convexity.STRONGLY_CONCAVE, ConvexityCertificate(
+                Convexity.STRONGLY_CONCAVE,
+                ds,
+                "second-derivative-bound",
+                sp.simplify(-hi),
+                (d2, hi),
+            )
+    except SYMBOLIC_QUERY_ERRORS:
+        pass
+    return None
+
+
+def convexity_implications(primary):
+    """Return ordinary convexity/concavity properties implied by ``primary``.
+
+    The ordering lives in one place so default strongest-class results and
+    ``all_properties=True`` cannot drift apart across scalar and multivariate
+    code paths.
+    """
+    table = {
+        Convexity.STRONGLY_CONVEX: (Convexity.STRICTLY_CONVEX, Convexity.CONVEX),
+        Convexity.STRICTLY_CONVEX: (Convexity.CONVEX,),
+        Convexity.CONVEX: (),
+        Convexity.STRONGLY_CONCAVE: (Convexity.STRICTLY_CONCAVE, Convexity.CONCAVE),
+        Convexity.STRICTLY_CONCAVE: (Convexity.CONCAVE,),
+        Convexity.CONCAVE: (),
+        Convexity.AFFINE: (Convexity.CONVEX, Convexity.CONCAVE),
+    }
+    return table.get(primary, ())
+
+
+def secondary_convexity_properties(expr, var, domain, primary):
+    props = list(convexity_implications(primary))
+    evidence = []
+    # Positive f: log-convexity/concavity reduces exactly to convexity of log(f).
+    s = function_sign(expr, var, domain=domain)
+    if s is Sign.POSITIVE:
+        try:
+            from ..proof_cache import cached_derivative
+
+            d2log = sp.simplify(cached_derivative(sp.log(expr), var, order=2))
+            ls = function_sign(d2log, var, domain=domain)
+            if ls in (Sign.POSITIVE, Sign.NONNEGATIVE, Sign.ZERO):
+                props.append(Convexity.LOG_CONVEX)
+            if ls in (Sign.NEGATIVE, Sign.NONPOSITIVE, Sign.ZERO):
+                props.append(Convexity.LOG_CONCAVE)
+        except SYMBOLIC_QUERY_ERRORS:
+            pass
+    # Every monotone univariate function is both quasiconvex and quasiconcave.
+    m = function_monotonicity(expr, var, domain=domain)
+    if m in (
+        Monotonicity.STRICTLY_INCREASING,
+        Monotonicity.NONDECREASING,
+        Monotonicity.STRICTLY_DECREASING,
+        Monotonicity.NONINCREASING,
+        Monotonicity.CONSTANT,
+    ):
+        props.extend((Convexity.QUASICONVEX, Convexity.QUASICONCAVE))
+    # A differentiable function with derivative of one strict sign is both
+    # pseudoconvex and pseudoconcave on an interval.
+    try:
+        ds = condition_to_set(domain, var)
+        if isinstance(ds, sp.Interval):
+            from ..proof_cache import cached_derivative
+
+            sg = function_sign(
+                cached_derivative(expr, var, order=1), var, domain=domain
+            )
+            if sg in (Sign.POSITIVE, Sign.NEGATIVE):
+                props.extend((Convexity.PSEUDOCONVEX, Convexity.PSEUDOCONCAVE))
+    except SYMBOLIC_QUERY_ERRORS:
+        pass
+    # deterministic order / dedupe
+    out = []
+    for p in props:
+        if p not in out and p is not primary:
+            out.append(p)
+    return tuple(out), tuple(evidence)
+
+
+def _positive_domain(domain, var):
+    ds = condition_to_set(domain, var)
+    if isinstance(ds, sp.Interval):
+        return ds.start.is_nonnegative is True and (ds.start != 0 or ds.left_open)
+    rel = var > 0
+    return domain == rel or (isinstance(domain, sp.And) and rel in domain.args)
+
+
+def special_function_convexity(expr, var, domain):
+    condition_to_set(domain, var)
+    # Gamma is positive and strictly log-convex on (0, infinity); positivity
+    # plus strict log-convexity also implies strict ordinary convexity.
+    if expr.func is sp.gamma and expr.args == (var,) and _positive_domain(domain, var):
+        return (Convexity.STRICTLY_CONVEX, Convexity.CONVEX, Convexity.LOG_CONVEX)
+    # Modified Bessel K_nu(x): for real fixed order, catalogue facts already
+    # give decreasing/convex; expose that as a strong special-function hint.
+    if expr.func is sp.besselk and len(expr.args) == 2 and expr.args[1] == var:
+        nu = expr.args[0]
+        if nu.is_real is True and _positive_domain(domain, var):
+            return (Convexity.STRICTLY_CONVEX, Convexity.CONVEX, Convexity.LOG_CONVEX)
+    return ()