funcprops 0.1.0__py3-none-any.whl

funcprops/__init__.py

@@ -0,0 +1,234 @@
+"""Symbolic function properties for SymPy expressions."""
+
+from .api import (
+    function_analytic,
+    function_bijective,
+    function_boundedness,
+    function_branchcuts,
+    function_branchpoints,
+    function_complex_zeros,
+    function_continuous,
+    function_convexity,
+    function_differentiability,
+    function_discontinuities,
+    function_domain,
+    function_homogeneity,
+    function_injective,
+    function_meromorphic,
+    function_monotonicity,
+    function_oscillation,
+    function_periodicity,
+    function_poles,
+    function_range,
+    function_sign,
+    function_singularities,
+    function_singularity_analysis,
+    function_smoothness,
+    function_surjective,
+    function_symmetry,
+    function_zeros,
+)
+from .dlmf import DLMFFact, dlmf_audit_report, dlmf_facts
+from .real_analysis.advanced_convexity import ConvexityCertificate
+from .real_analysis.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,
+    range_from_monotonic_partition,
+    solve_monotonic_inverse,
+)
+from .real_analysis.oscillation import OscillationCertificate
+from .real_analysis.smoothness import SmoothnessResult
+from .real_analysis.structural_properties import (
+    HomogeneityResult,
+    PeriodicityResult,
+    SymmetryResult,
+)
+from .registry import Family, FunctionRegistry, RuleCase, registry
+from .results import *
+from .singularities import SingularityAnalysis
+from .transcendental import (
+    AlgebraizationResult,
+    AnalyticNeighborhoodCertificate,
+    ArgumentPrincipleCertificate,
+    CertifiedComplexRootRectangle,
+    CertifiedIntegerBracket,
+    CertifiedRootInterval,
+    ComplexRectangle,
+    ComplexRootIsolationResult,
+    ExponentialFourierCount,
+    ExtremumEnvelope,
+    ExtremumFamilyCertificate,
+    ExtremumOrderingTheorem,
+    ExtremumRange,
+    IndexedExtremumValue,
+    IndexedTailIndex,
+    IndexedTailInversionCertificate,
+    IndexedZero,
+    IntervalPropertyCell,
+    ParametricZeroFamily,
+    PeriodicCondition,
+    PeriodicSet,
+    PropertyIntervalDecomposition,
+    RootCertificate,
+    RootIsolationResult,
+    UnivariateReductionResult,
+    ZeroGeometryCertificate,
+    ZeroInterlacing,
+    ZeroOrdering,
+    algebraize,
+    analytic_neighborhood,
+    argument_principle_count,
+    exponential_fourier_count,
+    exponential_polynomial_terms,
+    extremum_geometry,
+    extremum_ordering_theorems,
+    holomorphic_on_rectangle,
+    indexed_tail_integer_bracket,
+    indexed_tail_inversion,
+    isolate_complex_roots,
+    property_interval_decomposition,
+    reduce_univariate_condition,
+    robust_real_sign,
+    simplify_extremum_range,
+    symbolic_extremum_range,
+    transcendental_roots,
+    zero_geometry,
+    zero_ordering_bounds,
+)
+from .verification import (
+    verify_certificate,
+    verify_convexity_certificate,
+    verify_extremum_family_certificate,
+    verify_extremum_ordering_theorem,
+    verify_extremum_range,
+    verify_indexed_tail_inversion,
+    verify_integer_bracket,
+    verify_monotonic_decomposition,
+    verify_monotonic_partition,
+    verify_root_certificate,
+    verify_zero_geometry,
+)
+
+__all__ = [
+    name
+    for name in globals()
+    if name.startswith("function_")
+    or name
+    in {
+        "registry",
+        "FunctionRegistry",
+        "Family",
+        "RuleCase",
+        "Analyticity",
+        "Meromorphicity",
+        "Monotonicity",
+        "Convexity",
+        "Sign",
+        "Boundedness",
+        "Continuity",
+        "Differentiability",
+        "TruthValue",
+        "Periodicity",
+        "Symmetry",
+        "Homogeneity",
+        "PropertyResult",
+        "DetailedPropertyResult",
+        "SupportsDetailedPropertyResult",
+        "as_detailed_result",
+        "ConditionalValue",
+        "Singularity",
+        "SingularityKind",
+        "SingularityAnalysis",
+        "PeriodicSet",
+        "PeriodicCondition",
+        "RootCertificate",
+        "CertifiedRootInterval",
+        "ComplexRectangle",
+        "ArgumentPrincipleCertificate",
+        "CertifiedComplexRootRectangle",
+        "ComplexRootIsolationResult",
+        "ParametricZeroFamily",
+        "RootIsolationResult",
+        "IndexedZero",
+        "ZeroOrdering",
+        "ZeroInterlacing",
+        "ZeroGeometryCertificate",
+        "IntervalPropertyCell",
+        "PropertyIntervalDecomposition",
+        "zero_geometry",
+        "property_interval_decomposition",
+        "zero_ordering_bounds",
+        "IndexedExtremumValue",
+        "ExtremumEnvelope",
+        "ExtremumFamilyCertificate",
+        "ExtremumOrderingTheorem",
+        "ExtremumRange",
+        "ExponentialFourierCount",
+        "extremum_geometry",
+        "extremum_ordering_theorems",
+        "simplify_extremum_range",
+        "symbolic_extremum_range",
+        "AnalyticNeighborhoodCertificate",
+        "UnivariateReductionResult",
+        "PeriodicityResult",
+        "SymmetryResult",
+        "HomogeneityResult",
+        "MonotonicDecomposition",
+        "MonotonicInterval",
+        "IndexedMonotonicPartition",
+        "MonotonicPartition",
+        "NonMonotonicityWitness",
+        "InverseSolutionCertificate",
+        "PartitionRange",
+        "OscillationCertificate",
+        "monotonic_decomposition",
+        "monotonic_partition",
+        "solve_monotonic_inverse",
+        "range_from_monotonic_partition",
+        "injectivity_from_monotonic_partition",
+        "certified_monotonic_inverse",
+        "clear_monotonic_partition_cache",
+        "IndexedTailIndex",
+        "IndexedTailInversionCertificate",
+        "CertifiedIntegerBracket",
+        "indexed_tail_inversion",
+        "indexed_tail_integer_bracket",
+        "SmoothnessResult",
+        "ConvexityCertificate",
+        "DLMFFact",
+        "dlmf_facts",
+        "dlmf_audit_report",
+        "verify_certificate",
+        "verify_monotonic_decomposition",
+        "verify_monotonic_partition",
+        "verify_zero_geometry",
+        "verify_convexity_certificate",
+        "verify_extremum_ordering_theorem",
+        "verify_indexed_tail_inversion",
+        "verify_root_certificate",
+        "verify_extremum_family_certificate",
+        "verify_extremum_range",
+        "verify_integer_bracket",
+        "AlgebraizationResult",
+        "transcendental_roots",
+        "robust_real_sign",
+        "exponential_fourier_count",
+        "exponential_polynomial_terms",
+        "reduce_univariate_condition",
+        "algebraize",
+        "argument_principle_count",
+        "isolate_complex_roots",
+        "holomorphic_on_rectangle",
+        "analytic_neighborhood",
+    }
+]

funcprops/_semialg.py

@@ -0,0 +1,246 @@
+"""Adapter to semialg's public exact real-function API.
+
+funcprops owns the public property vocabulary and evidence objects. semialg
+provides the exact backend for semialgebraic functions on semialgebraic real
+domains, including domain, range, sign, monotonicity, convexity, smoothness,
+and mapping-property calculations. Imports remain lazy so catalogue and
+complex-analysis queries do not load the backend until a real-domain proof
+needs it.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from functools import cache
+
+import sympy as sp
+
+
+class SemialgUnavailable(ImportError):
+    """Raised when the required semialg public API cannot be loaded."""
+
+
+@cache
+def _public_function(name: str) -> Callable:
+    """Return one function from semialg's documented root API."""
+    try:
+        import semialg
+    except ImportError as exc:
+        raise SemialgUnavailable(
+            "funcprops real-analysis queries require semialg>=1.1.0"
+        ) from exc
+
+    try:
+        function = getattr(semialg, name)
+    except AttributeError as exc:
+        raise SemialgUnavailable(
+            f"semialg>=1.1.0 does not provide the required public function {name!r}"
+        ) from exc
+    if not callable(function):
+        raise SemialgUnavailable(f"semialg public attribute {name!r} is not callable")
+    return function
+
+
+def function_domain(expr, variable):
+    """Return semialg's recognized real-domain condition."""
+    function = _public_function("function_domain")
+    return function(sp.sympify(expr), [variable])
+
+
+def function_range(
+    expr, variable, value_symbol, *, constraints=True, method="qe", **kwargs
+):
+    """Return an exact real-range condition from semialg."""
+    function = _public_function("function_range")
+    return function(
+        sp.sympify(expr),
+        constraints,
+        [variable],
+        value_symbol=value_symbol,
+        method=method,
+        **kwargs,
+    )
+
+
+def function_convexity(
+    expr, variable, *, domain=True, strict_inequalities=True, **kwargs
+):
+    """Return semialg's strongest certified convexity classification."""
+    properties = kwargs.pop("properties", "primary")
+    return_result = kwargs.pop("return_result", False)
+    parameters = kwargs.pop("parameters", None)
+    if kwargs:
+        names = ", ".join(sorted(kwargs))
+        raise TypeError(f"unsupported semialg convexity options: {names}")
+
+    # semialg computes the strongest exact class. funcprops weakens the class
+    # afterwards when callers request non-strict semantics.
+    del strict_inequalities
+    function = _public_function("function_convexity")
+    return function(
+        sp.sympify(expr),
+        [variable],
+        domain=domain,
+        parameters=parameters,
+        return_result=return_result,
+        properties=properties,
+    )
+
+
+def function_monotonicity(expr, variable, *, domain=True, return_result=False):
+    """Return semialg's exact monotonicity classification."""
+    function = _public_function("function_monotonicity")
+    return function(
+        sp.sympify(expr),
+        variable,
+        domain=domain,
+        return_result=return_result,
+    )
+
+
+def function_smoothness(expr, variable, *, domain=True, max_order=6):
+    """Return semialg's exact regularity result on a semialgebraic domain."""
+    function = _public_function("function_smoothness")
+    return function(
+        sp.sympify(expr),
+        variable,
+        domain=domain,
+        max_order=max_order,
+    )
+
+
+def function_mapping_properties(
+    expr, variable, *, domain=True, codomain=True, image_variable=None
+):
+    """Return semialg's exact mapping properties for a semialgebraic map."""
+    function = _public_function("function_mapping_properties")
+    image_variables = None if image_variable is None else (image_variable,)
+    return function(
+        expr,
+        variable,
+        domain=domain,
+        codomain=codomain,
+        image_variables=image_variables,
+    )
+
+
+def eligible_problem(expr, variable, *, domain=True) -> bool:
+    """Return whether an expression/domain pair is safe for semialg delegation."""
+    from .real_analysis.common import (
+        is_semialgebraic_condition,
+        is_semialgebraic_expression,
+    )
+
+    return is_semialgebraic_expression(expr, variable) and is_semialgebraic_condition(
+        domain, variable
+    )
+
+
+def is_satisfiable(condition, variables):
+    """Decide satisfiability of a semialgebraic parameter guard exactly."""
+    function = _public_function("is_satisfiable")
+    normalized = tuple(sp.sympify(v) for v in variables)
+    return bool(function(sp.sympify(condition), normalized))
+
+
+def function_sign(expr, variable, *, assumptions=True, return_result=False):
+    """Return semialg's canonical exact sign classification."""
+    function = _public_function("function_sign")
+    return function(
+        sp.sympify(expr),
+        [variable],
+        assumptions=assumptions,
+        return_result=return_result,
+    )
+
+
+def function_sign_partition(expr, variable, *, domain=True):
+    """Return semialg's exact univariate sign partition."""
+    function = _public_function("function_sign_partition")
+    return function(sp.sympify(expr), variable, domain=domain)
+
+
+def normalize_sign(value):
+    """Translate a semialg sign classification into funcprops' Sign enum."""
+    from .results import Sign
+
+    classification = getattr(value, "classification", value)
+    return {
+        "positive": Sign.POSITIVE,
+        "negative": Sign.NEGATIVE,
+        "zero": Sign.ZERO,
+        "nonnegative": Sign.NONNEGATIVE,
+        "nonpositive": Sign.NONPOSITIVE,
+        "mixed": Sign.SIGN_CHANGING,
+    }.get(str(classification), Sign.UNKNOWN)
+
+
+def normalize_convexity(value):
+    """Translate semialg convexity vocabulary into funcprops' enum."""
+    from .results import Convexity
+
+    if isinstance(value, Convexity):
+        return value
+    if hasattr(value, "primary"):
+        value = value.primary
+    if isinstance(value, int):
+        return {
+            1: Convexity.STRICTLY_CONVEX,
+            2: Convexity.CONVEX,
+            -1: Convexity.STRICTLY_CONCAVE,
+            -2: Convexity.CONCAVE,
+        }.get(int(value), Convexity.UNKNOWN)
+    key = str(getattr(value, "name", value)).lower().replace("_", "").replace(" ", "")
+    return {
+        "stronglyconvex": Convexity.STRONGLY_CONVEX,
+        "strictlyconvex": Convexity.STRICTLY_CONVEX,
+        "convex": Convexity.CONVEX,
+        "affine": Convexity.AFFINE,
+        "strictlyconcave": Convexity.STRICTLY_CONCAVE,
+        "concave": Convexity.CONCAVE,
+        "stronglyconcave": Convexity.STRONGLY_CONCAVE,
+        "neither": Convexity.NEITHER,
+    }.get(key, Convexity.UNKNOWN)
+
+
+def normalize_monotonicity(value):
+    """Translate semialg monotonicity vocabulary into funcprops' enum."""
+    from .results import Monotonicity
+
+    classification = getattr(value, "classification", value)
+    return {
+        "strictly_increasing": Monotonicity.STRICTLY_INCREASING,
+        "increasing": Monotonicity.NONDECREASING,
+        "constant": Monotonicity.CONSTANT,
+        "decreasing": Monotonicity.NONINCREASING,
+        "strictly_decreasing": Monotonicity.STRICTLY_DECREASING,
+        "nonmonotonic": Monotonicity.NOT_MONOTONE,
+    }.get(str(classification), Monotonicity.UNKNOWN)
+
+
+def normalize_truth(value):
+    """Translate a backend boolean into funcprops' three-valued truth type."""
+    from .results import TruthValue
+
+    if value is True:
+        return TruthValue.TRUE
+    if value is False:
+        return TruthValue.FALSE
+    return TruthValue.UNKNOWN
+
+
+def prove_sign(expr, variable, relation, *, assumptions=True):
+    """Prove one exact sign relation with semialg's public sign provers."""
+    prover_names = {
+        "positive": "prove_positive",
+        "negative": "prove_negative",
+        "nonnegative": "prove_nonnegative",
+        "nonpositive": "prove_nonpositive",
+    }
+    try:
+        prover_name = prover_names[relation]
+    except KeyError as exc:
+        raise ValueError(f"unknown sign relation: {relation!r}") from exc
+
+    prover = _public_function(prover_name)
+    return prover(sp.sympify(expr), [variable], assumptions=assumptions)

funcprops/api.py

@@ -0,0 +1,70 @@
+"""Public routing layer for function-property queries.
+
+Each public query has a single implementation in either :mod:`funcprops.singularities`
+or :mod:`funcprops.real_analysis`.  This module only re-exports those implementations
+so callers have one stable import surface without duplicating property logic.
+"""
+
+from __future__ import annotations
+
+from .real_analysis.boundedness import function_boundedness
+from .real_analysis.convexity import function_convexity
+from .real_analysis.differentiability import function_differentiability
+from .real_analysis.domain import function_domain
+from .real_analysis.mapping import (
+    function_bijective,
+    function_injective,
+    function_surjective,
+)
+from .real_analysis.monotonicity import function_monotonicity
+from .real_analysis.oscillation import function_oscillation
+from .real_analysis.range import function_range
+from .real_analysis.sign import function_sign
+from .real_analysis.smoothness import function_smoothness
+from .real_analysis.structural_properties import (
+    function_homogeneity,
+    function_periodicity,
+    function_symmetry,
+)
+from .real_analysis.zeros import function_zeros
+from .singularities import (
+    function_analytic,
+    function_branchcuts,
+    function_branchpoints,
+    function_continuous,
+    function_discontinuities,
+    function_meromorphic,
+    function_poles,
+    function_singularities,
+    function_singularity_analysis,
+)
+from .transcendental.complex_roots import function_complex_zeros
+
+__all__ = [
+    "function_analytic",
+    "function_bijective",
+    "function_boundedness",
+    "function_branchcuts",
+    "function_branchpoints",
+    "function_complex_zeros",
+    "function_continuous",
+    "function_convexity",
+    "function_differentiability",
+    "function_discontinuities",
+    "function_domain",
+    "function_homogeneity",
+    "function_injective",
+    "function_meromorphic",
+    "function_monotonicity",
+    "function_oscillation",
+    "function_periodicity",
+    "function_poles",
+    "function_range",
+    "function_sign",
+    "function_singularities",
+    "function_singularity_analysis",
+    "function_smoothness",
+    "function_surjective",
+    "function_symmetry",
+    "function_zeros",
+]

funcprops/branchcuts/__init__.py

@@ -0,0 +1,141 @@
+"""Symbolic principal-branch cuts, boundary jumps, and restrictions.
+
+The low-level API computes cut conditions and jumps.  The property-level
+:func:`funcprops.function_branchcuts` query converts those loci into the common
+funcprops singularity vocabulary.
+"""
+
+from ..engine import simplify_condition
+from .computation import (
+    branch_cut_jumps,
+    branch_cut_jumps_pairs,
+    condition_false_q,
+    condition_simplify,
+    differentiate_pairs,
+    jump_pairs_from_table,
+    numeric_branch_cut_jumps,
+    unsatisfiable_q,
+)
+from .core import (
+    IMPLEMENTED_RULE_NAMES,
+    BranchRule,
+    ConditionalJump,
+    JumpTerm,
+    RestrictedExpr,
+    Undefined,
+    apply_restrictions,
+    branch_jump,
+    get_branch_rule,
+    propagate_undefined,
+    restrict,
+    simplify_restricted,
+)
+from .post_simplify import (
+    merge_duplicate_pairs,
+    post_simplify_pairs,
+    post_simplify_restricted,
+    rewrite_branch_expr,
+    simplify_branch_condition,
+)
+
+
+def branch_cut_conditions(expr, variable, *, assumptions=True):
+    """Return unique symbolic principal-cut conditions for ``expr``.
+
+    This property query is intentionally cheaper than full jump propagation.
+    It pulls primitive cut rules back through arguments and recursively includes
+    inner cuts, but does not form plus/minus boundary-value products.
+    """
+    from sympy import Dummy, S, sympify
+
+    expr = sympify(expr)
+    variable = sympify(variable)
+    out = []
+    seen = set()
+
+    def add(cond):
+        cond = simplify_condition(sympify(cond), assumptions=assumptions)
+        if cond is S.false:
+            return
+        key = repr(cond)
+        if key not in seen:
+            seen.add(key)
+            out.append(cond)
+
+    def visit(e):
+        e = sympify(e)
+        if not e.has(variable):
+            return
+        # Exact primitive rule first.
+        try:
+            rule = get_branch_rule(e, variable)
+        except (NotImplementedError, ValueError, TypeError, AttributeError):
+            rule = None
+        if rule is not None:
+            for term in rule.jump_terms:
+                add(term.cond)
+        else:
+            # Pull a one-variable primitive rule back through each varying argument.
+            for i, arg in enumerate(getattr(e, "args", ())):
+                if not getattr(arg, "has", lambda *_: False)(variable):
+                    continue
+                u = Dummy("funcprops_branch_arg")
+                args = list(e.args)
+                args[i] = u
+                try:
+                    template = e.func(*args)
+                    rule = get_branch_rule(template, u)
+                except (NotImplementedError, ValueError, TypeError, AttributeError):
+                    continue
+                for term in rule.jump_terms:
+                    add(term.cond.xreplace({u: arg}))
+        # Branches inside arguments remain branches of the composite expression.
+        for arg in getattr(e, "args", ()):
+            if getattr(arg, "has", lambda *_: False)(variable):
+                visit(arg)
+
+    visit(expr)
+    return tuple(out)
+
+
+def coverage_summary():
+    """Return BranchCuts-rule coverage against the funcprops catalogue."""
+    from ..registry import registry
+
+    families = list(registry())
+    return {
+        "implemented_rules": {"total": len(IMPLEMENTED_RULE_NAMES)},
+        "sympy": {"total": sum(bool(f.sympy_names) for f in families)},
+        "mpmath": {"total": sum(bool(f.mpmath_names) for f in families)},
+    }
+
+
+__all__ = [
+    "IMPLEMENTED_RULE_NAMES",
+    "BranchRule",
+    "ConditionalJump",
+    "JumpTerm",
+    "RestrictedExpr",
+    "Undefined",
+    "apply_restrictions",
+    "branch_cut_conditions",
+    "branch_cut_jumps",
+    "branch_cut_jumps_pairs",
+    "branch_jump",
+    "condition_false_q",
+    "condition_simplify",
+    "coverage_summary",
+    "differentiate_pairs",
+    "get_branch_rule",
+    "jump_pairs_from_table",
+    "merge_duplicate_pairs",
+    "numeric_branch_cut_jumps",
+    "post_simplify_pairs",
+    "post_simplify_restricted",
+    "propagate_undefined",
+    "restrict",
+    "rewrite_branch_expr",
+    "simplify_branch_condition",
+    "simplify_restricted",
+    "unsatisfiable_q",
+]