The Cluster-in-Molecules method

sequential and parallel execution

If the user is not interested in parallel CIM calculations, 
MTDCIM must be set at 0, which is a default value, and no 
additional steps have to be taken. If the user is 
interested in a parallel execution, MTDCIM must initially 
be set at 1 to prepare for individual subsystem GAMESS 
runs, and then, after the individual subsystem runs are 
completed, reset to 2 to complete the CIM calculation. When 
MTDCIM is initially set at 1, multiple input files 
$JOB.Sys-N.inp for individual subsystem calculations with 
GAMESS, which can be run independent of one another, and 
the $JOB.cim file, which contains the information about all 
subsystems needed to complete the CIM calculation, are 
automatically generated, and the program stops awaiting 
further execution. Each subsystem N has then to be run as 
an independent GAMESS calculation using the $JOB.Sys-N.inp 
input file. This produces the $JOB.Sys-N.cim files which 
contain the information about the correlation energy 
contributions due to the occupied LMOs central in 
subsystems. All $JOB.Sys-N.cim files resulting from the 
individual subsystem calculations with GAMESS and the 
$JOB.cim file are used to assemble the final results of a 
CIM calculation for the entire system. In order to 
accomplish this and complete the CIM run, one has to reset 
MTDCIM in the main $JOB.inp input file to 2 and run GAMESS 
again.

restarts

If any of the subsystem GAMESS calculations using the 
$JOB.Sys-N.inp input files fails, the user can always rerun 
it (editing the corresponding $JOB.Sys-N.inp file(s), if 
need be), and then use MTDCIM=2 to complete the desired CIM 
calculation for the entire system. This applies to 
sequential and parallel CIM calculations. In the latter 
case, this is a natural consequence of the way the parallel 
execution is structured (see note 1). In the former case 
(MTDCIM=0), if the entire calculation is completed, the 
$JOB.Sys-N.* subsystem files are deleted, but if one of the 
subsystem calculations fails, the program aborts, leaving 
all $JOB.Sys-N.inp input files, the $JOB.Sys-N.cim output 
files from the completed subsystem calculations, and the 
$JOB.cim file on the disk. One can rerun the subsystem 
GAMESS calculation that failed, editing the corresponding 
$JOB.Sys-N.inp file if need be, and the remaining subsystem 
calculations, and then, once all subsystem GAMESS runs are 
completed, finish the calculation by using MTDCIM=2 in the 
main $JOB.inp input. This has an advantage over the more 
automated method of restarting the sequential CIM 
calculations described below in that the Hartree-Fock and 
orbital localization calculations for the entire system do 
not have to be repeated.

If the sequential (MTDCIM=0) run does not complete due to 
the failure of one of the subsystem GAMESS calculations, 
one can also follow a simpler, more automated restart 
strategy. At the time of failure, all $JOB.Sys-N.inp input 
files, the $JOB.Sys-N.cim output files from the completed 
subsystem calculations, and the $JOB.cim file are saved on 
the disk. After inspecting the main output file, the user 
can simply delete the $JOB.dat file and the $JOB.Sys-N.cim 
file resulting from the failed subsystem calculation, edit 
the corresponding $JOB.Sys-N.inp file, if necessary, and 
rerun the GAMESS calculation with MTDCIM=0. The Hartree-
Fock and orbital localization calculations for the entire 
system will be performed again, but the user will avoid the 
need for running individual subsystem calculations one-by-
one, as described above.

the cimshell script

The Python script "cimshell" that automatically produces 
typical $JOB.sh files for parallel OpenMP and MPI subsystem 
calculations using the $JOB.Sys-N.inp files can be found in 
$GMS_PATH/tools/cim/, where $GMS_PATH is the GAMESS main 
directory. In order to run the subsystem calculations with 
OpenMP or MPI, and with the help of the "cimshell" script, 
the following steps should be performed:
    1. Run GAMESS CIM calculation using MTDCIM=1 to produce
       the $JOB.Sys-N.inp and $JOB.cim files.
    2. After all subsystem $JOB.Sys-N.inp input files are
       generated, use "cimshell" to automatically generate
       the OpenMP or MPI script $JOB.sh for parallel
       execution. By default, the "cimshell" program must
       be run in the directory where the $JOB.inp and all
       $JOB.Sys-N.inp files reside. For example, "cimshell
       --np 4 $JOB" generates the $JOB.sh script for an
       OpenMP parallel calculation on 4 cores, whereas
       "cimshell --np 8 --para mpi --submit pbs --MPI_EXEC
       mpiexec $JOB" generates the $JOB.sh script for an
       MPI parallel calculation on 8 processors using the
       PBS queue system for submitting the job. In these
       two examples, we are assuming that the "cimshell"
       has been copied to the directory where all
       $JOB.Sys-N.inp files reside; this can be altered by
       redefining the $PATH variable (adding
       $GMS_PATH/tools/cim/ to it). Use "cimshell -h" for
       more information about the "cimshell" options.
    3. Run or submit the $JOB.sh script to have subsystem
       calculations performed in parallel. In order to do
       this, the user must compile the ompjob.for (the
       OpenMP case) or mpijob.for (the MPI case) programs
       that reside in $GMS_PATH/tools/cim/. The
       corresponding executables used by $JOB.sh are called
       ompjob and mpijob, respectively. The example of the
       Makefile that can be used to install ompjob and
       mpijob can be found in $GMS_PATH/tools/cim/.
    4. After all subsystem calculations are completed, run
       the final GAMESS CIM calculation using the original
       input file $JOB.inp in which with MTDCIM=2. GAMESS
       will automatically find the relevant $JOB.Sys-N.cim
       and $JOB.cim files to complete the CIM calculation
       for the entire system and print the final CIM
       energies in the main output.

CIM references

THE FOLLOWING PAPERS SHOULD BE CITED WHEN USING
CLUSTER-IN-MOLECULE OPTIONS:

DUAL-ENVIRONMENT CIM (CIMTYP=DECIM)
W. LI, P. PIECUCH, J.R. GOUR, AND S. LI,
  J. CHEM. PHYS. 131, 114109-1 - 114109-30 (2009).
SEE, ALSO, S. LI, J. SHEN, W. LI, AND  Y. JIANG,
  J. CHEM. PHYS. 125,  074109-1 - 074109-10 (2006)

SINGLE-ENVIRONMENT CIM (CIMTYP=SECIM,GSECIM)
W. LI, P. PIECUCH, J.R. GOUR, AND S. LI,
  J. CHEM. PHYS. 131, 114109-1 - 114109-30 (2009);
W. LI AND P. PIECUCH, J. PHYS. CHEM. A 114, 8644-8657 
(2010).

IN ADDITION, THE USE OF MULTI-LEVEL CIM SHOULD REFERENCE
W. LI AND P. PIECUCH, J. PHYS. CHEM. A 114, 6721-6727 
(2010).