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.