saddlepoint-expansions 0.2.1__tar.gz

saddlepoint_expansions-0.2.1/.github/workflows/ci.yml

@@ -0,0 +1,55 @@
+name: CI
+on:
+  push:
+    branches: [main]
+    tags: ['*']
+  pull_request:
+  workflow_dispatch:
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: ${{ startsWith(github.ref, 'refs/pull/') }}
+jobs:
+  test:
+    name: Python ${{ matrix.python-version }} - ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 40
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest]
+        python-version: ['3.10', '3.13']
+        include:
+          - os: macos-latest
+            python-version: '3.12'
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+      - name: Install
+        run: python -m pip install --upgrade pip && python -m pip install -e ".[test]"
+      - name: Test
+        run: pytest -q
+  docs:
+    name: Documentation
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+          cache: pip
+      - name: Install
+        run: python -m pip install --upgrade pip && python -m pip install -e ".[docs]"
+      - name: Build
+        run: sphinx-build -W --keep-going -b html docs docs/_build/html
+      - name: Deploy
+        if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+        uses: peaceiris/actions-gh-pages@v4
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: docs/_build/html
+          force_orphan: true

saddlepoint_expansions-0.2.1/.github/workflows/publish.yml

@@ -0,0 +1,42 @@
+name: Publish to PyPI
+# Trusted publishing: PyPI accepts the upload on the strength of this workflow's identity
+# (repository s-broda/saddlepoint-expansions, file publish.yml, environment pypi), so no token is
+# stored anywhere. Set up once on pypi.org under Publishing, as a pending publisher for the
+# project name saddlepoint-expansions. Runs when a GitHub release is published, or by hand.
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+jobs:
+  build:
+    name: Build sdist and wheel
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+      - name: Build
+        run: |
+          python -m pip install --upgrade build twine
+          python -m build
+          python -m twine check dist/*
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+  publish:
+    name: Upload to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/saddlepoint-expansions/
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

saddlepoint_expansions-0.2.1/.gitignore

@@ -0,0 +1,8 @@
+__pycache__/
+*.pyc
+*.egg-info/
+build/
+dist/
+docs/_build/
+.pytest_cache/
+.DS_Store

saddlepoint_expansions-0.2.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Simon A. Broda and Raymond Kan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

saddlepoint_expansions-0.2.1/PKG-INFO

@@ -0,0 +1,134 @@
+Metadata-Version: 2.5
+Name: saddlepoint-expansions
+Version: 0.2.1
+Summary: Saddlepoint expansions of any order for multivariate tail probabilities and densities, from the cumulant generating function
+Project-URL: Repository, https://github.com/s-broda/saddlepoint-expansions
+Project-URL: Documentation, https://s-broda.github.io/saddlepoint-expansions/
+Author: Simon A. Broda, Raymond Kan
+License: MIT License
+        
+        Copyright (c) 2026 Simon A. Broda and Raymond Kan
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: Taylor-mode automatic differentiation,asymptotic expansion,orthant probability,saddlepoint approximation,tail probability
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Requires-Python: >=3.10
+Requires-Dist: numpy>=1.24
+Requires-Dist: scipy>=1.10
+Provides-Extra: docs
+Requires-Dist: furo; extra == 'docs'
+Requires-Dist: myst-parser; extra == 'docs'
+Requires-Dist: sphinx>=7; extra == 'docs'
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == 'test'
+Description-Content-Type: text/markdown
+
+# saddlepoint-expansions
+
+[![CI](https://github.com/s-broda/saddlepoint-expansions/actions/workflows/ci.yml/badge.svg)](https://github.com/s-broda/saddlepoint-expansions/actions/workflows/ci.yml)
+[![Documentation](https://img.shields.io/badge/docs-latest-blue.svg)](https://s-broda.github.io/saddlepoint-expansions/)
+
+Saddlepoint expansions of any order for tail probabilities and densities of random vectors,
+from the cumulant generating function alone. Python port of the Julia package
+[SaddlepointExpansions.jl](https://github.com/s-broda/SaddlepointExpansions.jl).
+
+The package implements the expansions of Broda and Kan, *Uniform saddlepoint expansions for
+multivariate tail probabilities*: the orthant probability `P(X ≥ x)` of a random vector in any
+dimension (first-order term: Kolassa 2003), its density, and the density and distribution
+function of a ratio, with the univariate expansions of Daniels and of Hauschildt and Robinson as
+the one-dimensional case; and those of Bao, Broda and Kan, *Inversion formulas and saddlepoint
+expansions for Studentized means*, for the density and distribution function of `X/sqrt(Y)`
+(`studentized_density`, `studentized_tailprob`, `studentized_quantile`). The expansion of order `M` has relative error `O(n^-M)`, uniformly for
+saddlepoints in the closed positive orthant; saddlepoints with negative components are handled
+by inclusion-exclusion.
+
+The cumulant generating function is supplied as an ordinary Python function written with numpy.
+All its derivatives are generated by Taylor-mode automatic differentiation, with a small
+truncated-polynomial algebra included in the package (no dependency beyond numpy and scipy),
+directly in the whitened coordinates in which the expansions are evaluated.
+
+```python
+import numpy as np
+from saddlepoint_expansions import CGF, sample_mean, tailprob, density
+
+# X = (U0 + U1, U0 + U2), U_i independent unit exponentials; the mean of n = 5 observations
+K = CGF(lambda t: -np.log(1 - t[0]) - np.log(1 - t[1]) - np.log(1 - t[0] - t[1]), 2,
+        domain=lambda t: t[0] < 1 and t[1] < 1 and t[0] + t[1] < 1)
+Kn = sample_mean(K, 5)
+
+tailprob(Kn, [3.0, 3.0], order=4)["F"]      # P(X̄₁ ≥ 3, X̄₂ ≥ 3), orders 1 to 4; exact 0.02215196
+density(Kn, [3.0, 3.0], order=4)["f"]       # the joint density
+tailprob(Kn, [3.0, 3.0], lower=True)["F"]   # P(X̄₁ ≤ 3, X̄₂ ≤ 3)
+```
+
+A library of cumulant generating functions (normal, gamma, noncentral chi-squared, quadratic
+forms in normal variables, Wishart diagonals, sums of exponentials) and transformations
+(reflection, marginals, linear combinations, sample means, independent sums) is included, and
+the lower-level derivative interface (`spa_bi`, `spa_mv`, `spa_orthant`, ...) remains available
+for models with closed-form derivatives. A `CGF` can also carry its Taylor polynomials in closed
+form (`quadratic_forms_cgf` does, by the trace recursion of the paper), and `ratio_density` and
+`ratio_tailprob` handle vectors of ratios.
+
+## Installation
+
+```
+pip install git+https://github.com/s-broda/saddlepoint-expansions
+```
+
+Python 3.10 or later, numpy and scipy.
+
+## Differences from the Julia package
+
+Everything is in double precision. The Julia package also runs in arbitrary precision
+(`BigFloat`), uses an exact recursion for the orthant integrals in that case, and repeats
+densities in three or more dimensions, and the Studentized-mean density, in higher precision when
+the terms cancel strongly; here the cancellation indicator (`info["kappa_pdf"]`, `info["kappa"]`)
+is reported instead. The
+Julia package is the reference implementation: the test suite of this package compares every
+function with values computed by it (`tests/reference_values.csv`, written by
+`test/reference_values.jl` of the Julia package and shared with the MATLAB counterpart).
+
+## Documentation and tests
+
+```
+pip install -e ".[docs,test]"
+sphinx-build -b html docs docs/_build/html
+pytest
+```
+
+## Citation
+
+> Broda, S. A. and Kan, R. Uniform saddlepoint expansions for multivariate tail probabilities.
+
+and, for the Studentized-mean functions,
+
+> Bao, Y., Broda, S. A. and Kan, R. Inversion formulas and saddlepoint expansions for Studentized means.
+
+## License
+
+MIT; see `LICENSE`.

saddlepoint_expansions-0.2.1/README.md

@@ -0,0 +1,84 @@
+# saddlepoint-expansions
+
+[![CI](https://github.com/s-broda/saddlepoint-expansions/actions/workflows/ci.yml/badge.svg)](https://github.com/s-broda/saddlepoint-expansions/actions/workflows/ci.yml)
+[![Documentation](https://img.shields.io/badge/docs-latest-blue.svg)](https://s-broda.github.io/saddlepoint-expansions/)
+
+Saddlepoint expansions of any order for tail probabilities and densities of random vectors,
+from the cumulant generating function alone. Python port of the Julia package
+[SaddlepointExpansions.jl](https://github.com/s-broda/SaddlepointExpansions.jl).
+
+The package implements the expansions of Broda and Kan, *Uniform saddlepoint expansions for
+multivariate tail probabilities*: the orthant probability `P(X ≥ x)` of a random vector in any
+dimension (first-order term: Kolassa 2003), its density, and the density and distribution
+function of a ratio, with the univariate expansions of Daniels and of Hauschildt and Robinson as
+the one-dimensional case; and those of Bao, Broda and Kan, *Inversion formulas and saddlepoint
+expansions for Studentized means*, for the density and distribution function of `X/sqrt(Y)`
+(`studentized_density`, `studentized_tailprob`, `studentized_quantile`). The expansion of order `M` has relative error `O(n^-M)`, uniformly for
+saddlepoints in the closed positive orthant; saddlepoints with negative components are handled
+by inclusion-exclusion.
+
+The cumulant generating function is supplied as an ordinary Python function written with numpy.
+All its derivatives are generated by Taylor-mode automatic differentiation, with a small
+truncated-polynomial algebra included in the package (no dependency beyond numpy and scipy),
+directly in the whitened coordinates in which the expansions are evaluated.
+
+```python
+import numpy as np
+from saddlepoint_expansions import CGF, sample_mean, tailprob, density
+
+# X = (U0 + U1, U0 + U2), U_i independent unit exponentials; the mean of n = 5 observations
+K = CGF(lambda t: -np.log(1 - t[0]) - np.log(1 - t[1]) - np.log(1 - t[0] - t[1]), 2,
+        domain=lambda t: t[0] < 1 and t[1] < 1 and t[0] + t[1] < 1)
+Kn = sample_mean(K, 5)
+
+tailprob(Kn, [3.0, 3.0], order=4)["F"]      # P(X̄₁ ≥ 3, X̄₂ ≥ 3), orders 1 to 4; exact 0.02215196
+density(Kn, [3.0, 3.0], order=4)["f"]       # the joint density
+tailprob(Kn, [3.0, 3.0], lower=True)["F"]   # P(X̄₁ ≤ 3, X̄₂ ≤ 3)
+```
+
+A library of cumulant generating functions (normal, gamma, noncentral chi-squared, quadratic
+forms in normal variables, Wishart diagonals, sums of exponentials) and transformations
+(reflection, marginals, linear combinations, sample means, independent sums) is included, and
+the lower-level derivative interface (`spa_bi`, `spa_mv`, `spa_orthant`, ...) remains available
+for models with closed-form derivatives. A `CGF` can also carry its Taylor polynomials in closed
+form (`quadratic_forms_cgf` does, by the trace recursion of the paper), and `ratio_density` and
+`ratio_tailprob` handle vectors of ratios.
+
+## Installation
+
+```
+pip install git+https://github.com/s-broda/saddlepoint-expansions
+```
+
+Python 3.10 or later, numpy and scipy.
+
+## Differences from the Julia package
+
+Everything is in double precision. The Julia package also runs in arbitrary precision
+(`BigFloat`), uses an exact recursion for the orthant integrals in that case, and repeats
+densities in three or more dimensions, and the Studentized-mean density, in higher precision when
+the terms cancel strongly; here the cancellation indicator (`info["kappa_pdf"]`, `info["kappa"]`)
+is reported instead. The
+Julia package is the reference implementation: the test suite of this package compares every
+function with values computed by it (`tests/reference_values.csv`, written by
+`test/reference_values.jl` of the Julia package and shared with the MATLAB counterpart).
+
+## Documentation and tests
+
+```
+pip install -e ".[docs,test]"
+sphinx-build -b html docs docs/_build/html
+pytest
+```
+
+## Citation
+
+> Broda, S. A. and Kan, R. Uniform saddlepoint expansions for multivariate tail probabilities.
+
+and, for the Studentized-mean functions,
+
+> Bao, Y., Broda, S. A. and Kan, R. Inversion formulas and saddlepoint expansions for Studentized means.
+
+## License
+
+MIT; see `LICENSE`.

saddlepoint_expansions-0.2.1/docs/api.md

@@ -0,0 +1,58 @@
+# API reference
+
+## Cumulant generating functions and the high-level interface
+
+```{eval-rst}
+.. autoclass:: saddlepoint_expansions.CGF
+   :members: __add__
+
+.. autofunction:: saddlepoint_expansions.derivatives
+.. autofunction:: saddlepoint_expansions.saddlepoint
+.. autofunction:: saddlepoint_expansions.tailprob
+.. autofunction:: saddlepoint_expansions.density
+.. autofunction:: saddlepoint_expansions.ratio_density
+.. autofunction:: saddlepoint_expansions.ratio_tailprob
+.. autofunction:: saddlepoint_expansions.studentized_density
+.. autofunction:: saddlepoint_expansions.studentized_tailprob
+.. autofunction:: saddlepoint_expansions.studentized_quantile
+.. autofunction:: saddlepoint_expansions.studentized_saddlepoint
+.. autofunction:: saddlepoint_expansions.studentized_locus
+.. autofunction:: saddlepoint_expansions.reflect
+.. autofunction:: saddlepoint_expansions.marginal
+.. autofunction:: saddlepoint_expansions.linear_combination
+.. autofunction:: saddlepoint_expansions.sample_mean
+.. autofunction:: saddlepoint_expansions.shift
+```
+
+## Library of cumulant generating functions
+
+```{eval-rst}
+.. automodule:: saddlepoint_expansions.cgfs
+   :members:
+```
+
+## The derivative interface
+
+```{eval-rst}
+.. autofunction:: saddlepoint_expansions.spa_saddle
+.. autofunction:: saddlepoint_expansions.spa_uni
+.. autofunction:: saddlepoint_expansions.spa_ratio_pdf
+.. autofunction:: saddlepoint_expansions.spa_bi
+.. autofunction:: saddlepoint_expansions.spa_bi_at
+.. autofunction:: saddlepoint_expansions.spa_orthant2
+.. autofunction:: saddlepoint_expansions.spa_mv
+.. autofunction:: saddlepoint_expansions.spa_mv_at
+.. autofunction:: saddlepoint_expansions.spa_orthant
+.. autofunction:: saddlepoint_expansions.orthant2
+.. autofunction:: saddlepoint_expansions.orthant3
+.. autofunction:: saddlepoint_expansions.kfun
+.. autofunction:: saddlepoint_expansions.kwhite
+.. autofunction:: saddlepoint_expansions.ratio_mv
+```
+
+## The Taylor algebra
+
+```{eval-rst}
+.. automodule:: saddlepoint_expansions.taylor
+   :members: TPoly, Algebra, get_algebra, variables, from_coefficients, sincu, sinhc, DomainError
+```

saddlepoint_expansions-0.2.1/docs/conf.py

@@ -0,0 +1,28 @@
+import os
+import sys
+
+sys.path.insert(0, os.path.abspath("../src"))
+
+project = "saddlepoint-expansions"
+author = "Simon A. Broda and Raymond Kan"
+copyright = "2026, Simon A. Broda and Raymond Kan"
+release = "0.1.0"
+
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx.ext.napoleon",
+    "sphinx.ext.mathjax",
+    "sphinx.ext.intersphinx",
+    "myst_parser",
+]
+myst_enable_extensions = ["dollarmath", "amsmath"]
+autodoc_member_order = "bysource"
+autodoc_typehints = "none"
+intersphinx_mapping = {
+    "python": ("https://docs.python.org/3", None),
+    "numpy": ("https://numpy.org/doc/stable/", None),
+}
+html_theme = "furo"
+html_title = "saddlepoint-expansions"
+source_suffix = {".rst": "restructuredtext", ".md": "markdown"}
+exclude_patterns = ["_build"]

saddlepoint_expansions-0.2.1/docs/guide.md

@@ -0,0 +1,185 @@
+# Guide
+
+## Cumulant generating functions
+
+A {class}`~saddlepoint_expansions.CGF` wraps a Python function `K(t)` of a numpy vector `t` of
+length $d$ (also for $d = 1$, where you write `t[0]`), together with the dimension and,
+optionally, a predicate describing the domain:
+
+```python
+K = CGF(lambda t: -3*np.log(1 - t[0]) - 2*np.log(1 - 2*t[1]), 2,
+        domain=lambda t: t[0] < 1 and t[1] < 1/2)
+```
+
+The function is evaluated on vectors of truncated multivariate Taylor polynomials
+({class}`~saddlepoint_expansions.taylor.TPoly`) to generate its derivatives, so it must be
+written generically: arithmetic, `np.exp`, `np.log`, `np.sqrt`, powers, `np.sum`, products
+with constant matrices and vectors (`A @ t`), `np.sin`, `np.cos`, `np.tan`, `np.sinh`,
+`np.cosh`, `np.tanh`, `np.arctan` all work, and {func}`~saddlepoint_expansions.sinhc` and
+{func}`~saddlepoint_expansions.sincu` give $\sinh(x)/x$ and $\sin(x)/x$ with their removable
+singularity at zero (write `np.log(sinhc(t[0]))` for the uniform distribution, not
+`np.log(np.sinh(t[0])/t[0])`, which is $0/0$ at the origin where the saddlepoint iteration starts); `math.log`, `float(...)` and calls into
+numerical libraries that require floats do not. For determinants and inverses of matrices that
+depend on `t`, write the factorization in generic arithmetic as
+{func}`~saddlepoint_expansions.quadratic_forms_cgf` does, or use that constructor.
+
+Outside its domain, `K` may raise a {class}`~saddlepoint_expansions.DomainError` (`np.log` and
+`np.sqrt` of a polynomial with a negative constant term do this automatically) or return a
+non-finite value. When the formula is finite outside the true domain, as with $1/(1-t)$, the
+`domain` predicate is needed; it is also cheaper than an exception.
+
+Transformations: {func}`~saddlepoint_expansions.reflect` (sign changes),
+{func}`~saddlepoint_expansions.marginal`, {func}`~saddlepoint_expansions.linear_combination`
+($Y = B'X$), {func}`~saddlepoint_expansions.sample_mean` ($nK(t/n)$),
+{func}`~saddlepoint_expansions.shift` ($X + c$), and `K1 + K2` for the sum of independent
+vectors. The library: {func}`~saddlepoint_expansions.normal_cgf`,
+{func}`~saddlepoint_expansions.gamma_cgf`, {func}`~saddlepoint_expansions.ncx2_cgf`,
+{func}`~saddlepoint_expansions.exponential_sums_cgf`,
+{func}`~saddlepoint_expansions.quadratic_forms_cgf`,
+{func}`~saddlepoint_expansions.wishart_diag_cgf`,
+{func}`~saddlepoint_expansions.common_component_cgf`, {func}`~saddlepoint_expansions.uniform_cgf`.
+
+## Tail probabilities
+
+{func}`~saddlepoint_expansions.tailprob`` (K, x, order=M)` returns the expansions of orders
+$1, \dots, M$ of $P(X \ge x)$ in `F`, with the saddlepoint `tau`, a `status` string and the
+full result of the underlying routine in `info`. The expansion of order $M$ keeps the terms of
+orders $n^{-m/2}$, $m \le 2M - 1$, and has relative error $O(n^{-M})$; in practice each order
+gains one to two digits at moderate sample sizes, and the first order is accurate to a few
+percent.
+
+`lower=True` gives $P(X \le x)$ and `signs` a mixed corner, e.g. `signs=[1, -1]` for
+$P(X_1 \ge x_1, X_2 \le x_2)$. When the saddlepoint has negative components, the expansion is
+applied through the inclusion-exclusion identity of the paper, which preserves the relative
+error bound. In three dimensions the orthant integrals are computed by Gauss quadrature and in
+four or more by randomized quasi-Monte Carlo (`info["err"]` is then a standard error); keyword
+arguments are passed on to {func}`~saddlepoint_expansions.spa_mv` (`nG`, `nqmc`, ...) and, for
+$d = 2$, to {func}`~saddlepoint_expansions.spa_orthant2` (`nG`, `logscale` for probabilities
+below the double-precision range, ...). For $d = 1$, `x` may be a scalar.
+
+## Densities
+
+{func}`~saddlepoint_expansions.density`` (K, x, order=M)` returns the expansions of orders
+$1, \dots, M$ of the density (the terms $m \le M-1$ of the expansion in powers of $n^{-1}$,
+relative error $O(n^{-M})$); a finite sum of Hermite polynomials, no integration, any
+dimension. In three or more dimensions the terms can cancel strongly at high orders; check
+`info["kappa_pdf"]`, the ratio of the sum of the absolute terms to the sum (about $\log_{10}$
+of it digits are lost). The Julia package repeats such computations in higher precision; this
+package works in double precision.
+
+## Ratios
+
+For a bivariate `K` with a positive denominator $X_2 > 0$:
+{func}`~saddlepoint_expansions.ratio_density`` (K, r)` is the Rice expansion of the density of
+$X_1/X_2$ at $r$ through the saddlepoint of $K_W(s) = K(s, -rs)$, and
+{func}`~saddlepoint_expansions.ratio_tailprob`` (K, r, lower=...)` is the univariate expansion
+for $W = X_1 - rX_2$ at $0$. Example, the noncentral $F$ with $Q_1 \sim \chi^2_m(\lambda)$ and
+$Q_2 \sim \chi^2_n$:
+
+```python
+K = CGF(lambda t: ncx2_cgf(m, lam)(t[:1]) + ncx2_cgf(n)(t[1:]), 2,
+        domain=lambda t: t[0] < 0.5 and t[1] < 0.5)
+c = f*m/n
+ratio_tailprob(K, c, lower=True)["F"]     # P(F <= f), orders 1..3
+ratio_density(K, c)["f"] * (m/n)          # density of F at f
+```
+
+*Several ratios.* With a vector `r` of length $d$, `K` is the cgf of $(X_1, \dots, X_d, Y_1, \dots, Y_d)$,
+or of $(X_1, \dots, X_d, Y)$ for a common denominator, and `ratio_density` returns the joint density
+of $(X_1/Y_1, \dots, X_d/Y_d)$ at `r` (Theorem 4 with the amplitude expansion of Corollary 1 of
+the paper, every Taylor coefficient from one polynomial of $K(s, -r \circ s + \tau)$), while
+`ratio_tailprob` returns the orthant probability $P(R \ge r)$ with `lower` and `signs` as in
+`tailprob`. The sample autocorrelations at lags one and two, for example, are two ratios of
+quadratic forms with a common denominator:
+
+```python
+N = 50; Mc = np.eye(N) - np.ones((N, N))/N
+A = lambda j: (np.diag(np.ones(N - j), j) + np.diag(np.ones(N - j), -j))/2
+K = quadratic_forms_cgf([Mc @ A(1) @ Mc, Mc @ A(2) @ Mc, Mc])
+ratio_density(K, [-1, -1]/np.sqrt(N), order=5)["f"]
+```
+
+## Studentized means
+
+For $Q = X/\sqrt{Y}$ with $Y > 0$, with `K` the joint cumulant generating function of $(X, Y)$,
+the expansions of Bao, Broda and Kan, *Inversion formulas and saddlepoint expansions for
+Studentized means*:
+
+```python
+studentized_density(K, q, order=3)           # density of X/sqrt(Y) at q, orders 1..3
+studentized_tailprob(K, q, order=3)          # P(X/sqrt(Y) >= q); lower=True for P(X/sqrt(Y) <= q)
+studentized_quantile(K, 0.05, order=3)       # the q with P(X/sqrt(Y) <= q) = 0.05 under the expansion
+```
+
+Unlike a ratio, $X - q\sqrt{Y}$ is not linear in $(X, Y)$, and the inversion is a double
+integral with a kernel in $s$ and $t$. The saddlepoint $(\hat s, \hat t, \hat v)$ solves
+$K_s = qv$, $K_t = v^2$, $qs + 2tv = 0$ ({func}`~saddlepoint_expansions.studentized_saddlepoint`);
+the density is the bivariate amplitude expansion about it, and the distribution function is a
+Hauschildt-Robinson type expansion in $s$ after the $t$-integral is expanded by Laplace's method,
+all Taylor coefficients being generated from the Taylor polynomial of `K` at the saddlepoint by
+Newton's method and composition on power series. `order=M` keeps the terms $m \le M - 1$ of the
+density and $m \le 2M - 1$ of the distribution function (relative error $O(n^{-M})$);
+`info["Fp"]` holds every half-order. The saddlepoints for all $q$ lie on the curve
+$sK_s + 2tK_t = 0$ ({func}`~saddlepoint_expansions.studentized_locus`), which is how
+`studentized_quantile` searches: along the curve each $\hat s$ gives its $q$ and its distribution
+function directly, so that no saddlepoint equation is solved for a trial $q$.
+
+The noncentral $t$ distribution, for example, with $X \sim N(\mu, 1)$ and
+$Y \sim \chi^2_\nu/\nu$ independent, $n$ pairs: $\bar X/\sqrt{\bar Y} = T/\sqrt{n}$, $T$
+noncentral $t$ with $n\nu$ degrees of freedom and noncentrality $\sqrt{n}\mu$:
+
+```python
+K = sample_mean(CGF(lambda t: mu*t[0] + t[0]**2/2 - nu/2*np.log(1 - 2*t[1]/nu), 2,
+                    domain=lambda t: t[1] < nu/2), n)
+studentized_tailprob(K, x/np.sqrt(n), lower=True)["F"]     # P(T <= x)
+```
+
+The terms of high order of the density cancel by many orders of magnitude where $|\hat t|$ is
+large; `info["kappa"]` is the cancellation indicator, and in double precision the terms beyond
+the fourth are often unreliable there (the Julia package repeats the computation in higher
+precision; here `status` reports `"coefficients inaccurate"`). The Taylor algebra carries complex
+coefficients for these expansions (the Hessian of the exponent is indefinite where $\hat t < 0$).
+
+## Closed-form Taylor polynomials
+
+Automatic differentiation is the default, but a `CGF` can carry its Taylor polynomials in closed
+form through the argument `taylor`, a function `taylor(t, N, M)` returning the polynomial of
+degree `N` of $K(t + Mv)$ as a {class}`~saddlepoint_expansions.taylor.TPoly` (built from a
+coefficient table with {func}`~saddlepoint_expansions.taylor.from_coefficients`), or `None`
+outside the domain. {func}`~saddlepoint_expansions.quadratic_forms_cgf` uses this with the trace
+recursion of the paper evaluated directly in the whitened directions, which makes large matrices
+cheap, and the transformations carry the option along; pass `closedform=False` to differentiate
+the generic formula instead. Comparisons between polynomials, or with numbers, compare the
+constant terms, so a cgf written with an `if` on its argument can be differentiated.
+
+## Derivatives and the saddlepoint
+
+{func}`~saddlepoint_expansions.derivatives`` (K, t, N)` returns all derivatives
+$K^{(\nu)}(t)$, $|\nu| \le N$, as a dict keyed by the multi-index, and
+{func}`~saddlepoint_expansions.saddlepoint`` (K, x)` solves $K'(\tau) = x$ by Newton's method
+with backtracking. The derivatives at the saddlepoint are generated once, to the degree $2M + 1$
+needed by order $M$, and the whitened coefficients (of $K_Y(u) = K(L^{-T}u)$,
+$K''(\tau) = LL'$) are generated by differentiating the composed function directly, which keeps
+them as accurate as the original ones.
+
+## The derivative interface
+
+The engine can be used with derivatives supplied by the user, as `Kfun(nu, t)` returning the
+derivative of multi-index order `nu` (a tuple) at `t`, NaN outside the domain:
+{func}`~saddlepoint_expansions.spa_saddle`, {func}`~saddlepoint_expansions.spa_uni`,
+{func}`~saddlepoint_expansions.spa_ratio_pdf`, {func}`~saddlepoint_expansions.spa_bi`,
+{func}`~saddlepoint_expansions.spa_bi_at`, {func}`~saddlepoint_expansions.spa_orthant2`,
+{func}`~saddlepoint_expansions.spa_mv`, {func}`~saddlepoint_expansions.spa_mv_at`,
+{func}`~saddlepoint_expansions.spa_orthant`. These follow the Julia package and the MATLAB
+programs of the paper. {func}`~saddlepoint_expansions.kfun` and
+{func}`~saddlepoint_expansions.kwhite` turn a `CGF` into the functions they take.
+
+## The Taylor algebra
+
+{mod}`saddlepoint_expansions.taylor` is a self-contained implementation of truncated
+multivariate Taylor polynomials: `variables(d, N)` returns the $d$ variables of degree $N$ as
+an object array, and any generic function evaluated on them returns a
+{class}`~saddlepoint_expansions.taylor.TPoly` whose `coeff(nu)` is $f^{(\nu)}(0)/\nu!$ and
+`derivative(nu)` is $f^{(\nu)}(0)$. Products use precomputed index tables and `np.bincount`; a
+product of two polynomials of degree 12 in three variables takes about 0.1 ms, an `exp` or `log`
+about 1 ms.