add a README file

1 files changed, 92 insertions, 0 deletions

diff --git a/README b/README
new file mode 100644
index 0000000..951c2df
--- /dev/null
+++ b/README
@@ -0,0 +1,92 @@
+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