Using Tables in the Workflow Builder

Downloads & Links

showcase_table.hdf5
iteration_block_with_table.hdf5
table_iteration.hdf5

The Table is a powerful tool that can be used in a variety of situations. The main purpose is to collect data, for later analysis. Tables are also used as a container to pass initial training data to the ActiveLearningSimulation, etc.

In the next sections you will learn how to use the Table block and TableIteration block, through a set of simple examples:

• Table. The block that collect data in a table.

• TableIteration. The block that iterate over rows of a table.

These two blocks can be found in the Workflow Catalogs under Algorithm, and are very convenient ways to first collect data, and later process the collected data.

In the Downloads & Links sidebar you will find a list of all the workflows that are created in the following examples.

Table of Contents

• How to collect data in a table
  

• How to collect data in a table using an Iteration block
  

• How to extract data from a table using a TableIteration block
  

How to collect data in a table

The most simple workflow is to add a Configuration to a Table. Thus in this example we have placed a single Configuration block followed by a Table block.

The purpose of the Table block is to collect data in columns and rows, thus we need to specify how many columns the table should have, and which data type the column should accept.

Double click to edit the Table block. In this case we want a single column that contain a BulkConfiguration. Thus, the data type of the first column should be BulkConfiguration. Click on the Add button to add a column to the table specification.

Note

A Table consists of columns with different types of data and rows for each entry. The different data types for a column will be explained below.

Several column options are available:

• Type. This is the most generic column type. You simply need to specify the type of the objects to collect.

• PhysicalQuantity. Collects a PhysicalQuantity, and requires the unit of the PhysicalQuantity to collect.

• Configuration. Collects a Configuration, and a large array of setting for further specification. Such as to only collect MoleculeConfiguration, or only collect BulkConfiguration with a calculator attached, or only collect BulkConfiguration with a Simple Cubic Bravais lattice type, etc.

• NEB. Collects a NudgedElasticBand, and a large array of settings for further specification

• Calculator. Collects a Calculator, and a large array of settings for further specification, such as the type of calculator and supported elements.

Note

Type should only be used when one of the more specific column options cannot be used. Thus if we want to collect BulkConfigurations, we could do this using the Type column, but the Configuration column, allows you to specify more information, such as if the configuration have spatial regions, etc.

Select Configuration in the menu, in order to specify a column with a BulkConfiguration. We will later in this guide also use the Type, and the PhysicalQuantity column options.

Once the Configuration column have been added it should be visible in the list of columns, and it can be selected. Once selected the settings for the Configuration column become visible on the right in the Column Specification.

Specify BulkConfiguration as the configuration type in the widget.

The resulting workflow will place the provided bulk configuration into the table, resulting in a table with a single column and a single row.

Naturally this is a very simple example that is not very useful on its own. So in the next example we will go through a bigger more useful example.

How to collect data in a table using an Iteration block

A standard use case for the Table is to collect results using an Iteration block iteration_block_with_table.hdf5.

In this example we first define an Iteration block, where we loop over a k-point sampling parameter. The goal in this examples to determine if a k-point sampling of (9,9,9) is converged.

To specify the k-point sampling parameter we open the editor for the Iteration block. We click on the Add button to add an iterator to the Iteration block.

In this case we select the List of integers in the menu.

Fill in the name and values of the iterator. In this case we want to loop over the values (1,3,5,7,9).

Tip

Range of integers could also be used. For this example that would mean setting the Start to 1, Step size to 2, Steps to 4, resulting in a Stop of 9.

The attentive reader would notice, that the range specification is over determined. Thus changing Start, Step size or Steps will update Stop, while changing Stop will update Start.

The Iteration block, works as a Block of Blocks (see the Block of blocks) block and in this case it consist of 5 blocks:

• Configuration. This will create a configuration.

• Set LCAOCalculator. This will create a LCAOCalculator, set it on the configuration and update the configuration.

• TotalEnergy. Calculates a TotalEnergy analysis object.

• Extract total_energy. A Custom block that extract the total energy in eV from the TotalEnergy analysis object.

• Table. The table block.

First we modify the LCAO calculator to use the iterator. First a Monkhorst-Pack grid is selected and then the iterator sampling is selected using the in the A, B, C sampling fields

Secondly, we use a Custom block to extract the total energy from the TotalEnergy analysis object (see the What is a workflow block and how to edit it). The Custom blocks are very powerful and flexible blocks. They support insertion of custom QuantumATK scripts, thus allowing Custom blocks to serve as an interface to a complex calculation setup.

To extract the total energy from the TotalEnergy analysis object we must specify in the Inputs tab that the Custom block requires a TotalEnergy analysis object as input.

In the Outputs tab we need to specify that the Custom block returns a quantity in units of eV.

Finally in the Script tab we write the script to extract the total energy from the TotalEnergy object.

Running the calculation results in a table, that can be viewed in the Table Viewer. (The Table Viewer can be open using the data tool Analyzers and Preferences)

It is fairly easy to see that the total energy is converged to within 10 meV (or at least 4 significant digits).

How to extract data from a table using a TableIteration block

Imagine the scenario where you have just done the previous calculation, but realize that you also need to check that the direct bandgap is converged.

You can now load the previous Table using a Load from file block, and use the TableIteration to calculate the bandgap for each row of the table table_iteration.hdf5.

Note

When the Load from file block is used to load a Table from file. It will recognize it, and adapt the name and the icon of the Load from file block to Load Table with the Table icon. Load from file

The Load from file block is used to load the table. Use the Load from file button to specify the table.

The TableIteration block takes a table as input and provide the tables row information for each iteration. However, there could be many tables in the workflow and we thus need specify the columns we require to be present in the provided table. In other words we need to align the columns of the TableIteration block, with the columns of the Table.

The methodology is similar to specifying the Table block. Thus we need to specify a Configuration column, an integer column for the sampling, and a total energy column.

The Configuration column:

The integer column:

The total energy column:

Similar to the last example, we need a Custom block, in this case to extract the direct bandgap of a Bandstructure object. Thus we specify the Script tab of the Custom block

We furthermore need to specify in the Inputs tab of the Custom block, that a Bandstructure object is required as input.

In the Outputs tab of the Custom block, we specify that a physical quantity with units of eV is provided as output.

Finally we again collect the sampling and bandgaps in a table. Thus we again need to specify a number of columns to collect the data. In this case, lets collect the bandgap and the sampling.

The bandgap specification, is a PhysicalQuantity Column with the bandgap in units of eV:

The sampling specification, is a Type Column with the type specified as integer.

Resulting in the table, where it is clear that the direct bandgap is converged to within 1 meV (atleast 3 significant digits). (The Table Viewer can be open using the data tool Analyzers and Preferences)

We have now used the Table and TableIteration blocks, and hopefully shown how convenient, and versatile these can be. You can collect almost anything in a table, you can easily load a table using a Load from file block, and you can easily iterate over rows of a table.