ENH: Set up initial reference framework and add reference tables for scipy special test cases

.github/workflows/tests.yml

@@ -0,0 +1,21 @@
+name: xsref tests
+
+on: [ push, pull_request ]
+
+jobs:
+  xsref_tests:
+    name: xsref table consistency tests
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+
+      - name: Setup Python
+        uses: actions/setup-python@0b93645e9fea7318ecaed2b359559ac225c90a2b # v5.3.0
+        with:
+          python-version: '3.12'
+
+      - name: Install xsref and dependencies
+        run: pip install .[test]
+
+      - name: Run tests
+        run: pytest

README.md

@@ -1,2 +1,82 @@
 # xsref
-Test case generation for xsf special function library
+
+## Introduction and Installation
+
+This package is used to generate test cases for scalar kernels in the xsf
+special function library. Reference values are computed using
+[`mpmath`](https://mpmath.org/). Reference tables are stored in
+[parquet](https://parquet.apache.org/docs/file-format/) files within the
+`xref` repo itself at `xsref/tables/`. Since `xsref` relies on these parquet
+files being part of the repo itself, it should be installed using an inplace
+build
+
+```bash
+pip install -e .
+```
+
+from inside the top level directory of the `xsf` repo. Or
+
+```bash
+pip install -e .[test]
+```
+
+if one wants to install the test dependencies.
+
+## Reference tables
+
+Subdirectories under `xsref/tables` should correspond to conceptually related
+collections of test cases. Subdirectories under these subdirectories should
+correspond to special functions, and share a name with the corresponding `xsf`
+scalar kernel function name (not the SciPy ufunc name). For example
+`xsref/tables/scipy_special_tests` is for parquet files for all test cases
+that appeared in the `scipy.special` tests prior to the separation of scalar kernels
+into the separate [xsf](https://github.com/scipy/xsf) library.
+`xsref/tables/scipy_special_tests/cyl_bessel_i` contains parquet files containing
+reference test cases for the [modified Bessel function $I_v$](https://dlmf.nist.gov/10.25#E2)
+which corresponds to the SciPy ufunc
+[`iv`](https://docs.scipy.org/doc/scipy/reference/generated/scipy.special.iv.html).
+
+Within a directory like `xsref/tables/scipy_special_tests/cyl_bessel_i`, for
+each type overload, there will be a parquet file for inputs, such as `In_d_d-d.parquet`
+[^1]. The substring `d_d-d` says that this is for cases for the
+signature `double cyl_bessel_i(double, double)`. There will be a corresponding
+parquet file containing reference output values `Out_d_d-d.parquet`. For each
+tested platform there will be parquet files like `Err_d_d-d_gcc-linux-x86_x6.parquet`
+containing current extended relative error [^2] values for `xsf`'s implementation compared
+to the reference implementation. Rather than having some fixed tolerance
+standard, we track the current relative error at each snapshot of development history,
+and test that it is not made worse by some fixed multiple. The idea is to use just
+tests to drive continuous improvement, helping us identify cases where the scalar
+kernels could be improved.
+
+The hope is that the reference implementations be independent of the `xsf`
+implementations, relying on arbitrary precision calculations based on simple
+definitions. In this case, agreement between the `xsf` implementation and the
+reference implementation should make us reasonably confident that the `xsf`
+implementation is accurate. However, disagreement could occur either due to
+flaws in the `xsf` implementation, or flaws in the reference implementation.
+Such situations must be investigated on a case by case basis.
+
+There are functions and parameter regions where we do not yet have an
+arbitrary precision reference implementation. Currently there is a fallback to
+the SciPy implementations from just before the scalar kernels were split
+into the separate `xsf` library. The `Out` parquet files contain a boolean column,
+`"fallback"` which is True for cases where such a fallback was used. 
+
+## Testing
+
+The test suite uses `pytest` and can be run by invoking the `pytest` command
+in a shell from within the top level of the `xsref` repo. Currently the test
+suite only checks the consistency of the reference tables.
+
+--
+
+[^1]: For complex valued cases, it would be nice to be able to use NumPy typecodes
+      such as `In_d_D-D.parquet`, but this will not work on case insensitive file
+	  systems such as the default on MacOS. Instead of `D` we use `cd` for complex
+	  double and instead of `F` we use `cf` for complex float. The filename in
+	  question here would thus be `In_d_cd-cd.parquet`.
+
+[^2]: Extended relative error is a metric we've devised which given any two floating
+      point numbers (or complex floating point numbers), including exceptional values like
+	  `NaN`s, infinities, and zeros, will return a non-`NaN` result.

pyproject.toml

@@ -0,0 +1,24 @@
+[build-system]
+requires = ["setuptools", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "xsref"
+version = "0.0.0"
+license = {file = "LICENSE"}
+maintainers = [
+            {name = "xsf developers", email = "albert.steppi@gmail.com"}
+]
+requires-python = ">=3.11"
+dependencies = [
+	     "mpmath==1.3.0",
+	     "numpy",
+	     "packaging",
+	     "polars",
+	     "pyarrow",
+	     "scipy==1.15.1",
+]
+readme = "README.md"
+
+[project.optional-dependencies]
+test = ["pytest"]

pytest.ini

@@ -0,0 +1,180 @@
+[pytest]
+markers =
+    airy: mark a test as pertaining to airy.
+    airye: mark a test as pertaining to airye.
+    bdtr: mark a test as pertaining to bdtr.
+    bdtrc: mark a test as pertaining to bdtrc.
+    bdtri: mark a test as pertaining to bdtri.
+    bei: mark a test as pertaining to bei.
+    beip: mark a test as pertaining to beip.
+    ber: mark a test as pertaining to ber.
+    berp: mark a test as pertaining to berp.
+    besselpoly: mark a test as pertaining to besselpoly.
+    beta: mark a test as pertaining to beta.
+    betaln: mark a test as pertaining to betaln.
+    betainc: mark a test as pertaining to betainc.
+    betaincc: mark a test as pertaining to betaincc.
+    betaincinv: mark a test as pertaining to betaincinv.
+    betainccinv: mark a test as pertaining to betainccinv.
+    binom: mark a test as pertaining to binom.
+    cbrt: mark a test as pertaining to cbrt.
+    cem: mark a test as pertaining to cem.
+    cem_cva: mark a test as pertaining to cem_cva.
+    chdtr: mark a test as pertaining to chdtr.
+    chdtrc: mark a test as pertaining to chdtrc.
+    chdtri: mark a test as pertaining to chdtri.
+    cosdg: mark a test as pertaining to cosdg.
+    cosm1: mark a test as pertaining to cosm1.
+    cospi: mark a test as pertaining to cospi.
+    cotdg: mark a test as pertaining to cotdg.
+    cyl_bessel_i: mark a test as pertaining to cyl_bessel_i.
+    cyl_bessel_i0: mark a test as pertaining to cyl_bessel_i0.
+    cyl_bessel_i0e: mark a test as pertaining to cyl_bessel_i0e.
+    cyl_bessel_i1: mark a test as pertaining to cyl_bessel_i1.
+    cyl_bessel_i1e: mark a test as pertaining to cyl_bessel_i1e.
+    cyl_bessel_ie: mark a test as pertaining to cyl_bessel_ie.
+    cyl_bessel_j: mark a test as pertaining to cyl_bessel_j.
+    cyl_bessel_j0: mark a test as pertaining to cyl_bessel_j0.
+    cyl_bessel_j1: mark a test as pertaining to cyl_bessel_j1.
+    cyl_bessel_je: mark a test as pertaining to cyl_bessel_je.
+    cyl_bessel_k: mark a test as pertaining to cyl_bessel_k.
+    cyl_bessel_k0: mark a test as pertaining to cyl_bessel_k0.
+    cyl_bessel_k0e: mark a test as pertaining to cyl_bessel_k0e.
+    cyl_bessel_k1: mark a test as pertaining to cyl_bessel_k1.
+    cyl_bessel_k1e: mark a test as pertaining to cyl_bessel_k1e.
+    cyl_bessel_ke: mark a test as pertaining to cyl_bessel_ke.
+    cyl_bessel_y: mark a test as pertaining to cyl_bessel_y.
+    cyl_bessel_y0: mark a test as pertaining to cyl_bessel_y0.
+    cyl_bessel_y1: mark a test as pertaining to cyl_bessel_y1.
+    cyl_bessel_ye: mark a test as pertaining to cyl_bessel_ye.
+    cyl_hankel_1: mark a test as pertaining to cyl_hankel_1.
+    cyl_hankel_1e: mark a test as pertaining to cyl_hankel_1e.
+    cyl_hankel_2: mark a test as pertaining to cyl_hankel_2.
+    cyl_hankel_2e: mark a test as pertaining to cyl_hankel_2e.
+    dawsn: mark a test as pertaining to dawsn.
+    digamma: mark a test as pertaining to digamma.
+    ellipe: mark a test as pertaining to ellipe.
+    ellipeinc: mark a test as pertaining to ellipeinc.
+    ellipj: mark a test as pertaining to ellipj.
+    ellipk: mark a test as pertaining to ellipk.
+    ellipkinc: mark a test as pertaining to ellipkinc.
+    ellipkm1: mark a test as pertaining to ellipkm1.
+    erf: mark a test as pertaining to erf.
+    erfi: mark a test as pertaining to erfi.
+    erfc: mark a test as pertaining to erfc.
+    erfcx: mark a test as pertaining to erfcx.
+    erfcinv: mark a test as pertaining to erfcinv.
+    exp1: mark a test as pertaining to exp1.
+    exp10: mark a test as pertaining to exp10.
+    exp2: mark a test as pertaining to exp2.
+    expi: mark a test as pertaining to expi.
+    expit: mark a test as pertaining to expit.
+    expm1: mark a test as pertaining to expm1.
+    expn: mark a test as pertaining to expn.
+    exprel: mark a test as pertaining to exprel.
+    fdtr: mark a test as pertaining to fdtr.
+    fdtrc: mark a test as pertaining to fdtrc.
+    fdtri: mark a test as pertaining to fdtri.
+    fresnel: mark a test as pertaining to fresnel.
+    gamma: mark a test as pertaining to gamma.
+    gammaincc: mark a test as pertaining to gammaincc.
+    gammainc: mark a test as pertaining to gammainc.
+    gammainccinv: mark a test as pertaining to gammainccinv.
+    gammaincinv: mark a test as pertaining to gammaincinv.
+    gammaln: mark a test as pertaining to gammaln.
+    gammasgn: mark a test as pertaining to gammasgn.
+    gdtr: mark a test as pertaining to gdtr.
+    gdtrc: mark a test as pertaining to gdtrc.
+    gdtrib: mark a test as pertaining to gdtrib.
+    hyp1f1: mark a test as pertaining to hyp1f1.
+    hyp2f1: mark a test as pertaining to hyp2f1.
+    hyperu: mark a test as pertaining to hyperu.
+    it1i0k0: mark a test as pertaining to it1i0k0.
+    it1j0y0: mark a test as pertaining to it1j0y0.
+    it2i0k0: mark a test as pertaining to it2i0k0.
+    it2j0y0: mark a test as pertaining to it2j0y0.
+    it2struve0: mark a test as pertaining to it2struve0.
+    itairy: mark a test as pertaining to itairy.
+    itmodstruve0: mark a test as pertaining to itmodstruve0.
+    itstruve0: mark a test as pertaining to itstruve0.
+    iv_ratio: mark a test as pertaining to iv_ratio.
+    iv_ratio_c: mark a test as pertaining to iv_ratio_c.
+    kei: mark a test as pertaining to kei.
+    keip: mark a test as pertaining to keip.
+    kelvin: mark a test as pertaining to kelvin.
+    ker: mark a test as pertaining to ker.
+    kerp: mark a test as pertaining to kerp.
+    kolmogc: mark a test as pertaining to kolmogc.
+    kolmogci: mark a test as pertaining to kolmogci.
+    kolmogi: mark a test as pertaining to kolmogi.
+    kolmogorov: mark a test as pertaining to kolmogorov.
+    kolmogp: mark a test as pertaining to kolmogp.
+    lambertw: mark a test as pertaining to lambertw.
+    lanczos_sum_expg_scaled: mark a test as pertaining to lanczos_sum_expg_scaled.
+    lgam1p: mark a test as pertaining to lgam1p.
+    log1p: mark a test as pertaining to log1p.
+    log1pmx: mark a test as pertaining to log1pmx.
+    loggamma: mark a test as pertaining to loggamma.
+    log_expit: mark a test as pertaining to log_expit.
+    log_wright_bessel: mark a test as pertaining to log_wright_bessel.
+    logit: mark a test as pertaining to logit.
+    mcm1: mark a test as pertaining to mcm1.
+    mcm2: mark a test as pertaining to mcm2.
+    modified_fresnel_minus: mark a test as pertaining to modified_fresnel_minus.
+    modified_fresnel_plus: mark a test as pertaining to modified_fresnel_plus.
+    msm1: mark a test as pertaining to msm1.
+    msm2: mark a test as pertaining to msm2.
+    nbdtr: mark a test as pertaining to nbdtr.
+    nbdtrc: mark a test as pertaining to nbdtrc.
+    ndtr: mark a test as pertaining to ndtr.
+    ndtri: mark a test as pertaining to ndtri.
+    oblate_aswfa: mark a test as pertaining to oblate_aswfa.
+    oblate_aswfa_nocv: mark a test as pertaining to oblate_aswfa_nocv.
+    oblate_radial1: mark a test as pertaining to oblate_radial1.
+    oblate_radial1_nocv: mark a test as pertaining to oblate_radial1_nocv.
+    oblate_radial2: mark a test as pertaining to oblate_radial2.
+    oblate_radial2_nocv: mark a test as pertaining to oblate_radial2_nocv.
+    oblate_segv: mark a test as pertaining to oblate_segv.
+    owens_t: mark a test as pertaining to owens_t.
+    pbdv: mark a test as pertaining to pbdv.
+    pbvv: mark a test as pertaining to pbvv.
+    pbwa: mark a test as pertaining to pbwa.
+    pdtr: mark a test as pertaining to pdtr.
+    pdtrc: mark a test as pertaining to pdtrc.
+    pdtri: mark a test as pertaining to pdtri.
+    pmv: mark a test as pertaining to pmv.
+    poch: mark a test as pertaining to poch.
+    prolate_aswfa: mark a test as pertaining to prolate_aswfa.
+    prolate_aswfa_nocv: mark a test as pertaining to prolate_aswfa_nocv.
+    prolate_radial1: mark a test as pertaining to prolate_radial1.
+    prolate_radial1_nocv: mark a test as pertaining to prolate_radial1_nocv.
+    prolate_radial2: mark a test as pertaining to prolate_radial2.
+    prolate_radial2_nocv: mark a test as pertaining to prolate_radial2_nocv.
+    prolate_segv: mark a test as pertaining to prolate_segv.
+    radian: mark a test as pertaining to radian.
+    rgamma: mark a test as pertaining to rgamma.
+    riemann_zeta: mark a test as pertaining to riemann_zeta.
+    round: mark a test as pertaining to round.
+    scaled_exp1: mark a test as pertaining to scaled_exp1.
+    sem: mark a test as pertaining to sem.
+    sem_cva: mark a test as pertaining to sem_cva.
+    shichi: mark a test as pertaining to shichi.
+    sici: mark a test as pertaining to sici.
+    sindg: mark a test as pertaining to sindg.
+    sinpi: mark a test as pertaining to sinpi.
+    smirnov: mark a test as pertaining to smirnov.
+    smirnovc: mark a test as pertaining to smirnovc.
+    smirnovci: mark a test as pertaining to smirnovci.
+    smirnovi: mark a test as pertaining to smirnovi.
+    smirnovp: mark a test as pertaining to smirnovp.
+    spence: mark a test as pertaining to spence.
+    struve_h: mark a test as pertaining to struve_h.
+    struve_l: mark a test as pertaining to struve_l.
+    tandg: mark a test as pertaining to tandg.
+    voigt_profile: mark a test as pertaining to voigt_profile.
+    wofz: mark a test as pertaining to wofz.
+    wright_bessel: mark a test as pertaining to wright_bessel.
+    xlogy: mark a test as pertaining to xlogy.
+    xlog1py: mark a test as pertaining to xlog1py.
+    zeta: mark a test as pertaining to zeta.
+    zetac: mark a test as pertaining to zetac.

src/xsref/__init__.py

@@ -0,0 +1,4 @@
+import xsref._reference._functions
+from xsref._reference._functions import *  # noqa
+
+__all__ = xsref._reference._functions.__all__