# License 
Copyright (c) 2011-, JGU Mainz, Tobias S. Baumann
All rights reserved.

This software was developed at:

	 Institute of Geosciences
	 Johannes-Gutenberg University, Mainz
	 Johann-Joachim-Becherweg 21
	 55128 Mainz, Germany

NAplus is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published
by the Free Software Foundation, version 3 of the License.

NAplus is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with NAplus. If not, see <http://www.gnu.org/licenses/>.

	Tobias Baumann   [baumann@uni-mainz.de]


This documentation is outdated, but will be updated soon. Jan 2016.


This code makes use of subfunctions of the original Neighbourhood algorithm
by M. Sambridge (1999). The original main routine was replaced by a new parallel layout, 
which performs the optimisation without any synchronisation or collective communication.
Our updated parallel framework implements an explicitly handled version of the MPI message 
buffer, and fully non-blocking communication. As a result, the algorithm is highly scalable 
on massively parallel computers. The changes and updates were necessary to explicitly handle
forward models that are computationally intensive and have to be performed in parallel. 

Tobias S. Baumann, Mainz, Germany, January 2013 

Quick reference (February 2013)

(1) Modify Makefile.in
    ... and pay attention to its comments

(2) Compile & link
    - Go to /src
    - make NAplus (clean with make clean_all)
(3) Run the code:
	- Go to /bin
	- mpirun -np X NAplus -groupsize X

    - Outputfiles:
    	- LOG_NAplus_<date_time>_Group<X>.txt (Information provided by the user; works for LaMEM and MATLAB fwrd models)
    	- models_all_ID<X>.bin (File that contains almost all models)
    	- models_own_ID<X>.bin (File that only contains own models

	- Restart an inversion:
		- (1) Run NAplus_binmerge in your working directory
		- (2) mv models_merge.bin models_all.bin
		- (3) switch on the restart option in na.in
		- (4) restart    

(4) Compile utility programs
	- Go to /src
	- make UTILS
 	- I recommend to include $NAPLUS_DIR/bin into your PATH environment. Thus, you don't need to copy utility programs
(5) Use utility programs

(6) MATLAB forward model

	- This task requires additional tuning of your PATH environment and is of course platform dependent.
	- MATLAB_DIR needs to point to the matlab installation directory
	- startup.m and all addpath, genpath,.. etc functions cause runtime problems! use if (~isdeployed) to handle these
	  cases in your code.
	- Use MATLABPATH instead of startup.m and userpath('my/path/to/matlab/home').
	  This sets the "userpath" on UNIX platforms. Be careful. Don't replace, only ADD your own paths

	   export MATLAB_HOME=/gpfs/fs1/home/baumann/01_software/MATLAB
	   export MATLABPATH=$MATLABPATH:/gpfs/fs1/home/baumann/01_software/MATLAB/Milamin_vep_src/kdtree_alg

	- MATLAB documentation recommends to avoid global variables for deployed code	 
	- Modify LD_LIBRARY_PATH; Matlab/NAplus require the following

	   (1) NAplus shared library of MATLAB-forward model
	   (2) MATLAB shared libraries (Important: DO NOT LINK $MATLAB_DIR/sys/os/glnxa64. It might be linked on some 
	       systems, CHECK your LD_LIBRARY_PATH)

	   (2) MATLAB-JAVA shared libraries (optional! probably not needed since display is switch off)

Example 1: RosenBrock3D with paraview output
	- copy na_rosenbrock3D.in from /inputfiles to /bin and rename it to na.in
        - run mpiexec -n 2 -groupsize 1 (using 2 processors)   
	- Run "NAplus_binmerge" in the directory that contains models_own_ID<X>.bin files
	  It creates a file models_merge.bin that holds all models.
	- Run "NAplus_bin2ascii -rank 0 -prefix merge" to convert this file to ascii
	  Run "NAplus_bin2ascii -help" for more help
	- Run "NAplus_ascii2pv3d -p "<pattern of filename(s)>"
	  This converts the ascii file to a paraview file
	  Run "NAplus_ascii2pv3d --help" for more help
	- Use paraview to plot the data with the 'glyph' mode

Example 2: RosenBrock2D with matlab output 
	- copy na_rosenbrock2D.in from /inputfiles to /bin and rename it to na.in
	- run mpiexec -n 2 -groupsize 1 (using 2 processors) 
	- Run "NAplus_binmerge"
	- NAplus_bin2ascii -rank 0 -prefix merge
	- start matlab and load the file with the matlab command:
	  x = data(:,4);
	  y = data(:,5);
	  misfit = data(:,6);
	  scatter(x,y,5,log10(misfit)), colorbar