add a README.md

README.md

@@ -0,0 +1,76 @@
+# Statistical analysis
+
+
+## Description
+
+This repository contains source code of two documents
+
+- `lectures`: an summary of the lectures of the course
+
+- `notes`: an explanation of the solutions of the exercises
+
+and the programs written for each exercise (`ex-n` directories)
+
+
+## Building the documents
+
+The two documents `excercise.pdf` and `lectures.pdf` are written in Pandoc
+markdown. XeTeX (with some standard LaTeX packages), the
+[pandoc-crossref](https://github.com/lierdakil/pandoc-crossref) filter and a
+Make program are required to build. Simply typing `make` in the respective
+directory will build the document, provided the above dependencies are met.
+
+
+## Building the programs
+
+The programs used to solve the exercise are written in standard C99 (with the
+only exception of the `#pragma once` clause) and require the following
+libraries to build:
+
+- [GMP](https://gmplib.org/)
+
+- [GSL](https://www.gnu.org/software/gsl/)
+
+* [pkg-config](https://www.freedesktop.org/wiki/Software/pkg-config/)
+  (build-time only)
+
+Additionally Python (version 3) with `numpy` and `matplotlib` is required to
+generate plots.
+
+For convenience a `shell.nix` file is provided to set up the build environment.
+See this [guide](https://nixos.org/nix/manual/#chap-quick-start) if you have
+never used Nix before. Running `nix-shell` in the top-level will drop you into
+the development shell.
+
+Once ready, invoke `make` with the program you wishes to build. For example
+
+    $ make ex-1/bin/main
+
+or, to build every program of an exercise
+
+    $ make ex-1
+
+To clean up the build results run
+
+    $ make clean
+
+
+## Running the programs
+
+Notes:
+
+- Many programs generate random numbers using a PRNG that is seeded with a
+fixed value, for reproducibility. It's possible to test the program on 
+different samples by changing the seed via the environment variable
+`GSL_RNG_SEED`.
+
+
+### Exercise 1
+
+`ex-1/bin/main` generate random numbers following the Landau distribution and
+run a series of test to check if they really belong to such a distribution.
+
+The size of the sample can be controlled with the argument `-n N`.
+
+The program outputs the result of a Kolmogorov-Smirnov test and t-tests
+comparing the sample mode, FWHM and median, in this order.