---
myst:
  substitutions:
    VaspNEBCalculation: "{py:class}`VaspNEBCalculation <aiida_vasp.calcs.neb.VaspNEBCalculation>`"
    VaspCalculation: "{py:class}`VaspCalculation<aiida_vasp.calcs.vasp.VaspCalculation>`"
---

(vasp_calculation)=

# 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 {py:class}`CalcJobNode<aiida.orm.CalcJobNode>`, which is derived from a {py:class}`ProcessNode<aiida.orm.ProcessNode>` class.


An AiiDA-VASP calculation can be accessed by loading it using the {py:class}`CalculationFactory<aiida.plugins.factories.CalculationFactory>` from [AiiDA]:

```python
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:

```python
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 {py:class}`CalcJob<aiida.engine:CalcJob>` should not be confused with a {py:class}`CalcJobNode<aiida.orm: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 {py:class}`CalcJob<aiida.engine:CalcJob>` and {py:class}`WorkChain<aiida.engine: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 {py:func}`CalcFunctionNode<aiida.orm.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 {py:class}`Data <aiida.orm:Data>` object.

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

```python
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

```python
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
         }
      }
    },
  # ....
}
```



[verdi_shell]: https://aiida.readthedocs.io/projects/aiida-core/en/latest/howto/interact.html#how-to-interact-scripts