Introduction

The main way of interacting with AiiDA is through a command line interface tool called verdi. You have already used verdi when installing AiiDA, either through verdi quicksetup or verdi setup. But verdi is very versatile and provides a wealth of other functionalities; here is a list:

  • code: Setup and manage codes.
  • comment: Inspect, create and manage comments.
  • computer: Setup and manage computers.
  • config: Set, unset and get profile specific or global configuration options.
  • daemon: Inspect and manage the daemon.
  • data: Inspect, create and manage data nodes.
  • devel: Commands for developers.
  • export: Create and manage export archives.
  • graph: Create visual representations of the provenance graph.
  • group: Inspect, create and manage groups.
  • import: Import one or multiple exported AiiDA archives
  • node: Inspect, create and manage nodes.
  • process: Inspect and manage processes.
  • profile: Inspect and manage the configured profiles.
  • quicksetup: Quick setup for the most common usecase (1 user, 1 machine).
  • rehash: Recompute the hash for nodes in the database
  • restapi: Run the AiiDA REST API server
  • run: Execute an AiiDA script.
  • setup: Setup and configure a new profile.
  • shell: Start a python shell with preloaded AiiDA environment.
  • status: Show service status overview.
  • user: Inspect and manage users.

Concepts

In this section, a few basic concepts of the command line interface will be explained that will apply to all the verdi commands.

Help strings

Each verdi command and any optional sub commands have automatically generated help strings that explain the command’s functionality and usage. To show the help string for any command, simply append the --help option. For example verdi calculation kill --help will display:

Usage: verdi calculation kill [OPTIONS] [CALCULATIONS]...

  Kill one or multiple running calculations.

Options:
  -f, --force  do not ask for confirmation
  -h, --help   Show this message and exit.

All help strings have the same format and consist of three parts:

  • A usage line describing how to invoke and the accepted parameters
  • A description of the commands functionality
  • A list of the available options

The [OPTIONS] and [CALCULATIONS]... tags in the usage description, denote the ‘parameters’ that the command takes. A more detailed description of the available options will be listed after the description of the commands functionality The positional arguments will only be described in the command description itself. For a more detailed explanation of the difference between options and arguments, see the section about command line parameters.

Parameters

Most of the verdi commands and their subcommands can take one or multiple parameters. In the language of command line interfaces, these parameters come in two flavors:

  • Options
  • Arguments

Arguments are positional parameters, whereas options are indicated by a flag that precedes the value, typically of the form -f, or --flag. The command line help string section explained that each command will have a help string with a usage line, for example:

Usage: verdi calculation kill [OPTIONS] [CALCULATIONS]...

The [OPTIONS] tag indicates that the command takes one or multiple options and one or multiple [CALCULATIONS] as arguments. The square brackets in the usage line, indicate that the parameter is optional and not required. Three dots ... following a parameter indicate that it can not take just one, but also more than one values.

Profile

AiiDA supports multiple profiles per installation, that can each be configured to use different databases. One of these profiles will always be marked as the default profile. To show the current default profile, execute the command:

verdi profile list

The default profile will be highlighted. By default, all verdi commands will always use the default profile. Having to change the default profile, anytime one wants to apply the verdi command to another profile is cumbersome. Therefore, each verdi command supports the -p/--profile option, that will force verdi to use the given profile. For example, if you wanted to display the list of calculations for a profile that is not the current default, you can execute:

verdi -p <profile> calculation list

Note that the specified profile will be used for this and only this command. All subsequent commands, when no specific profile is given, will return to using the default profile.

Identifiers

Many commands will support arguments or options that serve to identify specific entities in the database, such as nodes, users, groups etc. Any entity in AiiDA typically will have three different types of identifier:

  • ID: the integer primary key in the database
  • UUID: the universally unique identifier, a dash-separated hexadecimal string
  • LABEL: a custom string-based label

The ID and UUID identifiers follow the exact same rules for all the entities in AiiDA’s data model. However, the LABEL will vary from entity to entity. For a Code instance it will be the label attribute, whereas for a Group instance, it will be its name.

All verdi command arguments and options that serve to pass an entity identifier, will automatically deduce the intended identifier type. However, since the type of the value is lost over the command line (as each value will be passed as a string type), the command line will have to guess the type. Each value will first be interpreted as an ID. If the value cannot be mapped to the ID of an entity, it will instead be considered a partial or full UUID. In the case where the identifier can be resolved to neither a valid ID nor a UUID, the code will finally assume that the value should be interpreted as a LABEL. In almost all cases, this approach will be able to successfully and unambiguously determine the identifier type, however, there are exceptions.

Consider for example a database with the following three groups:

ID UUID LABEL
10 12dfb104-7b2b-4bca-adc0-1e4fd4ffcc88 group
11 deadbeef-62ba-444f-976d-31d925dac557 10
12 3df34a1e-5215-4e1a-b626-7f75b9586ef5 deadbeef

We would run into trouble if we wanted to identify the second group by its label 10, since it would first be interpreted as an ID, which would return the first group instead. Likewise, if we wanted to retrieve the third group by its label, we would get the second group instead, since the label deadbeef is also a valid partial UUID of the second group. Finally, say we wanted to select the first group using its partial UUID 12, it would unfortunately match the third group on its ID instead.

Luckily, verdi provides the tools to break all of these ambiguities with guaranteed success. The latter ambiguity, between an ID and UUID can always be resolved by passing a larger partial UUID. Inevitably, eventually a non-numeric character or a dash will be included in the partial UUID, rendering it an invalid ID and the identifier will be cast to the right type. The case of an identifier, that is intended to refer to a LABEL, that just happens to also be a valid ID or UUID cannot be solved in this way. For this case verdi reserves a special character, the exclamation mark ! that can be appended to the identifier. Before any type guessing is done, the command line will check for the presence of this marker, and if found will directly interpret the identifier as a LABEL. For example, to solve ambiguity problems of the first two examples given in this section, one would have had to pass 10! and deadbeef!. The exclamation point would have forced them to be interpreted as a LABEL and ensured that the right group would be retrieved.

In summary, to guarantee correct identification of a specific type:

  • UUID: include at least one non-numeric character or dash in the partial identifier
  • LABEL: append an exclamation mark ! at the end of the identifier

Multi value options

The section on command line parameters explained that some commands support options and arguments that take one or multiple values. This is fairly typical for command line arguments, but slightly more unorthodox for options, that typically only ever take one value, or none at all if it is a flag. However, verdi has multiple commands where an option needs to be able to support options that take more than one value. Take for example the verdi export create command, with part of its help string:

Usage: verdi export create [OPTIONS] OUTPUT_FILE

  Export various entities, such as Codes, Computers, Groups and Nodes, to an
  archive file for backup or sharing purposes.

Options:
  -X, --codes CODE...             one or multiple codes identified by their
                                  ID, UUID or label
  -Y, --computers COMPUTER...     one or multiple computers identified by
                                  their ID, UUID or label
  -G, --groups GROUP...           one or multiple groups identified by their
                                  ID, UUID or name
  -N, --nodes NODE...             one or multiple nodes identified by their ID
                                  or UUID

The file to which the export archive should be written is given by the argument OUTPUT_FILE and the command supports various identifier options, e.g. CODE... and NODE..., that allow the user to specify which entities should be exported. Note the terminal dots ... that indicate that the options take one or more values. In traditional command line interfaces, one would have to repeat the option flag if multiple values needed to be specified, e.g.:

verdi export create -N 10 -N 11 -N 12 archive.aiida

However, for large numbers of values, this gets cumbersome, which is why verdi supports so-called multiple value options, that allow this to be rewritten as:

verdi export create -N 10 11 12 archive.aiida

Unfortunately, this leads to an ambiguity, as the ‘greedy’ multi value option -N will interpret the argument archive.aiida as an option value. This will cause the command to abort if the validation fails, but even worse it might be silently accepted. The root of the problem is that the multi value option needs to necessarily be greedy and cannot distinguish which value belongs to it and which value is just another argument. The typical solution for this problem is to use the so called ‘endopts’ marker, which is defined as two dashes --, which can be used to mark the end of the options and clearly distinguish them from the arguments. The previous command can therefore be made unambiguous as follows:

verdi export create -N 10 11 12 -- archive.aiida

This time the parser will notice the -- end options marker and correctly identify archive.aiida as the positional argument.

Commands

Below is a list with all the available subcommands.

verdi code

Setup and manage code objects.

  • delete: delete a code from the database. Only possible for disconnected codes (i.e. a code that has not been used yet)
  • duplicate: setup a new code, starting from the settings of an existing one
  • hide: hide codes from verdi code list
  • list: lists the installed codes
  • relabel: change the label (name) of a code. If you like to load codes based on their labels and not on their UUID’s or PK’s, make sure to use unique labels!
  • reveal: un-hide codes for verdi code list
  • setup: setup a new code
  • show: shows the information of the installed code

verdi comment

There are various ways of attaching notes/comments to a node within AiiDA. In the first scripting examples, you might already have noticed the possibility of storing a label or a description to any AiiDA Node. However, these properties are defined when the Node is created, and it is not possible to modify them after the Node has been stored. The Node comment provides a simple way to have a more dynamic management of comments, in which any user can write a comment on the Node, or modify it or delete it. The verdi comment command provides a set of methods that are used to manipulate the comments:

  • add: add a new comment to a Node
  • remove: remove a comment
  • show: show the existing comments attached for a given Node
  • update: modify a comment

verdi computer

Setup and manage computer objects.

  • configure: set up some extra info that can be used in the connection with that computer
  • delete: deletes a computer node. Works only if the computer node is a disconnected node in the database (has not been used yet)
  • disable: disable a computer (see enable for a larger description)
  • enable: to enable a computer. If the computer is disabled, the daemon will not try to connect to the computer, so it will not retrieve or launch calculations. Useful if a computer is under mantainance
  • list: list all installed computers
  • rename: changes the name of a computer
  • setup: creates a new computer object
  • show: shows the details of an installed computer
  • test: tests if the current user (or a given user) can connect to the computer and if basic operations perform as expected (file copy, getting the list of jobs in the scheduler queue, …)
  • duplicate: setup a new computer, starting from the settings of an existing one
  • update: [deprecated: use verdi computer duplicate instead] change configuration of a computer. Works only if the computer node is a disconnected node in the database (has not been used yet)

verdi config

This command allows you to set various configuration options that change how AiiDA works. The options can be set for specific profiles or globally. The command works just like git config does. Only passing the option name as an argument will print its value, if it is set. Passing a value as a second argument, will set that value for the given option. With the --unset flag an option can be unset and by using --global the get, set or unset operation is applied globally instead of the default profile.

verdi daemon

Manage the daemon, i.e. the process that runs in background and that manages submission/retrieval of calculations and workflows.

  • decr: decrease the number of workers of the daemon
  • incr: increase the number of workers of the daemon
  • logshow: show the last lines of the daemon log (use for debugging)
  • restart: restarts the daemon
  • start: starts the daemon
  • status: see the status of the daemon
  • stop: stops the daemon

verdi data

Manage Data nodes.

  • array: handles aiida.orm.nodes.data.array.ArrayData objects
    • show: visualizes the data object
  • bands: handles aiida.orm.nodes.data.array.bands.BandsData objects (band structure object)
  • cif: handles the CifData objects
    • deposit: deposit the node to a remote database
    • export: export the node as a string of a specified format
    • import: create or return (if already present) a database node, having the contents of a supplied file
    • list: list currently saved nodes of CifData kind
    • show: use third-party visualizer (like jmol) to graphically show the CifData
  • parameter: handles the Dict objects
    • show: output the content of the python dictionary in different formats.
  • remote: handle RemoteData objects
    • cat: output the content of a file in the RemoteData folder.
    • ls: list the contents of the RemoteData folder.
    • show: display general information about the RemoteData object.
  • structure: handles the StructureData
    • deposit: deposit the node to a remote database
    • export: export the node as a string of a specified format
    • import: import a StructureData node from file
    • list: list currently saved nodes of StructureData kind
    • show: use a third-party visualizer (like vmd or xcrysden) to graphically show the StructureData
  • trajectory: handles the TrajectoryData objects
    • deposit: deposit the node to a remote database
    • export: export the node as a string of a specified format
    • list: list currently saved nodes of TrajectoryData kind
    • show: use third-party visualizer (like jmol) to graphically show the TrajectoryData
  • upf: handles the Pseudopotential Datas
    • exportfamily: export a family of pseudopotential files into a folder
    • import: create or return (if already present) a database node, having the contents of a supplied file
    • listfamilies: list presently stored families of pseudopotentials
    • uploadfamily: install a new family (group) of pseudopotentials

verdi devel

Commands intended for developers, such as setting config properties and running the unit test suite.

  • run_daemon: run an instance of the daemon runner in the current interpreter
  • tests: run the unittest suite

verdi export

Create and manage export archives.

  • create: export a selection of nodes to an aiida export file. See also verdi import and the Export File format.
  • migrate: migrate export archives between file format versions.

verdi graph

Create graphical representations of part of the provenance graph. Requires that graphviz be installed.

  • generate: generates a graph from a given root node either in a graphical or a .dot format.

verdi group

Create and manage group objects.

  • addnodes: add nodes to a group.
  • list: list all the groups in the database.
  • description: show or change the description of a group
  • show: show the content of a group.
  • create: create a new empty group.
  • rename: change the name of a group.
  • delete: delete an existing group (but not the nodes belonging to it).
  • removenodes: remove nodes from a group.

verdi help

This command is deprecated, please use verdi --help instead

verdi import

Import archive files that were created with verdi export create.

verdi install

This command is deprecated, please use the setup command instead

verdi node

Manage Node instances from the provenance graph.

  • delete: delete a node and all its descendants from the provenance graph
  • description: view or set the description of a node
  • label: view or set the label of a node
  • repo: shows files and their contents in the local repository
  • show: shows basic node information (PK, UUID, class, inputs and outputs)
  • tree: shows a tree represenatation in ASCII of the node and its links

Warning

In order to preserve the provenance, verdi node delete will delete not only the list of specified nodes, but also all the children nodes! So please be sure to double check what is going to be deleted before running this function. This command cannot be undone.

verdi process

Inspect and manage processes.

  • list: Show a list of processes that are still running.
  • kill: Kill running processes.
  • pause: Pause running processes.
  • play: Play paused processes.
  • watch: Watch the state transitions for a process.

verdi profile

List and change the default profiles.

  • delete: delete a profile and the corresponding database and repository
  • list: show the list of currently available profiles and the current default profile
  • setdefault: set the default profile, i.e. the profile that is used for all verdi commands if not explicitly specified

verdi quicksetup

Set up a sane aiida configuration with as little interaction as possible.

verdi rehash

Rehash all nodes in the database filtered by their identifier and/or based on their class.

verdi restapi

Run an instance of the REST API server on localhost.

verdi run

Run a python script for AiiDA. This is the command line equivalent of the verdi shell. Has also features of autogrouping: by default, every node created in one a call of verdi run will be grouped together.

verdi setup

Create and setup a new profile.

verdi shell

Start a python shell with preloaded AiiDA environment. Which modules will be preloaded can be configured through properties set in the configuration file.

verdi status

Show overview of status for services needed by AiiDA. This can be helpful for pinning down potential problems during debugging.

verdi user

Configure and manage users

  • configure: configure a new AiiDA user
  • list: list existing users configured for your AiiDA installation