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
- Typical workflow
- Create atomistic structure
- Set up calculation
- Run a job
- Analyze results
- What’s next
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
|
|||
---|---|---|---|---|---|---|
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:
- by clicking the QuantumATK NanoLab icon on the Desktop;
- 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.
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 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 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.
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 Send to button and choose Workflows from the drop down menu. The Builder window is automatically replaced by the Workflows window.
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 Set LCAOCalculator block and a 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 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 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.
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 and sending it to the Editor tool.
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 Jobs tool to run the script directly from inside QuantumATK NanoLab:
- Click the 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 button to start executing the calculation.
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 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 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.
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.
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 LCAOCalculator
and the 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.