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).