Calculators

A calculator can be connected to a ListOfAtoms. If the ListOfAtoms is asked for the potential energy, it will ask its calculator to calculate the energy. A calculator may also be able to calculate forces and stresses.

The ASE package includes a very simple calculator based on pair potentials:

>>> from ASE.Calculators.PairPotential import PairPotential
>>> from ASE.IO.NetCDF import ReadNetCDF
>>> water = ReadNetCDF('water.nc')
>>> water.SetCalculator(PairPotential())
>>> print water.GetPotentialEnergy()
-9.66399870713

The SetCalculator(calculator) method is used to establish the connection between the ListOfAtoms and the calculator. There is also a GetCalculator() method. When a ListOfAtoms has a calculator attached to it, one can use the following ListOfAtoms methods:

GetPotentialEnergy():
Return the potential energy.
GetCartesianForces():
Return the atomic forces in an array.
GetStress():
Return the stress tensor as an array with shape (3, 3).

For all three methods, the attached calculator will be asked to do the calculation for the current state of the ListOfAtoms.

Attention!

The ListOfAtoms will store the forces in its atoms - so one can ask the individual atoms for the forces using the atom.GetCartesianForce() method. This will return the force from the last force calculation - a new force calculation will not be triggered!

A very simple calculator

The ASE package includes a very simple calculator called PairPotential. It conforms to the ASE specifications and is based on pair potentials and the minimum image convention. It does not use neighbor lists, and is therefore not very efficient for large systems. However, as it is a pure python implementation, and it serves well as a demonstration of how a calculator can be implemented. It is used intensively in the test suite.

!DANGER!

Currently, it will only work with �and eV units!

Implementations

Apart for the PairPotential there are currently ... . Check out the complete list of implementations. If you are interested in adding an ASE interface to your favorite calculator, then see how to do it here.

DFT calculator interface

As an extension of the calculator interface, there is also a specialized DFT calculator with additional Get/Set methods.

DFT Calculator interface methods

GetNumberOBands:
Return the number of electronic bands.
SetNumberOfBands(nbands):
Set the number of electronic bands.
GetXCFunctional:
Return the XC-functional identifier ('LDA','PBE' ..)
SetXCFunctional(xc):
Set the XC-functional. xc must be one of: 'LDA', 'PBE', ..,.
GetBZKPoints
Return the K-points in the in the Brillouin zone. The K-points are in units of the reciprocal space basis.
SetBZKPoints(bzkpts):
Set the K-points in the Brillouin zone. kpts should be in units of the reciprocal space basis.
GetSpinPolarized:
Is it a spin-polarized calculation.
SetSpinPolarized(spinpol):
spinpol should be set to True for a spin-polarized calculation, otherwise spinpol should be False.
GetIBZKPoints:
Return k-points in the irreducible part of the irreducible Brillouin zone. The K-points are in units of the reciprocal space basis
GetIBZKPointWeights
Weights of the k-points. The sum of all weights is one.
GetEigenvalues(kpt=0, spin=0):
Return the eigenvalues for all bands for the given K-point kpt and the given spin spin. Eigenvalues are relative to the Fermi-level.
GetOccupationNumbers(kpt=0, spin=0):
Return the occupation numbers for all bands for the given K-point kpt and the given spin spin. These numbers fall in the range [0,1] for a spin-polarized calculation, and in the range [0,2] otherwise.
GetWaveFunctionArray(band, kpt=0, spin=0):

Return array of wavefunction values. The wavefunction are returned for the band band, K-point kpt and spin spin.

The wavefunction is returned as a three-dimensional Numerical array, corresponding to the grid use in the calculation.

GetWaveFunctionArrays(kpt=0, spin=0):
Return array of wavefunction values for all bands for the given K-point kpt and the given spin spin. The wavefunctions are returned as a three-dimensional Numerical array.
GetDensityArray(spin=0):
Return array of density values for the given spin spin.

For some of the Set method one can, for ease of use, use a keyword in the construction of the Calculator, e.g. one can use:

>>> calc = DFTCalculator(bands=20)

Below follow the type and shape definitions for each of DFT calculator methods, and, if defined, the corresponding keyword:

Get methods Set methods type shape keyword
GetNumberOfBands SetNumberOfBands Int scalar bands
GetXCFunctional SetXCFunctional str3 scalar xc
GetBZKPoints SetBZKPoints Float (Nk, 3) kpts
GetIBZKPoints SetIBZKPoints Float (Nki,3)  
GetSpinPolarized SetSpinPolarized logic scalar spin
GetEigenvalues   Float (Nb)  
GetOccupationNumbers   Float (Nb)  
GetWaveFunctionArray   F/C (N1,N2,N3)  
GetWaveFunctionArrays   F/C (N1,N2,N3,Nb)  
GetDensityArray   Float (M1,M2,M3)  

The Get methods will return Numeric arrays of the given shape. A description of the dimensions used are listed below:

Dimension Description
Nk Number of K-points in the Brillouin zone.
Nki Number of K-points in the irreducible part of the Brillouin zone.
Nb Number of electronic bands in the calculation.
N1,N2,N2 Size of the three-dimensional grid on which the wavefunctions are returned.
M1,M2,M3 Size of the three-dimensional grid on which the density are returned.

Working with the DFT calculator

Starting a calculation from scratch
>>> calc = DFTCalculator()
reading from an old calculation

If you want to restart a calculation or read specific information from an old calculation, one have to access the information via the atoms, using:

>>> atoms = DFTCalculator.ReadAtoms('file')

Now you can get the`calculator <calculators.html#calculators>`, attached to the atoms, and get the information, using:

>>> calc = atoms.GetCalculator()
>>> print calc.GetEigenValues()

Often ASE methods take the atoms as the argument, using the GetCalculator method to access the relevant information, i.e the VTK methods for 3D plotting:

>>> from ASE.Visualization.VTK import VTKPlotWaveFunction
>>> atoms = DFTCalculator.ReadAtoms(filename='oldfile')
>>> VTKPlotWaveFunction(atoms)