# 5. XTP ASE Interface

## 5.1. Installation

### 5.1.1. Environment variables

The environment variable `VOTCASHARE` must be defined in order for the interface to find the default xml files and create the options data structure. You can set this environment variable in your shell configuration file:

    $ export VOTCASHARE=/share/votca/

Or within python itself:

    >>> os.environ['VOTCASHARE'] = '/share/votca/'

## 5.2. Option parser

The XTPOptions class is the preferred handler for setting all the options of the xtp calculator.

## 5.3. XTP calculator

Frequently used options can be specified using the calculator’s set routine.

keyword | type | default value | description
--- | --- | --- | ---
`label` | `str` | None | Name of input and output files
`xc` | `str` | None | XC functional to be used
`basisset` | `str` | None | Basis set to be used
`charge` | int | 0 | Charge of the molecule

## 5.4. Single Point Caclulation

Here is an example of setting up a calculation on a water molecule:

    # Set up a water molecule
    from ase.build import molecule
    wat = molecule('H2O')

    # Set up a XTP calculator
    from pyxtp import xtp

    # change options for the calculations
    calc = xtp(label='water')
    calc.options.dftpackage.functional = 'PBE'
    calc.options.dftpackage.basisset = 'def2-svp'
    calc.options.dftpackage.auxbasisset = 'aux-def2-svp'

    # attach the calculator
    wat.calc = calc

    # compute the energy terms
    wat.get_potential_energy()

## 5.5. Geometry Optimization

Here is an example of setting up a geometry of a carbon monoxide molecule using forces calculated on the first singlet state:

    # Set up a water molecule
    from ase.build import molecule
    co = molecule('CO')
    co.rattle()

    # Set up a XTP calculator
    from pyxtp import xtp

    # change options for the calculations
    calc = xtp()
    calc.options.dftpackage.functional = 'PBE'
    calc.options.dftpackage.basisset = 'def2-svp'
    calc.options.dftpackage.auxbasisset = 'aux-def2-svp'

    # specify the wich forces we want to use
    calc.select_force(energy='singlets', level=0, dynamic=False)

    # attach the calculator
    co.calc = calc

    # compute the energy terms
    from ase.optimize import QuasiNewton
    from ase.io import write
    dyn = QuasiNewton(co, trajectory='test.traj')
    dyn.run(fmax=0.01)
    write('final.xyz', atoms)