Completed README.md with overview of Code (included in doxygen-genera…

…ted documentation)

README.md

@@ -1,12 +1,27 @@
 # Accelerator System Simulation Engine
 
-This code base includes:
+![Caption text](doc/reports/physics/figures/Model_hierarchy.png)
+
+## Overview
+
+This code base includes elements to run time-series simulations of an entire accelerator.
+The description of the Physics involved, along with general considerations on the capabilities of the models as well as details on the hierarchy can be found in the `doc/reports/physics/` directory. To generate a PDF version of that document, type:
+
+		$ make physics_model.pdf
+
+The code base (`source/` directory) has three components to it:
 
 * Back-end physics simulator (in C),
+
+	Each element shown in the model hierarchy of the Physics document has a C file associated with it, where the mathematica equations are implemented.
 * Top-level code to configure and run simulations (in Python),
+
+	The main Python program (used to interface with a User interface) is in `source/main.py`.
+	The Python code used to configure the models is in `source/reasjson`, which translates long JSON configuration files into a hierarchical structure of Python objects. The idea behind this setup is that it is easy to find tools to easily generate JSON files, including user-friendly online tools.
+
 * Logic to glue C with Python (SWIG).
 
-Full documenation can be found in the `doc/` directory.
+	The C and the Python code is well partitioned and one should be able to develop them independently, Makefiles handle the magic of generating SWIG wrappers for the Python to interact with the C back-end. SWIG is also useful if someone prefers a language other than Python to run the models.
 
 ## Dependencies
 
@@ -25,7 +40,7 @@ Full documenation can be found in the `doc/` directory.
 
 The version used for development:
 
-		$ swig -version 
+		$ swig -version
 		SWIG Version 3.0.5
 		Compiled with g++ [x86_64-unknown-linux-gnu]
 		Configured options: +pcre
@@ -37,11 +52,71 @@ This version has also been tested to work:
 		Compiled with g++ [x86_64-unknown-linux-gnu]
 		Configured options: +pcre
 
-* Pydot - Python wrapper of Graphviz, used for generating images of connectivities.
 * [Oct2py](https://pypi.python.org/pypi/oct2py): Python to GNU Octave bridge --> run m-files from Python for some unit tests.
+* Pydot - Python wrapper of Graphviz, used for generating images of connectivities.
+* Doxygen - Automatic code documentation
 
-## Dependencies
+		$ doxygen --version
+		1.8.6
+
+## Unit tests
+
+A series of unit tests have been designed for two purposes:
+
+* Provide means for proper development by testing every component of this complicated system independently,
+
+* Illustrate usage:
+
+	All unit tests are written in Python. For a component `X.c` in the back-end code, there is a `X_test.py` program that will parse some JSON configuration for the test and exercise its functionality. Unit tests produce plots (which are all shown and documented in the Physics document), and in some cases they will even return a PASS/FAIL boolean and print out some test results to standard output.
+
+To run all the unit tests sequentially, type (from the top directory):
+
+		$ make unit_tests.log
+
+Once you type that command, a plot will pop on the screen. Close it in order to run the next test and generate a new plot. Once the full test is completed, you can examine the `unit_tests.log` file for some test results. If everything went well, you should see this at the end of the file:
+
+		ooooo ALL TESTS PASSED ooooo
+
+## Documentation
+
+### Physics
+
+Full documentation on the Physics involved in this model, along with general information on the model hierarchy and capabilities can be found in the `doc` directory. As indicated above, to produce the Physics document in PDF form type:
+
+ 		$ make physics_model.pdf
+
+ You can also find presentations in the form of Impress.js websites and LaTeX in the `doc/presentations` directory. For the web presentations, open the index.html files on your browser and navigate using the mouse and keyboard arrows.
+
+ ### Code base
+
+ The code base is fully commented and automatically-generated documentation using Doxygen is available in two forms:
+
+ * HTML
+
+To generate type (from the top level directory):
+
+		$ make doxygen
+
+That command with create a directory called `_doxygen/` in the top directory, and will actually generate the documentation in both HTML and LaTex formats.
+To access the HTML documentation open the `_doxygen/html/index.html` file on your browser.
+
+* PDF (from a LaTeX file)
+
+To generate type (from the top level directory):
+
+		$ make code_map.pdf
+
+This command will make a copy of the PDF available in the top level directory.
+
+To clean up the directory from all files generated by the Makefiles, type:
+
+		$ make clean
+
+## Version control
+
+This code is version controlled using Git, and currently hosted in the ATG group's Gitlab server at LBNL (gitlab.lbl.gov).
+To get access to the code or for any questions feel free to contact me at [email protected].
+
+## Acknowledgments
 
-To run a basic run of unit tests, type (from the top directory):
-
-		$ make unit_tests.log
+Many people has contributed to this work in one way or another over the years. A lot of the Physics came from Larry Doolittle (LBNL) and Paul Emma (SLAC), and many students helped in the different stages of the development, especially Alejandro Queiruga and Daniel Driver from UCB in the initial translation of our legacy Octave/Matlab code into C. Other people who greatly helped include John Byrd and Gang Huang from LBNL, Claudio Rivetta (SLAC), Quim Llimona from Universitat Pompeu Fabra in Barcelona, and Marvin Munoz and Jack Olivieri (once interns at LBNL).

doxygen.config

@@ -32,7 +32,7 @@ DOXYFILE_ENCODING      = UTF-8
 # title of most generated pages and in a few other places.
 # The default value is: My Project.
 
-PROJECT_NAME           = "System Simulation Engine"
+PROJECT_NAME           = "Accelerator System Simulation Engine"
 
 # The PROJECT_NUMBER tag can be used to enter a project or revision number. This
 # could be handy for archiving the generated documentation or if some version

rules.mk

@@ -90,7 +90,7 @@ physics_model.pdf: $(DOC_DIR)/reports/physics/latex/physics_model.pdf
 cavity_model.pdf: $(DOC_DIR)/reports/physics/latex/cavity_model.pdf
 	mv $< $@
 
-doxygen: $(SOURCE_DIR)/*.c $(SOURCE_DIR)/*.py $(SOURCE_DIR)/readjson/*.py
+doxygen: $(SOURCE_DIR)/*.c $(SOURCE_DIR)/*.py $(SOURCE_DIR)/readjson/*.py README.md
 	doxygen doxygen.config
 	@echo "Code documentation can be found in the _doxygen/ directory in HTML and LaTex formats"