How to use QuantumATK for fast and easy atomic scale modelling

In this tutorial, you will perform your first calculation with a pre-made atomic structure in QuantumATK NanoLab. In the following tutorials, we will do more calculations of different atomic properties and will learn how to create the first atomic structure from scratch.

Tutorials in the Getting Started category use simple examples to introduce the calculation setup in QuantumATK NanoLab. For more advanced workflows, check out the topical categories in the Tutorials list, which will teach you how to use QuantumATK Engine for specific applications.

Note

We will assume that a working copy of QuantumATK has already been installed, as described in the Installation Guide.

Table of Contents

introbar

Typical workflow

The recommended way of using QuantumATK Engine is through QuantumATK NanoLab. It helps you focus on solving your problem, by assisting you with the preparation steps. A typical workflow in QuantumATK NanoLab consists of the following steps:

Create atomic
structure
 
Set up
calculations
 
Run
a job
 
Analyze
results
builder_step right_arrow workflow_step right_arrow jobs_step right_arrow viewer_step

We will demonstrate each workflow step through a very simple example in which we will be calculating the bandstructure of a SiC crystal. In the next tutorials, we will show how to use QuantumATK to calculate many other properties and teach you how to choose the simulation parameters to best suit your goals.

Create atomistic structure

Let’s start by opening QuantumATK NanoLab. There are two different ways to do it:

  1. by clicking the qatkicon QuantumATK NanoLab icon on the Desktop;
  2. by executing the quantumatk command in a terminal.

The Open Project window will appear where you can create |new_project|s and open existing ones. We will start by creating a new QuantumATK project with the title SiC_example.

../../_images/new_project_sic.png

Once you open a new project, you will see the main window of QuantumATK NanoLab showing the contents of the new SiC_example project folder. The project is currently empty.

We will start by loading a SiC BulkConfiguration using the Builder tool. The Builder tool is used to load, build, edit, visualize and inspect atomic configurations. It contains a plethora of built-in plugins for manipulating atomic configurations, as well as databases with built-in atomic configurations.

Let’s load a SiC crystal in the Builder tool. To open the Builder tool, click the qatkicon-nl-builder icon in the vertical toolbar on the left. Once you are in the Builder tool, let’s load a SiC crystal from the Database.

To open the Database click the add_icon and select From Database. Make sure you are at the Crystals tab, and type SiC in the text search. Double click the SiC configuration from the list to load it to the Builder.

../../_images/builder_database_sic.png

The SiC crystal should now be visible in the Builder. In the window on the right, you will see a small icon corresponding the SiC crystal. This window is also called Builder stash. It contains all the atomic configurations that you have created or loaded in the Builder.

In the central window of the Builder you will see a 3D graphical model of the SiC crystal. The central window is also referred to as the 3D Viewer. From here you can click, rotate, zoom or pan the atomic configuration selected in the stash window.

Set up calculation

Let’s create a bandstructure calculation for the SiC crystal loaded in the Builder tool. We will start by sending the SiC crystal from the Builder to the Workflows tool.

To send the SiC crystal from the Builder to the Workflows tool, click the qatkicon-builder-sendto Send to button and choose qatkicon-nl-workflow Workflows from the drop down menu. The Builder window is automatically replaced by the Workflows window.

../../_images/workflow_with_one_block.png

The Workflows tool is used to assemble calculation steps, which can be run through the Jobs tool. Each calculation step can be one QuantumATK Engine object. A catalog of built-in blocks, or calculation steps, are available under the QuantumATK tab in the right window.

We can see that the Workflows tool already contains the SiC crystal. This will be our first calculation step. Let’s complete the calculation steps in the current workflow by adding a calculator and an analysis object.

In the QuantumATK tab on the right find the qatkicon-scripter-calculator Set LCAOCalculator block and a qatkicon_bandstructure_icon Bandstructure analysis block. Drag the blocks from the list of QuantumATK blocks to the central window.

We have now created a workflow tree with one configuration, a calculator, and an analysis block. The qatkicon-scripter-calculator Set LCAOCalculator block will get the SiC crystal as an input, which is a BulkConfiguration object. The output of the block will be the BulkConfiguration object with an attached LCAOCalculator object. The qatkicon_bandstructure_icon Bandstructure block will get the BulkConfiguration with the attached LCAOCalculator as an input, and will output a Bandstructure object. After we run the workflow, the Bandstructure object will be the final result.

The created workflow was automatically saved as the SiC.hdf5 file in the Workflows folder. The file has extension .hdf5 and is available in the stash of workflows on the right, as well as in the Data.

Note

HDF5 is a data model, library, and file format for storing and managing data and is the format used for files storing QuantumATK objects.

The calculator computes the electronic ground state of the SiC crystal with DFT. It contains a wide range of settings, all of which have sensible default values. However, you will most often need to change at least a few of them in order to make the calculation match your scientific goals. Double-click the dropped LCAOCalculator block when you wish to edit it.

The Bandstructure block performs electronic ground state analysis of the SiC crystal. Double click the Bandstructure block to open its editor and to increase Points per sampling to 25.

../../_images/bandstructure_editor.png

Note

When changing the value of a field in the Bandstructure block editor, make sure to confirm the change by hitting Enter before closing the dialog. Otherwise, the change will not get saved.

At this step we can generate a Python script based on this workflow by clicking qatkicon-builder-sendto and sending it to the Editor tool.

../../_images/editor_analysis_SiC.png

We are now prepared to run the calculation on our local machine or a supercomputing cluster.

Run a job

There are different ways to run the created workflow. For example, we could export it to a script and run it from a terminal:

atkpython analysis_SiC_bulk.py > analysis_SiC_bulk.log

A very convenient alternative is to use the qatkicon-nl-jobs Jobs tool to run the script directly from inside QuantumATK NanoLab:

../../_images/workflow_with_export_script_dialog.png
  • Click the qatkicon-builder-sendto in the lower-right corner of the Workflows, and select Jobs as script from the menu.
  • The Export to script dialog appears, prompting you to export the workflow to a Python script and make sure it is saved. After saving the script, the Jobs window will open followed by the Submission Settings dialog.
  • Choose a Local machine type. This is your current machine. This option is automatically created after the installation of QuantumATK NanoLab. When you click OK, the QuantumATK Python script will be added to the job queue of the chosen machine.
  • Select your script and click the qatkicon-movietool-play button to start executing the calculation.
../../_images/jobs_tool_with_local_machine_dialog.png
../../_images/job_manager_with_one_task.png

Tip

See the Jobs tutorial for more instructions on using the Jobs for multi-CPU execution of QuantumATK Python scripts on your local machine and on remote supercomputers.

Analyze results

The calculation should last for about 20s. After it has finished, a new .hdf5 result file will appear in the Data tool. New .hdf5 files will be automatically scanned and their contents displayed in the central window of the Data.

You should be able to search and see the contents of the result file, analysis_SiC.hdf5. The content should include Bandstructure_0, BulkConfiguration_0 and LCAOCalculator_0, which correspond to the calculated Bandstructure object, the SiC crystal and the same SiC crystal with the attached LCAOCalculator.

Other files you will see include the Builder_Stash.hdf5, the qatkicon-nl-workflow sic_bulk workflow and the Python script analysis_SiC.py.

The Builder_Stash.hdf5 contains atomic configurations from the Builder stash. Currently there is only one qatkicon-scripter-bulk BulkConfiguration. The workflow sic_bulk is the workflow which we have just created. The analysis_SiC.py is the sic_bulk workflow exported as a Python script.

../../_images/data_view_with_results.png

To analyze the bandstructure results, search a bandstructure item in the Data and double click it to launch the Bandstructure analyzer. Both the direct and indirect band gaps are given by the analyzer.

../../_images/bandstructure_analyzer.png

You can download the workflow SiC.hdf5 and the results analysis_SiC.hdf5 here or in the Downloads & Links at the beginning of the page.

Looking at the band gap results you can clearly see that they are inaccurate. This is because we were using default parameters in the qatkicon-scripter-calculator LCAOCalculator and the qatkicon_bandstructure_icon Bandstructure blocks. To calculate the band gaps of SiC crystal the right way, follow the tutorial bandstructure_detailed.

What’s next

In the next tutorials we will show how to use QuantumATK to calculate many other properties and teach you how to choose the simulation parameters to best suit your goals.