initial upload of README.md only

README.md

@@ -1,4 +1,385 @@
-ntchem-mini
-===========
 
-NTChem-mini package
+NTChem-mini
+=============
+
+* draft version: 0.9 (based on NTChem/RI-MP2 dated 2014/10/31)
+* update: 2014/11/24
+* contact: [email protected]
+
+
+About NTChem and NTChem-mini
+--------------------------------
+
+> *この部分は次のURLに書かれた内容から引用・翻訳した。*
+> (河東田さんにチェックを依頼する)
+>
+> https://www.bunken.org/msf/page/2013/pdf/4E12_w.pdf
+>
+> *annual meeting of Japan Society for Molecular Science (2013)*
+
+NTChem is a general purpose software package for ab initio quantum chemistry
+applications.
+NTChem is designed to perform the high-performance computation of large scale
+molecular electronic structures on the supercomputers such as K computer.
+It has been developed with much attention paid to the following aspects.
+(1) Develop the theory and algorithm of computational method for the large size
+molecules, the high-performance computing scheme, the high precision computing
+scheme which other quantum chemistry software can not handle.
+(2) Develop the new software based on the above theory and algorithm, release
+in public, and perform the state of the art computations such as the whole
+protein computation composed of 10000+ atom molecules, and/or 
+the detail chemical reaction tracing analysis of the molecular
+composed of 100+ to 1000 atoms.
+
+NTChem is developed from scratch as the novel domestic software.
+It includes many theoretical methods newly developed for its own,
+as well as the many features that existing software has.
+
+NTChem-mini includes a subset of NTChem known as NTChem/RI-MP2
+that includes the efficient scheme to account for the electron
+correlations based on the resolution of identity second-order Moller Plesset
+perturbation (RI-MP2) method which enables the computation of the large
+molecular systems such as nano-molecules and biological molecules.
+NTChem-mini is a packaged version of NTChem/RI-MP2, including a suite of
+test data, installation write up, and testing procedures.
+
+The parallel program model used in NTChem-mini is MPI and OpenMP.
+
+
+Installation
+------------
+
+The installation steps of NTChem-mini on Linux platform are explained below.
+Confirm first that the prerequisite software is available on the 
+installing platform.
+
++ Prerequisite software:
+  - Fortran compiler
+  - MPI library,
+  - BLAS library
+  - LAPACK library
+
+####step 1. Obtain the distribution package.
+
+Obtain the NTChem-mini package file "ntchem-mini-1.0.tar.gz" from the Fiber
+distribution site.
++ http://fiber-miniapp.github.io/
+
+On an appropriate directory, extract the contents using tar command.
+
+    $ tar -zxf ntchem-mini-1.0.tar.gz
+    $ cd ./ntchem-rimp2
+    $ TOP_DIR=${PWD}
+
+The variable TOP_DIR is used to point the installation directory hereafter .
+This readme file (README.md) is included in the ${TOP_DIR} directory.
+
+
+####step 2.  Choose config_mine for the installing platform.
+
+In the ${TOP_DIR}/platforms subdirectory, there are several
+config_mine.${COMPILER} files where COMPILER value represents the type of
+the compiler or the system type of the installing platform.
+These are small text script files which set the minimum path variables
+for compilation.
+Choose one of these config_mine.${COMPILER} files that matches the installing
+platform, and copy it as config_mine.
+
+    $ ls -go platforms/config_mine.*
+    -rwxr-xr-x 1 1091 Nov  7 00:00 platforms/config_mine.ANY
+    -rwxr-xr-x 1  162 Nov  7 00:00 platforms/config_mine.K
+    -rwxr-xr-x 1  140 Nov  7 00:00 platforms/config_mine.RICC
+    -rwxr-xr-x 1  124 Nov  7 00:00 platforms/config_mine.Tsubame2
+    -rwxr-xr-x 1  125 Nov  7 00:00 platforms/config_mine.c0
+    -rwxr-xr-x 1  246 Nov  7 00:00 platforms/config_mine.gfortran
+    -rwxr-xr-x 1  148 Nov  7 00:00 platforms/config_mine.intel
+    -rwxr-xr-x 1  156 Nov  7 00:00 platforms/config_mine.pgi
+    $ cp config_mine.${COMPILER} config_mine
+
+If the installing platform does not match any of the provided config_mine.*,
+then use config_mine.ANY and edit it to set the appropriate values.
+
+Note that NTChem requires BLAS and LAPACK math libraries.
+K, intel and pgi platforms have their own libraries.
+Gfortran(GNU) does not come with such library. For gfortran, ATLAS library is
+assumed to be installed on the platform. See comments in config_mine.gfortran.
+
+
+####step 3.  Compile and build the executable program
+
+In the ${TOP_DIR} directory, choose or edit the config_mine file as above,
+execute config_mine script and make command.
+
+    $ make distclean
+    $ ./config_mine
+    $ make
+    $ ls -go bin/rimp2.exe 
+    -rwxr-xr-x 1 1556942 Oct 10 10:26 bin/rimp2.exe
+    $ 
+
+Compiling time of the source program should be short, i.e. within a minute.
+After the successful compilation, the executable file "rimp2.ex" should be
+created in the same directory.
+
+#### Installation Example: Installing on K computer
+
+Below is an example of compiling on K computer.
+
+    $ make distclean
+    $ cp platforms/config_mine.K config_mine
+    $ ./config_mine
+    $ make
+    $ ls -go rimp2.ex
+	-rwxr-xr-x 1 1140539 Sept 22 13:35 2014 rimp2.ex
+
+
+#### Installation Example: Intel platform with modulefiles
+
+Below is an example of compiling with Intel compiler, Intel MPI and Intel MKL
+with module environment.
+
+    $ module load intel impi mkl
+    $ cp platforms/config_mine.intel config_mine
+    $ make distclean
+    $ ./config_mine
+    $ make
+    $ ls -go bin/rimp2.exe 
+    -rwxr-xr-x 1 1556942 Oct 10 10:26 bin/rimp2.exe
+
+#### Installation Example: Intel platform without modulefiles
+
+If the installing platform does not support modulefiles,
+then manually set the environment variables for using the compiler software.
+Intel provides the initialization files for each of the components, and it
+is usually simple enough to load the intel environment variables by reading
+those initialization file.
+
+Below is an example of compiling with Intel compiler, Intel MPI and Intel MKL
+using the initialization files for sh/bash.
+Note that the path variables
+INTEL_DIR, I_MPI_ROOT and MKLROOT must be changed according to the
+actual path on the installing platform.
+
+    $ export INTEL_DIR=/usr/local/intel/composer_xe_2013
+    $ source ${INTEL_DIR}/bin/compilervars.sh intel64
+    $ export I_MPI_ROOT=/usr/local/intel/impi/4.1.0.024
+    $ export I_MPI_F90=ifort
+    $ export I_MPI_F77=ifort
+    $ export I_MPI_CC=icc
+    $ export I_MPI_CXX=icpc
+    $ source ${I_MPI_ROOT}/bin64/mpivars.sh
+    $ export MKLROOT=/usr/local/intel/composer_xe_2013/mkl
+    $ source ${MKLROOT}/bin/mklvars.sh intel64
+    $ make distclean
+    $ cp platforms/config_mine.intel config_mine
+    $ ./config_mine
+    $ make
+    $ ls -go bin/rimp2.exe 
+    -rwxr-xr-x 1 1556942 Oct 10 10:26 bin/rimp2.exe
+
+
+Running the small test jobs
+--------------------
+In the ${TOP_DIR}/tests directory , there are several subdirectories
+containing the test data along with the job script.
+
+    $ cd ${TOP_DIR}/tests
+	$ ls -go
+	drwxr-xr-x 2    4096 Nov  5 17:53 c6h6
+	drwxr-xr-x 2    4096 Nov  5 17:53 h2o
+	drwxr-xr-x 2    4096 Nov  5 17:53 taxol
+
+The list of subdirectories and their data type.
++ directory name: data type
+  - c6h6/	benzene RI-MP2/SVP
+  - h2o/	H2O 10mer RI-MP2/cc-pVTZ
+  - taxol/	taxol RI-MP2/cc-pVDZ
+
+
+Each subdirectory contains a group of input files.
+It also contains the job script examples for several platforms.
++ input files:
+  - ${DataName}.Basis
+  - ${DataName}.Basis_RIC
+  - ${DataName}.Geom
+  - ${DataName}.MO
+  - ${DataName}.OrbEne
+  - ${DataName}.SCF_Info
+  - ${DataName}.TotEne
+  - ${DataName}.inp
++ job scripts:
+  - ${PLATFORM}.sh
+
+The ${DataName}.inp is also aliases as "INPUT" file.
+The string value of ${DataName} is given as the namelist variable of &prefix,
+such as Name='taxol_rimp2_cc-pvdz' in "INPUT" file.
+The string value of ${PLATFORM} represents the type of running platform
+or maybe the name of job manager.
+
+
+#### Example: Running the test job on general Linux platform.
+Below is an example of running NTChem-mini interactively using the taxol
+test data on general Linux platform which supports the module environment.
+
+    $ module load intel impi mkl
+    $ cd ${TOP_DIR}/tests/taxol
+    $ NPROCS=8
+    $ export OMP_NUM_THREADS=2
+    $ eval `grep Name INPUT | tr [,] [\ ]`
+    $ time mpirun -np $NPROCS ./rimp2.exe | tee ${Name}.out
+
+If the module environment is not supported on the plarform, then the
+environment variables can be set explicitly as shown in the
+"Installation Example:" section above.
+
+For batch jobs, the job script file with corresponding directives
+should be written.
+Example job script files for some platforms can be found under the
+${TOP_DIR}/tests/* subdirectories.
+
+    $ cd ${TOP_DIR}/tests/taxol
+    $ ls -go *sh
+    -rw-r--r-- 1 1394 Sep 16 17:31 AICS-common.sh
+    -rw-r--r-- 1  862 Sep 16 17:31 Kcomputer.sh
+    -rw-r--r-- 1  627 Sep 16 17:31 RICC_mpc.sh
+    -rwxr-xr-x 1  168 Sep 16 17:31 Tsubame2.sh
+
+
+
+#### Example: Running the test job on K computer
+Below in an example job script for K computer with necessary file staging
+directives.
+
+	pjsub Kcomputer.sh
+
+
+#### Example: Running the test job on Intel platform with LSF
+
+Below is an example of a batch job script with LSF directives 
+
+    $ cat job.sh
+    #BSUB -J BSUB-TAXOL
+    #BSUB -o BSUB-TAXOL-%J
+    #BSUB -n 32
+    #BSUB -R "span[ptile=2]"
+    #BSUB -x
+    module load intel impi mkl
+    set -x
+    date
+    MODEL=taxol
+    DATA_DIR=${HOME}/ntchem/ntchem-rimp2/tests/${MODEL}
+    cd ${DATA_DIR}; if [ $? != 0 ] ; then echo '@@@ Directory error @@@'; exit; fi
+    eval `grep Name INPUT | tr [,] [\ ]`
+    NPROCS=32
+    export OMP_NUM_THREADS=8
+    time mpirun -np $NPROCS ./rimp2.exe | tee ${Name}.out
+    $
+    $ bsub < job.sh
+    $
+
+
+#### Verifying the computed results
+
+The data directory contains a small Python script file "check.py" to verify 
+the computed results recorded in  ${Name}.out file.
+Run this script file and confirm the output message.
+
+    $ python ./check.py
+    The result is OK
+
+
+
+Running the large size performance tests 
+-----------------------------
+
+The default test data included in the above NTChem-mini package are limited
+to small molecular sets in order to make the package compact.
+For running the performance tests, it is recommended to use larger molecular
+data.
+A separate file containing the molecular data suitable for such performance
+test has been made available for downloading from the following site.
+
+http://hpci-aplfs.aics.riken.jp/fiber/ntchem-mini/ntchem-data-perf.tar.gz
+
+> comments. needs updating the URL above.
+
+#### Setting up the performance test data
+
+After the previous Installation steps are completed, download the performance
+data file ntchem-data-perf.tar.gz from the above URL.
+Save it on the ${TOP_DIR} directory and extract the performance data files.
+There should be new data file directories under tests_perf/ .
+
+    $ cd ${TOP_DIR}
+	$ tar -zxf ntchem-data-perf.tar.gz
+	$ ls tests_perf/
+	c54h18_cc-pvdz  c54h18x2_cc-pvdz  c60atc60h28
+	c54h18_cc-pvtz  c54h18x2_cc-pvtz
+
++ directory name: data type
+  - c54h18_cc-pvdz: nanographene C54H18 RI-MP2/cc-pVDZ
+  - c54h18x2_cc-pvdz: nanographene dimer (C54H18)2 RI-MP2/cc-pVDZ
+  - c54h18_cc-pvtz: nanographene C54H18 RI-MP2/cc-pVTZ
+  - c54h18x2_cc-pvtz: nanographene dimer (C54H18)2 RI-MP2/cc-pVTZ
+  - c60atc60h28: buckycatcher C60@C60H28 RI-MP2/cc-pVTZ
++ buckycatcher data _c60atc60h28_ is most appropriate for the
+performance tests.
+
+
+#### Running the performance tests
+Like the default test data included in the NTChem-mini package,
+there is a set of job script files in the performance test data directory
+covering the typical platforms.
+Choose the one that matches the testing plarform.
+Edit it, if necessary, in the same manner as was done for the
+default test data.
+Execute it as a batch job or as a background job.
+The c60atc60h28 buckycatcher job takes about 2 hours using 32 nodes
+on K computer.
+
+
+##### strong scaling tests
+
+The strong scaling tests for NTChem-mini in general can be done by just
+changing the number of MPI processes per job.
+For example, a simple script such as below will define the strong scaling runs
+for 8/16/32 processes.
+
+    $ for NPROCS in 8 16 32
+    $ do
+    $ time -p mpirun -np $NPROCS ./rimp2.exe
+    $ done
+
+In this case, each execution of rimp2.exe reads the same "INPUT" file.
+
+##### weak scaling tests
+
+It is not straight forward to define the test data for evaluating the
+weak scaling performance, since the computational workload of NTChem-mini
+increases at N^5 order accroding to the number of atoms N.
+In order to prepare for the weak scaling performance test, specific testing
+configuration should be defined and the corresponding input data files
+must be generated. Such configuration can be defined through
+the discussion with the authors of NTChem.
+
+
+License term
+-----------------------------
+(河東田さんにLicense条項を確認)
+
+The License term of NTChem is provided in the BSD 2-Clause License.
+Please refer to "LICENSE" file included in the NTChem-mini package.
+
+
+_ contact person/organizatin for NTChem _
+Contact for inquiry regarding NTChem should be made to:
+
+_ Michio Katouda email: <[email protected]> _
+
+Copyright (c) 2012-2014, Computational Molecular Science Research Team,
+RIKEN Advanced Institute for Computational Science
+
+
+<!-- メモ。HTML を入れちゃうとMarkdownの処理と合わない事があるね、、、
+<style type="text/css" > div { width: 700px; } </style> 
+-->