pyapprox

KO | EN

gitlite — search

#typescript #ai-agents #ai #dsh-plugin #deepseek-harness #open-source #cli #claude-code #codex #developer-tools #react #windows

★ 76 Open GitHub ↗

Flexible and efficient tools for high-dimensional approximation, scientific machine learning and uncertainty quantification.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

[![Tests](https://github.com/sandialabs/pyapprox/actions/workflows/tests.yml/badge.svg)](https://github.com/sandialabs/pyapprox/actions/workflows/tests.yml)
[![Lint](https://github.com/sandialabs/pyapprox/actions/workflows/lint.yml/badge.svg)](https://github.com/sandialabs/pyapprox/actions/workflows/lint.yml)
[![Docs](https://github.com/sandialabs/pyapprox/actions/workflows/docs.yml/badge.svg)](https://github.com/sandialabs/pyapprox/actions/workflows/docs.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://raw.githubusercontent.com/sandialabs/pyapprox/main/LICENSE)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)

# PyApprox

PyApprox provides flexible and efficient tools for high-dimensional approximation, uncertainty quantification, and decision-making under uncertainty. It implements methods addressing various issues surrounding high-dimensional parameter spaces and limited evaluations of expensive simulation models, with the goal of facilitating simulation-aided knowledge discovery, prediction, and design.

**[Documentation](https://sandialabs.github.io/pyapprox/)** | **[Tutorials](https://sandialabs.github.io/pyapprox/)** | **[Paper](https://doi.org/10.1016/j.envsoft.2023.105825)**

Tools are provided for:

1. **Surrogate modeling** — polynomial chaos expansions (least squares, compressive sensing, interpolation), Gaussian process regression (single- and multi-output, DAG-structured), low-rank tensor decompositions (function trains), and sparse grid interpolation
2. **Multi-fidelity estimation** — approximate control variates (ACV), multi-level Monte Carlo (MLMC), multi-fidelity Monte Carlo (MFMC), MLBLUE, and group ACV
3. **Bayesian experimental design** — KL-based and goal-oriented optimal experimental design with gradient-based optimization
4. **Bayesian inference** — MCMC sampling and conjugate posterior analysis
5. **Sensitivity analysis** — Sobol indices, Morris screening, and surrogate-based sensitivity
6. **Probability and risk** — random variable transformations, risk measures, and random field representations (KLE)
7. **PDE solvers** — collocation and Galerkin finite-element methods for advection-diffusion-reaction, Helmholtz, Stokes, elasticity, and more
8. **Optimization** — implicit function differentiation, adjoint methods, and design under uncertainty

All code is fully typed, supports dual backends (NumPy and PyTorch), and preserves PyTorch autograd computation graphs for automatic differentiation.

## Quick Start

```python
import numpy as np
from pyapprox.util.backends.numpy import NumpyBkd
from pyapprox.interface.functions.fromcallable.function import FunctionFromCallable
from pyapprox.probability import UniformMarginal, IndependentJoint
from pyapprox.surrogates.sparsegrids import create_basis_factories
from pyapprox.surrogates.sparsegrids.isotropic_fitter import IsotropicSparseGridFitter
from pyapprox.surrogates.sparsegrids.subspace_factory import TensorProductSubspaceFactory
from pyapprox.surrogates.affine.indices import LinearGrowthRule

bkd = NumpyBkd()

# Define a 2D function using the FunctionProtocol
def target(samples):
    x, y = samples[0], samples[1]
    return bkd.reshape(x**3 + x*y + y**2, (1, -1))

func = FunctionFromCallable(1, 2, target, bkd)

# Build a sparse grid surrogate
marginals = [UniformMarginal(-1.0, 1.0, bkd) for _ in range(2)]
joint = IndependentJoint(marginals, bkd)
factories = create_basis_factories(joint.marginals(), bkd, "gauss")
growth = LinearGrowthRule(scale=1, shift=1)
tp_factory = TensorProductSubspaceFactory(bkd, factories, growth)
fitter = IsotropicSparseGridFitter(bkd, tp_factory, level=3)
samples = fitter.get_samples()
result = fitter.fit(func(samples))
surrogate = result.surrogate

# Evaluate surrogate at new points
test_pts = joint.rvs(100)
approx_values = surrogate(test_pts)
```

## Requirements

- Python >= 3.11
- NumPy >= 2.0, SciPy >= 1.11, PyTorch >= 2.0
- matplotlib, sympy, networkx

## Installation

PyApprox lives in a monorepo with three packages (`pyapprox`,
`pyapprox-benchmarks`, `pyapprox-tutorials`). Until the monorepo is
published to PyPI, install from source or directly from GitHub.

### From source (recommended for development)

```bash
git clone https://github.com/sandialabs/pyapprox.git
cd pyapprox
make install-dev
```

This installs all three packages in editable mode with full dev tooling
via the `[dev]` extra (tests, docs, linters, plus the runtime extras
`fem`, `umbridge`, `numba`, `parallel`, `cvxpy`).

### Latest from GitHub (no clone)

```bash
pip install \
    "pyapprox[runtime-extras] @ git+https://github.com/sandialabs/pyapprox.git#subdirectory=packages/pyapprox" \
    "pyapprox-benchmarks @ git+https://github.com/sandialabs/pyapprox.git#subdirectory=packages/pyapprox-benchmarks" \
    "pyapprox-tutorials @ git+https://github.com/sandialabs/pyapprox.git#subdirectory=packages/pyapprox-tutorials"
```

### Runtime extras

```bash
pip install -e "packages/pyapprox[fem]"             # Finite element (scikit-fem)
pip install -e "packages/pyapprox[umbridge]"        # UMBridge model interface
pip install -e "packages/pyapprox[numba]"           # Numba JIT acceleration
pip install -e "packages/pyapprox[parallel]"        # Parallel execution
pip install -e "packages/pyapprox[cvxpy]"           # Convex optimization
pip install -e "packages/pyapprox[runtime-extras]"  # All the above
```

### Using conda

```bash
conda env create -f environment.yml
conda activate pyapprox
make install-dev
```

## Running Tests

Tests are split across three directories:

| Directory | What it tests | Requires |
|-----------|---------------|----------|
| `packages/pyapprox/tests/` | Core pyapprox library | `pyapprox[test]` only |
| `packages/pyapprox-benchmarks/tests/` | Benchmark functions | `pyapprox-benchmarks` |
| `tests/integration/` | Cross-package interactions | `pyapprox-benchmarks` |

```bash
make test              # all tests (core + benchmarks + integration)
make test-core         # core tests only (no pyapprox-benchmarks needed)
make test-all          # all tests including slowest
```

`make install-dev` installs everything needed for all test directories.

Some tests are marked as slow and are skipped by default:

```bash
PYAPPROX_RUN_SLOW=1 pytest -v --tb=short           # include slow tests (>5s)
PYAPPROX_RUN_SLOWER=1 pytest -v --tb=short          # include slower tests (>30s)
PYAPPROX_RUN_SLOWEST=1 pytest -v --tb=short         # include all tests
```

## Building Documentation

The tutorial site is built with [Quarto](https://quarto.org/). Install it, then:

```bash
make docs                     # build with parallel execution
make docs-serve               # build and serve locally
```

Or manually:

```bash
cd packages/pyapprox-tutorials/tutorials
./build.sh -j auto            # parallel execution (auto-detect CPUs)
./build.sh --notebooks        # also generate downloadable .ipynb files
./build.sh --serve            # start local server after build
```

Output is written to `packages/pyapprox-tutorials/tutorials/library/_site/`.

## Linting

```bash
make lint                     # ruff style and import checks
make typecheck                # mypy static type checking
```

## Contributing

Contributions are welcome. Please:

1. Fork the repository and create a feature branch
2. Ensure all tests pass (including slow): `PYAPPROX_RUN_SLOWEST=1 make test-all`
3. Ensure no lint errors: `make lint`
4. Submit a pull request

## Citation

If you use PyApprox in your research, please cite:

```bibtex
@article{JAKEMAN2023105825,
  title = {PyApprox: A software package for sensitivity analysis, Bayesian inference,
           optimal experimental design, and multi-fidelity uncertainty quantification
           and surrogate modeling},
  author = {J.D. Jakeman},
  journal = {Environmental Modelling \& Software},
  volume = {170},
  pages = {105825},
  year = {2023},
  doi = {10.1016/j.envsoft.2023.105825}
}
```

## License

PyApprox is licensed under the [MIT License](LICENSE).

## Acknowledgements

This research was developed with funding from the Defense Advanced Research Projects Agency (DARPA), the U.S. Department of Energy Office of Science Advanced Scientific Computing Research (ASCR) program, and the Sandia National Laboratories Laboratory Directed Research and Development (LDRD) program. The views, opinions and/or findings expressed are those of the author and should not be interpreted as representing the official views or policies of the Department of Defense or the U.S. Government.

pyapprox

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README