Importing, adding, and exporting structures

There are several ways to insert new structures into the Builder. Most of them can be accessed using the Add button (see the image below) on the Stash menu.


The windows that opens when clicking the Add button shows the different options to add a new structure (see below).


Adding an already existing structure

Add a structure from a file

A structure can be added from a file by choosing Add ‣ From Files. For a list of supported file formats, see the Plugins section.

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 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, you can paste a Python code from the clipboard into the Builder by choosing Add ‣ From Clipboard.


If you select multiple files, they will be imported as individual Stash items.

Internal database

VNL contains an internal database with several hundred crystals, molecules and fullerenes. To add a structure from this database, click Add ‣ From Database, and select the relevant database from the menu (for example, Databases ‣ Crystals).


Fig. 6 Use the menu in the toolbar to select between the crystal, molecules and fullerenes databases.

In the databases window, type the name of the desired structure in the search field to filter the list.


Fig. 7 The crystal database. Use the search field to look for your desired crystal structure.

Once you have located and selected the desired struture, click the plus_icon icon to add it as a new Stash item. You can also double-click a line in the list to add that structure.

Crystallography Open Database

In addition to the internal database, the Crystallography Open Database (COD) plugin allows you to query the Crystallography Open Database for additional structures. This is particularly useful if the structure you are looking for is not in the VNL internal database. The COD plugin can be accessed by clicking on Add ‣ From Plugin ‣ Crystallography Open Database.


Fig. 8 The search window of the COD plugin.

You can query the database by selecting different search options such as the elements in your structure and the structural parameters. Searching the COD will return a list of the structures matching your search parameters. For each structure, relevant information is shown such as the reference to the original paper in which the structure was reported. You can further refine your search by typing the name of the desired structure in the search field.


Fig. 9 The results window of the COD plugin.

Once you have selected a structure, you can decide to either add it to the Stash, or download the .CIF file containing the structure.

A more extensive explanation on how to use the advanced features of the plugin can be found by in the Help section of the COD plugin window.

Creating a new structure

New configuration

To create a brand new structure, 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 available in the Builder, such as the Molecular Builder.

Custom builders

Each entry in the Add ‣ From Plugin menu is associated with a plugin. These plugins can be simple and just take a few parameters, or use a very elaborate interface to create complicated structures.


While other plugins normally operate on existing Stash item, these plugins create a new Stash item.


Fig. 10 Building a nanotube, also multiwall, in VNL is very easy - just use Add ‣ From Plugin ‣ Nanotube.

The Builder comes with the following built-in plugins:


In addition to the built-in plugins, you can also write your own plugin or download and install new addons to extend the list, to make it easier to build a particular new type of structure.

Combining, modifying and converting structures

In many cases it is necessary to combine two structures into one, or to convert one type of configuration to another, e.g. bulk to device.

In the Builder there are plugins that can be used to modify or combine structures for special purposes. They are located in the plugin panel on the right-hand side of the Builder. Two examples are:

  • the Interface Builder, for combining two structure to form an interface, which can be accessed by clicking on Builders ‣ Interface;
  • the Surface (cleave) plugin for cleaving a crystal, which can be accessed by clicking on Builders ‣ Surface (Cleave).

Each plugin contains instructions explaining how to use it.

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 atomic 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. Similarly, to convert a bulk structure or slab to a surface, use Device Tools ‣ Surface From Bulk. To go back, click the BulkMode02_icon button on the toolbar. You can also convert a periodic structure to a molecule (removing the unit cell) using the MoleculeMode02_icon button.

Saving and exporting structures

Once you have created a structure, you may want to save it as an ATK Python/NetCDF file or export it to a non-ATK format.


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.


When saving into NetCDF files, the structure is appended if the file exists.


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.

Sending the structure to other VNL tools

As all instruments in VNL, the Builder window has a script drag script_icon button and a Send To sendto_icon button in the lower right-hand corner (see Fig. 5). 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.