You should have a working version of ATK 2008.10 installed along with the appropriate licenses. Installation and license configuration is documented in Introduction and The FLEXlm license system.

You can enter interactive mode simply by typing: atk at your command line. This should display something similar to the text below the first time you start :

**********************************************************************
Welcome to IPython. I will try to create a personal configuration directory
where you can customize many aspects of IPython's functionality in:

/home/username/.ipython

Successful installation!

Please read the sections 'Initial Configuration' and 'Quick Tips' in the
IPython manual (there are both HTML and PDF versions supplied with the
distribution) to make sure that your system environment is properly configured
to take advantage of IPython's features.
Please press >RETURN< to start IPython.
**********************************************************************

The text displayed on your screen might be different if you have previously used IPython and therefore already have a configuration file. The configuration file for IPython is located in /home/$USERNAME/.ipython/ipythonrc under Linux and C:\Documents and settings\$USERNAME\_ipython under Windows. This file can be used to customize the behavior of your interactive ATK session.

Interactive ATK creates two useful variables on session start up:

These two objects can at anytime provide you with a history of what was entered and what has been printed out. Below is a short example of how this could be used:

$ atk
ATK 2008.10

In [1]: from ATK.KohnSham import *

In [2]: molecule_element = [Hydrogen]*2

In [3]: molecule_coord = [(0.0,0.0,0.0)*Angstrom,(0.8,0.0,0.0)*Angstrom]

In [4]: hydrogen_molecule = MoleculeConfiguration(
   ...: elements = molecule_element,
   ...: cartesian_coordinates = molecule_coord)

In [5]: In
Out[5]: ['\n', 'from ATK.KohnSham import *\n',
 'molecule_element = [Hydrogen]*2\n',
 'molecule_coord = [(0.0,0.0,0.0)*Angstrom,(0.8,0.0,0.0)*Angstrom]\n',
 'hydrogen_molecule = MoleculeConfiguration(\nelements = molecule_element,
\ncartesian_coordinates = molecule_coord)\n', 'In\n']

In [6]: Out
Out[6]:
{5: ['\n', 'from ATK.KohnSham import *\n',
 'molecule_element = [Hydrogen]*2\n',
'molecule_coord = [(0.0,0.0,0.0)*Angstrom,(0.8,0.0,0.0)*Angstrom]\n', 
'hydrogen_molecule = MoleculeConfiguration(\nelements = molecule_element,
\ncartesian_coordinates = molecule_coord)\n', 'In\n', 'Out\n'],
 6: >Recursion on dict with id=-1233127796>}

As can be seen from the sample script above, you work with NanoLanguage in the same way as you would do with a file. The commands are exactly the same. Think of it as if you type your usual input file line-by-line. In contains all lines entered via the command line. Out on the contrary shows all output that was generated from the above commands. Note that only line 5 and 6 produced any output. Line 5 was the command to print In and 6 was the request to print Out itself.

You can exit your interactive ATK session using the key combination Ctrl-D which results in the following output:

In [1]:
Do you really want to exit ([y]/n)?

Hitting the Return key will exit the session. Alternatively, the commands %Exit and %Quit (note the percentage sign) will do the same trick.

Interactive ATK really becomes useful when you are unsure what you might obtain from your calculation. It is possible to start a calculation and once it has finished you will be in the interactive mode ready to conduct analysis upon your newly obtained results.

Consider the example below:

from ATK.KohnSham import *

# Specify atoms, positions and Bravais lattice
atom = [Iron]
position = [(0.0,0.0,0.0)]*Angstrom
unitcell = BodyCenteredCubic(2.87*Angstrom)

# Combine atom, positions and lattice into a
# crystal structure
Iron = BulkConfiguration(
    bravais_lattice=unitcell,
    elements=atom,
    cartesian_coordinates=position
    )

# Specify calculation dependent parameters
kpoints = brillouinZoneIntegrationParameters((10,10,10))

initial_density = electronDensityParameters(
    mesh_cutoff=100*Rydberg,
    initial_scaled_spin=[0.5]
    )

dft_iron = KohnShamMethod(
    electron_density_parameters = initial_density,
    brillouin_zone_integration_parameters=kpoints,
    )
# Start calculation and store results in a variable
scf_iron = dft_iron.apply(Iron)

interactive-iron.py

In the script sample above we create a spin-polarized bulk iron sample and calculate the electron density. However, no real analysis is performed. If we invoke ATK with the -i option, we will be in interactive mode once the script completes and can from there conduct our analysis of the system.

$ atk -i interactive-iron.py
ATK 2008.10
In [1]:

Now it is up to you to perform your experiments. Perhaps you would like to know what your are dealing with. To display all defined variables and functions, use the Python dir() function. Note how all the available ATK names show up. This is because we imported all of them when we ran the script. Now, when we are in interactive mode, all of these functions and variables are still available to us.

In [1]: dir()

Try calculating the total energy of Fermi level of the bulk sample.

In [2]: calculateTotalEnergy(scf_iron)
Out[2]: <NL.ScienceUtilities.Units.PhysicalQuantity.PhysicalQuantity
 instance at 0xb683b42c>

In [3]: print calculateTotalEnergy(scf_iron)
-754.959041604 eV
In [5]: print calculateFermiEnergy(scf_iron)
-6.01897855787 eV

The first time we calculated the total energy, we did not specify any variable into which the returned object should be returned nor did we print its value. This explains why we see a reference to an object in the middle of everything.

When you are done performing your experiment, you could have it all displayed on your screen by printing the In variable, which shows all entered command. This way, you can create your own little log of events that happened and have an input file ready for the next experiment so you do not have to run it interactively.

Remember that interactive ATK is based on iPython and as such it can do everything that iPython can do. So it is quite possible to import other modules that you might have available or customized functions for your specific experiment. The possibilities are almost endless!

Suppose you want to import a file located in specific directory which is not included in your PYTHONPATH (that is, the places IPython will automatically look for files). You can add an arbitrary directory to the search path using the following set of commands:

In [1]: import sys
In [2]: sys.path.append('/home/ll/lib/python')

where /home/ll/lib/python is replaced by a directory on your machine. If you now try to type in the command:

In [3]: print sys.path

you should see that the directory that you entered now appears in the list of directories. If you had a file called, say, ATKHelpers.py located in the directory mentioned above, you would now be able to treat it like any other module in Python:

In [4]: from ATKHelpers import myATKHelperFunction

This way, you can keep all your additional helper function and classes in one handy file.

One of the other things that is different about using ATK interactively is the use of auto-completion: If a module has already been imported e.g. by issuing the following command:

In [2]: from ATK.KohnSham import *

You can specify a Bravais lattice by typing in the first characters, for example

In [2]: BaseCent

and then pressing the Tab key will provide you with a list of available keywords that start with the letters BaseCent. This helps preventing spelling errors and aids those who keep forgetting the name of a particular function.

The up and down arrow keys ↑ and ↓ to scroll through a history stack of previously entered commands. This provides a hand shortcut for revoking and then reediting old commands.

The interactive version of ATK is based on iPython and as such additional technical information can be found on the iPython homepage along with the documentation for iPython.

In particular, we recommend consulting the PyReadline homepage for information on Tab-completion, clipboard copy-and-paste, and many other Windows features.