Setup a code¶
Once you have at least one computer configured, you can configure the codes. In AiiDA, for full reproducibility of each calculation, we store each code in the database, and attach to each calculation a given code. This has the further advantage to make very easy to query for all calculations that were run with a given code (for instance because I am looking for phonon calculations, or because I discovered that a specific version had a bug and I want to rerun the calculations).
In AiiDA, we distinguish two types of codes: remote codes and local codes, where the distinction between the two is described here below.
With remote codes we denote codes that are installed/compiled on the remote computer. Indeed, this is very often the case for codes installed in supercomputers for high-performance computing applications, because the code is typically installed and optimized on the supercomputer.
In AiiDA, a remote code is identified by two mandatory pieces of information:
- A computer on which the code is (that must be a previously configured computer);
- The absolute path of the code executable on the remote computer.
With local codes we denote codes for which the code is not already present on the remote machine, and must be copied for every submission. This is the case if you have for instance a small, machine-independent Python script that you did not copy previously in all your clusters.
In AiiDA, a local code can be set up by specifying:
- A folder, containing all files to be copied over at every submission
- The name of executable file among the files inside the folder specified above
Setting up a code¶
command allows to manage codes in AiiDA.
To setup a new code, you execute:
verdi code setup
and you will be guided through a process to setup your code.
The setup will ask you a few pieces of information. At every prompt, you can
? character and press
<enter> to get a more detailed
explanation of what is being asked.
You will be asked for:
- Label: A label to refer to this code. Note: this label is not enforced
to be unique. However, if you try to keep it unique, at least within
the same computer, you can use it later
to refer and use to your code. Otherwise, you need to remember its
- Description: A human-readable description of this code (for instance “Quantum Espresso v.5.0.2 with 5.0.3 patches, pw.x code, compiled with openmpi”).
- Default calculation input plugin: A string that identifies the default input plugin to
be used to generate new calculations to use with this code.
This string has to be a valid string recognized by the
CalculationFactoryfunction. To get the list of all available Calculation plugin strings, use the
verdi plugin list aiida.calculationscommand.
- Installed on target computer: either True (for local codes) or False (for remote
codes). For the meaning of the distinction, see above. Depending
on your choice, you will be asked for:
- REMOTE CODES:
- Remote computer name: The computer name on which the code resides, as configured and stored in the AiiDA database.
- Remote absolute path: The (full) absolute path of the code executable on the remote machine, including the name of the executable.
- LOCAL CODES:
- Local directory containing the code: The absolute path where the executable and all other files needed to run the code are stored; these will be copied over to the remote computers for every submitted calculation.
- Relative path of executable inside code folder: The relative path of the executable file inside the folder entered in the previous step.
- REMOTE CODES:
At the end of these steps, you will be prompted to edit a script,
and you will have the opportunity to include
bash commands that will
be executed before running the submission script (after the
‘pre execution script’ lines) and after running the submission script
(after the ‘Post execution script’ separator).
This is intended for code-dependent settings, for instance to load modules or set variables
that are needed by the code. For example:
module load intelmpi
At the end, you will get a confirmation command, and also the ID of the code in the
pk, i.e. the principal key, and the
In a manner analogous to a computer setup, it is also possible to provide some (or all) the information described above via a configuration file using
verdi code setup --config code.yml
code.yml is a configuration file in the
This file contains the information in a series of key:value pairs:
--- label: "qe-6.3-pw" description: "quantum_espresso v6.3" input_plugin: "quantumespresso.pw" on_computer: true remote_abs_path: "/path/to/code/pw.x" computer: "localhost" prepend_text: | module load module1 module load module2 append_text: " "
The keys mirror the available options of the command, which you can print using:
verdi code setup --help
Note the syntax differences: remove the
- within the keys by the underscore
Codes are a subclass of the
and as such you can attach any set of attributes to the code. These can
be extremely useful for querying: for instance, you can attach the version
of the code as an attribute, or the code family (for instance: “pw.x code of
Quantum Espresso”) to later query for all runs done with a pw.x code and
version more recent than 5.0.0, for instance. However, in the
present AiiDA version you cannot add attributes from the command line using
verdi, but you have to do it using Python code.
You can change the label of a code by using the following command:
verdi code relabel "ID" "new-label"
(Without the quotation marks!) “ID” can either be the numeric ID (PK) of
the code (preferentially), or possibly its label (or
if this string uniquely identifies a code.
You can also list all available codes (and their relative IDs) with:
verdi code list
which also accepts some flags to filter only codes on a
given computer, only codes using a specific plugin, etc.; use the
command line option to see the documentation of all possible options.
You can then get the information of a specific code with:
verdi code show "ID"
Finally, to delete a code use:
verdi code delete "ID"
(only if it wasn’t used by any calculation, otherwise an exception is raised).
And now, you are ready to launch your calculations!