ppapp 1.0.0__py3-none-any.whl

ppapp/__init__.py

@@ -0,0 +1,58 @@
+"""
+ppapp - Piecewise Polynomial Approximation
+
+Code generator for piecewise Chebyshev approximation of mathematical functions.
+
+Reference: Joachim Wuttke and Alexander Kleinsorge,
+           "Algorithm 1XXX: Code generation for piecewise Chebyshev approximation"
+
+License:   GNU General Public License, version 3 or higher
+Copyright: Forschungszentrum Jülich GmbH 2025
+"""
+
+from ppapp.ppapp import (
+    Subdomain,
+    analyse_row,
+    compute_subdomains,
+    error_bound,
+    hexfloat,
+    n_output_coeffs,
+)
+from ppapp.cheb_coeffs import (
+    cheb_cn,
+    cheb_pm,
+    check_coeffs,
+    ref_f,
+    set_reference_function,
+)
+
+__version__ = "0.1.0"
+
+
+def get_docs_path() -> str:
+    """Return path to the documentation directory."""
+    from importlib.resources import files
+    return str(files("ppapp") / "docs")
+
+
+def get_user_manual_path() -> str:
+    """Return path to the user manual PDF."""
+    from importlib.resources import files
+    return str(files("ppapp") / "docs" / "userManual.pdf")
+
+
+__all__ = [
+    "cheb_cn",
+    "cheb_pm",
+    "ref_f",
+    "check_coeffs",
+    "set_reference_function",
+    "Subdomain",
+    "analyse_row",
+    "error_bound",
+    "compute_subdomains",
+    "hexfloat",
+    "n_output_coeffs",
+    "get_docs_path",
+    "get_user_manual_path",
+]

ppapp/__main__.py

@@ -0,0 +1,6 @@
+"""Entry point for running ppapp as a module: python -m ppapp"""
+
+from ppapp.ppapp import main
+
+if __name__ == "__main__":
+    exit(main())

ppapp/cheb_coeffs.py

@@ -0,0 +1,231 @@
+"""
+Code generating code for piecewise Chebyshev approximation
+
+Reference: Joachim Wuttke and Alexander Kleinsorge,
+           Algorithm 1XXX: Code generation for piecewise Chebyshev approximation
+
+File:      ppapp/cheb_coeffs.py
+
+License:   GNU General Public License, version 3 or higher (see LICENSE)
+Copyright: Forschungszentrum Jülich GmbH 2025
+Author:    Joachim Wuttke <j.wuttke@fz-juelich.de>
+"""
+
+from math import isfinite
+from typing import Callable, Optional
+
+from flint import arb, ctx
+
+
+def str_arb(A: arb) -> str:
+    """Convert arbitrary precision number to string representation."""
+    a: float = float(A)
+    return f"{a:10.5e}"
+
+
+def sizeT(N: int) -> int:
+    """Returns total number of coefficients T_nm with n<=N.
+    For N = -2,-1,0,1,..., result is 0,0,1,2,4,6,9,12,16,20,... (OEIS A002620)."""
+    assert N >= -2
+    return ((N + 2) // 2) * ((N + 1) // 2 + 1)
+
+
+def precompute_Tnm(N: int) -> list[int]:
+    """Returns flat list of nonzero coefficients T_nm with n<=N.
+    For N = 0,1,..., result is 1,1,-1,2,-3,4,1,-8,8,5,-20,16,-1,18,-48,32,... (OEIS A008310)."""
+    assert N >= 0
+    if N == 0:
+        return [1]
+    if N == 1:
+        return [1, 1]
+    # The first two coefficients:
+    # R.append(1)
+    # if N >= 1: R.append(1)
+    R = [1, 1]
+    # Remaining coefficients by recursion:
+    for n in range(2, N + 1):
+        if n % 2 == 0:
+            R.append(-R[sizeT(n - 3)])
+        for j in range((n + 1) & 1, n // 2):
+            R.append(2 * R[sizeT(n - 2) + j - ((n + 1) & 1)] - R[sizeT(n - 3) + j])
+        R.append(2 * R[sizeT(n - 2) + (n - 1) // 2])
+    assert len(R) == sizeT(N)
+    assert R[-1] == (1 << (0 if N == 0 else N - 1))  # T_nn is 2^{n-1}; will fail if there is overflow
+    return R
+
+
+def cheb_cn_arb(a: float, b: float, N: int, prec: int) -> list[arb]:
+    """Returns the Chebyshev coefficients c_n as vector of arbitrary-precision numbers."""
+    assert my_arb_f is not None, "Reference function not set; call set_reference_function first"
+
+    # Set global precision
+    ctx.prec = prec
+
+    # Compute the c_n
+    M = arb((a + b) * 0.5)  # midpoint
+    H = arb((b - a) * 0.5)  # halfrange
+
+    assert N > 0  # otherwise division by 0; no obvious way to salvage the formalism
+    N_inv: float = 1.0 / N
+
+    CC = []
+    for n in range(N + 1):
+        sn = 1 if n == 0 else 2
+        C = arb(0)
+        for k in range(N + 1):  # increment c_n = sum_{k=0}^N sk f(xk) Tn((xk-a)/(b-a))
+            sk = 1 if (k == 0 or k == N) else 2
+            E = arb(k) * arb.pi() * N_inv  # E = k*pi/N
+            E = E.cos()  # E = xk = cos(k*pi/N) = Chebyshev extremal point
+            T = E.chebyshev_t(n)  # T = T_n(ek)
+            E = E * H
+            E = E + M  # E = midpoint + halfrange*xk
+            F = my_arb_f(E, prec)  # F = f(xk), here we evaluate the reference function
+            F = F * T  # F = f(xk) * T_n(ek)
+            C = C + sk * F  # increment C by sigma_k * f(xk) * T_n(ek)
+
+        E = arb(sn * 0.5)
+        E = E * N_inv  # E = sigma_n/(2N)
+        C = C * E
+        CC.append(C)
+
+    return CC
+
+
+# Module-level cache for precomputed T_nm coefficients
+_cached_Tnm: list[int] = []
+
+
+def cheb_pm_prec(a: float, b: float, N: int, prec: int) -> list[float]:
+    """Returns monomial coefficents p_m for m=0,..,N, computed with precision prec."""
+    global _cached_Tnm
+
+    # Recompute T_nm if needed for larger N
+    if len(_cached_Tnm) < sizeT(N):
+        _cached_Tnm = precompute_Tnm(N)
+
+    Tnm = _cached_Tnm
+
+    CC = cheb_cn_arb(a, b, N, prec)
+
+    # Compute the p_m
+    # ctx.prec is already set by cheb_cn_arb
+    result: list[float] = []
+    p0: Optional[float] = None  # Store first coefficient for comparison
+    eps = 2.0 ** -53  # Machine epsilon for double precision
+    for m in range(N + 1):  # compute p_m
+        P = arb(0)
+        for n in range(m, N + 1, 2):  # increment p_m = sum_{n=0}^m c_n T_{nm}
+            t = Tnm[sizeT(n - 1) + (m - n % 2) // 2]
+            P = P + t * CC[n]  # increment p_m by t*C
+
+        p: float = float(P.mid())
+        if not isfinite(p):
+            raise RuntimeError("Invalid coefficient p_m, not a number or infinite")
+        dp = float(P.rad())
+        if m == 0:
+            if p == 0:  # p_0 must be nonzero
+                raise RuntimeError("Unexpected coefficient value 0 for p_0")
+            p0 = abs(p)
+        # Accept coefficient if either:
+        # 1. Relative precision is good (dp/|p| <= 1e-18), or
+        # 2. Coefficient is negligible (|p| <= |p_0| * eps, i.e., below machine precision)
+        assert p0 is not None  # p0 is set on first iteration (m == 0)
+        if abs(dp / p) > 1e-18 if p != 0 else True:
+            if abs(p) > p0 * eps:  # Significant coefficient with poor precision
+                result = []
+                break
+        result.append(p)
+        # import sys
+        # print(f"p_{m}={p}", file=sys.stderr)
+
+    return result
+
+
+def ref_f(x: float) -> float:
+    """Returns f(x), computed to relative precision 1e-18."""
+    assert my_arb_f is not None, "Reference function not set; call set_reference_function first"
+
+    for prec in range(77, 170, 9):
+        ctx.prec = prec
+        X = arb(x)
+        F = my_arb_f(X, prec)
+        y = float(F.mid())
+        dy = float(F.rad())
+        if y == 0:
+            raise RuntimeError("Unexpected function value 0")
+        if abs(dy / y) < 1e-18:
+            return y
+
+    raise RuntimeError("Reference function did not achieve accuracy 1e-18")
+
+
+def check_coeffs(a: float, b: float, P: list[float], tin: float, relerr: float) -> None:
+    """Checks whether economized coefficients reproduce reference function within a few epsilon."""
+    from sys import stderr
+    x: float = (b + a) * 0.5 + (b - a) * 0.5 * tin
+    t: float = (x - (a + b) * 0.5) / ((b - a) * 0.5)  # convert back to suppress irrelevant conversion error from t->x
+    fnew = P[-1]
+    for c in reversed(P[:-1]):
+        fnew = fnew * t + c
+
+    fref = ref_f(x)
+    if abs((fnew - fref) / fref) > relerr * (2.0 ** -53):  # epsilon = 2^-53
+        print(f"t={t} x={x} => relerr={abs((fnew - fref) / fref)}:", file=stderr)
+        f3 = 0.0
+
+        for m in range(len(P)):
+            tm = t ** m
+            f3 += P[m] * tm
+            print(f"m={m:2d} t^m={tm:8.2g} P[m]={P[m]:8.2g} term={tm * P[m]:8.2g} sum={f3:22.16e}", file=stderr)
+
+        print(f"                                              hor={fnew:22.16e}", file=stderr)
+        print(f"                                              ref={fref:22.16e}", file=stderr)
+        raise RuntimeError("Approximation not accurate enough")
+
+
+def cheb_cn(a: float, b: float, N: int) -> list[float]:
+    """Returns polynomial coefficents c_n for m=0,..,N,
+    such that the reference function f is approximated by sum_{n=0}^N c_n T_n((x-a)/(b-a)).
+    Full double-precision accuracy is ensured by running the arbitrary-precision computation
+    in function cheb_cn_arb with different precisions."""
+    # Compute with increasing precision until results agree.
+    for prec in range(72, 400, 32):
+        CC = cheb_cn_arb(a, b, N, prec)
+        result: list[float] = []
+        for C in CC:
+            c = float(C.mid())
+            if not isfinite(c):
+                raise RuntimeError("Invalid coefficient c_n, not a number or infinite")
+            dc = float(C.rad())
+            if abs(dc / c) > 1e-18:
+                result = []
+                break
+            result.append(c)
+        if result:
+            return result
+
+    raise RuntimeError("Loop in precision did not converge")
+
+
+def cheb_pm(a: float, b: float, N: int) -> list[float]:
+    """Returns polynomial coefficents p_m for m=0,..,N,
+    such that the reference function f is approximated by sum_{m=0}^N p_m ((x-a)/(b-a))^m.
+    Full double-precision accuracy is ensured by running the arbitrary-precision computation
+    in function cheb_coeffs_prec with different precisions."""
+    # Compute with increasing precision until results agree.
+    for prec in range(72, 800, 32):
+        result = cheb_pm_prec(a, b, N, prec)
+        if result:
+            return result
+
+    raise RuntimeError("Loop in precision did not converge")
+
+
+# The reference function my_arb_f will be set dynamically by the calling code
+my_arb_f: Optional[Callable[[arb, int], arb]] = None
+
+
+def set_reference_function(arb_f_func: Callable[[arb, int], arb]) -> None:
+    """Set the reference function to use for coefficient computation."""
+    global my_arb_f
+    my_arb_f = arb_f_func

ppapp/demo_functions/__init__.py

@@ -0,0 +1,20 @@
+"""
+Demo functions for ppapp.
+
+These modules demonstrate how to define target functions for the
+piecewise Chebyshev approximation generator. Each module defines:
+
+- my_arb_f(X: arb, prec: int) -> arb: The function to approximate
+- my_domain: Tuple[float, float]: The domain [a, b)
+- my_testcases: List of (x, f_expected, tolerance) tuples
+
+Available demo functions:
+- imwofx: Im w(x) = exp(-x^2) * erfi(x)
+- erfcx: erfcx(x) = exp(x^2) * erfc(x)
+- polynomial: f(x) = x^3 - x^2 + x - 1
+- voigt_hwhm: Voigt half-width at half-maximum
+"""
+
+from ppapp.demo_functions import erfcx, imwofx, polynomial, voigt_hwhm
+
+__all__ = ["imwofx", "erfcx", "polynomial", "voigt_hwhm"]

ppapp/demo_functions/erfcx.py

@@ -0,0 +1,47 @@
+#!/usr/bin/env python3
+
+"""
+Code generating code for piecewise Chebyshev approximation
+
+Reference: Joachim Wuttke and Alexander Kleinsorge,
+           Algorithm 1XXX: Code generation for piecewise Chebyshev approximation
+
+File:      ppapp/demo_functions/erfcx.py
+
+Arbitrary-precision implementation of function erfcx(x).
+
+License:   GNU General Public License, version 3 or higher (see src/LICENSE)
+Copyright: Forschungszentrum Jülich GmbH 2025
+Author:    Joachim Wuttke <j.wuttke@fz-juelich.de>
+"""
+
+
+from flint import arb
+
+# The total intermediate domain [a,b) to be covered by piecewise polynomial approximation:
+my_domain: tuple[float, float] = (0.125, 12.0)
+
+
+def my_arb_f(X: arb, prec: int) -> arb:
+    """
+    Evaluates the overflow-compensated complementary error function
+      f(x) = erfcx(x) = exp(x^2) * erfc(x),
+    using 'prec' binary digits.
+
+    Args:
+        X: Input value as arbitrary precision number
+        prec: Precision in binary digits
+
+    Returns:
+        F = f(X) with given precision
+    """
+    return X.erfc() * (X ** 2).exp()
+
+
+# A few test cases, just to secure against gross errors.
+# Each entry is (x, f_expected(x), tolerance)
+my_testcases: list[tuple[float, float, float]] = [
+    (0.2, 0.8090195, 1e-5),
+    (1.0, 0.4275836, 1e-5),
+    (12.0, 0.046854221, 1e-5),
+]

ppapp/demo_functions/imwofx.py

@@ -0,0 +1,47 @@
+#!/usr/bin/env python3
+
+"""
+Code generating code for piecewise Chebyshev approximation
+
+Reference: Joachim Wuttke and Alexander Kleinsorge,
+           Algorithm 1XXX: Code generation for piecewise Chebyshev approximation
+
+File:      ppapp/demo_functions/imwofx.py
+
+Arbitrary-precision implementation of function Im w(x).
+
+License:   GNU General Public License, version 3 or higher (see src/LICENSE)
+Copyright: Forschungszentrum Jülich GmbH 2025
+Author:    Joachim Wuttke <j.wuttke@fz-juelich.de>
+"""
+
+
+from flint import arb
+
+# The total intermediate domain [a,b) to be covered by piecewise polynomial approximation:
+my_domain: tuple[float, float] = (0.5, 12.0)
+
+
+def my_arb_f(X: arb, prec: int) -> arb:
+    """
+    Evaluates the overflow-compensated imaginary error function
+      f(x) = exp(-x^2) * erfi(x) = Im w(x),
+    using 'prec' binary digits.
+
+    Args:
+        X: Input value as arbitrary precision number
+        prec: Precision in binary digits
+
+    Returns:
+        F = f(X) with given precision
+    """
+    return X.erfi() * (-(X ** 2)).exp()
+
+
+# A few test cases, just to secure against gross errors.
+# Each entry is (x, f_expected(x), tolerance)
+my_testcases: list[tuple[float, float, float]] = [
+    (0.5, 0.478925, 1e-5),
+    (1.0, 0.607158, 1e-5),
+    (12.0, 0.0471808, 1e-5),
+]

ppapp/demo_functions/polynomial.py

@@ -0,0 +1,51 @@
+#!/usr/bin/env python3
+
+"""
+Code generating code for piecewise Chebyshev approximation
+
+Reference: Joachim Wuttke and Alexander Kleinsorge,
+           Algorithm 1XXX: Code generation for piecewise Chebyshev approximation
+
+File:      ppapp/demo_functions/polynomial.py
+
+Arbitrary-precision implementation of polynomial f(x) = x^3 - x^2 + x - 1.
+
+License:   GNU General Public License, version 3 or higher (see src/LICENSE)
+Copyright: Forschungszentrum Jülich GmbH 2025
+Author:    Joachim Wuttke <j.wuttke@fz-juelich.de>
+"""
+
+
+from flint import arb
+
+# The total intermediate domain [a,b) to be covered by piecewise polynomial approximation:
+# Avoid x=1 where f(x)=0 (would cause division by zero in relative error checks)
+my_domain: tuple[float, float] = (1.5, 4.0)
+
+
+def my_arb_f(X: arb, prec: int) -> arb:
+    """
+    Evaluates the polynomial
+      f(x) = x^3 - x^2 + x - 1 = (x-1)(x^2+1),
+    using 'prec' binary digits.
+
+    Args:
+        X: Input value as arbitrary precision number
+        prec: Precision in binary digits
+
+    Returns:
+        F = f(X) with given precision
+    """
+    # Compute x^3 - x^2 + x - 1
+    X2 = X ** 2
+    X3 = X2 * X
+    return X3 - X2 + X - 1
+
+
+# A few test cases, just to secure against gross errors.
+# Each entry is (x, f_expected(x), tolerance)
+my_testcases: list[tuple[float, float, float]] = [
+    (1.5, 1.625, 1e-10),    # 3.375 - 2.25 + 1.5 - 1 = 1.625
+    (2.0, 5.0, 1e-10),      # 8 - 4 + 2 - 1 = 5
+    (3.0, 20.0, 1e-10),     # 27 - 9 + 3 - 1 = 20
+]

ppapp/demo_functions/voigt_hwhm.py

@@ -0,0 +1,139 @@
+#!/usr/bin/env python3
+
+"""
+Code generating code for piecewise Chebyshev approximation
+
+Reference: Joachim Wuttke and Alexander Kleinsorge,
+           Algorithm 1XXX: Code generation for piecewise Chebyshev approximation
+
+File:      ppapp/demo_functions/voigt_hwhm.py
+
+Arbitrary-precision implementation of the half width at half maximum of the Voigt function.
+
+License:   GNU General Public License, version 3 or higher (see src/LICENSE)
+Copyright: Forschungszentrum Jülich GmbH 2025
+Authors:   Eva Mukherjee, Joachim Wuttke <j.wuttke@fz-juelich.de>
+"""
+
+import sys
+
+from flint import acb, arb, ctx
+
+
+def acb_faddeeva_w(z: acb, prec: int) -> acb:
+    """
+    Computes the Faddeeva function w(z).
+
+    Args:
+        z: Complex input as arbitrary precision complex number
+        prec: Precision in binary digits
+
+    Returns:
+        w(z) = exp(-z^2) * erfc(-i*z)
+    """
+    ctx.prec = prec
+
+    minus_iz = acb(z.imag, -z.real)
+    return (-(z * z)).exp() * minus_iz.erfc()
+
+
+def my_arb_voigt(q: arb, sigma: arb, gamma: arb, prec: int) -> arb:
+    """
+    Computes the Voigt function V(q; sigma, gamma).
+
+    Args:
+        q: Position parameter
+        sigma: Gaussian width parameter
+        gamma: Lorentzian width parameter
+        prec: Precision in binary digits
+
+    Returns:
+        V(q; sigma, gamma)
+    """
+    ctx.prec = prec
+
+    # Calculating the complex argument z = q / (sqrt(2) * sigma) + i * gamma / (sqrt(2) * sigma)
+    T2 = arb(0.5).sqrt() / sigma
+    z_complex_arg = acb(q * T2, gamma * T2) # (q+i*gamma) / (sqrt(2)*sigma)
+
+    # Faddeeva function
+    w_z_result = acb_faddeeva_w(z_complex_arg, prec)
+    T1 = w_z_result.real
+
+    # Calculating 1 / (sqrt(2*pi)*sigma)
+    T2 = T2 / arb.pi().sqrt()
+
+    # Computing the Voigt Function
+    return T2 * T1
+
+
+def my_arb_f(X: arb, prec: int) -> arb:
+    """
+    Computes the half width at half maximum (HWHM) of the Voigt function
+    as a function of the ratio sigma/gamma.
+
+    Args:
+        X: Input value representing sigma/gamma ratio
+        prec: Precision in binary digits
+
+    Returns:
+        HWHM for the given sigma/gamma ratio
+    """
+    ctx.prec = prec
+
+    # The input 'X' represents the ratio sigma/gamma.
+    gamma = arb(1.0)
+    sigma = X * gamma  # sigma = (sigma/gamma) * gamma = X * 1
+
+    # Calculating V(0; sigma, gamma)
+    V_zero = my_arb_voigt(arb(0.0), sigma, gamma, prec)
+
+    # Calculating the target value: 0.5 * V(0; sigma, gamma)
+    target_V = V_zero / 2
+
+    # Bisection Method
+    # Finding the root of the function f(q) = V(q; sigma, gamma) - target value
+    a = arb(0.0)
+    b = arb(1.0)
+
+    # Finding b such that V(b) < target_V
+    for _ in range(10):
+        val_c = my_arb_voigt(b, sigma, gamma, prec)
+        if val_c < target_V:
+            break
+        b *= 2
+
+    # Bisection loop
+    max_iter = 2 * prec
+    tol = arb(2.0) ** (-prec)
+
+    for _ in range(max_iter):
+        diff = b - a
+        if diff <= tol:
+            break
+        c = (a + b) / 2
+        val_c = my_arb_voigt(c, sigma, gamma, prec)
+        if val_c > target_V:
+            a = c  # V(c) too high => mid is too small
+        else:
+            b = c  # V(c) too low => mid is too large
+
+    # Check convergence
+    diff = b - a
+    if diff > tol:
+        print(f"Warning: bisection may not have converged for X={float(X)}", file=sys.stderr)
+
+    # The result is the HWHM which is midpoint of [a, b]
+    return (a + b) / 2
+
+
+# The total domain [a,b) to be covered by piecewise polynomial approximation.
+my_domain: tuple[float, float] = (0.5, 12.0)
+
+# Test cases.
+# Each entry is (x, f_expected(x), tolerance)
+my_testcases: list[tuple[float, float, float]] = [
+    (1.0, 1.80057, 1e-5),
+    (2.0, 2.93434, 1e-5),
+    (0.5, 1.28521, 1e-5),
+]