certsf 0.3.0

Alpha special-function wrappers with explicit certification diagnostics.

certsf

certsf provides alpha special-function wrappers with explicit certification diagnostics and, where available, rigorous Arb ball enclosures through python-flint.

The public API is intentionally small: every function returns an SFResult object with the computed value, backend metadata, certification status, optional error bounds, and diagnostics explaining how the result was produced.

The certification scope lives in docs/certification.md; the scope-by-scope audit lives in docs/certification_audit.md; the 0.3 custom-method audit lives in docs/v0_3_custom_method_audit.md; the active 0.3.0 certified scope lives in docs/certified_scope_0_3_0.md, and the published 0.2.0 support matrix lives in docs/certified_scope_0_2_0.md. The frozen 0.1.0 matrix remains archived in docs/certified_scope_0_1_0.md, and the formula audit trail lives in docs/formula_audit.md. Release claim wording is guarded by docs/release_claims.md.

Installation

From PyPI:

python -m pip install certsf

For certified Arb-backed mode:

python -m pip install "certsf[certified]"

For MCP tooling plus certified mode:

python -m pip install "certsf[mcp,certified]"

Prerelease versions such as 0.3.0a5 require --pre unless installing an exact version, for example certsf==0.3.0a5.

For local development:

python -m pip install -e ".[dev]"

For runtime use without optional MCP tooling:

python -m pip install -e ".[certified]"

The base package depends on scipy and mpmath. Certified mode additionally requires python-flint.

Quick Start

from certsf import gamma, besselj, pcfu

g = gamma("3.2", dps=50, mode="certified")
j = besselj("2.5", "4.0+1.25j", dps=60, mode="certified")
u = pcfu("2.5", "1.25", dps=60, mode="certified")

print(g.value)
print(g.abs_error_bound)
print(g.certified)
print(g.backend)
print(g.diagnostics)

For a plain numerical value, use mode="fast" or mode="high_precision":

from certsf import airy

result = airy("1.0", dps=80, mode="high_precision")
print(result.value)

Result Object

Every wrapper returns an SFResult with these fields:

• value: string value, or a JSON string for multi-component results.
• abs_error_bound: rigorous absolute error bound when certified.
• rel_error_bound: rigorous relative error bound when available.
• certified: True only when a rigorous enclosure was produced.
• function: canonical function name.
• method: implementation method, such as scipy.special, mpmath, arb_ball, stirling_loggamma, stirling_shifted_loggamma, or stirling_exp_gamma, or stirling_recip_rgamma.
• backend: backend package name.
• requested_dps: requested decimal precision.
• working_dps: internal decimal precision estimate.
• diagnostics: structured details about mode, domain, formula, and scope.

Unsupported certified domains return a clean non-certified result with value="", certified=False, and an explanatory diagnostics error. They do not silently fall back to mpmath and call the value certified.

Certified successes also expose diagnostics["certificate_level"], diagnostics["audit_status"], and diagnostics["certification_claim"], so callers can distinguish direct Arb primitive wrappers from narrow identity formulas, custom asymptotic-bound methods, and experimental formula-backed claims.

Choosing a Mode

• mode="fast" uses scipy.special; it is quick and non-certified.
• mode="high_precision" uses mpmath; it supports higher precision and complex arguments, but is still non-certified.
• mode="certified" uses python-flint / Arb when a validated enclosure path exists.
• mode="auto" chooses certified mode when certify=True, otherwise fast mode for dps <= 15 and high-precision mode for larger dps requests.

Fast mode is double precision. If you request more than 15 digits while forcing mode="fast", the result reports working_dps=16 and includes a diagnostic warning that the requested digits are not guaranteed.

Use mode="certified" when the error bound matters. Use high_precision when you need more digits but not a rigorous certificate.

The dispatcher uses an explicit MethodSpec registry for every concrete mode. Each registered method records its backend, callable, certification intent, domain note, and certificate scope. Callers may pass method=... for registered methods. For loggamma, explicit mode="certified", method="stirling" or method="stirling_shifted" selects an alpha-certified custom asymptotic bound for positive-real inputs with real x >= 20; neither method is automatic default selection. Explicit mode="certified", method="certified_auto" is a selector only: it may choose direct Arb or a positive-real Stirling method, but it does not change omitted-method or method="auto" dispatch. Adding a public wrapper requires registering its SciPy, mpmath, and Arb methods together; tests verify the registry, public API, and MCP tool list stay in sync. For gamma, explicit mode="certified", method="stirling_exp" selects an alpha-certified positive-real method for finite real x >= 20 by exponentiating a certified positive-real loggamma enclosure. It is explicit only and does not change default certified gamma. For rgamma, explicit mode="certified", method="stirling_recip" selects an alpha-certified positive-real method for finite real x >= 20 by exponentiating the negated certified positive-real loggamma enclosure. It is explicit only and does not change default certified rgamma.

Supported Functions

The 0.3 development line keeps the 0.2 public wrapper surface and adds explicit custom certified asymptotic methods for loggamma, positive-real gamma, and positive-real rgamma. Default certified loggamma, default certified gamma, and default certified rgamma still use direct Arb. The package remains alpha-quality in scientific scope.

Area	Release status
gamma, loggamma, rgamma, gamma_ratio, loggamma_ratio, beta, pochhammer	alpha-certified, direct Arb gamma primitives and finite products
erf, erfc, erfcx, erfi, dawson, erfinv, erfcinv	alpha-certified, direct Arb error-function primitives plus erfcx, erfi, and dawson identity formulas; real erfinv on (-1, 1); real erfcinv on (0, 2)
airy, ai, bi	alpha-certified, direct Arb primitive
besselj, bessely, besseli, besselk	alpha-certified where direct Arb primitive works; real-valued order only
pcfd, pcfu, pcfv, pcfw, pbdv	experimental certified formula layer
MCP server	experimental tool interface
Custom Taylor/asymptotic methods	alpha-certified custom asymptotic bound for positive-real loggamma via explicit method="stirling" or method="stirling_shifted"; explicit method="certified_auto" may select those methods or direct Arb; active explicit positive-real gamma method method="stirling_exp" via certified loggamma exponentiation; active explicit positive-real rgamma method method="stirling_recip" via certified loggamma exponentiation; real x >= 20 for custom methods; not automatic default selection

from certsf import (
    beta,
    gamma,
    loggamma,
    loggamma_ratio,
    pochhammer,
    dawson,
    erfinv,
    erfcinv,
    erf,
    erfc,
    erfcx,
    erfi,
    rgamma,
    gamma_ratio,
    airy,
    ai,
    bi,
    besselj,
    bessely,
    besseli,
    besselk,
    pbdv,
    pcfd,
    pcfu,
    pcfv,
    pcfw,
)

Gamma Family

• gamma(z)
• loggamma(z), using the principal branch
• rgamma(z) = 1 / gamma(z)
• gamma_ratio(a, b) = Gamma(a) / Gamma(b)
• loggamma_ratio(a, b) = loggamma(a) - loggamma(b), using the principal loggamma branch
• beta(a, b) = Gamma(a) Gamma(b) / Gamma(a+b)
• pochhammer(a, n) = (a)_n = Gamma(a+n) / Gamma(a)

rgamma is the safest wrapper near non-positive integer gamma poles. In certified mode, rgamma returns a rigorous zero at poles, while gamma and loggamma return clean non-certified failures when the requested value is not finite.

from certsf import gamma_ratio

r = gamma_ratio("3.2", "1.2", mode="certified", dps=50)
print(r.value)
print(r.certified)
print(r.diagnostics)

Certified gamma_ratio(a, b) evaluates Gamma(a) * rgamma(b). This lets denominator poles certify to exact zero when Gamma(a) is finite, while numerator poles and simultaneous numerator/denominator poles return clean non-certified failures with pole diagnostics. See docs/gamma_ratio.md.

from certsf import loggamma_ratio

r = loggamma_ratio("3.2", "1.2", mode="certified", dps=50)
print(r.value)
print(r.certified)
print(r.diagnostics)

Certified loggamma_ratio(a, b) evaluates Arb lgamma(a) - lgamma(b) with certificate_scope="direct_arb_loggamma_ratio". Any gamma pole in either argument returns a clean non-certified failure. For complex values, the result is the difference of principal loggamma values, not necessarily the principal logarithm of gamma_ratio(a, b). See docs/loggamma_ratio.md.

Explicit loggamma(x, mode="certified", method="stirling") evaluates the positive-real Stirling expansion with Arb ball arithmetic for the finite sum and an explicit first-omitted-term tail bound. Explicit method="stirling_shifted" evaluates the same positive-real target after an Arb recurrence shift loggamma(x)=loggamma(x+r)-sum(log(x+j)), using a documented shift policy and the same tail-bound theorem at the shifted argument. These custom methods are limited to real x >= 20, record certificate_scope="stirling_loggamma_positive_real", and return method="stirling_loggamma" or method="stirling_shifted_loggamma". They do not certify complex loggamma branches, real x < 20, x <= 0, or gamma-ratio asymptotics, and they are not selected by default. See docs/stirling_loggamma.md.

Explicit method="certified_auto" in certified mode is a conservative selector for existing loggamma methods. Outside the positive-real Stirling scope it uses direct Arb; for real x >= 20 it may select unshifted or shifted Stirling only when that method certifies its documented tail bound. It is not used for method=None or method="auto", and it does not add complex Stirling, gamma-ratio asymptotics, or beta asymptotics.

Explicit gamma(x, mode="certified", method="stirling_exp") evaluates positive-real gamma for finite real x >= 20 by exponentiating a certified positive-real loggamma Arb enclosure. It records certificate_scope="gamma_positive_real_stirling_exp" and returns method="stirling_exp_gamma". It does not certify complex gamma, reflection-formula paths, near-pole behavior, gamma-ratio asymptotics, or beta asymptotics, and it is not selected by default. See docs/gamma_stirling_exp.md and the 0.3 custom-method audit in docs/v0_3_custom_method_audit.md.

Explicit rgamma(x, mode="certified", method="stirling_recip") evaluates positive-real reciprocal gamma for finite real x >= 20 by exponentiating the negated certified positive-real loggamma Arb enclosure. It records certificate_scope="rgamma_positive_real_stirling_recip" and returns method="stirling_recip_rgamma". It does not certify complex rgamma, reflection-formula paths, near-pole behavior, gamma-ratio asymptotics, or beta asymptotics, and it is not selected by default. See docs/rgamma_stirling_recip.md and the 0.3 custom-method audit in docs/v0_3_custom_method_audit.md.

from certsf import beta

r = beta("2", "3", mode="certified", dps=50)
print(r.value)
print(r.certified)
print(r.diagnostics)

Certified beta(a, b) evaluates Gamma(a) * Gamma(b) * rgamma(a+b) with certificate_scope="direct_arb_beta". Poles in Gamma(a) or Gamma(b) return clean non-certified failures. A pole in Gamma(a+b) certifies to zero only when both numerator gamma factors are finite and Arb returns the zero product. The wrapper does not claim limiting values at simultaneous singularities. See docs/beta.md.

from certsf import pochhammer

r = pochhammer("0.5", "3", mode="certified", dps=50)
print(r.value)
print(r.certified)
print(r.diagnostics)

Certified pochhammer(a, n) evaluates the finite product product_{k=0}^{n-1} (a+k) with Arb ball arithmetic for integer n >= 0. n = 0 certifies to 1, exact zero factors certify to zero, and non-integer or negative n returns a clean non-certified failure. The wrapper does not claim analytic continuation in n or simultaneous-pole limiting values. See docs/pochhammer.md.

Error Functions

• erf(z) = 2/sqrt(pi) * integral_0^z exp(-t^2) dt
• erfc(z) = 1 - erf(z)
• erfcx(z) = exp(z^2) erfc(z)
• erfi(z) = -i erf(i z)
• dawson(z) = sqrt(pi)/2 * exp(-z^2) * erfi(z)
• erfinv(x), the real principal inverse satisfying erf(erfinv(x)) = x for -1 < x < 1
• erfcinv(x), the real principal inverse satisfying erfc(erfcinv(x)) = x for 0 < x < 2

from certsf import dawson, erf, erfc, erfcinv, erfcx, erfi, erfinv

r = erf("1.0", mode="certified", dps=50)
c = erfc("1.0", mode="certified", dps=50)
x = erfcx("1.0", mode="certified", dps=50)
i = erfi("1.0", mode="certified", dps=50)
d = dawson("1.0", mode="certified", dps=50)
v = erfinv("0.5", mode="certified", dps=50)
w = erfcinv("0.5", mode="certified", dps=50)

from certsf import dawson

r = dawson("1.0", mode="certified", dps=50)

from certsf import erfi

r = erfi("1.0", mode="certified", dps=50)

from certsf import erfinv

r = erfinv("0.5", mode="certified", dps=50)

from certsf import erfcinv

r = erfcinv("0.5", mode="certified", dps=50)

Certified erf, erfc, and erfi use direct Arb error-function primitives for real or complex inputs when Arb returns finite enclosures. If a supported python-flint build lacks direct erfc but exposes direct erf, certified erfc may evaluate 1 - erf(z) and records formula="1-erf". Certified erfcx prefers direct Arb erfcx when available; otherwise it uses the Arb identity formula exp(z^2)*erfc(z) and records formula="exp(z^2)*erfc(z)". Certified erfi prefers direct Arb erfi when available; otherwise it uses the Arb identity formula -i*erf(i*z) and records formula="-i*erf(i*z)". Certified dawson prefers direct Arb dawson when available; otherwise it uses the Arb identity formula sqrt(pi)/2*exp(-z^2)*erfi(z) and records formula="sqrt(pi)/2*exp(-z^2)*erfi(z)". Certified erfinv is restricted to the real principal inverse on -1 < x < 1. It prefers direct Arb erfinv when available; otherwise it uses a certified monotone real-root enclosure for erf(y)-x=0 and records certificate_scope="arb_erfinv_real_root", certificate_level="certified_real_root", and audit_status="monotone_real_inverse". Certified mode rejects endpoints, out-of-interval values, and complex inputs as clean non-certified failures. Certified erfcinv is restricted to the real principal inverse on 0 < x < 2. It prefers direct Arb erfcinv when available; otherwise it uses the existing certified real-inverse path for erfinv(1-x) and records certificate_scope="arb_erfcinv_via_erfinv", certificate_level="certified_real_root", audit_status="monotone_real_inverse", and formula="erfinv(1-x)". Certified mode rejects endpoints, out-of-interval values, and complex inputs as clean non-certified failures. No custom asymptotic certification is added. See docs/error_function.md and docs/dawson.md, docs/erfinv.md, and docs/erfcinv.md.

Airy Family

• airy(z) returns Ai, Ai', Bi, and Bi' in one JSON payload.
• ai(z, derivative=0) and ai(z, derivative=1).
• bi(z, derivative=0) and bi(z, derivative=1).
• airyai and airybi remain public aliases for ai and bi.

Certified Airy wrappers use Arb ball arithmetic and report component-level absolute and relative error bounds.

Bessel Family

• besselj(v, z) for (J_v(z))
• bessely(v, z) for (Y_v(z))
• besseli(v, z) for (I_v(z))
• besselk(v, z) for (K_v(z))

Certified Bessel wrappers support real-valued order and real or complex arguments. Complex order is outside the certified scope and returns a clean non-certified failure.

Parabolic-Cylinder Family

• pbdv(v, x) returns (D_v(x)) and (D_v'(x)) in one JSON payload.
• pcfd(v, z) returns (D_v(z)).
• pcfu(a, z) returns (U(a,z)).
• pcfv(a, z) returns (V(a,z)).
• pcfw(a, x) returns (W(a,x)).

Certified pcfu, pcfd, pbdv, and pcfv support real parameters and real or complex arguments. Certified pcfw currently supports real parameters and real arguments; complex arguments return a clean non-certified failure until a validated complex-domain target is selected.

For pbdv, the argument name x follows SciPy's real-variable naming, but the certified formula layer intentionally accepts complex arguments for the D_v(x) value and derivative pair. Use pcfd(v, z) when only the complex D_v(z) value is needed.

The parabolic-cylinder family is an experimental certified formula layer: Arb encloses the implemented documented formula, while formula/domain audit remains visible before broadening the claim.

Multi-Component Values

Functions such as airy and pbdv keep backward-compatible JSON strings in SFResult.value, and provide helpers for Python callers:

from certsf import pbdv

result = pbdv("2.5", "1.25", dps=60, mode="certified")
values = result.value_as_dict()
bounds = result.abs_error_bound_as_dict()

print(values["value"])
print(values["derivative"])
print(bounds["value"])
print(bounds["derivative"])
print(result.component("value"))

MCP Wrapper

certsf.mcp_server exposes thin MCP-facing wrappers around the same public API. MCP payloads decode multi-component values and bounds as nested JSON objects instead of JSON-encoded strings. Install the optional MCP dependency before running the server:

python -m pip install -e ".[mcp,certified]"
python -m certsf.mcp_server

Development

Run the test suite with:

python -m pytest

The tests exercise the SciPy, mpmath, and Arb-backed paths when the optional dependencies are installed.

The repository also includes:

• docs/release_checklist.md for prerelease/release verification.
• docs/release_claims.md for conservative alpha release claim wording.
• docs/certification_audit.md for scope-level certification evidence and remaining audit gates.
• docs/v0_3_custom_method_audit.md for the explicit 0.3 custom-method audit covering loggamma Stirling methods, certified_auto, and gamma(method="stirling_exp") and rgamma(method="stirling_recip").
• docs/audit/ for family-level certification checklists.
• docs/gamma_ratio.md for gamma-ratio pole policy and certified-backend rationale.
• docs/loggamma_ratio.md for loggamma-ratio branch convention and pole policy.
• docs/beta.md for beta-function pole policy and certified-backend rationale.
• docs/pochhammer.md for Pochhammer/rising-factorial certified-domain policy.
• docs/stirling_loggamma.md for the explicit positive-real Stirling loggamma method.
• docs/gamma_stirling_exp.md for the explicit positive-real gamma method via certified loggamma exponentiation.
• docs/rgamma_stirling_recip.md for the explicit positive-real rgamma method via certified loggamma exponentiation.
• docs/loggamma_certified_auto_decision.md for decision-support and evidence-gathering notes on whether explicit method="certified_auto" should later become the default certified loggamma selector.
• docs/error_function.md for error-function certified-domain policy.
• docs/dawson.md for Dawson integral certified-domain policy.
• docs/erfinv.md for inverse-error-function certified-domain policy.
• docs/erfcinv.md for inverse-complementary-error-function certified-domain policy.
• docs/certified_scope_0_3_0.md for the active 0.3.0 development scope.
• docs/certified_scope_0_2_0.md for the published 0.2.0 certified support matrix.
• docs/v0.3.0_final_readiness_audit.md for the v0.3.0 final-readiness audit and final-release sequence.
• docs/release-0.3.0.md for v0.3.0 final release planning notes.
• docs/release-0.3.0-alpha.5.md for v0.3.0-alpha.5 release planning, which packages only the explicit positive-real rgamma method="stirling_recip" while keeping default dispatch unchanged.
• docs/release-0.3.0-alpha.4.md for v0.3.0-alpha.4 release planning, which packages only the explicit positive-real gamma method="stirling_exp" while keeping default dispatch unchanged.
• docs/release-0.3.0-alpha.3.md for v0.3.0-alpha.3 release planning, which packages only the explicit certified_auto preselection optimization while keeping method="certified_auto" explicit and leaving default dispatch unchanged.
• docs/release-0.3.0-alpha.2.md for v0.3.0-alpha.2 release planning.
• docs/release-0.3.0-alpha.1.md for v0.3.0-alpha.1 release planning.
• docs/release-0.2.0.md for v0.2.0 final release planning notes.
• docs/certified_scope_0_1_0.md for the frozen 0.1.0 certified support matrix.
• docs/release-0.2.0-alpha.10.md for v0.2.0-alpha.10 feature-alpha planning notes.
• docs/release-0.2.0-alpha.9.md for v0.2.0-alpha.9 feature-alpha planning notes.
• docs/release-0.2.0-alpha.8.md for v0.2.0-alpha.8 feature-alpha planning notes.
• docs/release-0.2.0-alpha.7.md for v0.2.0-alpha.7 feature-alpha planning notes.
• docs/release-0.2.0-alpha.6.md for v0.2.0-alpha.6 feature-alpha planning notes.
• docs/release-0.2.0-alpha.5.md for v0.2.0-alpha.5 feature-alpha planning notes.
• docs/release-0.2.0-alpha.4.md for v0.2.0-alpha.4 feature-alpha planning notes.
• docs/release-0.2.0-alpha.3.md for v0.2.0-alpha.3 feature-alpha planning notes.
• docs/release-0.2.0-alpha.2.md for v0.2.0-alpha.2 feature-alpha planning notes.
• docs/release-0.2.0-alpha.1.md for v0.2.0-alpha.1 feature-alpha planning notes.
• docs/release-0.1.0.md for conservative 0.1.0 release notes and example commands.
• docs/release-0.1.0-alpha.2.md for the v0.1.0-alpha.2 planning notes.
• examples/basic_usage.py for a short end-to-end usage example.
• examples/certified_vs_high_precision.py for a compact comparison of high-precision and certified result diagnostics.
• examples/gamma_certified.py, examples/airy_components.py, examples/bessel_complex.py, examples/pcf_experimental.py, and examples/mcp_payload.py for payload-first release examples.
• benchmarks/bench_gamma.py, benchmarks/bench_gamma_methods.py, benchmarks/bench_rgamma_methods.py, benchmarks/bench_loggamma_methods.py, benchmarks/analyze_loggamma_auto.py, benchmarks/summarize_loggamma_auto.py, benchmarks/bench_airy.py, benchmarks/bench_bessel.py, and benchmarks/bench_pcf.py for lightweight JSON-lines timing smoke benchmarks. The gamma/rgamma/loggamma custom-method benchmarks compare direct Arb, explicit custom methods, high-precision mpmath, and fast SciPy paths without making a default-method performance claim. The explicit certified-auto selector uses preselection diagnostics to avoid unnecessary custom candidate evaluations, but it remains decision support only; method="certified_auto" remains explicit and no default-dispatch change is made. Direct Arb remains the default certified gamma, rgamma, and loggamma path. A compact loggamma sample summary is checked in at docs/benchmark_samples/loggamma_certified_auto_sample_summary.json.