Building
========

First you have to install the gsl and nlopt libraries. On Fedora you can
install these with the following command:

    $ yum install gsl gsl-devel NLopt NLopt-devel

Then, to build everything you just type:

    $ make

Some of the test programs also require the plot program which can be installed
with:

    $ yum install plotutils

Fitting Events
==============

You can fit events from SNOMAN data structure files by running the following
command:

    $ ./src/fit [input file] -o [output file]

and then plot the fit results by using the plot script:

    $ ./utils/plot.py [output file]

The plot script relies on the MC information in the SNOMAN file, so make sure
that SNOMAN is set up to output MC info when you simulate events (see the next
section).

Simulating Events with SNOMAN
=============================

Since the fitter reads in SNOMAN data structures it is necessary to use a
command file which correctly specifies the output file format. To benchmark the
fit results it is also necessary to save the initial MC vertex information.

I have created a template command file in macros/mc_run_10000.cmd which
simulates run 10000 from the D2O phase. You can create a proper command file to
run SNOMAN with by running the snogen program which uses a simple templating
system to fill in some variables in this template. For example to simulate 100
1 GeV muons uniformly distributed throughout the AV and with isotropic
directions you can run:

    $ ./macros/snogen -p mu_minus -e 1000.0 -n 100 | /path/to/snoman.exe

See the comment at the top of ./macros/snogen for more information.

Debugging
=========

To debug memory issues you can compile everything with an address sanitizer.
Edit the Makefile and add the following flags:

    CFLAGS=-fsanitize=address
    LDLIBS=-lasan

and make sure that -lasan is the first library in the list. Then, recompile:

    $ make clean
    $ make

and run the fitter. It should crash if there is a buffer overflow or use after
free bug.

You can also run the fitter with valgrind to search for memory leaks:

    $ valgrind --leak-check=full ./src/fit [input file]

Profiling
=========

To profile the code, you can use the linux perf command along with Brendan
Gregg's flamegraph software to produce a flame graph.

First run the fitter:

    $ ./src/fit [input file]

Then, identify the PID of the fit program and run:

    $ sudo perf record -F 99 -p [PID] --call-graph dwarf sleep 10

Then, to create the flame graph:

    $ sudo chown [username]:[username] perf.data
    $ perf script > out.perf
    $ stack-collapse.pl out.perf > out.folded
    $ flamegraph.pl out.folded > kernel.svg