Skip to main content

jaxgsa

Global sensitivity analysis in JAX

PyPI DOI CI Documentation jaxgsa studio License: BSD-3-Clause Python

jaxgsa helps you find which inputs drive variation in a model's output. You choose input distributions, evaluate your model at sample points, and use jaxgsa to estimate each input's effect. It does not run your model for you.

Why jaxgsa

  • Many outputs in one call. Time series and multi-output models are analysed in one compiled JAX call, not one Python loop per output. On a laptop CPU (Apple M1 Pro, float32), Sobol analysis of 1,000 time points takes 78 ms, and sampling, evaluating and analysing 81,920 model runs with 1,000 outputs each takes 0.26 s (benchmarks).
  • Gradients come free. DGSM gets model derivatives from JAX, and the estimator cores are differentiable, so an index can sit inside a larger JAX computation (differentiation guide).
  • Fourteen methods behind one interface. Variance-based, screening, moment-independent, kernel and surrogate methods share the same Problem, sample and result types.
  • Dependent inputs. Correlated, custom-sampled and categorical inputs are supported, with methods whose indices keep their meaning under dependence.
  • CPU, GPU or TPU. The same code runs on any device JAX supports.

Install

uv add jaxgsa

Python 3.12 or newer is required. If you do not use uv, install with pip install jaxgsa.

First analysis

This example uses the Ishigami test model, whose sensitivity indices are known. Save it as first_analysis.py and run uv run first_analysis.py:

import jaxgsa
from jaxgsa.benchmarks.ishigami import PROBLEM, evaluate

# Draw the structured input values Sobol analysis needs.
design = jaxgsa.sobol.sample(PROBLEM, n_samples=4096, seed=42, verbose=False)

# In your work, replace this call with your model evaluated at design.samples.
Y = evaluate(design.samples)

result = jaxgsa.sobol.analyze(design, Y, verbose=False)
print("S1:", result.S1)
print("ST:", result.ST)

S1 estimates how much output variation an input explains on its own. ST also counts its interactions with other inputs. For this run, x3 has S1 near zero but ST around 0.24: it matters through an interaction with x1. Looking at S1 alone would miss it. These numbers are estimates, so check their uncertainty before making a close decision.

The getting-started tutorial explains each step and how to interpret the result.

Capabilities

jaxgsa provides fourteen analysis methods. Which one fits depends on your model and your question. The table lists what the package supports and where to find a worked example:

Capability Methods Example
Generate a sampling design sobol, efast, morris, kucherenko Basic example
Analyse existing X, Y with no special design borgonovo, hdmr, hsic, optimal_transport, pawn, pce, rank, shapley, vkoga Existing data
Drop failed or NaN model runs (on_invalid="drop") every method except efast Failed runs
Many outputs, or an output over time, in one call all methods Multi-output example
Correlated inputs borgonovo, hdmr, hsic, kucherenko, optimal_transport, pawn, rank, vkoga, shapley with backend="hdmr" Dependent inputs
Categorical inputs borgonovo, optimal_transport, pawn, sobol Categorical example
Lognormal, Weibull, triangular and beta inputs every method except dgsm; efast, hdmr and shapley with backend="hdmr" take triangular and beta only Non-uniform inputs
Gradients of an index differentiable estimator cores Differentiation guide
Bootstrap confidence intervals (n_bootstrap) every method except efast and hsic (HSIC reports permutation p-values) Bootstrap example

The methods guide describes what each method measures and its assumptions. The API reference gives signatures and result fields.

Scalar, multi-output, and time-series results are supported. Thirteen methods also accept output channels with separate, irregular time grids. See the multi-output and irregular-output examples.

More to read

jaxgsa studio

The separate jaxgsa studio runs ported analyses locally in the browser. Its source and development instructions are in web/. The Python package and documentation site have separate builds.

Use with a coding agent

jaxgsa ships an agent skill. It tells a coding agent how to use the API and the caveats of each method. Install it with the skills CLI:

npx skills add DanielePessina/jaxgsa --skill jaxgsa

The CLI asks which agents to install it for, such as Claude Code, Codex or Cursor. To install it for Claude Code in all your projects, add -g -a claude-code.

Develop

git clone https://github.com/DanielePessina/jaxgsa.git
cd jaxgsa
uv sync --extra dev
uv run pytest

See CONTRIBUTING.md. To run the docs locally:

npm --prefix docs install
npm --prefix docs run docs:dev

Cite jaxgsa

For research, please cite jaxgsa and the primary paper for each sensitivity method (see the methods guide). For the software citation, use the general DOI 10.5281/zenodo.22099117, which covers all versions:

In BibTeX:

@software{pessina2026jaxgsa,
  author    = {Pessina, Daniele and Papathanasiou, Maria M.},
  title     = {jaxgsa: Global Sensitivity Analysis in JAX},
  year      = {2026},
  publisher = {Zenodo},
  doi       = {10.5281/zenodo.22099117},
  url       = {https://doi.org/10.5281/zenodo.22099117}
}

Or as a text citation:

Daniele Pessina and Maria M. Papathanasiou (2026). jaxgsa: Global Sensitivity Analysis in JAX. Zenodo. https://doi.org/10.5281/zenodo.22099117

To cite a specific release, use its version DOI instead. The Zenodo record lists the DOI of each release. See CITATION.cff for machine-readable citation metadata.

Acknowledgements

jaxgsa is designed, written and maintained by Daniele Pessina, as part of his work in the Papathanasiou Lab (Life Science and Process Systems Engineering Lab, Imperial College London). The lab supported and funded its development.

Life Science and Process Systems Engineering Lab

License

BSD-3-Clause. See LICENSE.

Metadata

Release files for jaxgsa 1.3.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for jaxgsa 1.3.1
File Size Uploaded Provenance Actions
jaxgsa-1.3.1.tar.gz 5.3 MB With provenance Details for jaxgsa-1.3.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for jaxgsa 1.3.1
File Interpreter ABI Platform Actions
jaxgsa-1.3.1-py3-none-any.whl Python 3 none any Details for jaxgsa-1.3.1-py3-none-any.whl

Total release size: 5.9 MB

Release files / jaxgsa-1.3.1.tar.gz

Download URL jaxgsa-1.3.1.tar.gz
Size 5.3 MB
Tags Source
SHA-256 checksum
How to use checksums
399622c448fe8b450ccb570f953660ed420d0bb8aa37f45700a32860fe8bc61d
BLAKE2b-256 checksum
How to use checksums
6b33165889c4c188358c2e61190ccb25f70ad8b58980d1055068918186235275
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 26, 2026.

Transparency log

Release files / jaxgsa-1.3.1-py3-none-any.whl

Download URL jaxgsa-1.3.1-py3-none-any.whl
Size 630.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
c7af4d3b426fddd89c81efaf81cea56bcd91dbd39b886e1efbb448e616f5803f
BLAKE2b-256 checksum
How to use checksums
7aa8af3d940abf49705b3529d9fff4706ef0fcc58179553075633e9cf9b71beb
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 26, 2026.

Transparency log

Security for jaxgsa 1.3.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for jaxgsa-1.3.1.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 26, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page