PyXis

PyXis is a Python package for the statistical analysis of lattice field theory data. It provides automatically propagates uncertainty on Monte Carlo observables through resampling (jackknife and bootstrap). Correlated and uncorrelated fits in both the frequentist and the Bayesian framework, and model averaging are also available

Distribution: PyXis  ·  importable as pyxis.

PyXis takes its name from the greek πυξίς, a small box in which valuables were kept. Lattice field theories live in a finite volume (a box) and this package is built to analyse what comes out of it.

---

Table of Contents

• Features
• Requirements
• Installation
• Quickstart
• More complete examples
• Sanity checks
• Project layout
• License
• Bug reports
• Authors and contact

---

Features

Observables and error propagation

• Obs, ObsArray, Corr and CMatrix carry their resamples: every arithmetic operation and every mathematical function (sqrt, log, exp, sin, cos, acosh, abs, first_diff, gradient, ...) propagates the uncertainty and correlations automatically.
• Jackknife method is the default; calling setup_bootstrap(nb) on the Ensemble switches to bootstrap method.
• Observables from different ensembles are combined into a SimpleObs and the error is propagated assuming they are statistically independent.
• Complex observables are supported, with real and imaginary parts propagated independently (real, imag, isrealobj, iscomplexobj).
• FromData builds the appropriate object from the shape of the raw data: 1D → Obs, 2D → Corr, 4D → CMatrix. ObsFromResamples imports already-resampled data.

Ensembles, autocorrelation and binning

• Ensemble collects the properties of a gauge ensemble and sets up the resampling.
• Autocorrelation function and integrated autocorrelation time, binning and find_optimal_bin_size, reweighting.

Fits

• fit — frequentist fit built on scipy.optimize, correlated or uncorrelated, applied directly to Obs/Corr objects.
• lsqfit_fit — interface to lsqfit/gvar, parallelized over the resamples through pathos.
• bayesian_fit — MAP estimate with priors, minimized with iminuit or scipy minimizers.
• Priors: Normal, LogNormal, HalfNormal, Cauchy, Exponential, Gamma.
• Generalized chi-square and p-value for uncorrelated fits on correlated data, SVD cut of the covariance matrix.

Models

• Ready-made models: linear_MODEL, quadratic_MODEL, cubic_MODEL, const_MODEL, logC_MODEL, eff_mass_MODEL, single_exp_MODEL, double_exp_MODEL, three_exp_MODEL, n_exp_MODEL, linear_with_exponential_correction_MODEL, each with its analytic jacobian and a jax counterpart.
• n_exponential_model, ConspiracyModel and AgnosticModel for multi-exponential simultaneous fits with identical or distinct scatterers; SearchCorrelatorModel to scan over fit ranges and number of states.
• SimFit for frequentist simultaneous fits of several correlators.
• test_jacobian checks a user-supplied jacobian against the model.

Model averaging

• model_average combines the fits of a dictionary of models, weighting them with the information criteria provided by pyaic: the standard AIC, the regularization-independent RIAIC and its Bayesian extension RIBAIC.

Linear algebra and spectroscopy

• GEVP for generalized eigenvalue problems on correlation matrices, apply_svdcut, matmul, eig, diag, is_positive_definite.
• Effective masses and plateau search on correlators (find_plateaux).

Reproducibility

• pyxis.random.seed(n) sets a package-wide generator, retrievable with get_rng(), with get_state/set_state for advanced use.

---

Requirements

• Python ≥ 3.13
• gvar ≥ 13.1, iminuit ≥ 2.31, jax ≥ 0.6, lsqfit ≥ 13.3, matplotlib ≥ 3.10, numpy ≥ 2.3, pathos ≥ 0.3.4, scipy ≥ 1.16
• pyaic — installed automatically from GitHub, so git and network access are needed at installation time.

---

Installation

1. Clone the repository

git clone https://github.com/laudid46/pyxis.git
cd pyxis

2. Create and activate a virtual environment (recommended)

python3.13 -m venv .venv
source .venv/bin/activate           # macOS / Linux
# .\.venv\Scripts\Activate.ps1      # Windows PowerShell

3. Install the package

For regular use:

pip install .

For development (changes to the source are picked up immediately):

pip install .                # regular installation
pip install -e .             # editable installation
pip install -e ".[test]"     # editable, with the test dependencies

4. Check the installation

From the repository root:

pytest               # test package installation

This requires the test extra (see above). Expected output: 22 passed.

---

Quickstart

Observables and error propagation

import numpy as np
import pyxis as pyx

ncfg = 500
data = np.random.normal(1.0, 0.2, size=ncfg)

# jackknife (default)
ens = pyx.Ensemble(name="ensemble-1", nc=ncfg)
obs = pyx.Obs("obs", ens, data)
obs.show()

# bootstrap: same ensemble, resampling declared upfront
ens.setup_bootstrap(1000)
obs_boot = pyx.Obs("obs-boot", ens, data)
obs_boot.show()

# derived observables: the uncertainty is propagated through the resamples
derived = pyx.sin(pyx.log(obs_boot)) + pyx.exp(obs_boot)
derived.show()

Correlated fit, frequentist and Bayesian

import numpy as np
import pyxis as pyx

tmax, ncfg = 30, 1000
ens = pyx.Ensemble("test-ensemble", ncfg)

# mock data lying on 0.42 + 1.23 * t, with noise on both parameters
t = np.arange(tmax)
slope = 1.23 + np.random.normal(0.0, 0.1, (ncfg, tmax))
inter = 0.42 + np.random.normal(0.0, 0.5, (ncfg, tmax))
line = (slope * t + inter).T          # shape (tmax, ncfg) -> Corr

data = pyx.FromData(line, ens, "line")

# frequentist, correlated fit
res = pyx.fit(pyx.linear_MODEL, data.trange, data,
              sigma=data.covariance, p0=[0.0, 0.0], absolute_sigma=True)
res.show()

# Bayesian fit (MAP) with Gaussian priors
priors = [pyx.Normal("a", mu=data.mean[0], sigma=data.mean[0]),   # intercept
          pyx.Normal("b", mu=0.0, sigma=2.0)]                     # slope

res = pyx.bayesian_fit(priors, data, model=pyx.linear_MODEL,
                       x0={"a": 0.0, "b": 0.0}, sigma=data.covariance)
res.show()

Note. The order of the priors in the list must match the order in which the parameters are passed to the model function. Swapping them silently gives wrong results.

---

More complete examples

The examples/ directory doubles as a collection of worked examples; examples/INDEX describes each of them in one line. A few entry points:

file	topic
check1.py, check2.py	error propagation with bootstrap and jackknife
check10.py, check12.py	autocorrelation, integrated autocorrelation time, optimal bin size
check14.py, check19.py	effective mass and plateau extraction
check15.py, check16.py	model averaging, standard and simultaneous fits
check20.py	correlation matrices and GEVP
check23.py, check24.py	standard and Bayesian fits, single and simultaneous
check27.py – check29.py	correlated vs uncorrelated fits
check30.py – check40.py	ConspiracyModel and AgnosticModel
check41.py – check58.py	jacobians of all the models

---

Sanity checks

The checks are plain scripts, run one at a time:

cd examples
python check1.py

Run them from inside examples/: some of them read data/data.txt through a relative path.

---

Project layout

PyXis/
├── LICENSE                 # GPL-3.0
├── README.md               # this file
├── pyproject.toml          # metadata and dependencies
├── pyxis/
│   ├── __init__.py         # re-exports the whole public API
│   ├── __version__.py
│   ├── obs.py              # Obs, ObsArray, Corr, CMatrix, SimpleObs
│   ├── ensemble.py         # Ensemble: configurations, binning, bootstrap
│   ├── data.py             # FromData, ObsFromResamples, slicing helpers
│   ├── models.py           # fit models, jacobians, SimFit,
│   │                       # ConspiracyModel, AgnosticModel
│   ├── optimize.py         # fit, lsqfit_fit, bayesian_fit, model_average
│   ├── stat.py             # priors, likelihood, posterior
│   ├── linalg.py           # GEVP, svd cut, matrix utilities
│   ├── random.py           # package-wide random generator
│   └── utils.py            # logger, test_jacobian
├── examples/
│   ├── INDEX               # one-line description of every check
│   ├── check1.py …         # sanity checks
│   └── data/
│       └── data.txt        # reference dataset
├── tests/
│   ├── test_00.py          # test to check installation
└── doc/
    └── pyxis_logo.png      # pyxis logo

---

License

Distributed under the GNU General Public License v3.0 (GPL-3.0). See the LICENSE file for the full terms.

---

Bug reports

https://github.com/laudid46/pyxis/issues

---

Authors and contact

Davide Laudicina — davide.laudicina@ruhr-uni-bochum.de

Repository: https://github.com/laudid46/pyxis