Repository

ADerrors.jl

Error propagation and analysis of Monte Carlo data with the $\Gamma$-method and automatic differentiation in Julia.

julia> using ADerrors
julia> a = uwreal([1.0, 0.1], "Var with error")1.0 (Error not available... maybe run uwerr)
julia> b = a^2 + 1.0 / a2.0 (Error not available... maybe run uwerr)
julia> uwerr(b)
julia> println("b = ", b)b = 2.0 +/- 0.1

Features

  • Exact linear error propagation, even in iterative algorithms.
  • Exact linear error propagation in fit parameters, integrals and roots of non-linear functions.
  • Handles data from any number of ensembles (i.e. simulations with different parameters), including replicas (several runs with the same simulation parameters) and irregular MC measurements.
  • Correlations between observables are treated consistently.
  • Fits of uwreal data with expected $\chi^2$ and fit p-values (generalized $\chi^2$ distribution, Imhof method).

Installation

The package is not in the general registry. It depends on BDIO.jl, also not registered; install both with the package manager:

julia> import Pkg
(v1.x) pkg> add https://igit.ific.uv.es/alramos/bdio.jl
(v1.x) pkg> add https://igit.ific.uv.es/alramos/aderrors.jl

Source code

The canonical repository is hosted at the IFIC GitLab. Issues and merge requests should be opened there.

Documentation

  • Getting started — a basic tutorial on uwreal variables, error analysis, and fits.
  • API — reference documentation of the exported functions:
    • Observables: creating uwreal values from MC series on named (possibly replica) ensembles, or from central values with externally known covariances (cobs).
    • Error analysis: the uwerr Γ-method error analysis, with automatic or user-controlled summation windows (wpm).
    • Ensemble ID database: managing ensemble identifiers (change_id, ensembles); thread-safety caveats.
    • I/O: saving and loading observables in BDIO format (write_uwreal, read_uwreal).
    • Correlations: covariance matrices and direct access to the Γ auto- and cross-correlation functions (cov, trcov, trcorr).
    • Inspecting results: central values, errors, autocorrelation diagnostics (taui, rho, window, ...), details, and comparisons and ordering between observables.
    • Error propagation: errors of roots of non-linear functions (root_error) and integrals (int_error).
    • Fits and p-values: errors of fit parameters (fit_error), expected χ² (chiexp) and fit p-values from the generalized χ² distribution (pvalue, Imhof method or Monte Carlo).

The full documentation is also available via the usual Julia REPL help mode (?function_name).

How to cite

If you use this package for your scientific work, please consider citing:

  • U. Wolff, "Monte Carlo errors with less errors". Comput.Phys.Commun. 156 (2004) 143-153.
  • S. Schaefer, R. Sommer, F. Virotta, "Critical slowing down and error analysis in lattice QCD simulations". Nucl.Phys.B 845 (2011) 93-119.
  • A. Ramos, "Automatic differentiation for error analysis of Monte Carlo data". Comput.Phys.Commun. 238 (2019) 19-35.
  • M. Bruno, R. Sommer, Comput.Phys.Commun. 285 (2023), 108643.