funcprops 0.1.0__py3-none-any.whl

funcprops/real_analysis/zeros.py

@@ -0,0 +1,327 @@
+from __future__ import annotations
+
+import sympy as sp
+from sympy import S
+
+from ..exceptions import SYMBOLIC_QUERY_ERRORS
+from ..results import PropertyResult
+from ..stratification import evaluate_parameter_strata
+from ..transcendental.roots import (
+    RootCertificate,
+    RootIsolationResult,
+    transcendental_roots,
+)
+from .common import condition_to_set
+from .domain import function_domain
+
+
+def _merge_root_results(results, domain_set):
+    """Merge per-cell zero results without discarding certification metadata."""
+    roots = []
+    zero_intervals = []
+    isolated = []
+    certificates = []
+    evidence = []
+    families = []
+    geometry = []
+    complete = True
+    methods = []
+    periodic = None
+    for result in results:
+        roots.extend(result.roots)
+        zero_intervals.extend(result.zero_intervals)
+        isolated.extend(result.isolated_intervals)
+        certificates.extend(result.certificates)
+        evidence.extend(result.evidence)
+        families.extend(result.parametric_families)
+        geometry.extend(result.geometry)
+        complete = complete and result.complete
+        methods.append(result.method)
+        if result.periodic is not None:
+            # A periodic representation cannot in general be combined losslessly
+            # with unrelated domain cells. Preserve it only for the single-cell case.
+            if periodic is None and len(results) == 1:
+                periodic = result.periodic
+            else:
+                complete = False
+    roots = tuple(sorted(set(roots), key=sp.default_sort_key))
+    zero_intervals = tuple(sorted(set(zero_intervals), key=sp.default_sort_key))
+    method = "domain_cell_isolation:" + "+".join(dict.fromkeys(methods))
+    return RootIsolationResult(
+        roots,
+        zero_intervals,
+        tuple(isolated),
+        periodic,
+        complete,
+        method,
+        (*tuple(evidence), ("domain_cells", domain_set)),
+        tuple(certificates),
+        tuple(families),
+        tuple(geometry),
+    )
+
+
+def _domain_cells(domain_set):
+    """Return explicit real interval/point cells, or ``None`` if unresolved."""
+    domain_set = sp.simplify(domain_set)
+    if domain_set is S.EmptySet:
+        return ()
+    if isinstance(domain_set, (sp.Interval, sp.FiniteSet)):
+        return (domain_set,)
+    if isinstance(domain_set, sp.Union):
+        cells = []
+        for arg in domain_set.args:
+            sub = _domain_cells(arg)
+            if sub is None:
+                return None
+            cells.extend(sub)
+        return tuple(cells)
+    return None
+
+
+def _finite_real_solutions(equation, var):
+    try:
+        sol = sp.solveset(equation, var, domain=S.Reals)
+    except SYMBOLIC_QUERY_ERRORS:
+        return ()
+    if not isinstance(sol, sp.FiniteSet):
+        return ()
+    return tuple(q for q in sol if q.is_real is not False)
+
+
+def _structural_exceptional_points(expr, var, domain_set):
+    """Exact points at which a real-expression regime or branch can change."""
+    equations = []
+    try:
+        den = sp.denom(sp.together(expr))
+        if den != 1:
+            equations.append(sp.Eq(den, 0))
+    except SYMBOLIC_QUERY_ERRORS:
+        pass
+    for node in sp.preorder_traversal(expr):
+        if node.func is sp.log and node.args:
+            equations.append(sp.Eq(node.args[0], 0))
+        elif isinstance(node, sp.Pow):
+            base, exponent = node.args
+            if exponent.is_Rational and not exponent.is_Integer:
+                equations.append(sp.Eq(base, 0))
+        elif isinstance(node, sp.Piecewise):
+            for _value, cond in node.args:
+                if cond is True or cond is S.true:
+                    continue
+                from sympy.core.relational import Relational
+
+                for rel in cond.atoms(Relational):
+                    equations.append(sp.Eq(rel.lhs - rel.rhs, 0))
+    points = []
+    for eq in equations:
+        for point in _finite_real_solutions(eq, var):
+            try:
+                contained = domain_set.contains(point)
+            except SYMBOLIC_QUERY_ERRORS:
+                continue
+            if contained is S.true and point not in points:
+                points.append(point)
+    return tuple(sorted(points, key=sp.default_sort_key))
+
+
+def _split_interval_at_points(interval, points):
+    if not isinstance(interval, sp.Interval):
+        return (interval,)
+    interior = []
+    for point in points:
+        try:
+            if interval.contains(point) is S.true and point not in (
+                interval.start,
+                interval.end,
+            ):
+                interior.append(point)
+        except SYMBOLIC_QUERY_ERRORS:
+            pass
+    interior = tuple(sorted(set(interior), key=sp.default_sort_key))
+    if not interior:
+        return (interval,)
+    cells = []
+    left = interval.start
+    left_open = interval.left_open
+    for point in interior:
+        cells.append(sp.Interval(left, point, left_open=left_open, right_open=True))
+        cells.append(sp.FiniteSet(point))
+        left = point
+        left_open = True
+    cells.append(
+        sp.Interval(
+            left, interval.end, left_open=left_open, right_open=interval.right_open
+        )
+    )
+    return tuple(c for c in cells if c is not S.EmptySet)
+
+
+def _zeros_on_set(expr, var, domain_set, *, return_result, allow_numerical):
+    """Evaluate zero geometry on one parameter-free real set.
+
+    Disconnected real domains are analyzed cell by cell so no certificate spans a
+    pole, branch boundary, logarithmic exclusion, or other point where the input is
+    undefined.
+    """
+    cells = _domain_cells(domain_set)
+    if cells is not None:
+        exceptional = _structural_exceptional_points(expr, var, domain_set)
+        split_cells = []
+        for cell in cells:
+            split_cells.extend(_split_interval_at_points(cell, exceptional))
+        cells = tuple(split_cells)
+    if cells is not None and not (
+        len(cells) == 1 and isinstance(cells[0], sp.Interval) and cells[0] == domain_set
+    ):
+        results = []
+        for cell in cells:
+            if isinstance(cell, sp.FiniteSet):
+                roots = []
+                certs = []
+                cell_complete = True
+                for point in cell:
+                    try:
+                        value = sp.simplify(expr.subs(var, point))
+                    except SYMBOLIC_QUERY_ERRORS:
+                        cell_complete = False
+                        continue
+                    if value == 0 or value.is_zero is True:
+                        roots.append(point)
+                        certs.append(
+                            RootCertificate(
+                                sp.FiniteSet(point),
+                                1,
+                                "exact_domain_point_root",
+                                (("value", value),),
+                                True,
+                            )
+                        )
+                    elif value.is_zero is not False:
+                        cell_complete = False
+                results.append(
+                    RootIsolationResult(
+                        tuple(roots),
+                        complete=cell_complete,
+                        method="domain_point_evaluation",
+                        certificates=tuple(certs),
+                    )
+                )
+            else:
+                results.append(
+                    transcendental_roots(
+                        expr, var, cell, allow_numerical=allow_numerical
+                    )
+                )
+        rr = _merge_root_results(results, domain_set)
+    else:
+        rr = transcendental_roots(
+            expr, var, domain_set, allow_numerical=allow_numerical
+        )
+    if return_result:
+        return rr
+    if rr.complete:
+        if rr.periodic is not None:
+            return rr.periodic
+        if (
+            rr.method == "dlmf_indexed_zeros"
+            and rr.evidence
+            and isinstance(rr.evidence[0], sp.Set)
+        ):
+            return rr.evidence[0]
+        if rr.isolated_intervals or rr.parametric_families:
+            return rr
+        parts = []
+        if rr.roots:
+            parts.append(sp.FiniteSet(*rr.roots))
+        parts.extend(rr.zero_intervals)
+        if not parts:
+            return S.EmptySet
+        return sp.Union(*parts) if len(parts) > 1 else parts[0]
+    return rr
+
+
+def function_zeros(
+    expr,
+    var,
+    *,
+    domain=True,
+    return_result=False,
+    allow_numerical=False,
+    _domain_ready=False,
+):
+    """Return the certified real zero set of ``expr``.
+
+    Exact finite and periodic families are returned directly. Parameter-dependent
+    domain conditions are evaluated stratum by stratum. If a root is only
+    certified by an isolating interval, ``RootIsolationResult`` is returned so
+    the certificate is not discarded.
+    """
+    expr = sp.sympify(expr)
+    var = sp.sympify(var)
+    natural = function_domain(expr, var)
+    if isinstance(natural, PropertyResult):
+        # Unknown natural-domain information must not erase an explicit user
+        # restriction. Fall back to the requested set/condition only.
+        if domain is True:
+            domain_set = S.Reals
+        elif isinstance(domain, sp.Set):
+            domain_set = domain
+        else:
+            domain_set = condition_to_set(sp.sympify(domain), var)
+            if domain_set is None:
+                return RootIsolationResult(
+                    (), complete=False, method="unsupported-domain"
+                )
+        return _zeros_on_set(
+            expr,
+            var,
+            domain_set,
+            return_result=return_result,
+            allow_numerical=allow_numerical,
+        )
+
+    if domain is True:
+        condition = natural
+    elif isinstance(domain, sp.Set):
+        natural_set = condition_to_set(natural, var)
+        domain_set = sp.Intersection(
+            natural_set if natural_set is not None else S.Reals, domain
+        )
+        return _zeros_on_set(
+            expr,
+            var,
+            domain_set,
+            return_result=return_result,
+            allow_numerical=allow_numerical,
+        )
+    else:
+        condition = sp.And(natural, sp.sympify(domain))
+
+    if not _domain_ready:
+        stratified = evaluate_parameter_strata(
+            condition,
+            var,
+            lambda branch: function_zeros(
+                expr,
+                var,
+                domain=branch,
+                return_result=return_result,
+                allow_numerical=allow_numerical,
+                _domain_ready=True,
+            ),
+            source="zero-parameter-stratification",
+        )
+        if stratified is not None:
+            return stratified
+
+    domain_set = condition_to_set(condition, var)
+    if domain_set is None:
+        return RootIsolationResult((), complete=False, method="unsupported-domain")
+    return _zeros_on_set(
+        expr,
+        var,
+        domain_set,
+        return_result=return_result,
+        allow_numerical=allow_numerical,
+    )

funcprops/registry.py

@@ -0,0 +1,274 @@
+from __future__ import annotations
+
+import json
+import re
+from collections.abc import Iterable
+from dataclasses import dataclass
+from functools import lru_cache
+from importlib.resources import files
+from typing import Any
+
+import sympy as sp
+from sympy import Symbol
+
+from .conditions import parse_catalogue_expression
+
+
+def _balanced_content(text: str, start: int, open_char="[", close_char="]"):
+    depth = 0
+    for i in range(start, len(text)):
+        ch = text[i]
+        if ch == open_char:
+            depth += 1
+        elif ch == close_char:
+            depth -= 1
+            if depth == 0:
+                return text[start + 1 : i]
+    return None
+
+
+def _split_top_level(text: str):
+    out = []
+    start = 0
+    depth = 0
+    pairs = {"[": "]", "(": ")", "{": "}"}
+    closes = set(pairs.values())
+    stack = []
+    for i, ch in enumerate(text):
+        if ch in pairs:
+            stack.append(pairs[ch])
+            depth += 1
+        elif ch in closes and stack and ch == stack[-1]:
+            stack.pop()
+            depth -= 1
+        elif ch == "," and depth == 0:
+            out.append(text[start:i].strip())
+            start = i + 1
+    out.append(text[start:].strip())
+    return out
+
+
+def _source_signature(lhs: str | None):
+    """Extract the represented function pattern and property mode/variable."""
+    if not lhs:
+        return None, (), None, None
+    lhs = lhs.split("/;", 1)[0].strip()
+    first = lhs.find("[")
+    if first < 0:
+        return None, (), None, None
+    outer = _balanced_content(lhs, first)
+    if outer is None:
+        return None, (), None, None
+    outer_args = _split_top_level(outer)
+    if not outer_args:
+        return None, (), None, None
+    fpat = outer_args[0].strip()
+    if fpat.startswith("HoldPattern["):
+        i = fpat.find("[")
+        inner = _balanced_content(fpat, i)
+        if inner is not None:
+            fpat = inner.strip()
+    hidx = fpat.find("[")
+    if hidx < 0:
+        return fpat, (), None, outer_args[1] if len(outer_args) > 1 else None
+    head = fpat[:hidx].strip()
+    inner = _balanced_content(fpat, hidx)
+    args = tuple(_split_top_level(inner or "")) if inner is not None else ()
+    prop_head = lhs[:first].strip()
+    mode = None
+    var_token = None
+    if "SingularityProperties" in prop_head and len(outer_args) > 1:
+        token = outer_args[1].strip()
+        if token == "True":
+            mode = "real"
+        elif token == "False":
+            mode = "complex"
+        else:
+            mode = "any"
+    if "RealUnivariateProperties" in prop_head and len(outer_args) > 1:
+        var_token = outer_args[1].strip()
+    return head, args, mode, var_token
+
+
+def _pattern_name(token: str):
+    token = token.strip()
+    m = re.match(r"([A-Za-z$][A-Za-z0-9$]*)_", token)
+    if m:
+        return m.group(1)
+    m = re.match(r"([A-Za-z$][A-Za-z0-9$]*):", token)
+    if m:
+        return m.group(1)
+    return None
+
+
+def _literal_pattern_matches(token: str, actual) -> bool:
+    token = token.strip()
+    # Ordinary named patterns are handled by guards/assumptions.
+    if "_" in token and re.match(r"^[A-Za-z$][A-Za-z0-9$]*_", token):
+        return True
+    # a:(2|3), a:3 style restricted alternatives/defaults.
+    if ":" in token and re.match(r"^[A-Za-z$][A-Za-z0-9$]*:", token):
+        rhs = token.split(":", 1)[1].strip()
+        if rhs.startswith("(") and rhs.endswith(")") and "|" in rhs:
+            vals = rhs[1:-1].split("|")
+            return any(_literal_pattern_matches(v, actual) for v in vals)
+        if rhs.startswith("_"):
+            return True
+        return _literal_pattern_matches(rhs, actual)
+    # List/vector patterns and Blank/Repeated constructs are too rich to match
+    # syntactically here; leave them to their explicit registry guard.
+    if any(x in token for x in ("_", "Repeated[", "Vectors[", "Matrices[")):
+        return True
+    try:
+        literal = parse_catalogue_expression(token)
+        if isinstance(actual, sp.Basic) and isinstance(literal, sp.Basic):
+            return sp.simplify(actual - literal) == 0
+        return actual == literal
+    except (TypeError, ValueError):
+        return False
+
+
+@dataclass(frozen=True)
+class RuleCase:
+    value_source: str
+    condition_source: str
+    source_property_type: str | None = None
+    source_lhs: str | None = None
+
+    @property
+    def condition(self):
+        return parse_catalogue_expression(self.condition_source or "True")
+
+    @property
+    def value(self):
+        return parse_catalogue_expression(self.value_source)
+
+    @property
+    def signature(self):
+        return _source_signature(self.source_lhs)
+
+    def substitutions(self, expr):
+        _, patterns, _, _ = self.signature
+        repl = {}
+        for token, actual in zip(patterns, getattr(expr, "args", ()), strict=False):
+            name = _pattern_name(token)
+            if name:
+                repl[Symbol(name)] = actual
+        return repl
+
+    def instantiate(self, expr):
+        repl = self.substitutions(expr)
+        value = self.value
+        condition = self.condition
+        if isinstance(value, sp.Basic):
+            value = value.xreplace(repl)
+        if isinstance(condition, sp.Basic):
+            condition = condition.xreplace(repl)
+        return value, condition
+
+    def matches(self, expr, *, var=None, mode=None) -> bool:
+        _, patterns, case_mode, var_token = self.signature
+        args = getattr(expr, "args", ())
+        if patterns and len(patterns) != len(args):
+            return False
+        for token, actual in zip(patterns, args, strict=False):
+            if not _literal_pattern_matches(token, actual):
+                return False
+        if mode in ("real", "complex") and case_mode not in (None, "any", mode):
+            return False
+        if var is not None and var_token is not None:
+            name = _pattern_name(var_token)
+            if name:
+                mapped = self.substitutions(expr).get(Symbol(name))
+                if mapped is not None and mapped != var:
+                    return False
+        return True
+
+    def specificity(self, *, mode=None) -> int:
+        _, patterns, case_mode, _ = self.signature
+        score = 0
+        for token in patterns:
+            t = token.strip()
+            if ":" in t:
+                score += 3
+            elif re.search(r"_(Integer|Real|Complex|Positive|NonNegative)", t):
+                score += 2
+            elif "_" not in t:
+                score += 4
+        if mode in ("real", "complex") and case_mode == mode:
+            score += 2
+        return score
+
+
+@dataclass(frozen=True)
+class Family:
+    raw: dict[str, Any]
+
+    @property
+    def id(self):
+        return self.raw["family_id"]
+
+    @property
+    def sympy_names(self):
+        return tuple(self.raw.get("sympy_names", ()))
+
+    @property
+    def mpmath_names(self):
+        return tuple(self.raw.get("mpmath_names", ()))
+
+    @property
+    def catalogue_names(self):
+        return tuple(self.raw.get("catalogue_names", ()))
+
+    def cases(self, prop: str) -> tuple[RuleCase, ...]:
+        p = self.raw.get("properties", {}).get(prop, {})
+        return tuple(
+            RuleCase(
+                **{
+                    k: c.get(k)
+                    for k in (
+                        "value_source",
+                        "condition_source",
+                        "source_property_type",
+                        "source_lhs",
+                    )
+                }
+            )
+            for c in p.get("cases", ())
+        )
+
+
+class FunctionRegistry:
+    def __init__(self, records: Iterable[dict[str, Any]]):
+        self._families = tuple(Family(r) for r in records)
+        self._by_name = {}
+        for fam in self._families:
+            for n in (
+                fam.id,
+                *fam.sympy_names,
+                *fam.mpmath_names,
+                *fam.catalogue_names,
+            ):
+                self._by_name.setdefault(n, fam)
+
+    def __len__(self):
+        return len(self._families)
+
+    def __iter__(self):
+        return iter(self._families)
+
+    def get(self, name: str) -> Family | None:
+        return self._by_name.get(name)
+
+    def require(self, name: str) -> Family:
+        f = self.get(name)
+        if f is None:
+            raise KeyError(name)
+        return f
+
+
+@lru_cache(maxsize=1)
+def registry() -> FunctionRegistry:
+    p = files("funcprops").joinpath("data/catalogue.json")
+    payload = json.loads(p.read_text())
+    return FunctionRegistry(payload["families"])