ASE Manual Release 3.6.1.2825 CAMd - CampOS Wiki

ASE Manual 

Release 3.6.1.2828 

CAMd 

November 17, 2012

CONTENTS 

1 Atomic Simulation Environment 3 

1.1 News . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 

2 Overview 5 

3 Installation requirements 7 

4 Download 9 

4.1 Latest stable release . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 

4.2 Latest development release . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 

5 Installation 11 

5.1 Installation with package manager on Linux . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 

5.2 OSX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 

5.3 Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 

5.4 Manual installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 

5.5 Run the tests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 

5.6 Video tutorial . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 

6 Tutorials 15 

6.1 Python . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 

6.2 ASE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 

6.3 NumPy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45 

6.4 Further reading . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46 

6.5 Videos . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51 

7 Documentation for modules in ASE 53 

7.1 The Atoms object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53 

7.2 The Atom object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65 

7.3 Units . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67 

7.4 The ase.data module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67 

7.5 File input and output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67 

7.6 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70 

7.7 ASE-GUI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72 

7.8 Command line tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79 

7.9 Creating atomic structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83 

7.10 Structure optimization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97 

7.11 Parallel calculations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102 

7.12 Visualization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103 

7.13 ASE-VTK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107 

7.14 Calculators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110 

7.15 Constraints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139 

7.16 Nudged elastic band . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143 

7.17 Vibration analysis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145 

i

7.18 Phonon calculations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147 

7.19 Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147 

7.20 Infrared intensities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150 

7.21 Molecular dynamics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152 

7.22 Density Functional Theory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156 

7.23 Electron transport . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165 

7.24 The data module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166 

7.25 Trajectory files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169 

7.26 Utillity functions and classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172 

7.27 Thermochemistry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173 

8 Frequently Asked Questions 179 

8.1 ASE-GUI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179 

8.2 General . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179 

8.3 Download . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180 

9 Glossary 181 

10 Mailing Lists 183 

10.1 Internet Relay Chat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183 

11 ASE development 185 

11.1 Development topics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185 

11.2 Creating an encrypted password for SVN access . . . . . . . . . . . . . . . . . . . . . . . . . . 197 

12 Bugs! 199 

12.1 Bug report . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199 

12.2 Known bugs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199 

13 Porting old ASE-2 code to version 3 201 

13.1 The ASE2ase tool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201 

Bibliography 203 

Python Module Index 205 

Index 207 

ii

• Introduction to ASE - what is it? 

• Download and installation instructions 

• Tutorials 

• Documentation for modules in ASE 

• Frequently Asked Questions 

• Mailing Lists 

• Glossary 

• ASE development 

• Bugs! 

• Porting old ASE-2 code to version 3 

The complete table of contents: 

ASE Manual, Release 3.6.1.2828 

CONTENTS 1


2 CONTENTS

CHAPTER 

ONE 

ATOMIC SIMULATION ENVIRONMENT 

The Atomic Simulation Environment (ASE) is the common part of the simulation tools developed at CAMd. ASE 

provides Python modules for manipulating atoms, analyzing simulations, visualization etc. 

Note: The old ASE-2 webpage has moved to http://wiki.fysik.dtu.dk/ase2. 

Supported calculators: 

1.1 News 

• ASE version 3.6.0 released (24 February 2012). 

• Bugfix release: ASE version 3.5.1 (24 May 2011). 

• ASE version 3.5.0 released (13 April 2011). 

• ASE version 3.4.1 released (11 August 2010). 

• ASE version 3.4 released (23 April 2010). 

• ASE version 3.3 released (11 January 2010). 

Gaussian 

Mopac 

3


• ASE version 3.2 released (4 September 2009). 

• ASE has reached revision 1000 (16 July 2009). 

• ASE version 3.1.0 released (27 March 2009). 

• Improved vibrations module: More accurate and possibility to calculate infrared intensities 

(13 March 2009). 

• ASE version 3.0.0 released (13 November 2008). 

• Asap version 3.0.2 released (15 October 2008). 

• An experimental abinit interface released (9 June 2008). 

• Thursday April 24 will be ASE documentation-day. Ten people from CAMd/Cinf will do a “doc-sprint” 

from 9 to 16. (17 Apr 2008) 

• The new ASE-3.0 Sphinx page is now up and running! (2 Apr 2008) 

• A beta version of the new ASE-3.0 will be used for the electronic structure course at CAMd. (10 Jan 2008) 

4 Chapter 1. Atomic Simulation Environment

CHAPTER 

TWO 

OVERVIEW 

ASE is an Atomistic Simulation Environment written in the Python programming language with the aim of setting 

up, stearing, and analyzing atomistic simulations. The ASE has been constructed with a number of “design goals” 

that make it: 

• Easy to use: 

Setting up an atomistic total energy calculation or molecular dynamics simulation with ASE is simple and 

straightforward. ASE can be used via a graphical user interface, Command line tools and the 

Python language. Python scripts are easy to follow (see What is Python? for a short introduction). It is 

simple for new users to get access to all of the functionality of ASE. 

• Flexible: 

Since ASE is based on the Python scripting language it is possible to perform very complicated simulation 

tasks without any code modifications. For example, a sequence of calculations may be performed with the 

use of simple “for-loop” constructions. There exist ASE modules for performing many standard simulation 

tasks. 

• Customizable: 

The Python code in ASE is structured in modules intended for different purposes. There are calculators 

for calculating energies, forces and stresses, md and optimize modules for controlling the motion of 

atoms, constraint objects and filters for performing nudged-elastic-band calculations etc. The 

modularity of the object-oriented code make it simple to contribute new functionality to ASE. 

• Pythonic: 

It fits nicely into the rest of the Python world with use of the popular NumPy package for numerical work 

(see Numeric arrays in Python for a short introduction). The use of the Python language allows ASE to be 

used both interactively as well as in scripts. 

• Open to participation: 

The CAMPOS Atomic Simulation Environment is released under the GNU Lesser General Public License 

version 2.1 or any later version. See the files COPYING and COPYING.LESSER which accompany the 

downloaded files, or see the license at GNU’s web server at http://www.gnu.org/licenses/. Everybody is 

invited to participate in using and developing the code. 

5


6 Chapter 2. Overview

CHAPTER 

THREE 

INSTALLATION REQUIREMENTS 

The following packages are required for basic ASE functionality: 

1. Python 2.4 - 2.7. 

2. NumPy. 

It is highly recommended (but not required) to install also these two: 

3. matplotlib. 

4. pygtk. 

Matplotlib is needed for writing png and eps files, and both packages are needed for ASE’s simple 

GUI (called ag, see gui). Some of these packages may already be installed on your system. 

Specific information for different operating systems is provided at Installation. 

7


8 Chapter 3. Installation requirements

4.1 Latest stable release 

The latest stable release can be obtained from svn or as a tarball. 

Note: The recommended installation path is $HOME. 

When using svn please set the following variable: 

• bash: 

export ASE_TAGS=https://svn.fysik.dtu.dk/projects/ase/tags/ 

• csh/tcsh: 

setenv ASE_TAGS https://svn.fysik.dtu.dk/projects/ase/tags/ 

CHAPTER 

FOUR 

DOWNLOAD 

Release Date Retrieve as svn checkout Retrieve as tarball 

3.6.0 Feb 24 2012 svn co -r 2515 $ASE_TAGS/3.6.0 ase-3.6.0 python-ase-3.6.0.2515.tar.gz 

3.5.1 May 24 2011 svn co -r 2175 $ASE_TAGS/3.5.1 ase-3.5.1 python-ase-3.5.1.2175.tar.gz 

3.4.1 Aug 11 2010 svn co -r 1765 $ASE_TAGS/3.4.1 ase-3.4.1 python-ase-3.4.1.1765.tar.gz 

3.4.0 Apr 23 2010 svn co -r 1574 $ASE_TAGS/3.4.0 ase-3.4.0 python-ase-3.4.0.1574.tar.gz 

3.3.1 Jan 20 2010 svn co -r 1390 $ASE_TAGS/3.3.1 ase-3.3.1 python-ase-3.3.1.1390.tar.gz 

3.2.0 Sep 4 2009 svn co -r 1121 $ASE_TAGS/3.2.0 ase-3.2.0 python-ase-3.2.0.1121.tar.gz 

3.1.0 Mar 27 2009 svn co -r 846 $ASE_TAGS/3.1.0 ase-3.1.0 python-ase-3.1.0.846.tar.gz 

3.0.0 Nov 13 2008 svn co -r 657 $ASE_TAGS/3.0.0 ase-3.0.0 python-ase-3.0.0.657.tar.gz 

4.2 Latest development release 

The latest revision can be obtained like this: 

$ svn checkout https://svn.fysik.dtu.dk/projects/ase/trunk ase 

or from the daily snapshot: python-ase-snapshot.tar.gz. 

Note: The recommended checkout path is $HOME. 

9


10 Chapter 4. Download

After performing the installation do not forget to Run the tests! 

5.1 Installation with package manager on Linux 

Install the binaries with the software package manager of your Linux distribution. 

This is the preferred way to install on a Linux system. 

If you prefer to install from sources follow Manual installation. 

The currently supported systems include (issue the commands below as root): 

• RHEL/CentOS 6: 

CHAPTER 

FIVE 

INSTALLATION 

yum install wget 

cd /etc/yum.repos.d/ 

wget http://download.opensuse.org/repositories/home:/dtufys/CentOS_CentOS-6/home:dtufys.repo 

yum install python-ase 

yum install python-matplotlib # optionally 

• Fedora 17: 

yum install wget 

cd /etc/yum.repos.d/ 

wget http://download.opensuse.org/repositories/home:/dtufys/Fedora_17/home:dtufys.repo 

yum install python-ase 

yum install python-matplotlib # optionally 

• openSUSE 12.2: 

zypper ar -f http://download.opensuse.org/repositories/home:/dtufys/openSUSE_12.2/home:dtufys 

yast -i python-ase 

yast -i python-matplotlib # optionally 

• Debian 6.0: 

sudo bash -c ’echo "deb http://widehat.opensuse.org/repositories/home:/dtufys/Debian_6.0 /" > 

wget http://widehat.opensuse.org/repositories/home:/dtufys/Debian_6.0/Release.key && sudo apt 

sudo apt-get update 

sudo apt-get install python-ase 

sudo apt-get install python-matplotlib # optionally 

• Ubuntu 12.04: 

sudo bash -c ’echo "deb http://widehat.opensuse.org/repositories/home:/dtufys/xUbuntu_12.04 / 

wget http://widehat.opensuse.org/repositories/home:/dtufys/xUbuntu_12.04/Release.key && sudo 

sudo apt-get update 

sudo apt-get install python-ase 

sudo apt-get install python-matplotlib # optionally 

11


Note: Alternative packages for ubuntu are provided at Ubuntu package. 

For the full list of supported distributions check https://build.opensuse.org/package/show?package=pythonase&project=home%3Adtufys 

Note: Explore the repositories - more software packages are available! 

Note: If you prefer to install manually, proceed to Manual installation, or alternatively, manually unpack the 

RPMS, e.g.: 

# download the packages + dependencies (you can do that also manually!) 

$ yumdownloader --resolve python-ase 

# unpack into the current directory 

$ find . -name "*.rpm" | xargs -t -I file sh -c "rpm2cpio file | cpio -idm" 

# modify profile.d environment scripts 

$ find . -name "*.*sh" | xargs -t -I file sh -c ’sed -i "s#PA=/usr#PA=$PWD/usr#" file’ 

# modify environment modules scripts 

$ find . -name "*.modules" | xargs -t -I file sh -c ’sed -i "s# /usr# $PWD/usr#" file’ 

# make scripts executable 

$ find . -name "*.*sh" | xargs -t -I file sh -c "chmod u+x file" 

# source the scripts (example for bash) 

$ for f in ‘find . -name "*.sh"‘; do source $f; done 

# verify the desired installation location is used 

$ python -c "import ase; print ase.__file__" 

This method works for all the RPM packages from the repository (like gpaw), however not for the external, 

distribution provided packages, which may require manually creating the environment scripts. 

5.2 OSX 

For Apple users, the MacPorts Project provides a straight-forward route to obtain all necessary requirements. 

Unfortunately, MacPorts does not install the gtk bindings to matplotlib by default, which are required to open the 

GUI. To get all the ASE prerequisites for python 2.7 in one single command anyway, install MacPorts and then 

run: 

$ port install py27-matplotlib +gtk2 

Use the sudo command if you have root access and if you require a system-wide install. Once finished, please 

follow Manual installation. 

5.3 Windows 

Note: ASE is not yet fully functional on Windows! https://trac.fysik.dtu.dk/projects/ase/ticket/62 

On Windows the following packages need to installed. On the command prompt: 

Note: installation assumes the python TARGETDIR C:\Python27 , leave also the default C:\Program 

Files\pythonxy . 

• pythonxy. Download the exe installer and install with: 

12 Chapter 5. Installation

Python(x,y)-2.7.2.2.exe /Log="%TMP%\pythonxy_install.log" /S 

Note: Open Task Manager and control when the process in finished. 


• pygtk_win32. Download the msi pygtk-all-in-one installer. Specify the correct TARGETDIR and install: 

pygtk-all-in-one-2.24.2.win32-py2.7.msi TARGETDIR="%HOMEDRIVE%\Python27" ALLUSERS=1 /l*vx "%T 

Note: If performing clicking-installation make sure that the default python Windows TARGETDIR is selected. 

• Download the python-ase-win32.msi installer and install with: 

python-ase-X.X.X.win32.msi /l*vx "%TMP%\python-ase_install.log" /passive 

Note: You can build the msi ASE package on Windows with: 

python setup.py bdist_msi 

The msi package will be created under the dist directory. 

5.4 Manual installation 

After the Download of ASE source create the link to the requested version, e.g.: 

• if retrieved from svn: 

$ cd $HOME 

$ ln -s ase-3.5.1 ase 

• if retrieved as tarball: 

$ cd $HOME 

$ tar zxf python-ase-3.5.1.2175.tar.gz 

$ ln -s python-ase-3.5.1.2175 ase 

It is sufficient to put the directory $HOME/ase in your PYTHONPATH environment variable, and the directory 

$HOME/ase/tools in your PATH environment variable. Do this permanently in your ~/.bashrc file: 

export PYTHONPATH=$HOME/ase:$PYTHONPATH 

export PATH=$HOME/ase/tools:$PATH 

or your ~/.cshrc file: 

setenv PYTHONPATH ${HOME}/ase:${PYTHONPATH} 

setenv PATH ${HOME}/ase/tools:${PATH} 

Instead of HOME, you may use any other directory. 

Optional, NOT recommended way of installing ASE system-wide is: 

$ cd ase 

$ sudo python setup.py install 

This is one of the best ways to ruin a Linux system. 

5.4. Manual installation 13


5.5 Run the tests 

Make sure that everything works by running the test suite. This will create many files, so run the tests in a 

new directory (preferably using bash): 

$ bash 

$ mkdir /tmp/testase.$$; cd /tmp/testase.* 

$ testase.py 2>&1 | tee testase.log 

Note: In the development version of ASE, and in future stable versions, the test script is just named testase. 

Note: The last test ase/test/COCu111.py requires closing the graphics windows to terminate the whole test-suite. 

If any of the tests fail, then please send us testase.log (see Bugs!). 

Note: If matplotlib or pygtk is not installed, one of the tests will fail - avoid this with: 

$ testase.py --no-display 

5.6 Video tutorial 

In the video: Overview of the features of ASE, followed by a Manual installation of ASE on a Linux system. 

Note: Use “Right Click -> Play” to play. 

14 Chapter 5. Installation

6.1 Python 

If you are not familiar with Python please read What is Python?. 

6.1.1 What is Python? 

This section will give a very brief introduction to the Python language. 

See Also: 

• The Python home page. 

• Python Recipes. 

• Try a Python quick reference card or a different reference card. 

Executing Python code 

You can execute Python code interactively by starting the interpreter like this: 

$ python 

Python 2.5.1 (r251:54863, Mar 7 2008, 04:10:12) 

[GCC 4.1.3 20070929 (prerelease) (Ubuntu 4.1.2-16ubuntu2)] on linux2 

Type "help", "copyright", "credits" or "license" for more information. 

>>> print ’hello’ 

hello 

CHAPTER 

SIX 

TUTORIALS 

You can also put the print ’hello’ line in a file (hello.py) and execute it as a Python script: 

$ python hello.py 

hello 

Or like this: 

$ python -i hello.py 

hello 

>>> print ’hi!’ 

hi! 

Finally, you can put #!/usr/bin/env python in the first line of the hello.py file, make it executable 

(chmod +x hello.py) and execute it like any other executable. 

Tip: For interactive Python sessions, it is very convenient to have a personal .pythonrc file: 

15


import rlcompleter 

import readline 

readline.parse_and_bind("tab: complete") 

from ase import * 

and point the PYTHONSTARTUP environment variable at it (see here for details). 

Tip: For an even better interactive experience, use ipython. 

Types 

Python has the following predefined types: 

type description example 

bool boolean False 

int integer 117 

float floating point number 1.78 

complex complex number 0.5 + 2.0j 

str string ’abc’ 

tuple tuple (1, ’hmm’, 2.0) 

list list [1, ’hmm’, 2.0] 

dict dictionary {’a’: 7.0, 23: True} 

file file open(’stuff.dat’, ’w’) 

A dict object is mapping from keys to values: 

>>> d = {’s’: 0, ’p’: 1} 

>>> d[’d’] = 2 

>>> d 

{’p’: 1, ’s’: 0, ’d’: 2} 

>>> d[’p’] 

1 

A list object is an ordered collection of arbitrary objects: 

>>> l = [1, (’gg’, 7), ’hmm’] 

>>> l[1] 

(’gg’, 7) 

>>> l.append(1.2) 

>>> l[-2] 

’hmm’ 

A tuple behaves like a list - except that it can’t be modified inplace. Objects of types list and dict are 

mutable - all the other types listed in the table are immutable, which means that once an object has been created, 

it can not change. 

Note: List and dictionary objects can change. Variables in Python are references to objects. This is demonstrated 

here: 

>>> a = [’q’, ’w’] 

>>> b = a 

>>> a.append(’e’) 

>>> a 

[’q’, ’w’, ’e’] 

>>> b 

[’q’, ’w’, ’e’] 

Note: Another very important type is the ndarray type described here: Numeric arrays in Python. 

16 Chapter 6. Tutorials

Loops 

A loop in Python can be done like this: 

>>> things = [’a’, 7] 

>>> for x in things: 

... print x 

... 

a 

7 


The things object could be any sequence. Strings, tuples, lists, dictionaries, ndarrays and files are sequences. 

Functions and classes 

A function is defined like this: 

>>> def f(x, m=2, n=1): 

... y = x + n 

... return y**m 

Here f is a function, x is an argument, m and n are keywords with default values 2 and 1 and y is a variable. 

A class is defined like this: 

>>> class A: 

... def __init__(self, b): 

... self.c = b 

... def m(self): 

... return f(self.c, n=0) 

The __init__() function is called a constructor. You can think of a class as a template for creating user defined 

objects. 

In the class A __init__ is a constructor, c is an attribute and m is a method. 

>>> a = A(7) 

>>> a.c 

7 

>>> a.m() 

49 

>>> g = a.m 

>>> g() 

49 

Here we make an instance/object a of type A and g is a method bound to a. 

Importing modules 

If you put the definitions of the function f and the class C in a file stuff.py, then you can use that code from 

another piece of code: 

from stuff import f, C 

print f(1, 2) 

print C(1).m(2) 

or: 

import stuff 

print stuff.f(1, 2) 

print stuff.C(1).m(2) 

6.1. Python 17


or: 

import stuff as st 

print st.f(1, 2) 

print st.C(1).m(2) 

Python will look for stuff.py in these directories: 

1. current working directory 

2. directories listed in your PYTHONPATH 

3. Python’s own system directory (typically /usr/lib/python2.5) 

and import the first one found. 

6.2 ASE 

Most of the tutorials will use the EMT potential, but any other Calculator could be plugged in instead. 

6.2.1 Introduction: Nitrogen on copper 

This section gives a quick (and incomplete) overview of what ASE can do. 

We will calculate the adsorption energy of a nitrogen molecule on a copper surface. This is done by calculating 

the total energy for the isolated slab and for the isolated molecule. The adsorbate is then added to the slab and 

relaxed, and the total energy for this composite system is calculated. The adsorption energy is obtained as the sum 

of the isolated energies minus the energy of the composite system. 

Here is a picture of the system after the relaxation: 

Please have a look at the following script doc/tutorials/N2Cu.py: 

from ase import Atoms 

from ase.visualize import view 

from ase.calculators.emt import EMT 

from ase.constraints import FixAtoms 

from ase.optimize import QuasiNewton 

from ase.lattice.surface import fcc111,add_adsorbate 

h = 1.85 

d = 1.10 

slab = fcc111(’Cu’, size=(4,4,2), vacuum=10.0) 

slab.set_calculator(EMT()) 


e_slab = slab.get_potential_energy() 

molecule = Atoms(’2N’, positions=[(0., 0., 0.), (0., 0., d)]) 

molecule.set_calculator(EMT()) 

e_N2 = molecule.get_potential_energy() 

add_adsorbate(slab, molecule, h, ’ontop’) 

constraint = FixAtoms(mask=[a.symbol != ’N’ for a in slab]) 

slab.set_constraint(constraint) 

dyn = QuasiNewton(slab, trajectory=’N2Cu.traj’) 

dyn.run(fmax=0.05) 


print ’Adsorption energy:’, e_slab + e_N2 - slab.get_potential_energy() 

#view(slab) 

Assuming you have ASE setup correctly (Installation requirements) run the script: 

python N2Cu.py 

Please read below what the script does. 

Atoms 

The Atoms object is a collection of atoms. Here is how to define a N2 molecule by directly specifying the position 

of two nitrogen atoms: 


d = 1.10 

molecule = Atoms(’2N’, positions=[(0., 0., 0.), (0., 0., d)]) 

You can also build crystals using, for example, the lattice module which returns Atoms objects corresponding to 

common crystal structures. Let us make a Cu (111) surface: 

from ase.lattice.surface import fcc111 

slab = fcc111(’Cu’, size=(4,4,2), vacuum=10.0) 

Calculators 

Many calculators can be used with ASE, including emt, Asap, Dacapo, GPAW, Abinit, Vasp. See the ASE 

home page for the full list. 

In this overview we use the effective medium theory (EMT) calculator, as it is very fast and hence useful for 

getting started. 

We can attach a calculator to the previously created Atoms objects: 

from ase import EMT 



and use it to calculate the total energies for the systems by using the get_potential_energy() method 

from the Atoms class: 

e_slab = slab.get_potential_energy() 

e_N2 = molecule.get_potential_energy() 

Structure relaxation 

Let’s use the QuasiNewton minimizer to optimize the structure of the N2 molecule adsorbed on the Cu surface. 

First add the adsorbate to the Cu slab, for example in the on-top position: 

6.2. ASE 19


h = 1.85 

add_adsorbate(slab, molecule, h, ’ontop’) 

In order to speed up the relaxation, let us keep the Cu atoms fixed in the slab by using FixAtoms from the 

constraints module. Only the N2 molecule is then allowed to relax to the equilibrium structure: 


constraint = FixAtoms(mask=[a.symbol != ’N’ for a in slab]) 

slab.set_constraint(constraint) 

Now attach the QuasiNewton minimizer to the system and save the trajectory file. Run the minimizer with the 

convergence criteria that the force on all atoms should be less than some fmax: 


dyn = QuasiNewton(slab, trajectory=’N2Cu.traj’) 


Note: The general documentation on structure optimizations contains information about different algorithms, 

saving the state of an optimizer and other functionality which should be considered when performing expensive 

relaxations. 

Input-output 

Writing the atomic positions to a file is done with the write() function: 

from ase.io import write 

write(’slab.xyz’, slab) 

This will write a file in the xyz-format. Possible formats are: 

format description 

xyz Simple xyz-format 

cube Gaussian cube file 

pdb Protein data bank file 

traj ASE’s own trajectory format 

py Python script 

Reading from a file is done like this: 

from ase.io import read 

slab_from_file = read(’slab.xyz’) 

If the file contains several configurations, the default behavior of the write() function is to return the last 

configuration. However, we can load a specific configuration by doing: 

read(’slab.traj’) # last configuration 

read(’slab.traj’, -1) # same as above 

read(’slab.traj’, 0) # first configuration 

Visualization 

The simplest way to visualize the atoms is the view() function: 


view(slab) 

This will pop up a gui window. Alternative viewers can be used by specifying the optional keyword 

viewer=... - use one of ‘ase.gui’, ‘gopenmol’, ‘vmd’, or ‘rasmol’. (Note that these alternative viewers are not 

a part of ASE and will need to be installed by the user separately.) The VMD viewer can take an optional data 

argument to show 3D data: 


view(slab, viewer=’VMD’, data=array) 

Molecular dynamics 


Let us look at the nitrogen molecule as an example of molecular dynamics with the VelocityVerlet algorithm. 

We first create the VelocityVerlet object giving it the molecule and the time step for the integration 

of Newton’s law. We then perform the dynamics by calling its run() method and giving it the number of steps 

to take: 

from ase.md.verlet import VelocityVerlet 

from ase import units 

dyn = VelocityVerlet(molecule, dt=1.0 * units.fs) 

for i in range(10): 

pot = molecule.get_potential_energy() 

kin = molecule.get_kinetic_energy() 

print ’%2d: %.5f eV, %.5f eV, %.5f eV’ % (i, pot + kin, pot, kin) 

dyn.run(steps=20) 

6.2.2 Manipulating atoms 

XXX rewrite this: use fcc111() function and do some relaxation ... 

We will set up a one layer slab of Ni atoms with one Ag adatom. 

Define the slab atoms: 

>>> from ase import Atoms 

>>> atoms = Atoms(’Ni4’, [(0, 0, 0), 

... (0.45, 0, 0), 

... (0, 0.5, 0), 

... (0.5, 0.5, 0)]) 

Have a look at the individual atoms: 

>>> atoms[0] 

Atom(’Ni’, [0.0, 0.0, 0.0], atoms=..., index=0) 

>>> atoms[1] 


>>> atoms[2] 


>>> atoms[3] 


Let us assume we forgot how many atoms we set up: 

>>> atoms[4] 

Traceback (most recent call last): 

File "", line 1, in ? 

IndexError: list index out of range 

Wrong because we only have four atoms 

>>> len(atoms) 

4 

Change the position of the 2nd atom in the list 

>>> atoms[1].x = 0.5 

>>> atoms.get_positions() 

array([[ 0. , 0. , 0. ], 

[ 0.5, 0. , 0. ], 



[ 0. , 0.5, 0. ], 

[ 0.5, 0.5, 0. ]]) 

What is the unit cell so far? 

>>> atoms.get_cell() 

array([[ 1., 0., 0.], 

[ 0., 1., 0.], 

[ 0., 0., 1.]]) 

Now, setup a p(2x2) cell in a hexagonal surface. Here, a is the fcc lattice constant, the cell is 10 layers high: 

>>> from numpy import sqrt 

>>> a = 3.55 

>>> cell = [(2/sqrt(2.)*a, 0, 0), 

... (1/sqrt(2.)*a, sqrt(3./2.)*a, 0), 

... (0, 0, 10*sqrt(3.)/3.*a)] 

>>> cell 

[(5.0204581464244864, 0, 0), 

(2.5102290732122432, 4.3478442934401409, 0), 

(0, 0, 20.495934556231713)] 

>>> atoms.set_cell(cell, scale_atoms=True) 

The argument scale_atoms=True indicates that the atomic positions should be scaled with the unit cell. The 

default is scale_atoms=False indicating that the cartesian coordinates remain the same when the cell is changed. 


array([[ 0. , 0. , 0. ], 

[ 2.51022907, 0. , 0. ], 

[ 1.25511454, 2.17392215, 0. ], 

[ 3.76534361, 2.17392215, 0. ]]) 

Plot the whole system by bringing up the gui: 

>>> from ase.visualize import view 

>>> view(atoms) 

Within the viewer (called ag or ase.gui) it is possible to repeat the unit cell in all three directions (using the 

Repeat → View window). 



We now add an adatom. Since the supercell is now declared as the unit cell for our atoms we can either add the 

atom using its cartesian coordinates in Angstrom or rescale the unit cell and use scaled coordinates. We try the 

latter: 

>>> from numpy import identity 

>>> from ase import Atom 

>>> xyzcell = identity(3) # The 3x3 unit matrix 

>>> atoms.set_cell(xyzcell, scale_atoms=True) # Set the unit cell and rescale 

>>> atoms.append(Atom(’Ni’, (1/6., 1/6., .1))) 

>>> atoms.set_cell(cell, scale_atoms=True) # Set the unit cell and scale back 

The structure now looks like this: 


6.2.3 Using the spacegroup subpackage 

The most evident usage of the spacegroup subpackage is to set up an initial unit of a bulk structure. For this you 

only need to supply the unique atoms and their scaled positions, space group and lattice parameters. 

Examples of setting up bulk structures 

We start by showing some examples of how to set up some common or interesting bulk structures using 

ase.lattice.spacegroup.crystal(). This function takes a lot of arguments, of which the most important are: 

symbols [string | sequence of strings] Either a string formula or sequence of element symbols. E.g. 

‘NaCl’ and (‘Na’, ‘Cl’) are equivalent. 

basis [list of scaled coordinates] Coordinates of the non-equivalent sites in units of the lattice vectors. 

spacegroup [int | string | Spacegroup instance] Space group given either as its number in International 

Tables or as its Hermann-Mauguin (or international) symbol. 

setting [1 | 2] Space group setting. 



cellpar [[a, b, c, alpha, beta, gamma]] Cell parameters with angles in degree. Is not used when cell 

is given. 

Aluminium (fcc) 

from ase.lattice.spacegroup import crystal 

a = 4.05 

al = crystal(’Al’, [(0,0,0)], spacegroup=225, cellpar=[a, a, a, 90, 90, 90]) 

The spacegroup argument can also be entered with its Hermann-Mauguin symbol, e.g. spacegroup=225 is equivalent 

to spacegroup=’F m -3 m’. 

Iron (bcc) 


a = 2.87 

fe = crystal(’Fe’, [(0,0,0)], spacegroup=229, cellpar=[a, a, a, 90, 90, 90]) 

Magnesium (hcp) 


a = 3.21 

c = 5.21 

mg = crystal(’Mg’, [(1./3., 2./3., 3./4.)], spacegroup=194, 

cellpar=[a, a, c, 90, 90, 120]) 


Diamond 



a = 3.57 

diamond = crystal(’C’, [(0,0,0)], spacegroup=227, cellpar=[a, a, a, 90, 90, 90]) 

Sodium chloride 


a = 5.64 

nacl = crystal([’Na’, ’Cl’], [(0, 0, 0), (0.5, 0.5, 0.5)], spacegroup=225, 

cellpar=[a, a, a, 90, 90, 90]) 

Rutile 


a = 4.6 

c = 2.95 

rutile =crystal([’Ti’, ’O’], basis=[(0, 0, 0), (0.3, 0.3, 0.0)], 

spacegroup=136, cellpar=[a, a, c, 90, 90, 90]) 



CoSb3 skutterudite 

Skutterudites are quite interesting structures with 32 atoms in the unit cell. 


a = 9.04 

skutterudite = crystal((’Co’, ’Sb’), 

basis=[(0.25,0.25,0.25), (0.0, 0.335, 0.158)], 

spacegroup=204, 

cellpar=[a, a, a, 90, 90, 90]) 

#ase.view(skutterudite) 

Often this structure is visualised with the Cobalt atoms on the corners. This can easily be accomplished with 

ASE using ase.utils.geomegry.cut(). Below is the origo argument used to put the Cobalt atom on the corners and 

extend to include all corner and edge atoms, even those belonging to neighbouring unit cells. 


import numpy as np 

import ase.utils.geometry as geometry 

import ase.io as io 


# Create a new atoms instance with Co at origo including all atoms on the 

# surface of the unit cell 

cosb3 = geometry.cut(skutterudite, origo=(0.25, 0.25, 0.25), extend=1.01) 

# Define the atomic bonds to show 

bondatoms = [] 

symbols = cosb3.get_chemical_symbols() 

for i in xrange(len(cosb3)): 

for j in xrange(i): 

if (symbols[i] == symbols[j] == ’Co’ and 

cosb3.get_distance(i, j) < 4.53): 

bondatoms.append((i, j)) 

elif (symbols[i] == symbols[j] == ’Sb’ and 

cosb3.get_distance(i, j) < 2.99): 

bondatoms.append((i, j)) 

# Create nice-looking image using povray 

io.write(’spacegroup-cosb3.pov’, cosb3, 

transparent=False, 

display=False, 

run_povray=True, 

camera_type=’perspective’, 

canvas_width=320, 

radii=0.4, 

rotation=’90y’, 

bondlinewidth=0.07, 

bondatoms=bondatoms, 

) 



The Spacegroup class 

The Spacegroup class is used internally by the ase.lattice.spacegroup.crystal() function, but might sometimes 

also be useful if you want to know e.g. the symmetry operations of a given space group. Instances of the Spacegroup 

class are immutable objects holding space group information, such as symmetry operations. 

Let us e.g. consider the fcc structure. To print information about the space group, do 

from ase.lattice.spacegroup import Spacegroup 

sg = Spacegroup(225) 

print ’Space group:’, sg.no, sg.symbol 

print ’Primitive cell:\n’, sg.scaled_primitive_cell 

print ’Reciprocal cell:\n’, sg.scaled_reciprocal_cell 

print ’Lattice type:’, sg.lattice 

print ’Lattice sub-translations’, sg.subtrans 

print ’Centerosymmetric’, sg.centerosymmetric 

print ’Rotation matrices (not including inversions)\n’, sg.rotations 

print ’Translation vectors (not including inversions)\n’, sg.translations 

or simply 

print sg 

Or, if you want to figure out what sites in the unit cell are equivalent to (0, 0, 0.5), simply do 

sites,kinds = sg.equivalent_sites([(0, 0, 0.5)]) 

where sites will be an array containing the scaled positions of the four symmetry-equivalent sites. 

6.2.4 Atomization energy 

The following script will calculate the atomization energy of a nitrogen molecule: 



atom = Atoms(’N’, calculator=EMT()) 

e_atom = atom.get_potential_energy() 

d = 1.1 

molecule = Atoms(’2N’, [(0., 0., 0.), (0., 0., d)]) 


e_molecule = molecule.get_potential_energy() 

e_atomization = e_molecule - 2 * e_atom 

print ’Nitrogen atom energy: %5.2f eV’ %e_atom 

print ’Nitrogen molecule energy: %5.2f eV’ %e_molecule 

print ’Atomization energy: %5.2f eV’ %-e_atomization 

First, an Atoms object containing one nitrogen is created and a fast EMT calculator is attached to it simply as an 

argument. The total energy for the isolated atom is then calculated and stored in the e_atom variable. 

The molecule object is defined, holding the nitrogen molecule at the experimental bond length. The EMT 

calculator is then attached to the molecule and the total energy is extracted into the e_molecule variable. 

Running the script will produce the output: 

Nitrogen atom energy: 4.97 eV 

Nitrogen molecule energy: 0.04 eV 

Atomization energy: 9.90 eV 


6.2.5 Finding lattice constants 

See Also: 

Equation of state. 

HCP 

Let’s try to find the a and c lattice constants for HCP nickel using the EMT potential. 


First, we make a good intial guess for a and c using the FCC nearest neighbor distance and the ideal c/a ratio: 


a0 = 3.52 / np.sqrt(2) 

c0 = np.sqrt(8 / 3.0) * a0 

and create a trajectory for the results: 

from ase.io import PickleTrajectory 

traj = PickleTrajectory(’Ni.traj’, ’w’) 

Finally, we do the 9 calculations (three values for a and three for c): 

from ase.lattice import bulk 


eps = 0.01 

for a in a0 * np.linspace(1 - eps, 1 + eps, 3): 

for c in c0 * np.linspace(1 - eps, 1 + eps, 3): 

ni = bulk(’Ni’, ’hcp’, a=a, c=c) 

ni.set_calculator(EMT()) 

ni.get_potential_energy() 

traj.write(ni) 

Analysis 

Now, we need to extract the data from the trajectory. Try this: 

>>> from ase.lattice import bulk 

>>> ni = bulk(’Ni’, ’hcp’, a=2.5, c=4.0) 

>>> ni.cell 

array([[ 2.5 , 0. , 0. ], 

[-1.25 , 2.16506351, 0. ], 

[ 0. , 0. , 4. ]]) 

So, we can get a and c from ni.cell[0, 0] and ni.cell[2, 2]: 


configs = read(’Ni.traj@:’) 

energies = [config.get_potential_energy() for config in configs] 

a = np.array([config.cell[0, 0] for config in configs]) 

c = np.array([config.cell[2, 2] for config in configs]) 

We fit the energy to this expression: 

The best fit is found like this: 

p0 + p1a + p2c + p3a 2 + p4ac + p5c 2 

functions = np.array([a**0, a, c, a**2, a * c, c**2]) 

p = np.linalg.lstsq(functions.T, energies)[0] 



and we can find the minimum like this: 

p0 = p[0] 

p1 = p[1:3] 

p2 = np.array([(2 * p[3], p[4]), 

(p[4], 2 * p[5])]) 

a0, c0 = np.linalg.solve(p2.T, -p1) 

Results: 

a c 

2.466 4.023 

Using the stress tensor 

One can also use the stress tensor to optimize the unit cell: 

from ase.optimize import BFGS 

from ase.constraints import StrainFilter 

sf = StrainFilter(ni) 

opt = BFGS(sf) 

opt.run(0.005) 

If you want the optimization path in a trajectory, add these lines before calling the run() method: 

traj = PickleTrajectory(’path.traj’, ’w’, ni) 

opt.attach(traj) 

6.2.6 Equation of state 

First, do a bulk calculation for different lattice constants: 



from ase.io.trajectory import PickleTrajectory 


a = 4.0 # approximate lattice constant 

b = a / 2 

ag = Atoms(’Ag’, 

cell=[(0,b,b), (b,0,b), (b,b,0)], 

pbc=1, 

calculator=EMT()) # use EMT potential 

cell = ag.get_cell() 

traj = PickleTrajectory(’Ag.traj’, ’w’) 

for x in np.linspace(0.95, 1.05, 5): 

ag.set_cell(cell * x, scale_atoms=True) 

traj.write(ag) 

This will write a trajectory file containing five configurations of FCC silver for five different lattice constans. Now, 

analyse the result with the EquationOfState class and this script: 


from ase.units import kJ 

from ase.utils.eos import EquationOfState 

configs = read(’Ag.traj@0:5’) # read 5 configurations 

# Extract volumes and energies: 

volumes = [ag.get_volume() for ag in configs] 

energies = [ag.get_potential_energy() for ag in configs] 

eos = EquationOfState(volumes, energies) 

v0, e0, B = eos.fit() 


print B / kJ * 1.0e24, ’GPa’ 

eos.plot(’Ag-eos.png’) 

A quicker way to do this analysis, is to use the gui tool: 

$ ag Ag.traj 

And then choose Tools → Bulk modulus. 

6.2.7 Dissociation 






# Find the initial and final states for the reaction. 

# Set up a (3 x 3) two layer slab of Ru: 

a = 2.70 

c = 1.59 * a 

sqrt3 = 3. ** .5 

bulk = Atoms(’2Cu’, [(0., 0., 0.), (1./3, 1./3, -0.5*c)], 

tags=(1, 1), 

pbc=(1, 1, 0)) 

bulk.set_cell([(a, 0, 0), 

(a / 2, sqrt3 * a / 2, 0), 

(0, 0, 1)]) 

slab = bulk.repeat((4, 4, 1)) 

# Initial state. 

# Add the molecule: 

x = a / 2. 

y = a * 3. ** .5 / 6. 




z = 1.8 

d = 1.10 # N2 bond length 

# Molecular state parallel to the surface: 

slab += Atoms(’2N’, [(x, y, z), (x + sqrt3 * d / 2, y + d / 2, z)]) 

# Use the EMT calculator for the forces and energies: 


# We don’t want to worry about the Cu degrees of freedom: 

mask = [atom.symbol == ’Cu’ for atom in slab] 

slab.set_constraint(FixAtoms(mask=mask)) 

relax = QuasiNewton(slab) 

relax.run(fmax=0.05) 

print ’initial state:’, slab.get_potential_energy() 

write(’N2.traj’, slab) 

# Now the final state. 

# Move the second N atom to a neighboring hollow site: 

slab[-1].set_position((x + a, y, z)) 

relax.run() 

print ’final state: ’, slab.get_potential_energy() 

write(’2N.traj’, slab) 





from ase.neb import NEB 


initial = read(’N2.traj’) 

final = read(’2N.traj’) 

configs = [initial.copy() for i in range(8)] + [final] 

constraint = FixAtoms(mask=[atom.symbol != ’N’ for atom in initial]) 

for config in configs: 

config.set_calculator(EMT()) 

config.set_constraint(constraint) 

band = NEB(configs) 

band.interpolate() 

# Create a quickmin object: 

relax = QuasiNewton(band) 

relax.run(steps=20) 

e0 = initial.get_potential_energy() 


d = config[-2].position - config[-1].position 

print np.linalg.norm(d), config.get_potential_energy() - e0 

6.2.8 Dissociation using ANEB 


# XXX This cannot be converted to ase 3, since we lack ANEB 

raise NotImplementedError 



#from ASE.Calculators.PairPotential import PairPotential 

#from ASE.Filters.Subset import Subset 

#from ASE.Dynamics.AdaptiveNudgedElasticBand import AdaptiveNudgedElasticBand 

#from ASE.IO.NetCDF import ReadNetCDF 

import os 

# check that N2.nc and 2N.nc exists otherwise run 

# N2Ru-Dissociation1.py 

if not (os.path.exists(’N2.nc’) and os.path.exists(’N2.nc’)): 

os.system(’python N2Ru-Dissociation1.py’) 

initial = read(’N2.traj’) 

final = read(’2N.traj’) 

configs = [initial.copy() for i in range(4)] + [final] 

constraint = FixAtoms(mask=[atom.symbol != ’N’ for atom in initial]) 


config.set_calculator(EMT()) 

config.set_constraint(constraint) 

band = NEB(configs) 


# Create a quickmin object: 

relax = QuasiNewton(band) 

#configs0 = [initial] 

#for i in range(3): 

# configs0.append(initial.Copy()) 

#configs0.append(final) 

# 

#configs = [] 

#for config in configs0: 

# config.SetCalculator(PairPotential()) 

# configs.append(Subset(config, indices=[-2, -1])) 

# setup the Adaptive Nudged Elastic Band dynamics 

aneb = AdaptiveNudgedElasticBand(configs,prefix=’aneb’,linear_interpolation=True,maxlevels=1) 

aneb.Converge() 

# test the anebfit tool 

os.system(’anebfit aneb’) 

os.system(’xmgrace aneb_-1.agr&’) 

# clean up 

# os.system(’rm aneb*conf*’) 

6.2.9 Association 


#from math import sqrt 

#from ASE.Calculators.PairPotential import PairPotential 

#from ASE.Filters.Subset import Subset 

#from ASE.Filters.FixBondLength import FixBondLength 



#from ASE.Dynamics.MDMin import MDMin 

#from ASE.Trajectories.NetCDFTrajectory import NetCDFTrajectory 

#from ASE.IO.NetCDF import ReadNetCDF 

slab = read(’2N.traj’) 


constraint = FixBondLength(-2, -1) 

#mask=[atom.symbol != ’N’ for atom in slab]) 

#molecule = Subset(slab, indices=[-2, -1]) 

# Create a trajectory for the dissociation path: 

path = PickleTrajectory(’association.traj’, slab) 

# Put the initial state in the trajectory: 

path.write() 

# From now on, we relax the molecule under the constraint of fixed 

# bond length: 

#fixed = FixBondLength(molecule, 0, 1) 

#relax = MDMin(fixed, dt=0.08, fmax=0.05) 

relax = QuasiNewton(slab) 

d = linalg.norm(slab[-2].position - slab[-1].position) 

#d = fixed.GetBondLength() 

delta = 0.1 

e0 = slab.get_potential_energy() 

print d, 0.0 

while d > 1.10: 

d -= delta 

fixed.SetBondLength(d, fix=’first’) 

# XXX 

raise NotImplementedError 

relax.run(fmax=.05) 

path.write() 

print d, slab.GetPotentialEnergy() - e0 

6.2.10 Diffusion of gold atom on Al(100) surface (NEB) 

First, set up the initial and final states: 


from ase.lattice.surface import fcc100, add_adsorbate 




# 2x2-Al(001) surface with 3 layers and an 

# Au atom adsorbed in a hollow site: 

slab = fcc100(’Al’, size=(2, 2, 3)) 

add_adsorbate(slab, ’Au’, 1.7, ’hollow’) 

slab.center(axis=2, vacuum=4.0) 

# Make sure the structure is correct: 

#view(slab) 

# Fix second and third layers: 

mask = [atom.tag > 1 for atom in slab] 

#print mask 

slab.set_constraint(FixAtoms(mask=mask)) 

# Use EMT potential: 


# Initial state: 

qn = QuasiNewton(slab, trajectory=’initial.traj’) 

qn.run(fmax=0.05) 

# Final state: 

slab[-1].x += slab.get_cell()[0, 0] / 2 

qn = QuasiNewton(slab, trajectory=’final.traj’) 


Note: Notice how the tags are used to select the constrained atoms 

Now, do the NEB calculation: 






initial = read(’initial.traj’) 

final = read(’final.traj’) 

constraint = FixAtoms(mask=[atom.tag > 1 for atom in initial]) 

images = [initial] 


image = initial.copy() 

image.set_calculator(EMT()) 

image.set_constraint(constraint) 

images.append(image) 

images.append(final) 

neb = NEB(images) 

neb.interpolate() 

qn = BFGS(neb, trajectory=’neb.traj’) 





Note: For this reaction, the reaction coordinate is very simple: The x-coordinate of the Au atom. In such cases, 

the NEB method is overkill, and a simple constraint method should be used like in this tutorial: Diffusion of gold 

atom on Al(100) surface (constraint). 

See Also: 

• neb 

• constraints 

• Diffusion of gold atom on Al(100) surface (constraint) 

• fcc100() 

Parallelizing over images 

Instead of having one process do the calculations for all three internal images in turn, it will be faster to have three 

processes do one image each. This can be done like this: 







from ase.parallel import rank, size 

initial = read(’initial.traj’) 

final = read(’final.traj’) 

constraint = FixAtoms(mask=[atom.tag > 1 for atom in initial]) 


j = rank * 3 // size # my image number 


image = initial.copy() 

if i == j: 


image.set_constraint(constraint) 

images.append(image) 

images.append(final) 



neb = NEB(images, parallel=True) 


qn = BFGS(neb) 

if rank % (size // 3) == 0: 

traj = PickleTrajectory(’neb%d.traj’ % j, ’w’, images[1 + j], master=True) 

qn.attach(traj) 


6.2.11 Diffusion of gold atom on Al(100) surface (constraint) 

In this tutorial, we will calculate the energy barrier that was found using the NEB method in the Diffusion of gold 

atom on Al(100) surface (NEB) tutorial. Here, we use a siple FixedPlane constraint that forces the Au atom to 

relax in the yz-plane only: 

from ase.lattice.surface import fcc100, add_adsorbate 

from ase.constraints import FixAtoms, FixedPlane 



# 2x2-Al(001) surface with 3 layers and an 

# Au atom adsorbed in a hollow site: 

slab = fcc100(’Al’, size=(2, 2, 3)) 

add_adsorbate(slab, ’Au’, 1.7, ’hollow’) 

slab.center(axis=2, vacuum=4.0) 

# Make sure the structure is correct: 

#view(slab) 

# Fix second and third layers: 

mask = [atom.tag > 1 for atom in slab] 

#print mask 

fixlayers = FixAtoms(mask=mask) 

# Constrain the last atom (Au atom) to move only in the yz-plane: 

plane = FixedPlane(-1, (1, 0, 0)) 

slab.set_constraint([fixlayers, plane]) 

# Use EMT potential: 


# Initial state: 


qn = QuasiNewton(slab, trajectory=’mep%d.traj’ % i) 


slab[-1].x += slab.get_cell()[0, 0] / 8 

The result can be analysed with the command ag mep?.traj -n -1 (choose Tools → NEB). The barrier is found to 

be 0.35 eV - exactly as in the NEB tutorial. 

Here is a side-view of the path (unit cell repeated twice): 



See Also: 

• neb 

• constraints 

• Diffusion of gold atom on Al(100) surface (NEB) 

• fcc100() 

6.2.12 Molecular dynamics 

Note: These examples can be used without Asap installed, then the ase.EMT calculator (implemented in Python) 

is used, but nearly superhuman patience is required. 

Here we demonstrate now simple molecular dynamics is performed. A crystal is set up, the atoms are given 

momenta corresponding to a temperature of 300K, then Newtons second law is integrated numerically with a time 

step of 5 fs (a good choice for copper). 

"Demonstrates molecular dynamics with constant energy." 


from ase.lattice.cubic import FaceCenteredCubic 

from ase.md.velocitydistribution import MaxwellBoltzmannDistribution 



# Use Asap for a huge performance increase if it is installed 

useAsap = False 

if useAsap: 

from asap3 import EMT 

size = 10 

else: 

size = 3 

# Set up a crystal 

atoms = FaceCenteredCubic(directions=[[1,0,0],[0,1,0],[0,0,1]], symbol="Cu", 

size=(size,size,size), pbc=True) 

# Describe the interatomic interactions with the Effective Medium Theory 


atoms.set_calculator(EMT()) 

# Set the momenta corresponding to T=300K 

MaxwellBoltzmannDistribution(atoms, 300*units.kB) 


# We want to run MD with constant energy using the VelocityVerlet algorithm. 

dyn = VelocityVerlet(atoms, 5*units.fs) # 5 fs time step. 

#Function to print the potential, kinetic and total energy 

def printenergy(a): 

epot = a.get_potential_energy() / len(a) 

ekin = a.get_kinetic_energy() / len(a) 

print ("Energy per atom: Epot = %.3feV Ekin = %.3feV (T=%3.0fK) Etot = %.3feV" % 

(epot, ekin, ekin/(1.5*units.kB), epot+ekin)) 

# Now run the dynamics 

printenergy(atoms) 


dyn.run(10) 

printenergy(atoms) 

Note how the total energy is conserved, but the kinetic energy quickly drops to half the expected value. Why? 

Instead of printing within a loop, it is possible to use an “observer” to observe the atoms and do the printing (or 

more sophisticated analysis). 




from ase.md.velocitydistribution import MaxwellBoltzmannDistribution 




useAsap = True 

if useAsap: 


size = 10 

else: 

size = 3 



size=(size,size,size), pbc=True) 





# We want to run MD with constant energy using the VelocityVerlet algorithm. 

dyn = VelocityVerlet(atoms, 5*units.fs) # 5 fs time step. 

#Function to print the potential, kinetic and total energy. 

def printenergy(a=atoms): #store a reference to atoms in the definition. 








dyn.attach(printenergy, interval=10) 

printenergy() 

dyn.run(200) 

Constant temperature MD 

Often, you want to control the temperature of an MD simulation. This can be done with the Langevin dynamics 

module. In the previous examples, replace the line dyn = VelocityVerlet(...) with: 

dyn = Langevin(atoms, 5*units.fs, T*units.kB, 0.002) 

where T is the desired temperature in Kelvin. You also need to import Langevin, see the class below. 

The Langevin dynamics will then slowly adjust the total energy of the system so the temperature approaches the 

desired one. 

As a slightly less boring example, let us use this to melt a chunck of copper by starting the simulation without any 

momentum of the atoms (no kinetic energy), and with a desired temperature above the melting point. We will also 

save information about the atoms in a trajectory file called moldyn3.traj. 




from ase.md.langevin import Langevin 



from asap3 import EMT # Way too slow with ase.EMT ! 

size = 10 

T = 1500 # Kelvin 



size=(size,size,size), pbc=False) 



# We want to run MD with constant energy using the Langevin algorithm 

# with a time step of 5 fs, the temperature T and the friction 

# coefficient to 0.02 atomic units. 

dyn = Langevin(atoms, 5*units.fs, T*units.kB, 0.002) 








#We also want to save the positions of all atoms after every 100th time step. 

traj = PickleTrajectory("moldyn3.traj", ’w’, atoms) 

dyn.attach(traj.write, interval=50) 


printenergy() 

dyn.run(5000) 

After running the simulation, you can study the result with the command 


ag moldyn3.traj 


Try plotting the kinetic energy. You will not see a well-defined melting point due to finite size effects (including 

surface melting), but you will probably see an almost flat region where the inside of the system melts. The 

outermost layers melt at a lower temperature. 

Note: The Langevin dynamics will by default keep the position and momentum of the center of mass unperturbed. 

This is another improvement over just setting momenta corresponding to a temperature, as we did before. 

Isolated particle MD 

When simulating isolated particles with MD, it is sometimes preferable to set random momenta corresponding to 

a spefic temperature and let the system evolve freely. With a relatively high temperature, the is however a risk that 

the collection of atoms will drift out of the simulation box because the randomized momenta gave the center of 

mass a small but non-zero velocity too. 

Let us see what happens when we propagate a nanoparticle for a long time: 

"Demonstrates molecular dynamics for isolated particles." 


from ase.cluster.cubic import FaceCenteredCubic 


from ase.md.velocitydistribution import MaxwellBoltzmannDistribution, \ 

Stationary, ZeroRotation 




useAsap = True 

if useAsap: 


size = 4 

else: 

size = 2 

# Set up a nanoparticle 

atoms = FaceCenteredCubic(’Cu’, surfaces=[[1,0,0],[1,1,0],[1,1,1]], 

layers=(size,size,size), vacuum=4) 



# Do a quick relaxation of the cluster 

qn = QuasiNewton(atoms) 

qn.run(0.001, 10) 



Stationary(atoms) # zero linear momentum 

ZeroRotation(atoms) # zero angular momentum 

# We want to run MD using the VelocityVerlet algorithm. 

dyn = VelocityVerlet(atoms, 5*units.fs, trajectory=’moldyn4.traj’) # save trajectory. 











printenergy() 

dyn.run(2000) 

After running the simulation, use ag to compare the results with how it looks if you comment out either the line 

that says Stationary (atoms), ZeroRotation (atoms) or both. 

ag moldyn4.traj 

Try playing the movie with a high frame rate and set frame skipping to a low number. Can you spot the subtle 

difference? 

6.2.13 Tutorial: STM images - Al(100) 

The STM is a revolutionary experimental surface probe that has provided direct local insight into the surface 

electronic structure. Sometimes the interpretation of STM topographs are not straightforward and therefore theoretically 

modeled STM images may resolve conflicting possibilities and point to an underlying atomistic model. 

The CAMPOS code includes python modules for generating Tersoff-Hamann STM topographs. The STM code is 

illustrated here for a Al(100) in a 2x2 unit cell. 

Let’s make the Al(100) fcc surface by using the lattice module: 

from ase.lattice.surface import * 

atoms = fcc100(’Al’, size=(2,2,2)) 

Now a calculator must be defined, in this tutorial we will make a STM image from the GPAW calculator. 

For the GPAW code the calculator for the Al(100) surface can be defined like this: 

from gpaw import GPAW 

calc = GPAW(gpts=(28,28,20),nbands=28, 

kpts=(4,4,1),txt=’Al100.out’) 

atoms.set_calculator(calc) 

energy = atoms.get_potential_energy() 

calc.write(’Al100.gpw’, ’all’) 

Linescans 

In this section we will make simulated STM linescans and contour plot using matplotlib. First initialize the STM 

object and get the averaged current along the z-direction: 

from ase import STM 

stm = STM(atoms, symmetries=[0, 1, 2]) 

z = 2.5 

c = stm.get_averaged_current(z) 

From the current we make a scan to get a 2D array of constant current heights: 

h = stm.scan(c) 

Finally we make a contour plot: 

import pylab as p 

p.contourf(h, 40) 

p.hot() 

p.colorbar() 

p.show() 


6.2.14 Partly occupied Wannier Functions 

from ase.data.molecules import molecule 


atoms = molecule(’C6H6’) 

atoms.center(vacuum=3.5) 

calc = GPAW(h=.21, xc=’PBE’, txt=’benzene.txt’, nbands=18) 


atoms.get_potential_energy() 

calc.set(fixdensity=True, txt=’benzene-harris.txt’, 

nbands=40, eigensolver=’cg’, convergence={’bands’: 35}) 


calc.write(’benzene.gpw’, mode=’all’) 

from gpaw import restart 

from ase.dft import Wannier 

atoms, calc = restart(’benzene.gpw’, txt=None) 

# Make wannier functions of occupied space only 

wan = Wannier(nwannier=15, calc=calc) 

wan.localize() 

for i in range(wan.nwannier): 

wan.write_cube(i, ’benzene15_%i.cube’ % i) 

# Make wannier functions using (three) extra degrees of freedom. 

wan = Wannier(nwannier=18, calc=calc, fixedstates=15) 


wan.save(’wan18.pickle’) 


wan.write_cube(i, ’benzene18_%i.cube’ % i) 




atoms, calc = restart(’benzene.gpw’, txt=None) 

wan = Wannier(nwannier=18, calc=calc, fixedstates=15, file=’wan18.pickle’) 

import pylab as pl 

weight_n = pl.sum(abs(wan.V_knw[0])**2, 1) 

N = len(weight_n) 

F = wan.fixedstates_k[0] 

pl.figure(1, figsize=(12, 4)) 

pl.bar(range(1, N+1), weight_n, width=0.65, bottom=0, 

color=’k’, edgecolor=’k’, linewidth=None, 

align=’center’, orientation=’vertical’) 

pl.plot([F+.5, F+.5], [0, 1], ’k--’) 

pl.axis(xmin=.32, xmax=N+1.33, ymin=0, ymax=1) 

pl.xlabel(’Eigenstate’) 

pl.ylabel(’Projection of wannier functions’) 

pl.savefig(’spectral_weight.png’) 

pl.show() 



from ase.dft.kpoints import monkhorst_pack 




kpts = monkhorst_pack((13, 1, 1)) + [1e-5, 0, 0] 

calc = GPAW(h=.21, xc=’PBE’, kpts=kpts, nbands=12, txt=’poly.txt’, 

eigensolver=’cg’, convergence={’bands’: 9}) 

CC = 1.38 

CH = 1.094 

a = 2.45 

x = a / 2. 

y = np.sqrt(CC**2 - x**2) 

atoms = Atoms(’C2H2’, pbc=(True, False, False), cell=(a, 8., 6.), 

calculator=calc, positions=[[0, 0, 0], 

[x, y, 0], 

[x, y+CH, 0], 

[0, -CH, 0]]) 

atoms.center() 


calc.write(’poly.gpw’, mode=’all’) 




atoms, calc = restart(’poly.gpw’, txt=None) 

# Make wannier functions using (one) extra degree of freedom 

wan = Wannier(nwannier=6, calc=calc, fixedenergy=1.5) 


wan.save(’poly.pickle’) 

wan.translate_all_to_cell((2, 0, 0)) 


wan.write_cube(i, ’polyacetylene_%i.cube’ % i) 

# Print Kohn-Sham bandstructure 

ef = calc.get_fermi_level() 

f = open(’KSbands.txt’, ’w’) 

for k, kpt_c in enumerate(calc.get_ibz_k_points()): 

for eps in calc.get_eigenvalues(kpt=k): 

print >> f, kpt_c[0], eps - ef 

# Print Wannier bandstructure 

f = open(’WANbands.txt’, ’w’) 

for k in np.linspace(-.5, .5, 100): 

for eps in np.linalg.eigvalsh(wan.get_hamiltonian_kpoint([k, 0, 0])).real: 

print >> f, k, eps - ef 

import pylab as pl 

fig = pl.figure(1, dpi=80, figsize=(4.2, 6)) 

fig.subplots_adjust(left=.16, right=.97, top=.97, bottom=.05) 

# Plot KS bands 

k, eps = pl.load(’KSbands.txt’, unpack=True) 

pl.plot(k, eps, ’ro’, label=’DFT’, ms=9) 

# Plot Wannier bands 

k, eps = pl.load(’WANbands.txt’, unpack=True) 

pl.plot(k, eps, ’k.’, label=’Wannier’) 

pl.plot([-.5, .5], [1, 1], ’k:’, label=’_nolegend_’) 

pl.text(-.5, 1, ’fixedenergy’, ha=’left’, va=’bottom’) 

pl.axis(’tight’) 

pl.xticks([-.5, -.25, 0, .25, .5], 



[ r’$X$’, r’$\Delta$’, r’$\Gamma$’, r’$\Delta$’, r’$X$’], size=16) 

pl.ylabel(r’$E - E_F\ \rm{(eV)}$’, size=16) 

pl.legend() 

pl.savefig(’bands.png’, dpi=80) 

pl.show() 

6.3 NumPy 

If your ASE scripts make extensive use of matrices you may want to familiarize yourself with Numeric arrays in 

Python. 

6.3.1 Numeric arrays in Python 

Links to NumPy’s webpage: 

• Numpy and Scipy Documentation 

• Numpy guide book 

• Numpy example list 

• Numpy functions by category 

ASE makes heavy use of an extension to Python called NumPy. The NumPy module defines an ndarray type that 

can hold large arrays of uniform multidimensional numeric data. An array is similar to a list or a tuple, but 

it is a lot more powerful and efficient. 

XXX More examples from everyday ASE-life here ... 

>>> import numpy as np 

>>> a = np.zeros((3, 2)) 

>>> a[:, 1] = 1.0 

>>> a[1] = 2.0 

>>> a 

array([[ 0., 1.], 

[ 2., 2.], 

[ 0., 1.]]) 

>>> a.shape 

(3, 2) 

>>> a.ndim 

2 

The conventions of numpy’s linear algebra package: 


>>> 

>>> # Make a random hermitian matrix, H 

>>> H = np.random.rand(6, 6) + 1.j * np.random.rand(6, 6) 

>>> H = H + H.T.conj() 

>>> 

>>> # Determine eigenvalues and rotation matrix 

>>> eps, U = np.linalg.eigh(H) 

>>> 

>>> # Sort eigenvalues 

>>> sorted_indices = eps.real.argsort() 

>>> eps = eps[sorted_indices] 

>>> U = U[:, sorted_indices] 

>>> 

>>> # Make print of numpy arrays less messy: 

>>> np.set_printoptions(precision=3, suppress=True) 

>>> 

6.3. NumPy 45


>>> # Check that U diagonalizes H: 

>>> print np.dot(np.dot(U.T.conj(), H), U) - np.diag(eps) 

>>> print np.allclose(np.dot(np.dot(U.T.conj(), H), U), np.diag(eps)) 

>>> 

>>> # The eigenvectors of H are the *coloumns* of U: 

>>> np.allclose(np.dot(H, U[:, 3]), eps[3] * U[:, 3]) 

>>> np.allclose(np.dot(H, U), eps * U) 

The rules for multiplying 1D arrays with 2D arrays: 

• 1D arrays and treated like shape (1, N) arrays (row vectors). 

• left and right multiplications are treated identically. 

• A length m row vector can be multiplied with an n x m matrix, producing the same result as if replaced by a 

matrix with n copies of the vector as rows. 

• A length n column vector can be multiplied with an n x m matrix, producing the same result as if replaced 

by a matrix with m copies of the vector as columns. 

Thus, for the arrays below: 

>>> M = np.arange(5 * 6).reshape(5, 6) # A matrix af shape (5, 6) 

>>> v5 = np.arange(5) + 10 # A vector of length 5 

>>> v51 = v5[:, None] # A length 5 coulomn vector 

>>> v6 = np.arange(6) - 12 # A vector of length 6 

>>> v16 = v6[None, :] # A length 6 row vector 

The following identities hold: 

v6 * M == v16 * M == M * v6 == M * v16 == M * v16.repeat(5, 0) 

v51 * M == M * v51 == M * v51.repeat(6, 1) 

The exact same rules apply for adding and subtracting 1D arrays to / from 2D arrays. 

6.4 Further reading 

For more details: 

• Look at the documentation for the individual modules. 

• See the automatically generated documentation Epydoc: ase. 

• Browse the source code online. 

• Have a look at siesta exercises: 

6.4.1 Exercises 

Note: CAMd summer school participants should read this page before doing the SIESTA exercises. 

Exercise 2 contains a script which takes somewhat long time. For this reason you may want to submit the script 

to Niflheim in advance, before analyzing the results in Exercise 1. 

Siesta 1: Basis Sets 

This exercise is intended to illustrate the definition of basis sets with different numbers of orbitals and localization 

radii in SIESTA. It is based on the H2O molecule. You will first use standard basis sets generated by SIESTA, 

and then a basis set specifically optimized for the H2O molecule. The tips at the end of this page will help you in 

analyzing the results of the calculations. 



We are going to use the ASE interface to the siesta calculator, for the official SIESTA documentation see here. 

Part 1: Standard basis sets 

In the following script you will relax the structure of the H2O molecule to find its equilibrium structure. 

import time 


from ase import Atoms, units 


from ase.calculators.siesta import Siesta 

# Set up a H2O molecule by specifying atomic positions 

h2o = Atoms(symbols=’H2O’, 

positions=[( 0.776070, 0.590459, 0.00000), 

(-0.776070, 0.590459, 0.00000), 

(0.000000, -0.007702, -0.000001)], 

pbc=(1,1,1)) 

# Center the molecule in the cell with some vacuum around 

h2o.center(vacuum=6.0) 

# Select some energy-shifts for the basis orbitals 

e_shifts = [0.01,0.1,0.2,0.3,0.4,0.5] 

# Run the relaxation for each energy shift, and print out the 

# corresponding total energy, bond length and angle 

for e_s in e_shifts: 

starttime = time.time() 

calc = Siesta(’h2o’,meshcutoff=200.0 * units.Ry, mix=0.5, pulay=4) 

calc.set_fdf(’PAO.EnergyShift’, e_s * units.eV) 

calc.set_fdf(’PAO.SplitNorm’, 0.15) 

calc.set_fdf(’PAO.BasisSize’, ’SZ’) 

h2o.set_calculator(calc) 

# Make a -traj file named h2o_current_shift.traj: 

dyn = QuasiNewton(h2o, trajectory=’h2o_%s.traj’ % e_s) 

dyn.run(fmax=0.02) # Perform the relaxation 

E = h2o.get_potential_energy() 

print # Make the output more readable 

print "E_shift: %.2f" %e_s 

print "----------------" 

print "Total Energy: %.4f" % E # Print total energy 

d = h2o.get_distance(0,2) 

print "Bond length: %.4f" % d # Print bond length 

p = h2o.positions 

d1 = p[0] - p[2] 

d2 = p[1] - p[2] 

r = np.dot(d1, d2) / (np.linalg.norm(d1) * np.linalg.norm(d2)) 

angle = np.arccos(r) / pi * 180 

print "Bond angle: %.4f" % angle # Print bond angle 

endtime = time.time() 

walltime = endtime - starttime 

print ’Wall time: %.5f’ % walltime 

print # Make the output more readable 

Run the script using three different basis sets: single-Z (SZ), double-Z (DZ) and double-Z plus polarization (DZP). 

Run it in different directories for each basis set, since the run will produce a large amount of output files. The 

bases are defined in the script through these three lines: 

6.4. Further reading 47


calc.set_fdf(’PAO.BasisSize’,’SZ’) 

calc.set_fdf(’PAO.EnergyShift’,e_s * eV) 

calc.set_fdf(’PAO.SplitNorm’,0.15) 

For each of the basis sets the script will run the relaxation for different EnergyShift parameters. Look at the 

results as a function of basis size and localization radius (or energy shift). 

In particular, you should look at: 

• Total energy 

• Bond lenghts at the relaxed structure 

• Bond angles at the relaxed structure 

• Execution time 

• Radius of each of the orbitals 

• Shape of the orbitals 

The script will print bond lengths and angles, total energy plus the wall time for each energy shift. The radii of the 

orbitals from the last run can be found in the file h2o.txt along with miscellaneous other informations. Orbital 

shapes from the last run are stored in the ORB.* files, which contain the value of the orbitals versus radius. (Note 

that the standard way to plot the orbitals is to multiply the orbital by r l ). 

You can visualize both the static atoms and the relaxation trajectory using the the ASE gui. For example you can 

visualize the relaxation trajectory from the command line by doing: 

$ ag h2o_0.1.traj 

Note that you will get a trajectory file .traj for each energy shift in the loop. 

Try to get plots like the following, obtained for a SZ basis: 


Try to answer these questions: 

1. What is the best basis set that you have found? Why? 

2. How do the results compare with experiment? 


3. What do you consider a reasonable basis for the molecule, if you need an accuracy in the geometry of about 

1%? 

4. In order to assess convergence with respect to basis set size, should you compare the results with the experimental 

ones, or with those of a converged basis set calculation? 

Part 2: Optimized basis sets 

You will now do the same calculations as in Part 1, but now using a basis set specifically optimized for the H2O 

molecule. Use the following optimized block instead of the basis-definition lines in Part1: 

calc.set_fdf(’PAO.Basis’, 

["""H 2 0.22 

n=1 0 2 E 2.07 0.00 

4.971 1.771 

1.000 1.000 

n=2 1 1 E 0.89 0.01 

4.988 

1.000 

O 3 -0.20 

n=2 0 2 E 0.00 1.31 

5.000 2.581 

1.000 1.000 

n=2 1 2 E 0.00 5.28 

6.500 2.487 

1.000 1.000 

n=3 2 1 E 104.31 0.00 

3.923 

1.000"""]) 

Compare the parameters with those of the calculations in Part 1. 

Do the runs with this basis set, and compare the results with the previous ones. 

Tips 

Tip 1: You can see the radii of the orbitals in the output file, just after the line reading: 

6.4. Further reading 49


printput: Basis input ---------------------------------------------- 

Tip 2: You can look at the shape of the orbitals by plotting the contents of the ORB* files generated by SIESTA. 

Tip 3: You will find a lot of information on the run in the .txt output file 

Tip 4: In ag you can select View → VMD to start the VMD viewer. There you can change the atom representation 

to what you feel is more convenient. Do that by selecting Graphics → Representations in the top bar. 

Tip 5: SIESTA will store basis functions in ORB.* files. These files can be plotted using the xmgrace command 

on the GBAR like this: 

$ xmgrace ORB.S1.1.O ORB.S2.1.O 

Siesta 2: Molecular Dynamics 

This exercise is intended to illustrate a Molecular Dynamics run with the SIESTA calculator. The system is a 

Si(001) surface, in the 2x1 reconstruction with asymmetric dimers. The simulation cell contains two dimers. An 

H2 molecule approaches the surface, above one of the dimers, and dissociates, ending up with a H atom bonded 

to each of the Si atoms in the dimer (and thus leading to a symmetric dimer). You can get the xyz file with the 

initial geometry doc/exercises/siesta2/geom.xyz. 

#!/usr/bin/env python 



from ase.calculators.siesta import Siesta 

from ase.md import VelocityVerlet 


# Read in the geometry from a xyz file, set the cell, boundary conditions and center 

atoms = read(’geom.xyz’) 

atoms.set_cell([7.66348,7.66348,7.66348*2]) 

atoms.set_pbc((1,1,1)) 


# Set initial velocities for hydrogen atoms along the z-direction 

p = atoms.get_momenta() 

p[0,2]= -1.5 

p[1,2]= -1.5 

atoms.set_momenta(p) 

# Keep some atoms fixed during the simulation 

atoms.set_constraint(FixAtoms(indices=range(18,38))) 

# Set the calculator and attach it to the system 

calc = Siesta(’si001+h2’,basis=’SZ’,xc=’PBE’,meshcutoff=50*units.Ry) 

calc.set_fdf(’PAO.EnergyShift’, 0.25 * units.eV) 

calc.set_fdf(’PAO.SplitNorm’, 0.15) 


# Set the VelocityVerlet algorithm and run it 

dyn = VelocityVerlet(atoms,dt=1.0 * units.fs,trajectory=’si001+h2.traj’) 

dyn.run(steps=100) 

Note that both H atoms are given an initial velocity towards the surface through the lines: 

p = atoms.get_momenta() 

p[0,2]= -1.5 

p[1,2]= -1.5 

atoms.set_momenta(p) 

Run the program, and check the results. You can visualize the dynamics using the trajectory file with the help of 

the ASE gui. For example you can visualize the behaviour of the potential and total energies during the dynamics 


y doing: 

$ ag -b si001+h2.traj -g i,e,e+ekin 


The -b option turns on plotting of bonds between the atoms. Check that the total energy is a conserved quantity 

in this microcanonical simulation. 

You can also use VMD to visualize the trajectory. To do this, you need a .xyz file that you can write using ag: 

$ ag si001+h2.traj -o si.xyz -r 2,2,1 

Then simply open the file using VMD: 

$ vmd si.xyz 

and set Graphics/Representations from the main menu in order to get a nice picture. 

You can also try to repeat the simulation with a different dynamics. For instance you can model a canonical 

ensemble with the Langevin dynamics, which couples the system to a heat bath: 

dyn = Langevin(atoms, 1 * fs, kB * 300, 0.002, trajectory=traj) 

6.5 Videos 

The following video tutorials are available: 

• Overview and installation of ASE, by Anthony Goodrow (duration: ~5min 30sec; size: 26 MB) - en: 

6.5. Videos 51



CHAPTER 

SEVEN 

DOCUMENTATION FOR MODULES IN 

ASE 

Quick links: 

atom atoms calculators constraints dft 

data gui infrared io lattice 

md neb optimize parallel phonons 

spacegroup structure surface transport thermochemistry 

units utils vibrations visualize vtk 

See Also: 

• Tutorials 

• Automatically generated documentation (API) 

• Source code 

List of all modules: 

7.1 The Atoms object 

The Atoms object is a collection of atoms. Here is how to define a CO molecule: 


d = 1.1 

co = Atoms(’CO’, positions=[(0, 0, 0), (0, 0, d)]) 

Here, the first argument specifies the type of the atoms and we used the positions keywords to specify their 

positions. Other possible keywords are: numbers, tags, momenta, masses, magmoms and charges. 

Here is how you could make an infinite gold wire with a bond length of 2.9 Å: 


d = 2.9 

L = 10.0 

wire = Atoms(’Au’, 

positions=[(0, L / 2, L / 2)], 

cell=(d, L, L), 

pbc=(1, 0, 0)) 

53


Here, two more optional keyword arguments were used: 

cell: Unit cell size This can be a sequence of three numbers for an orthorhombic unit cell or three by three 

numbers for a general unit cell (a sequence of three sequences of three numbers). The default value is [1.0, 

1.0, 1.0]. 

pbc: Periodic boundary conditions The default value is False - a value of True would give periodic boundary 

conditions along all three axes. It is possible to give a sequence of three booleans to specify periodicity 

along specific axes. 

You can also use the following methods to work with the unit cell and the boundary conditions: set_pbc(), 

set_cell(), get_cell(), and get_pbc(). 

7.1.1 Working with the array methods of Atoms objects 

Like with a single Atom the properties of a collection of atoms can be accessed and changed with get- and setmethods. 

For example the positions of the atoms can be addressed as 

>>> a = Atoms(’N3’, [(0, 0, 0), (1, 0, 0), (0, 0, 1)]) 

>>> a.get_positions() 

array([[ 0., 0., 0.], 

[ 1., 0., 0.], 

[ 0., 0., 1.]]) 

>>> a.set_positions([(2, 0, 0), (0, 2, 2), (2, 2, 0)]) 


array([[ 2., 0., 0.], 

[ 0., 2., 2.], 

[ 2., 2., 0.]]) 

Here is the full list of the get/set methods operating on all the atoms at once. The get methods return an array 

of quantities, one for each atom; the set methods take similar arrays. E.g. get_positions() return N * 3 

numbers, get_atomic_numbers() return N integers. 

These methods return copies of the internal arrays, it is thus safe to modify the returned arrays. 

54 Chapter 7. Documentation for modules in ASE


get_atomic_numbers() set_atomic_numbers() 

get_charges() set_charges() 

get_chemical_symbols() set_chemical_symbols() 

get_initial_magnetic_moments() set_initial_magnetic_moments() 

get_magnetic_moments() 

get_masses() set_masses() 

get_momenta() set_momenta() 

get_forces() 

get_positions() set_positions() 

get_potential_energies() 

get_scaled_positions() set_scaled_positions() 

get_stresses() 

get_tags() set_tags() 

get_velocities() set_velocities() 

There are also a number of get/set methods that operate on quantities common to all the atoms or defined for the 

collection of atoms: 

get_calculator() set_calculator() 

get_cell() set_cell() 

get_center_of_mass() 

get_kinetic_energy() 

get_magnetic_moment() 

get_name() 

get_number_of_atoms() 

get_pbc() set_pbc() 

get_potential_energy() 

get_stress() 

get_total_energy() 

get_volume() 

7.1.2 Unit cell and boundary conditions 

The Atoms object holds a unit cell which by default is the 3x3 unit matrix as can be seen from 

>>> a.get_cell() 

array([[ 1., 0., 0.], 

[ 0., 1., 0.], 

[ 0., 0., 1.]]) 

The cell can be defined or changed using the set_cell() method. Changing the unit cell does per default not 

move the atoms: 

>>> a.set_cell(2 * identity(3)) 


array([[ 2., 0., 0.], 

[ 0., 2., 0.], 

[ 0., 0., 2.]]) 


array([[ 2., 0., 0.], 

[ 1., 1., 0.], 

[ 2., 2., 0.]]) 

However if we set scale_atoms=True the atomic positions are scaled with the unit cell: 

>>> a.set_cell(identity(3), scale_atoms=True) 


array([[ 1. , 0. , 0. ], 

[ 0.5, 0.5, 0. ], 

[ 1. , 1. , 0. ]]) 

7.1. The Atoms object 55


The set_pbc() method specifies whether periodic boundary conditions are to be used in the directions of the 

three vectors of the unit cell. A slab calculation with periodic boundary conditions in x and y directions and free 

boundary conditions in the z direction is obtained through 

>>> a.set_pbc((True, True, False)) 

7.1.3 Special attributes 

It is also possible to work directly with the attributes positions, numbers, pbc and cell. Here we change 

the position of the 2nd atom (which has count number 1 because Python starts counting at zero) and the type of 

the first atom: 

>>> a.positions[1] = (1, 1, 0) 


array([[2., 0., 0.], 

[1., 1., 0.], 

[2., 2., 0.]]) 

>>> a.positions 

array([[2., 0., 0.], 

[1., 1., 0.], 

[2., 2., 0.]]) 

>>> a.numbers 

array([7, 7, 7]) 

>>> a.numbers[0] = 13 

>>> a.get_chemical_symbols() 

[’Al’, ’N’, ’N’] 

Check for periodic boundary conditions: 

>>> a.pbc # equivalent to a.get_pbc() 

array([False, False, False], dtype=bool) 

>>> a.pbc.any() 

False 

>>> a.pbc[2] = 1 

>>> a.pbc 

array([False, False, True], dtype=bool) 

7.1.4 Adding a calculator 

A calculator can be attached to the atoms with the purpose of calculating energies and forces on the atoms. ASE 

works with many different calculators. 

A calculator object calc is attached to the atoms like this: 

>>> a.set_calculator(calc) 

After the calculator has been appropriately setup the energy of the atoms can be obtained through 

>>> a.get_potential_energy() 

The term “potential energy” here means for example the total energy of a DFT calculation, which includes both 

kinetic, electrostatic, and exchange-correlation energy for the electrons. The reason it is called potential energy is 

that the atoms might also have a kinetic energy (from the moving nuclei) and that is obtained with 

>>> a.get_kinetic_energy() 

In case of a DFT calculator, it is up to the user to check exactly what the get_potential_energy() method 

returns. For example it may be the result of a calculation with a finite temperature smearing of the occupation 

numbers extrapolated to zero temperature. More about this can be found for the different calculators. 

The following methods can only be called if a calculator is present: 


• get_potential_energy() 

• get_potential_energies() 

• get_forces() 

• get_stress() 

• get_stresses() 

• get_total_energy() 

• get_magnetic_moments() 

• get_magnetic_moment() 

Not all of these methods are supported by all calculators. 

7.1.5 List-methods 

method example 

+ wire2 = wire + co 

+=, extend() wire += co 

wire.extend(co) 

append() wire.append(Atom(’H’)) 

* 

wire3 = wire * (3, 1, 1) 

*=, repeat() wire *= (3, 1, 1) 

wire.repeat((3, 1, 1)) 

len len(co) 

del del wire3[0] 

del wire3[[1,3]] 

pop() oxygen = wire2.pop() 


Note that the del method can be used with the more powerful numpy-style indexing, as in the second example 

above. This can be combined with python list comprehension in order to selectively delete atoms within an ASE 

Atoms object. For example, the below code creates an ethanol molecule and subsequently strips all the hydrogen 

atoms from it: 


atoms = molecule(’CH3CH2OH’) 

del atoms[[atom.index for atom in atoms if atom.symbol==’H’]] 

7.1.6 Other methods 

• center() 

• translate() 

• rotate() 

• rotate_euler() 

• get_dihedral() 

• set_dihedral() 

• rotate_dihedral() 

• rattle() 

• set_constraint() 

• set_distance() 

• copy() 



• get_center_of_mass() 

• get_distance() 

• get_volume() 

• has() 

• edit() 

• identical_to() 

7.1.7 List of all Methods 

class ase.atoms.Atoms(symbols=None, positions=None, numbers=None, tags=None, momenta=None, 

masses=None, magmoms=None, charges=None, 

scaled_positions=None, cell=None, pbc=None, celldisp=None, constraint=None, 

calculator=None, info=None) 

Atoms object. 

The Atoms object can represent an isolated molecule, or a periodically repeated structure. It has a unit cell 

and there may be periodic boundary conditions along any of the three unit cell axes. 

Information about the atoms (atomic numbers and position) is stored in ndarrays. Optionally, there can be 

information about tags, momenta, masses, magnetic moments and charges. 

In order to calculate energies, forces and stresses, a calculator object has to attached to the atoms object. 

Parameters: 

symbols: str (formula) or list of str Can be a string formula, a list of symbols or a list of Atom objects. 

Examples: ‘H2O’, ‘COPt12’, [’H’, ‘H’, ‘O’], [Atom(‘Ne’, (x, y, z)), ...]. 

positions: list of xyz-positions Atomic positions. Anything that can be converted to an ndarray of shape 

(n, 3) will do: [(x1,y1,z1), (x2,y2,z2), ...]. 

scaled_positions: list of scaled-positions Like positions, but given in units of the unit cell. Can not be set 

at the same time as positions. 

numbers: list of int Atomic numbers (use only one of symbols/numbers). 

tags: list of int Special purpose tags. 

momenta: list of xyz-momenta Momenta for all atoms. 

masses: list of float Atomic masses in atomic units. 

magmoms: list of float or list of xyz-values Magnetic moments. Can be either a single value for each 

atom for collinear calculations or three numbers for each atom for non-collinear calculations. 

charges: list of float Atomic charges. 

cell: 3x3 matrix Unit cell vectors. Can also be given as just three numbers for orthorhombic cells. Default 

value: [1, 1, 1]. 

celldisp: Vector Unit cell displacement vector. To visualize a displaced cell around the center of mass of a 

Systems of atoms. Default value = (0,0,0) 

pbc: one or three bool Periodic boundary conditions flags. Examples: True, False, 0, 1, (1, 1, 0), (True, 

False, False). Default value: False. 

constraint: constraint object(s) Used for applying one or more constraints during structure optimization. 

calculator: calculator object Used to attach a calculator for calculating energies and atomic forces. 

info: dict of key-value pairs Dictionary of key-value pairs with additional information about the system. 

The following keys may be used by ase: 

• spacegroup: Spacegroup instance 


• unit_cell: ‘conventional’ | ‘primitive’ | int | 3 ints 

• adsorbate_info: 


Items in the info attribute survives copy and slicing and can be store to and retrieved from trajectory 

files given that the key is a string, the value is picklable and, if the value is a user-defined object, its 

base class is importable. One should not make any assumptions about the existence of keys. 

Examples: 

These three are equivalent: 

>>> d = 1.104 # N2 bondlength 

>>> a = Atoms(’N2’, [(0, 0, 0), (0, 0, d)]) 

>>> a = Atoms(numbers=[7, 7], positions=[(0, 0, 0), (0, 0, d)]) 

>>> a = Atoms([Atom(’N’, (0, 0, 0)), Atom(’N’, (0, 0, d)]) 

FCC gold: 

>>> a = 4.05 # Gold lattice constant 

>>> b = a / 2 

>>> fcc = Atoms(’Au’, 

... cell=[(0, b, b), (b, 0, b), (b, b, 0)], 

... pbc=True) 

Hydrogen wire: 

>>> d = 0.9 # H-H distance 

>>> L = 7.0 

>>> h = Atoms(’H’, positions=[(0, L / 2, L / 2)], 

... cell=(d, L, L), 

... pbc=(1, 0, 0)) 

append(atom) 

Append atom to end. 

calc 

Calculator object. 

cell 

Attribute for direct manipulation of the unit cell. 

center(vacuum=None, axis=None) 

Center atoms in unit cell. 

Centers the atoms in the unit cell, so there is the same amount of vacuum on all sides. 

Parameters: 

vacuum (default: None): If specified adjust the amount of vacuum when centering. If vacuum=10.0 

there will thus be 10 Angstrom of vacuum on each side. 

axis (default: None): If specified, only act on the specified axis. Default: Act on all axes. 

constraints 

Constraints of the atoms. 

copy() 

Return a copy. 

edit() 

Modify atoms interactively through ag viewer. 

Conflicts leading to undesirable behaviour might arise when matplotlib has been pre-imported with 

certain incompatible backends and while trying to use the plot feature inside the interactive ag. To 

circumvent, please set matplotlib.use(‘gtk’) before calling this method. 

extend(other) 

Extend atoms object by appending atoms from other. 



get_angle(list) 

Get angle formed by three atoms. 

calculate angle between the vectors list[0]->list[1] and list[1]->list[2], where list contains the atomic 

indexes in question. 

get_angular_momentum() 

Get total angular momentum with respect to the center of mass. 

get_array(name, copy=True) 

Get an array. 

Returns a copy unless the optional argument copy is false. 

get_atomic_numbers() 

Get integer array of atomic numbers. 

get_calculation_done() 

Let the calculator calculate its thing, using the current input. 

get_calculator() 

Get currently attached calculator object. 

get_cell() 

Get the three unit cell vectors as a 3x3 ndarray. 

get_celldisp() 

Get the unit cell displacement vectors . 

get_center_of_mass(scaled=False) 

Get the center of mass. 

If scaled=True the center of mass in scaled coordinates is returned. 

get_charges() 

Get array of charges. 

get_chemical_formula(mode=’hill’) 

Get the chemial formula as a string based on the chemical symbols. 

Parameters: 

mode: There are three different modes available: 

‘all’: The list of chemical symbols are contracted to at string, e.g. [’C’, ‘H’, ‘H’, ‘H’, ‘O’, ‘H’] 

becomes ‘CHHHOH’. 

‘reduce’: The same as ‘all’ where repeated elements are contracted to a single symbol and a 

number, e.g. ‘CHHHOCHHH’ is reduced to ‘CH3OCH3’. 

‘hill’: The list of chemical symbols are contracted to a string following the Hill notation (alphabetical 

order with C and H first), e.g. ‘CHHHOCHHH’ is reduced to ‘C2H6O’ and ‘SOOHOHO’ 

to ‘H2O4S’. This is default. 

get_chemical_symbols(reduce=False) 

Get list of chemical symbol strings. 

get_dihedral(list) 

Calculate dihedral angle. 

Calculate dihedral angle between the vectors list[0]->list[1] and list[2]->list[3], where list contains the 

atomic indexes in question. 

get_dipole_moment() 

Calculate the electric dipole moment for the atoms object. 

Only available for calculators which has a get_dipole_moment() method. 


get_distance(a0, a1, mic=False) 

Return distance between two atoms. 

Use mic=True to use the Minimum Image Convention. 

get_forces(apply_constraint=True) 

Calculate atomic forces. 


Ask the attached calculator to calculate the forces and apply constraints. Use apply_constraint=False 

to get the raw forces. 

get_initial_magnetic_moments() 

Get array of initial magnetic moments. 

get_isotropic_pressure(stress) 

Get the current calculated pressure, assume isotropic medium. in Bar 

get_kinetic_energy() 

Get the kinetic energy. 


Get calculated total magnetic moment. 

get_magnetic_moments() 

Get calculated local magnetic moments. 

get_masses() 

Get array of masses. 

get_momenta() 

Get array of momenta. 

get_moments_of_inertia(vectors=False) 

Get the moments of inertia along the principal axes. 

The three principal moments of inertia are computed from the eigenvalues of the symmetric inertial 

tensor. Periodic boundary conditions are ignored. Units of the moments of inertia are 

amu*angstrom**2. 

get_number_of_atoms() 

Returns the number of atoms. 

Equivalent to len(atoms) in the standard ASE Atoms class. 

get_pbc() 

Get periodic boundary condition flags. 

get_positions(wrap=False) 

Get array of positions. If wrap==True, wraps atoms back into unit cell. 

get_potential_energies() 

Calculate the potential energies of all the atoms. 

Only available with calculators supporting per-atom energies (e.g. classical potentials). 

get_potential_energy() 

Calculate potential energy. 

get_reciprocal_cell() 

Get the three reciprocal lattice vectors as a 3x3 ndarray. 

Note that the commonly used factor of 2 pi for Fourier transforms is not included here. 

get_scaled_positions() 

Get positions relative to unit cell. 

Atoms outside the unit cell will be wrapped into the cell in those directions with periodic boundary 

conditions so that the scaled coordinates are between zero and one. 



get_stress(voigt=True) 

Calculate stress tensor. 

Returns an array of the six independent components of the symmetric stress tensor, in the traditional 

Voigt order (xx, yy, zz, yz, xz, xy) or as a 3x3 matrix. Default is Voigt order. 

get_stresses() 

Calculate the stress-tensor of all the atoms. 

Only available with calculators supporting per-atom energies and stresses (e.g. classical potentials). 

Even for such calculators there is a certain arbitrariness in defining per-atom stresses. 

get_tags() 

Get integer array of tags. 

get_temperature() 

Get the temperature. in Kelvin 

get_total_energy() 

Get the total energy - potential plus kinetic energy. 

get_velocities() 

Get array of velocities. 

get_volume() 

Get volume of unit cell. 

has(name) 

Check for existence of array. 

name must be one of: ‘tags’, ‘momenta’, ‘masses’, ‘magmoms’, ‘charges’. 

new_array(name, a, dtype=None, shape=None) 

Add new array. 

If shape is not None, the shape of a will be checked. 

numbers 

Attribute for direct manipulation of the atomic numbers. 

pbc 

Attribute for direct manipulation of the periodic boundary condition flags. 

pop(i=-1) 

Remove and return atom at index i (default last). 

positions 

Attribute for direct manipulation of the positions. 

rattle(stdev=0.001, seed=42) 

Randomly displace atoms. 

This method adds random displacements to the atomic positions, taking a possible constraint into 

account. The random numbers are drawn from a normal distribution of standard deviation stdev. 

For a parallel calculation, it is important to use the same seed on all processors! 

repeat(rep) 

Create new repeated atoms object. 

The rep argument should be a sequence of three positive integers like (2,3,1) or a single integer (r) 

equivalent to (r,r,r). 

rotate(v, a=None, center=(0, 0, 0), rotate_cell=False) 

Rotate atoms based on a vector and an angle, or two vectors. 

Parameters: 

v: Vector to rotate the atoms around. Vectors can be given as strings: ‘x’, ‘-x’, ‘y’, ... . 



a = None: Angle that the atoms is rotated around the vecor ‘v’. If an angle is not specified, the length 

of ‘v’ is used as the angle (default). The angle can also be a vector and then ‘v’ is rotated into ‘a’. 

center = (0, 0, 0): The center is kept fixed under the rotation. Use ‘COM’ to fix the center of mass, 

‘COP’ to fix the center of positions or ‘COU’ to fix the center of cell. 

rotate_cell = False: If true the cell is also rotated. 

Examples: 

Rotate 90 degrees around the z-axis, so that the x-axis is rotated into the y-axis: 

>>> a = pi / 2 

>>> atoms.rotate(’z’, a) 

>>> atoms.rotate((0, 0, 1), a) 

>>> atoms.rotate(’-z’, -a) 

>>> atoms.rotate((0, 0, a)) 

>>> atoms.rotate(’x’, ’y’) 

rotate_dihedral(list, angle, mask=None) 

Rotate dihedral angle. 

Complementing the two routines above: rotate a group by a predefined dihedral angle, starting from 

its current configuration 

rotate_euler(center=(0, 0, 0), phi=0.0, theta=0.0, psi=0.0) 

Rotate atoms via Euler angles. 

See e.g http://mathworld.wolfram.com/EulerAngles.html for explanation. 

Parameters: 

center : The point to rotate about. A sequence of length 3 with the coordinates, or ‘COM’ to select 

the center of mass, ‘COP’ to select center of positions or ‘COU’ to select center of cell. 

phi : The 1st rotation angle around the z axis. 

theta : Rotation around the x axis. 

psi : 2nd rotation around the z axis. 

set_angle(list, angle, mask=None) 

Set angle formed by three atoms. 

Sets the angle between vectors list[1]->list[0] and list[1]->list[2]. 

Same usage as in set_dihedral. 

set_array(name, a, dtype=None, shape=None) 

Update array. 

If shape is not None, the shape of a will be checked. If a is None, then the array is deleted. 

set_atomic_numbers(numbers) 

Set atomic numbers. 

set_calculator(calc=None) 

Attach calculator object. 

set_cell(cell, scale_atoms=False, fix=None) 

Set unit cell vectors. 

Parameters: 

cell [] Unit cell. A 3x3 matrix (the three unit cell vectors) or just three numbers for an orthorhombic 

cell. 

scale_atoms [bool] Fix atomic positions or move atoms with the unit cell? Default behavior is to not 

move the atoms (scale_atoms=False). 



Examples: 

Two equivalent ways to define an orthorhombic cell: 

>>> a.set_cell([a, b, c]) 

>>> a.set_cell([(a, 0, 0), (0, b, 0), (0, 0, c)]) 

FCC unit cell: 

>>> a.set_cell([(0, b, b), (b, 0, b), (b, b, 0)]) 

set_charges(charges) 

Set charges. 

set_chemical_symbols(symbols) 

Set chemical symbols. 

set_constraint(constraint=None) 

Apply one or more constrains. 

The constraint argument must be one constraint object or a list of constraint objects. 

set_dihedral(list, angle, mask=None) 

set the dihedral angle between vectors list[0]->list[1] and list[2]->list[3] by changing the atom indexed 

by list[3] if mask is not None, all the atoms described in mask (read: the entire subgroup) are moved 

example: the following defines a very crude ethane-like molecule and twists one half of it by 30 

degrees. 

>>> atoms = Atoms(’HHCCHH’, [[-1, 1, 0], [-1, -1, 0], [0, 0, 0], 

[1, 0, 0], [2, 1, 0], [2, -1, 0]]) 

>>> atoms.set_dihedral([1,2,3,4],7*pi/6,mask=[0,0,0,1,1,1]) 

set_distance(a0, a1, distance, fix=0.5) 

Set the distance between two atoms. 

Set the distance between atoms a0 and a1 to distance. By default, the center of the two atoms will be 

fixed. Use fix=0 to fix the first atom, fix=1 to fix the second atom and fix=0.5 (default) to fix the center 

of the bond. 

set_initial_magnetic_moments(magmoms=None) 

Set the initial magnetic moments. 

Use either one or three numbers for every atom (collinear or non-collinear spins). 

set_masses(masses=’defaults’) 

Set atomic masses. 

The array masses should contain a list of masses. In case the masses argument is not given or for those 

elements of the masses list that are None, standard values are set. 

set_momenta(momenta) 

Set momenta. 

set_pbc(pbc) 

Set periodic boundary condition flags. 

set_positions(newpositions) 

Set positions, honoring any constraints. 

set_scaled_positions(scaled) 

Set positions relative to unit cell. 

set_tags(tags) 

Set tags for all atoms. 

set_velocities(velocities) 

Set the momenta by specifying the velocities. 


translate(displacement) 

Translate atomic positions. 


The displacement argument can be a float an xyz vector or an nx3 array (where n is the number of 

atoms). 

write(filename, format=None, **kwargs) 

Write yourself to a file. 

7.2 The Atom object 

ASE defines a python class called Atom to setup and handle atoms in electronic structure and molecular simulations. 

From a python script, atoms can be created like this: 

>>> from ase import Atom 

>>> a1 = Atom(’Si’, (0, 0, 0)) 

>>> a2 = Atom(’H’, (1.3, 0, 0), mass=2) 

>>> a3 = Atom(position=(0, 0, 0), Z=14) # same is a1 

class ase.atom.Atom(symbol=’X’, position=(0, 0, 0), tag=None, momentum=None, mass=None, magmom=None, 

charge=None, atoms=None, index=None) 

Class for representing a single atom. 

Parameters: 

symbol: str or int Can be a chemical symbol (str) or an atomic number (int). 

position: sequence of 3 floats Atomi position. 

tag: int Special purpose tag. 

momentum: sequence of 3 floats Momentum for atom. 

mass: float Atomic mass in atomic units. 

magmom: float or 3 floats Magnetic moment. 

charge: float Atomic charge. 

The first argument to the constructor of an Atom object is the chemical symbol, and the second argument is the 

position in Å units (see units). The position can be any numerical sequence of length three. The properties of 

an atom can also be set using keywords like it is done in the a2 and a3 examples above. 

More examples: 

>>> a = Atom(’O’, charge=-2) 

>>> b = Atom(8, charge=-2) 

>>> c = Atom(’H’, (1, 2, 3), magmom=1) 

>>> print a.charge, a.position 

-2 [ 0. 0. 0.] 

>>> c.x = 0.0 

>>> c.position 

array([ 0., 2., 3.]) 

>>> b.symbol 

’O’ 

>>> c.tag = 42 

>>> c.number 

1 

>>> c.symbol = ’Li’ 

>>> c.number 

3 

If the atom object belongs to an Atoms object, then assigning values to the atom attributes will change the corresponding 

arrays of the atoms object: 

7.2. The Atom object 65


>>> OH = Atoms(’OH’) 

>>> OH[0].charge = -1 

>>> OH.get_charges() 

array([-1., 0.]) 

Another example: 

>>> for atom in bulk: 

... if atom.symbol = ’Ni’: 

... atom.magmom = 0.7 # set initial magnetic moment 

The different properties of an atom can be obtained and changed via attributes (position, number, tag, 

momentum, mass, magmom, charge, x, y, z): 

>>> a1.position = [1, 0, 0] 

>>> a1.position 

array([ 1., 0., 0.]) 

>>> a1.z = 2.5 

>>> a1.position 

array([ 1. , 0. , 2.5]) 

>>> a2.magmom = 1.0 

That last line will set the initial magnetic moment that some calulators use (similar to the 

set_initial_magnetic_moments() method). 

Note: The position and momentum attributes refer to mutable objects, so in some cases, you may want to 

use a1.position.copy() in order to avoid changing the position of a1 by accident. 

7.2.1 Getting an Atom from an Atoms object 

Indexing an Atoms object returns an Atom object still remembering that it belongs to the collective Atoms: 

Modifying it will also change the atoms object: 

>>> atoms = ase.data.molecules.molecule(’CH4’) 


array([[ 0. , 0. , 0. ], 

[ 0.629118, 0.629118, 0.629118], 

[-0.629118, -0.629118, 0.629118], 

[ 0.629118, -0.629118, -0.629118], 

[-0.629118, 0.629118, -0.629118]]) 

>>> a = atoms[2] 

>>> a 

Atom(’H’, [-0.62911799999999996, -0.62911799999999996, 0.62911799999999996], index=2) 

>>> a.x = 0 


array([[ 0. , 0. , 0. ], 

[ 0.629118, 0.629118, 0.629118], 

[ 0. , -0.629118, 0.629118], 

[ 0.629118, -0.629118, -0.629118], 

[-0.629118, 0.629118, -0.629118]]) 

See Also: 

Atom: All the details! 

atoms: More information about how to use collections of atoms. 

calculators: Information about how to calculate forces and energies of atoms. 


7.3 Units 


Physical units are defined in the ase/units.py module. Electron volts (eV) and angstroms (Ang) are defined as 1.0. 

Other units are nm, Bohr, Hartree or Ha, kJ, kcal, mol, Rydberg or Ry, second, fs and kB. 

Note: All constants are taken from the 1986 CODATA. 

Examples: 

>>> from ase import * 

>>> 2 * Bohr 

1.0583545150138329 

>>> 25 * Rydberg 

340.14244569396635 

>>> 100 * kJ/mol 

1.0364272141304978 

>>> 300 * kB 

0.025852157076770025 

>>> 0.1 * fs 

0.009822693531550318 

>>> print ’1 Hartree = ’+str(Hartree*mol/kcal)+’ kcal/mol’ 

7.4 The ase.data module 

This module defines the following variables: atomic_masses, atomic_names, chemical_symbols, 

covalent_radii, cpk_colors and reference_states. All of these are lists that should be indexed 

with an atomic number: 

>>> atomic_names[92] 

’Uranium’ 

>>> atomic_masses[2] 

4.0026000000000002 

If you don’t know the atomic number of some element, then you can look it up in the atomic_numbers 

dictionary: 

>>> atomic_numbers[’Cu’] 

29 

>>> covalent_radii[29] 

1.1699999999999999 

7.5 File input and output 

The io module has two basic functions: read() and write(). The two methods are described here: 

ase.io.read(filename, index=-1, format=None) 

Read Atoms object(s) from file. 

filename: str Name of the file to read from. 

index: int or slice If the file contains several configurations, the last configuration will be returned by 

default. Use index=n to get configuration number n (counting from zero). 

format: str Used to specify the file-format. If not given, the file-format will be guessed by the filetype 

function. 

Known formats: 

7.3. Units 67


format short name 

GPAW restart-file gpw 

Dacapo netCDF output file dacapo 

Old ASE netCDF trajectory nc 

Virtual Nano Lab file vnl 

ASE pickle trajectory traj 

ASE bundle trajectory bundle 

GPAW text output gpaw-text 

CUBE file cube 

XCrySDen Structure File xsf 

Dacapo text output dacapo-text 

XYZ-file xyz 

VASP POSCAR/CONTCAR file vasp 

VASP OUTCAR file vasp_out 

SIESTA STRUCT file struct_out 

ABINIT input file abinit 

V_Sim ascii file v_sim 

Protein Data Bank pdb 

CIF-file cif 

FHI-aims geometry file aims 

FHI-aims output file aims_out 

VTK XML Image Data vti 

VTK XML Structured Grid vts 

VTK XML Unstructured Grid vtu 

TURBOMOLE coord file tmol 

TURBOMOLE gradient file tmol-gradient 

exciting input exi 

AtomEye configuration cfg 

WIEN2k structure file struct 

DftbPlus input file dftb 

CASTEP geom file cell 

CASTEP output file castep 

CASTEP trajectory file geom 

ETSF format etsf.nc 

DFTBPlus GEN format gen 

CMR db/cmr-file db 

CMR db/cmr-file cmr 

LAMMPS dump file lammps 

EON reactant.con file eon 

Gromacs coordinates gro 

Gaussian com (input) file gaussian 

Gaussian output file gaussian_out 

ase.io.write(filename, images, format=None, **kwargs) 

Write Atoms object(s) to file. 

filename: str Name of the file to write to. 

images: Atoms object or list of Atoms objects A single Atoms object or a list of Atoms objects. 

format: str Used to specify the file-format. If not given, the file-format will be taken from suffix of the 

filename. 

The accepted output formats: 


ASE pickle trajectory traj 

Continued on next page 


The use of additional keywords is format specific. 

Table 7.2 – continued from previous page 


ASE bundle trajectory bundle 

CUBE file cube 

XYZ-file xyz 

VASP POSCAR/CONTCAR file vasp 

ABINIT input file abinit 

Protein Data Bank pdb 

CIF-file cif 

XCrySDen Structure File xsf 

FHI-aims geometry file aims 

gOpenMol .plt file plt 

Python script py 

Encapsulated Postscript eps 

Portable Network Graphics png 

Persistance of Vision pov 

VTK XML Image Data vti 

VTK XML Structured Grid vts 

VTK XML Unstructured Grid vtu 

TURBOMOLE coord file tmol 

exciting exi 

AtomEye configuration cfg 

WIEN2k structure file struct 

CASTEP cell file cell 

DftbPlus input file dftb 

ETSF etsf.nc 

DFTBPlus GEN format gen 

CMR db/cmr-file db 

CMR db/cmr-file cmr 

EON reactant.con file eon 

Gromacs coordinates gro 

GROMOS96 (only positions) g96 


The cube and plt formats accept (plt requires it) a data keyword, which can be used to write a 3D array 

to the file along with the nuclei coordinates. 

The vti, vts and vtu formats are all specifically directed for use with MayaVi, and the latter is designated 

for visualization of the atoms whereas the two others are intended for volume data. Further, it should be 

noted that the vti format is intended for orthogonal unit cells as only the grid-spacing is stored, whereas 

the vts format additionally stores the coordinates of each grid point, thus making it useful for volume date 

in more general unit cells. 

The eps, png, and pov formats are all graphics formats, and accept the additional keywords: 

rotation: str (default ‘’) The rotation angles, e.g. ‘45x,70y,90z’. 

show_unit_cell: int (default 0) Can be 0, 1, 2 to either not show, show, or show all of the unit cell. 

radii: array or float (default 1.0) An array of same length as the list of atoms indicating the sphere radii. 

A single float specifies a uniform scaling of the default covalent radii. 

bbox: 4 floats (default None) Set the bounding box to (xll, yll, xur, yur) (lower left, upper right). 

colors: array (default None) An array of same length as the list of atoms, indicating the rgb color code 

for each atom. Default is the jmol_colors of ase/data/colors. 

scale: int (default 20) Number of pixels per Angstrom. 

7.5. File input and output 69


For the pov graphics format, scale should not be specified. The elements of the color array can additionally 

be strings, or 4 and 5 vectors for named colors, rgb + filter, and rgb + filter + transmit specification. 

This format accepts the additional keywords: 

run_povray, display, pause, transparent, canvas_width, canvas_height, 

camera_dist, image_plane, camera_type, point_lights, area_light, background, 

textures, celllinewidth, bondlinewidth, bondatoms 

The read() function is only designed to retrive the atomic configuration from a file, but for the CUBE format 

you can import the function: 

io.read_cube_data() 

which will return a (data, atoms) tuple: 

from ase.io.cube import read_cube_data 

data, atoms = read_cube_data(’abc.cube’) 

7.6 Examples 


adsorbate = Atoms(’CO’) 

adsorbate[1].z = 1.1 

a = 3.61 

slab = fcc111(’Cu’, (2, 2, 3), a=a, vacuum=7.0) 

add_adsorbate(slab, adsorbate, 1.8, ’ontop’) 

Write PNG image: 

write(’slab.png’, slab * (3, 3, 1), rotation=’10z,-80x’) 

Write POVRAY file: 

write(’slab.pov’, slab * (3, 3, 1), rotation=’10z,-80x’) 

This will write both a slab.pov and a slab.ini file. Convert to PNG with the command povray 

slab.ini or use the run_povray=True option: 


Here is an example using bbox: 

d = a / 2**0.5 

write(’slab.pov’, slab * (2, 2, 1), 

bbox=(d, 0, 3 * d, d * 3**0.5)) 

Note that the XYZ-format does not contain information about the unic cell: 

>>> write(’slab.xyz’, slab) 

>>> a = read(’slab.xyz’) 


array([[ 1., 0., 0.], 

[ 0., 1., 0.], 

[ 0., 0., 1.]]) 

>>> a.get_pbc() 

array([False, False, False], dtype=bool) 

Use ASE’s native format for writing all information: 

>>> write(’slab.traj’, slab) 

>>> b = read(’slab.traj’) 

>>> b.get_cell() 

array([[ 5.10531096e+00, -4.11836034e-16, 1.99569088e-16], 

[ 2.55265548e+00, 4.42132899e+00, 7.11236625e-17], 

[ 8.11559027e+00, 4.68553823e+00, 1.32527034e+01]]) 

>>> b.get_pbc() 

array([ True, True, True], dtype=bool) 


A script showing all of the povray parameters, and generating the image below, can be found here: 

doc/ase/save_pov.py 

7.6. Examples 71


An other example showing how to change colors and textures in pov can be found here: 

doc/tutorials/saving_graphics.py 

7.7 ASE-GUI 

The graphical user-interface allows users to visualize, manipulate, and render molecular systems and atoms objects. 

It also allows to setup and run a number of calculations and can be used to transfer between different file 

formats. 


7.7.1 ag basics and command line options 

General use 


Visualizing a system with ag is straight-forward using a regular mouse. The scroll function allows to change the 

magnification, the left mouse button selects atoms, the right mouse button allows to rotate, and the middle button 

allows to translate the system on the screen. 

Depending on the number of selected atoms, ag automatically measures different quantities: 

Selection measurement 

single atom xyz position and atomic symbol 

two atoms interatomic distance and symbols 

three atoms all three internal angles and symbols 

four atoms, selected sequentially Measures the dihedral angle, e.g. the angle between bonds 12 and 34 

more than four atoms chemical composition of selection. 

ag can save the following file formats: 

File format Comment 

xyz XYZ file 

traj ASE trajectory 

pdb PDB file 

cube Gaussian cube file 

py Python script 

vnl VNL file 

png Portable Network Graphics 

pov Persistance of Vision 

eps Encapsulated PostScript 

in FHI-aims geometry input 

POSCAR VASP geometry input 

bundle ASE bundle trajectory 

cif Crystallographic Information File 

Files 

The ag program can read all the file formats the ASE’s read() function can understand. 

$ ag N2Fe110-path.traj 

Selecting part of a trajectory 

A Python-like syntax for selecting a subset of configurations can be used. Instead of the Python syntax 

list[start:stop:step], you use filaname@start:stop:step: 

$ ag x.traj@0:10:1 # first 10 images 

$ ag x.traj@0:10 # first 10 images 

$ ag x.traj@:10 # first 10 images 

$ ag x.traj@-10: # last 10 images 

$ ag x.traj@0 # first image 

$ ag x.traj@-1 # last image 

$ ag x.traj@::2 # every second image 

If you want to select the same range from many files, the you can use the -n or --image-number option: 

$ ag -n -1 *.traj # last image from all files 

$ ag -n 0 *.traj # first image from all files 

Tip: Type ag -h for a description of all command line options. 

7.7. ASE-GUI 73


Writing files 

$ ag -n -1 a*.traj -o new.traj 

Possible formats are: traj, xyz, cube, pdb, eps, png, and pov. For details, see the io module documentation. 

Interactive use 

The ag program can also be launched directly from a Python script or interactive session: 


>>> atoms = ... 


or 

>>> view(atoms, repeat=(3, 3, 2)) 

or, to keep changes to your atoms: 

>>> atoms.edit() 

NEB calculations 

Use Tools → NEB to plot energy barrier. 

$ ag --interpolate 3 initial.xyz final.xyz -o interpolated_path.traj 

Plotting data from the command line 

Plot the energy relative to the energy of the first image as a function of the distance between atom 0 and 5: 

$ ag -g "d(0,5),e-E[0]" x.traj 

$ ag -t -g "d(0,5),e-E[0]" x.traj > x.dat # No GUI, write data to stdout 

The symbols are the same as used in the plotting data function. 

Defaults for ag 

Using a file ~/.ase/gui.py, certain defaults can be set. If it exists, this file is executed after initializing the 

variables and colours normally used in ag. One can change the default graphs that are plotted, and the default radii 

for displaying specific atoms. This example will display the energy evolution and the maximal force in a graph 

and also display Cu atoms (Z=29) with a radius of 1.6 Angstrom. 

gui_default_settings[’gui_graphs_string’] = "i, e - min(E), fmax" 

gui_default_settings[’covalent_radii’] = [[29,1.6]] 

High contrast settings for ag 

In revision 2600 or later, it is possible to change the foreground and background colors used to draw the atoms, 

for instance to draw white graphics on a black background. This can be done in ~/.ase/gui.py. 

gui_default_settings[’gui_foreground_color’] = ’#ffffff’ #white 

gui_default_settings[’gui_background_color’] = ’#000000’ #black 



To change the color scheme of graphs it is necessary to change the default behaviour of Matplotlib in a similar 

way by using a file ~/.matplotlib/matplotlibrc. 

patch.edgecolor : white 

text.color : white 

axes.facecolor : black 

axes.edgecolor : white 

axes.labelcolor : white 

axes.color_cycle : b, g, r, c, m, y, w 

xtick.color : white 

ytick.color : white 

grid.color : white 

figure.facecolor : 0.1 

figure.edgecolor : black 

Finally, the color scheme of the windows themselves (i.e. menus, buttons and text etc.) can be changed by 

choosing a different desktop theme. In Ubuntu it is possible to get white on a dark background by selecting the 

theme HighContrastInverse under Appearances in the system settings dialog. 

7.7.2 Edit 

Add atoms 

Allows to add single atoms or a group of atoms to an existing atoms object. If the description is an atom or a 

known molecule from the g1, g2, or g3 set (e.g. CH4), then the structure from the data molecule is used. In 

addition, a molecule can also be imported from file via the load molecule button. 

The specified position can either be absolute, or determined automatically via 

auto+ 

where auto is the centre of mass of the currently selected atoms, and is the distance toward the viewing 

plane. 

The molecule-to-be is rotated into the current viewing plane before addition into the system. Two options exist for 

chosing the origin within the new atoms, it can be either the centre of mass or the origin of the loaded geometry. 

Modify 

Menu to allow modification of the atomic symbol, an attached tag, or its magnetic moment. 

Copy/Paste 

Allows to copy parts of an existing system to a clipboard, and pastes via the same infrastructure as the Add 

atoms functionality. Note that the on-screen orientation of the pasted atoms will be the same as at the time of 

copying. Note also that, by default, the origin of the pasted system is taken to be the atom furthest away from the 

viewing point. 

7.7.3 View 

Repeat 

Menu to allow repition of periodic unit cells. Use the ‘Set unit cell’ button to set the overall unit cell to the current 

one. 



Rotate 

Menu to manually fine tune the viewing angle. Use ‘Update’ button to set the menu to the current angle. 

Colors 

The colors menu allows numerous ways to change the color scheme and to encode additional information into 

the display colors. This includes automatic coloring by atomic numbers (default), user-specified atomic number 

scheme, coloring by tags, forces, or completely manually specified colors. In addition, several standard color 

scales are available. 

Settings 

Basic viewing settings. Also allows to constrain/unconstrain atoms and to mark selected atoms as invisible. 

7.7.4 Tools 

Graphs 

Allows to graph different quantities for a given trajectory. A ‘save’ button also gives the opportunity to save the 

data to file. 

This example plots the maximal force for each image i and could help in investigating the convergence properties 

for relaxations: 

i, e-min(E), fmax 

These are the symbols that can be used: 

Symbol Interpretation 

e total energy 

epot potential energy 

ekin kinetic energy 

fmax maximum force 

fave average force 

d(n1,n2) distance between two atoms 

R[n,0-2] position of atom number n 

i current image number 

E[i] energy of image number i 

F[n,0-2] force on atom number n 

M[n] magnetic moment of atom number n 

A[0-2,0-2] unit-cell basis vectors 

s path length 

a(n1,n2,n3) tangle between atoms n1, n2 and n3, centered on n2 

dih(n1,n2,n3,n4) dihedral angle between n1, n2, n3, and n4 

T temperature (requires velocity) 

Movie 

Allows to play the current trajectory as a movie using a number of different settings. Default duration is 5 s. 

Expert mode 

Python interface to all ag functions, with numerous extra commands defined that help to modify and visualize a 

system. The commands come in two flavors, the first is interpreted on an atom-by-atom basis (e.g. operates on 



position, color, etc) and the second is based on the entire frame. The flavor of a given line is determined from the 

first command. Note that the frame-based commands can be used in atom-based operations, but not vice versa. 

See below for some examples. 

Regular python syntax applies to the commands and numpy has been imported as np. 

Two buttons allow to reduce the operation to a given frame: 

Only selected 

atoms (sa) 

Only current 

frame (cf) 

Restricts operation only to the selected atoms. The text command sa activates or 

deactivates this button. 

Restricts operation only to the current frame, useful for long trajectories. The text 

command cf activates or deactivates this button. 

List of atom-based commands with a few examples: 

Com- Interpretation 

mand 

x,y,z Cartesian coordinates. Example: x += A[0][0] 

r,g,b Color components, invoking the expert mode changes the color mode to manual and allows to 

address all colors individually. Example: r = 

(z-min(R[:,2]))/(max(R[:,2])-min(R[:,2])) 

rad atomic display radius 

s Boolean to control the selection of an atom. Example: s = Z == 6 and x > 5 or s = d 

== False 

f force on an atom 

Z atomic number 

m magnetic moment 

d dynamic, e.g. d = False fixes an atom 

List of frame-based and global commands and global objects with examples: 

Command Interpretation 

e total energy 

fmax maximal force 

A unit cell 

E total energy array of all frames. Example: e-min(E) 

F all forces in one frame 

M all magnetic moments 

R all atomic positions 

S boolean array of the entire selection 

D boolean array of dynamic atoms (False = atom is fixed) 

del S deletes current selection 

sa,cf toggles the selected-atoms-only or the current-frame-only buttons 

frame provides and edits the frame number in a trajectory 

center centers system in its unit cell 

cov array of original covalent radii 

self expert mode window 

gui ag GUI object, this controls the entire ag session 

img ag images object, all physical data is stored here 

To save data between commands, one has to assign variables to parent objects in the gui, e.g. via 

self.temp_var = R-img.P[0,:]. DISCLAIMER: Doing so might risk the functionality ofthe entire ag 

session if you accidentally overwrite basic functionality of the gui or the image objects stored within. 

Finally, recurring selections of commands collected as scripts can be executed as 

exec 

If the file in question is saved in the directory ~/.ase/ then just the filename will also do. 



Constraints 

Allows to set (or remove) constraints based on the currently selected atoms. 

Render scene 

Graphical interface to the ASE povray interface, ideally it requires that povray is installed on your computer to 

function, but it also can be used just to export the complete set of povray files. 

The texture of each atom is adjustable: The default texture is applied to all atoms, but then additional textures 

can be defined based on selections (Create new texture from current selection). These can be 

obtained either from selecting atoms by hand or by defining a selection with a boolean expression, for example 

Z==6 and x>5 and y5 and y

7.7.5 Setup 


The setup menus allow for the intuitive creation of numerous standard surfaces, nanoparticles, graphene and 

graphene nanoribbons, as well as nanotubes. 

Along with creating the geometry within ag, a button provides the necessary python code allowing one to recreate 

the exact same geometry in ASE scripts. 

7.7.6 Calculate 

Set calculator 

Allows ag to choose a calculator for internal computations (see below). Different density functional codes and 

force fields, as well as the EMT calculator are available. For the FHI-aims and VASP calculators, it is also possible 

to export an entire set of input files. 

Energy and forces 

Invokes the currently set calculator and provides energies and optional forces for all atoms. 

Energy minimization 

Runs an ASE relaxation using the currently selected calculator with a choice of relaxation algorithm and convergence 

criteria. Great for quickly (pre-)relaxing a molecule before placing it into a bigger system. 

Scale system 

Stub 

7.8 Command line tools 

The ase program can be used to do calculations with ASE supported calculators on the command line without 

having to write a Python script. The syntax is: 

$ ase [calculator] [task] [options] system(s) 

The name of the calculator must be lower case and will default to EMT. The task must be molecule or bulk. 

There are several ways to specify the system or systems to perform the calculations on: 

• Chemical names: H2O or Fe. Default molecule definitions are used. 

• Range of chemical symbols: Sc-Zn (3d-metals) 

• Special names: G2, G2_1 or S22 

• File names: benzene.xyz or slab.traj 

The exact meaning of these names will depend on the task. 

Simple examples: 

$ ase emt H2 --relax=0.01 

$ ase abinit bulk Si -a 5.5 -p ecut=150 -k 4,4,4 

7.8. Command line tools 79


7.8.1 Command line options 

General options: 

-h, --help Show help message and exit. 

-t TAG, --tag=TAG String tag added to filenames. 

-M , --magnetic-moment= Magnetic moment(s). Use “-M 1” or “-M 

2.3,-2.3”. 

-G, --gui Pop up ASE’s GUI. 

-s, --write-summary Write summary. 

--slice= Select subset of calculations using Python slice syntax. Use ”::2” to do 

every second calculation and ”:-5” to do the last five. 

-w FILENAME, --write-to-file=FILENAME Write configuration to file. 

-i, --interactive-python-session Run calculation inside interactive Python session. A possible 

$PYTHONSTARTUP script will be imported and the “atoms” variable refers 

to the Atoms object. 

-l, --use-lock-files Skip calculations where the json lock-file or result file already exists. 

-R FMAX, --relax=FMAX Relax internal coordinates using L-BFGS algorithm. 

-F , --fit= Find optimal bondlength and vibration frequency for dimer molecules or 

optimal volume and bulk modulus for bulk systems using N points and a 

variation from -x % to +x % for the bondlength or lattice constants. 

--constrain-tags= Constrain atoms with tags T1, T2, ... 

-k , --monkhorst-pack= Monkhorst-Pack sampling of BZ. Example: 

“4,4,4”: 4x4x4 k-points, “4,4,4g”: same set of k-points shifted to include the 

Gamma point. 

--k-point-density=K_POINT_DENSITY Density of k-points in Å. 

-p , --parameters= Comma-separated key=value pairs of calculator 

specific parameters. 

Options specific to the molecule task: 

-v VACUUM, --vacuum=VACUUM Amount of vacuum to add around isolated systems (in 

Angstrom). 

--unit-cell=CELL Unit cell. Examples: “10.0” or “9,10,11” (in Angstrom). 

--bond-length=BOND_LENGTH Bond length of dimer in Angstrom. 

--atomize Calculate Atomization energies. 

Options specific to the bulk task: 

-x CRYSTAL_STRUCTURE, --crystal-structure=CRYSTAL_STRUCTURE Crystal structure. 

-a LATTICE_CONSTANT, --lattice-constant=LATTICE_CONSTANT Lattice constant in Å. 

--c-over-a=C_OVER_A c/a ratio. 

-O, --orthorhombic Use orthorhombic unit cell. 

-C, --cubic Use cubic unit cell. 

-r REPEAT, --repeat=REPEAT Repeat unit cell. Use “-r 2” or “-r 2,3,1”. 


7.8.2 Molecules 

Example: 

$ ase abinit H2 -p ecut=200,xc=LDA -F 5,1 --atomize 


This will calculate the energy of a H2 molecule using Abinit with a planewave cutoff of 200 eV and the LDA 

XC-functional. A fit using 5 points and a variation of the bond length from -1 % to +1 % is made and in addition 

the energy of a single hydrogen atom is also calculated. 

Results are written to json files and can be analysed with: 

$ ase abinit H H2 -s 

name E E-E0 d0 hnu Ea Ea0 

eV eV Ang meV eV eV 

H2 -29.703 0.022 0.770 556.096 4.852 4.873 

H -12.426 

Note: The json files are simple text files that can be more or less’ed or pretty printed with python -m 

json.tool H2-molecule-abinit.jon. 

7.8.3 Bulk systems 

Example: 

$ ase bulk Ni Cu Pd Ag Pt Au -F 5,1 

Here we used the default EMT potential and the result is: 

$ ase bulk Ni Cu Pd Ag Pt Au -s 

name E E-E0 V0 B 

eV eV Ang^3 GPa 

Ni -0.009 0.005 10.600 175.978 

Ag 0.002 0.002 16.775 100.151 

Pt -0.000 0.000 15.080 278.087 

Au 0.003 0.003 16.684 173.868 

Pd 0.000 0.001 14.588 179.105 

Cu -0.006 0.001 11.565 134.439 

More examples 

Anti-ferromagnetic bcc iron: 

$ ase vasp bulk -x bcc Fe -C -M 2.3,-2.3 -p xc=PBE -k 8,8,8 

Bulk silicon (128 atoms, Gamma point only): 

$ ase abinit bulk Si -r 4,4,4 -k 1,1,1 -a 5.46 

Bulk aluminum in orthorhombic cell with LDA and fixed rmt: 

$ ase elk bulk --orthorhombic Al -k 4,4,4 -a 4.05 -p "swidth=0.1,rmt={’Al’: 1.9}" 

7.8.4 Batch jobs 

Suppose you want to run a large number of similar calculations like relaxing the structure of all the molecules in 

the G2-1 database. You could do that by submitting this job to your compute cluster: 

7.8. Command line tools 81


$ ase gpaw G2_1 -v 6.0 -p xc=vdW-DF,h=0.18 -R 0.02 

The molecule task will expand G2_1 to a lot of molecules, so it makes sense to use -l option 

(--use-lock-files) and submit the same job many times. A lock file will be created for each started calculation 

and calculations with existing lock file skipped. Moreover the calculations can be run in parallel (if parallel 

version of GPAW is installed): 

$ mpiexec gpaw-python ‘which ase‘ gpaw G2_1 -v 6.0 -p xc=vdW-DF,h=0.18 -R 0.02 -l 

7.8.5 Making your own tasks 

FCC clusters with 13 atoms 

Put this in m13.py: 

from math import sqrt 

from ase.cluster.cubic import FaceCenteredCubic 

from ase.tasks.molecule import MoleculeTask 

from ase.data import covalent_radii, atomic_numbers 

class M13Task(MoleculeTask): 

taskname = ’m13’ 

def build_system(self, name): 

if self.bond_length is None: 

b = 2 * covalent_radii[atomic_numbers[name]] 

else: 

b = self.bond_length 

task = M13Task() 

Then do this: 

return FaceCenteredCubic(name, [(1, 0, 0)], [1], 

latticeconstant=b * sqrt(2)) 

$ ase m13.py Pt -R 0.01 

The relaxed EMT bondlength of 2.62 Å can be extracted from the created trajectory like this: 

$ ag -tg "e,fmax,d(0,9)" Pt-m13-emt.traj 

10.9824302706 2.27575724833 2.72 

10.0805658256 1.45353946744 2.68 

9.61654400875 0.447140179352 2.64 

9.57510700742 0.0656434401881 2.6222281202 

9.57424531861 0.00239771758341 2.62450316817 

or like this: 

>>> from ase.io import read 

>>> pt = read(’Pt-m13-emt.traj’) 

>>> pt.get_distance(0, 9) 

2.6245031681662452 

Convergence test 

See convergence.py. 

7.8.6 To be done 

• Optimize c/a ratio. 



• Implement different way of cell sampling for eos: [a0 + s for s in [x * np.array(range(- N/2 + 1, N/2 + 

1))]] where x is sampling step length, N number of steps. Current way of sampling gives different length of 

sampling interval depending on the lattice constant guess a0. DONE 

• Write results to file (pickel, csv, cmr (db), traj, ...) per system, together with json file! 

• Split off EnergyTask from Task. 

• Set correct magnetic moments for atoms. DONE 

• Allow setting charges in ase.tasks.task 

• Check occupation numbers and requested total magnetic moments for molecules/atoms. DONE 

• Add –exclude option. 

• Relax cell. DONE 

• Optimize first then fit. DONE 

• Behavior of -w option? 

• Reaction task? 

• Rethink analysis and summary stuff: 

– it would be nice to calculate for example cohesive energies on the command line, i.e. using 

species belonging to different tasks 

– analysis should be more modular: one may want for example to calculate zpe energies for adsorption 

systems including molecules and surfaces and print the zpe correction for a given reaction. 

• ase.tasks.main - print complete architecture string in case of error (like in ase/test/__init__.py) 

7.9 Creating atomic structures 

See Also: 

• The lattice module 

• The spacegroup module 

• The surface module 

7.9.1 Common bulk crystals 

ase.structure.bulk(name, crystalstructure, a=None, c=None, covera=None, orthorhombic=False, 

cubic=False) 

Helper function for creating bulk systems. 

examples: 

name: str Chemical symbol or symbols as in ‘MgO’ or ‘NaCl’. 

crystalstructure: str Must be one of sc, fcc, bcc, hcp, diamond, zincblende or rocksalt. 

a: float Lattice constant. 

c: float Lattice constant. 

covera: float c/a raitio used for hcp. Defaults to ideal ratio. 

orthorhombic: bool Construct orthorhombic unit cell instead of primitive cell which is the default. 

cubic: bool Construct cubic unit cell. 

7.9. Creating atomic structures 83


>>> from ase.structure import bulk 

>>> a1 = bulk(’Cu’, ’fcc’, a=3.6) 

>>> a2 = bulk(’Cu’, ’fcc’, a=3.6, orthorhombic=True) 

>>> a3 = bulk(’Cu’, ’fcc’, a=3.6, cubic=True) 

>>> a1.cell 

array([[ 0. , 1.8, 1.8], 

[ 1.8, 0. , 1.8], 

[ 1.8, 1.8, 0. ]]) 

>>> a2.cell 

array([[ 2.54558441, 0. , 0. ], 

[ 0. , 2.54558441, 0. ], 

[ 0. , 0. , 3.6 ]]) 

>>> a3.cell 

array([[ 3.6, 0. , 0. ], 

[ 0. , 3.6, 0. ], 

[ 0. , 0. , 3.6]]) 

7.9.2 Nanotubes 

ase.structure.nanotube(n, m, length=1, bond=1.42, symbol=’C’, verbose=False) 

examples: 

>>> from ase.structure import nanotube 

>>> cnt1 = nanotube(6, 0, length=4) 

>>> cnt2 = nanotube(3, 3, length=6, bond=1.4, symbol=’Si’) 

7.9.3 Graphene nanoribbons 

ase.structure.graphene_nanoribbon(n, m, type=’zigzag’, saturated=False, C_H=1.09, 

C_C=1.42, vacuum=2.5, magnetic=None, initial_mag=1.12, 

sheet=False, main_element=’C’, 

saturate_element=’H’, vacc=None) 

Create a graphene nanoribbon. 

Creates a graphene nanoribbon in the x-z plane, with the nanoribbon running along the z axis. 

Parameters: 

n: int The width of the nanoribbon. 


examples: 

m: int The length of the nanoribbon. 

type: str The orientation of the ribbon. Must be either ‘zigzag’ or ‘armchair’. 

saturated: bool If true, hydrogen atoms are placed along the edge. 

C_H: float Carbon-hydrogen bond length. Default: 1.09 Angstrom. 

C_C: float Carbon-carbon bond length. Default: 1.42 Angstrom. 

vacuum: float Amount of vacuum added to both sides. Default 2.5 Angstrom. 

magnetic: bool Make the edges magnetic. 

initial_mag: float Magnitude of magnetic moment if magnetic=True. 

sheet: bool If true, make an infinite sheet instead of a ribbon. 

>>> from ase.structure import graphene_nanoribbon 

>>> gnr1 = graphene_nanoribbon(3, 4, type=’armchair’, saturated=True) 

>>> gnr2 = graphene_nanoribbon(2, 6, type=’zigzag’, saturated=True, 

>>> C_H=1.1, C_C=1.4, vacuum=6.0, 

>>> magnetic=True, initial_mag=1.12) 

7.9.4 Special points in the Brillouin zone 

You can find the psecial points in the Brillouin zone: 

>>> from ase.structure import bulk 

>>> from ase.dft.kpoints import ibz_points, get_bandpath 

>>> si = bulk(’Si’, ’diamond’, a=5.459) 

>>> points = ibz_points[’fcc’] 

>>> G = points[’Gamma’] 

>>> X = points[’X’] 

>>> W = points[’W’] 

>>> K = points[’K’] 

>>> L = points[’L’] 

>>> kpts, x, X = get_bandpath([W, L, G, X, W, K], si.cell) 

>>> print len(kpts), len(x), len(X) 

50 50 6 




7.9.5 Surfaces 

Common surfaces 

A number of utility functions are provided to set up the most common surfaces, to add vacuum layers, and to add 

adsorbates to a surface. In general, all surfaces can be set up with the modules described in the section General 

crystal structures and surfaces, but these utility functions make common tasks easier. 

Example 

To setup an Al(111) surface with a hydrogen atom adsorbed in an on-top position: 


slab = fcc111(’Al’, size=(2,2,3), vacuum=10.0) 

This will produce a slab 2x2x3 times the minimal possible size, with a (111) surface in the z direction. A 10 Å 

vacuum layer is added on each side. 

To set up the same surface with with a hydrogen atom adsorbed in an on-top position 1.5 Å above the top layer: 


slab = fcc111(’Al’, size=(2,2,3)) 

add_adsorbate(slab, ’H’, 1.5, ’ontop’) 

slab.center(vacuum=10.0, axis=2) 

Note that in this case is is probably not meaningful to use the vacuum keyword to fcc111, as we want to leave 10 

Å of vacuum after the adsorbate has been added. Instead, the center() method of the Atoms is used to add 

the vacuum and center the system. 

The atoms in the slab will have tags set to the layer number: First layer atoms will have tag=1, second layer atoms 

will have tag=2, and so on. Addsorbates get tag=0: 

>>> print atoms.get_tags() 

[3 3 3 3 2 2 2 2 1 1 1 1 0] 

This can be useful for setting up constraints (see Diffusion of gold atom on Al(100) surface (NEB)). 

Utility functions for setting up surfaces 

All the functions setting up surfaces take the same arguments. 

symbol: The chemical symbol of the element to use. 

size: A tuple giving the system size in units of the minimal unit cell. 

a: (optional) The lattice constant. If specified, it overrides the expermental lattice constant of the element. Must 

be specified if setting up a crystal structure different from the one found in nature. 

c: (optional) Extra HCP lattice constant. If specified, it overrides the expermental lattice constant of the element. 

Can be specified if setting up a crystal structure different from the one found in nature and an ideal c/a ratio 

is not wanted (c/a = (8/3) 1/3 ). 

vacuum: The thickness of the vacuum layer. The specified amount of vacuum appears on both sides of the slab. 

Default value is None, meaning not to add any vacuum. In that case a “vacuum” layer equal to the interlayer 

spacing will be present on the upper surface of the slab. Specify vacuum=0.0 to remove it. 

orthogonal: (optional, not supported by all functions). If specified and true, forces the creation of a unit cell with 

orthogonal basis vectors. If the default is such a unit cell, this argument is not supported. 

Each function defines a number of standard adsorbtion sites that can later be used when adding an adsorbate with 

lattice.surface.add_adsorbate(). 


The following functions are provided 

ase.lattice.surface.fcc100(symbol, size, a=None, vacuum=0.0) 

ase.lattice.surface.fcc110(symbol, size, a=None, vacuum=0.0) 

ase.lattice.surface.bcc100(symbol, size, a=None, vacuum=0.0) 

ase.lattice.surface.hcp10m10(symbol, size, a=None, c=None, vacuum=0.0) 

ase.lattice.surface.diamond100(symbol, size, a=None, vacuum=0.0) 

These allways give orthorhombic cells: 




fcc100 

fcc110 

bcc100 

hcp10m10 

diamond100 

ase.lattice.surface.fcc111(symbol, size, a=None, vacuum=0.0, orthogonal=False) 

ase.lattice.surface.bcc110(symbol, size, a=None, vacuum=0.0, orthogonal=False) 

ase.lattice.surface.bcc111(symbol, size, a=None, vacuum=0.0, orthogonal=False) 

ase.lattice.surface.hcp0001(symbol, size, a=None, c=None, vacuum=0.0, orthogonal=False) 



ase.lattice.surface.diamond111(symbol, size, a=None, vacuum=0.0, orthogonal=False) 

These can give both non-orthorhombic and orthorhombic cells: 

fcc111 

bcc110 

bcc111 

hcp0001 

diamond111 not implemented 

The adsorption sites are marked with: 



ontop hollow fcc hcp bridge shortbridge longbridge 

Adding new utility functions If you need other surfaces than the ones above, the easiest is to look in the source 

file surface.py, and adapt one of the existing functions. Please contribute any such function that you make either 

by cheking it into SVN or by mailing it to the developers. 

Adding adsorbates 

After a slab has been created, a vacuum layer can be added. It is also possible to add one or more adsorbates. 

ase.lattice.surface.add_adsorbate(slab, adsorbate, height, position=(0, 0), offset=None, 

mol_index=0) 

Add an adsorbate to a surface. 

This function adds an adsorbate to a slab. If the slab is produced by one of the utility functions in 

ase.lattice.surface, it is possible to specify the position of the adsorbate by a keyword (the supported keywords 

depend on which function was used to create the slab). 

If the adsorbate is a molecule, the atom indexed by the mol_index optional argument is positioned on top 

of the adsorption position on the surface, and it is the responsibility of the user to orient the adsorbate in a 

sensible way. 

This function can be called multiple times to add more than one adsorbate. 

Parameters: 

slab: The surface onto which the adsorbate should be added. 

adsorbate: The adsorbate. Must be one of the following three types: A string containing the chemical 

symbol for a single atom. An atom object. An atoms object (for a molecular adsorbate). 

height: Height above the surface. 

position: The x-y position of the adsorbate, either as a tuple of two numbers or as a keyword (if the surface 

is produced by one of the functions in ase.lattice.surfaces). 

offset (default: None): Offsets the adsorbate by a number of unit cells. Mostly useful when adding 

more than one adsorbate. 

mol_index (default: 0): If the adsorbate is a molecule, index of the atom to be positioned above the location 

specified by the position argument. 

Note position is given in absolute xy coordinates (or as a keyword), whereas offset is specified in unit cells. 

This can be used to give the positions in units of the unit cell by using offset instead. 

Create specific non-common surfaces 

New in version 3.5.2. In addition to the most normal surfaces, a function has been constructed to create more 

uncommon surfaces that one could be interested in. It is constructed upon the Miller Indices defining the surface 

and can be used for both fcc, bcc and hcp structures. The theory behind the implementation can be found here: 

general_surface.pdf. 

Example 

To setup a Au(211) surface with 9 layers and 10 Å of vacuum: 

from ase.lattice.surface import surface 

s1 = surface(’Au’, (2, 1, 1), 9) 

s1.center(vacuum=10, axis=2) 



This is the easy way, where you use the experimental lattice constant for gold bulk structure. You can write: 


view(s1) 

or simply s1.edit() if you want to see and rotate the structure. 

Next example is a molybdenum bcc(321) surface where we decide what lattice constant to use: 


Mobulk = bulk(’Mo’, ’bcc’, a=3.16, cubic=True) 

s2 = surface(Mobulk, (3, 2, 1), 9) 




As the last example, creation of alloy surfaces is also very easily carried out with this module. In this example, 

two Pt3Rh fcc(211) surfaces will be created: 

a = 4.0 


Pt3Rh = Atoms(’Pt3Rh’, 

scaled_positions=[(0, 0, 0), 

(0.5, 0.5, 0), 

(0.5, 0, 0.5), 

(0, 0.5, 0.5)], 

cell=[a, a, a], 

pbc=True) 

s3 = surface(Pt3Rh, (2, 1, 1), 9) 


Pt3Rh.set_chemical_symbols(’PtRhPt2’) 

s4 = surface(Pt3Rh , (2, 1, 1), 9) 



7.9.6 General crystal structures and surfaces 


Modules for creating crystal structures are found in the module lattice. Most Bravais lattices are implemented, 

as are a few important lattices with a basis. The modules can create lattices with any orientation (see below). These 

modules can be used to create surfaces with any crystal structure and any orientation by later adding a vacuum 

layer with lattice.surface.add_vacuum(). 

Example 

To set up a slab of FCC copper with the [1,-1,0] direction along the x-axis, [1,1,-2] along the y-axis and [1,1,1] 

along the z-axis, use: 




atoms = FaceCenteredCubic(directions=[[1,-1,0], [1,1,-2], [1,1,1]], 

size=(2,2,3), symbol=’Cu’, pbc=(1,1,0)) 

The minimal unit cell is repeated 2*2*3 times. The lattice constant is taken from the database of lattice constants 

in data module. There are periodic boundary conditions along the x and y axis, but free boundary conditions 

along the z axis. Since the three directions are perpendicular, a (111) surface is created. 

To set up a slab of BCC copper with [100] along the first axis, [010] along the second axis, and [111] along the 

third axis use: 

from ase.lattice.cubic import BodyCenteredCubic 

atoms = BodyCenteredCubic(directions=[[1,0,0], [0,1,0], [1,1,1]], 

size=(2,2,3), symbol=’Cu’, pbc=(1,1,0), 

latticeconstant=4.0) 

Since BCC is not the natural crystal structure for Cu, a lattice constant has to be specified. Note that since the 

repeat directions of the unit cell are not orthogonal, the Miller indices of the surfaces will not be the same as the 

Miller indices of the axes. The indices of the surfaces in this example will be (1,0,-1), (0,1,-1) and (0,0,1). 

Available crystal lattices 

The following modules are currently available (the * mark lattices with a basis): 

• lattice.cubic 

– SimpleCubic 

– FaceCenteredCubic 

– BodyCenteredCubic 

– Diamond (*) 

• lattice.tetragonal 

– SimpleTetragonal 

– CenteredTetragonal 

• lattice.orthorhombic 

– SimpleOrthorhombic 

– BaseCenteredOrthorhombic 

– FaceCenteredOrthorhombic 

– BodyCenteredOrthorhombic 

• lattice.monoclinic 

– SimpleMonoclinic 

– BaseCenteredMonoclinic 

• lattice.triclinic 

– Triclinic 

• lattice.hexagonal 

– Hexagonal 

– HexagonalClosedPacked (*) 

– Graphite (*) 


Usage 


• The rhombohedral (or trigonal) lattices are not implemented. They will be implemented when the need 

arises (and if somebody can tell me the precise definition of the 4-number Miller indices - I only know that 

they are “almost the same as in hexagonal lattices”). 

• lattice.compounds 

Lattices with more than one element. These are mainly intended as examples allowing you to define new 

such lattices. Currenly, the following are defined 

– B1 = NaCl = Rocksalt 

– B2 = CsCl 

– B3 = ZnS = Zincblende 

– L1_2 = AuCu3 

– L1_0 = AuCu 

The lattice objects are called with a number of arguments specifying e.g. the size and orientation of the lattice. 

All arguments should be given as named arguments. At a minimum the symbol argument must be specified. 

symbol The element, specified by the atomic number (an integer) or by the atomic symbol (i.e. ‘Au’). For 

compounds, a tuple or list of elements should be given. This argument is mandatory. 

directions and/or miller: Specifies the orientation of the lattice as the Miller indices of the three basis 

vectors of the supercell (directions=...) and/or as the Miller indices of the three surfaces 

(miller=...). Normally, one will specify either three directions or three surfaces, but any combination 

that is both complete and consistent is allowed, e.g. two directions and two surface miller indices (this 

example is slightly redundant, and consistency will be checked). If only some directions/miller indices are 

specified, the remaining should be given as None. If you intend to generate a specific surface, and prefer to 

specify the miller indices of the unit cell basis (directions=...), it is a good idea to give the desired 

Miller index of the surface as well to allow the module to test for consistency. Example: 

>>> atoms = BodyCenteredCubic(directions=[[1,-1,0],[1,1,-1],[0,0,1]], 

... miller=[None, None, [1,1,2]], ...) 

If neither directions nor miller are specified, the default is directions=[[1,0,0], 

[0,1,0], [0,0,1]]. 

size: A tuple of three numbers, defining how many times the fundamental repeat unit is repeated. Default: 

(1,1,1). Be aware that if high-index directions are specified, the fundamental repeat unit may be large. 

latticeconstant: The lattice constant. If no lattice constant is specified, one is extracted from 

ASE.ChemicalElements provided that the element actually has the crystal structure you are creating. Depending 

on the crystal structure, there will be more than one lattice constant, and they are specified by giving 

a dictionary or a tuple (a scalar for cubic lattices). Distances are given in Angstrom, angles in degrees. 

Structure Lattice constants Dictionary-keys 

Cubic a ‘a’ 

Tetragonal (a, c) ‘a’, ‘c’ or ‘c/a’ 

Orthorhombic (a, b, c) ‘a’, ‘b’ or ‘b/a’, ‘c’ or ‘c/a’ 

Triclinic (a, b, c, α, β, γ) ‘a’, ‘b’ or ‘b/a’, ‘c’ or ‘c/a’, ‘alpha’, ‘beta’, ‘gamma’ 

Monoclinic (a, b, c, alpha) ‘a’, ‘b’ or ‘b/a’, ‘c’ or ‘c/a’, ‘alpha’ 

Hexagonal (a, c) ‘a’, ‘c’ or ‘c/a’ 

Example: 

>>> atoms = Monoclinic( ... , latticeconstant={’a’: 3.06, 

... ’b/a’: 0.95, ’c/a’: 1.07, ’alpha’: 74}) 

debug: Controls the amount of information printed. 0: no info is printed. 1 (the default): The indices of surfaces 

and unit cell vectors are printed. 2: Debugging info is printed. 



Defining new lattices 

Often, there is a need for new lattices - either because an element crystallizes in a lattice that is not a simple 

Bravais lattice, or because you need to work with a compound or an ordered alloy. 

All the lattice generating objects are instances of a class, you generate new lattices by deriving a new class and 

instantiating it. This is best explained by an example. The diamond lattice is two interlacing FCC lattices, so it 

can be seen as a face-centered cubic lattice with a two-atom basis. The Diamond object could be defined like this: 

from ase.lattice.cubic import FaceCenteredCubicFactory 

class DiamondFactory(FaceCenteredCubicFactory): 

"""A factory for creating diamond lattices.""" 

xtal_name = ’diamond’ 

bravais_basis = [[0, 0, 0], [0.25, 0.25, 0.25]] 

Diamond = DiamondFactory() 

Lattices with more than one element 

Lattices with more than one element is made in the same way. A new attribute, element_basis, is added, 

giving which atoms in the basis are which element. If there are four atoms in the basis, and element_basis is 

(0,0,1,0), then the first, second and fourth atoms are one element, and the third is the other element. As an 

example, the AuCu3 structure (also known as L12) is defined as: 

# The L1_2 structure is "based on FCC", but is really simple cubic 

# with a basis. 

class AuCu3Factory(SimpleCubicFactory): 

"A factory for creating AuCu3 (L1_2) lattices." 

bravais_basis = [[0, 0, 0], [0, 0.5, 0.5], [0.5, 0, 0.5], [0.5, 0.5, 0]] 

element_basis = (0, 1, 1, 1) 

AuCu3 = L1_2 = AuCu3Factory() 

Sometimes, more than one crystal structure can be used to define the crystal structure, for example the Rocksalt 

structure is two interpenetrating FCC lattices, one with one kind of atoms and one with another. It would be 

tempting to define it as 

class NaClFactory(FaceCenteredCubicFactory): 

"A factory for creating NaCl (B1, Rocksalt) lattices." 

bravais_basis = [[0, 0, 0], [0.5, 0.5, 0.5]] 

element_basis = (0, 1) 

B1 = NaCl = Rocksalt = NaClFactory() 

but if this is used to define a finite system, one surface would be covered with one type of atoms, and the opposite 

surface with the other. To maintain the stochiometry of the surfaces, it is better to use the simple cubic lattice with 

a larger basis: 

# To prevent a layer of element one on one side, and a layer of 

# element two on the other side, NaCl is based on SimpleCubic instead 

# of on FaceCenteredCubic 

class NaClFactory(SimpleCubicFactory): 

"A factory for creating NaCl (B1, Rocksalt) lattices." 

bravais_basis = [[0, 0, 0], [0, 0, 0.5], [0, 0.5, 0], [0, 0.5, 0.5], 

[0.5, 0, 0], [0.5, 0, 0.5], [0.5, 0.5, 0], 

[0.5, 0.5, 0.5]] 

element_basis = (0, 1, 1, 0, 1, 0, 0, 1) 


B1 = NaCl = Rocksalt = NaClFactory() 

More examples can be found in the file ase/lattice/compounds.py. 

7.9.7 Molecules 

The G2-database of common molecules is available in the data.molecules module. 

ase.data.molecules.molecule(name, **kwargs) 

Deprecated. 

Example: 

>>> from ase.data.molecules import molecule 

>>> atoms = molecule(’H2O’) 


ASE contains a number of modules for setting up atomic structures, mainly molecules, bulk crystals and surfaces. 

Some of these modules have overlapping functionality, but strike a different balance between flexibility and easeof-use. 

Common bulk crystals 

The ase.structure.bulk() function can be used to create the most common bulk crystal structures. The 

function creates a single unit cell oriented such that the number of atoms in the cell is minimal. 

Read more: Common bulk crystals. 

Common surfaces 

The lattice.surface module contains a number of functions for creating the most common surfaces in a 

minimal unit cell, and for adding adsorbates to these surfaces. 

Read more: Surfaces. 

Nanotubes and nanoribbons 

The functions ase.structure.nanotube() and ase.structure.graphene_nanoribbon() can 

be used to create Carbon nanotubes and graphene sheets or nanoribbons. Per default, they create Carbon nanotubes 

and sheets, but other elements can be used. 

Read more: Nanotubes and Graphene nanoribbons. 

Generally oriented bulk crystals and surfaces 

The lattice module contains functions for creating most common crystal structures with arbitrary orientation. 

The user can specify the desired Miller index along the three axes of the simulation, and the smallest periodic 

structure fulfilling this specification is created. Thirteen of the 14 Bravais lattices are supported by the module, as 

are a few lattices with a basis, and lattices for some of the most common compounds/alloys. The modules makes 

it possible to define further lattices based on the supported Bravais lattices. 

Both bulk crystals and surfaces can be created. 

Read more: General crystal structures and surfaces. 

Molecules 

Some common molecules are available in the molecules module. 

Read more: Molecules. 

7.10 Structure optimization 

The optimization algorithms can be roughly divided into local optimization algorithms which find a nearby local 

minimum and global optimization algorithms that try to find the global minimum (a much harder task). 

7.10. Structure optimization 97


7.10.1 Local optimization 

The local optimization algorithms available in ASE are: BFGS, LBFGS, BFGSLineSearch, 

LBFGSLineSearch, MDMin, and FIRE. 

See Also: 

Performance test for all ASE local optimizers. 

MDMin and FIRE both use Newtonian dynamics with added friction, to converge to an energy minimum, whereas 

the others are of the quasi-Newton type, where the forces of consecutive steps are used to dynamically update a 

Hessian describing the curvature of the potential energy landscape. You can use the QuasiNewton synonym for 

BFGSLineSearch because this algorithm is in many cases the optimal of the quasi-Newton algorithms. 

All of the local optimizer classes have the following structure: 

class Optimizer: 

def __init__(self, atoms, restart=None, logfile=None): 

def run(self, fmax=0.05, steps=100000000): 

def get_number_of_steps(): 

The convergence criterion is that the force on all individual atoms should be less than fmax: 

BFGS 

max | 

a 

� Fa| < fmax 

The BFGS object is one of the minimizers in the ASE package. The below script uses BFGS to optimize the 

structure of a water molecule, starting with the experimental geometry: 





d = 0.9575 

t = np.pi / 180 * 104.51 

water = Atoms(’H2O’, 

positions=[(d, 0, 0), 

(d * np.cos(t), d * np.sin(t), 0), 

(0, 0, 0)], 

calculator=EMT()) 

dyn = BFGS(water) 


which produces the following output. The columns are the solver name, step number, clock time, potential energy 

(eV), and maximum force.: 

BFGS: 0 19:45:25 2.769633 8.6091 

BFGS: 1 19:45:25 2.154560 4.4644 

BFGS: 2 19:45:25 1.906812 1.3097 

BFGS: 3 19:45:25 1.880255 0.2056 

BFGS: 4 19:45:25 1.879488 0.0205 

When doing structure optimization, it is useful to write the trajectory to a file, so that the progress of the optimization 

run can be followed during or after the run: 

dyn = BFGS(water, trajectory=’H2O.traj’) 


Use the command ag H2O.traj to see what is going on (more here: gui). The trajectory file can also be 

accessed using the module ase.io.trajectory. 



The attach method takes an optional argument interval=n that can be used to tell the structure optimizer 

object to write the configuration to the trajectory file only every n steps. 

During a structure optimization, the BFGS and LBFGS optimizers use two quantities to decide where to move the 

atoms on each step: 

• the forces on each atom, as returned by the associated Calculator object 

∂ • the Hessian matrix, i.e. the matrix of second derivatives 2 E 

∂xi∂xj 

coordinates. 

of the total energy with respect to nuclear 

If the atoms are close to the minimum, such that the potential energy surface is locally quadratic, the Hessian 

and forces accurately determine the required step to reach the optimal structure. The Hessian is very expensive to 

calculate a priori, so instead the algorithm estimates it by means of an initial guess which is adjusted along the 

way depending on the information obtained on each step of the structure optimization. 

It is frequently practical to restart or continue a structure optimization with a geometry obtained from a previous 

relaxation. Aside from the geometry, the Hessian of the previous run can and should be retained for the second 

run. Use the restart keyword to specify a file in which to save the Hessian: 

dyn = BFGS(atoms=system, trajectory=’qn.traj’, restart=’qn.pckl’) 

This will create an optimizer which saves the Hessian to qn.pckl (using the Python pickle module) on each 

step. If the file already exists, the Hessian will also be initialized from that file. 

The trajectory file can also be used to restart a structure optimization, since it contains the history of all forces and 

positions, and thus whichever information about the Hessian was assembled so far: 

dyn = BFGS(atoms=system, trajectory=’qn.traj’) 

dyn.replay_trajectory(’history.traj’) 

This will read through each iteration stored in history.traj, performing adjustments to the Hessian as appropriate. 

Note that these steps will not be written to qn.traj. If restarting with more than one previous trajectory 

file, use ag to concatenate them into a single trajectory file first: 

$ ag part1.traj part2.traj -o history.traj 

The file history.traj will then contain all necessary information. 

When switching between different types of optimizers, e.g. between BFGS and LBFGS, the pickle-files specified 

by the restart keyword are not compatible, but the Hessian can still be retained by replaying the trajectory as 

above. 

LBFGS 

LBFGS is the limited memory version of the BFGS algorithm, where the inverse of Hessian matrix is updated 

instead of the Hessian itself. Two ways exist for determining the atomic step: Standard LBFGS and 

LBFGSLineSearch. For the first one, both the directions and lengths of the atomic steps are determined by the 

approximated Hessian matrix. While for the latter one, the approximated Hessian matrix is only used to find out 

the directions of the line searches and atomic steps, the step lengths are determined by the forces. 

To start a structure optimization with LBFGS algorithm is similar to BFGS. A typical optimization should look 

like: 

dyn = LBFGS(atoms=system, trajectory=’lbfgs.traj’, restart=’lbfgs.pckl’) 

where the trajectory and the restart save the trajectory of the optimization and the vectors needed to generate the 

Hessian Matrix. 

FIRE 

Read about this algorithm here: 

Erik Bitzek, Pekka Koskinen, Franz Gähler, Michael Moseler, and Peter Gumbsch 



MDMin 

Structural Relaxation Made Simple 

Physical Review Letters, Vol. 97, 170201 (2006) 

The MDmin algorithm is a modification of the usual velocity-Verlet molecular dynamics algorithm. Newtons 

second law is solved numerically, but after each time step the dot product between the forces and the momenta is 

checked. If it is zero, the system has just passed through a (local) minimum in the potential energy, the kinetic 

energy is large and about to decrease again. At this point, the momentum is set to zero. Unlike a “real” molecular 

dynamics, the masses of the atoms are not used, instead all masses are set to one. 

The MDmin algorithm exists in two flavors, one where each atom is tested and stopped individually, and one 

where all coordinates are treated as one long vector, and all momenta are set to zero if the dotproduct between the 

momentum vector and force vector (both of length 3N) is zero. This module implements the latter version. 

Although the algorithm is primitive, it performs very well because it takes advantage of the physics of the problem. 

Once the system is so near the minimum that the potential energy surface is approximately quadratic it becomes 

advantageous to switch to a minimization method with quadratic convergence, such as Conjugate Gradient or 

Quasi Newton. 

SciPy optimizers 

SciPy provides a number of optimizers. An interface module for a couple of these have been written for ASE. 

Most notable are the optimizers SciPyFminBFGS and SciPyFminCG. These are called with the regular syntax and 

can be imported as: 

from ase.optimize.sciopt import SciPyFminBFGS, SciPyFminCG 

class ase.optimize.sciopt.SciPyFminBFGS(atoms, logfile=’-‘, trajectory=None, callback_always=False, 

alpha=70.0) 

Quasi-Newton method (Broydon-Fletcher-Goldfarb-Shanno) 

Initialize object 

Parameters: 

callback_always: book Should the callback be run after each force call (also in the linesearch) 

alpha: float Initial guess for the Hessian (curvature of energy surface). A conservative value of 70.0 is the 

default, but number of needed steps to converge might be less if a lower value is used. However, a 

lower value also means risk of instability. 

class ase.optimize.sciopt.SciPyFminCG(atoms, logfile=’-‘, trajectory=None, callback_always=False, 

alpha=70.0) 

Non-linear (Polak-Ribiere) conjugate gradient algorithm 

See Also: 

Initialize object 

Parameters: 

callback_always: book Should the callback be run after each force call (also in the linesearch) 

alpha: float Initial guess for the Hessian (curvature of energy surface). A conservative value of 70.0 is the 

default, but number of needed steps to converge might be less if a lower value is used. However, a 

lower value also means risk of instability. 

SciPyFminBFGS, SciPyFminCG 


BFGSLineSearch 


BFGSLineSearch is the BFGS algorithm with an line search mechanism that enforces the step taken fulfills the 

Wolfe conditions, so that the energy and absolute value of the force decrease monotonically. Like the lbfgs 

algorithm the inverse of the Hessian Matrix is updated. 

The usage of BFGSLineSearch algorithm is similar to other BFGS type algorithms. A typical optimization should 

look like: 

from ase.optimize.bfgslinesearch import BFGSLineSearch 

dyn = BFGSLineSearch(atoms=system, trajectory=’bfgs_ls.traj’, restart=’bfgs_ls.pckl’) 

where the trajectory and the restart save the trajectory of the optimization and the information needed to generate 

the Hessian Matrix. 

Note: In many of the examples, tests, exercises and tutorials, QuasiNewton is used – it is a synonym for 

BFGSLineSearch. 

7.10.2 Global optimization 

There are currently two global optimisation algorithms available. 

Basin hopping 

The global optimization algorithm can be used quite similar as a local optimization algorithm: 


from ase.optimize.basin import BasinHopping 

bh = BasinHopping(atoms=system, # the system to optimize 

temperature=100 * kB, # ’temperature’ to overcome barriers 

dr=0.5, # maximal stepwidth 

optimizer=LBFGS, # optimizer to find local minima 

fmax=0.1, # maximal force for the optimizer 

) 

Read more about this algorithm here: 

and here: 

David J. Wales and Jonathan P. K. Doye 

Global Optimization by Basin-Hopping and the Lowest Energy Structures of Lennard-Jones Clusters 

Containing up to 110 Atoms 

J. Phys. Chem. A, Vol. 101, 5111-5116 (1997) 

David J. Wales and Harold A. Scheraga 

Global Optimization of Clusters, Crystals, and Biomolecules 

Science, Vol. 285, 1368 (1999) 

Minima hopping 

The minima hopping algorithm was developed and described by Goedecker: 

Stefan Goedecker 

Minima hopping: An efficient search method for the global minimum of the potential energy surface 

of complex molecular systems 

J. Chem. Phys., Vol. 120, 9911 (2004) 



This algorithm utilizes a series of alternating steps of NVE molecular dynamics and local optimizations, and has 

two parameters that the code dynamically adjusts in response to the progress of the search. The first parameter 

is the initial temperature of the NVE simulation. Whenever a step finds a new minimum this temperature is 

decreased; if the step finds a previously found minimum the temperature is increased. The second dynamically 

adjusted parameter is Ediff, which is an energy threshold for accepting a newly found minimum. If the new 

minimum is no more than Ediff eV higher than the previous minimum, it is acccepted and Ediff is decreased; if it 

is more than Ediff eV higher it is rejected and Ediff is increased. The method is used as: 

from ase.optimize.minimahopping import MinimaHopping 

opt = MinimaHopping(atoms=system) 

opt(totalsteps=10) 

This will run the algorithm until 10 steps are taken; alternatively, if totalsteps is not specified the algorithm will 

run indefinitely (or until stopped by a batch system). A number of optional arguments can be fed when initializing 

the algorithm as keyword pairs. The keywords and default values are: 

T0: 1000., # K, initial MD ‘temperature’ 

beta1: 1.1, # temperature adjustment parameter 

beta2: 1.1, # temperature adjustment parameter 

beta3: 1. / 1.1, # temperature adjustment parameter 

Ediff0: 0.5, # eV, initial energy acceptance threshold 

alpha1 : 0.98, # energy threshold adjustment parameter 

alpha2 : 1. / 0.98, # energy threshold adjustment parameter 

mdmin : 2, # criteria to stop MD simulation (no. of minima) 

logfile: ‘hop.log’, # text log 

minima_threshold : 0.5, # A, threshold for identical configs 

timestep : 1.0, # fs, timestep for MD simulations 

optimizer : QuasiNewton, # local optimizer to use 

minima_traj : ‘minima.traj’, # storage file for minima list 

Specific definitions of the alpha, beta, and mdmin parameters can be found in the publication by Goedecker. 

minima_threshold is used to determine if two atomic configurations are identical; if any atom has moved by 

more than this amount it is considered a new configuration. Note that the code tries to do this in an intelligent 

manner: atoms are considered to be indistinguishable, and translations are allowed in the directions of the periodic 

boundary conditions. Therefore, if a CO is adsorbed in an ontop site on a (211) surface it will be considered 

identical no matter which ontop site it occupies. 

The trajectory file minima_traj will be populated with the accepted minima as they are found. A log of the 

progress is kept in logfile. 

The code is written such that a stopped simulation (e.g., killed by the batching system when the maximum wall 

time was exceeded) can usually be restarted without too much effort by the user. In most cases, the script can be 

resubmitted without any modification – if the logfile and minima_traj are found, the script will attempt 

to use these to resume. (Note that you may need to clean up files left in the directory by the calculator, however, 

such as the .nc file produced by Jacapo.) 

Note that these searches can be quite slow, so it can pay to have multiple searches running at a time. Multiple 

searches can run in parallel and share one list of minima. (Run each script from a separate directory but specify 

the location to the same absolute location for minima_traj). Each search will use the global information of the 

list of minima, but will keep its own local information of the initial temperature and Ediff. 

7.11 Parallel calculations 

ase.parallel.paropen(name, mode=’r’, buffering=0) 

MPI-safe version of open function. 

In read mode, the file is opened on all nodes. In write and append mode, the file is opened on the master 

only, and /dev/null is opened on all other nodes. 


ase.parallel.parprint(*args, **kwargs) 

MPI-safe print - prints only from master. 

Tries to adopt python 3 behaviour. 

7.12 Visualization 

visualize.view(atoms, data=None, viewer=None, repeat=None) 


This provides an interface to various visualization tools, such as ase.gui, ase.visualize.vtk, RasMol, 

VMD, VTK, gOpenMol, or Avogadro. The default viewer is the ase.gui, described in the gui module. The 

simplest invocation is: 

>>> from ase import view 


where atoms is any Atoms object. Alternative viewers can be used by specifying the optional keyword 

viewer=... - use one of ‘ase.gui’, ‘gopenmol’, ‘vmd’, or ‘rasmol’. The VMD and Avogadro viewers can 

take an optional data argument to show 3D data, such as charge density: 

>>> view(atoms, viewer=’VMD’, data=array) 

If you do not wish to open an interactive gui, but rather visualize your structure by dumping directly to a graphics 

file; you can use the write command of the io module, which can write ‘eps’, ‘png’, and ‘pov’ files directly, 

like this: 

>>> write(’image.png’, atoms) 

7.12.1 VTK 

The Visualization Toolkit (VTK) is a powerful platform-independent graphics engine, which comes as an open 

source graphics toolkit licensed under the BSD license. It is available for a wide range of programming languages, 

including easily scriptable interfaces in Python and Tcl. 

In the scientific community, VTK is used by thousands of researchers and developers for 3D computer graphics, 

image processing, and visualization. VTK includes a suite of 3D interaction widgets within the development 

framework for information visualization, integrating GUI toolkits such as Qt and Tk into a highly flexible design 

platform. 

For visualization purposes within ASE, two different VTK-approaches are supported, namely: 

Scripted on-the-fly rendering ASE includes VTK-scripting for easy data visualization using the 

vtk module. Development is in progress, so you might want to check out the latest development 

release from SVN (see Latest development release). 

Interactive rendering MayaVi is an easy-to-use GUI for VTK. With Enthought’s traits-based VTKwrapper 

(TVTK), constructing VTK pipelines has been simplified greatly by introducing three 

basic concepts: data sources, filters and visualization modules. MayaVi also supports the VTK 

file formats, including the flexible VTK XML, which in ASE can be used to export atomic 

positions, forces and volume data using the write command in the io module. 

A key feature of VTK is the inherent ability to use MPI for parallel rending, which is provided with built-in 

parallel composite rendering objects to handle domain decomposition and subsequent recombination of the raster 

information. This is particularly useful for non-interactive ray tracing, batch isosurface generation and in-situ 

visualization of simulation data in cluster computing. 

See Also: 

ParaView is a VTK-based open-source, multi-platform data analysis and visualization application for extremely 

large data-sets using distributed memory computing resources and parallel rendering through MPI. 

7.12. Visualization 103


7.12.2 PrimiPlotter 

The PrimiPlotter is intended to do on-the-fly plotting of the positions of the atoms during long molecular dynamics 

simulations. The module ase.visualize.primiplotter contains the PrimiPlotter and the various output 

modules, see below. 

class ase.visualize.primiplotter.PrimiPlotter(atoms, verbose=0, timing=0, interval=1, 

initframe=0) 

Primitive PostScript-based plots during a simulation. 

The PrimiPlotter plots atoms during simulations, extracting the relevant information from the list of atoms. 

It is created using the list of atoms as an argument to the constructor. Then one or more output devices must 

be attached using set_output(device). The list of supported output devices is at the end. 

The atoms are plotted as circles. The system is first rotated using the angles specified by set_rotation([vx, 

vy, vz]). The rotation is vx degrees around the x axis (positive from the y toward the z axis), then vy degrees 

around the y axis (from x toward z), then vz degrees around the z axis (from x toward y). The rotation 

matrix is the same as the one used by RasMol. 

Per default, the system is scaled so it fits within the canvas (autoscale mode). Autoscale mode is enabled and 

disables using autoscale(“on”) or autoscale(“off”). A manual scale factor can be set with set_scale(scale), 

this implies autoscale(“off”). The scale factor (from the last autoscale event or from set_scale) can be 

obtained with get_scale(). Finally, an explicit autoscaling can be triggered with autoscale(“now”), this is 

mainly useful before calling get_scale or before disabling further autoscaling. Finally, a relative scaling 

factor can be set with SetRelativeScaling(), it is multiplied to the usual scale factor (from autoscale or from 

set_scale). This is probably only useful in connection with autoscaling. 

The radii of the atoms are obtained from the first of the following methods which work: 

1.If the radii are specified using PrimiPlotter.set_radii(r), they are used. Must be an array, or a single 

number. 

2.If the atoms has a get_atomic_radii() method, it is used. This is unlikely. 

3.If the atoms has a get_atomic_numbers() method, the corresponding covalent radii are extracted from 

the ASE.ChemicalElements module. 

4.If all else fails, the radius is set to 1.0 Angstrom. 

The atoms are colored using the first of the following methods which work. 

1.If colors are explicitly set using PrimiPlotter.set_colors(), they are used. 

2.If these colors are specified as a dictionary, the tags (from atoms.get_tags()) are used as an index into 

the dictionary to get the actual colors of the atoms. 

3.If a color function has been set using PrimiPlotter.set_color_function(), it is called with the atoms as 

an argument, and is expected to return an array of colors. 

4.If the atoms have a get_colors() method, it is used to get the colors. 

5.If these colors are specified as a dictionary, the tags (from atoms.get_tags()) are used as an index into 

the dictionary to get the actual colors of the atoms. 

6.If all else fails, the atoms will be white. 

The colors are specified as an array of colors, one color per atom. Each color is either a real number from 

0.0 to 1.0, specifying a grayscale (0.0 = black, 1.0 = white), or an array of three numbers from 0.0 to 1.0, 

specifying RGB values. The colors of all atoms are thus a Numerical Python N-vector or a 3xN matrix. 

In cases 1a and 3a above, the keys of the dictionary are integers, and the values are either numbers 

(grayscales) or 3-vectors (RGB values), or strings with X11 color names, which are then translated to RGB 

values. Only in case 1a and 3a are strings recognized as colors. 

Some atoms may be invisible, and thus left out of the plot. Invisible atoms are determined from the following 

algorithm. Unlike the radius or the coloring, all points below are tried and if an atom is invisible by any 

criterion, it is left out of the plot. 


1.All atoms are visible. 


2.If PrimiPlotter.set_invisible() has be used to specify invisible atoms, any atoms for which the value is 

non-zero becomes invisible. 

3.If an invisiblility function has been set with PrimiPlotter.set_invisibility_function(), it is called with 

the atoms as argument. It is expected to return an integer per atom, any non-zero value makes that 

atom invisible. 

4.If a cut has been specified using set_cut, any atom outside the cut is made invisible. 

Note that invisible atoms are still included in the algorithm for positioning and scaling the plot. 

The following output devices are implemented. 

PostScriptFile(prefix): Create PS files names prefix0000.ps etc. 

PnmFile(prefix): Similar, but makes PNM files. 

GifFile(prefix): Similar, but makes GIF files. 

JpegFile(prefix): Similar, but makes JPEG files. 

X11Window(): Show the plot in an X11 window using ghostscript. 

Output devices writing to files take an extra optional argument to the constructor, compress, specifying if 

the output file should be gzipped. This is not allowed for some (already compressed) file formats. 

Instead of a filename prefix, a filename containing a % can be used. In that case the filename is expected to 

expand to a real filename when used with the Python string formatting operator (%) with the frame number 

as argument. Avoid generating spaces in the file names: use e.g. %03d instead of %3d. 

Parameters to the constructor: 

atoms: The atoms to be plottet. 

verbose = 0: Write progress information to stderr. 

timing = 0: Collect timing information. 

interval = 1: If specified, a plot is only made every interval’th time update() is called. Deprecated, normally 

you should use the interval argument when attaching the plotter to e.g. the dynamics. 

initframe = 0: Initial frame number, i.e. the number of the first plot. 

log(message) 

logs a message to the file set by set_log. 

plot() 

Create a plot now. Does not respect the interval timer. 

This method makes a plot unconditionally. It does not look at the interval variable, nor is this plot 

taken into account in the counting done by the update() method if an interval variable was specified. 

set_color_function(colors) 

Set a color function, to be used to color the atoms. 

set_colors(colors) 

Explicitly set the colors of the atoms. 

set_dimensions(dims) 

Set the size of the canvas (a 2-tuple). 

set_invisibility_function(invfunc) 

Set an invisibility function. 

set_invisible(inv) 

Choose invisible atoms. 

set_log(log) 

Sets a file for logging. 

7.12. Visualization 105


log may be an open file or a filename. 

set_radii(radii) 

Set the atomic radii. Give an array or a single number. 

set_rotation(rotation) 

Set the rotation angles (in degrees). 

update(newatoms=None) 

Cause a plot (respecting the interval setting). 

update causes a plot to be made. If the interval variable was specified when the plotter was create, it 

will only produce a plot with that interval. update takes an optional argument, newatoms, which can 

be used to replace the list of atoms with a new one. 

7.12.3 FieldPlotter 

The FieldPlotter is intended to plot fields defined on the atoms in large-scale simulations. The fields could be e.g. 

pressure, stress or temperature (kinetic energy), i.e. any quantity that in a given simulation is best defined on a 

per-atom basis, but is best interpreted as a continuum field. 

The current version of FieldPlotter only works if the number of atoms is at least 5-10 times larger than the number 

of pixels in the plot. 

class ase.visualize.fieldplotter.FieldPlotter(atoms, datasource=None, verbose=0, 

timing=0, interval=1, initframe=0) 

log(message) 

logs a message to the file set by set_log. 

plot(data=None) 

Create a plot now. Does not respect the interval timer. 

This method makes a plot unconditionally. It does not look at the interval variable, nor is this plot 

taken into account in the counting done by the update() method if an interval variable was specified. 

If data is specified, it must be an array of numbers with the same length as the atoms. That data will 

then be plotted. If no data is given, the data source specified when creating the plotter is used. 

set_background(value) 

Set the data value of the background. See also set_background_color 

Set the value of the background (parts of the plot without atoms) to a specific value, or to ‘min’ or 

‘max’ representing the minimal or maximal data values on the atoms. 

Calling set_background cancels previous calls to set_background_color. 

set_background_color(color) 

Set the background color. See also set_background. 

Set the background color. Use a single value in the range [0, 1[ for gray values, or a tuple of three such 

values as an RGB color. 

Calling set_background_color cancels previous calls to set_background. 

set_black_white_colors(reverse=False) 

Set the color to Black-White (greyscale) 

set_color_function(colors) 

Set a color function, to be used to color the atoms. 

set_data_range(range1, range2=None) 

Set the range of the data used when coloring. 

This function sets the range of data values mapped unto colors in the final plot. 

Three possibilities: 



‘data’: Autoscale using the data on visible atoms. The range goes from the lowest to the highest 

value present on the atoms. If only a few atoms have extreme values, the entire color range may 

not be used on the plot, as many values may be averaged on each point in the plot. 

‘plot’: Autoscale using the data on the plot. Unlike ‘data’ this guarantees that the entire color 

range is used. 

min, max: Use the range [min, max] 

set_dimensions(dims) 

Set the size of the canvas (a 2-tuple). 

set_invisibility_function(invfunc) 

Set an invisibility function. 

set_invisible(inv) 

Choose invisible atoms. 

set_log(log) 

Sets a file for logging. 

log may be an open file or a filename. 

set_plot_plane(plane) 

Set the plotting plane to xy, xz or yz (default: xy) 

set_radii(radii) 

Set the atomic radii. Give an array or a single number. 

set_red_yellow_colors(reverse=False) 

Set colors to Black-Red-Yellow-White (a.k.a. STM colors) 

set_rotation(rotation) 

Set the rotation angles (in degrees). 

update(newatoms=None) 

Cause a plot (respecting the interval setting). 

update causes a plot to be made. If the interval variable was specified when the plotter was create, it 

will only produce a plot with that interval. update takes an optional argument, newatoms, which can 

be used to replace the list of atoms with a new one. 

7.13 ASE-VTK 

For ASE, the vtk interface consists of Python modules for automatic visualization of positions, bonds, forces and 

volume data (e.g. wave functions) from an Atoms object, provided such data is made available by the calculator. 

Note: The Python modules in ASE are intended to wrap lower-level functionality of the VTK object models 

in small and easy-to-comprehend classes. To be able to distinguish between build-in VTK objects and their 

wrappers, and because VTK uses the CamelCase naming convention whereas ASE uses lower-case cf. our coding 

conventions, all variables referring to VTK built-in types are prefixed by vtk_. However, both VTK and wrapper 

classes are named according to the standard vtkFooBar. 

7.13.1 Representing atoms 

class ase.visualize.vtk.atoms.vtkAtoms(atoms, scale=1) 

Bases: ase.visualize.vtk.module.vtkModuleAnchor, ase.visualize.vtk.grid.vtkAtomicPositi 

Provides fundamental representation for Atoms-specific data in VTK. 

7.13. ASE-VTK 107


The vtkAtoms class plots atoms during simulations, extracting the relevant information from the list of 

atoms. It is created using the list of atoms as an argument to the constructor. Then one or more visualization 

modules can be attached using add_module(name, module). 

Example: 

>>> va = vtkAtoms(atoms) 

>>> va.add_forces() 

>>> va.add_axes() 

>>> XXX va.add_to_renderer(vtk_ren) 

Construct a fundamental VTK-representation of atoms. 

atoms: Atoms object or list of Atoms objects The atoms to be plotted. 

scale = 1: float or int Relative scaling of all Atoms-specific visualization. 

add_axes() 

Add an orientation indicator for the cartesian axes. An appropriate vtkAxesModule is added to the 

module anchor under axes. 

add_cell() 

Add a box outline of the cell using atoms.get_cell(). The existing vtkUnitCellModule is added 

to the module anchor under cell. 

add_forces() 

Add force vectors for the atoms using atoms.get_forces(). A vtkGlyphModule is added to the 

module anchor under force. 

add_velocities() 

Add velocity vectors for the atoms using atoms.get_velocities(). A vtkGlyphModule is added to 

the module anchor under velocity. 

Atom-centered data 

The superclass vtkAtomicPositions implements the basic concepts for representing atomic-centered data 

in VTK. 

class ase.visualize.vtk.grid.vtkAtomicPositions(pos, cell) 

Provides an interface for adding Atoms-centered data to VTK modules. Atomic positions, e.g. obtained 

using atoms.get_positions(), constitute an unstructured grid in VTK, to which scalar and vector can be added 

as point data sets. 

Just like Atoms, instances of vtkAtomicPositions can be divided into subsets, which makes it easy 

to select atoms and add properties. 

Example: 

>>> cell = vtkUnitCellModule(atoms) 

>>> apos = vtkAtomicPositions(atoms.get_positions(), cell) 

>>> apos.add_scalar_property(atoms.get_charges(), ’charges’) 

>>> apos.add_vector_property(atoms.get_forces(), ’forces’) 

Construct basic VTK-representation of a set of atomic positions. 

pos: NumPy array of dtype float and shape (n,3) Cartesian positions of the atoms. 

cell: Instance of vtkUnitCellModule of subclass thereof Holds information equivalent to that of 

atoms.get_cell(). 

add_scalar_property(data, name=None, active=True) 

Add VTK-representation of scalar data at the atomic positions. 

data: NumPy array of dtype float and shape (n,) Scalar values corresponding to the atomic positions. 

name=None: str Unique identifier for the scalar data. 


active=True: bool Flag indicating whether to use as active scalar data. 

add_vector_property(data, name=None, active=True) 

Add VTK-representation of vector data at the atomic positions. 


data: NumPy array of dtype float and shape (n,3) Vector components corresponding to the 

atomic positions. 

name=None: str Unique identifier for the vector data. 

active=True: bool Flag indicating whether to use as active vector data. 

get_points(subset=None) 

Return (subset of) vtkPoints containing atomic positions. 

subset=None: list of int A list of indices into the atomic positions; ignored if None. 

get_unstructured_grid(subset=None) 

Return (subset of) an unstructured grid of the atomic positions. 

Predefined shapes 

subset=None: list of int A list of indices into the atomic positions; ignored if None. 

The class vtkGlyphModule implements the lower-level objects for representing predefined shapes (glyphs) in 

VTK. 

class ase.visualize.vtk.module.vtkGlyphModule(vtk_pointset, glyph_source, scalemode=None, 

colormode=None) 

Modules represent a unified collection of VTK objects needed for introducing basic visualization concepts 

such as surfaces or shapes. 

A common trait of all modules is the need for an actor representation and corresponding generic properties 

such as lighting, color and transparency. 

Poly data modules are based on polygonal data sets, which can be mapped into graphics primitives suitable 

for rendering within the VTK framework. 

Glyph modules construct these polygonal data sets by replicating a glyph source across a specific set of 

points, using available scalar or vector point data to scale and orientate the glyph source if desired. 

Example: 

>>> atoms = molecule(’C60’) 

>>> cell = vtkUnitCellModule(atoms) 

>>> apos = vtkAtomicPositions(atoms.get_positions(), cell) 

>>> vtk_ugd = apos.get_unstructured_grid() 

>>> glyph_source = vtkAtomSource(’C’) 

>>> glyph_module = vtkGlyphModule(vtk_ugd, glyph_source) 

Construct VTK-representation of a module containing glyphs. These glyphs share a common source, defining 

their geometrical shape, which is cloned and oriented according to the input data. 

vtk_pointset: Instance of vtkPointSet or subclass thereof A vtkPointSet defines a set of positions, 

which may then be assigned specific scalar of vector data across the entire set. 

glyph_source: Instance of ~vtk.vtkCustomGlyphSource or subclass thereof Provides the basic shape 

to distribute over the point set. 

get_actor() 

Return the actor representing this module in a rendering scene. 

set_actor(vtk_act) 

Set the actor representing this module in a rendering scene. 

set_property(vtk_property) 

Set the property of the actor representing this module. 

7.13. ASE-VTK 109


7.14 Calculators 

For ASE, a calculator is a black box that can take atomic numbers and atomic positions from an Atoms object 

and calculate the energy and forces and sometimes also stresses. 

In order to calculate forces and energies, you need to attach a calculator object to your atoms object: 

>>> a = read(’molecule.xyz’) 

>>> e = a.get_potential_energy() 

Traceback (most recent call last): 

File "", line 1, in 

File "/home/jjmo/ase/ase/atoms.py", line 399, in get_potential_energy 

raise RuntimeError(’Atoms object has no calculator.’) 

RuntimeError: Atoms object has no calculator. 

>>> from ase.calculators import Abinit 

>>> calc = Abinit(...) 

>>> a.set_calculator(calc) 

>>> e = a.get_potential_energy() 

>>> print e 

-42.0 

Here, we used the set_calculator() method to attach an instance of the Abinit class and then we asked 

for the energy. 

Alternatively, a calculator can be attached like this: 

atoms = Atoms(..., calculator=Siesta()) 

7.14.1 Supported calculators 

Code Description Type 

GPAW Grid-based real-space PAW code DFT, HF 

Asap Highly efficient EMT code (written in C++) EMT 

jacapo ASE interface to Dacapo, a planewave ultra-soft pseudopotential code DFT 

Dacapo Old interface to Dacapo. Requires Numeric python and ASE2. DFT 

emt Effective Medium Theory calculator EMT 

abinit A planewave pseudopotential code DFT 

siesta LCAO pseudopotential code DFT 

dftb DftbPlus DFT based tight binding DFT 

turbomole Fast atom orbital code Turbomole, DFT, HF 

castep Planewave pseodopotential code DFT, HF 

vasp Planewave PAW code DFT 

FHI-aims Numeric Atomic Orbital, full potential code DFT, HF 

exciting Full Potential LAPW code DFT, LAPW 

fleur Full Potential LAPW code DFT, LAPW 

lammps Classical molecular dynamics code 

gromacs Classical molecular dynamics code 

mmtk XXX Library for molecular simulations 

The calculators can be divided in three groups: 

1. GPAW, Asap, Dacapo have their own native ASE interfaces. 

2. Jacapo, ABINIT, SIESTA, DftbPlus, TURBOMOLE, VASP, FLEUR, FHI-aims, LAMMPS, MMTK and 

Gromacs have Python wrappers in the ASE package, but the actual codes are not part of ASE. 

3. EMT is a pure python implementation of the Effective Medium Theory potential and it is included in the 

ASE package. 


7.14.2 Documentation for group 2 and 3 calculators 

Pure Python EMT calculator 


The EMT potential is included in the ASE package in order to have a simple calculator that can be used for quick 

demonstrations and tests. 

Warning: If you want to do a real application using EMT, you should used the much more efficient implementation 

in the ASAP calculator. 

class emt.EMT 

Right now, the only supported elements are: H, C, N, O, Al, Ni, Cu, Pd, Ag, Pt and Au. The EMT parameters for 

the metals are quite realistic for many purposes, whereas the H, C, N and O parameters are just for fun! 

Jacapo - ASE python interface for Dacapo 

Introduction 

Jacapo is an ASE interface for Dacapo and fully compatible with ASE. It replaces the old Dacapo interface using 

Numeric python and ASE2. The code was originally developed by John Kitchin and detailed documentation as 

well as many examples are available online: 

http://gilgamesh.cheme.cmu.edu/doc/software/jacapo/index.html 

Jacapo is included as an optional calculator in ASE and small differences to the above documentation may occur. 

Jacapo Calculator 

The Jacapo calculator is automatically installed with ase and can be imported using: 

from ase.calculators.jacapo import * 

class jacapo.Jacapo 

Here is a list of available keywords to initialize the calculator: 

keyword type description 

nc str Output NetCDF file, or input file if nc already exists. 

outnc str Output file. By default equal to nc. 

atoms object ase atoms object 

pw float Planewave cutoff in eV 

dw float Density cutoff in eV 

xc str Exchange-correlation functional. One of 

[’PZ’,’VWN’,’PW91’,’PBE’,’RPBE’,’revPBE’] 

nbands int Number of bands 

ft float Fermi temperature 

kpts list K-point grid, e.g. kpts = (2,2,1) 

spinpol boolean Turn on/off spin-polarization 

fixmagmom str Magnetic moment of the unit cell 

symmetry boolean Turn on/off symmetry reduction 

stress boolean Turn on/off stress calculation 

dipole boolean Turn on/off dipole correction 

stay_alive boolean Turn on/off stay alive 

debug int Set debug level (0=off, 10=extreme) 

deletenc boolean If the nc file exists, delete it (to ensure a fresh run). Default is False. 

7.14. Calculators 111


Example 

Here is an example of how to calculate the total energy of a CO molecule: 



from ase.calculators.jacapo import * 

CO = data.molecules.molecule(’CO’) 

CO.set_cell([6,6,6]) 

CO.center() 

calc = Jacapo(nc=’CO.nc’, 

atoms=CO, 

pw=300, 

nbands=8) 

print CO.get_potential_energy() 

Restarting from an old Calculation 

With Jacapo it is very easy to restart an old calculation. All necessary information (including the constraints) is 

stored in the out.nc file. To continue for example a geometry optimization do something like this: 

calc = Jacapo(’old.nc’,stay_alive=True) 

atoms = calc.get_atoms() 

dyn = QuasiNewton(atoms,logfile=’qn.log’) 


Note, that the stay_alive flag is not stored in the .nc file and must be set when the calculator instance is created. 

ABINIT 

Introduction 

ABINIT is a density-functional theory code based on pseudopotentials and a planewave basis. 

Environment variables 

Note: setting environment variables is necessary only if you configure your ABINIT/ASE environment from 

scratch. 

You need to write a script called abinit.py containing something like this: 

import os 

abinit = ’/usr/bin/abinis’ # full path to the abinit executable 

exitcode = os.system(’%s < %s.files > %s.log’ % (abinit, label, label)) 

The environment variable ABINIT_SCRIPT must point to that file. 

A directory containing the pseudopotential files (at least of .fhi type) is also needed, and it is to be put in the 

environment variable ABINIT_PP_PATH. Abinit does not provide tarballs of pseduopotentials so the easiest way 

is to download and unpack http://wiki.fysik.dtu.dk/abinit-files/abinit-pseudopotentials-2.tar.gz 

Set the environment variables in your in your shell configuration file: 

$ export ABINIT_SCRIPT=$HOME/bin/abinit.py 

$ export ABINIT_PP_PATH=${HOME}/abinit-pseudopotentials-2/LDA_FHI 

$ export ABINIT_PP_PATH=${HOME}/abinit-pseudopotentials-2/GGA_FHI:$ABINIT_PP_PATH 

$ export ABINIT_PP_PATH=${HOME}/abinit-pseudopotentials-2/LDA_HGH:$ABINIT_PP_PATH 



$ export ABINIT_PP_PATH=${HOME}/abinit-pseudopotentials-2/LDA_PAW:$ABINIT_PP_PATH 

$ export ABINIT_PP_PATH=${HOME}/abinit-pseudopotentials-2/LDA_TM:$ABINIT_PP_PATH 

$ export ABINIT_PP_PATH=${HOME}/abinit-pseudopotentials-2/GGA_FHI:$ABINIT_PP_PATH 

$ export ABINIT_PP_PATH=${HOME}/abinit-pseudopotentials-2/GGA_HGHK:$ABINIT_PP_PATH 

$ export ABINIT_PP_PATH=${HOME}/abinit-pseudopotentials-2/GGA_PAW:$ABINIT_PP_PATH 

$ export ABINIT_PP_PATH=$HOME/mypps:$ABINIT_PP_PATH 

ABINIT Calculator 

The default parameters are very close to those that the ABINIT Fortran code uses. These are the exceptions: 

class abinit.Abinit(label=’abinit’, xc=’LDA’, mix=0.1) 

Here is a detailed list of all the keywords for the calculator: 

keyword type default value description 

kpts list [1,1,1] Monkhorst-Pack k-point sampling 

nbands int None Number of band. May be omitted. 

nstep int None Number of self-consistent field STEPS. 

ecut float None Planewave cutoff energy in eV (default: None) 

xc str ’LDA’ Exchange-correlation functional. 

npulayit int 7 Number of old densities to use for Pulay mixing 

diemix float 0.1 Pulay mixing weight 

diemac float 1e6 Model DIElectric MACroscopic constant 

width float 0.04 Ha Fermi-distribution width in eV (default: 0.04 Ha) 

charge float 0 Total charge of the system (default: 0) 

label str ’abinit’ Name of the output file 

pps str ’fhi’ Pseudopotentials used ‘fhi’, ‘hgh’, ‘hgh.sc’, ‘hgh.k’, ‘tm’, ‘paw’ 

toldfe float 1.0e-6 TOLerance on the DiFference of total Energy 

A value of None means that ABINIT’s default value is used. 

Warning: abinit does not specify a default value for Planewave cutoff energy in eV - you need to set 

them as in the example at thei bottom of the page, otherwise calculation will fail. Calculations wihout k-points 

are not parallelized by default and will fail! To enable band paralellization specify Number of BanDs in a 

BLOCK (nbdblock) as Extra parameters - see http://www.abinit.org/Infos_v5.2/tutorial/lesson_parallelism.html. 

Extra parameters 

The ABINIT code reads the input parameters for any calculation from a .in file and .files file. This means 

that you can set parameters by manually setting entries in this input .in file. This is done by the syntax: 

>>> calc.set_inp(’name_of_the_entry’, value) 

For example, the ndtset can be set using 

>>> calc.set_inp(’ndtset’, 2) 

The complete list of keywords can be found in the official ABINIT manual. 

Pseudopotentials 

Pseudopotentials in the ABINIT format are available on the pseudopotentials website. A database of user contributed 

pseudopotentials is also available there. 



Example 1 

Here is an example of how to calculate the total energy for bulk Silicon: 


from ase.calculators.abinit import Abinit 

a0 = 5.43 

bulk = Atoms(’Si2’, [(0, 0, 0), 

(0.25, 0.25, 0.25)], 

pbc=True) 

b = a0 / 2 

bulk.set_cell([(0, b, b), 

(b, 0, b), 

(b, b, 0)], scale_atoms=True) 

calc = Abinit(label=’Si’, 

nbands=8, 

xc=’PBE’, 

ecut=50 * Ry, 

mix=0.01, 

kpts=[10, 10, 10]) 

bulk.set_calculator(calc) 

e = bulk.get_potential_energy() 

SIESTA 

Introduction 

SIESTA is a density-functional theory code for very large systems based on atomic orbital (LCAO) basis sets. 


You need to write a script called run_siesta.py containing something like this: 

import os 

siesta = ’siesta_2.0’ 

exitcode = os.system(’%s < %s.fdf > %s.txt’ % (siesta, label, label)) 

The environment variable SIESTA_SCRIPT must point to that file. 

A directory containing the pseudopotential files .vps is also needed, and it is to be put in the environment variable 

SIESTA_PP_PATH. 

Set both environment variables in your shell configuration file: 

$ export SIESTA_SCRIPT=$HOME/siesta/run_siesta.py 

$ export SIESTA_PP_PATH=$HOME/mypps 

SIESTA Calculator 

The default parameters are very close to those that the SIESTA Fortran code uses. These are the exceptions: 

class siesta.Siesta(label=’siesta’, xc=’LDA’, pulay=5, mix=0.1) 

Here is a detailed list of all the keywords for the calculator: 




kpts list [1,1,1] Monkhorst-Pack k-point sampling 

nbands int None Number of bands 

meshcutoff float None Mesh cut-off energy in eV 

basis str None Type of basis set (‘sz’, ‘dz’, ‘szp’, ‘dzp’) 

xc str ’LDA’ Exchange-correlation functional. 

pulay int 5 Number of old densities to use for Pulay mixing 

mix float 0.1 Pulay mixing weight 

width float None Fermi-distribution width in eV 

charge float None Total charge of the system 

label str ’siesta’ Name of the output file 

A value of None means that SIESTA’s default value is used. 

Extra FDF parameters 

The SIESTA code reads the input parameters for any calculation from a .fdf file. This means that you can set 

parameters by manually setting entries in this input .fdf file. This is done by the syntax: 

>>> calc.set_fdf(’name_of_the_entry’, value) 

For example, the EnergyShift can be set using 

>>> calc.set_fdf(’PAO.EnergyShift’, 0.01 * Rydberg) 

The complete list of the FDF entries can be found in the official SIESTA manual. 

Customized basis-set 

Standard basis sets can be set by the keyword basis directly in the Siesta calculator object. If a customized basis 

is needed, it can be set as an FDF entry, as explained in the previous section. 

As an example, we generate a triple-zeta triple-polarized (TZTP) basis for Au. Since the valence states are 6s and 

5d, we will have 3 zeta orbitals for l=0 and 3 for l=2 plus 3 polarization orbitals for l=1. The basis can be defined 

by 

>>> value = ["""Au 2 split 0.00 #label, num. of l-shells,type,charge 

>>> 0 3 P 3 #l,nzeta,’P’(opt):pol.functions,npolzeta 

>>> 0.00 0.00 0.00 #rc of basis functions for each zeta function 

>>> #0.00 => rc determined by PAO.EnergyShift 

>>> 2 3 #l,nzeta 

>>> 0.00 0.00 0.00"""] #rc 

>>> calc.set_fdf(’PAO.Basis’,value=value) 

The default basis set generation fails for Pt for some versions of Siesta. If this happens, you should specify the 

basis set manually. This is exemplified below. 

For Pt, using calc.set_fdf(’PAO.EnergyShift’, 0.1 * eV) is usually resonable, and a single-zeta 

polarized basis set can be specified by writing: 

# Define SZP basis set for Pt 


["""\ 

Pt 2 # Species label, number of l-shells 

n=6 0 1 P # n, l, Nzeta, Polarization, NzetaPol 

0. # 0.0 => default [6.982 \n 1.000] 

n=5 2 1 # n, l, zeta 

0."""]) # 0.0 => default [5.172 \n 1.000] 

A double-zeta polarized basis set for Pt may be specified by: 



# Define DZP basis set for Pt 


["""\ 

Pt 2 split 0.00 # Species label, number of l-shells 

n=6 0 2 P 1 # n, l, Nzeta, Polarization, NzetaPol 

0.00 0.00 # 0.0 => default [6.982 5.935 \n 1.000 1.000] 

n=5 2 2 # n, l, zeta 

0.00 0.00"""]) # 0.0 => default [5.172 3.060 \n 1.000 1.000] 

You can also reuse the basis set of a previous calculation, by copying the .ion files to the new location, and set the 

User.Basis tag to True: 

# Load basis from previous calc (*.ion files) 

calc.set_fdf(’User.Basis’, True) 

Warning: Specifying a basis set manually in any way will, for some obscure reason, make Siesta crash if you have 

ghost atoms! 

Pseudopotentials 

Pseudopotential files in the .psf or .vps formats are needed. Pseudopotentials generated from the ABINIT 

code and converted to the SIESTA format are available in the SIESTA website . A database of user contributed 

pseudopotentials is also available there. 

You can also find an on-line pseudopotential generator from the OCTOPUS code. 

Example 

Here is an example of how to calculate the total energy for bulk Silicon, using a double-zeta basis generated by 

specifying a given energy-shift: 



a0 = 5.43 

bulk = Atoms(’Si2’, [(0, 0, 0), 

(0.25, 0.25, 0.25)], 

pbc=True) 

b = a0 / 2 

bulk.set_cell([(0, b, b), 

(b, 0, b), 

(b, b, 0)], scale_atoms=True) 

calc = Siesta(label=’Si’, 

xc=’PBE’, 

meshcutoff=200 * Ry, 

basis=’dz’, 

mix=0.01, 

kpts=[10, 10, 10]) 

calc.set_fdf(’PAO.EnergyShift’, 0.01 * Ry) 

bulk.set_calculator(calc) 

e = bulk.get_potential_energy() 

Here, the only input information on the basis set is, that it should be double-zeta (basis=’dz’) and that the confinement 

potential should result in an energy shift of 0.01 Rydberg (the PAO.EnergyShift fdf tag). Sometimes 

it can be necessary to specify more information on the basis set. For example, the default basis set generation fails 

for Pt for some versions of Siesta. To fix this, you must specify the basis set manually. Manual basis set specifications 

are described in Customized basis-set. 


Restarting from an old Calculation 


If you want to rerun an old SIESTA calculation, made using the ASE interface or not, you can set the fdf tag 

UseSaveData to True. This is equivalent to setting both DM.UseSaveDM and MD.UseSaveXV to True, i.e. 

it will reuse the the density matrix, and the atomic coordinates (and unit cell) of the previous calculation. Note 

that the Siesta jobname (the label keyword in the ASE interface) must be identical to the jobname of the old 

calculation. 

DftbPlus 

Introduction 

DftbPlus is a density-functional based tight-binding code using atom centered orbitals. This interface makes it 

possible to use DftbPlus as a calculator in ASE. You need to register at DftbPlus site to download the code. 

Additionally you need Slater-coster files for the combination of atom types of your system. These can be obtained 

at dftb.org. 


Set environment variables in your configuration file (what is the directory for the Slater-Koster files and what is 

the name of the executable): 

• bash: 

$ DFTB_PREFIX=/my_disk/my_name/lib/Dftb+sk/mio-0-1/ (an example) 

$ DFTB_COMMAND=~/bin/DFTB+/dftb+_s081217.i686-linux (an example) 

• csh/tcsh: 

$ setenv DFTB_PREFIX /my_disk/my_name/lib/Dftb+sk/mio-0-1/ (an example) 

$ setenv DFTB_COMMAND ~/bin/DFTB+/dftb+_s081217.i686-linux (an example) 

DftbPlus Calculator 

This is a preliminary version of the DftbPlus calculator, so all the DftbPlus features are unfortunately not there. 

Use write_dftb=False to use your own ‘dftb_in.hsd’-file with all the flavours you need. In that case ase only 

updates the coordinates of the system, otherwise file ‘dftb_in.hsd’ remains intact (see example 2 below). However, 

in case of own ‘dftb_in.hsd’ file you need first read in atom position and atom type information of your system for 

ase (for instance a xyz-file), see example 2 below. 

The atom positions in file ‘dftb_in.hsd’ are updated during ASE geometry optimization. 

For the spin polarised calculations this ASE-interface generates parameters with GGA-PBE-spin parameters. If 

you need LDA use your own ‘dftb_in.hsd’-file. 

Information of periodicity is taken from ase (see example1 below). 

For example: 

calc = Dftb(label=’o2’, 

write_dftb=True, 

do_spin_polarized=True, 

unpaired_electrons=2.0, 

fermi_temperature=100.0, 

scc=True) 



Parameters 

label: str Prefix to use for filenames (label.txt, ...). Default is ‘dftb’. 

write_dftb: boolean True: a minimal input file (name of which is always ‘dftb_in.hsd’) is written based on 

values given here. False: input file for dftb+ is not written. User must have generated file ‘dftb_in.hsd’ in 

the working directory. Use write_dftb=False to use your own ‘dftb_in.hsd’-file. 

charge: float Total charge of the system. 

include_dispersion: boolean True: Default dispersion parameters are written in the file ‘dftb_in.hsd’ (requires 

that also write_dftb_input_file==True) False: dispersion parameters are not written here. 

do_spin_polarized: boolean True: Spin polarized calculation False: Spin unpolarized calculation 

unpaired_electrons: float Number of spin unpaired electrons in the system. Relevant only if 

do_spin_polarized==True 

fermi_temperature: float Fermi temperature for electrons. 

scc: boolean True: Do charge self consistent dftb+ False: No SCC, charges on atoms are not iterated 

Example1: Geometry Optimization 


import os 


from ase.calculators.dftb import Dftb 



d = 1.10 

test = Atoms(’2O’, positions=[(0., 0., 0.), (0., 0., d)]) 

test.set_pbc([False, False, False]) 

test.set_calculator(Dftb(label=’o2’,write_dftb=True,do_spin_polarized=True,unpaired_electrons=2.0, 

dyn = QuasiNewton(test, trajectory=’test.traj’) 


write(’test.final.xyz’, test) 

Example2: Geometry Optimization using your own ‘dftb_in.hsd’ file 

#!/usr/bin/python 

from ase.io import read, write 

from ase.calculators.dftb import Dftb 


system = read(’h2o_1.xyz’) 

system.set_calculator(Dftb(label=’dftb’,write_dftb=False)) 

qn = QuasiNewton(system) 


write(’final.xyz’, system) 

write(’final.traj’, system) 

Input file for example 2 (h2o_1.xyz) 


3 

H2O 

O 0.00000 0.00000 0.00000 

H 0.00000 0.00000 1.00000 

H 1.00000 0.00000 0.00000 


You also need to have generated the file ‘dftb_in.hsd’, here is and example: change the variable ‘Prefix’ below 

Geometry = { 

TypeNames = { "O" } 

TypesAndCoordinates [Angstrom] = { 

1 0.00000000000000 0.00000000000000 0.00000000000000 

1 0.00000000000000 0.00000000000000 1.10000000000000 

} 

Periodic = No 

} 

Driver = ConjugateGradient { 

MovedAtoms = Range { 1 -1 } 

MaxForceComponent = 1.0e-4 

MaxSteps = 0 

OutputPrefix = o2 

} 

Hamiltonian = DFTB { # DFTB Hamiltonian 

SCC = Yes # Use self consistent charges 

SCCTolerance = 1.0e-5 # Tolerance for charge consistence 

MaxSCCIterations = 1000 # Nr. of maximal SCC iterations 

Mixer = Broyden { # Broyden mixer for charge mixing 

MixingParameter = 0.2 # Mixing parameter 

} 

SlaterKosterFiles = Type2FileNames { # File names from two atom type names 

TURBOMOLE 

Introduction 

TURBOMOLE is a density-functional or Hartree Fock code using atom centered orbitals. This interface makes it 

possible to use TURBOMOLE as a calculator in ASE. 


Set environment variables in your configuration file: 

• bash: 

$ TURBODIR=/my_disk/my_name/TURBOMOLE 

$ PATH=$PATH:$TURBODIR/scripts 

$ PATH=$PATH:$TURBODIR/bin/‘sysname‘ 

• csh/tcsh: 

$ setenv TURBODIR /my_disk/my_name/TURBOMOLE 

$ set path=($path ${TURBODIR}/scripts) 

$ set path=($path ${TURBODIR}/bin/‘sysname‘) 



Turbomole Calculator 

All usual turbomole input files generated by Turbomole’s define [coord, control, basis, (auxbasis), 

mos/alpha+beta] must be present in the current working directory. 

Turbomole files are updated during the ASE-run. 

Do not use internal coordinates, only cartesians are allowed. 

In the coord file one can fix atoms the turbomole way (writing a ‘f’ in the end of the line in the coord file). 

Ase-Turbomole uses turbomole programs ‘ridft’ and ‘rdgrad’ if keyword ‘$ricore’ is present in the Turbomole’s 

control file. Otherwise programs ‘dscf’ and ‘grad’ are used. 

Example1: Geometry Optimization 


import os 

from ase.io import read,write 


# Turbomole input coordinates must be in the file ’coord’. 

# The coordinates are updated to the file ’coord’ during the minimization. 

test = read(’coord’) 

test.set_calculator(Turbomole()) 

dyn = QuasiNewton(test, trajectory=’test.traj’) 


write(’coord.final.tmol’, test) 

Example2: Diffusion run using NEB 


import os 



from ase.calculators.turbomole import Turbomole 


initial = read(’initial.coord’) 

final = read(’final.coord’) 

os.system(’rm -f coord; cp initial.coord coord’) 

# Make a band consisting of 5 configs: 

configs = [initial] 

configs += [initial.copy() for i in range(3)] 

configs += [final] 

band = NEB(configs, climb=True) 

# Interpolate linearly the positions of the not-endpoint-configs: 


#Set calculators 


config.set_calculator(Turbomole()) 


# Optimize the Path: 

relax = BFGS(band, trajectory=’neb.traj’) 


Example3: Diffusion run using NEB, Restart old calculation 


import os 





initial = read(’initial.coord’) 

final = read(’final.coord’) 

os.system(’rm -f coord; cp initial.coord coord’) 

#restart 

configs = read(’neb.traj@-5:’) 

band = NEB(configs, climb=True) 

#Set calculators 


config.set_calculator(Turbomole()) 

# Optimize: 

relax = BFGS(band, trajectory=’neb.traj’) 


For developers: python files affected by the turbomole interface 

ase: 

__init__.py 

new lines 17from 

ase.calculators import LennardJones, \ 

EMT, ASAP, Siesta, Dacapo, Vasp, Turbomole 

ase/io: 

__init__.py 

new line 44 

TURBOMOLE coord file (filename===’coord’) 

new lines 145if 

format == ’turbomole’: 

from ase.io.turbomole import read_turbomole 

return read_turbomole(filename) 

new line 184 

TURBOMOLE coord file turbomole 

new lines 267elif 

format == ’tmol’: 

from ase.io.turbomole import write_turbomole 

write_turbomole(filename, images) 

return 

new lines 349if 

lines[0].startswith(’$coord’): 

return ’turbomole’ 




NEW FILE: 

ase/io/turbomole.py 

ase/calculators: 

__init__.py 

new line 10 


NEW FILE: 

ase/calculators/turbomole.py 

VASP 

Introduction 

VASP is a density-functional theory code using pseudopotentials or the projector-augmented wave method and a 

plane wave basis set. This interface makes it possible to use VASP as a calculator in ASE, and also to use ASE as 

a post-processor for an already performed VASP calculation. 


You need to write a script called run_vasp.py containing something like this: 

import os 

exitcode = os.system(’vasp’) 

The environment variable VASP_SCRIPT must point to that file. 

A directory containing the pseudopotential directories potpaw (LDA XC) potpaw_GGA (PW91 XC) and 

potpaw_PBE (PBE XC) is also needed, and it is to be put in the environment variable VASP_PP_PATH. 

Set both environment variables in your shell configuration file: 

$ export VASP_SCRIPT=$HOME/vasp/run_vasp.py 

$ export VASP_PP_PATH=$HOME/vasp/mypps 

VASP Calculator 

The default setting used by the VASP interface is 

class vasp.Vasp(restart=None, xc=’PW91’, setups=None, kpts=(1, 1, 1), gamma=None) 

Below follows a list with a selection of parameters 


restart bool None Restart old calculation or use ASE for post-processing 

xc str ’PW91’ XC-functional 

setups str None Additional setup option 

kpts seq Gamma-point k-point sampling 

gamma bool None Gamma-point centered k-point sampling 

reciprocal bool None Use reciprocal units if k-points are specified explicitly 

prec str Accuracy of calculation 

encut float Kinetic energy cutoff 

ediff float Convergence break condition for SC-loop. 

nbands int Number of bands 

algo str Electronic minimization algorithm 

ismear int Type of smearing 

sigma float Width of smearing 

nelm int Maximum number of SC-iterations 


seq: A sequence of three int‘s. 


For parameters in the list without default value given, VASP will set the default value. Most of the parameters 

used in the VASP INCAR file are allowed keywords. See the official VASP manual for more details. 

Note: Parameters can be changed after the calculator has been constructed by using the set() method: 

>>> calc.set(prec=’Accurate’, ediff=1E-5) 

This would set the precision to Accurate and the break condition for the electronic SC-loop to 1E-5 eV. 

Spin-polarized calculation 

If the atoms object has non-zero magnetic moments, a spin-polarized calculation will be performed by default. 

Here follows an example how to calculate the total magnetic moment of a sodium chloride molecule. 

from ase import Atoms, Atom 

from ase.calculators.vasp import Vasp 

a = [6.5, 6.5, 7.7] 

d = 2.3608 

NaCl = Atoms([Atom(’Na’, [0, 0, 0], magmom=1.928), 

Atom(’Cl’, [0, 0, d], magmom=0.75)], 

cell=a) 

calc = Vasp(prec = ’Accurate’, 

xc = ’PBE’, 

lreal = False) 

NaCl.set_calculator(calc) 

print NaCl.get_magnetic_moment() 

In this example the initial magnetic moments are assigned to the atoms when defining the Atoms object. The calculator 

will detect that at least one of the atoms has a non-zero magnetic moment and a spin-polarized calculation 

will automatically be performed. The ASE generated INCAR file will look like: 

INCAR created by Atomic Simulation Environment 

PREC = Accurate 

LREAL = .FALSE. 

ISPIN = 2 

MAGMOM = 1*1.9280 1*0.7500 

Note: It is also possible to manually tell the calculator to perform a spin-polarized calculation: 

>>> calc.set(ispin=2) 

This can be useful for continuation jobs, where the initial magnetic moment is read from the WAVECAR file. 

Restart old calculation 

To continue an old calculation which has been performed without the interface use the restart parameter when 

constructing the calculator 

>>> calc = Vasp(restart=True) 

Then the calculator will read atomic positions from the CONTCAR file, physical quantities from the OUTCAR file, 

k-points from the KPOINTS file and parameters from the INCAR file. 



Note: Only Monkhorst-Pack and Gamma-centered k-point sampling are supported for restart at the moment. 

Some INCAR parameters may not be implemented for restart yet. Please report any problems to the ASE mailing 

list. 

The restart parameter can be used , as the name suggest to continue a job from where a previous calculation 

finished. Furthermore, it can be used to extract data from an already performed calculation. For example, to get the 

total potential energy of the sodium chloride molecule in the previous section, without performing any additional 

calculations, in the directory of the previous calculation do: 

>>> calc = Vasp(restart=True) 

>>> atoms = calc.get_atoms() 

>>> atoms.get_potential_energy() 

-4.7386889999999999 

FHI-aims 

Introduction 

FHI-aims is a all-electron full-potential density functional theory code using a numeric local orbital basis set. This 

interface provides all that should be required to run FHI-aims from within ASE. 

Running the Calculator 

The default initialization command for the FHI-aims calculator is 

class FHI-aims.Aims(output_template = ‘aims’, track_output = False) 

In order to run a calculation, you have to ensure that at least the following str variables are specified, either in 

the initialization or as shell variables: 

key- description 

word 

run_command The full command required to run FHI-aims from a shell, including anything to do with an MPI 

wrapper script and the number of tasks. An alternative way to set this command is via the shell 

variable AIMS_COMMAND, which is checked upon initialization and when starting a run. 

species_dir Directory where the species defaults are located that should be used. Can also be specified with 

the system variable AIMS_SPECIES_DIR. 

xc The minimal physical specification: what kind of calculation should be done. 

In addition, you might want to specify at least one of self-consistency accuracy commands (see below) in order to 

avoid an excessively long calculation. 

Two general options might come in useful to postprocess the output: 

keyword description 

output_template Base name for the output, in case the calculator is called multiple times within a single 

script. 

track_output True/False - if True all the output files will be kept, while the number of calls to the 

calculator is encoded in the output file name. 

List of keywords 

This is a non-exclusive list of keywords for the control.in file that can be addresses from within ASE. The 

meaning for these keywords is exactly the same as in FHI-aims, please refer to its manual for help on their use. 

One thing that should be mentioned is that keywords with more than one option have been implemented as lists, eg. 

k_grid=(12,12,12) or relativistic=(’atomic_zora’,’scalar’). In those cases, specifying a 

single string containing all the options is also possible. 



None of the keywords have any default within ASE,but do check the defaults set by FHI-aims. If there is a keyword 

that you would like to set and that is not yet implemented here, it is trivial to add to the first few lines of the aims 

calculator in the file ASE/ase/calculators/aims.py . 

Describing the basic physics of the system: 

keyword type 

xc str 

charge float 

spin str 

relativistic list 

use_dipole_correction bool 

vdw_correction_hirshfeld str 

k_grid list 

Driving relaxations and molecular dynamics: 

keyword type 

relax_geometry list 

max_relaxation_steps int 

n_max_pulay int 

sc_iter_limit int 

restart_relaxations bool 

MD_run list 

MD_schedule list 

MD_segment list 

Output options: 

keyword type 

output_level str 

output list 

cubes AimsCube 

See below for a description of the volumetric cube file output interface AimsCube 

Keywords for accuracy settings: 

keyword type 

sc_accuracy_eev exp 

sc_accuracy_etot exp 

sc_accuracy_forces exp 

sc_accuracy_rho exp 

compute_forces bool 

Keywords to adjust the SCF-cycle 

keyword type 

charge_mix_param float 

prec_mix_param float 

spin_mix_param float 

KS_method str 

restart str 

restart_read_only str 

restart_write_only srt 

preconditioner list 

mixer str 

empty_states int 

ini_linear_mixing int 

mixer_threshold list 

occupation_type list 

Note: 



Any argument can be changed after the initial construction of the 

calculator, simply by setting it with the method 

>>> calc.set( keyword=value ) 

Volumetric Data Output 

The class 

class FHI-aims.AimsCube(origin=(0,0,0),edges=[(0.1,0.0,0.0),(0.0,0.1,0.0),(0.0,0.0,0.1)],points=(50,50,50),plots=None) 

describes an object that takes care of the volumetric output requests within FHI-aims. An object of this type can 

be attached to the main Aims() object as an option. 

The possible arguments for AimsCube are: 

keyword type 

origin list 

edges 3x3-array 

points list 

plots list 

The possible values for the entry of plots are discussed in detail in the FHI-aims manual, see below for an example. 

Example 

As an example, here is a possible setup to obtain the geometry of a water molecule: 



from ase.calculators.aims import Aims, AimsCube 


water = Atoms(’HOH’, [(1,0,0), (0,0,0), (0,1,0)]) 

water_cube = AimsCube(points=(29,29,29), 

plots=(’total_density’,’delta_density’, 

’eigenstate 5’,’eigenstate 6’)) 

calc=Aims(xc=’pbe’, 

sc_accuracy_etot=1e-6, 

sc_accuracy_eev=1e-3, 

sc_accuracy_rho=1e-6, 

sc_accuracy_forces=1e-4, 

species_dir=’/home/hanke/codes/fhi-aims/fhi-aims.workshop/species_defaults/light/’, 

run_command=’aims.workshop.serial.x’, 

cubes=water_cube) 

water.set_calculator(calc) 

dynamics = QuasiNewton(water,trajectory=’square_water.traj’) 

dynamics.run(fmax=0.01) 

view(water) 

LAMMPS 

Introduction 

LAMMPS (Large-scale Atomic/Molecular Massively Parallel Simulator) is a classical molecular dynamics code. 



“LAMMPS has potentials for soft materials (biomolecules, polymers) and solid-state materials (metals, 

semiconductors) and coarse-grained or mesoscopic systems. It can be used to model atoms or, 

more generically, as a parallel particle simulator at the atomic, meso, or continuum scale.” 


The environment variable LAMMPS_COMMAND should contain the path to the lammps binary, or more generally, 

a command line possibly also including an MPI-launcher command. For example (in a Bourne-shell compatible 

environment): 

$ export LAMMPS_COMMAND=/path/to/lmp_binary 

or possibly something similar to 

$ export LAMMPS_COMMAND="/path/to/mpirun --np 4 lmp_binary" 

LAMMPS Calculator 

The LAMMPS calculator first appeared in ASE version 3.5.0. At the time of the release of ASE 3.5.0, the 

LAMMPS calculator is still in a fairly early stage of development (if you are missing some feature, consider 

checking out the source code development tree or some more recent version of ASE). 

class lammps.LAMMPS(..., parameters={}, files=[], ...) 

Below follows a list with a selection of parameters 

keyword 

type default 

value 

description 

files list[] List of files needed by LAMMPS. Typically a list of potential files. 

parameters dict{} Dictionary with key-value pairs corresponding to commands and arguments. 

Command-argument pairs provided here will be used for overriding the the 

calculator defaults. 

Example 

A simple example. 

from ase import Atoms, Atom 

from ase.calculators.lammps import LAMMPS 

a = [6.5, 6.5, 7.7] 

d = 2.3608 

NaCl = Atoms([Atom(’Na’, [0, 0, 0]), 

Atom(’Cl’, [0, 0, d])], 

cell=a, pbc=True) 

calc = LAMMPS() 

NaCl.set_calculator(calc) 

print NaCl.get_stress() 

Molecular Modelling Toolkit 

class mmtk.MMTK 



Warning: ASE2 has an interface to MMTK, but ASE3 has not. There may be a problem with MMTK and 

numpy? 

Let us know if you need MMTK, and we will take a look at it. 

exciting 

Introduction 

exciting is a full-potential all-electron density-functional-theory (DFT) package based on the linearized augmented 

planewave (LAPW) method. It can be applied to all kinds of materials, irrespective of the atomic species 

involved, and also allows for the investigation of the core region. The website is http://exciting-code.org/ 

The module depends on lxml http://codespeak.net/lxml/ 

Exciting Calculator Class 

class ase.calculators.exciting.Exciting(dir=’calc’, template=None, 

speciespath=’http://xml.excitingcode.org/species/’, 

bin=’excitingser’, kpts=(1, 1, 

1), **kwargs) 

Exciting calculator object constructor 

dir: string directory in which to execute exciting 

template: string Path to XSLT template if it should be used default: none 

speciespath: string Directory or URL to look up species files 

bin: string Path or executable name of exciting default: excitingser 

kpts: integer list length 3 Number of k-points 

kwargs: dictionary like list of key value pairs to be converted into groundstate attributes 

There are two ways to construct the exciting calculator. 

Constructor Keywords One is by giving parameters of the ground state in the constructor. The possible attributes 

can be found at http://exciting-code.org/input-reference#groundstate. 

class exciting.Exciting(bin=’excitingser’, kpts=(4, 4, 4), xctype=’GGArevPBE’) 

XSLT Template The other way is to use an XSLT template 

class exciting.Exciting(template=’template.xsl’, bin=’excitingser’) 

The template may look like: 

 

 

 

 

 

created from template 

 



 

 

 

 

 

 

 

 

 

 

 

 

Current Limitations 

The calculator supports only total energy and forces no stress strain implemented in exciting yet. However it is 

planned to be implemented soon. http://exciting-code.org/current-developments. 

The keywords on the constructor are converted into attributes of the groundstate element. No check is done 

there and not all options are accessible in that way. By using the template one can exceed this limitation. 

FLEUR 

Introduction 

FLEUR is a density-functional theory code which uses the full potential linearized augmented plane-wave 

(FLAPW) method. FLEUR can be applied to any element in the periodic table, and the code is well suited 

especially to surfaces and magnetic materials. 


In order to use FLEUR through ASE, two environment variables have to be set. FLEUR_INPGEN should point to 

the simple input generator of FLEUR, and FLEUR to the actual executable. Note that FLEUR has different executables 

e.g. for cases with and without inversion symmetry, so the environment variable has to be set accordingly. 

As an example, the variables could be set like: 

$ export FLEUR_INPGEN=$HOME/fleur/v25/inpgen.x 

$ export FLEUR=$HOME/fleur/v25/fleur.x 

or: 

$ export FLEUR="mpirun -np 32 $HOME/fleur/v25/fleur.x" 

for parallel calculations. 

FLEUR Calculator 

Currently, limited number of FLEUR parameters can be set via the ASE interface Below follows a list of supported 

parameters 




xc str ’LDA’ XC-functional. Must be one of ‘LDA’, ‘PBE’, ‘RPBE’ 

kpts seq Gamma-point k-point sampling 

convergence dict {’energy’: 0.0001} Convergence criteria (meV) 

width float Width of Fermi smearing (eV) 

kmax float Plane-wave cut-off (a.u.) 

mixer dict Mixing parameters ‘imix’, ‘alpha’, and ‘spinf’ 

maxiter int 40 Maximum number of SCF steps 

maxrelax int 20 Maximum number of relaxation steps 

workdir str Current dir Working directory for the calculation 

seq: A sequence of three int‘s. dict: A dictionary 

Spin-polarized calculation 

If the atoms object has non-zero magnetic moments, a spin-polarized calculation will be performed by default. 

Utility functions 

As only a subset of FLEUR parameters can currently be specified through ASE interface, the interface defines 

some utility functions for cases where manual editing of the FLEUR input file inp is necessary. 

FLEUR.write_inp(atoms) 

Write the inp input file of FLEUR. 

First, the information from Atoms is written to the simple input file and the actual input file inp is then 

generated with the FLEUR input generator. The location of input generator is specified in the environment 

variable FLEUR_INPGEN. 

Finally, the inp file is modified according to the arguments of the FLEUR calculator object. 

FLEUR.initialize_density(atoms) 

Creates a new starting density. 

FLEUR.calculate(atoms) 

Converge a FLEUR calculation to self-consistency. 

Input files should be generated before calling this function FLEUR performs always fixed number of SCF 

steps. This function reduces the number of iterations gradually, however, a minimum of five SCF steps is 

always performed. 

FLEUR.relax(atoms) 

Currently, user has to manually define relaxation parameters (atoms to relax, relaxation directions, etc.) in 

inp file before calling this function. 

Examples 

Lattice constant of fcc Ni 

from numpy import linspace 

from ase.calculators.fleur import FLEUR 



atoms = bulk(’Ni’, a=3.52) 

calc = FLEUR(xc=’PBE’, kmax=3.6, kpts=(10, 10, 10), workdir=’lat_const’) 


traj = PickleTrajectory(’Ni.traj’,’w’, atoms) 

cell0 = atoms.get_cell() 


for s in linspace(0.95, 1.05, 7): 

cell = cell0 * s 

atoms.set_cell((cell)) 

ene = atoms.get_potential_energy() 

traj.write() 

See the equation of states tutorial for analysis of the results. 

CASTEP 

Introduction 


CASTEP 1 is a software package which uses density functional theory to provide a good atomic-level description 

of all manner of materials and molecules. CASTEP can give information about total energies, forces and stresses 

on an atomic system, as well as calculating optimum geometries, band structures, optical spectra, phonon spectra 

and much more. It can also perform molecular dynamics simulations. 

The CASTEP calculator interface class offers intuitive access to all CASTEP settings and most results. All 

CASTEP specific settings are accessible via attribute access (i.e. calc.param.keyword = ... or 

calc.cell.keyword = ...) 

Getting Started: 

Set the environment variables appropriately for your system. 

>>> export CASTEP_COMMAND=’ ... ’ 

>>> export CASTEP_PP_PATH=’ ... ’ 

Running the Calculator 

The default initialization command for the CASTEP calculator is 

class castep.Castep(directory=’CASTEP’, label=’castep’) 

To do a minimal run one only needs to set atoms, this will use all default settings of CASTEP, meaning LDA, 

singlepoint, etc.. 

With a generated castep_keywords.py in place all options are accessible by inspection, i.e. tab-completion. This 

works best when using ipython. All options can be accessed via calc.param. or calc.cell. 

and documentation is printed with calc.param. ? or calc.cell. 

?. All options can also be set directly using calc.keyword = ... or calc.KEYWORD = 

... or even calc.KeYwOrD or directly as named arguments in the call to the constructor (e.g. 

Castep(task=’GeometryOptimization’)). 

All options that go into the .param file are held in an CastepParam instance, while all options that go into 

the .cell file and don’t belong to the atoms object are held in an CastepCell instance. Each instance can 

be created individually and can be added to calculators by attribute assignment, i.e. calc.param = param or 

calc.cell = cell. 

All internal variables of the calculator start with an underscore (_). All cell attributes that clearly belong into 

the atoms object are blocked. Setting calc.atoms_attribute (e.g. = positions) is sent directly to the 

atoms object. 

1 S. J. Clark, M. D. Segall, C. J. Pickard, P. J. Hasnip, M. J. Probert, K. Refson, M. C. Payne Zeitschrift für Kristallographie 220(5-6) 

pp.567- 570 (2005) 



Arguments: 

Key- Description 

word 

directory The relative path where all input and output files will be placed. If this does not exist, it will be 

created. Existing directories will be moved to directory-TIMESTAMP unless 

self._rename_existing_dir is set to false. 

label The prefix of .param, .cell, .castep, etc. files. 

Additional Settings 

Internal Description 

Setting 

_castep_command (=castep): the actual shell command used to call CASTEP. 

_check_checkfile (=True): this makes write_param() only write a continue or reuse statement if the 

addressed .check or .castep_bin file exists in the directory. 

_copy_pspots (=False): if set to True the calculator will actually copy the needed pseudo-potential 

(*.usp) file, usually it will only create symlinks. 

_export_settings (=True): if this is set to True, all calculator internal settings shown here will be included 

in the .param in a comment line (#) and can be read again by merge_param. merge_param 

can be forced to ignore this directive using the optional argument 

ignore_internal_keys=True. 

_force_write (=True): this controls wether the *cell and *param will be overwritten. 

_prepare_input_only (=False): If set to True, the calculator will create *cell und *param file but not start the 

calculation itself. If this is used to prepare jobs locally and run on a remote cluster it is 

recommended to set _copy_pspots = True. 

_castep_pp_path (=’.’) : the place where the calculator will look for pseudo-potential files. 

_rename_existing_dir (=True) : when using a new instance of the calculator, this will move directories out of 

the way that would be overwritten otherwise, appending a date string. 

_set_atoms (=False) : setting this to True will overwrite any atoms object previously attached to the 

calculator when reading a .castep file. By default, the read() function will only create a 

new atoms object if none has been attached and otherwise try to assign forces etc. based 

on the atom’s positions. _set_atoms=True could be necessary if one uses CASTEP’s 

internal geometry optimization (calc.param.task=’GeometryOptimization’) 

because then the positions get out of sync. Warning: this option is generally not 

recommended unless one knows one really needs it. There should never be any need, if 

CASTEP is used as a single-point calculator. 

_track_output(=False) : if set to true, the interface will append a number to the label on all input and 

output files, where n is the number of calls to this instance. Warning: this setting may consume 

a lot more disk space because of the additional *check files. 

_try_reuse (=_track_output) : when setting this, the interface will try to fetch the reuse file 

from the previous run even if _track_output is True. By default it is equal to 

_track_output, but may be overridden. 

Since this behavior may not always be desirable for single-point calculations. Regular 

reuse for e.g. a geometry-optimization can be achieved by setting calc.param.reuse 

= True. 

Special features: 

.dryrun_ok() Runs castep_command seed -dryrun in a temporary directory return True if all variables 

initialized ok. This is a fast way to catch errors in the input. Afterwards _kpoints_used is set. 

.merge_param() Takes a filename or filehandler of a .param file or CastepParam instance and merges it into 

the current calculator instance, overwriting current settings 



.keyword.clear() Can be used on any option like calc.param.keyword.clear() or 

calc.cell.keyword.clear() to return to the CASTEP default. 

.initialize() Creates all needed input in the _directory. This can then copied to and run in a place 

without ASE or even python. 

.set_pspot(’’) This automatically sets the pseudo-potential for all present species to 

_.usp. Make sure that _castep_pp_path is set correctly. 

print(calc) Prints a short summary of the calculator settings and atoms. 

ase.io.castep.read_seed(’path-to/seed’) Given you have a combination of 

seed.{param,cell,castep} this will return an atoms object with the last ionic positions in the .castep 

file and all other settings parsed from the .cell and .param file. If no .castep file is found the positions are 

taken from the .cell file. The output directory will be set to the same directory, only the label is preceded 

by ‘copy_of_’ to avoid overwriting. 

Notes/Issues: 

• Currently only the FixAtoms constraint is fully supported for reading and writing. 

• There is no support for the CASTEP unit system. Units of eV and Angstrom are used throughout. In particular 

when converting total energies from different calculators, one should check that the same CODATA 

version is used for constants and conversion factors, respectively. 

Example: 

#!/usr/bin/python 

"""This simple demo calculates the total energy of CO molecules 

using once LDA and once PBE as xc-functional. Obviously 

some parts in this scripts are longer than necessary, but are shown 

to demonstrate some more features.""" 

import ase 

import ase.calculators.castep, ase.io.castep 

calc = ase.calculators.castep.Castep() 

directory = ’CASTEP_ASE_DEMO’ 

# include interface settings in .param file 

calc._export_settings = True 

# reuse the same directory 

calc._directory = directory 

calc._rename_existing_dir = False 

calc._label = ’CO_LDA’ 

# necessary for tasks with changing positions 

# such as GeometryOptimization or MolecularDynamics 

calc._set_atoms = True 

# Param settings 

calc.param.xc_functional = ’LDA’ 

calc.param.cut_off_energy = 400 

# Prevent CASTEP from writing *wvfn* files 

calc.param.num_dump_cycles = 0 

# Cell settings 

calc.cell.kpoint_mp_grid = ’1 1 1’ 

calc.cell.fix_com = False 

calc.cell.fix_all_cell = True 



# Set and clear and reset settings (just for shows) 

calc.param.task = ’SinglePoint’ 

# Reset to CASTEP default 

calc.param.task.clear() 

# all of the following are identical 

calc.param.task = ’GeometryOptimization’ 

calc.task = ’GeometryOptimization’ 

calc.TASK = ’GeometryOptimization’ 

calc.Task = ’GeometryOptimization’ 

# Prepare atoms 

mol = ase.atoms.Atoms(’CO’, [[0, 0, 0], [0, 0, 1.2]], cell=[10, 10, 10]) 

mol.set_calculator(calc) 

# Check for correct input 

if calc.dryrun_ok(): 

print(’%s : %s ’ % (mol.calc._label, mol.get_potential_energy())) 

else: 

print("Found error in input") 

print(calc._error) 

# Read all settings from previous calculation 

mol = ase.io.castep.read_seed(’%s/CO_LDA’ % directory) 

# Use the OTF pseudo-potential we have just generated 

mol.calc.set_pspot(’OTF’) 

# Change some settings 

mol.calc.param.xc_functional = ’PBE’ 

# don’t forget to set an appropriate label 

mol.calc._label = ’CO_PBE’ 

# Recalculate the potential energy 

print(’%s : %s ’ % (mol.calc._label, mol.get_potential_energy())) 

Gromacs 

Introduction 

Gromacs is a free classical molecular dynamics package. It is mainly used in modeling of biological systems. It 

is part of the ubuntu-linux distribution. 

Gromacs Calculator 

This ASE-interface is a preliminary one and it is VERY SLOW so do not use it for production runs. It is here 

because of hopefully we’ll get a QM/MM calculator which is using gromacs as the MM part. 

For example: 

calc = Gromacs( init_structure_file=infilename, force_field=’oplsaa’, water_model=’tip3p’, define = ‘- 

DFLEXIBLE’, integrator = ‘md’, nsteps = ‘0’, nstfout = ‘1’, nstlog = ‘1’, nstenergy = ‘1’, energygrps = 

‘System’, nstlist = ‘1’, ns_type = ‘grid’, pbc = ‘xyz’, rlist = ‘1.15’, coulombtype = ‘PME-Switch’, rcoulomb 

= ‘0.8’, vdwtype = ‘shift’, rvdw = ‘0.8’, rvdw_switch = ‘0.75’, DispCorr = ‘Ener’) 


Parameters 


The description of the parameters can be found in the Gromacs manual: 

http://www.gromacs.org/Documentation/Manual 

except these parameters should be fixed: integrator = ‘md’, nsteps = ‘0’ 

and extra (ie non-gromacs) parameter: 

init_structure_file: str The name of the initial structure file. The structure file should be in .gro format because 

pdb reading in ASE is not very good. 

Example1: Geometry Optimization of a histidine molecule 

Initial pdb coordinates (file his.pdb): 

COMPND HIS HISTIDINE 

REMARK HIS Part of HIC-Up: http://xray.bmc.uu.se/hicup 

REMARK HIS Extracted from PDB file pdb1wpu.ent 

HETATM 1 N HIS 4234 0.999 -1.683 -0.097 1.00 20.00 

HETATM 2 CA HIS 4234 1.191 -0.222 -0.309 1.00 20.00 

HETATM 3 C HIS 4234 2.641 0.213 -0.105 1.00 20.00 

HETATM 4 O HIS 4234 3.529 -0.651 -0.222 1.00 20.00 

HETATM 5 CB HIS 4234 0.245 0.546 0.619 1.00 20.00 

HETATM 6 CG HIS 4234 -1.200 0.349 0.280 1.00 20.00 

HETATM 7 ND1 HIS 4234 -1.854 -0.849 0.470 1.00 20.00 

HETATM 8 CD2 HIS 4234 -2.095 1.176 -0.310 1.00 20.00 

HETATM 9 CE1 HIS 4234 -3.087 -0.752 0.006 1.00 20.00 

HETATM 10 NE2 HIS 4234 -3.258 0.467 -0.474 1.00 20.00 

HETATM 11 OXT HIS 4234 2.889 1.404 0.141 1.00 20.00 

REMARK HIS ENDHET 

First generate the initial structure in gromacs format (.gro) 

pdb2gmx -f his.pdb -o hish.gro -ff oplsaa -water tip3p 

Then setup a periodic simulation box 

editconf_d -f hish.gro -o hishBOX.gro -box 3 3 3 

Finally, relax the structure: The sample file: 


""" An example for using gromacs calculator in ase. 

Atom positions are relaxed. 

A sample call: 

""" 

./gromacs_example_relax.py hishBOX.gro 



from ase.calculators.gromacs import Gromacs 


from ase.optimize.bfgslinesearch import BFGSLineSearch 

from ase.optimize import MDMin 

from ase.optimize.sciopt import SciPyFminBFGS, SciPyFminCG 

from ase.optimize.sciopt import SciPyFmin 

from ase.optimize.sciopt import SciPyOptimizer 

import sys 





infilename = sys.argv[1] 

calc = Gromacs( 

init_structure_file=infilename, 

force_field=’oplsaa’, 

water_model=’tip3p’, 

define = ’-DFLEXIBLE’, 

integrator = ’md’, 

nsteps = ’0’, 

nstfout = ’1’, 

nstlog = ’1’, 

nstenergy = ’1’, 

energygrps = ’System’, 

nstlist = ’1’, 

ns_type = ’grid’, 

pbc = ’xyz’, 

rlist = ’1.15’, 

coulombtype = ’PME-Switch’, 

rcoulomb = ’0.8’, 

vdwtype = ’shift’, 

rvdw = ’0.8’, 

rvdw_switch = ’0.75’, 

DispCorr = ’Ener’) 

system = read(’gromacs.gro’) 

system.set_calculator(calc) 

e_system = system.get_potential_energy() 

f_system = system.get_forces() 

# SciPyFminCG == non-linear Polak-Ribiere, should be the same as gromacs 

dyn = SciPyFminCG(system) 


7.14.3 Calculator interface 

All calculators must have the following interface: 

class ase.calculators.interface.Calculator 

Class for demonstrating the ASE-calculator interface. 

A good implementation of a calculator should store a copy of the atoms object used for the last calculation. 

When one of the get_potential_energy, get_forces, or get_stress methods is called, the calculator should 

check if anything has changed since the last calculation and only do the calculation if it’s really needed. The 

Atoms class implements the methods __eq__ and __ne__ that can be used for checking identity (using == 

and !=): Two sets of atoms are considered identical if they have the same positions, atomic numbers, unit 

cell and periodic boundary conditions. 

calculation_required(atoms, quantities) 

Check if a calculation is required. 

Check if the quantities in the quantities list have already been calculated for the atomic configuration 

atoms. The quantities can be one or more of: ‘energy’, ‘forces’, ‘stress’, and ‘magmoms’. 

get_forces(atoms) 

Return the forces. 

get_potential_energy(atoms=None, force_consistent=False) 

Return total energy. 

Both the energy extrapolated to zero Kelvin and the energy consistent with the forces (the free energy) 

can be returned. 


get_stress(atoms) 

Return the stress. 

set_atoms(atoms) 

Let the calculator know the atoms. 


This method is optional. If it exists, it will be called when the Atoms.set_calculator() method is called. 

Don’t store a reference to atoms - that will create a cyclic reference loop! Store a copy instead. 

7.14.4 Electronic structure calculators 

These calculators have wave functions, electron densities, eigenvalues and many other quantities. Therefore, it 

makes sense to have a set of standard methods for accessing those quantities: 

class ase.calculators.interface.DFTCalculator 

Class for demonstrating the ASE interface to DFT-calculators. 

get_bz_k_points() 

Return all the k-points in the 1. Brillouin zone. 

The coordinates are relative to reciprocal latice vectors. 

get_effective_potential(spin=0, pad=True) 

Return pseudo-effective-potential array. 

get_eigenvalues(kpt=0, spin=0) 

Return eigenvalue array. 

get_fermi_level() 

Return the Fermi level. 

get_ibz_k_points() 

Return k-points in the irreducible part of the Brillouin zone. 

The coordinates are relative to reciprocal latice vectors. 

get_k_point_weights() 

Weights of the k-points. 

The sum of all weights is one. 

get_magnetic_moment(atoms=None) 

Return the total magnetic moment. 

get_number_of_bands() 

Return the number of bands. 

get_number_of_grid_points() 

Return the shape of arrays. 

get_number_of_spins() 

Return the number of spins in the calculation. 

Spin-paired calculations: 1, spin-polarized calculation: 2. 

get_occupation_numbers(kpt=0, spin=0) 

Return occupation number array. 

get_pseudo_density(spin=None, pad=True) 

Return pseudo-density array. 

If spin is not given, then the total density is returned. Otherwise, the spin up or down density is 

returned (spin=0 or 1). 

get_pseudo_wave_function(band=0, kpt=0, spin=0, broadcast=True, pad=True) 

Return pseudo-wave-function array. 



get_spin_polarized() 

Is it a spin-polarized calculation? 

get_wannier_localization_matrix(nbands, dirG, kpoint, nextkpoint, G_I, spin) 

Calculate integrals for maximally localized Wannier functions. 

get_xc_functional() 

Return the XC-functional identifier. 

‘LDA’, ‘PBE’, ... 

initial_wannier(initialwannier, kpointgrid, fixedstates, edf, spin, nbands) 

Initial guess for the shape of wannier functions. 

Use initial guess for wannier orbitals to determine rotation matrices U and C. 

7.14.5 Building new calculators 

Adding an ASE interface to your favorite force-calculator can be very simple. Take a look at the Python wrapper 

we have in the ASE code for using the SIESTA code with ASE: ase/calculators/siesta.py. Here, a Siesta class 

is defined. An instance of this class will simply write the fdf input-file, start the SIESTA Fortran program, and 

finally read the energy, forces and stresses from the text output-file. 

7.14.6 Building neighbor-lists 

The EMT potential and the GPAW DFT calculator both make use of ASE’s built-in neighbor-list class: 

class ase.calculators.neighborlist.NeighborList(cutoffs, skin=0.3, sorted=False, 

self_interaction=True, bothways=False) 

Neighbor list object. 

cutoffs: list of float List of cutoff radii - one for each atom. 

skin: float If no atom has moved more than the skin-distance since the last call to the update() method, 

then the neighbor list can be reused. This will save some expensive rebuilds of the list, but extra 

neighbors outside the cutoff will be returned. 

self_interaction: bool Should an atom return itself as a neighbor? 

bothways: bool Return all neighbors. Default is to return only “half” of the neighbors. 

Example: 

nl = NeighborList([2.3, 1.7]) 

nl.update(atoms) 

indices, offsets = nl.get_neighbors(0) 

build(atoms) 

Build the list. 

get_neighbors(a) 

Return neighbors of atom number a. 

A list of indices and offsets to neighboring atoms is returned. The positions of the neighbor atoms can 

be calculated like this: 

indices, offsets = nl.get_neighbors(42) 

for i, offset in zip(indices, offsets): 

print atoms.positions[i] + dot(offset, atoms.get_cell()) 

Notice that if get_neighbors(a) gives atom b as a neighbor, then get_neighbors(b) will not return a as 

a neighbor - unless bothways=True was used. 


update(atoms) 

Make sure the list is up to date. 

7.15 Constraints 


When performing minimizations or dynamics one may wish to keep some degrees of freedom in the system fixed. 

One way of doing this is by attaching constraint object(s) directly to the atoms object. 

Important: setting constraints will freeze the corresponding atom positions. Changing such atom positions can be 

achieved: 

• by directly setting the positions attribute (see example of setting Special attributes), 

• alternatively, by removing the constraints first: 

del atoms.constraints 

or: 

atoms.set_constraint() 

and using the set_positions() method. 

7.15.1 The FixAtoms class 

This class is used for fixing some of the atoms. 

class constraints.FixAtoms(indices=None, mask=None) 

You must supply either the indices of the atoms that should be fixed or a mask. The mask is a list of booleans, one 

for each atom, being true if the atoms should be kept fixed. 

For example, to fix the positions of all the Cu atoms in a simulation with the indices keyword: 

>>> c = FixAtoms(indices=[atom.index for atom in atoms if atom.symbol == ’Cu’]) 

>>> atoms.set_constraint(c) 

or with the mask keyword: 

>>> c = FixAtoms(mask=[atom.symbol == ’Cu’ for atom in atoms]) 


7.15.2 The FixBondLength class 

This class is used to fix the distance between two atoms specified by their indices (a1 and a2) 

class constraints.FixBondLength(a1, a2) 

Example of use: 

>>> c = FixBondLength(0, 1) 


In this example the distance between the atoms with indices 0 and 1 will be fixed in all following dynamics and/or 

minimizations performed on the atoms object. 

This constraint is useful for finding minimum energy barriers for reactions where the path can be described well 

by a single bond length (see the Dissociation tutorial). 

Important: If fixing multiple bond lengths, use the FixBondLengths class below, particularly if the same atom is 

fixed to multiple partners. 

7.15. Constraints 139


7.15.3 The FixBondLengths class 

More than one bond length can be fixed by using this class. Especially for cases in which more than one bond 

length constraint is applied on the same atom. It is done by specifying the indices of the two atoms forming the 

bond in pairs. 

class constraints.FixBondLengths(pairs) 


>>> c = FixBondLengths([[0, 1], [0, 2]]) 


Here the distances between atoms with indices 0 and 1 and atoms with indices 0 and 2 will be fixed. The constraint 

is for the same purpose as the FixBondLength class. 

7.15.4 The FixedLine class 

class ase.constraints.FixedLine(a, direction) 

Constrain an atom a to move on a given line only. 

The line is defined by its direction. 

7.15.5 The FixedPlane class 

class ase.constraints.FixedPlane(a, direction) 

Constrain an atom a to move in a given plane only. 

The plane is defined by its normal: direction. 

Example of use: Diffusion of gold atom on Al(100) surface (constraint). 

7.15.6 The FixedMode class 

class ase.constraints.FixedMode(mode) 

Constrain atoms to move along directions orthogonal to a given mode only. 

A mode is a list of vectors specifying a direction for each atom. It often comes from 

ase.vibrations.Vibrations.get_mode(). 

7.15.7 The BondSpring class 

This constraint applies a Hookean restorative force between two atoms if the distance between them exceeds 

a threshhold. This is useful to maintain the identity of molecules in quenched molecular dynamics, without 

changing the degrees of freedom or violating conservation of energy. When the distance between the two atoms 

is less than the threshhold length, this constraint is completely inactive. 

The below example tethers together atoms at index 3 and 4 together: 

>>> c = BondSpring(a1=3, a2=4, threshhold_length=1.79, 

springconstant=5.) 


Alternatively, this constraint can tether a single atom to a point in space, for example to prevent the top layer of 

a slab from subliming during a high-temperature MD simulation. An example of tethering atom at index 3 to its 

original position: 

>>> c = BondSpring(a1=3, a2=atoms[3].position, threshhold_length=0.94, 

springconstant=2.) 



Reasonable values of the threshhold and spring constant for some common bonds are below. 

Bond threshhold_length springconstant 

O-H 1.40 5 

C-O 1.79 5 

C-H 1.59 7 

C=O 1.58 10 

Pt sublimation 0.94 2 

Cu sublimation 0.97 2 

7.15.8 The FixInternals class 


This class allows to fix an arbitrary number of bond lengths, angles and dihedral angles. The defined constraints are 

satisfied self consistently. To define the constraints one needs to specify the atoms object on which the constraint 

works (needed for atomic masses), a list of bond, angle and dihedral constraints. Those constraint definitions 

are always list objects containing the value to be set and a list of atomic indices. The epsilon value specifies the 

accuracy to which the constraints are fullfilled. 

class constraints.FixInternals(atoms, bonds=[bond1, bond2], angles=[angle1], dihedrals=[dihedral1, 

dihedral2], epsilon=1.e-7) 


>>> bond1 = [1.20, [1, 2]] 

>>> angle_indices1 = [2, 3, 4] 

>>> dihedral_indices1 = [2, 3, 4, 5] 

>>> angle1 = [atoms.get_angle(angle_indices1), angle_indices1] 

>>> dihedral1 = [atoms.get_dihedral(dihedral_indices1), \ 

dihedral_indices1] 

>>> c = FixInternals(atoms, bonds=[bonds1], angles=[angles1], \ 

dihedrals=[dihedral1]) 

>>> atoms.set_onstraint(c) 

This example defines a bond an angle and a dihedral angle constraint to be fixed at the same time. 

7.15.9 Combining constraints 

It is possible to supply several constraints on an atoms object. For example one may wish to keep the distance 

between two nitrogen atoms fixed while relaxing it on a fixed ruthenium surface: 

>>> pos = [[0.00000, 0.00000, 9.17625], 

... [0.00000, 0.00000, 10.27625], 

... [1.37715, 0.79510, 5.00000], 

... [0.00000, 3.18039, 5.00000], 

... [0.00000, 0.00000, 7.17625], 

... [1.37715, 2.38529, 7.17625]] 

>>> unitcell = [5.5086, 4.7706, 15.27625] 

>>> atoms = Atoms(positions=pos, 

... symbols=’N2Ru4’, 

... cell=unitcell, 

... pbc=[True,True,False]) 

>>> fa = FixAtoms(mask=[a.symbol == ’Ru’ for a in atoms]) 

>>> fb = FixBondLength(0, 1) 

>>> atoms.set_constraint([fa, fb]) 

When applying more than one constraint they are passed as a list in the set_constraint() method, and they 

will be applied one after the other. 

Important: If wanting to fix the length of more than one bond in the simulation, do not supply a list of 

FixBondLength instances; instead, use a single instance of FixBondLengths. 

7.15. Constraints 141


7.15.10 Making your own constraint class 

A constraint class must have these two methods: 

constraints.adjust_positions(oldpositions, newpositions) 

Adjust the newpositions array inplace. 

constraints.adjust_forces(positions, forces) 

Adjust the forces array inplace. 

A simple example: 


class MyConstraint: 

"""Constrain an atom to move along a given direction only.""" 

def __init__(self, a, direction): 

self.a = a 

self.dir = direction / sqrt(np.dot(direction, direction)) 

def adjust_positions(self, oldpositions, newpositions): 

step = newpositions[self.a] - oldpositions[self.a] 

step = np.dot(step, self.dir) 

newpositions[self.a] = oldpositions[self.a] + step * self.dir 

def adjust_forces(self, positions, forces): 

forces[self.a] = self.dir * np.dot(forces[self.a], self.dir) 

7.15.11 The Filter class 

Constraints can also be applied via filters, which acts as a wrapper around an atoms object. A typical use case will 

look like this: 

------- -------- ---------- 

| | | | | | 

| Atoms |> atoms = Atoms(...) 

>>> filter = Filter(atoms, ...) 

>>> dyn = Dynamics(filter, ...) 

This class hides some of the atoms in an Atoms object. 

class constraints.Filter(atoms, indices=None, mask=None) 

You must supply either the indices of the atoms that should be kept visible or a mask. The mask is a list of 

booleans, one for each atom, being true if the atom should be kept visible. 


>>> from ase import Atoms, Filter 

>>> atoms=Atoms(positions=[[ 0 , 0 , 0], 

... [ 0.773, 0.600, 0], 

... [-0.773, 0.600, 0]], 

... symbols=’OH2’) 

>>> f1 = Filter(atoms, indices=[1, 2]) 

>>> f2 = Filter(atoms, mask=[0, 1, 1]) 

>>> f3 = Filter(atoms, mask=[a.Z == 1 for a in atoms]) 

>>> f1.get_positions() 

[[ 0.773 0.6 0. ] 

[-0.773 0.6 0. ]] 



In all three filters only the hydrogen atoms are made visible. When asking for the positions only the positions of 

the hydrogen atoms are returned. 

7.16 Nudged elastic band 

The Nudged Elastic Band method is a technique for finding transition paths (and corresponding energy barriers) 

between given initial and final states. The method involves constructing a “chain” of “replicas” or “images” of the 

system and relaxing them in a certain way. 

Relevant literature References: 

1. H. Jonsson, G. Mills, and K. W. Jacobsen, in ‘Classical and Quantum Dynamics in Condensed Phase Systems’, 

edited by B. J. Berne, G. Cicotti, and D. F. Coker, World Scientific, 1998 [standard formulation] 

2. ‘Improved Tangent Estimate in the NEB method for Finding Minimum Energy Paths and Saddle Points’, 

Graeme Henkelman and Hannes Jonsson, J. Chem. Phys. 113, 9978 (2000) [improved tangent estimates] 

3. ‘A Climbing-Image NEB Method for Finding Saddle Points and Minimum Energy Paths’, Graeme Henkelman, 

Blas P. Uberuaga and Hannes Jonsson, J. Chem. Phys. 113, 9901 (2000) 

7.16.1 The NEB class 

This module defines one class: 

class ase.neb.NEB(images, k=0.1, climb=False, parallel=False, world=None) 

Nudged elastic band. 

images: list of Atoms objects Images defining path from initial to final state. 

k: float or list of floats Spring constant(s). One number or one for each spring. 

climb: bool Use a climbing image (default is no climbing image). 

parallel: bool Distribute images over processors. 

Example of use, between initial and final state which have been previously saved in A.traj and B.traj: 

from ase import io 


from ase.optimize import MDMin 

# Read initial and final states: 

initial = io.read(’A.traj’) 

final = io.read(’B.traj’) 

# Make a band consisting of 5 images: 


images += [initial.copy() for i in range(3)] 

images += [final] 

neb = NEB(images) 

# Interpolate linearly the potisions of the three middle images: 


# Set calculators: 

for image in images[1:4]: 

image.set_calculator(MyCalculator(...)) 

# Optimize: 

optimizer = MDMin(neb, trajectory=’A2B.traj’) 

optimizer.run(fmax=0.04) 

Be sure to use the copy method (or similar) to create new instances of atoms within the list of images fed to the 

NEB. Do not use something like [initial for i in range(3)], as it will only create references to the original atoms 

object. 

Notice the use of the interpolate() method to get a good initial guess for the path from A to B. 

7.16. Nudged elastic band 143


NEB.interpolate() 

Interpolate path linearly from initial to final state. 

Only the internal images (not the endpoints) need have calculators attached. 

See Also: 

optimize: Information about energy minimization (optimization). 

calculators: How to use calculators. 

Tutorials: 

• Diffusion of gold atom on Al(100) surface (NEB) 

• Dissociation 

• Dissociation 

Note: If there are M images and each image has N atoms, then the NEB object behaves like one big Atoms 

object with MN atoms, so its get_positions() method will return a MN × 3 array. 

7.16.2 Trajectories 

The code: 


optimizer = QuasiNewton(neb, trajectory=’A2B.traj’) 

will write all images to one file. The Trajectory object knows about NEB calculations, so it will write M images 

with N atoms at every iteration and not one big configuration containing MN atoms. 

The result of the latest iteration can now be analysed with this command: ag A2B.traj@-5:. 

For the example above, you can write the images to individual trajectory files like this: 

for i in range(1, 4): 

qn.attach(io.PickleTrajectory(’A2B-%d.traj’ % i, ’w’, images[i])) 

The result of the latest iteration can be analysed like this: 

$ ag A.traj A2B-?.traj B.traj -n -1 

7.16.3 Restarting 

Restart the calculation like this: 

images = io.read(’A2B.traj@-5:’) 

7.16.4 Climbing image 

The “climbing image” variation involves designating a specific image to behave differently to the rest of the chain: 

it feels no spring forces, and the component of the potential force parallel to the chain is reversed, such that it 

moves towards the saddle point. This depends on the adjacent images providing a reasonably good approximation 

of the correct tangent at the location of the climbing image; thus in general the climbing image is not turned on 

until some iterations have been run without it (generally 20% to 50% of the total number of iterations). 

To use the climbing image NEB method, instantiate the NEB object like this: 

neb = NEB(images, climb=True) 



Note: Quasi-Newton methods, such as BFGS, are not well suited for climbing image NEB calculations. FIRE 

have been known to give good results, although convergence is slow. 

7.16.5 Parallelization over images 

Some calculators can parallelize over the images of a NEB calculation. The script will have to be run with an 

MPI-enabled Python interpreter like GPAW‘s gpaw-python. All images exist on all processors, but only some of 

them have a calculator attached: 

from ase.parallel import rank, size 


# Number of internal images: 

n = len(images) - 2 

j = rank * n // size 

for i, image in enumerate(images[1:-1]): 

if i == j: 


Create the NEB object with NEB(images, parallel=True) and let the master processes write the images: 

if rank % (size // n) == 0: 

traj = io.PickleTrajectory(’neb%d.traj’ % j, ’w’, images[1 + j], 

master=True) 

optimizer.attach(traj) 

For a complete example using GPAW, see here. 

7.17 Vibration analysis 

You can calculate the vibrational modes of a an Atoms object in the harmonic approximation using the 

Vibrations. 

class ase.vibrations.Vibrations(atoms, indices=None, name=’vib’, delta=0.01, nfree=2) 

Class for calculating vibrational modes using finite difference. 

The vibrational modes are calculated from a finite difference approximation of the Hessian matrix. 

The summary(), get_energies() and get_frequencies() methods all take an optional method keyword. Use 

method=’Frederiksen’ to use the method described in: 

T. Frederiksen, M. Paulsson, M. Brandbyge, A. P. Jauho: “Inelastic transport theory from firstprinciples: 

methodology and applications for nanoscale devices”, Phys. Rev. B 75, 205413 

(2007) 

atoms: Atoms object The atoms to work on. 

indices: list of int List of indices of atoms to vibrate. Default behavior is to vibrate all atoms. 

name: str Name to use for files. 

delta: float Magnitude of displacements. 

nfree: int Number of displacements per atom and cartesian coordinate, 2 and 4 are supported. Default is 2 

which will displace each atom +delta and -delta for each cartesian coordinate. 

Example: 

7.17. Vibration analysis 145


>>> from ase import Atoms 

>>> from ase.calculators import EMT 

>>> from ase.optimize import BFGS 

>>> from ase.vibrations import Vibrations 

>>> n2 = Atoms(’N2’, [(0, 0, 0), (0, 0, 1.1)], 

... calculator=EMT()) 

>>> BFGS(n2).run(fmax=0.01) 

BFGS: 0 16:01:21 0.440339 3.2518 

BFGS: 1 16:01:21 0.271928 0.8211 

BFGS: 2 16:01:21 0.263278 0.1994 

BFGS: 3 16:01:21 0.262777 0.0088 

>>> vib = Vibrations(n2) 

>>> vib.run() 

Writing vib.eq.pckl 

Writing vib.0x-.pckl 

Writing vib.0x+.pckl 

Writing vib.0y-.pckl 

Writing vib.0y+.pckl 

Writing vib.0z-.pckl 

Writing vib.0z+.pckl 

Writing vib.1x-.pckl 

Writing vib.1x+.pckl 

Writing vib.1y-.pckl 

Writing vib.1y+.pckl 

Writing vib.1z-.pckl 

Writing vib.1z+.pckl 

>>> vib.summary() 

--------------------- 

# meV cm^-1 

--------------------- 

0 0.0 0.0 

1 0.0 0.0 

2 0.0 0.0 

3 2.5 20.4 

4 2.5 20.4 

5 152.6 1230.8 

--------------------- 

Zero-point energy: 0.079 eV 

>>> vib.write_mode(-1) # write last mode to trajectory file 

get_energies(method=’standard’, direction=’central’) 

Get vibration energies in eV. 

get_frequencies(method=’standard’, direction=’central’) 

Get vibration frequencies in cm^-1. 

run() 

Run the vibration calculations. 

This will calculate the forces for 6 displacements per atom +/-x, +/-y, +/-z. Only those calculations 

that are not already done will be started. Be aware that an interrupted calculation may produce an 

empty file (ending with .pckl), which must be deleted before restarting the job. Otherwise the forces 

will not be calculated for that displacement. 

Note that the calculations for the different displacements can be done simultaneously by several independent 

processes. This feature relies on the existence of files and the subsequent creation of the file 

in case it is not found. 

summary(method=’standard’, direction=’central’, freq=None, log=) 

Print a summary of the vibrational frequencies. 

Parameters: 

method [string] Can be ‘standard’(default) or ‘Frederiksen’. 



direction: string Direction for finite differences. Can be one of ‘central’ (default), ‘forward’, ‘backward’. 

freq [numpy array] Optional. Can be used to create a summary on a set of known frequencies. 

log [if specified, write output to a different location than] stdout. Can be an object with a write() 

method or the name of a file to create. 

write_jmol() 

Writes file for viewing of the modes with jmol. 

write_mode(n, kT=0.025852157076770025, nimages=30) 

Write mode to trajectory file. 

name is a string that is prefixed to the names of all the files created. atoms is an Atoms object that is either at a fully 

relaxed ground state or at a saddle point. freeatoms is a list of atom indices for which the vibrational modes will 

be calculated, the rest of the atoms are considered frozen. displacements is a list of displacements, one for each 

free atom that are used in the finite difference method to calculate the Hessian matrix. method is -1 for backward 

differences, 0 for centered differences, and 1 for forward differences. 

Warning: Using the dacapo caculator you must make sure that the symmetry program in dacapo finds the 

same number of symmetries for the displaced configurations in the vibrational modules as found in the ground 

state used as input. This is because the wavefunction is reused from one displacement to the next. One way to 

ensure this is to tell dacapo not to use symmetries. 

This will show op as a python error ‘Frames are not aligned’. This could be the case for other calculators as 

well. 

You can get a NetCDF trajectory corresponding to a specific mode by using: 

>>> mode=0 

>>> vib.create_mode_trajectory(mode=mode,scaling=5) 

This will create a NetCDF trajectory file CO_vib_mode_0.traj, corresponding to the highest frequency mode. 

scaling is an option argument, that will give the amplitude of the mode, default is 10. 

7.18 Phonon calculations 

Module for calculating vibrational normal modes for periodic systems using the so-called small displacement 

method (see e.g. [Alfe]). So far, space-group symmetries are not exploited to reduce the number of atomic 

displacements that must be calculated and subsequent symmetrization of the force constants. 

For polar materials the dynamical matrix at the zone center acquires a non-analytical contribution that accounts 

for the LO-TO splitting. This contribution requires additional functionality to evaluate and is not included in the 

present implementation. Its implementation in conjunction with the small displacement method is described in 

[Wang]. 

7.19 Example 

Simple example showing how to calculate the phonon dispersion for bulk aluminum using a 7x7x7 supercell 

within effective medium theory: 

from ase.structure import bulk 


from ase.dft.kpoints import ibz_points, get_bandpath 

from ase.phonons import Phonons 

# Setup crystal and EMT calculator 

atoms = bulk(’Al’, ’fcc’, a=4.05) 

calc = EMT() 

7.18. Phonon calculations 147


# Phonon calculator 

N = 7 

ph = Phonons(atoms, calc, supercell=(N, N, N), delta=0.05) 

ph.run() 

# Read forces and assemble the dynamical matrix 

ph.read(acoustic=True) 

# High-symmetry points in the Brillouin zone 

points = ibz_points[’fcc’] 

G = points[’Gamma’] 

X = points[’X’] 

W = points[’W’] 

K = points[’K’] 

L = points[’L’] 

U = points[’U’] 

point_names = [’$\Gamma$’, ’X’, ’U’, ’L’, ’$\Gamma$’, ’K’] 

path = [G, X, U, L, G, K] 

# Band structure in meV 

path_kc, q, Q = get_bandpath(path, atoms.cell, 100) 

omega_kn = 1000 * ph.band_structure(path_kc) 

# Calculate phonon DOS 

omega_e, dos_e = ph.dos(kpts=(50, 50, 50), npts=5000, delta=5e-4) 

omega_e *= 1000 

# Plot the band structure and DOS 

import pylab as plt 

plt.figure(1, (8, 6)) 

plt.axes([.1, .07, .67, .85]) 

for n in range(len(omega_kn[0])): 

omega_n = omega_kn[:, n] 

plt.plot(q, omega_n, ’k-’, lw=2) 

plt.xticks(Q, point_names, fontsize=18) 

plt.yticks(fontsize=18) 

plt.xlim(q[0], q[-1]) 

plt.ylabel("Frequency ($\mathrm{meV}$)", fontsize=22) 

plt.grid(’on’) 

plt.axes([.8, .07, .17, .85]) 

plt.fill_between(dos_e, omega_e, y2=0, color=’lightgrey’, edgecolor=’k’, lw=1) 

plt.ylim(0, 35) 

plt.xticks([], []) 

plt.yticks([], []) 

plt.xlabel("DOS", fontsize=18) 

plt.show() 


Mode inspection using ag: 


# Write modes for specific q-vector to trajectory files 

ph.write_modes([l/2 for l in L], branches=[2], repeat=(8, 8, 8), kT=3e-4) 

7.19. Example 149


7.20 Infrared intensities 

InfraRed is an extension of Vibrations, in addition to the vibrational modes, also the infrared intensities of 

the modes are calculated for an Atoms object. 

class ase.infrared.InfraRed(atoms, indices=None, name=’ir’, delta=0.01, nfree=2, directions=None) 

Class for calculating vibrational modes and infrared intensities using finite difference. 

The vibrational modes are calculated from a finite difference approximation of the Dynamical matrix and 

the IR intensities from a finite difference approximation of the gradient of the dipole moment. The method 

is described in: 

D. Porezag, M. R. Pederson: “Infrared intensities and Raman-scattering activities within densityfunctional 

theory”, Phys. Rev. B 54, 7830 (1996) 

The calculator object (calc) linked to the Atoms object (atoms) must have the attribute: 

>>> calc.get_dipole_moment(atoms) 

In addition to the methods included in the Vibrations class the InfraRed class introduces 

two new methods; get_spectrum() and write_spectra(). The summary(), get_energies(), 

get_frequencies(), get_spectrum() and write_spectra() methods all take an optional method keyword. Use 

method=’Frederiksen’ to use the method described in: 

T. Frederiksen, M. Paulsson, M. Brandbyge, A. P. Jauho: “Inelastic transport theory from firstprinciples: 

methodology and applications for nanoscale devices”, Phys. Rev. B 75, 205413 

(2007) 

atoms: Atoms object The atoms to work on. 

indices: list of int List of indices of atoms to vibrate. Default behavior is to vibrate all atoms. 

name: str Name to use for files. 

delta: float Magnitude of displacements. 

nfree: int Number of displacements per degree of freedom, 2 or 4 are supported. Default is 2 which will 

displace each atom +delta and -delta in each cartesian direction. 

directions: list of int Cartesian coordinates to calculate the gradient of the dipole moment in. For example 

directions = 2 only dipole moment in the z-direction will be considered, whereas for directions = [0, 

1] only the dipole moment in the xy-plane will be considered. Default behavior is to use the dipole 

moment in all directions. 

Example: 


>>> from ase.calculators.vasp import Vasp 

>>> from ase.infrared import InfraRed 

>>> water = read(’water.traj’) # read pre-relaxed structure of water molecule 

>>> calc = Vasp(prec=’Accurate’, 

... ediff=1E-8, 

... isym=0, 

... idipol=4, # calculate the total dipole moment 

... dipol=water.get_center_of_mass(scaled=True), 

... ldipol=True) 

>>> water.set_calculator(calc) 

>>> ir = InfraRed(water) 

>>> ir.run() 

>>> ir.summary() 

------------------------------------- 

Mode Frequency Intensity 

# meV cm^-1 (D/Å)^2 amu^-1 

------------------------------------- 


0 16.9i 136.2i 1.6108 

1 10.5i 84.9i 2.1682 

2 5.1i 41.1i 1.7327 

3 0.3i 2.2i 0.0080 

4 2.4 19.0 0.1186 

5 15.3 123.5 1.4956 

6 195.5 1576.7 1.6437 

7 458.9 3701.3 0.0284 

8 473.0 3814.6 1.1812 

------------------------------------- 

Zero-point energy: 0.573 eV 

Static dipole moment: 1.833 D 

Maximum force on atom in ‘equilibrium‘: 0.0026 eV/Å 


This interface now also works for calculator ‘siesta’, (added get_dipole_moment for siesta). 

Example: 

>>> #!/usr/bin/env python 


>>> from ase.calculators.siesta import Siesta 

>>> from ase.infrared import InfraRed 

>>> bud = read(’bud1.xyz’) 

>>> calc = Siesta(label=’bud’, 

... meshcutoff=250 * Ry, 

... basis=’DZP’, 

... kpts=[1, 1, 1]) 

>>> calc.set_fdf(’DM.MixingWeight’, 0.08) 

>>> calc.set_fdf(’DM.NumberPulay’, 3) 

>>> calc.set_fdf(’DM.NumberKick’, 20) 

>>> calc.set_fdf(’DM.KickMixingWeight’, 0.15) 

>>> calc.set_fdf(’SolutionMethod’, ’Diagon’) 

>>> calc.set_fdf(’MaxSCFIterations’, 500) 

>>> calc.set_fdf(’PAO.BasisType’, ’split’) 

>>> #50 meV = 0.003674931 * Ry 

>>> calc.set_fdf(’PAO.EnergyShift’, 0.003674931 * Ry ) 

>>> calc.set_fdf(’LatticeConstant’, 1.000000 * Ang) 

>>> calc.set_fdf(’WriteCoorXmol’, ’T’) 

>>> bud.set_calculator(calc) 

>>> ir = InfraRed(bud) 

>>> ir.run() 

>>> ir.summary() 

get_spectrum(start=800, end=4000, npts=None, width=4, type=’Gaussian’, 

method=’standard’, direction=’central’, intensity_unit=’(D/A)2/amu’, normalize=False) 

Get infrared spectrum. 

The method returns wavenumbers in cm^-1 with corresponding absolute infrared intensity. Start and 

end point, and width of the Gaussian/Lorentzian should be given in cm^-1. normalize=True ensures 

the integral over the peaks to give the intensity. 

write_spectra(out=’ir-spectra.dat’, start=800, end=4000, npts=None, width=10, 

type=’Gaussian’, method=’standard’, direction=’central’, intensity_unit=’(D/A)2/amu’, 

normalize=False) 

Write out infrared spectrum to file. 

First column is the wavenumber in cm^-1, the second column the absolute infrared intensities, and the 

7.20. Infrared intensities 151


third column the absorbance scaled so that data runs from 1 to 0. Start and end point, and width of the 

Gaussian/Lorentzian should be given in cm^-1. 

7.21 Molecular dynamics 

Typical computer simulations involve moving the atoms around, either to optimize a structure (energy minimization) 

or to do molecular dynamics. This chapter discusses molecular dynamics, energy minimization algorithms 

will be discussed in the optimize section. 

A molecular dynamics object will operate on the atoms by moving them according to their forces - it integrates 

Newton’s second law numerically. A typical molecular dynamics simulation will use the Velocity Verlet dynamics. 

You create the VelocityVerlet object, giving it the atoms and a time step, and then you perform dynamics 

by calling its run() method: 

dyn = VelocityVerlet(atoms, 5.0 * units.fs) 

dyn.run(1000) # take 1000 steps 

A number of different algorithms can be used to perform molecular dynamics, with slightly different results. 

7.21.1 Choosing the time step 

All the dynamics objects need a time step. Choosing it too small will waste computer time, choosing it too large 

will make the dynamics unstable, typically the energy increases dramatically (the system “blows up”). If the time 

step is only a little to large, the lack of energy conservation is most obvious in Velocity Verlet dynamics, where 

energy should otherwise be conserved. 

Experience has shown that 5 femtoseconds is a good choice for most metallic systems. Systems with light atoms 

(e.g. hydrogen) and/or with strong bonds (carbon) will need a smaller time step. 

All the dynamics objects documented here are sufficiently related to have the same optimal time step. 

7.21.2 File output 

The time evolution of the system can be saved in a trajectory file, by creating a trajectory object, and attaching it 

to the dynamics object. This is documented in the module ase.io.trajectory. 

Unlike the geometry optimization classes, the molecular dynamics classes do not support giving a trajectory file 

name in the constructor. Instead the trajectory must be attached explicitly to the dynamics, and it is stongly 

recommended to use the optional interval argument, so every time step is not written to the file. 

7.21.3 Logging 

A logging mechanism is provided, printing time; total, potential and kinetic energy; and temperature (calculated 

from the kinetic energy). It is enabled by giving the logfile argument when the dynamics object is created, 

logfile may be an open file, a filename or the string ‘-‘ meaning standard output. Per default, a line is printed 

for each timestep, specifying the loginterval argument will chance this to a more reasonable frequency. 

The logging can be customized by explicitly attaching a ase.md.MDLogger object to the dynamics: 

from ase.md import MDLogger 

dyn = VelocityVerlet(atoms, dt=2*ase.units.fs) 

dyn.attach(MDLogger(dyn, atoms, ’md.log’, header=False, stress=False, 

peratom=True, mode="a"), interval=1000) 

This example will skip the header line and write energies per atom instead of total energies. The parameters are 


header: Print a header line defining the columns. 

stress: Print the six components of the stress tensor. 

peratom: Print energy per atom instead of total energy. 

mode: If ‘a’, append to existing file, if ‘w’ overwrite existing file. 


Despite appearances, attaching a logger like this does not create a cyclic reference to the dynamics. 

Note: If building your own logging class, be sure not to attach the dynamics object directly to the logging object. 

Instead, create a weak reference using the proxy method of the weakref package. See the ase.md.MDLogger 

source code for an example. (If this is not done, a cyclic reference may be created which can cause certain 

calculators, such as Jacapo, to not terminate correctly.) 

7.21.4 Constant NVE simulations (the microcanonical ensemble) 

Newton’s second law preserves the total energy of the system, and a straightforward integration of Newton’s 

second law therefore leads to simulations preserving the total energy of the system (E), the number of atoms (N) 

and the volume of the system (V). The most appropriate algorithm for doing this is velocity Verlet dynamics, since 

it gives very good long-term stability of the total energy even with quite large time steps. Fancier algorithms such 

as Runge-Kutta may give very good short-term energy preservation, but at the price of a slow drift in energy over 

longer timescales, causing trouble for long simulations. 

In a typical NVE simulation, the temperature will remain approximately constant, but if significant structural 

changes occurs they may result in temperature changes. If external work is done on the system, the temperature is 

likely to rise significantly. 

Velocity Verlet dynamics 

class md.verlet.VelocityVerlet(atoms, timestep) 

VelocityVerlet is the only dynamics implementing the NVE ensemble. It requires two arguments, the atoms 

and the time step. Choosing a too large time step will immediately be obvious, as the energy will increase with 

time, often very rapidly. 

Example: See the tutorial Molecular dynamics. 

7.21.5 Constant NVT simulations (the canonical ensemble) 

Since Newton’s second law conserves energy and not temperature, simulations at constant temperature will somehow 

involve coupling the system to a heat bath. This cannot help being somewhat artificial. Two different approaches 

are possible within ASE. In Langevin dynamics, each atom is coupled to a heat bath through a fluctuating 

force and a friction term. In Nosé-Hoover dynamics, a term representing the heat bath through a single degree of 

freedom is introduced into the Hamiltonian. 

Langevin dynamics 

class md.langevin.Langevin(atoms, timestep, temperature, friction) 

The Langevin class implements Langevin dynamics, where a (small) friction term and a fluctuating force are added 

to Newton’s second law which is then integrated numerically. The temperature of the heat bath and magnitude of 

the friction is specified by the user, the amplitude of the fluctuating force is then calculated to give that temperature. 

This procedure has some physical justification: in a real metal the atoms are (weakly) coupled to the electron gas, 

and the electron gas therefore acts like a heat bath for the atoms. If heat is produced locally, the atoms locally 

get a temperature that is higher than the temperature of the electrons, heat is transferred to the electrons and then 

rapidly transported away by them. A Langevin equation is probably a reasonable model for this process. 

7.21. Molecular dynamics 153


A disadvantage of using Langevin dynamics is that if significant heat is produced in the simulation, then the 

temperature will stabilize at a value higher than the specified temperature of the heat bath, since a temperature 

difference between the system and the heat bath is necessary to get a finite heat flow. Another disadvantage is that 

the fluctuating force is stochastic in nature, so repeating the simulation will not give exactly the same trajectory. 

When the Langevin object is created, you must specify a time step, a temperature (in energy units) and a friction. 

Typical values for the friction are 0.01-0.02 atomic units. 

# Room temperature simulation 

dyn = Langevin(atoms, 5 * units.fs, units.kB * 300, 0.002) 

Both the friction and the temperature can be replaced with arrays giving per-atom values. This is mostly useful 

for the friction, where one can choose a rather high friction near the boundaries, and set it to zero in the part of the 

system where the phenomenon being studied is located. 

Nosé-Hoover dynamics 

In Nosé-Hoover dynamics, an extra term is added to the Hamiltonian representing the coupling to the heat bath. 

From a pragmatic point of view one can regard Nosé-Hoover dynamics as adding a friction term to Newton’s 

second law, but dynamically changing the friction coefficient to move the system towards the desired temperature. 

Typically the “friction coefficient” will fluctuate around zero. 

Nosé-Hoover dynamics is not implemented as a separate class, but is a special case of NPT dynamics. 

Berendsen NVT dynamics 

class md.nvtberendsen.NVTBerendsen(atoms, timestep, temperature, taut, fixcm) 

In Berendsen NVT simulations the velocities are scaled to achieve the desired temperature. The speed of the 

scaling is determined by the parameter taut. 

This method does not result proper NVT sampling but it usually is sufficiently good in practise (with large taut). 

For discussion see the gromacs manual at www.gromacs.org. 

atoms: The list of atoms. 

timestep: The time step. 

temperature: The desired temperature, in Kelvin. 

taut: Time constant for Berendsen temperature coupling. 

fixcm: If True, the position and momentum of the center of mass is kept unperturbed. Default: True. 

# Room temperature simulation (300K, 0.1 fs time step) 

dyn = NVTBerendsen(atoms, 0.1 * units.fs, 300, taut=0.5*1000*units.fs) 

7.21.6 Constant NPT simulations (the isothermal-isobaric ensemble) 

class md.npt.NPT(atoms, timestep, temperature, externalstress, ttime, pfactor, mask=None) 

Dynamics with constant pressure (or optionally, constant stress) and constant temperature (NPT or N,stress,T 

ensemble). It uses the combination of Nosé-Hoover and Parrinello-Rahman dynamics proposed by Melchionna et 

al. [1] and later modified by Melchionna [2]. The differential equations are integrated using a centered difference 

method [3]. Details of the implementation are available in the document XXX NPTdynamics.tex, distributed with 

the module. 

The dynamics object is called with the following parameters: 

atoms: The atoms object. 

timestep: The timestep in units matching eV, Å, u. Use the units.fs constant. 

temperature: The desired temperature in eV. 



externalstress: The external stress in eV/Å^3. Either a symmetric 3x3 tensor, a 6-vector representing the same, or 

a scalar representing the pressure. Note that the stress is positive in tension whereas the pressure is positive 

in compression: giving a scalar p is equivalent to giving the tensor (-p. -p, -p, 0, 0, 0). 

ttime: Characteristic timescale of the thermostat. Set to None to disable the thermostat. 

pfactor: A constant in the barostat differential equation. If a characteristic barostat timescale of ptime is desired, 

set pfactor to ptime^2 * B (where B is the Bulk Modulus). Set to None to disable the barostat. Typical 

metallic bulk moduli are of the order of 100 GPa or 0.6 eV/Å^3. 

mask=None: Optional argument. A tuple of three integers (0 or 1), indicating if the system can change size along 

the three Cartesian axes. Set to (1,1,1) or None to allow a fully flexible computational box. Set to (1,1,0) to 

disallow elongations along the z-axis etc. 

Useful parameter values: 

• The same timestep can be used as in Verlet dynamics, i.e. 5 fs is fine for bulk copper. 

• The ttime and pfactor are quite critical[4], too small values may cause instabilites and/or wrong fluctuations 

in T / p. Too large values cause an oscillation which is slow to die. Good values for the characteristic 

times seem to be 25 fs for ttime, and 75 fs for ptime (used to calculate pfactor), at least for bulk copper 

with 15000-200000 atoms. But this is not well tested, it is IMPORTANT to monitor the temperature and 

stress/pressure fluctuations. 

It has the following methods: 

NPT.run(n): 

Perform n timesteps. 

NPT.initialize(): 

Estimates the dynamic variables for time=-1 to start the algorithm. This is automatically called before the 

first timestep. 

NPT.set_stress(): 

Set the external stress. Use with care. It is preferable to set the right value when creating the object. 

NPT.set_mask(): 

Change the mask. Use with care, as you may “freeze” a fluctuation in the strain rate. 

NPT.set_strainrate(eps): 

Set the strain rate. eps must be an upper-triangular matrix. If you set a strain rate along a direction that is 

“masked out” (see set_mask), the strain rate along that direction will be maintained constantly. 

NPT.get_gibbs_free_energy(): 

Gibbs free energy is supposed to be preserved by this dynamics. This is mainly intended as a diagnostic 

tool. 

References: 

[1] S. Melchionna, G. Ciccotti and B. L. Holian, Molecular Physics 78, p. 533 (1993). 

[2] S. Melchionna, Physical Review E 61, p. 6165 (2000). 

[3] B. L. Holian, A. J. De Groot, W. G. Hoover, and C. G. Hoover, Physical Review A 41, p. 4552 (1990). 

[4] F. D. Di Tolla and M. Ronchetti, Physical Review E 48, p. 1726 (1993). 

See Also: 

The API documentation: md 

Berendsen NPT dynamics 

class md.nptberendsen.NPTBerendsen(atoms, timestep, temperature, taut, fixcm, pressure, taup, 

compressibility) 

7.21. Molecular dynamics 155


In Berendsen NPT simulations the velocities are scaled to achieve the desired temperature. The speed of the 

scaling is determined by the parameter taut. 

The atom positions and the simulation cell are scaled in order to achieve the desired pressure. 

This method does not result proper NPT sampling but it usually is sufficiently good in practise (with large taut and 

taup). For discussion see the gromacs manual at www.gromacs.org. or amber at ambermd.org 

atoms: The list of atoms. 

timestep: The time step. 

temperature: The desired temperature, in Kelvin. 

taut: Time constant for Berendsen temperature coupling. 

fixcm: If True, the position and momentum of the center of mass is kept unperturbed. Default: True. 

pressure: The desired pressure, in bar (1 bar = 1e5 Pa). 

taup: Time constant for Berendsen pressure coupling. 

compressibility: The compressibility of the material, water 4.57E-5 bar-1, in bar-1 

# Room temperature simulation (300K, 0.1 fs time step, atmospheric pressure) 

dyn = NPTBerendsen(atoms, timestep=0.1*units.fs, temperature=300, 

taut=0.1*1000*units.fs, pressure = 1.01325, 

taup=1.0*1000*units.fs, compressibility=4.57e-5) 

7.22 Density Functional Theory 

7.22.1 Brillouin zone sampling 

The k-points are always given relative to the basis vectors of the reciprocal unit cell. 

Monkhorst-Pack 

ase.dft.kpoints.monkhorst_pack(size) 

Construct a uniform sampling of k-space of given size. 

The k-points are given as [MonkhorstPack]: 

� 

i=1,2,3 

2ni − Ni − 1 

bi, 

2Ni 

where ni = 1, 2, ..., Ni, size = (N1, N2, N3) and the bi‘s are reciprocal lattice vectors. 

ase.dft.kpoints.get_monkhorst_pack_size_and_offset(kpts) 

Find Monkhorst-Pack size and offset. 

Example: 

Returns (size, offset), where: 

kpts = monkhorst_pack(size) + offset. 

The set of k-points must not have been symmetry reduced. 

>>> from ase.dft.kpoints import * 

>>> monkhorst_pack((4, 1, 1)) 

array([[-0.375, 0. , 0. ], 

[-0.125, 0. , 0. ], 

[ 0.125, 0. , 0. ], 

[ 0.375, 0. , 0. ]]) 


get_monkhorst_pack_size_and_offset([[0, 0, 0]]) 

(array([1, 1, 1]), array([ 0., 0., 0.])) 

Chadi-Cohen 

Predefined sets of k-points: 

dft.kpoints.cc6_1x1 


dft.kpoints.cc18_sq3xsq3 






Naming convention: cc18_sq3xsq3 is 18 k-points for a sq(3)xsq(3) cell. 

Try this: 


>>> import pylab as plt 

>>> from ase.dft.kpoints import cc162_1x1 

>>> B = [(1, 0, 0), (-0.5, 3**0.5 / 2, 0), (0, 0, 1)] 

>>> k = np.dot(cc162_1x1, B) 

>>> plt.plot(k[:, 0], k[:, 1], ’o’) 

[] 

>>> p.show() 


7.22. Density Functional Theory 157


7.22.2 Maximally localized Wannier functions 

This page describes how to construct the Wannier orbitals using the class Wannier. The page is organized as 

follows: 

• Introduction: A short summary of the basic theory. 

• The Wannier class : A description of how the Wannier class is used, and the methods defined within. 

Introduction 

The point of Wannier functions is the transform the extended Bloch eigenstates of a DFT calculation, into a smaller 

set of states designed to facilitate the analysis of e.g. chemical bonding. This is achived by designing the Wannier 

functions to be localized in real space instead of energy (which would be the eigen states). 

The standard Wannier transformation is a unitary rotation of the Bloch states. This implies that the Wannier 

functions (WF) span the same Hilbert space as the Bloch states, i.e. they have the same eigenvalue spectrum, 

and the original Bloch states can all be exactly reproduced from a linear combination of the WF. For maximally 

localized Wannier functions (MLWF), the unitary transformation is chosen such that the spread of the resulting 

WF is minimized. 

The standard choice is to make a unitary transformation of the occupied bands only, thus resulting in as many WF 

as there are occupied bands. If you make a rotation using more bands, the localization will be improved, but the 

number of wannier functions increase, thus making orbital based analysis harder. 

The class defined here allows for construction of partly occupied MLWF. In this scheme the transformation is still 

a unitary rotation for the lowest states (the fixed space), but it uses a dynamically optimized linear combination 

of the remaining orbitals (the active space) to improve localization. This implies that e.g. the eigenvalues of 

the Bloch states contained in the fixed space can be exactly reproduced by the resulting WF, whereas the largest 

eigenvalues of the WF will not necessarily correspond to any “real” eigenvalues (this is irrelevant, as the fixed 

space is usually chosen large enough, i.e. high enough above the fermilevel, that the remaining DFT eigenvalues 

are meaningless anyway). 

For the theory behind this method see the paper “Partly Occupied Wannier Functions” Thygesen, Hansen and 

Jacobsen, Phys. Rev. Lett, Vol. 94, 26405 (2005). 

The Wannier class 

Usual invocation: 


wan = Wannier(nwannier=18, calc=GPAW(’save.gpw’), fixedstates=15) 

wan.localize() # Optimize rotation to give maximal localization 

wan.save(’file.pickle’) # Save localization and rotation matrix 

# Re-load using saved wannier data 

wan = Wannier(nwannier=18, calc=calc, fixedstates=15, file=’file.pickle’) 

# Write a cube file 

wan.write_cube(index=5, fname=’wannierfunction5.cube’) 

For examples of how to use the Wannier class, see the Wannier tutorial. 

class ase.dft.wannier.Wannier(nwannier, calc, file=None, nbands=None, fixedenergy=None, 

fixedstates=None, spin=0, initialwannier=’random’, seed=None, 

verbose=False) 

Maximally localized Wannier Functions 

Find the set of maximally localized Wannier functions using the spread functional of Marzari and Vanderbilt 

(PRB 56, 1997 page 12847). 

Required arguments: 



nwannier: The number of Wannier functions you wish to construct. This must be at least 

half the number of electrons in the system and at most equal to the number of bands in the 

calculation. 

calc: A converged DFT calculator class. If file arg. is not provided, the calculator must 

provide the method get_wannier_localization_matrix, and contain the wavefunctions 

(save files with only the density is not enough). If the localization matrix is read 

from file, this is not needed, unless get_function or write_cube is called. 

Optional arguments: 

nbands: Bands to include in localization. The number of bands considered by Wannier can 

be smaller than the number of bands in the calculator. This is useful if the highest bands of 

the DFT calculation are not well converged. 

spin: The spin channel to be considered. The Wannier code treats each spin channel independently. 

fixedenergy / fixedstates: Fixed part of Heilbert space. Determine the fixed part of 

Hilbert space by either a maximal energy or a number of bands (possibly a list for multiple 

k-points). Default is None meaning that the number of fixed states is equated to nwannier. 

file: Read localization and rotation matrices from this file. 

initialwannier: Initial guess for Wannier rotation matrix. Can be ‘bloch’ to start from 

the Bloch states, ‘random’ to be randomized, or a list passed to calc.get_initial_wannier. 

seed: Seed for random initialwannier. 

verbose: True / False level of verbosity. 

get_centers(scaled=False) 

Calculate the Wannier centers 

pos = L / 2pi * phase(diag(Z)) 

get_function(index, repeat=None) 

Get Wannier function on grid. 

Returns an array with the funcion values of the indicated Wannier function on a grid with the size of 

the repeated unit cell. 

For a calculation using k-points the relevant unit cell for eg. visualization of the Wannier orbitals is 

not the original unit cell, but rather a larger unit cell defined by repeating the original unit cell by the 

number of k-points in each direction. Note that for a Γ-point calculation the large unit cell coinsides 

with the original unit cell. The large unitcell also defines the periodicity of the Wannier orbitals. 

index can be either a single WF or a coordinate vector in terms of the WFs. 

get_functional_value() 

Calculate the value of the spread functional. 

Tr[|ZI|^2]=sum(I)sum(n) w_i|Z_(i)_nn|^2, 

where w_i are weights. 

get_hamiltonian(k=0) 

Get Hamiltonian at existing k-vector of index k 

dag 

H(k) = V diag(eps ) V 

k k k 

get_hamiltonian_kpoint(kpt_c) 

Get Hamiltonian at some new arbitrary k-vector 



_ ik.R 

H(k) = >_ e H(R) 

R 

Warning: This method moves all Wannier functions to cell (0, 0, 0) 

get_hopping(R) 

Returns the matrix H(R)_nm=. 

1 _ -ik.R 

H(R) = = --- >_ e H(k) 

Nk k 

where R is the cell-distance (in units of the basis vectors of the small cell) and n,m are indices of the 

Wannier functions. 

get_pdos(w, energies, width) 

Projected density of states (PDOS). 

Returns the (PDOS) for Wannier function w. The calculation is performed over the energy grid specified 

in energies. The PDOS is produced as a sum of Gaussians centered at the points of the energy 

grid and with the specified width. 

get_radii() 

Calculate the spread of the Wannier functions. 

-- / L \ 2 2 

radius**2 = - > | --- | ln |Z| 

--d \ 2pi / 

initialize(file=None, initialwannier=’random’, seed=None) 

Re-initialize current rotation matrix. 

Keywords are identical to those of the constructor. 

localize(step=0.25, tolerance=1e-08, updaterot=True, updatecoeff=True) 

Optimize rotation to give maximal localization 

max_spread(directions=[0, 1, 2]) 

Returns the index of the most delocalized Wannier function together with the value of the spread 

functional 

save(file) 

Save information on localization and rotation matrices to file. 

translate(w, R) 

Translate the w’th Wannier function 

The distance vector R = [n1, n2, n3], is in units of the basis vectors of the small cell. 

translate_all_to_cell(cell=[0, 0, 0]) 

Translate all Wannier functions to specified cell. 

Move all Wannier orbitals to a specific unit cell. There exists an arbitrariness in the positions of the 

Wannier orbitals relative to the unit cell. This method can move all orbitals to the unit cell specified 

by cell. For a Γ-point calculation, this has no effect. For a k-point calculation the periodicity of 

the orbitals are given by the large unit cell defined by repeating the original unitcell by the number 

of k-points in each direction. In this case it is usefull to move the orbitals away from the boundaries 

of the large cell before plotting them. For a bulk calculation with, say 10x10x10 k points, one could 

move the orbitals to the cell [2,2,2]. In this way the pbc boundary conditions will not be noticed. 

translate_to_cell(w, cell) 

Translate the w’th Wannier function to specified cell 

write_cube(index, fname, repeat=None, real=True) 

Dump specified Wannier function to a cube file 


In Dacapo, the inialwannier keyword can be a list as described below: 


Setup an initial set of Wannier orbitals. initialwannier can set up a starting guess for the Wannier 

functions. This is important to speed up convergence in particular for large systems For transition 

elements with d electrons you will always find 5 highly localized d-orbitals centered at the atom. 

Placing 5 d-like orbitals with a radius of 0.4 Angstroms and center at atom no. 7, and 3 p-like orbitals 

with a radius of 0.4 Angstroms and center at atom no. 27 looks like this: 

initialwannier = [[[7],2,0.4],[[27],1,0.4]] 

Placing only the l=2, m=-2 and m=-1 orbitals at atom no. 7 looks like this: 

initialwannier = [[[7],2,-2,0.4],[[7],2,-1,0.4]] 

I.e. if you do not specify the m quantum number all allowed values are used. Instead of placing an 

orbital at an atom, you can place it at a specified position. For example the following: 

initialwannier = [[[0.5,0.5,0.5],0,0.5]] 

places an s orbital with radius 0.5 Angstroms at the position (0.5, 0.5, 0.5) in scaled coordinates of 

the unit cell. 

Note: For calculations using k-points, make sure that the Γ-point is included in the k-point grid. The Wannier 

module does not support k-point reduction by symmetry, so you must use the usesymm=False keyword in the 

calc, and shift all k-points by a small amount (but not less than 2e-5 in) in e.g. the x direction, before performing 

the calculation. If this is not done the symmetry program will still use time-reversal symmetry to reduce the 

number of k-points by a factor 2. The shift can be performed like this: 


kpts = monkhorst_pack((15, 9, 9)) + [2e-5, 0, 0] 

7.22.3 Density of states 

Example: 

calc = ... 

dos = DOS(calc, width=0.2) 

d = dos.get_dos() 

e = dos.get_energies() 

You can plot the result like this: 

import pylab as plt 

plt.plot(e, d) 

plt.xlabel(’energy [eV]’) 

plt.ylabel(’DOS’) 

plt.show() 



Calculations involving moments of a DOS distribution may be facilitated by the use of 

get_distribution_moment() method, as in the following example: 

from ase.dft import get_distribution_moment 

volume = get_distribution_moment(e,d) 

center, width = get_distribution_moment(e,d,(1,2)) 

More details 

class ase.dft.dos.DOS(calc, width=0.1, window=None, npts=201) 

Electronic Density Of States object. 

calc: calculator object Any ASE compliant calculator object. 

width: float Width of guassian smearing. 

window: tuple of two float Use window=(emin, emax). If not specified, a window big enough to 

hold all the eigenvalues will be used. 

npts: int Number of points. 

get_energies() 

Return the array of energies used to sample the DOS. The energies are reported relative to the Fermi 

level. 

get_dos(spin=None) 

Get array of DOS values. 

The spin argument can be 0 or 1 (spin up or down) - if not specified, the total DOS is returned. 

ase.dft.get_distribution_moment(x, y, order=0) 

Return the moment of nth order of distribution. 

1st and 2nd order moments of a band correspond to the band’s center and width respectively. 

For integration, the trapezoid rule is used. 

XXX This page needs more work! 


7.22.4 STMTool 

The STMTool class generates Tersoff-Hamann STM topographs. 


Here is how you could make a STM picture from the GPAW code, assuming you have allready generated the the 

Al100.gpw GPAW restart file, (see the STM tutorial for a full description): 

>>> from ASE.Utilities.ElectronicStates import ElectronicStates 

>>> from ASE.Utilities.STMTool import STMTool 

>>> from ASE.Visualization.VTK import VTKPlotSTM 

>>> loe = ElectronicStates(filename = ’Al100.gpw’) 

>>> stm = STMTool(loe,contourvalue=1.0e-4, channel="s", 

... normalaxis=2, smoothfactor=0.1) # available channels: s,px,py,pz 

>>> stmplot = VTKPlotSTM(stm) 

>>> stmplot.set_color_range((3.325,3.55)) # from surface span color range 

>>> stmplot.render() # updates picture 

From the planewave code dacapo, the dacapo codes own version of the ElectronicStates class must be used: 

>>> from Dacapo.ElectronicStates import ElectronicStates 

>>> from ASE.Utilities.STMTool import STMTool 

>>> from ASE.Visualization.VTK import VTKPlotSTM 

>>> loe = ElectronicStates(filename=’Al100.nc’) 

From this point the code is identical to the example above. 

The list of keywords for the STMTool object is: 

listofeigenstates The ElectronicStates object holding information about each eigenstate of the 

slab. 

contourvalue The density of states at the Fermi level for which the topograph is generated. This argument is 

mandatory, as no universal (simple) default is natural. Often used values are [1.0e-6 - 1.0e-3], but is very 

system dependent. 

channel Selects whether the topograph is generated by the value or gradient isosurface of the Fermi level DOS. 

This adjusts for the orbital character of the DOS of the actual STM tip in the probing energy window, i.e. 

the STM tip states that couples to the substrate. Available options are “s”, “px”, “py” and “pz”. Default is 

“s”. 

normalaxis The surface normal direction, (0,1,2) for (x,y,z) respectively. normalaxis = 2 is default. 

smoothfactor The thermal convolution applied to the slab states. It is necessary to apply this due to finite 

k-point sampling. 

7.22.5 STM linescans 

The class ST MLineScan can be used to simulate an STM linescan. It must be initialized with an instance of the 

STMTool class. 

Note that the linescans are limited to be along one of the axis of the unit cell. The origin of the linescan can only 

assume discrete values corresponding to the FFT grid. 

The class is used like: 

linescan = STMLineScan(stm,fftnumber=12,axis=1) 

See more details in the linescansection of the ST Mtutorial. 



7.22.6 Bader Analysis 

Henkelman et. al have implemented a fast and robust algorithm for calculating the electronic charges on individual 

atoms in molecules or crystals, based on the Bader partitioning scheme [Bader]. In that method, the 

analysis is based purely on the electron density. The partitioning of the density is determined according to its 

zero-flux surfaces. Details of their implementation can be found in [Tang]. The program is freely available at 

http://theory.cm.utexas.edu/henkelman/research/bader/ where you will also find a description of the method. 

The algorithm is very well suited for large solid state physical systems, as well as large biomolecular systems. 

The computational time depends only on the size of the 3D grid used to represent the electron density, and scales 

linearly with the total number of grid points. As the accuracy of the method depends on the grid spacing, it is 

recommended to check for convergnce in this parameter (which should usually by smaller than the default value). 

The program takes cube input files. It does not support units, and assumes atomic units for the density (Bohr^-3). 

All ase dft calculators have a get_pseudo_density method, which can be used to get the density. A simple 

python script for making a cube file, ready for the Bader program, could be: 


>>> density = calc.get_pseudo_density() * Bohr**3 

>>> write(’filename.cube’, atoms, data=density) 

Some calculators (e.g. gpaw) also have a method called get_all_electron_density, in which case this is 

preferable to get_pseudo_density. 

Note that it is strongly recommended to use version 0.26b or higher of the program, and the examples below refer 

to this version. 

Example: The water molecule 

The following example shows how to do Bader analysis for a water molecule. 

First do a ground state calculation, and save the density as a cube file: 


from gpaw import * 

atoms = molecule(’H2O’, cell=[7.5, 9, 9], calculator=GPAW(h=.17, xc=’PBE’)) 



rho = atoms.calc.get_all_electron_density(gridrefinement=4) * Bohr**3 

write(’water_density.cube’, atoms, data=rho) 

Then analyse the density cube file by running (use bader -h for a description of the possible options): 

$ bader -p all_atom -p atom_index water_density.cube 

This will produce a number of files. The ACF.dat file, contains a summary of the Bader analysis: 

| # X Y Z CHARGE MIN DIST 

| ----------------------------------------------------------------- 

| 1 7.0865 8.5038 9.0672 9.1121 1.3250 

| 2 7.0865 9.9461 7.9403 0.4440 0.2834 

| 3 7.0865 7.0615 7.9403 0.4440 0.2834 

| ----------------------------------------------------------------- 

| NUMBER OF ELECTRONS: 9.99999 

Revealing that 0.56 electrons have been transfered from each Hydrogen atom to the Oxygen atom. 

The BvAtxxxx.dat files, are cube files for each Bader volume, describing the density within that volume. (I.e. it is 

just the original cube file, truncated to zero outside the domain of the specific Bader volume). 

AtIndex.dat is a cube file with an integer value at each grid point, describing which Bader volume it belongs to. 



The plot below shows the dividing surfaces of the Hydrogen Bader volumes. This was achieved by plotting a 

contour surface of AtIndex.dat at an isovalue of 1.5. 

You can attach the output charges from the bader program to the atoms for further processing: 


from ase.io.bader import attach_charges 

# define the molecule as above 

atoms = molecule(’H2O’) 

atoms.set_cell([7.5, 9, 9]) 


# the next two lines are equivalent (only one needed) 

attach_charges(atoms) 

attach_charges(atoms, ’ACF.dat’) 

for atom in atoms: 

print ’Atom’, atom.symbol, ’Bader charge’, atom.charge 

7.23 Electron transport 

The transport module of ASE assumes the generic setup of the system in question sketched below: 

. . . 

. . . 

7.23. Electron transport 165


There is a central region (blue atoms plus the molecule) connected to two semi-infinite leads constructed by 

infinitely repeated principal layers (red atoms). The entire structure may be periodic in the transverse direction, 

which can be effectively sampled using k-points (yellowish atoms). 

The system is described by a Hamiltonian matrix which must be represented in terms of a localized basis set such 

that each element of the Hamiltonian can be ascribed to either the left, central, or right region, or the coupling 

between these. 

The Hamiltonian can thus be decomposed as: 

⎛ 

. .. 

⎜ VL 

⎜ 

⎜V 

⎜ 

H = ⎜ 

⎝ 

† 

L HL VL 

V † 

L HC VR 

V † 

R HR VR 

V † 

R 

⎞ 

⎟ 

⎠ 

. .. 

where H L/R describes the left/right principal layer, and HC the central region. V L/R is the coupling between 

principal layers, and from the principal layers into the central region. The central region must contain at least one 

principal layer on each side, and more if the potential has not converged to its bulk value at this size. The central 

region is assumed to be big enough that there is no direct coupling between the two leads. The principal layer 

must be so big that there is only coupling between nearest neighbor layers. 

Having defined H L/R, V L/R, and HC, the elastic transmission function can be determined using the Nonequilibrium 

Green Function (NEGF) method. This is achieved by the class: TransportCalculator (in 

ase.transport.calculators) which makes no requirement on the origin of these five matrices. 

class ase.transport.calculators.TransportCalculator(energies, h, h1, h2, 

s=None, s1=None, s2=None, 

align_bf=False) 

Determine transport properties of device sandwiched between semi-infinite leads using nonequillibrium 

Green function methods. 

energies is the energy grid on which the transport properties should be determined. 

h1 (h2) is a matrix representation of the Hamiltonian of two principal layers of the left (right) lead, and the 

coupling between such layers. 

h is a matrix representation of the Hamiltonian of the scattering region. This must include at least on lead 

principal layer on each side. The coupling in (out) of the scattering region is assumed to be identical to the 

coupling between left (right) principal layers. 

s, s1, and s2 are the overlap matrices corresponding to h, h1, and h2. Default is the identity operator. 

If align_bf is True, the onsite elements of the Hamiltonians will be shifted to a common fermi level. 

This module is stand-alone in the sense that it makes no requirement on the origin of these five matrices. They 

can be model Hamiltonians or derived from different kinds of electronic structure codes. 

For an example of how to use the transport module, see the GPAW exercise on electron transport 

7.24 The data module 

7.24.1 Atomic data 

This module defines the following variables: 

data.atomic_masses 

data.atomic_names 

data.chemical_symbols 

data.covalent_radii 


data.cpk_colors 

data.reference_states 

data.vdw_radii 

All of these are lists that should be indexed with an atomic number: 

>>> from ase.data import * 

>>> atomic_names[92] 

’Uranium’ 

>>> atomic_masses[2] 

4.0026000000000002 

data.atomic_numbers 


If you don’t know the atomic number of some element, then you can look it up in the atomic_numbers 

dictionary: 

>>> atomic_numbers[’Cu’] 

29 

>>> covalent_radii[29] 

1.1699999999999999 

The covalent radii are taken from [Cordeo08]. The source of the van der Waals radii is given in vdw.py. 

7.24.2 Molecular data 

The G1, G2, and G3-databases are available in the molecules module. 

Example: 

>>> from ase.data.molecules import molecule 

>>> atoms = molecule(’H2O’) 

All molecular members of each database is conveniently contained in a list of strings (g1, g2, g3), and one can 

look up the experimental atomization energy for each molecule. This is extrapolated from experimental heats of 

formation at room temperature, using calculated zero-point energies and thermal corrections. 

Example: 

>>> from ase.data.molecules import molecule, g2, get_atomization_energy 

>>> g2[11] 

’H2O’ 

>>> atoms = molecule(g2[11]) 

>>> get_atomization_energy(g2[11]) 

232.57990000000001 

>>> from ase.units import kcal,mol 

>>> get_atomization_energy(g2[11])*kcal/mol 

10.08562144637833 

where the last line converts the experimental atomization energy of H2O from units of kcal/mol to eV. 

7.24.3 S22, s26, and s22x5 data 

The s22, s26, and s22x5 databases are available in the s22 module. 

Each weakly bonded complex is identified as an entry in a list of strings (s22, s26, s22x5), and is fully created by 

a ‘create’-function: 

>>> from ase.data.s22 import s22, create_s22_system 

>>> sys = s22[0] 

>>> sys 

’Ammonia_dimer’ 

7.24. The data module 167


>>> atoms = create_s22_system(sys) 

>>> atoms.get_chemical_symbols() 

[’N’, ’H’, ’H’, ’H’, ’N’, ’H’, ’H’, ’H’] 

The coupled-cluster interaction energies for the s22 and s26 systems are retrieved like this: 

>>> from ase.data.s22 import s22, get_interaction_energy_s22 

>>> get_interaction_energy_s22(s22[0]) 

-0.1375 

in units of eV. For s22 these are not the original energies, but from more recent work where the same (large) basis 

set was used for all complexes, yielding more accurate coupled-cluster interaction energies. 

The s22x5 database expands on the original s22 data by introducing non-equilibrium geometries for each complex 

(0.9, 1.0, 1.2, 1.5, and 2.0 times original intermolecular distance). However, these calculations were done in 

accordance with the methods used in the original s22 work, and so is expected to inherit the same problems with 

mixed basis set sizes. Assuming the interaction energy error due to this is the same in all 5 geometries for each 

complex, the default s22x5 interaction energies are therefore corrected with the energy difference between original 

and newer energies at the original separation. 

Example: 

>>> from ase.data.s22 import * 

>>> sys1 = s22[0] 

>>> sys1 

’Ammonia_dimer’ 

>>> atoms1 = create_s22_system(sys1) 

>>> sys2 = s22x5[0] 

>>> sys2 

’Ammonia_dimer_0.9’ 


>>> sys3 = s22x5[1] 

>>> sys3 

’Ammonia_dimer_1.0’ 


>>> get_interaction_energy_s22(sys1) 

-0.1375 


-0.1375 


-0.1375 

>>> get_interaction_energy_s22x5(sys2) 

-0.10549743024963291 

>>> get_interaction_energy_s22x5(sys3) 

-0.1375 

>>> get_interaction_energy_s22x5(sys3,correct_offset=False) 

-0.1362 

>>> get_interaction_energy_s22x5(sys1,dist=1.0) 

-0.1375 

>>> get_interaction_energy_s22x5(sys1,dist=0.9) 

-0.10549743024963291 

>>> get_interaction_energy_s22x5(sys1,dist=0.9,correct_offset=False) 

-0.1045 

>>> get_number_of_dimer_atoms(sys1) 

[4, 4] 

>>> get_s22x5_distance(sys2) 

-0.25040236345454536 

>>> get_s22x5_distance(sys3) 

0.0 

where sys1 is an s22 complex in the original geometry, while sys2 and sys3 are two different s22x5 geometries 

of the exact same complex. It is seen that the interaction energies for an s22 system and its s22x5 equivalent 

(indexed ‘_1.0’) does not neccesarily match when the energy offset-correction is turned off. The last two functions 



are convenience functions, giving the number of atoms in the two molecules constituting a dimer and the relative 

intermolecular distance in a dimer (relative to the ‘1.0’ separation, and in Angstrom), respectively. 

7.25 Trajectory files 

The io.trajectory module defines Trajectory objects, that is objects storing the temporal evolution of a 

simulation. A Trajectory file contains one or more Atoms objects, usually to be interpreted as a time series, 

although that is not a requirement. 

The io.trajectory module currently defines two kinds of Trajectory files, the PickleTrajectory and the 

BundleTrajectory. PickleTrajectory is the recommended Trajectory format, BundleTrajectory is only intended 

for large molecular dynamics simulations (large meaning millions of atoms). 

In the future, other kinds of Trajectories may be defined, with similar Python interface but with different underlying 

file formats. 

7.25.1 PickleTrajectory 

The PickleTrajectory has the interface 

class ase.io.trajectory.PickleTrajectory(filename, mode=’r’, atoms=None, master=None, 

backup=True) 

Reads/writes Atoms objects into a .traj file. 

A PickleTrajectory can be created in read, write or append mode. 

Parameters: 

filename: The name of the parameter file. Should end in .traj. 

mode=’r’: The mode. 

‘r’ is read mode, the file should already exist, and no atoms argument should be specified. 

‘w’ is write mode. If the file already exists, is it renamed by appending .bak to the file name. The 

atoms argument specifies the Atoms object to be written to the file, if not given it must instead be given 

as an argument to the write() method. 

‘a’ is append mode. It acts a write mode, except that data is appended to a preexisting file. 

atoms=None: The Atoms object to be written in write or append mode. 

master=None: Controls which process does the actual writing. The default is that process number 0 does 

this. If this argument is given, processes where it is True will write. 

backup=True: Use backup=False to disable renaming of an existing file. 

close() 

Close the trajectory file. 

open(filename, mode) 

Opens the file. 

For internal use only. 

post_write_attach(function, interval=1, *args, **kwargs) 

Attach a function to be called after writing ends. 

function: The function or callable object to be called. 

interval: How often the function is called. Default: every time (1). 

All other arguments are stored, and passed to the function. 

7.25. Trajectory files 169


pre_write_attach(function, interval=1, *args, **kwargs) 

Attach a function to be called before writing begins. 




set_atoms(atoms=None) 

Associate an Atoms object with the trajectory. 

Mostly for internal use. 

write(atoms=None) 

Write the atoms to the file. 

If the atoms argument is not given, the atoms object specified when creating the trajectory object is 

used. 

Note that there is apparently no methods for reading the trajectory. Reading is instead done by indexing the 

trajectory, or by iterating over the trajectory: traj[0] and traj[-1] return the first and last Atoms object in 

the trajectory. 

Examples 

Reading a configuration: 


traj = PickleTrajectory("example.traj") 

atoms = traj[-1] 

Reading all configurations: 

traj = PickleTrajectory("example.traj") 

for atoms in traj: 

# Analyze atoms 

Writing every 100th time step in a molecular dynamics simulation: 

# dyn is the dynamics (e.g. VelocityVerlet, Langevin or similar) 

traj = PickleTrajectory("example.traj", "w", atoms) 

dyn.attach(traj.write, interval=100) 

dyn.run(10000) 

traj.close() 

7.25.2 BundleTrajectory 

The BundleTrajectory has the interface 

class ase.io.bundletrajectory.BundleTrajectory(filename, mode=’r’, atoms=None, 

backup=True) 

Reads and writes atoms into a .bundle directory. 

The BundleTrajectory is an alternative way of storing trajectories, intended for large-scale molecular dynamics 

simulations, where a single flat file becomes unwieldy. Instead, the data is stored in directory, a 

‘bundle’ (the name bundle is inspired from bundles in Mac OS, which are really just directories the user is 

supposed to think of as a single file-like unit). 

Parameters: 

filename: The name of the directory. Preferably ending in .bundle. 



mode (optional): The file opening mode. ‘r’ means open for reading, ‘w’ for writing and ‘a’ for appending. 

Default: ‘r’. If opening in write mode, and the filename already exists, the old file is renamed to .bak 

(any old .bak file is deleted), except if the existing file is empty. 

atoms (optional): The atoms that will be written. Can only be specified in write or append mode. If not 

specified, the atoms must be given as an argument to the .write() method instead. 

backup=True: Use backup=False to disable renaming of an existing file. 

close() 

Closes the trajectory. 

classmethod delete_bundle(filename) 

Deletes a bundle. 

static is_bundle(filename) 

Check if a filename exists and is a BundleTrajectory. 

static is_empty_bundle(filename) 

Check if a filename is an empty bundle. Assumes that it is a bundle. 

log(text) 

Write to the log file in the bundle. 

Logging is only possible in write/append mode. 

This function is mainly for internal use, but can also be called by the user. 

post_write_attach(function, interval=1, *args, **kwargs) 

Attach a function to be called after writing ends. 




pre_write_attach(function, interval=1, *args, **kwargs) 

Attach a function to be called before writing begins. 




read_extra_data(name, n=0) 

Read extra data stored alongside the atoms. 

Currently only used to read data stored by an NPT dynamics object. The data is not associated with 

individual atoms. 

select_data(data, value) 

Selects if a given data type should be written. 

Data can be written in every frame (specify True), in the first frame only (specify ‘only’) or not at 

all (specify False). Not all data types support the ‘only’ keyword, if not supported it is interpreted as 

True. 

The following data types are supported, the letter in parenthesis indicates the default: 

positions (T), numbers (O), tags (O), masses (O), momenta (T), forces (T), energy (T), energies (F), 

stress (F), magmoms (T) 

If a given property is not present during the first write, it will be not be saved at all. 

set_extra_data(name, source=None, once=False) 

Adds extra data to be written. 

Parameters: name: The name of the data. 

7.25. Trajectory files 171


source (optional): If specified, a callable object returning the data to be written. If not specified it is 

instead assumed that the atoms contains the data as an array of the same name. 

once (optional): If specified and True, the data will only be written to the first frame. 

write(atoms=None) 

Write the atoms to the file. 

7.25.3 See also 

If the atoms argument is not given, the atoms object specified when creating the trajectory object is 

used. 

The function ase.io.write() can write a single Atoms object to a Trajectory file. 

The function ase.io.read() can read an Atoms object from a Trajectory file, per default it reads the last one. 

7.26 Utillity functions and classes 

7.26.1 Equation of state 

The EquationOfState class can be used to find equilibrium volume, energy, and bulk modulus for solids: 

class ase.utils.eos.EquationOfState(volumes, energies, eos=’sjeos’) 

Fit equation of state for bulk systems. 

The following equation is used: 

sjeos (default) 

A third order inverse polynomial fit 10.1103/PhysRevB.67.026103 

2 3 -1/3 

E(V) = c + c t + c t + c t , t = V 

0 1 2 3 

taylor 

A third order Taylor series expansion about the minimum volume 

murnaghan 

PRB 28, 5480 (1983) 

birch 

Intermetallic compounds: Principles and Practice, 

Vol I: Principles. pages 195-210 

birchmurnaghan 

PRB 70, 224107 

pouriertarantola 

PRB 70, 224107 

vinet 

PRB 70, 224107 

antonschmidt 

Intermetallics 11, 23-32 (2003) 

p3 

A third order polynomial fit 


Use: 

See Also: 

eos = EquationOfState(volumes, energies, eos=’sjeos’) 

v0, e0, B = eos.fit() 

eos.plot() 

The Equation of state tutorial. 

7.26.2 Symmetry analysis 

http://spglib.sourceforge.net/pyspglibForASE/ 

7.26.3 Phonons 

http://phonopy.sourceforge.net/ 

7.27 Thermochemistry 


ASE contains a thermochemistry module that lets the user derive commonly desired thermodynamic quantities 

from ASE output and some user-specified parameters. Two cases are currently handled by this module: the 

ideal-gas limit (in which translational and rotational degrees of freedom are taken into account) and the harmonic 

limit (generally used for adsorbates, in which all degrees of freedom are treated harmonically). Both cases rely on 

good vibrational energies being fed to the calculators, which can be calculated with the vibrations module. 

7.27.1 Ideal-gas limit 

The thermodynamic quantities of ideal gases are calculated by assuming that all spatial degrees of freedom are separable 

into translational, rotational, and vibrational degrees of freedom. The IdealGasThermo class supports 

calculation of enthalpy (H), entropy (S), and free energy (G), and has the interface listed below. 

class ase.thermochemistry.IdealGasThermo(vib_energies, geometry, electronicenergy=None, 

atoms=None, symmetrynumber=None, 

spin=None, natoms=None) 

Class for calculating thermodynamic properties of a molecule based on statistical mechanical treatments in 

the ideal gas approximation. 

Inputs for enthalpy calculations: 

vib_energies [list] a list of the vibrational energies of the molecule (e.g., from 

ase.vibrations.Vibrations.get_energies). The number of vibrations used is automatically calculated 

by the geometry and the number of atoms. If more are specified than are needed, then the lowest 

numbered vibrations are neglected. If either atoms or natoms is unspecified, then uses the entire list. 

Units are eV. 

geometry [‘monatomic’, ‘linear’, or ‘nonlinear’] geometry of the molecule 

electronicenergy [float] the electronic energy in eV (If electronicenergy is unspecified, then the methods 

of this class can be interpreted as the enthalpy and free energy corrections.) 

natoms [integer] the number of atoms, used along with ‘geometry’ to determine how many vibrations to 

use. (Not needed if an atoms object is supplied in ‘atoms’ or if the user desires the entire list of 

vibrations to be used.) 

Extra inputs needed for for entropy / free energy calculations: 

atoms [an ASE atoms object] used to calculate rotational moments of inertia and molecular mass 

7.27. Thermochemistry 173


Example 

symmetrynumber [integer] symmetry number of the molecule. See, for example, Table 10.1 and Appendix 

B of C. Cramer “Essentials of Computational Chemistry”, 2nd Ed. 

spin [float] the total electronic spin. (0 for molecules in which all electrons are paired, 0.5 for a free radical 

with a single unpaired electron, 1.0 for a triplet with two unpaired electrons, such as O_2.) 

get_enthalpy(temperature, verbose=True) 

Returns the enthalpy, in eV, in the ideal gas approximation at a specified temperature (K). 

get_entropy(temperature, pressure, verbose=True) 

Returns the entropy, in eV/K, in the ideal gas approximation at a specified temperature (K) and pressure 

(Pa). 

get_free_energy(temperature, pressure, verbose=True) 

Returns the free energy, in eV, in the ideal gas approximation at a specified temperature (K) and 

pressure (Pa). 

The IdealGasThermo class would generally be called after an energy optimization and a vibrational analysis. 

The user needs to supply certain parameters if the entropy or free energy are desired, such as the geometry and 

symmetry number. An example on the nitrogen molecule is: 




from ase.vibrations import Vibrations 

from ase.thermochemistry import IdealGasThermo 

atoms = molecule(’N2’) 


dyn = QuasiNewton(atoms) 


electronicenergy = atoms.get_potential_energy() 

vib = Vibrations(atoms) 

vib.run() 

vib_energies = vib.get_energies() 

thermo = IdealGasThermo(vib_energies=vib_energies, 

electronicenergy=electronicenergy, atoms=atoms, 

geometry=’linear’, symmetrynumber=2, spin=0) 

G = thermo.get_free_energy(temperature=298.15, pressure=101325.) 

This will give the thermodynamic summary output: 

Enthalpy components at T = 298.15 K: 

=============================== 

E_elec 0.000 eV 

E_ZPE 0.116 eV 

Cv_trans (0->T) 0.039 eV 

Cv_rot (0->T) 0.026 eV 

Cv_vib (0->T) 0.000 eV 

(C_v -> C_p) 0.026 eV 

------------------------------- 

H 0.206 eV 

=============================== 

Entropy components at T = 298.15 K and P = 101325.0 Pa: 

================================================= 

S T*S 

S_trans (1 atm) 0.0015579 eV/K 0.464 eV 

S_rot 0.0004314 eV/K 0.129 eV 


S_elec 0.0000000 eV/K 0.000 eV 

S_vib 0.0000001 eV/K 0.000 eV 

S (1 atm -> P) -0.0000000 eV/K -0.000 eV 

------------------------------------------------- 

S 0.0019893 eV/K 0.593 eV 

================================================= 

Free energy components at T = 298.15 K and P = 101325.0 Pa: 

======================= 

H 0.206 eV 

-T*S -0.593 eV 

----------------------- 

G -0.387 eV 

======================= 

7.27.2 Harmonic limit 


In the harmonic limit, all degrees of freedom are treated harmonically. The HarmonicThermo class 

supports the calculation of internal energy, entropy, and free energy. This class uses all of the energies 

given to it in the vib_energies list; this is a list as can be generated with the .get_energies() method of 

ase.vibrations.Vibrations, but the user should take care that all of these energies are real (nonimaginary). 

The class HarmonicThermo has the interface described below. 

class ase.thermochemistry.HarmonicThermo(vib_energies, electronicenergy=None) 

Class for calculating thermodynamic properties in the approximation that all degrees of freedom are treated 

harmonically. Often used for adsorbates. 

Inputs: 

vib_energies [list] a list of the harmonic energies of the adsorbate (e.g., from 

ase.vibrations.Vibrations.get_energies). The number of energies should match the number of 

degrees of freedom of the adsorbate; i.e., 3*n, where n is the number of atoms. Note that this class 

does not check that the user has supplied the correct number of energies. Units of energies are eV. 

electronicenergy [float] the electronic energy in eV (If the electronicenergy is unspecified, then the methods 

of this class can be interpreted as the energy corrections.) 

get_entropy(temperature, verbose=True) 

Returns the entropy, in eV/K, in the harmonic approximation at a specified temperature (K). 

get_free_energy(temperature, verbose=True) 

Returns the free energy, in eV, in the harmonic approximation at a specified temperature (K). 

get_internal_energy(temperature, verbose=True) 

Returns the internal energy, in eV, in the harmonic approximation at a specified temperature (K). 

7.27.3 Background 

Ideal gas. The conversion of electronic structure calculations to thermodynamic properties in the ideal-gas 

limit is well documented; see, for example, Chapter 10 of Cramer, 2004. The key equations used in the 

IdealGasThermo class are summarized here. 

C.J. Cramer. Essentials of Computational Chemistry, Second Edition. Wiley, 2004. 

The ideal-gas enthalpy is calculated from extrapolation of the energy at 0 K to the relevant temperature (for an 

ideal gas, the enthalpy is not a function of pressure): 

H(T ) = Eelec + EZPE + 

� T 

0 

CP dT 



where the first two terms are the electronic energy and the zero-point energy, and the integral is over the constantpressure 

heat capacity. The heat capacity is separable into translational, rotational, vibrational, and electronic parts 

(plus a term of kB to switch from constant-volume to constant-pressure): 

CP = kB + CV ,trans + CV ,rot + CV ,vib + CV ,elec 

The translational heat capacity is 3/2 kB for a 3-dimensional gas. The rotational heat capacity is 0 for a monatomic 

species, kB for a linear molecule, and 3/2 kB for a nonlinear molecule. In this module, the electronic component 

of the heat capacity is assumed to be 0. The vibrational heat capacity contains 3N − 6 degrees of freedom for 

nonlinear molecules and 3N − 5 degrees of freedom for linear molecules (where N is the number of atoms). The 

integrated form of the vibrational heat capacity is: 

� T 

CV,vibdT = 

0 

vib �DOF 

i 

ɛi 

e ɛi/kBT − 1 

where ɛi are the energies associated with the vibrational frequencies, ɛi = hωi. 

The ideal gas entropy can be calculated as a function of temperature and pressure as: 

S(T, P ) = S(T, P ◦ ) − kB ln P 

P ◦ 

= Strans + Srot + Selec + Svib − kB ln P 

P ◦ 

where the translational, rotational, electronic, and vibrational components are calculated as below. (Note that 

the translational component also includes components from the Stirling approximation, and that the vibrational 

degrees of freedom are enumerated the same as in the above.) 

� ��2πMkBT Strans = kB ln 

h2 �3/2 kBT 

P ◦ 

� 

+ 5 

� 

2 

Srot = 

⎧ 

⎪⎨ 

⎪⎩ 

Svib = kB 

0 � � , if monatomic 

2 

8π IkBT 

kB ln σh2 � � 

+ 1 

, if linear 

� � 

√πIAIBIC � 2 

8π kBT 

kB ln σ h2 � � 

3/2 

+ 3 

� 

2 , if nonlinear 

vib �DOF 

i 

� 

ɛi 

kBT � eɛi/kBT � 

�� 

� −ɛi/kBT 

− ln 1 − e 

− 1 

Selec = kB ln [2 × (spin multiplicity) + 1] 

IA through IC are the three principle moments of inertia for a non-linear molecule. I is the degenerate moment of 

inertia for a linear molecule. σ is the symmetry number of the molecule. 

The ideal-gas free energy is then just calculated from the combination of the enthalpy and entropy: 

G(T, P ) = H(T ) − T S(T, P ) 



Harmonic limit. The conversion of electronic structure calculation information into thermodynamic properties is 

less established for adsorbates. However, the simplest approach often taken is to treat all 3N degrees of freedom 

of the adsorbate harmonically since the adsorbate often has no real translational or rotational degrees of freedom. 

This is the approach implemented in the HarmonicThermo class. Thus, the internal energy and entropy of the 

adsorbate are calculated as 

S = kB 

and the free energy is calculated as 

harm �DOF 

ɛi 

U(T ) = Eelec + EZPE + 

eɛi/kBT − 1 

harm �DOF 

i 

� 

i 

ɛi 

kBT � eɛi/kBT � 

�� 

� −ɛi/kBT 

− ln 1 − e 

− 1 

G(T, P ) = U(T ) − T S(T, P ) 

In this case, the number of harmonic energies (ɛi) used in the summation is generally 3N, where N is the number 

of atoms in the adsorbate. 




CHAPTER 

EIGHT 

FREQUENTLY ASKED QUESTIONS 

8.1 ASE-GUI 

See also the documantation for ag. 

8.1.1 How do I export images from a trajectory to png or pov files? 

With ag, you can choose File → Save, but this is not fun if you need to do it for many images. Here is how to do 

it on the command line for a number of images: 

ag images.traj@0 -o image0.pov 



If you have many images, it will be easier to do it using the Python interpreter: 


>>> for n, image in enumerate(read(’images.traj@:3’)): 

... write(’image%d.pov’ % n, image, run_povray=True, pause=False, 

... rotation=’-90x,10z’) 

Here, we also: 

Try: 

• run povray to generate png files 

• disable pausing between the images 

• set a rotation (choose View → Rotate ... in ag to select the best rotation angles) 

>>> help(write) 

to see all possibilities or read more here. 

8.2 General 

8.2.1 Citation: how should I cite ASE? 

If you find ASE useful in your research please cite: 

S. R. Bahn and K. W. Jacobsen 

An object-oriented scripting interface to a legacy electronic structure code 

Comput. Sci. Eng., Vol. 4, 56-66, 2002 

BibTex (doc/ASE.bib): 

179


@Article{ISI:000175131400009, 

Author = {S. R. Bahn and K. W. Jacobsen}, 

Title = {An object-oriented scripting interface to a legacy electronic structure code}, 

JournalFull = {COMPUTING IN SCIENCE \& ENGINEERING}, 

Year = {2002}, 

Volume = {4}, 

Number = {3}, 

Pages = {56-66}, 

Month = {MAY-JUN}, 

Abstract = {The authors have created an object-oriented scripting interface to a mature density fu 

code. The interface gives users a high-level, flexible handle on the code without rewriting the 

underlying number-crunching code. The authors also discuss the design issues and advantages of 

homogeneous interfaces}, 

Publisher = {IEEE COMPUTER SOC}, 

Address = {10662 LOS VAQUEROS CIRCLE, PO BOX 3014, LOS ALAMITOS, CA 90720-1314 USA}, 

Type = {Article}, 

Language = {English}, 

Affiliation = {Bahn, SR (Reprint Author), Tech Univ Denmark, Dept Phys, CAMP, Bldg 307, DK-2800 Ly 

Tech Univ Denmark, Dept Phys, CAMP, DK-2800 Lyngby, Denmark.}, 

ISSN = {1521-9615}, 

Keywords-Plus = {MULTISCALE SIMULATION; GOLD ATOMS}, 

Subject-Category = {Computer Science, Interdisciplinary Applications}, 

Author-Email = {bahn@fysik.dtu.dk kwj@fysik.dtu.dk}, 

Number-of-Cited-References = {19}, 

Journal-ISO = {Comput. Sci. Eng.}, 

Journal = {Comput. Sci. Eng.}, 

Doc-Delivery-Number = {543YL}, 

Unique-ID = {ISI:000175131400009}, 

DOI = {10.1109/5992.998641}, 

} 

8.3 Download 

Trying to checkout the code via SVN resulted: 

[~]$ svn checkout "https://svn.fysik.dtu.dk/projects/ase/trunk" 

svn: Unrecognized URL scheme ’https://svn.fysik.dtu.dk/projects/ase/trunk’ 

This error is diplayed in case the library ‘libsvn_ra_dav’ is missing on your system. The library is used by SVN, 

but is not installed by default. 

180 Chapter 8. Frequently Asked Questions

CHAPTER 

NINE 

GLOSSARY 

API Application Programming Interface. Automatically generated documentation from docstrings in the source 

code using Epydoc. See here. 

ASE Atomic Simulation Environment. 

Class XXX 

Constructor XXX 

Docstring XXX 

DFT Density Functional Theory. 

EMT Effective Medium Theory. 

HF Hartree-Fock approximation XXX ... 

Instance XXX 

LAPW In the linearized augmented plane wave (LAPW) method the unit cell of the crystal is divided into two 

different types of regions. The first one, called the muffin-tin region, consists of spheres centered around 

the atoms, while the second one, called the interstitial region consists of the remaining part of the unit cell. 

In the muffin-tin spheres the basis consists of atomic like functions to account for the rapid changes of the 

wave function in this area, whereas in the interstitial region the basis functions are plane waves, since the 

wave function changes only slowly at some distance from the atomic sites. 

Namespace An abstract container of the current scope‘s variables. 

ndarray NumPy‘s n-dimensional array. See Numeric arrays in Python. 

NumPy XXX See Numeric arrays in Python. 

Method XXX 

Python XXX What is Python?. 

Scope An enclosing context where values and expressions are associated. 

181


182 Chapter 9. Glossary

There is a mailing list for discussing ASE: 

• ase-users 

The mailing lists below are of interest for active ASE developers only: 

• ase-developers 

• ase-svncheckins 

or (mainly) dacapo / ASE-2 users / developers: 

• campos 

• campos-devel 

10.1 Internet Relay Chat 

CHAPTER 

TEN 

MAILING LISTS 

We have the IRC channel #campos on FreeNode. Please join us if you have any questions. For easy access, you 

can use this webclient. 

183


184 Chapter 10. Mailing Lists

As a developer, you should subscribe to all ASE related Mailing Lists. 

11.1 Development topics 

11.1.1 Release notes 

Development version in trunk 

trunk. 

CHAPTER 

ELEVEN 

ASE DEVELOPMENT 

• Important backwards incompatible change: The ase.lattice.surface.surface() function now returns a righthanded 

unit cell. 

• Mopac interface added. 

• Gaussian interface added. 

Version 3.6.0 

24 Feb 2012: tags/3.6.0. 

• ASE GUI translations added, available: da_DK, en_GB, es_ES. 

• New function for making surfaces with arbitrary Miller indices with the smallest possible surface unit cell: 

ase.lattice.surface.surface() 

• New ase.lattice.bulk() function. Will replace old ase.structure.bulk() function. The new one will produce 

a more natural hcp lattice and it will use experimental data for crystal structure and lattice constants if not 

provided explicitely. 

• New values for ase.data.covalent_radii from Cordeo et al.. 

• New command line tool: Command line tools and tests based on it: abinit, elk, fleur, nwchem. 

• New crystal builder for ag 

• Van der Waals radii in ase.data 

• ASE GUI (ag) now supports velocities for both graphs and coloring 

• Cleaned up some name-spaces: 

– ase now contains only Atoms and Atom 

– ase.calculators is now empty 

185


Version 3.5.1 

24 May 2011: tags/3.5.1. 

• Problem with parallel vibration calculations fixed: Ticket #80. 

Version 3.5.0 

13 April 2011: tags/3.5.0. 

• Improved EMT potential: uses a NeighborList object and is now ASAP compatible. 

• BFGSLineSearch is now the default (QuasiNewton==BFGSLineSearch). 

• There is a new interface to the LAMMPS molecular dynamics code. 

• New phonons module. 

• Van der Waals corrections for DFT, see GPAW usage. 

• New BundleTrajectory added. 

• Updated GUI interface: 

– Stability and usability improvements. 

– Povray render facility. 

– Updated expert user mode. 

– Enabled customization of colours and atomic radii. 

– Enabled user default settings via ~/.ase/gui.py. 

• Database library expanded to include: 

– The s22, s26 and s22x5 sets of van der Waals bonded dimers and complexes by the Hobza group. 

– The DBH24 set of gas-phase reaction barrier heights by the Truhlar group. 

• Implementation of the Dimer method. 

Version 3.4.1 

11 August 2010: tags/3.4.1. 

11.1.2 How to contribute 

Discussion of ASE development takes place on the ase-developer mailing list, and also sometimes on the #gpaw 

IRC channel on freenode. 

We welcome new developers who would like to help work on improving ASE. If you would like to contribute, 

your should first tell us what you want to work on. Use the mailing list for that. 

SVN access 

We don’t give new contributers write access to our SVN repository from day one. So, you will have to create a 

patch and send it to the mailing list: 

$ svn checkout https://svn.fysik.dtu.dk/projects/ase/trunk myase 

$ cd myase 

$ # do your thing ... 

$ svn diff > patch.txt 

Before you send the patch, please read our Coding Conventions and learn how to use pep8.py, pylint and epydoc: 

186 Chapter 11. ASE development

• Run pep8.py on your code 

• Using pylint to check your code 

• Run epydoc on your code 


One of the current committers will look at the patch and give you some feedback. Maybe the patch is fine and the 

committer will commit it to trunk. There could also be some more work to do like: 

• make it compatible with all supported pythons (see Installation requirements). 

• write more comments 

• fix docstrings 

• write a test 

• add some documentation 

Once everyone is happy, the patch can be appied. This patch-feedback loop is not something we have invented to 

prevent you from contributing - it should be viewed as an opportunity for you to learn how to write a code that fits 

into the ASE codebase. 

After a couple of contributions, we will probably trust you enough to add you as a committer. 

Committers 

Here is the list of current committers: 

user name real name 

anpet Andrew Peterson andy,peterson:stanford,edu 

askhl Ask Hjorth Larsen askhl:fysik,dtu,dk 

bjork Jonas Bjork J,Bjork:liverpool,ac,uk 

dlandis David Landis dlandis:fysik,dtu,dk 

dulak Marcin Dulak dulak:fysik,dtu,dk 

eojons Elvar Örn Jónsson elvar,jonsson:fysik,dtu,dk 

getri George Tritsaris getri:fysik,dtu,dk 

grabow Lars Grabow grabow:fysik,dtu,dk 

hahansen Heine Anton Hansen hahansen:fysik,dtu,dk 

ivca Ivano Eligio Castelli ivca:fysik,dtu,dk 

jakobb Jakob Blomquist jakobb:fysik,dtu,dk 

jber Jon Bergmann Maronsson jber:fysik,dtu,dk 

jblomqvist Janne Blomqvist Janne,Blomqvist:tkk,fi 

jensj Jens Jørgen Mortensen jensj:fysik,dtu,dk 

jesperf Jesper Friis jesper,friis:sintef,no 

jingzhe Jingzhe Chen jingzhe:fysik,dtu,dk 

jkitchin John Kitchin jkitchin:andrew,cmu,edu 

jussie Jussi Enkovaara jussi,enkovaara:csc,fi 

kkaa Kristen Kaasbjerg kkaa:fysik,dtu,dk 

kleis Jesper Kleis kleis:fysik,dtu,dk 

kwj Karsten Wedel Jacobsen kwj:fysik,dtu,dk 

markus Markus Kaukonen markus,kaukonen:iki,fi 

miwalter Michael Walter Michael,Walter:fmf,uni-freiburg,de 

moses Poul Georg Moses poulgeorgmoses:gmail,com 

mvanin Marco Vanin mvanin:fysik,dtu,dk 

s032082 Christian Glinsvad s032082:fysik,dtu,dk 

schiotz Jakob Schiotz schiotz:fysik,dtu,dk 

slabanja Mattias Slabanja slabanja:chalmers,se 

strange Mikkel Strange strange:fysik,dtu,dk 

tjiang Tao Jiang tjiang:fysik,dtu,dk 

tolsen Thomas Olsen tolsen:fysik,dtu,dk 

11.1. Development topics 187


Former committers: 

anro Anthony Goodrow anro:fysik,dtu,dk 

carstenr Carsten Rostgaard carstenr:fysik,dtu,dk 

hanke Felix Hanke F,Hanke:liverpool,ac,uk 

s042606 Janosch Michael Rauba s042606:fysik,dtu,dk 

s052580 Troels Kofoed Jacobsen s052580:fysik,dtu,dk 

11.1.3 Python 3 strategy 

• One codebase for both 2 and 3. 

• Use “print(...)” if possible: 

print ’bla bla’ # no 

print(’bla bla’) # yes 

print ’bla bla:’, x # no 

print(’bla bla: %s’ % x) # yes 

• Don’t do this: print >> f, .... Use f.write(... + ’\n’) or ase.utils.prnt(..., 

file=f). 

• More help here: http://packages.python.org/six/ 

11.1.4 Using version control (SVN) 

The version control system used in ASE development is subversion. A thorough subversion manual can be found 

at http://svnbook.red-bean.com/, here is a brief overview of the most basic features needed when developing ASE. 

• perform svn checkout of ase. 

Place it, for example, in ase-svn directory: 

cd 

svn checkout https://svn.fysik.dtu.dk/projects/ase/trunk ase-svn 

This retrieves the code tree from the subversion repository. Prepend PYTHONPATH and PATH environment 

variables as described at Installation. 

• Updating the working copy of the code (in the directory ase-svn): 

svn update 

After each (important) update, remove ase/svnrevision.py* files, and run: 

python setup.py sdist 

to keep the ase/svnrevision.py file up-to-date. 

• Checking the status of the working copy (in the directory ase-svn): 

svn stat 

The status about the files which are not in version control can be surpassed with the -q flag, and the status 

with respect to latest additions in server can be checked with the -u flag. 

• Committing the changes to the repository 

Before sending the changes in the working copy to the repository, working copy should be updated. After 

that, the changes can be send with: 

svn commit -m "Message to describe the committed changes" 

If the -m option is omitted, an editor is opened for writing the log message. 


• Adding files or directories to version control: 

svn add filename 


If filename is directory, also all the files within the directory are added. Note that svn commit is 

required before the new files are actually included in version control. 

• ASE documentation resides under doc directory, and is also under subversion control. See more at Writing 

documentation. 

11.1.5 Coding Conventions 

Importing modules 

In code, like the implementation of ASE, we must not use the import * syntax. Import everything explicitly 

from exactly the place where it’s defined: 


We distinguish between scripts and code. In your own scripts, it’s OK to use: 

from ase.all import * 

which will give you the most used symbols. 

Python Coding Conventions 

Please run pep8.py and pylint on your code before committing. 

The rules for the Python part are almost identical to those used by the Docutils project: 

Contributed code will not be refused merely because it does not strictly adhere to these conditions; as long as it’s 

internally consistent, clean, and correct, it probably will be accepted. But don’t be surprised if the “offending” 

code gets fiddled over time to conform to these conventions. 

The project shall follow the generic coding conventions as specified in the Style Guide for Python Code and 

Docstring Conventions PEPs, summarized, clarified, and extended as follows: 

• 4 spaces per indentation level. No hard tabs. 

• Very important: Read the Whitespace in Expressions and Statements section of PEP8. 

• Avoid introducing trailing whitespaces. 

• Try to use only 7-bit ASCII, no 8-bit strings. 

• No one-liner compound statements (i.e., no if x: return: use two lines & indentation), except for 

degenerate class or method definitions (i.e., class X: pass is OK.). 

• Lines should be no more than 78 characters long. 

• Use “StudlyCaps” for class names. 

• Use “lowercase” or “lowercase_with_underscores” for function, method, and variable names. For short 

names, maximum two words, joined lowercase may be used (e.g. “tagname”). For long names with three or 

more words, or where it’s hard to parse the split between two words, use lowercase_with_underscores (e.g., 

“note_explicit_target”, “explicit_target”). If in doubt, use underscores. 

• Avoid lambda expressions, which are inherently difficult to understand. Named functions are preferable 

and superior: they’re faster (no run-time compilation), and well-chosen names serve to document and aid 

understanding. 

• Avoid functional constructs (filter, map, etc.). Use list comprehensions instead. 

• Avoid from __future__ import constructs. They are inappropriate for production code. 



• Use ‘single quotes’ for string literals, and “”“triple double quotes”“” for docstrings. Double quotes are OK 

for something like "don’t". 

Attention: Thus spake the Lord: Thou shalt indent with four spaces. No more, no less. Four shall be the 

number of spaces thou shalt indent, and the number of thy indenting shall be four. Eight shalt thou not indent, 

nor either indent thou two, excepting that thou then proceed to four. Tabs are right out. 

Georg Brandl 

General advice 

• Get rid of as many break and continue statements as possible. 

Writing documentation in the code 

Here is an example of how to write good docstrings: 

http://projects.scipy.org/numpy/browser/trunk/doc/example.py 

Run pep8.py on your code 

The pep8.py program is installed together with ASE tools/pep8.py. It will check the PEP8 conventions for you. 

Try: 

$ pep8.py --help 

Using pylint to check your code 

A pylintrc trying to follow ASE Coding Conventions can be found here: doc/development/pylintrc 

Running pylint yourself 

Run pylint on a single file like this: 

[~]$ pylint mypythonfile.py 

Run pylint on a module like this: 

[~]$ pylint path/to/module/root/dir 

Output from pylint run on ASE 

• pylint_ase 

Run epydoc on your code 

Run: 

$ epydoc --docformat restructuredtext --parse-only --show-imports -v dir 

11.1.6 Writing documentation 

We use the Sphinx tool to generate the documentation (both HTML and PDF). The documentation is stored in 

SVN as text files in the doc directory using the reStructuredText markup language. 


Installing Docutils and Sphinx 


The reStructuredText parser that Sphinx needs, is part of the Docutils project. So, we need to install docutils and 

sphinx (version>= 0.5). 

Other requirements 

When building the documentation, a number of png-files are generated. For that to work, you need the following 

installed: 

• matplotlib 

• povray 

• dvipng 

• pdflatex 

• bibtex 

• AUCTex 

• convert (ImageMagick) 

Using Sphinx 

First, you should take a look at the documentation for Sphinx and reStructuredText. 

If you don’t already have your own copy of the ASE package, then get the Latest development release and install 

it. 

Then cd to the doc directory and build the html-pages: 

$ cd ~/ase/doc 

$ sphinx-build . _build 

Note: Make sure that you build the Sphinx documentation using the corresponding ASE version by setting the 

environment variables $PYTHONPATH and $PATH. 

Make your changes to the .rst files, run the sphinx-build command again, check the results and if things looks 

ok, commit: 

$ emacs index.rst 

$ sphinx-build . _build 

$ firefox _build/index.html 

$ svn ci -m "..." index.rst 

To build a pdf-file, you do this: 

$ sphinx-build -b latex . _build 

$ cd _build 

$ make ase-manual.pdf 

Extensions to Sphinx 

We have a couple of extensions to Sphinx: 

:mol: 

:svn: 

Use :mol:‘CH_3OH‘ to get CH3OH. 



:trac: 

:epydoc: 

:math: 

.. math:: 

A role for creating a link to a file in SVN. If you write :svn:‘ase/atoms.py‘, you will get: 

ase/atoms.py. 

A role for creating a link to a file in Trac. If you write :trac:‘ase/atoms.py‘, you will get: 

ase/atoms.py. 

A role for creating a link to the API-documentation generated with epydoc. If you write 

:epydoc:‘ase.atoms.Atoms‘, you will get: Atoms. 

This role is for inline LaTeX-style math. Example: :math:‘\sin(x_n^2)‘ gives you sin(x 2 n). 

Write displayed LaTeX-style math. Example: 

.. math:: \frac{1}{1+x^2} 

gives you: 

1 

1 + x 2 

If you add the line .. default-role:: math, then you can leave out the :math: part like here: 

‘\sin(x_n^2)‘. 

The implementation of these roles is here: doc/ext.py. Our custom, obsolete, implementation of the math role and 

directive is here: doc/mathpng.py. With sphinx >= 0.5 please use sphinx.ext.pngmath. 

reStructedText in emacs 

For people using emacs, the reStructuredText extension is highly recommended. The intallation procedure is 

described in the top of the file, but for most people, it is enough to place it in your emacs load-path (typically 

.emacs.d/) and add the lines: 

(add-to-list ’load-path "~/.emacs.d") 

(require ’rst) 

somewhere in your .emacs file. 

To make the mode auto load for relevant file extension, you can write something like: 

(setq auto-mode-alist 

(append ’(("\\.rst$" . rst-mode) 

("\\.rest$" . rst-mode)) auto-mode-alist)) 

In your .emacs file. 

Updating Sphinx 

Starting a new project with sphinx requires an initial configuration. This is achieved by running sphinxquickstart. 

When updating from a very old sphinx you may consider generating new configuration files and 

updating the old files accordingly. 

Note that the current project is configured up-to-date, so if you are “simply” writing the documentation you must 

skip the sphinx-quickstart step and focus on Using Sphinx. 

Here is how do you setup the GPAW project with sphinx: 


• cd to the doc directory, 

• run sphinx-quickstart and answer the questions (example given for GPAW): 

> Root path for the documentation [.]: 

> Separate source and build directories (y/N) [n]: 

> Name prefix for templates and static dir [.]: _ 

> Project name: GPAW 

> Author name(s): 2008, CAMd et al. 

> Project version: 0.5 

> Project release [0.5]: 

> Source file suffix [.rst]: 

> Name of your master document (without suffix) [index]: contents 


> autodoc: automatically insert docstrings from modules (y/N) [n]: y 

> doctest: automatically test code snippets in doctest blocks (y/N) [n]: 

> intersphinx: link between Sphinx documentation of different projects (y/N) [n]: y 

This will create doc/conf.py and doc/contents.rst. Both these files need to be edited further 

(doc/conf.py may for example include options for sphinx.ext.pngmath) 

11.1.7 Making movies 

A video tutorial can be produced in the following way: 

• change the screen resolution to 1280x1024, 

• record the movie of the screen (without sound) using recordmydesktop (gtk-recordMyDesktop), 

• convert the resulting ogv into avi using mencoder: 

mencoder video.ogv -o video.avi -oac copy -ovc lavc 

• record and edit the sound track using audacity: 

– use 44100 Hz for recording and save the final file as sound.wav, 

– make sure not to keep the microphone to close to avoid signal peaks, 

– cut microphone signal peaks, insert silences, ... 

• edit the movie using avidemux (to match the sound track): 

– load the video.avi: File->Open, make sure to use the following options when editing and saving: 

Video->Copy, Audio->Copy, Format->AVI, 

– add the sound.avi: Audio->Main Track->Audio Source->External WAV, 

– cut video frames (or copy and insert still frames to extend the video) to match the sound track. Set 

beginning mark and end mark - the cut or copy/paste operation applies to the selected region, 

– make sure to save intermediate stages when working on the video File->Save->Save Video (as AVI): 

* avidemux caches the audio track so to match the audio to a freshly cut video you can copy the 

audio file into another name, and add the sound track from that name, 

* sometimes when cutting frames avidemux does not allow to set the markers correctly, and there 

is no undo the last step in avidemux! 

– save the video_final.avi (that matches the sound track), and encode it into mpeg4 format using mencoder, 

using two passes: 



opt="vbitrate=550:mbd=2:dc=10 -vf unsharp=l:0.4:c:0.0:hqdn3d" 

mencoder -ovc lavc -lavcopts vcodec=msmpeg4v2:vpass=1 -nosound -o /dev/null video_final.a 

mencoder video_final.avi -oac mp3lame -af resample=32000:0:2 -lameopts vbr=3:br=80:mode=3 

-ovc lavc -lavcopts acodec=mp3lame:vcodec=msmpeg4v2:vpass=2:$opt \ 

-info name="Overview and installation of ASE":artist=CAMd:copyright="CAMd 2009" - 

– convert video_final.avi into a 800x600 swf file for streaming: 

ffmpeg -i video_final.avi -pass 1 -s 800x600 -b:a 256k -ar 44100 -ac 1 \ 

-vcodec flv -b:v 1200k -g 160 -mbd 2 oi_en_800x600.swf 

ffmpeg -i video_final.avi -pass 2 -s 800x600 -b:a 256k -ar 44100 -ac 1 \ 

-vcodec flv -b:v 1200k -g 160 -mbd 2 -y oi_en_800x600.swf 

11.1.8 New release 

When it is time for a new release of the code, here is what you have to do: 

** Warning: use only three digits release numbers, e.g. 3.1.0, 

• Checkout the Latest development release. 

• Run the tests. 

• Make sure version.py has the correct version number. 

• Make a tag in svn, using the current version number (to make sure not to include changes done by other 

developers in the meantime!): 

svn copy -r 845 https://svn.fysik.dtu.dk/projects/ase/trunk https://svn.fysik.dtu.dk/projects 

Note the resulting tag’s revision tags_revision. 

• Checkout the source, specyfing the version number in the directory name: 

svn co -r tags_revision https://svn.fysik.dtu.dk/projects/ase/tags/3.1.0 ase-3.1.0 

• Create the tar file: 

cd ase-3.1.0 

rm -f MANIFEST ase/svnversion.py*; python setup.py sdist 

Note that the tags_revision is put into the name of the tar file automatically. Make sure that you are 

getting only tags_revision in the tar file name! Any changes to the source will be reflected as a mixed 

or modified revision tag! 

• Put the tar file on webX (set it read-able for all): 

scp dist/python-ase-3.1.0."tags_revision".tar.gz root@webX:/var/www/wiki/ase-files 

• Add a link on News and update the information on the Installation requirements page and the Release notes 

page. 

• Increase the version number in ase/version.py, and commit the change: 

cd ~/ase 

svn ci -m "Version 3.2.0" 

Now the trunk is ready for work on the new version. 

• Send announcement email to the ase-users mailing list (see Mailing Lists). 

11.1.9 Testing the code 

All additions and modifications to ASE should be tested. 



Test scripts should be put in the ase/test directory. The scripts in this directory may be run by using the script 

tools/testase or by using the function: 

test.test(verbosity=1, dir=None) 

Runs the test scripts in ase/test. 

Important: When you fix a bug, add a test to the test suite checking that it is truly fixed. Bugs sometimes come 

back, do not give it a second chance! 

How to fail successfully 

The test suite provided by test.test() automatically runs all test scripts in the ase/test directory and summarizes 

the results. 

Note: Test scripts are run from within Python using the execfile() function. Among other things, this 

provides the test scripts with an specialized global namespace, which means they may fail or behave differently if 

you try to run them directly e.g. using python testscript.py. 

If a test script causes an exception to be thrown, or otherwise terminates in an unexpected way, it will show up in 

this summary. This is the most effective way of raising awareness about emerging conflicts and bugs during the 

development cycle of the latest revision. 

Remember, great tests should serve a dual purpose: 

Working interface To ensure that the class‘es and method‘s in ASE are functional and provide the expected 

interface. Empirically speaking, code which is not covered by a test script tends to stop working over time. 

Replicable results Even if a calculation makes it to the end without crashing, you can never be too sure that the 

numerical results are consistent. Don’t just assume they are, assert() it! 

test.assert(expression) 

Raises an AssertionError if the expression does not evaluate to True. 

Example: 

from ase import molecule 

atoms = molecule(’C60’) 

atoms.center(vacuum=4.0) 

result = atoms.get_positions().mean(axis=0) 

expected = 0.5*atoms.get_cell().diagonal() 

tolerance = 1e-4 

assert (abs(result - expected) < tolerance).all() 

Using functions to repeat calculations with different parameters: 

def test(parameter): 

# setup atoms here... 

atoms.set_something(parameter) 

# calculations here... 

assert everything_is_going_to_be_alright 

if __name__ in [’__main__’, ’__builtin__’]: 

test(0.1) 

test(0.3) 

test(0.7) 

Important: Unlike normally, the module __name__ will be set to ’__builtin__’ when a test script is run 

by the test suite. 



11.1.10 Translate ASE 

You can contribute by translating the ASE GUI, ag, into your language. 

How to translate 

If any of the below steps prove difficult, be sure to ask on the developer mailing list. These steps should work on 

GNU/Linux. 

• Download ASE. 

• Go to ase/gui/po. There is a directory of the form ll or ll_LL for each language, where ll is the 

language code and LL the country code. The latter is necessary only if variants of the same language are 

spoken in multiple countries. 

• If your language is not there already, run LANG=ll make init, substituting the desired language code. 

If necessary append the country code as well: LANG=ll_LL .... 

• There should now be a template file for your language, ll/LC_MESSAGES/ag.po, which can be filled 

out. 

You can edit the po-file with any text editor. It is easiest with a dedicated po-editor such as gtranslator, poedit or 

the gettext mode in EMACS (the package “gettext-el”). Fill out the missing msgstr entries like this: 

#: ../energyforces.py:61 

msgid "Calculate potential energy and the force on all atoms" 

msgstr "Beregn potentiel energi og kræfter på alle atomer" 

Your editor may wholly or partially hide some of the difficult formatting syntax. This next example shows a more 

syntactically complex case in case you need it: 

#: ../calculator.py:107 

msgid "" 

"GPAW implements Density Functional Theory using a\n" 

"Grid-based real-space representation of the wave\n" 

"functions, and the Projector Augmented Wave\n" 

"method for handling the core regions. \n" 

msgstr "" 

"GPAW implementerer tæthedsfunktionalteori med en Gitterbaseret\n" 

"repræsentation af bølgefunktioner i det reelle rum, samt\n" 

"Projector Augmented Wave-metoden til behandling\n" 

"af regionen omkring atomkerner. \n" 

If you are maintaining an existing translation, there may be some “fuzzy” messages. These are translations that 

were written previously but now need to be reviewed, maybe because the original string has been slightly modified. 

Edit them as appropriate and remove the “fuzzy” flag. 

There will be a few special constructs such as string substitution codes %(number)d or %s. These should remain 

unchanged in the translation as they are replaced by numbers or text at runtime. An underscore like in msgid 

"_File" indicates that F is a shortcut key. Conflicting shortcut keys are not a big problem, but avoid them if you 

see them. Finally, some messages may have a lot of whitespace in them. This is due to bad programming style; 

just try to get approximately the same spacing in your translation. 

Already after writing a few translations, you can check that the translation works as expected by following the 

instructions in the next section. 

Check and commit your translation 

• You can check the syntax by running msgfmt -cv ag.po. This will report any syntax errors. 

• You can test your translation in ag directly. First issue the command make in ase/gui/po, then reinstall 

ASE using the usual procedure. The translations will then be in the newly installed ASE. If you translate into 

the same language as your computer’s locale, you should see the translations when you start ag normally. If 



you translate ASE into another language, then run LANG=ll_LL.UTF-8 ag. On some operating systems 

you may need to run LANGUAGE=ll_LL.UTF-8 ag instead. 

Depending on your operating system, you may need to install gettext or locales. 

Send the partially or completely translated po-file to the developers mailing list and ask to have it committed. In 

fact, we will be quite thrilled if you send an e-mail even before you start, and be sure to send one whenever you 

have questions. 

Note: Certain uncommon languages such as Lojban, Anglo-Saxon or Klingon may not be compatible with our 

current build system. Please let us know if you want to translate ASE into such languages. 

Maintaining translations 

Messages will once in a while be added or changed in the ASE. Running make in ase/gui/po automatically 

synchronizes all templates with the messages in the current source tree while maximally reusing the existing 

translations. Some strings may be marked “fuzzy”, indicating that they need review by translators (this happens 

e.g. if an English message is changed only slightly). One can then update the few fuzzy or untranslated messages. 

The obvious time to do this is shortly before a new stable release. 

If you are a committer, please run make before committing and briefly check by running the translated ag that 

nothing is obviously horrible. 

11.1.11 To do 

Check our issue tracker. 

Documentation 

Code 

• Put example of Verlet dynamics in ase/md 

• talk about writing files - pos, py and pckl 

• Write more about the parameters of the supported elements of the EMT calculator. 

• Could the directions argument of ase.lattice.FaceCenteredCubic etc. have default values? 

11.2 Creating an encrypted password for SVN access 

Use this cammand: 

htpasswd -nm 

and type a good password twice. The encrypted password will be printed on the screen. 

If you don’t have the htpasswd command, then use Python: 

>>> import crypt 

>>> passwd = ’’ 

>>> print crypt.crypt(passwd, passwd) 

11.2. Creating an encrypted password for SVN access 197



CHAPTER 

TWELVE 

BUGS! 

If you find a bug in the ASE software, please report it to the developers so it can be fixed. We need that feedback 

from the community to maintain the quality of the code. 

12.1 Bug report 

• If you are unsure if it is a real bug, or a usage problem, it is probably best to report the problem on the 

ase-users mailing list (see Mailing Lists). 

Please provide the failing script as well as the information about your environment (processor architecture, 

versions of python and numpy). Then we (or other users) can help you to find out if it is a bug. 

Another advantage of reporting bugs on the mailing list: often other users will tell you how to work around 

the bug (until it is solved). 

• If you think it is a bug, you can also report it directly on our bug tracking system. The advantage of reporting 

bugs here is that it is not forgotten (which may be a risk on the mailing list). 

We do not guarantee to fix all bugs, but we will do our best. 

12.2 Known bugs 

A list of known bugs (tickets) is on our Trac. 

199


200 Chapter 12. Bugs!

CHAPTER 

THIRTEEN 

PORTING OLD ASE-2 CODE TO 

VERSION 3 

The old Numeric-Python based ASE-2 can coexist with the new numpy-based ASE-3, because the two packages 

have different names: ASE and ase respectively. Here is an example of combining both: 

from ASE.Trajectories.NetCDFTrajectory import NetCDFTrajectory 

traj = NetCDFTrajectory(’a.nc’) 

loa = traj.GetListOfAtoms(-1) 

# Convert to new style Atoms object: 


a = Atoms(loa) 

The new ASE can actually read old NetCDF trajectory files, so this would be simpler: 


a = read(’a.nc’) 

Note: Reading old NetCDF files in the new ASE, works even without having the libnetcdf and 

Scientific.IO.NetCDF libraries installed. 

13.1 The ASE2ase tool 

Use the ASE2ase tool (source code tools/ASE2ase) to convert old scripts: 

$ ASE2ase oldscript.py 

$ diff -u oldscript.py.bak oldscript.py 

Check that the differences look OK. The conversion tool isn’t clever enough to get everything right, so you will 

have to do some conversion manually also. If you have any problems doing this, then you should not hesitate to 

contact the campos-devel mailing list (see Mailing Lists) and ask for help. 

201


202 Chapter 13. Porting old ASE-2 code to version 3

BIBLIOGRAPHY 

[Alfe] D. Alfe, PHON: A program to calculate phonons using the small displacement method, Comput. Phys. 

Commun. 180, 2622 (2009) 

[Wang] Y. Wang et al., A mixed-space approach to first-principles calculations of phonon frequencies for polar 

materials, J. Phys.: Cond. Matter 22, 202201 (2010) 

[MonkhorstPack] Hendrik J. Monkhorst and James D. Pack: Special points for Brillouin-zone integrations, Phys. 

Rev. B 13, 5188–5192 (1976) 

[Bader] R. F. W. Bader. Atoms in Molecules: A Quantum Theory. Oxford University Press, New York, 1990. 

[Tang] W. Tang, E. Sanville, G. Henkelman. A grid-based Bader analysis algorithm without lattice bias. J. Phys.: 

Compute Mater. 21, 084204 (2009). 

[Cordeo08] Covalent radii revisited, Beatriz Cordero, Verónica Gómez, Ana E. Platero-Prats, Marc Revés, 

Jorge Echeverría, Eduard Cremades, Flavia Barragán and Santiago Alvarez, Dalton Trans., 2008, 2832-2838 

DOI:10.1039/B801115J 

203


204 Bibliography

a 

abinit, 112 

ase, 51 

ase.atom, 65 

ase.dft, 162 

ase.io.trajectory, 169 

ase.lattice.surface, 86 

atoms, 53 

b 

basics, 72 

c 

calculate, 79 

calculators, 109 

castep, 131 

constraints, 139 

d 

data, 166 

dft, 156 

dft.dos, 161 

dft.kpoints, 156 

dft.stm, 162 

dft.wannier, 157 

dftb, 117 

e 

edit, 75 

emt, 111 

exciting, 128 

f 

FHI-aims, 124 

fleur, 129 

g 

gromacs, 134 

gui, 72 

i 

infrared, 149 

io, 67 

j 

jacapo, 111 

PYTHON MODULE INDEX 

l 

lammps, 126 

lattice, 93 

lattice.spacegroup, 23 

m 

md, 152 

md.langevin, 153 

md.npt, 154 

md.nptberendsen, 155 

md.nvtberendsen, 154 

md.verlet, 153 

mmtk, 127 

n 

neb, 143 

o 

optimize, 98 

optimize.basin, 101 

optimize.bfgslinesearch, 101 

optimize.fire, 99 

optimize.lbfgs, 99 

optimize.mdmin, 100 

optimize.qn, 98 

optimize.sciopt, 100 

p 

parallel, 102 

phonons, 147 

s 

setup, 78 

siesta, 114 

structure, 83 

t 

test, 194 

thermochemistry, 173 

tools, 76 

transport, 165 

turbomole, 119 

u 

units, 66 

205


utils, 172 

v 

vasp, 122 

vibrations, 145 

view, 75 

visualize, 103 

visualize.vtk, 103 

vtk, 107 

206 Python Module Index

Symbols 

$HOME, 9 

$PATH, 191 

$PYTHONPATH, 191 

A 

Abinit (class in abinit), 113 

abinit (module), 112 

ABINIT_PP_PATH, 112 

ABINIT_SCRIPT, 112 

add_adsorbate() (in module ase.lattice.surface), 90 

add_axes() (ase.visualize.vtk.atoms.vtkAtoms method), 

108 

add_cell() (ase.visualize.vtk.atoms.vtkAtoms method), 

108 

add_forces() (ase.visualize.vtk.atoms.vtkAtoms 

method), 108 

Atoms (class in ase.atoms), 58 

atoms (module), 53 

INDEX 

B 

basics (module), 72 

bcc100() (in module ase.lattice.surface), 87 



build() (ase.calculators.neighborlist.NeighborList 

method), 138 

Bulk modulus, 172 

bulk() (in module ase.structure), 83 

BundleTrajectory (class in ase.io.bundletrajectory), 170 

C 

calc (ase.atoms.Atoms attribute), 59 

calculate (module), 79 

add_scalar_property() (ase.visualize.vtk.grid.vtkAtomicPositions calculate() (ase.calculators.fleur.FLEUR method), 130 

method), 108 

calculation_required() (ase.calculators.interface.Calculator 

add_vector_property() (ase.visualize.vtk.grid.vtkAtomicPositions method), 136 

method), 109 

Calculator (class in ase.calculators.interface), 136 

add_velocities() (ase.visualize.vtk.atoms.vtkAtoms calculators (module), 109 

method), 108 

Castep (class in castep), 131 

adjust_forces() (in module constraints), 142 

castep (module), 131 

adjust_positions() (in module constraints), 142 cell (ase.atoms.Atoms attribute), 59 

ag, 72 

center() (ase.atoms.Atoms method), 59 

Aims (class in FHI-aims), 124 

chemical_symbols (in module data), 166 

AimsCube (class in FHI-aims), 126 

Class, 181 

API, 181 

close() (ase.io.bundletrajectory.BundleTrajectory 

append() (ase.atoms.Atoms method), 59 

method), 171 

ASE, 181 

close() (ase.io.trajectory.PickleTrajectory method), 169 

ase, 79 

constraints (ase.atoms.Atoms attribute), 59 

ase (module), 51 

constraints (module), 139 

ase-gui, 72 

Constructor, 181 

ase.atom (module), 65 

copy() (ase.atoms.Atoms method), 59 

ase.dft (module), 162 

covalent_radii (in module data), 166 

ase.io.trajectory (module), 169 

cpk_colors (in module data), 166 

ase.lattice.surface (module), 86 

ase.transport.calculators.TransportCalculator (class in D 

transport), 166 

ASE2ase, 201 

assert() (in module test), 195 

Atom (class in ase.atom), 65 

atomic_masses (in module data), 166 

atomic_names (in module data), 166 

atomic_numbers (in module data), 167 

data (module), 166 

delete_bundle() (ase.io.bundletrajectory.BundleTrajectory 

class method), 171 

DFT, 181 

dft (module), 156 

dft.dos (module), 161 

207


dft.kpoints (module), 156 

dft.kpoints.cc12_2x3 (in module dft.kpoints), 157 


dft.kpoints.cc162_sq3xsq3 (in module dft.kpoints), 157 






dft.stm (module), 162 

dft.wannier (module), 157 

dftb (module), 117 

DFTCalculator (class in ase.calculators.interface), 137 

diamond100() (in module ase.lattice.surface), 87 

diamond111() (in module ase.lattice.surface), 89 

Docstring, 181 

DOS (class in ase.dft.dos), 162 

E 

edit (module), 75 

edit() (ase.atoms.Atoms method), 59 

EMT, 181 

EMT (class in emt), 111 

emt (module), 111 

environment variable 

$HOME, 9 

$PATH, 191 

$PYTHONPATH, 191 

ABINIT_PP_PATH, 112 

ABINIT_SCRIPT, 112 

FLEUR, 129 

FLEUR_INPGEN, 129 

HOME, 13 

LAMMPS_COMMAND, 127 

PATH, 13, 188 

PYTHONPATH, 13, 18, 188 

PYTHONSTARTUP, 16 

SIESTA_PP_PATH, 114 

SIESTA_SCRIPT, 114 

VASP_PP_PATH, 122 

VASP_SCRIPT, 122 

EquationOfState (class in ase.utils.eos), 172 

Exciting (class in ase.calculators.exciting), 128 

Exciting (class in exciting), 128 

exciting (module), 128 

extend() (ase.atoms.Atoms method), 59 

F 

fcc100() (in module ase.lattice.surface), 87 



FHI-aims (module), 124 

FieldPlotter (class in ase.visualize.fieldplotter), 106 

Filter (class in constraints), 142 

FixAtoms (class in constraints), 139 

FixBondLength (class in constraints), 139 

FixBondLengths (class in constraints), 140 

FixedLine (class in ase.constraints), 140 

FixedMode (class in ase.constraints), 140 

FixedPlane (class in ase.constraints), 140 

FixInternals (class in constraints), 141 

FLEUR, 129 

fleur (module), 129 

FLEUR_INPGEN, 129 

G 

get_actor() (ase.visualize.vtk.module.vtkGlyphModule 

method), 109 

get_angle() (ase.atoms.Atoms method), 59 

get_angular_momentum() (ase.atoms.Atoms method), 

60 

get_array() (ase.atoms.Atoms method), 60 

get_atomic_numbers() (ase.atoms.Atoms method), 60 

get_bz_k_points() (ase.calculators.interface.DFTCalculator 

method), 137 

get_calculation_done() (ase.atoms.Atoms method), 60 

get_calculator() (ase.atoms.Atoms method), 60 

get_cell() (ase.atoms.Atoms method), 60 

get_celldisp() (ase.atoms.Atoms method), 60 

get_center_of_mass() (ase.atoms.Atoms method), 60 

get_centers() (ase.dft.wannier.Wannier method), 159 

get_charges() (ase.atoms.Atoms method), 60 

get_chemical_formula() (ase.atoms.Atoms method), 60 

get_chemical_symbols() (ase.atoms.Atoms method), 

60 

get_dihedral() (ase.atoms.Atoms method), 60 

get_dipole_moment() (ase.atoms.Atoms method), 60 

get_distance() (ase.atoms.Atoms method), 60 

get_distribution_moment() (in module ase.dft), 162 

get_dos() (ase.dft.dos.DOS method), 162 

get_effective_potential() 

(ase.calculators.interface.DFTCalculator 

method), 137 

get_eigenvalues() (ase.calculators.interface.DFTCalculator 

method), 137 

get_energies() (ase.dft.dos.DOS method), 162 

get_energies() (ase.vibrations.Vibrations method), 146 

get_enthalpy() (ase.thermochemistry.IdealGasThermo 

method), 174 

get_entropy() (ase.thermochemistry.HarmonicThermo 

method), 175 

get_entropy() (ase.thermochemistry.IdealGasThermo 

method), 174 

get_fermi_level() (ase.calculators.interface.DFTCalculator 

method), 137 

get_forces() (ase.atoms.Atoms method), 61 

get_forces() (ase.calculators.interface.Calculator 

method), 136 

get_free_energy() (ase.thermochemistry.HarmonicThermo 

method), 175 

get_free_energy() (ase.thermochemistry.IdealGasThermo 

method), 174 

get_frequencies() (ase.vibrations.Vibrations method), 

146 

get_function() (ase.dft.wannier.Wannier method), 159 

208 Index


get_functional_value() (ase.dft.wannier.Wannier 

method), 137 

method), 159 

get_radii() (ase.dft.wannier.Wannier method), 160 

get_hamiltonian() (ase.dft.wannier.Wannier method), get_reciprocal_cell() (ase.atoms.Atoms method), 61 

159 

get_scaled_positions() (ase.atoms.Atoms method), 61 

get_hamiltonian_kpoint() (ase.dft.wannier.Wannier get_spectrum() (ase.infrared.InfraRed method), 151 

method), 159 

get_spin_polarized() (ase.calculators.interface.DFTCalculator 

get_hopping() (ase.dft.wannier.Wannier method), 160 

method), 137 

get_ibz_k_points() (ase.calculators.interface.DFTCalculator get_stress() (ase.atoms.Atoms method), 61 

method), 137 

get_stress() (ase.calculators.interface.Calculator 

get_initial_magnetic_moments() (ase.atoms.Atoms 

method), 136 

method), 61 

get_stresses() (ase.atoms.Atoms method), 62 

get_internal_energy() (ase.thermochemistry.HarmonicThermo get_tags() (ase.atoms.Atoms method), 62 

method), 175 

get_temperature() (ase.atoms.Atoms method), 62 

get_isotropic_pressure() (ase.atoms.Atoms method), 61 get_total_energy() (ase.atoms.Atoms method), 62 

get_k_point_weights() (ase.calculators.interface.DFTCalculator get_unstructured_grid() 

method), 137 

(ase.visualize.vtk.grid.vtkAtomicPositions 

get_kinetic_energy() (ase.atoms.Atoms method), 61 

method), 109 

get_magnetic_moment() (ase.atoms.Atoms method), get_velocities() (ase.atoms.Atoms method), 62 

61 

get_volume() (ase.atoms.Atoms method), 62 


get_wannier_localization_matrix() 



method), 137 

method), 138 

get_magnetic_moments() (ase.atoms.Atoms method), get_xc_functional() (ase.calculators.interface.DFTCalculator 

61 

method), 138 

get_masses() (ase.atoms.Atoms method), 61 

graphene_nanoribbon() (in module ase.structure), 84 

get_momenta() (ase.atoms.Atoms method), 61 gromacs (module), 134 

get_moments_of_inertia() (ase.atoms.Atoms method), gui, 72 

61 

gui (module), 72 

get_monkhorst_pack_size_and_offset() 

ase.dft.kpoints), 156 

(in module 

H 

get_neighbors() (ase.calculators.neighborlist.NeighborListHarmonicThermo 

(class in ase.thermochemistry), 175 

method), 138 

has() (ase.atoms.Atoms method), 62 

get_number_of_atoms() (ase.atoms.Atoms method), 61 hcp0001() (in module ase.lattice.surface), 88 

get_number_of_bands() 

hcp10m10() (in module ase.lattice.surface), 87 

(ase.calculators.interface.DFTCalculator HF, 181 

method), 137 

HOME, 13 

get_number_of_grid_points() 

(ase.calculators.interface.DFTCalculator I 

method), 137 

IdealGasThermo (class in ase.thermochemistry), 173 

get_number_of_spins() 

InfraRed (class in ase.infrared), 150 

(ase.calculators.interface.DFTCalculator infrared (module), 149 

method), 137 

initial_wannier() (ase.calculators.interface.DFTCalculator 

get_occupation_numbers() 

method), 138 

(ase.calculators.interface.DFTCalculator initialize() (ase.dft.wannier.Wannier method), 160 

method), 137 

initialize_density() (ase.calculators.fleur.FLEUR 

get_pbc() (ase.atoms.Atoms method), 61 

method), 130 

get_pdos() (ase.dft.wannier.Wannier method), 160 Instance, 181 

get_points() (ase.visualize.vtk.grid.vtkAtomicPositions interpolate() (neb.NEB method), 143 

method), 109 

io (module), 67 

get_positions() (ase.atoms.Atoms method), 61 is_bundle() (ase.io.bundletrajectory.BundleTrajectory 

get_potential_energies() (ase.atoms.Atoms method), 61 

static method), 171 

get_potential_energy() (ase.atoms.Atoms method), 61 is_empty_bundle() (ase.io.bundletrajectory.BundleTrajectory 

get_potential_energy() (ase.calculators.interface.Calculator static method), 171 

method), 136 

get_pseudo_density() (ase.calculators.interface.DFTCalculator J 

method), 137 

Jacapo (class in jacapo), 111 

get_pseudo_wave_function() 

jacapo (module), 111 


Index 209


L 

LAMMPS (class in lammps), 127 

lammps (module), 126 

LAMMPS_COMMAND, 127 

Langevin (class in md.langevin), 153 

LAPW, 181 

lattice (module), 93 

lattice.spacegroup (module), 23 

localize() (ase.dft.wannier.Wannier method), 160 

log() (ase.io.bundletrajectory.BundleTrajectory 

method), 171 

log() (ase.visualize.fieldplotter.FieldPlotter method), 

106 

log() (ase.visualize.primiplotter.PrimiPlotter method), 

105 

M 

max_spread() (ase.dft.wannier.Wannier method), 160 

md (module), 152 

md.langevin (module), 153 

md.npt (module), 154 

md.nptberendsen (module), 155 

md.nvtberendsen (module), 154 

md.verlet (module), 153 

Method, 181 

MMTK (class in mmtk), 127 

mmtk (module), 127 

molecule() (in module ase.data.molecules), 97 

monkhorst_pack() (in module ase.dft.kpoints), 156 

N 

Namespace, 181 

nanotube() (in module ase.structure), 84 

ndarray, 181 

NEB (class in ase.neb), 143 

neb (module), 143 

NeighborList (class in ase.calculators.neighborlist), 138 

new_array() (ase.atoms.Atoms method), 62 

NPT (class in md.npt), 154 

NPTBerendsen (class in md.nptberendsen), 155 

numbers (ase.atoms.Atoms attribute), 62 

NumPy, 181 

NVTBerendsen (class in md.nvtberendsen), 154 

O 

open() (ase.io.trajectory.PickleTrajectory method), 169 

optimize (module), 98 

optimize.basin (module), 101 

optimize.bfgslinesearch (module), 101 

optimize.fire (module), 99 

optimize.lbfgs (module), 99 

optimize.mdmin (module), 100 

optimize.qn (module), 98 

optimize.sciopt (module), 100 

P 

parallel (module), 102 

paropen() (in module ase.parallel), 102 

parprint() (in module ase.parallel), 102 

PATH, 13, 188 

pbc (ase.atoms.Atoms attribute), 62 

phonons (module), 147 

PickleTrajectory (class in ase.io.trajectory), 169 

plot() (ase.visualize.fieldplotter.FieldPlotter method), 

106 

plot() (ase.visualize.primiplotter.PrimiPlotter method), 

105 

pop() (ase.atoms.Atoms method), 62 

positions (ase.atoms.Atoms attribute), 62 

post_write_attach() (ase.io.bundletrajectory.BundleTrajectory 

method), 171 

post_write_attach() (ase.io.trajectory.PickleTrajectory 

method), 169 

pre_write_attach() (ase.io.bundletrajectory.BundleTrajectory 

method), 171 

pre_write_attach() (ase.io.trajectory.PickleTrajectory 

method), 169 

PrimiPlotter (class in ase.visualize.primiplotter), 104 

Python, 181 

PYTHONPATH, 13, 18, 188 

PYTHONSTARTUP, 16 

R 

rattle() (ase.atoms.Atoms method), 62 

read() (in module ase.io), 67 

read_cube_data() (in module io), 70 

read_extra_data() (ase.io.bundletrajectory.BundleTrajectory 

method), 171 

reference_states (in module data), 167 

relax() (ase.calculators.fleur.FLEUR method), 130 

repeat() (ase.atoms.Atoms method), 62 

rotate() (ase.atoms.Atoms method), 62 

rotate_dihedral() (ase.atoms.Atoms method), 63 

rotate_euler() (ase.atoms.Atoms method), 63 

run() (ase.vibrations.Vibrations method), 146 

S 

save() (ase.dft.wannier.Wannier method), 160 

SciPyFminBFGS (class in ase.optimize.sciopt), 100 

SciPyFminCG (class in ase.optimize.sciopt), 100 

Scope, 181 

select_data() (ase.io.bundletrajectory.BundleTrajectory 

method), 171 

set_actor() (ase.visualize.vtk.module.vtkGlyphModule 

method), 109 

set_angle() (ase.atoms.Atoms method), 63 

set_array() (ase.atoms.Atoms method), 63 

set_atomic_numbers() (ase.atoms.Atoms method), 63 

set_atoms() (ase.calculators.interface.Calculator 

method), 137 

set_atoms() (ase.io.trajectory.PickleTrajectory 

method), 170 

set_background() (ase.visualize.fieldplotter.FieldPlotter 

method), 106 

210 Index


set_background_color() 

set_rotation() (ase.visualize.fieldplotter.FieldPlotter 

(ase.visualize.fieldplotter.FieldPlotter 

method), 107 

method), 106 

set_rotation() (ase.visualize.primiplotter.PrimiPlotter 

set_black_white_colors() 

method), 106 

(ase.visualize.fieldplotter.FieldPlotter set_scaled_positions() (ase.atoms.Atoms method), 64 

method), 106 

set_tags() (ase.atoms.Atoms method), 64 

set_calculator() (ase.atoms.Atoms method), 63 set_velocities() (ase.atoms.Atoms method), 64 

set_cell() (ase.atoms.Atoms method), 63 

setup (module), 78 

set_charges() (ase.atoms.Atoms method), 64 

Siesta (class in siesta), 114 

set_chemical_symbols() (ase.atoms.Atoms method), 64 siesta (module), 114 

set_color_function() (ase.visualize.fieldplotter.FieldPlotterSIESTA_PP_PATH, 

114 

method), 106 

SIESTA_SCRIPT, 114 

set_color_function() (ase.visualize.primiplotter.PrimiPlotter structure (module), 83 

method), 105 

summary() (ase.vibrations.Vibrations method), 146 

set_colors() (ase.visualize.primiplotter.PrimiPlotter 

method), 105 

T 

set_constraint() (ase.atoms.Atoms method), 64 test, 13 

set_data_range() (ase.visualize.fieldplotter.FieldPlotter test (module), 194 

method), 106 

test.test() (in module test), 195 

set_dihedral() (ase.atoms.Atoms method), 64 

testase, 194 

set_dimensions() (ase.visualize.fieldplotter.FieldPlotter thermochemistry (module), 173 

method), 107 

tools (module), 76 

set_dimensions() (ase.visualize.primiplotter.PrimiPlotter translate() (ase.atoms.Atoms method), 64 

method), 105 

translate() (ase.dft.wannier.Wannier method), 160 

set_distance() (ase.atoms.Atoms method), 64 

translate_all_to_cell() (ase.dft.wannier.Wannier 

set_extra_data() (ase.io.bundletrajectory.BundleTrajectory method), 160 

method), 171 

translate_to_cell() (ase.dft.wannier.Wannier method), 

set_initial_magnetic_moments() (ase.atoms.Atoms 

160 

method), 64 

transport (module), 165 

set_invisibility_function() 

turbomole (module), 119 


method), 107 

U 

set_invisibility_function() 

(ase.visualize.primiplotter.PrimiPlotter 

method), 105 

set_invisible() (ase.visualize.fieldplotter.FieldPlotter 

method), 107 

set_invisible() (ase.visualize.primiplotter.PrimiPlotter 

method), 105 

set_log() (ase.visualize.fieldplotter.FieldPlotter 

method), 107 

units (module), 66 

update() (ase.calculators.neighborlist.NeighborList 

method), 138 

update() (ase.visualize.fieldplotter.FieldPlotter 

method), 107 

update() (ase.visualize.primiplotter.PrimiPlotter 

method), 106 

utils (module), 172 

set_log() (ase.visualize.primiplotter.PrimiPlotter V 

method), 105 

Vasp (class in vasp), 122 

set_masses() (ase.atoms.Atoms method), 64 

vasp (module), 122 

set_momenta() (ase.atoms.Atoms method), 64 

VASP_PP_PATH, 122 

set_pbc() (ase.atoms.Atoms method), 64 

VASP_SCRIPT, 122 

set_plot_plane() (ase.visualize.fieldplotter.FieldPlotter 

vdw_radii (in module data), 167 

method), 107 

VelocityVerlet (class in md.verlet), 153 

set_positions() (ase.atoms.Atoms method), 64 

Vibrations (class in ase.vibrations), 145 

set_property() (ase.visualize.vtk.module.vtkGlyphModule 

vibrations (module), 145 

method), 109 

view (module), 75 

set_radii() (ase.visualize.fieldplotter.FieldPlotter 

view() (in module visualize), 103 

method), 107 

visualize (module), 103 

set_radii() (ase.visualize.primiplotter.PrimiPlotter 

visualize.vtk (module), 103 

method), 106 

vtk, 107 

set_red_yellow_colors() 

vtk (module), 107 


vtkAtomicPositions (class in ase.visualize.vtk.grid), 

method), 107 

108 

Index 211


vtkAtoms (class in ase.visualize.vtk.atoms), 107 

vtkGlyphModule (class in ase.visualize.vtk.module), 

109 

W 

Wannier (class in ase.dft.wannier), 158 

write() (ase.atoms.Atoms method), 65 

write() (ase.io.bundletrajectory.BundleTrajectory 

method), 172 

write() (ase.io.trajectory.PickleTrajectory method), 170 

write() (in module ase.io), 68 

write_cube() (ase.dft.wannier.Wannier method), 160 

write_inp() (ase.calculators.fleur.FLEUR method), 130 

write_jmol() (ase.vibrations.Vibrations method), 147 

write_mode() (ase.vibrations.Vibrations method), 147 

write_spectra() (ase.infrared.InfraRed method), 151 

212 Index

ASE Manual Release 3.6.1.2825 CAMd - CampOS Wiki

You also want an ePaper? Increase the reach of your titles

Delete template?

Save as template?