funcprops 0.1.0__py3-none-any.whl

funcprops/transcendental/periodic.py

@@ -0,0 +1,222 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from math import gcd, lcm
+
+import sympy as sp
+from sympy import S
+
+from ..exceptions import SYMBOLIC_QUERY_ERRORS
+
+
+def _canonical_period(period):
+    p = sp.simplify(sp.sympify(period))
+    if p.is_negative is True:
+        p = -p
+    return p
+
+
+def _integer_ratio(a, b):
+    r = sp.simplify(a / b)
+    return int(r) if r.is_Integer is True and int(r) > 0 else None
+
+
+def _translate_set(s, delta):
+    delta = sp.sympify(delta)
+    if delta == 0:
+        return s
+    if isinstance(s, sp.Interval):
+        return sp.Interval(s.start + delta, s.end + delta, s.left_open, s.right_open)
+    if isinstance(s, sp.FiniteSet):
+        return sp.FiniteSet(*(sp.simplify(v + delta) for v in s))
+    if isinstance(s, sp.Union):
+        return sp.Union(*(_translate_set(a, delta) for a in s.args))
+    return sp.imageset(lambda t: t + delta, s)
+
+
+@dataclass(frozen=True)
+class PeriodicSet:
+    """Set obtained by translating a base set by integer multiples of a period."""
+
+    base: sp.Set
+    period: sp.Expr
+    variable: sp.Symbol | None = None
+    origin: sp.Expr = S.Zero
+
+    def __post_init__(self):
+        object.__setattr__(self, "base", sp.sympify(self.base))
+        object.__setattr__(self, "period", _canonical_period(self.period))
+        object.__setattr__(self, "origin", sp.sympify(self.origin))
+        if self.period.is_positive is not True:
+            raise ValueError("PeriodicSet period must be provably positive")
+        object.__setattr__(
+            self, "base", sp.Intersection(self.base, self.fundamental_interval)
+        )
+
+    @property
+    def fundamental_interval(self):
+        return sp.Interval.Ropen(self.origin, self.origin + self.period)
+
+    def normalize_point(self, value):
+        return sp.simplify(
+            self.origin + sp.Mod(sp.sympify(value) - self.origin, self.period)
+        )
+
+    def contains(self, value):
+        return sp.Contains(self.normalize_point(value), self.base)
+
+    def as_condition(self, variable=None):
+        v = sp.sympify(variable or self.variable)
+        if v is None:
+            raise ValueError("a variable is required")
+        return self.contains(v)
+
+    def intersect_fundamental(self, condition_or_set, variable=None):
+        if isinstance(condition_or_set, sp.Set):
+            s = condition_or_set
+        else:
+            sp.sympify(variable or self.variable)
+            try:
+                s = sp.sympify(condition_or_set).as_set()
+            except (AttributeError, *SYMBOLIC_QUERY_ERRORS):
+                return None
+        return sp.Intersection(s, self.fundamental_interval)
+
+    def with_period(self, new_period):
+        """Represent the same periodic set on a larger commensurate period."""
+        new_period = _canonical_period(new_period)
+        n = _integer_ratio(new_period, self.period)
+        if n is None:
+            raise ValueError("new period must be a positive integer multiple")
+        pieces = [_translate_set(self.base, k * self.period) for k in range(n)]
+        return PeriodicSet(sp.Union(*pieces), new_period, self.variable, self.origin)
+
+    def _align(self, other):
+        if not isinstance(other, PeriodicSet):
+            return None
+        if sp.simplify(self.origin - other.origin) != 0:
+            return None
+        p = common_period_values(self.period, other.period)
+        if p is None:
+            return None
+        return self.with_period(p), other.with_period(p)
+
+    def union(self, other):
+        aligned = self._align(other)
+        if aligned is None:
+            return sp.Union(self.as_sympy_set(), other.as_sympy_set())
+        a, b = aligned
+        return PeriodicSet(
+            sp.Union(a.base, b.base),
+            a.period,
+            self.variable or other.variable,
+            a.origin,
+        )
+
+    def intersection(self, other):
+        aligned = self._align(other)
+        if aligned is None:
+            return sp.Intersection(self.as_sympy_set(), other.as_sympy_set())
+        a, b = aligned
+        return PeriodicSet(
+            sp.Intersection(a.base, b.base),
+            a.period,
+            self.variable or other.variable,
+            a.origin,
+        )
+
+    def complement(self):
+        return PeriodicSet(
+            sp.Complement(self.fundamental_interval, self.base),
+            self.period,
+            self.variable,
+            self.origin,
+        )
+
+    def affine_pullback(self, a, b=0, variable=None):
+        """Exact pullback under ``t = a*x + b`` for nonzero real ``a``.
+
+        The previous implementation normalized by inspecting only five nearby
+        period copies, which was not valid for arbitrarily large/symbolic
+        translations.  A modular ConditionSet is exact for every shift.
+        """
+        a = sp.sympify(a)
+        b = sp.sympify(b)
+        if a == 0 or a.is_real is False:
+            raise ValueError("a must be nonzero real")
+        if a.is_positive is not True and a.is_negative is not True:
+            raise ValueError("sign of a must be known")
+        p = sp.simplify(self.period / sp.Abs(a))
+        x = sp.sympify(variable or self.variable or sp.Dummy("x", real=True))
+        fi = sp.Interval.Ropen(S.Zero, p)
+        # self.contains performs exact modular normalization in the source
+        # period, so no finite translation window is needed.
+        cond = self.contains(sp.simplify(a * x + b))
+        base = sp.ConditionSet(x, cond, fi)
+        # Simplify common finite-set cases without weakening the exact fallback.
+        if isinstance(self.base, sp.FiniteSet):
+            pts = []
+            for q in self.base:
+                pts.append(sp.simplify(sp.Mod((q - b) / a, p)))
+            base = sp.FiniteSet(*pts)
+        return PeriodicSet(base, p, x, S.Zero)
+
+    def as_sympy_set(self):
+        sp.Dummy("k", integer=True)
+        return sp.imageset(lambda t, k: t + k * self.period, self.base, S.Integers)
+
+
+@dataclass(frozen=True)
+class PeriodicCondition:
+    set: PeriodicSet
+
+    def as_expr(self, variable=None):
+        return self.set.as_condition(variable)
+
+    def __sympy__(self):
+        return self.as_expr()
+
+
+def positive_period(expr, var):
+    try:
+        from sympy.calculus.util import periodicity
+
+        p = periodicity(sp.sympify(expr), sp.sympify(var))
+    except SYMBOLIC_QUERY_ERRORS:
+        return None
+    if p in (None, S.Zero, sp.oo, -sp.oo):
+        return None
+    p = _canonical_period(p)
+    return p if p.is_positive is True else None
+
+
+def common_period_values(*periods):
+    ps = [_canonical_period(p) for p in periods]
+    if not ps:
+        return None
+    p0 = ps[0]
+    ratios = []
+    for p in ps:
+        r = sp.simplify(p / p0)
+        if r.is_Rational is not True:
+            return None
+        ratios.append(sp.Rational(r))
+    nums = [abs(int(r.p)) for r in ratios]
+    dens = [int(r.q) for r in ratios]
+    num = 1
+    for n in nums:
+        num = lcm(num, n)
+    den = dens[0]
+    for d in dens[1:]:
+        den = gcd(den, d)
+    return sp.simplify(p0 * sp.Rational(num, den))
+
+
+def common_positive_period(expressions, var):
+    ps = []
+    for e in expressions:
+        p = positive_period(e, var)
+        if p is None:
+            return None
+        ps.append(p)
+    return common_period_values(*ps)

funcprops/transcendental/proof.py

@@ -0,0 +1,104 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+
+import sympy as sp
+from sympy import S
+
+from ..exceptions import SYMBOLIC_QUERY_ERRORS
+
+
+class PerformanceGoal(str, Enum):
+    SPEED = "speed"
+    QUALITY = "quality"
+
+
+@dataclass(frozen=True)
+class ProofPolicy:
+    goal: PerformanceGoal = PerformanceGoal.QUALITY
+    allow_numerical_evidence: bool = True
+    require_certificate: bool = True
+    max_symbolic_recursion: int = 3
+
+
+def extended_real_sign(value):
+    value = sp.sympify(value)
+    if value is sp.oo:
+        return 1
+    if value is -sp.oo:
+        return -1
+    if value == 0 or value.is_zero is True:
+        return 0
+    if value.is_positive is True:
+        return 1
+    if value.is_negative is True:
+        return -1
+    # Do not certify a sign from a fixed-precision approximation.  This helper
+    # is used by proof infrastructure, so expressions too close to zero (or
+    # whose exact comparison is simply unknown) must remain unknown.
+    try:
+        q = sp.ask(sp.Q.positive(value))
+        if q is True:
+            return 1
+        q = sp.ask(sp.Q.negative(value))
+        if q is True:
+            return -1
+        q = sp.ask(sp.Q.zero(value))
+        if q is True:
+            return 0
+    except SYMBOLIC_QUERY_ERRORS:
+        pass
+    return None
+
+
+def find_parameters(expressions, variables):
+    """Return free symbolic parameters independent of ``variables``."""
+    variables = set(map(sp.sympify, variables))
+    if not isinstance(expressions, (tuple, list, set, frozenset)):
+        expressions = (expressions,)
+    free = set()
+    for e in expressions:
+        if isinstance(e, sp.Basic):
+            free.update(e.free_symbols)
+    return tuple(sorted(free - variables, key=sp.default_sort_key))
+
+
+def condition_to_intervals(condition, var, *, integers=False):
+    """Parse a solved univariate condition into ordered intervals/points.
+
+    This is the SymPy analogue of the useful CADToIntervals helper in the
+    supplied FunctionProperties source.  ``None`` means the condition is not
+    in a supported solved form.
+    """
+    condition = sp.sympify(condition)
+    var = sp.sympify(var)
+    try:
+        s = (
+            condition.as_set()
+            if condition not in (S.true, S.false)
+            else (S.Reals if condition is S.true else S.EmptySet)
+        )
+    except (AttributeError, *SYMBOLIC_QUERY_ERRORS):
+        return None
+    if integers:
+        s = sp.Intersection(s, S.Integers)
+    out = []
+
+    def visit(t):
+        if t is S.EmptySet:
+            return True
+        if isinstance(t, sp.Interval):
+            out.append(t)
+            return True
+        if isinstance(t, sp.FiniteSet):
+            out.extend(sp.FiniteSet(x) for x in sorted(t, key=sp.default_sort_key))
+            return True
+        if isinstance(t, sp.Union):
+            return all(visit(a) for a in t.args)
+        if isinstance(t, sp.Range):
+            out.append(t)
+            return True
+        return False
+
+    return tuple(out) if visit(s) else None

funcprops/transcendental/real_interval.py

@@ -0,0 +1,128 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import mpmath as mp
+import sympy as sp
+
+
+@dataclass(frozen=True)
+class RealIntervalEvaluation:
+    expression: sp.Basic
+    variable: sp.Symbol
+    domain: sp.Interval
+    lower: str
+    upper: str
+    excludes_zero: bool
+    strict_sign: int
+    source: str = "mpmath-outward-rounded-real-interval"
+
+
+def _const_iv(expr):
+    if isinstance(expr, sp.Integer):
+        n = int(expr)
+        return mp.iv.mpf([n, n])
+    if isinstance(expr, sp.Rational):
+        return mp.iv.mpf([int(expr.p), int(expr.p)]) / mp.iv.mpf(
+            [int(expr.q), int(expr.q)]
+        )
+    if expr == sp.pi:
+        return mp.iv.pi
+    if expr == sp.E:
+        return mp.iv.e
+    raise ValueError
+
+
+def _eval(expr, var, x):
+    expr = sp.sympify(expr)
+    if expr == var:
+        return x
+    if not expr.has(var) and (
+        isinstance(expr, (sp.Integer, sp.Rational)) or expr in (sp.pi, sp.E)
+    ):
+        return _const_iv(expr)
+    if expr.is_Add:
+        out = mp.iv.mpf([0, 0])
+        for arg in expr.args:
+            out += _eval(arg, var, x)
+        return out
+    if expr.is_Mul:
+        out = mp.iv.mpf([1, 1])
+        for arg in expr.args:
+            out *= _eval(arg, var, x)
+        return out
+    if expr.is_Pow:
+        base, exponent = expr.args
+        b = _eval(base, var, x)
+        if exponent.is_Integer:
+            return b ** int(exponent)
+        if exponent.is_Rational and float(b.a) > 0:
+            q = _const_iv(exponent)
+            return mp.iv.exp(q * mp.iv.log(b))
+        raise ValueError
+    if expr.func is sp.exp:
+        return mp.iv.exp(_eval(expr.args[0], var, x))
+    if expr.func is sp.log:
+        a = _eval(expr.args[0], var, x)
+        if float(a.a) <= 0:
+            raise ValueError
+        return mp.iv.log(a)
+    if expr.func is sp.sin:
+        return mp.iv.sin(_eval(expr.args[0], var, x))
+    if expr.func is sp.cos:
+        return mp.iv.cos(_eval(expr.args[0], var, x))
+    if expr.func is sp.tan:
+        return mp.iv.tan(_eval(expr.args[0], var, x))
+    if expr.func is sp.sinh:
+        a = _eval(expr.args[0], var, x)
+        return (mp.iv.exp(a) - mp.iv.exp(-a)) / 2
+    if expr.func is sp.cosh:
+        a = _eval(expr.args[0], var, x)
+        return (mp.iv.exp(a) + mp.iv.exp(-a)) / 2
+    if expr.func is sp.tanh:
+        a = _eval(expr.args[0], var, x)
+        e = mp.iv.exp(2 * a)
+        return (e - 1) / (e + 1)
+    raise ValueError
+
+
+def certified_real_interval_evaluate(expr, var, domain):
+    """Enclose ``expr(domain)`` for a finite exact real interval.
+
+    The routine intentionally supports a bounded elementary vocabulary and returns
+    ``None`` outside it.  Its purpose is a conservative root-isolation fallback:
+    excluding zero proves a cell root-free, and excluding zero from a derivative
+    enclosure proves strict monotonicity on that cell.
+    """
+    expr = sp.sympify(expr)
+    var = sp.sympify(var)
+    if (
+        not isinstance(domain, sp.Interval)
+        or domain.start in (-sp.oo, sp.oo)
+        or domain.end in (-sp.oo, sp.oo)
+        or domain.start.is_real is False
+        or domain.end.is_real is False
+    ):
+        return None
+    try:
+        a = _const_iv(domain.start)
+        b = _const_iv(domain.end)
+        x = mp.iv.mpf([a.a, b.b])
+        value = _eval(expr, var, x)
+        lo = float(value.a)
+        hi = float(value.b)
+    except (ValueError, TypeError, OverflowError, ZeroDivisionError):
+        return None
+    sign = 1 if lo > 0 else -1 if hi < 0 else 0
+    return RealIntervalEvaluation(
+        expr,
+        var,
+        domain,
+        str(value.a),
+        str(value.b),
+        sign != 0,
+        sign,
+    )
+
+
+__all__ = ["RealIntervalEvaluation", "certified_real_interval_evaluate"]

funcprops/transcendental/real_sign.py

@@ -0,0 +1,117 @@
+from __future__ import annotations
+
+import contextlib
+
+import mpmath as mp
+import sympy as sp
+
+from ..exceptions import SYMBOLIC_QUERY_ERRORS
+
+
+def _exact_sign(expr):
+    """Return -1, 0, or 1 when SymPy establishes the real sign."""
+    expr = sp.sympify(expr)
+    with contextlib.suppress(*SYMBOLIC_QUERY_ERRORS):
+        expr = sp.simplify(expr)
+    if expr.is_zero is True:
+        return 0
+    if expr.is_positive is True:
+        return 1
+    if expr.is_negative is True:
+        return -1
+    with contextlib.suppress(*SYMBOLIC_QUERY_ERRORS):
+        q = sp.sign(expr)
+        if q in (-1, 0, 1):
+            return int(q)
+    return None
+
+
+def _iv_rational(q):
+    if isinstance(q, sp.Integer):
+        return mp.iv.mpf([int(q), int(q)])
+    if isinstance(q, sp.Rational):
+        return mp.iv.mpf([int(q.p), int(q.p)]) / mp.iv.mpf([int(q.q), int(q.q)])
+    raise ValueError
+
+
+def _interval_eval(expr):
+    """Evaluate a numeric exp/log elementary expression with interval arithmetic.
+
+    This intentionally supports a small audited vocabulary. Unsupported heads raise
+    ``ValueError`` so callers remain conservative rather than silently falling back
+    to ordinary floating-point evaluation.
+    """
+    expr = sp.sympify(expr)
+    if isinstance(expr, (sp.Integer, sp.Rational)):
+        return _iv_rational(expr)
+    if expr == sp.pi:
+        return mp.iv.pi
+    if expr == sp.E:
+        return mp.iv.e
+    if expr.is_Add:
+        out = mp.iv.mpf([0, 0])
+        for arg in expr.args:
+            out += _interval_eval(arg)
+        return out
+    if expr.is_Mul:
+        out = mp.iv.mpf([1, 1])
+        for arg in expr.args:
+            out *= _interval_eval(arg)
+        return out
+    if expr.is_Pow:
+        base, exponent = expr.args
+        b = _interval_eval(base)
+        if exponent.is_Integer:
+            return b ** int(exponent)
+        if exponent.is_Rational:
+            # Only use real positive-base rational powers in the robust sign path.
+            if float(b.a) <= 0:
+                raise ValueError
+            return mp.iv.exp(_iv_rational(exponent) * mp.iv.log(b))
+        raise ValueError
+    if expr.func is sp.exp:
+        return mp.iv.exp(_interval_eval(expr.args[0]))
+    if expr.func is sp.log:
+        x = _interval_eval(expr.args[0])
+        if float(x.a) <= 0:
+            raise ValueError
+        return mp.iv.log(x)
+    if expr.func is sp.sinh:
+        x = _interval_eval(expr.args[0])
+        return (mp.iv.exp(x) - mp.iv.exp(-x)) / 2
+    if expr.func is sp.cosh:
+        x = _interval_eval(expr.args[0])
+        return (mp.iv.exp(x) + mp.iv.exp(-x)) / 2
+    if expr.func is sp.tanh:
+        x = _interval_eval(expr.args[0])
+        ex = mp.iv.exp(2 * x)
+        return (ex - 1) / (ex + 1)
+    raise ValueError
+
+
+def robust_real_sign(expr, *, interval_fallback=True):
+    """Return a certified sign for a real numeric expression when possible.
+
+    The exact symbolic route is tried first.  For unresolved numeric expressions in
+    an audited exp/log vocabulary, interval arithmetic is used so very large or very
+    small exponentials can be compared without overflow/underflow.  A numerical
+    interval containing zero is *not* converted into a sign.
+    """
+    expr = sp.sympify(expr)
+    sign = _exact_sign(expr)
+    if sign is not None or not interval_fallback:
+        return sign
+    if expr.free_symbols or expr.is_real is False:
+        return None
+    try:
+        value = _interval_eval(expr)
+        if float(value.a) > 0:
+            return 1
+        if float(value.b) < 0:
+            return -1
+    except (ValueError, TypeError, OverflowError, ZeroDivisionError):
+        return None
+    return None
+
+
+__all__ = ["robust_real_sign"]