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