Introduction to the Builder in Virtual

NanoLab
Manual
Version 2014.0

Introduction to the Builder in Virtual NanoLab: Manual

Version 2014.0
Copyright 20082014 QuantumWise A/S
Atomistix ToolKit Copyright Notice
All rights reserved.
This publication may be freely redistributed in its full, unmodified form. No part of this publication may be incorporated or used in other publications
without prior written permission from the publisher.

TABLE OF CONTENTS
1. Introduction ............................................................................................................ 1
Quick guide to changes for experienced users ........................................................ 1
Structure and layout of the Builder ........................................................................ 1
2. Importing, adding, and exporting structures ................................................................ 4
Adding a structure from an existing file/script ......................................................... 4
Creating a new structure ....................................................................................... 4
Saving and exporting structures ............................................................................. 6
3. Mouse and key operations ........................................................................................ 7
Controlling the 3D view ....................................................................................... 7
Selection ............................................................................................................ 8
Deleting atoms .................................................................................................. 10
Undo ............................................................................................................... 11
4. Using the Move Tool .............................................................................................. 12
Selection control ............................................................................................... 12
Translation ........................................................................................................ 14
Rotation - bond angle adjustments ...................................................................... 14
Dihedral adjustments ......................................................................................... 15
5. Overview of built-in plugins ................................................................................... 16
Toolbar plugins ................................................................................................. 16
Panel plugins .................................................................................................... 17
Custom builder plugins ...................................................................................... 19
Supported file formats for import/export ............................................................... 19
Third party plugins ............................................................................................. 20
6. Managing plugins (the AddOn Manager) .................................................................. 21
Developing your own plugins ............................................................................. 22

iii

CHAPTER 1. INTRODUCTION

The new Builder

in Virtual NanoLab (VNL), the GUI to Atomistix ToolKit, was introduced

in version 12.2 and provides many powerful tools for building advanced atomic-scale structures.
These can be used either in ATK calculations or for exporting to external file formats for use in
other software packages.
This manual will provide an overview of the Builder and introduce some basic concepts. For
more specific advice and tips for building concrete structures, there are several other resources
available on the QuantumWise website.

QUICK GUIDE TO CHANGES FOR EXPERIENCED USERS

First of all, here is a quick checklist for users who have used the old Builder and other tools in
VNL before, highlighting the changes compared to the 11.x versions.
The Database is now inside the Builder (Add>Add From Database...). It can however, for now,
also be opened via the Tools menu in the main VNL window.
Use the RIGHT mouse button to rotate the 3D view. Zooming is most easily done using the
mouse scroll wheel (pan the view by pressing down the scroll wheel and move the mouse).
The LEFT button is used to select atoms (where possible). See the complete list of mouse
shortcuts for details.

Going from bulk to device (the "Device" button

in the old Builder) is done via Device

Tools>Device From Bulk.

The Custom Builder is essentially gone, but the primary functionality of the old built-in
builders can be accessed from within the Builder instead. If you have a Custom Builder you
can't live without, the tool still exists - open it via the Tools menu in the main VNL window.
It is strongly recommend to convert it to a Builder plugin, however, as it will not be available
from 12.8 and onward.

STRUCTURE AND LAYOUT OF THE BUILDER

When the Builder starts up for the first time in a VNL session, it is empty. You will soon learn
how to add structures to it, but first let us define some terminology.
The various parts of the Builder are defined in the picture.

The stash is where the structures you are working on are stored. Each stash item is represented
by an icon, and corresponds to a single configuration (MoleculeConfiguration, BulkConfiguration, DeviceConfiguration, or NudgedElasticBand).

Warning
In version 12.2, the stash is not saved when you exit VNL! Thus, it is not a permanent
storage for structures, but rather a work space for the current session, containing items
you can operate on, combine - and save/export to other VNL tools or to files of various
formats.
Stash items can be selected and/or active - there is a difference. You can select more than one
structure, but only one can be active. There are some plugins that act on more than one structure
(e.g. to combine two configurations into one), and that is why you can select other items than
the active one.

Figure 1.1: In this picture the Si crystal is active - it is the structure shown in the 3D window, and operations
like mirror or delete atoms, etc, will be carried out on this structure. The active state is indicated by an
orange rectangle around the stash item. The methane molecule, on the other hand, is selected.

Right-click a stash item to open its context menu. This allows you to rename, copy, delete, and
in various ways save/export the structure to files or other tools in VNL. Renaming a stash item;
can also be done by selecting it and pressing F2.
The Copy and Delete operations are also available from the stash menu, to the left, and always
apply to the selected stash item. When you copy an item, a new identical stash item is immediately inserted on the stash.

On the left-hand side of the Builder is a plugin toolbar with buttons. Hold the mouse over each
button to see a tooltip describing it.
On the right-hand side is a toolbar with several panels, like Bulk Tools. Click the panel to open
it - it will expand several panel plugins that are relevant for bulk systems (see Figure 1.1). Each
such plugin, either a button on the plugin toolbar or a panel plugins, performs some operation
on the active stash item (sometimes combining more than one stash item into a new one). This
will be discussed in more detail later on.
It is now time to get some structures into the Builder so you can start using it for real!

CHAPTER 2. IMPORTING, ADDING, AND

EXPORTING STRUCTURES

ADDING A STRUCTURE FROM AN EXISTING FILE/SCRIPT

There are several ways to insert new structures into the Builder. All are collected under the
Add button on the stash menu.

The most general way to import a file into the Builder is to click Add>Add From Files.... In the
file dialog, select the import filter and locate the file(s) to import and click Open.
For a list of supported file formats, see the Plugins section.

Tip
If you select multiple files, they will be imported as individual stash items.
If the file is a natively supported file format (currently ATK-Python/NetCDF, XYZ, CIF, CAR,
VASP), you can also drag and drop the file from a file browser (like Explorer in Windows, or the
built-in file browser in VNL) onto the open Builder window or onto the Builder icon

on

the toolbar in the main VNL window to import the file.

It is also possible to drag and drop a Python script (as text), e.g. from an editor, onto the Builder.
Finally, if you copy some Python code to the clipboard, you can paste it into the Builder by
choosing Add>Add From Clipboard.

CREATING A NEW STRUCTURE

To create a brand new structure, to build up from scratch, click Add>New Configuration. This
will insert a molecule with a single hydrogen atom, and then you can manipulate this further
by using a combination of the plugins in the Builder. This is however mostly useful for building
very simple structures like dimers or elementary crystals; in most cases you will be much better
off taking an existing structure from the database and modifying it.

CUSTOM BUILDERS
Each entry in the Add Custom menu is defined by a plugin, and you can write your own or
download and install new addons to extend the list, to make it easy to build a particular new
type of structure. These plugins can be simple, and just take a few parameters (like the built-in
nanotube plugin) or use a very elaborate interface, to define the structure. These plugins create
a new stash item, whereas other plugins normally operate on existing stash item.

Figure 2.1:Building a nanotube, also multiwall, in VNL is very easy - just use Add>Add Custom>Nanotube.

There are a couple of template builders provided with the Builder, to build nanotubes or nanoribbon. Users familiar with VNL will recognize these from the old "Custom Builder", but the
functionality has been extended in 12.2 to allow you to build e.g. multiwall nanotubes and
boron-nitride structures.

DATABASE
VNL contains a database with several hundred crystals, molecules and fullerenes. To add a
structure from the database to the Builder, click Add>Add From Database..., then select the
relevant Database form the menu (Databases>Crystals, for instance). By entering some text in
the search field the list can be filtered.

Figure 2.2:The crystal database. Use the menu Databases to open the molecule and fullerene databases.

Once you have located and selected the desired struture, click the

icon to add it as a new

stash item. You can also double-click a line in the list to add that structure.

COMBINING AND CONVERTING STRUCTURES

In many cases it is necessary to combine two structures into one, or to convert a geometry into
another one.
In the Builder there are a couple of plugins that can combine two structures into one for special
purposes, e.g. the Builders>NEB and Builders>Interface builders, and a plugin to merge two
cells. To use these, just follow the instructions in the plugin panel. Under Builders you can also
find a plugin for cleaving a crystal.
Another possibility to is to drop a stash item from the stash onto the 3D window; this will add
the atoms of the dropped item to the active configuration (only the atom positions are used, not
unit cells or other properties). When you do this, the Builder activates the Move Tool, which is
powerful way to interactively translate and rotate fragments. For more details, see the dedicated
Move tool section.
To convert a bulk structure to a device, use Device Tools>Device From Bulk. To go back, click
the icon

on the toolbar. Similarly, you can convert a periodic structure to a molecule

(removing the unit cell) using

SAVING AND EXPORTING STRUCTURES

Once you have created a geometry, you will want to export or save (remember, as mentioned
above, that the stash is lost once VNL is closed).
To save the active stash item into a Python or NetCDF file, press Ctrl+S (or use the menu
File>Save as...) and use the file dialog to specify the file type and location.

Note
When saving into NetCDF files, the structure is appended if the file exists (even if there
is a warning that claims the file will be overwritten).
To export the active stash item to a non-ATK file format (like XYZ, CIF, etc), press Ctrl+E, or use
the menu File>Export configuration.
To save or export another stash item than the active one, right click it and choose Save as...
or Export from the context menu.
As all instruments in VNL, the Builder window has a script drag icon

and a Send To button

in the lower right-hand corner (see Figure 1.1). Using these you can transfer the active
structure to e.g. the Script Generator to set up a calculation. To send a particular stash item to
e.g. the Editor, right-click it and choose Send To" from the context menu.

CHAPTER 3. MOUSE AND KEY OPERATIONS

In this section you will learn to operate the 3D view and manipulate structures in simple ways,
including how to select atoms.

CONTROLLING THE 3D VIEW

Use the right mouse button to control the 3D view as follows:
Rotate - move the mouse while holding down the right mouse button.
If the mouse is close to the center of the 3D view, the rotation will be full 3D; if it is close to
the edges the rotation is constrained to the view plane. You can use the latter function to
rotate the structure controllably around a particular axis, if you first align this axis with the
screen normal.
Zoom - this easiest to do with the scroll wheel (roll it), but if you don't have one, you can
hold down Ctrl, press the right mouse button, and move the mouse back and forth to zoom.
Pan - easiest to do with the scroll wheel (press it down, and move the mouse), but if you don't
have one, you can hold down Shift, press the right mouse button, and move the mouse to
pan.

Figure 3.1: The compass in the upper right-hand corner helps you to orient yourself when rotating the 3D
view.

Press Ctrl+R to reset the 3D view to the default orientation and zoom.
For a periodic system, the crystal axes A, B, and C are indicated via labels and by coloring the
three sides of the cell that intersect at the cell (and coordinate system) origin.

Figure 3.2: The colors red, yellow and blue are used to indicate the A, B, and C crystal axes for a periodic
structure. These are the same colors as used on the compass for the X, Y, and Z, but in the general case
the axes are of course not necessarily parallel to the coordinate axes.

PREVIEW MODE
Many plugins have a Preview button, and some will even update the preview while the parameters are changed. The preview state is indicated by a text in the upper left corner of the 3D
window.

Important
Keep in mind that the stash item has not yet been modified - you need to press the relevant
button (often called Apply) to actually carry out the operation.
To dismiss the preview, just click the 3D window; you can then bring it by clicking the plugin
Preview button again.

Note
All other plugins are unavailable when a preview is show, to avoid confusion about
which structure you operate on.

SELECTION
Selecting atoms is often a crucial initial step before you can use different plugins to manipulate
the structure. Many plugins apply their operations on selected atoms only, although in several
cases they will act on the whole structure if no atoms are selected.
The Builder therefore has many ways to select atoms and manipulate selections. Selected atoms
are indicated by a yellow halo.

Figure 3.3: The oxygen atom in this water molecule is selected, as indicated by the yellow halo.

To select an individual atom, click it with the left mouse button. This will replace any current
selection already made.
To add atoms to an existing selection, hold down Ctrl and click the atom; if you click an already
selected atom, it will be removed from the selection.
To select many atoms, use the shape select tool, which are accessed via the top button of the
left toolbar. Select the desired shape:

Rectangle
Circle

.
. The circle is centered at the initial mouse position.

Lasso (free-form)

Then draw the shape using the left mouse button.

Note that the shape select tools operate on all atoms which are inside the shape drawn by the
mouse, including atoms that may be hidden from view because they are behind other atoms.
The single-click mouse select operations only apply on the atom you click.
The selection operations can be modified in various ways using the Ctrl and Shift keys.
To add atoms to an existing selection, hold down Ctrl (in this case, selected atoms that are
also inside the new selection area will not be deselected). To deselect atoms using a shape
select, hold down Shift.
Double-click an atom with the left mouse button to select all atoms in the same fragment,
i.e. all atoms that can reached from the double-clicked atom by going via bonds. If you hold
down Ctrl and double-click, the fragment will be added to the existing selection, or removed
if the clicked atom was already selected.
Hold down Shift and double-click an atom to select all atoms of the same element in the
structure. Hold down Ctrl too, and these atoms will be added to the existing selection (or
removed, if the clicked atom was already selected).
A few other useful keyboard tricks:
To deselect all atoms, left-click the background of the 3D window, or press Esc.

 Press Ctrl+A to select all atoms.

Press Ctrl+I to invert the selection (select all deselected atoms, and deselect all selected
atoms).

ADVANCED SELECT
Sometimes the atoms you want to select are not easily accessible via the mouse, or you need
detailed control of the precise atoms to select. In this case you can use the plugins under
Selection, for instance Expression Select, where you select atoms based on logical expressions, like "all oxygen atoms with a Z coordinate larger than 1.5 or an X coordinate smaller
than -0.5 ". This would be achieved by typing
e=O and (z>1.5 or x<-0.5)

in the Expression Select input field, and pressing Enter or Tab.

There are also plugins for selecting atoms pairs based on bond lengths; one of these is designed
to locate completely or almost overlapping atoms (close neighbors). Overlapping atoms can
occur as a result of e.g. a mirror operation or a translation, and can be hard to spot visually, but
they need to be removed before your can perform a calculation properly.

SELECT BY TAGS
A new concept in ATK 12.2 is that atoms can be assigned tags. Each atom can have many tags,
and the same tag can apply to many atoms. A tag can be any combination of words, that for
some reason help you identify particular atoms.
One of the intended purposes of tags is that you can assign them to a set of atoms when you
build the structure, and then use them later on, e.g. in the Script Generator, to assign a special
basis set, or initial spin to those atoms. Instead of having to list the atom indices of all those
atoms, you would just say "use basis set X for atoms with tag Y". For example, for a work function
calculation you will want to have a different basis set (with longer range) for the surface atoms
than the bulk atoms.
To add, remove and modify tags on atoms, use the plugin Selection>Tags plugin. This placement of the plugin indicates that tags are also a handy tool for selecting atoms. To select atoms
based on tags, it is quickest to use the Tag Select button on the toolbar.
Some tag features are not yet fully implemented, but support will be added to more and more
places in VNL in upcoming releases.

DELETING ATOMS
To delete atoms, first select them, then press Delete on the keyboard.

Tip
It is also possible to delete atoms using Coordinate Tools>Coordinate List, where you
can also insert atoms.

10

UNDO
All operations (except selections) in the Builder can be undone by pressing the icon in the top
toolbar (and, undone operations can be redone). The keyboard shortcut for undo is Ctrl+Z,
while Ctrl+Y stands for redo.

Note
Some plugins do not change the structure but rather create a new stash item; in this case
there is of course nothing to undo.

11

CHAPTER 4. USING THE MOVE TOOL

The Move Tool in the Builder is used to move, rotate, and align atoms, using the either the mouse
or with exact coordinate and vector control. This section will explain the basic features and
how to use them.
To activate the Move Tool, click the button

on the left toolbar, but take care to first consider

which atoms you wish to operate on (see below). The Move Tool will also automatically be
activated if you drop a system from the stash onto the 3D window.
When the Move Tool is active, a widget appears, where you can set some parameters that
control the operations. The parameters will be discussed in detail below.

Figure 4.1:The benzene molecule has been dropped from the stash onto the 3D window with the pyridine,
and three anchor atoms have been selected (red markers).

Also note that when the Move Tool is active, all other plugins are unavailable, to avoid interference (in the same way other plugins are disabled in preview mode). To use any other plugin,
you must first exit the Move Tool, either by closing the widget, or by clicking the shape select
icon

on the left toolbar.

SELECTION CONTROL
The Move tool operations are applied to the atoms which are selected when the tool is opened.
This selection, i.e. the atoms marked with yellow selection markers, is called the selection
group. In the figure above the selection group is the benzene molecule.

12

Note
If no atoms are selected when the tool is opened, the first atom you click will be selected,
along with all atoms in the same fragment (a fragment is a set atoms connected by bonds).
The selection group can not be modified once the Move Tool is activated (except in the
special case mentioned in the previous paragraph. To define a new selection group to
operate on, you must first close the Move Tool, select new atoms, and then activate it
again.

ANCHOR ATOMS
When the Move tool is active, you can within the selection group select up to three atoms which
are used to guide the operations. These atoms will be indicated by red selection markers, and
will also be marked by the numbers 0, 1, and 2 to show the selection sequence. These are called
anchor atoms. In the figure above you can see anchor atoms have been selected.

Figure 4.2:The three anchor atoms on the nanotube cap (in the process of being added to the open end
of the nanotube) are indicated by an index and red markers.

You can also see in Figure 4.2 that when the anchor atoms are selected, the three table rows in
the widget are populated. The three rows show
r0, the position of the first anchor atom (index 0).
r1 r0, i.e. the vector from the first to the second anchor atom.
r2 r1, i.e. the vector from the second to the third anchor atom.
The significance of these vector, or rather how to use them in a powerful way, will be become
more obvious in the following sections. As a general rule, select
one anchor atom to translate (move) the fragment,
two anchor atoms to adjust a bond angle,
three anchor atom for control of a dihedral angle.

13

To deselect all anchor atoms, click the background with the left mouse button. To deselect one
anchor atom, just left-click it again (if you deselect the first anchor atom, all anchor atoms are
deselected, and if you deselect the second anchor atom, the third one is also deselected).

TRANSLATION
To move (translate) the selection group, select (click) one anchor atom in the selection group.
Then use the mouse to drag this atom to a new position, holding down the left mouse button.
The entire group will follow rigidly, i.e. the same translation vector will be applied to all atoms
in the selection group.
The translation is carried out in the view/screen plane (except for snapping). For example, to
control the translation such that the atoms are moved only in the XZ-plane, but keep their Y
coordinates, click one of the buttons xz or zx to set the view plane.
You can also type in the exact new position of anchor atom 0 in the widget by entering its new
Cartesian or fractional coordinates in the table, in the row for r0.

SNAP AND FUSE

If Snap is checked when you translate by mouse, the anchor atom will snap to the positions of
other atoms, if you come close enough to them. This can be used to place the anchor atom
exactly at the position of another atom, which does not belong to the selection group.

Important
The configuration obtained just after snapping is not valid, which will be indicated by
the label showing that there are overlapping atoms. There may be more than one atom
pair overlapping as a result of the translation. Click Fuse to delete the overlapping atoms
not belonging to the selection group.
The snap atom defines the translation vector that is applied to the entire selection group in all
3 directions, X, Y, and Z. Therefore the snap translation may bring the selection out of the screen
plane if the snap atom does not have the same Y coordinate as the anchor atom (in the example
case of translation in the XZ plane).

Tip
A very powerful way to use snapping is to add alignment atoms at the positions where
you want to place an atom or molecule. This alignment atom will often be in a highsymmetry position, e.g. an fcc site a certain distance above a crystal surface. The
alignment atom itself is sacrificial, and will be removed by the fuse operation.
It is common that there are atoms which are close, but not exactly overlapping, after a
move operation. In this case Fuse cannot be used, but instead the plugin Select>Find
close neighbors is a useful tool to find and delete atoms which are close to each other.
Make a habit to check the structure with this tool after a complex operation, not just with
the Move Tool, but also e.g. after mirroring or rotating structures.

ROTATION - BOND ANGLE ADJUSTMENTS

If you select two anchor atoms and start moving either one with the mouse, the selection group
will rotate, using the first anchor atom as rotation center and the vector between the two anchor

14

atoms as rotation axis. During the rotation, you can snap to any other atom for more exact
control.
Alternatively, you can type in the direction vector between the two anchor atoms r1 r0 in the
widget. Only the direction of this vector matters, not its magnitude.
For example, if you want the group to be realigned such that the vector between the two anchor
atoms becomes parallel to the Z-direction, enter r1 r0=(0,0,1).

DIHEDRAL ADJUSTMENTS
Finally, if you select three anchor atoms, you can use the mouse to control the dihedral angle
between
1. the plane spanned by anchor atoms 0 and 1, plus the current mouse position
2. the plane spanned by anchor atoms 1 and 2, plus the current mouse position.
Snap works as above, as well as editing the widget.
To align the group such that the three anchor atoms lie in the XY-plane, enter r1 r0 = (0,1,0)
and r2 r1 = (1,0,0). The cross product of these two vectors is (0,0,1), which is the XY-plane
normal.

15

CHAPTER 5. OVERVIEW OF BUILT-IN PLUGINS

The Builder contains a lot of tools, each of which perform an isolated operation, for instance
repeat a periodic structure a number of times, rotate selected atom around a specified axis,
passivate selected atoms with hydrogen, and so on. The true power of the Builder comes from
the countless ways these operations can be combined.
Below follows an quick overview of the plugins shipped with ATK 12.2. This is mainly provided
in order to give a picture of the wide range of functionality that is available in the Builder. The
plugins are hopefully simple enough to use - many of them contain detailed instructions in the
interface itself, and also don't forget to use the tooltips to find out more about a particular
parameter.

TOOLBAR PLUGINS
Shape select use the mouse to paint a shape to select atoms. Hold the mouse over the
toolbar at this position to switch between the three modes: rectangle

, circle

, lasso

Tags

Move tool

- quickly select atoms with certain tags

- manipulate atoms by moving and rotating fragments in controlled ways (see

Chapter 4).

Convert the structure to a molecule (remove the unit cell).

Convert the structure to a periodic structure (for molecules, enscribe the molecule in a
cell; for device structures, remove the electrodes and keep the central region)

Split device

- for a device, create separate stash items corresponding to the two elec-

trodes and the central region

Periodic table

Passivate

- change element for selected atoms

- add hydrogen atoms to saturate all bonds (for selected atoms, if any, other-

wise for the whole structure); the plugin respects the periodicity of the structure.

16

Centroid

- when three atoms are selected, clicking this button adds an atom in the

average position of the selected atoms; very handy to create alignment points to use with the
Move tool!

Ghost

- convert selected atoms to ghost atoms (or un-ghost the atoms if they already are

ghosts).

Rattle

- randomly displace the atoms with a maximal amplitude of 0.125 in each

direction (i.e. at most 0.0625 towards +x or -x, etc)

PANEL PLUGINS
BUILDERS
Plugins for converting or combining structures into new geometries.
Interface create an interface between two bulk structures, e.g. SiO2 on Si; automatically
attempts to find an optimal interface configuration (minimal strain) by trying various rotations
and repetitions of the provided input structures (coincidence lattice method).
Nudged Elastic Band create a NEB path between two end configurations, using different
methods; the path can afterwards be further manipulated to remove or insert images, or refine
the path further between two images.
Surface (Cleave) cleave a bulk structure to create a surface, electrode (for a device) or a
slab; supports many different possibilities to choose the surface cell.
Wulff Cluster create a cluster using the Wulff construction.

BULK TOOLS
These plugins primarily operate on the unit cell of a periodic structure.
Fit Cell attempts to fit a cell to the structure by looking for periodic patterns.
Lattice Parameters edit the unit cell vectors and lattice constants.
Merge Cells merges two periodic structures; simpler than the interface builders, does not
attempt to strain the structures to match the periodicty - useful for merging 1D or 2D structures
like two nanotubes to form a junction.
Repeat repeats a periodic structure in A, B, and C.
Stretch Cell allow you to "pull" on the unit cell to stretch it; selected atoms will move
with the cell, either rigidly or they stretch too; can be used e.g. to strain a structure or make
a bilayer graphene junction with partial overlap.
Supercell apply a 3x3 matrix operation to a unit cell to make a supercell; atoms are repeated as needed to fill the new cell; handy for converting a hexagonal cell to an orthorhomic
supercell, and other things.

17

 Swap Axes sometimes you need to swap the roles of the unit cell vectors A, B and C, and
the direction of the unit cell in X, Y, and Z. Should almost always be applied twice, since
each operation changes a right-handed cell into a left-handed and vice versa.
Wrap during some operations the atoms can end up outside the unit cell; this plugin wraps
them back into the cell.

COORDINATE TOOLS
These plugins primarily operate on the atom coordinates.
Center center the atoms in a unit cell, or with respect to the origin in the case of a molecule.
Coordinate List edit the coordinates directly in a sortable coordinate list. Right-click the
table and use the context menu to insert/delete atoms. Selecting rows in the table selects the
corresponding atoms.
Mirror mirror selected atoms in a specified mirror plane, optionally while copying them
too.
Quick Optimizer run a geometry optimization of the structure using a classical potential,
if there is support for all elements in the structure; primarily useful for graphene, nanotubes,
and other carbon-based structures (but also Si and Ge nanowires etc) for which the Brenner
potential is available. There is also a set of EMT potentials for the fcc metals Ni, Cu, Pd, Ag,
Pt and Au, and their alloys (plus experimental support for Mg, Zr and Ru).
Rotate rotate selected atoms around a specified axis, optionally while copying them too;
the Move Tool provides an alternative way to rotate with the mouse.
Sort sort the coordinates; can also be done in the Coordinate List.
Transform by Expression apply a mathematical expression to the coordinates, e.g. x->x
+sin(y). Supports all mathematic functions available in the Python math module, and understands the variables x,y,z, and a,b,c for periodic systems.
Translate move selected atoms by a specified distance, optionally while copying them too;
the Move Tool provides an alternative way to move atoms with the mouse
Z-matrix edit the z-matrix of selected atoms.

DEVICE TOOLS
These plugins create or modify device geometries.
Central Region Size after a device has been created, use this plugin to change the size of
the central region, to add or remove screening layers.
Device From Bulk the main tool to create a device, by converting the central region to a
device structure.
Electrode Size similar to Central Region Size; after a device has been created, use this
plugin to change the size of the electrodes.

18

MISCELLANEOUS
Various plugins that do not fit in any other category.
Spatial Regions add, remove and edit metallic and dielectric regions.

SELECT
Plugins for advanced selection of atoms.
By expression enter a logical expression like "e=H and x<10" to select all hydrogen atoms
with X coordinate less than 10 .
Close neighbors very useful to detect (and delete) atoms which are on top of each other,
which would cause problems in the calculation.
By bond length select atoms by range of distance between them.
Tags add, edit or remove tags on atoms, also select atoms by tags (the Tag Select button
the toolbar is however a faster way to select atoms by tags).

CUSTOM BUILDER PLUGINS

Under the stash menu Add>Add Custom you will find a list of "template builders", plugins that
are designed to build a particular structure based on simple (or complex) rules and add a new
item to the stash.
In the native installation of VNL 12.2, you will find the following plugins for adding new stash
items:
Nanotube build any chirality nanotube, also boron-nitride etc, also multiwall (up to 3 walls).
Nanoribbon build one-dimensional ribbons cut out from nanosheets (see just below), with
optional added hydrogen termination.
Nanosheet build infinite two-dimensional sheets based on graphene and similar 2D hexagonal materials.

SUPPORTED FILE FORMATS FOR IMPORT/EXPORT

The following file formats are supported for import and export of atomic geometries (in addition
to ATK Python and NetCDF files, of course):
XYZ
CAR
CIF
VASP (POSCAR/CONTCAR, also in gz/gzip/zip versions)
CASTEP (.cell and .geom)
ASE Python

19

 FHI-aims
Support for additional file formats will be made available as plugins which can be installed via
the AddOn Manager.

THIRD PARTY PLUGINS

When you add new plugins to VNL, either from addons that you have developed yourself,
downloaded via the AddOn Manager, or obtained directly via third-party (or QuantumWise) as
a zip-file, they are always seamlessly integrated in the proper place where they belong. Thus,
if you add your own import filter, it will automatically appear in the dropdown list of file filters
in the Add>Add From Files... dialog.

20

CHAPTER 6. MANAGING PLUGINS (THE ADDON

MANAGER)

Each functionality in the Builder, be it a button, a Custom Builder, or an import filter, is a

plugin. A plugin is a small or large piece of code (technically, it's normally as class) that defines
that functionality.
It is possible to write your own plugin, using the Virtual NanoLab API (Application Programming
Interface).
An addon is a collection of plugins; some contain just one, to define a single button/filter etc,
while others contain a whole set of plugins which somehow are related to each other.
Using the AddOn manager (Help>AddOn Manager) you can easily update installed addons, or
install new ones to extend the functionality of VNL, either by downloading them from the
QuantumWise addon server, or installing them from files (addons are zip files) by clicking Local
Install.

Figure 6.1: In this example the EspressoFilters addon is not installed on this machine, but is available for
download and installation.

Tip
Make it a habit to check the AddOn Manager now and then, to see if there are any updates
available.
Addons are installed in vnl/lib/{python2.7}/site-packages/AddOns (the python2.7 part
is for Linux only) relative to the ATK installation direction. There you can inspect the source
code of almost all plugins provided with VNL, and use them for inspiration to create your own
ones!

21

DEVELOPING YOUR OWN PLUGINS

As mentioned in a few places in this manual, it is possible to write your own plugins to extend
the functionality of VNL for your own specific purposes. If you do so, we also hope that you
would share the plugin with other users, for the benefit of the entire ATK community.
More details about plugin development and sharing will be published separately, along with a
specification of the API.

22