Calculations

This page describes the basic concepts of calculations in AiiDA.

Basics

We call an AiiDA triggered execution of VASP a calculation job. The calculation job has to take some given input on AiiDA form and projects it to VASP in an understandable manner. Similarly, on termination, the calculation job has to parse the VASP output files such that the results are understandable for AiiDA and possibly also user friendly. In other words, a calculation job represents a single transaction with VASP.

In the database, a calculation job is represented by a CalcJobNode, which is derived from a ProcessNode class.

An AiiDA-VASP calculation can be accessed by loading it using the CalculationFactory from [AiiDA]:

some_calc = CalculationFactory('<plugin_namespace>.<calculation_name>')

from the verdi shell. If you want to load it from a python script, please have a look at verdi_shell. The <plugin_namespace> is always vasp for the AiiDA-VASP plugin. The <calculation_name> is the name of the file containing the module.

For instance, to load the two calculations mentioned above, we would issue:

vasp_calc = CalculationFactory('vasp.vasp')
vasp_neb = CalculationFactory('vasp.neb')

Definitions of calculations are placed in python modules inside the the src/aiida_vasp/calcs folder.

The general user should not care too much about the calculation itself as we believe it is better for the user to interact with VASP, or the other calculators from the workchains. Nevertheless, defining calculations is a crucial part of the plugin as it defines how we interact with VASP and how the input and output data are stored in the database.

Hint

A CalcJob should not be confused with a CalcJobNode. The former defines how a calculation should be run and the latter latter is for representing the stored data. All CalcJob will be stored as CalcJobNode objects, and the former can be accessed as the .process_class attribute of the latter.

Difference between calculation and workflow

In practice, both calculation and workflow takes some data and return some result, so what is the difference? From the provenance point of view, a calculation make generate new data while workflows only orchestrate calculations. Hence, a workflow should never return a Node that is not generated by some calculation, otherwise it means that the provenance is lost, i.e the returned data appears to be come from the void.

Hence, AiiDA make strict difference between a CalcJob and WorkChain.

If one want to perform additional operations based on returned data from VASP calculations, such operations should be wrapped inside a python function decorated by @calcfunction. Each call to such function creates a CalcFunctionNode with the input/output nodes, hence ensuring the provenance being fully recorded.

Defining calculation inputs

The calculation and workchains are processes in the terminology of AiiDA. Each are configured via a series of input nodes which are Data object.

The two common ways to launch a process is by using the submit or run_get_node functions in aiida.engine.

from aiida.engine import submit

submit(Process, **inputs)

where Process is a class of the process to be launched. In aiida-vasp, it may be VaspCalculation, VaspWorkChain or other provided processes. The inputs is a dictionary containing a nested key-value pairs defining inputs for each port of the process. A typical inputs dictionary for VaspWorkChain looks like

inputs = {
  'structure': si_structure,  # An instance of aiida.orm.StructureData
  'parameters': incar_tags,   # An instance of aiida.orm.Dict
  'calc':
    {'options':
      {'resources':
         {
          'num_machines': 1
         }
      }
    },
  # ....
}