===============
Dacapo Tutorial
===============

How to run Dacapo from CamposASE2
=================================

.. contents::

--------------------
Tutorial 1: CO dimer 
--------------------

Let's try to set up a CO dimer calculation. This is about as simple as
it may get::

	"""CO dimer in a box."""

	import os
	from Dacapo import Dacapo
	from ASE import Atom, ListOfAtoms

	atoms = ListOfAtoms([Atom('C', (2, 2, 2)),
                             Atom('O', (3.1, 2, 2))],
                     	     cell=(4, 4, 4), periodic=1)

	calc = Dacapo(planewavecutoff=300,    # in eV
                      nbands=10,              # 5 extra empty bands
                      out='CO_in_a_box.nc',
                      txtout='CO_in_a_box.txt')

        atoms.SetCalculator(calc)

        energy = atoms.GetPotentialEnergy()


If you have completed the installation of Dacapo and CamposASE2, you may save
the code piece above in a file (``CO.py``) and execute it with the
command ``python CO.py``.

OK, what is going on here? Let's go through this first script, line by
line::

  from Dacapo import Dacapo
  from ASE import Atom, ListOfAtoms

will define the classes ``Dacapo``, ``ListOfAtoms`` and ``Atom``.  A class
is sort of a template for creating objects - like here::

  atoms = ListOfAtoms([Atom('C', (4, 4, 4)),
                       Atom('O', (5.1, 4, 4))],
                      cell=(8, 8, 8), periodic=1)
    
Here we create a ``ListOfAtoms`` object from a list of ``Atom`` objects
and a ``cell`` keyword argument giving the size of the unit cell.  The
``periodic=1`` argument indicates that periodic boundary conditions
are used.  A plane wave calculations needs to have periodic
boundary conditions. In the example above, this is a dummy box that
contains the CO molecule. 

The statement::

       calc = Dacapo(planewavecutoff=300,    # in eV
                      nbands=10,              # 5 extra empty bands
                      out='CO_in_a_box.nc',
                      txtout='CO_in_a_box.txt')


will create a Dacapo calculator using a planewave cutoff of 300 eV, 10
electronic bands, and the file 'CO_in_a_box.nc' for output.  By
default, the CamposASE units are Angstrom and eV.  All lines starting
with "#" are comments, similarly to common shell languages. More
precisely, "#" means that the rest of the line is a comment, so that
you may also put comments after statements.

The plane wave cutoff and the number of bands are - apart from specifying the atoms - the
only calculational parameters you as a minimum need to provide. 



