Welcome to ChemShell!

To install ChemShell please follow the instructions Installing ChemShell in the INSTALL file.

Running ChemShell: A Quick-Start Guide

After successful compile, a ChemShell runtime script

YOUR_CHEMSH_ROOT/bin/CHEMSH_ARCH/chemsh

and binary

YOUR_CHEMSH_ROOT/bin/CHEMSH_ARCH/chemsh.x

will be installed, where CHEMSH_ARCH can be “intel” or “gnu” depending on the compilers you have used (they may coexist).

To print the helper:

YOUR_CHEMSH_ROOT/bin/CHEMSH_ARCH/chemsh -h

Linux PC

Basic run

On a Linux PC, a serial job is run by:

YOUR_CHEMSH_ROOT/bin/CHEMSH_ARCH/chemsh YOUR_CHEMSH_JOB.py > YOUR_CHEMSH_JOB.log

A parallel job, for example, of 4 MPI processes can be run by (use --debug to control how many details are printed):

YOUR_CHEMSH_ROOT/bin/CHEMSH_ARCH/chemsh -np 4 --debug 3 YOUR_CHEMSH_JOB.py > YOUR_CHEMSH_JOB.log

To run a task-farm parallel job consisting of 6 workgroups with 2 MPI processes in each workgroup:

YOUR_CHEMSH_ROOT/bin/CHEMSH_ARCH/chemsh -np 12 -nwg 6 --debug 5 YOUR_CHEMSH_JOB.py > YOUR_CHEMSH_JOB.log
HINT

All commands previously used for running ChemShell are saved in a local file: _chemsh_run.log

Advanced run

To start an (MPI parallel) interactive Python shell with ChemShell:

YOUR_CHEMSH_ROOT/bin/CHEMSH_ARCH/chemsh -np 12 -nwg 6 --debug 5

The above command is equivalent to:

mpirun -np 12 YOUR_CHEMSH_ROOT/bin/CHEMSH_ARCH/chemsh.x -nwg 6 --debug 5

Python interpreter

ChemShell inputs can also be executed in a Python interpreter, as follows:

export PYTHONPATH=YOUR_CHEMSH_ROOT

export CHEMSH_ARCH=intel [or gnu, etc.]

python3 YOUR_CHEMSH_JOB.py

This mode of execution can be useful on local computers (e.g. to aid developers when debugging), but using the chemsh script is in general recommended, especially on HPC systems. Execution via the chemsh script is required for MPI parallel calculations.

HPC platforms

ChemShell installed on a supercomputer normally can preload all necessary modules so you will not have to do it youself. ChemShell by default launches an interactive Python/ChemShell enviroment the same as on a Linux PC, this is to enable small tasks to be completed prior to submitting the heavy compute to the scheduler. for example:

YOUR_CHEMSH_ROOT/bin/intel/chemsh -np 2 -nwg 2 -npmm 1 --debug 5 YOUR_CHEMSH_JOB.py

This will run Chemshell interactively on a login node, which is not always allowed on HPC systems. To submit your job to the scheduling system on the supercomputer provide the –submit flag. You should also set some of the paramters that control your job execution such as wall time, for example:

YOUR_CHEMSH_ROOT/bin/intel/chemsh --submit -A YOUR_ACCOUNT -J YOUR_JOBNAME -wt 24:00:00 -np 1024 -nwg 64 -npmm 8 --debug 3 YOUR_CHEMSH_JOB.py

requests to the job scheduler 1024 MPI processes devided into 64 task-farm workgroups, 8 processes for the MM calculation within a workgroup, and 24 hours of walltime.

Building the documentation

To build the ChemShell manual and tutorial webpages type make in the docs/ directory. You will need to have the Sphinx documentation system installed (sphinx-doc.org). The manual and tutorial can then be opened in any web browser at docs/manual.html and docs/tutorial.html.