.. Py-ChemShell documentation master file, created by
   sphinx-quickstart on Thu Apr 20 11:57:41 2017.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.

###################
ChemShell tutorials
###################

This page guides you through a series of input scripts for ChemShell. It is
intended that they are followed in the order presented, so as to build up
simple elements that are then re-used. At all stages, it is recommended that
you find the appropriate section of the `manual <../../../manual/build/html/index.html>`_. The manual
is searchable so you should be able to take keywords from the examples.

In most cases the pages below correspond to a directory in the directory
``docs/tutorial/samples`` of your ChemShell distribution and the examples are
provided there with a ``.py`` suffix. Providing ChemShell has been set up 
correctly on your machine, the Unix shell command to run the examples will be:: 

$ chemsh FILENAME.py

.. note:: In this tutorial a dollar symbol ($) indicates that you should 
  type the command that follows in a Unix shell (rather than in ChemShell). 
  The dollar symbol represents the command prompt and should not itself
  be typed in.

.. !!! IMPORTANT NOTE FOR TUTORIAL WRITERS !!!
.. Sphinx toctrees are not flexible enough to generate the layout we would 
.. like for this front page (e.g. numbering of tutorials and interleaving text
.. in and around each section) so they have been hidden and manual links
.. inserted to the tutorials as appropriate.
.. However the toctrees are still necessary in order to generate the correct  
.. sidebar and should be updated whenever a new tutorial is added to the list.

Python basics
=============

ChemShell is controlled by scripts written in the `Python programming language <https://www.python.org/>`_. 
This is a more flexible and powerful approach than the input files normally 
used by computational chemistry codes, but does mean you need to know a few 
simple programming concepts. Although Python is very easy to pick up as you 
go along, we strongly recommend you familiarise yourself with the basics
first in order to understand how ChemShell works.

.. toctree::
   :maxdepth: 1
   :caption: Python basics
   :hidden:

   python_basics

1. :doc:`python_basics` 

A more detailed `Python tutorial <https://docs.python.org/3/tutorial/>`_ is 
available on the Python website if you would like to learn more of the 
language.


First steps with ChemShell
==========================

This section contains a selection of ChemShell data files illustrating simple 
tasks such as single-point energy evaluations and geometry optimisation.

.. toctree::
   :maxdepth: 1
   :caption: First steps with ChemShell
   :hidden:

   single_point
   minimisation
   transition_states
   reaction_paths
   forcefields_gulp
   qmmm_gulp

2. :doc:`single_point`
3. :doc:`minimisation`
4. :doc:`transition_states`
5. :doc:`reaction_paths`
6. :doc:`forcefields_gulp`
7. :doc:`qmmm_gulp`


Case studies
============

This section works through more in-depth examples including solid state 
and liquid-phase systems.

.. toctree::
   :maxdepth: 1
   :caption: Case studies
   :hidden:

   mgo_surface/index
   zeol_covalent/index
   li_mgo/index
   p450_enzyme/index
.. ionic_liquids/index


8.  :doc:`mgo_surface/index`
9.  :doc:`zeol_covalent/index`
10. :doc:`li_mgo/index`
11. :doc:`p450_enzyme/index`

.. :doc:`ionic_liquids/index`

Further reading
===============

In addition to the tutorials, the ChemShell manual provides a comprehensive
guide to the features available in the program.

* `ChemShell user manual <../../../manual/build/html/index.html>`_

Further details on the QM/MM computational technique can be found in the ChemShell publications:
          
* `QUASI: A general purpose implementation of the QM/MM approach and its application to problems in catalysis <https://dx.doi.org/10.1016/S0166-1280(03)00285-9>`_

* `ChemShell - a modular software package for QM/MM simulations <https://dx.doi.org/10.1002/wcms.1163>`_

* `Open-Source, Python-Based Redevelopment of the ChemShell Multiscale QM/MM Environment <https://dx.doi.org/10.1021/acs.jctc.8b01036>`_