Merge branch 'EasyBuild4'

Doc/UserManual/Installation.tex

 \newpage
-\section{Installation} \SecLabel{installation}
+\section{Installation} \SecLabel{InstallationProcedure}
 
-This section shortly describes how to build \BornAgain\ from source and run first
-simulation.
+This section describes how to build and install \BornAgain\ libraries from source.
+At the moment we support building on x86/x86\_64 Linux and Mac OS X operating systems.
+Support for Windows systems is planned in next releases.
+%In the later releases we are planing to include support for Windows systems and provide
+%binary distributions for major Windows/Mac/Linux.
+There are three major steps to building \BornAgain\ :
+\begin{enumerate}[1.]
+\item Acquire required third-party libraries.
+\item Get \BornAgain\ source code.
+\item Invoke cmake to build and install software.
+\end{enumerate}
+The remainder of this section explains each step in details.
 
+\subsection{Third-party software.}
+To successfully build \BornAgain\ a number of prerequisite packages must be installed.
 
+\begin{itemize}
+\item compilers: clang  versions $\geq 3.1$ or GCC versions $\geq 4.2$
+\item cmake ($\geq 2.8$)
+\item boost library ($\geq 1.48$)
+\item GNU scientific library ($\geq 1.15$)
+\item fftw3 library ($\geq 3.3$)
+\item python ($\geq 2.7$), python-devel, python-numpy-devel
+\end{itemize}
+\vspace*{2mm}
 
-\subsection{Installation hints}
+Other packages are optional
+\begin{itemize}
+\item ROOT framework (adds bunch of additional fitting algorithms to \BornAgain)
+\item python-matplotlib (allows to run usage examples with graphics)
+%\item Eigen3 library ($\geq 3.1.0$)
+\end{itemize}
 
-In this section we give short installation instruction for several selected operation systems.
+All required packages can be easily installed on most Linux distributions using system's package
+manager. Below we give few examples for several selected operation systems. Please note,
+that other distributions (Fedora, Mint, etc) may have different commands for invoking the package manager and slightly different names of packages (like ``boost'' instead of ``libboost'' etc). Besides that, installation should be very similar.
+\vspace*{3mm}
 
 % ---------------
 %  OpenSuse 12.3
 % ---------------
 \noindent
-{\bf OpenSuse 12.3} \newline
+{\large\bf OpenSuse 12.3} \newline
 Adding ``scientific'' repository 
 \begin{lstlisting}[language=shell, style=commandline]
 sudo zypper ar http://download.opensuse.org/repositories/science/openSUSE_12.3 science
@@ -23,12 +52,172 @@ sudo zypper ar http://download.opensuse.org/repositories/science/openSUSE_12.3 s
 \noindent
 Installing obligatory packages
 \begin{lstlisting}[language=shell, style=commandline]
-zypper install gsl-devel boost-devel fftw3-devel python-numpy-devel
+sudo zypper install git-core cmake gsl-devel boost-devel fftw3-devel python-devel python-numpy-devel
 \end{lstlisting}
 
 \noindent
 Installing optional packages
 \begin{lstlisting}[language=shell, style=commandline]
-sudo zypper install libroot-* root-plugin-* root-system-* root-ttf libeigen3-devel
+sudo zypper install libroot-* root-plugin-* root-system-* root-ttf libeigen3-devel python-matplotlib
 \end{lstlisting}
+\vspace*{3mm}
+
+
+% ---------------
+%  Ubuntu 13.04
+% ---------------
+\noindent
+{\large\bf Ubuntu 13.04} \newline
+Installing obligatory packages
+\begin{lstlisting}[language=shell, style=commandline]
+sudo apt-get install git cmake libgsl0-dev libboost-all-dev libfftw3-dev python-devel python-numpy
+\end{lstlisting}
+
+\noindent
+Installing optional packages
+\begin{lstlisting}[language=shell, style=commandline]
+sudo apt-get install libroot-* root-plugin-* root-system-* ttf-root-installer libeigen3-dev python-matplotlib python-matplotlib-tk
+\end{lstlisting}
+\vspace*{3mm}
+
+
+% ---------------
+%  MacOS 10.8
+% ---------------
+\noindent
+\noindent
+{\large\bf Mac OS X 10.8} \newline
+To simplify installation of third party open-source software on a Mac OS X system we recommend the use of \Code{MacPorts} package manager. 
+The easiest way to install MacPorts is by downloading the \Code{dmg} 
+from \url{www.macports.org/install.php} and running the system's installer.
+After installation new command ``\Code{port}'' will be available in terminal window of your Mac. \
+
+\noindent
+Installing obligatory packages
+\begin{lstlisting}[language=shell, style=commandline]
+sudo port -v selfupdate
+sudo port install git-core cmake
+sudo port install fftw-3 gsl
+sudo port install boost -no_single-no_static+python27 
+
+
+\end{lstlisting}
+
+\noindent
+Installing optional packages
+\begin{lstlisting}[language=shell, style=commandline]
+sudo port install py27-matplotlib py27-numpy py27-scipy
+sudo port install root +fftw3+python27
+sudo port install eigen3
+\end{lstlisting}
+
+
+
+
+\subsection{Getting source code}
+\BornAgain\ source can be downloaded at \url{http://apps.jcns.fz-juelich.de/BornAgain}
+and unpacked with
+\begin{lstlisting}[language=shell, style=commandline]
+tar xfz bornagain-<version>.tgz
+\end{lstlisting}
+
+\noindent
+Alternatively one can obtain \BornAgain\ source from our public Git repository.
+\begin{lstlisting}[language=bash, style=commandline]
+git clone git://apps.jcns.fz-juelich.de/BornAgain.git 
+\end{lstlisting}
+\vspace*{3mm}
+
+
+\noindent
+{\bf\large More about Git} \\
+Our Git repository holds two main branches called ``master'' and ``develop''. We consider ``master''
+branch to be the main branch where the source code of HEAD always reflect latest stable release. Git clone command shown above
+\begin{enumerate}[1.]
+\item Gives you source code snapshot corresponding to the latest stable release
+\item Automatically sets up your local master branch to track our remote master branch, 
+so you will be able to fetch changes from remote branch at any time using ``git pull'' command.
+\end{enumerate}
+
+Master branch is updating approximately once per month, that reflects our release cycle.
+The second main branch, ``develop'' branch, is a snapshot of current development.
+This is where any automatic nightly builds are built from. The develop branch is
+expected always to work, so to get the most recent features one can switch source tree to it by
+\begin{lstlisting}[language=bash, style=commandline]
+cd BornAgain
+git checkout develop
+git pull
+\end{lstlisting}
+\vspace*{3mm}
+
+
+
+\subsection{Building and installing the code}
+
+\BornAgain\ should be build using \Code{CMake} cross platform build system. 
+Having third-party libraries installed on the system and \BornAgain\ source code acquired as was explained in
+previous sections, type build commands
+\begin{lstlisting}[language=bash, style=commandline]
+mkdir <build_dir>
+cd <build_dir>
+cmake <source_dir> -DCMAKE_INSTALL_PREFIX=<install_dir>
+make
+\end{lstlisting}
+\vspace*{3mm}
+
+Here \Code{<source\_dir>} is the name of directory, where \BornAgain\ source code has been
+copied, \Code{<install\_dir>} is the directory, where user wants  the package
+to be installed, and \Code{<build\_dir>} is the directory where building will occur.
+
+\MakeRemark{About CMake}{
+\\ Having dedicated directory \Code{<build\_dir>} for build process
+is recommended by CMake. That allows several builds with different compilers/options from the same source and keeps source directory clean from build remnants.
+}
+
+Compilation process invoked by the command ``make'' lasts about 10 min for average laptop
+of 2012 edition. On multi-core machines the compilation can be speed up by invoking command
+make with the parameter ``make -j[N]'', where N is the number of cores.
+
+Running functional tests is an optional but recommended step. Command ``make check''
+will compile several additional tests and run them one by one. Every tests contains
+simulation of typical GISAS geometry and comparison of simulation results with reference files on numerical level. Having 100\% tests passed ensures that your local installation
+is correct.
+\begin{lstlisting}[language=bash, style=commandline]
+make check
+...
+100% tests passed, 0 tests failed out of 26
+Total Test time (real) = 89.19 sec
+[100%] Build target check
+\end{lstlisting}
+\vspace*{3mm}
+
+
+The last command ``make install'' copies compiled libraries and some usage examples
+into  installation directory.
+\begin{lstlisting}[language=bash, style=commandline]
+make install
+\end{lstlisting}
+\vspace*{3mm}
+
+
+\subsection{What is the next?}
+
+In your installation directory you will find
+\begin{lstlisting}[language=bash, style=commandline]
+./include - header files for compilation of your C++ program
+./lib - libraries to import into python or link with your C++ program
+./Examples - directory with examples
+\end{lstlisting}
+
+Run your first example and enjoy your first BornAgain simulation plot.
+\begin{lstlisting}[language=bash, style=commandline]
+cd <install_dir>/Examples/python/ex001_CylindersAndPrisms
+python CylindersAndPrisms.py
+\end{lstlisting}
+
+
+
+
+
+
 

Doc/UserManual/Introduction.tex

 \newpage
-\section{Introduction}
+\chapter{Introduction}
 
 \BornAgain\ is a  software to simulate and fit neutron and X-ray
 scattering at grazing incidence. It is a multi–platform open–source project that aims at supporting scientists in the analysis and fitting

Doc/UserManual/QuickStart.tex

@@ -6,13 +6,16 @@ simulation. More details about software architecture and installation
 procedure are given in \SecRef{SoftwareArchitecture} and \SecRef{InstallationProcedure}. \\
 
 \noindent
-{\bf Step I: $~$ installing third party libraries}
+{\bf Step I: $~$ installing third party software}
 \begin{itemize}
+\item compilers: clang  versions $\geq 3.1$ or GCC versions $\geq 4.2$
+\item cmake ($\geq 2.8$)
 \item boost library ($\geq 1.48$)
 \item GNU scientific library ($\geq 1.15$)
 \item fftw3 library ($\geq 3.3.1$)
-\item Eigen3 library ($\geq 3.1.0$), optional
-\item ROOT framework ($\geq 5.34.00$), optional
+\item python-2.7, python-devel, python-numpy-devel
+%\item Eigen3 library ($\geq 3.1.0$), optional
+%\item ROOT framework ($\geq 5.34.00$), optional
 \end{itemize}
 \vspace*{2mm}
 

Doc/UserManual/UserManual.tex

@@ -93,6 +93,7 @@
 %----------------------------------------------------------------------------------------
 \usepackage{listings}
 \usepackage{lstcustom}
+\usepackage{enumerate}
 \renewcommand{\lstfontfamily}{\ttfamily}
 %----------------------------------------------------------------------------------------
 %	COLORS
@@ -102,9 +103,6 @@
 \definecolor{lightgrey}{rgb}{0.9,0.9,0.9}
 
 
-%----------------------------------------------------------------------------------------
-%	COMMANDS
-%----------------------------------------------------------------------------------------
 %----------------------------------------------------------------------------------------
 %       Commands
 %----------------------------------------------------------------------------------------
@@ -113,6 +111,9 @@
 \newcommand{\IsGISAXS}{\Code{IsGISAXS}}%
 \newcommand{\SecLabel}[1]{\label{sec:#1}}%
 \newcommand{\SecRef}[1]{Section~\ref{sec:#1}}% 
+\newcommand{\MakeRemark}[2]
+{ \noindent \smallpencil \colorbox{Lightgray}{\parbox{\dimexpr\linewidth-8\fboxsep}			{\underline{#1} #2 }}
+}
 
 
 %----------------------------------------------------------------------------------------
@@ -139,27 +140,18 @@ keepaspectratio]{results2_2.png}%
 \vfill
 }}}
 
+
 %----------------------------------------------------------------------------------------
 %	DOCUMENT
 %----------------------------------------------------------------------------------------
-
 \begin{document}
 
-%\AddToShipoutPicture*{\BackgroundPic} % add background image to the
-%first page
 \maketitle
-
-
-%\begin{abstract}
-%This document describes the general architecture of the BornAgain project.
-%\end{abstract}
-
 \tableofcontents
 %\lstlistoflistings
 %\listoffigures
 %\listoftables
 
-
 \input{Introduction}
 \input{QuickStart}
 \input{SoftwareArchitecture}
@@ -171,15 +163,9 @@ keepaspectratio]{results2_2.png}%
 %\appendix
 %\input{Appendix}
 
-
-%\printindex
-%generate an index - hyperref
-
 \bibliography{ref}
 \bibliographystyle{unsrt}
 
 
-
-
 \end{document}
 

INSTALL

-Installation:
+Brief Installation instruction for BornAgain framework
 
-see the online documentation at http://apps.jcns.fz-juelich.de/BornAgain
+Detailed installation instructions can be found in User Guide available at
+http://apps.jcns.fz-juelich.de/BornAgain
 
-Installation instructions for *nix:
-1) Install dependencies
 
+-------------------------------------------------------------------------------
+1) Install third party software
+-------------------------------------------------------------------------------
+Required:
+* compilers: clang  versions >=3.1 or GCC versions >=4.2
+* cmake >=2.8
+* boost library >=1.48
+* GNU scientific library >= 1.15
+* fftw3 library >=3.3
+* python >=2.7, python-devel, python-numpy-devel
 
-\item boost library ($\geq 1.48$)
-\item GNU scientific library ($\geq 1.15$)
-\item fftw3 library ($\geq 3.3.1$)
-\item Eigen3 library ($\geq 3.1.0$), optional
-\item ROOT framework ($\geq 5.34.00$), optional
\ No newline at end of file
+Optional:
+* python-matplotlib (allows to run usage examples with graphics)
+* ROOT framework (adds bunch of additional fitting algorithms to BornAgain)
+
+
+-------------------------------------------------------------------------------
+2) Getting the source
+-------------------------------------------------------------------------------
+git clone git://apps.jcns.fz-juelich.de/BornAgain.git 
+
+
+-------------------------------------------------------------------------------
+3) Building with CMake
+-------------------------------------------------------------------------------
+mkdir <build_dir>
+cd <build_dir>
+cmake <source_dir> -DCMAKE_INSTALL_PREFIX=<install_dir>
+make
+make check
+make install
+
+
+-------------------------------------------------------------------------------
+4) Running first simulation
+-------------------------------------------------------------------------------
+cd <install_dir>/Examples/python/ex001_CylindersAndPrisms
+python CylindersAndPrisms.py

README

+A software to simulate and fit neutron and x-ray scattering at grazing incidence 
+(GISANS and GISAXS), using distorted-wave Born approximation (DWBA).
+
+license :  GNU General Public License v3 or higher (see Doc/COPYING)
+homepage:  http://apps.jcns.fz-juelich.de/BornAgain
+
+
+