README.md 3.14 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25
# ADerrors.jl

Error propagation and analysis of Monte Carlo data with the (``\Gamma``) method and automatic differentiation in `Julia`

The full documentation of the package is available via the usual
[Julia `REPL` help
mode](https://docs.julialang.org/en/v1/stdlib/REPL/#Help-mode-1) and
online in [HTML format](https://ific.uv.es/~alramos/docs/ADerrors/).

This work is an implementation of several ideas in data analysis. 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. DOI: 10.1016/S0010-4655(03)00467-3
- F. Virotta, "Critical slowing down and error analysis of lattice QCD simulations." PhD thesis.
- Stefan Schaefer, Rainer Sommer, Francesco 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. DOI: 10.1016/j.cpc.2018.12.020. 
- M. Bruno, R. Sommer, In preparation.

## Installation

The package in not in the general registry. Still one can use the package manager
```julia
julia> import Pkg
(v1.1) pkg> add https://gitlab.ift.uam-csic.es/alberto/aderrors.jl
```
Alberto Ramos's avatar
Alberto Ramos committed
26 27 28 29 30 31 32 33 34
## Features

- **Exact** linear error propagation, even in iterative algorithms
  (i.e. error propagation in fit parameters).
- Handles data from **any number of ensembles** (i.e. simulations with
  different parameters).
- Support for **replicas** (i.e. several runs with the same simulation
  parameters). 
- Irrelagular MC measurements are handled transparently.
35 36 37 38 39

## Tutorial

It is better to start with the [Getting started](https://ific.uv.es/~alramos/docs/ADerrors/tutorial/) guide.

40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71
# Alleviating time to first run

`Julia` is well known for being slow the first time that you run some
routines. On the first call to a function Julia not only runs the
code, but also compiles it, making the first call slow.
This problem can be alleviated in general with
[PackageCompiler.jl](https://github.com/JuliaLang/PackageCompiler.jl). This
is specially true for the case of `ADerrors` since most functions are
type static. 

As example, the file `extra/typical.jl` contains the most typical
calls to `ADerrors`. One can execute this file telling julia to
annotate the functions that are compiled
```julia
julia --trace-compile=precompile_aderrors.jl typical.jl
```
Now the functions annotated in `precompile_aderrors.jl` can be
compiled and included in a `sysimage` that is autmatically loaded
whenever you start Julia
```julia
julia> using PackageCompiler
julia> PackageCompiler.create_sysimage(:ADerrors; precompile_statements_file="precompile_aderrors.jl", replace_default=true)
```

This will make `ADerrors` from the first call. Obviously you can tune
the file `typical.jl` to your usage, or add other packages. Please
note that packages included in the sysimage are locked to the versions
of the sysimage. If you update `ADerrors` make sure to re-generate the
sysimage. Probably is better to read [the documentation of
PackageCompiler](https://julialang.github.io/PackageCompiler.jl/dev/sysimages/)
in order to fully understand the drawbacks.

72 73