File	Date	Author	Commit
batch	2016-04-18	Mario Barbatti	[2f969e] Initial commit
docs	2016-04-18	Mario Barbatti	[2f969e] Initial commit
install	2016-04-18	Mario Barbatti	[2f969e] Initial commit
source	2016-04-18	Mario Barbatti	[2f969e] Initial commit
test-nx	2016-04-18	Mario Barbatti	[2f969e] Initial commit
README.install	2016-04-18	Mario Barbatti	[2f969e] Initial commit

Read Me

----------------------------------------------------------------------
    NEWTON-X Installation Documentation
    Mario Barbatti, July 2007 - June 2015
    www.newtonx.org
----------------------------------------------------------------------

    Contents:

       0. READ ME FIRST
       I. Before installing
      II. Installation
     III. Info concerning compiler
      IV. Info concerning the libraries
       V. Info concerning third-party programs
      VI. More technical information about installation
     VII. Compiling individual programs
    VIII. Adding new programs 
      IX. Online support

----------------------------------------------------------------------
 0. READ ME FIRST
----------------------------------------------------------------------

    NEWTON-X is distributed with binary files statically compiled for 
    Linux. We strongly recommend that you use this version. 
    In this case, you should just:

    1. Unpack the Newton-X distribution.
    2. Set the shell-variable $NX to <install-path>/bin
    3. Run the test jobs to check the installation.

    If you want to install NEWTON-X by yourself, the basic steps are 
    indicated in the next sections.

    Information about version and licence is at 
    source/tools/version.txt

----------------------------------------------------------------------
 I. Before installing
----------------------------------------------------------------------

    For the basic installation of Newton-X with the default options, 
    you need:

    1. INTEL compiler 
    ifort command must be defined. For usage of other compilers see 
    III.

    2. MKL libraryies (software.intel.com/en-us/articles/intel-mkl). 
    See IV below.

    3. GSL libraries (www.gnu.org/software/gsl). 
    If this library is not in a standard path, see IV.

----------------------------------------------------------------------
 II. Installation
----------------------------------------------------------------------

    1. Unpack Newton-X distribution.

    2. Go to the install subdirectory and execute installnx.pl:
    > cd install
    > ./installnx.pl
 
    It will ask you for a installation path.
    It will ask you about which packages you want to install.

    3. After the installation, set the shell-variable $NX to
    <install-path>/bin
    In bash shell: export NX=<install-path>/bin
    In c shell: setenv NX <install-path>/bin

    4. An installation log is written to install/installnx.log.

----------------------------------------------------------------------
 III. Info concerning compiler
----------------------------------------------------------------------

    The default installation option for Newton-X uses the Intel Fortran 
    Compiler. We strongly recomend that you use it.

    You can change the compiler and the compiler options by modifying 
    installnx.pl. To do so, follow the instructions in VI.

    The CIOVERLAP package is distributed with Newton-X but it is 
    composed of an independent set of programs. It is compiled with GCC 
    and GFORTRAN compilers.

----------------------------------------------------------------------
 IV. Info concerning libraries
----------------------------------------------------------------------

    Some programs in NX use the BLAS/LAPACK libraries. In installnx.pl 
    the path to these library is given by the variables $LDFLAGS and 
    $LDLIBS. 

    The default is set to use MKL libraries from INTEL. 
    You should directly set the path to MKL by changing the $LDFLAGS 
    variable in installnx.pl.

    The cioverlap programs use BLAS, LAPACK, and GSL libraries. 

    If the libraries are not installed in the default search paths, 
    you should include these paths in the variables $idgsl (headers) 
    and $ldgsl (libraries) in installnx.pl.

----------------------------------------------------------------------
 V. Info concerning third-party programs
----------------------------------------------------------------------

    The third-party programs interfaced to NEWTON-X should be obtained 
    and installed separatedly. Consult the documentation at docs 
    directory or at www.newtonx.org to see the list of interfaced 
    programs and the web links to them.

----------------------------------------------------------------------
 VI. More technical information about installation
----------------------------------------------------------------------
 
    A. Changing installation options:

    You can change details of the installation mainly by changing 
    the section "SET YOUR CHOICES" below. It contains four parts:

    1) Definition of the fortran compiler:
    $comp        = calling of the Fortran compiler 
                   (eg, ifort for INTEL Fortran)

    2) Definition of libraries (BLAS/LAPACK):
    $LDFLAGS     = path (-L)
    $LDLIBS      = library (-l)

    3) GSL libraries:
    $idgsl       = header path
    $ldgls       = library path

    4) Definition of flags:
    $FFLAGS      = compilation flags

    5) Choice of static/dynamic link of CIOVERLAP.

    Parts 4 and 5 usually do not need be changed. 

    The cioverlap programs are installed using their own makefiles.
    These makefiles will be invoked by this program, but changes
    in the compilation options should be done there. Few options, 
    however, can be selected below, in part (5).

    B. Installation procedure:

    When you run ./installnx.pl, you will be asked for a directory for 
    installation. If the directory does not exist, it will be created.
    If another version of NX is there, the new installation will
    replace the files there.

    After creating the directories, the script copies all files to the
    user-provided installation directory.

    Then, makefiles routines are executed within each directory in 
    source. After compilation, the executables are copied to bin/ and
    executables and object files are removed from source.

    installnx.pl is a Perl routine, therefore it is necessary to have
    Perl installed in your system. The default path (/usr/bin/perl)
    is given in the first line. You must change it if your Perl
    is installed in another path.

----------------------------------------------------------------------
 VII. Compiling individual programs
----------------------------------------------------------------------

    An individual program in source/<dir>, for example, <file>.f90 can 
    be compiled by:
    > cd source/lib
    > make
    > cd ../<dir>
    > mkdir OBJ_<dir> EXE_<dir>
    > make <file>
    > cp EXE_<dir>/<file> $NX/.

    This procedure is not valid for initcond and CIOVERLAP.

----------------------------------------------------------------------
 VIII. Adding new programs
----------------------------------------------------------------------

    To add a new fortran code to be installed, just add it to the
    makefile routine in the proper source directory.

    To add a new perl code (or other files that do not need compilation)
    check whether it is already being copied by the *pl commands in
    copy_nx routine. If not, add it to this routine.

    Check whether the correct permission is being set in end_install
    routine.

----------------------------------------------------------------------
 IX. Online support
----------------------------------------------------------------------

    For more information, visit the Newton-X website at www.newtonx.org

    For support, visit the Newton-X discussion group at:
    https://groups.google.com/d/forum/newtonx