How to interact with AiiDA#
There are a variety of manners to interact with AiiDA:
Command line interface#
AiiDA comes with a command line interface called verdi.
The AiiDA Command Line section gives an overview of all available commands.
For more detailed information, refer to the topic section Command line interface.
Tip
The verdi command line interface can also be explored as a text-based user interface (TUI).
It requires aiida-core to be installed with the tui extra (e.g. pip install aiida-core[tui]).
The TUI can then be launched with verdi tui.
Scripts#
AiiDA’s Python API can be used in Python scripts mixed with any other Python code. The only requirement is that before the API is used an AiiDA profile is loaded. The recommended way of accomplishing this is to run the script through the command line interface:
verdi run script.py
The verdi CLI will automatically load the default profile, before calling the actual script, passing any command line arguments that may have been specified.
Note
A different profile can be selected using the --profile option, just as for all other verdi commands.
Alternatively, one can also add AiiDA’s specific shebang to the top of the file.
#!/usr/bin/env runaiida
When a script starts with this shebang, when it is executed, it is automatically passed to verdi run just as if it would have been called through verdi run directly.
This has the advantage that one no longer has to explicitly type verdi run when running the script, but can simply make it executable and execute it directly.
The downside is that it does not allow to specify a particular profile, but it always loads the default profile.
If, for whatever reason, verdi run nor the special shebang can be used, a profile can also be loaded directly through the API within the Python script itself:
from aiida import load_profile
load_profile()
One can pass a particular profile name to load_profile(), otherwise the default profile is loaded.
Within a script or Python instance, you can also switch to a different profile, or use one within a context manager:
from aiida import load_profile, profile_context, orm
with profile_context('my_profile_1'):
# The profile will be loaded within the context
node_from_profile_1 = orm.load_node(1)
# then the profile will be unloaded automatically
# load a global profile
load_profile('my_profile_2')
node_from_profile_2 = orm.load_node(1)
# switch to a different global profile
load_profile('my_profile_3', allow_switch=True)
node_from_profile_3 = orm.load_node(1)
Interactive shells#
AiiDA provides a Python API that can be used from an interactive shell, such as IPython. The recommended way of starting an interactive shell session to work with AiiDA, is through the command line interface:
$ verdi shell
This command will open a normal IPython shell but automatically loads the default AiiDA profile, which is required to use the Python API.
Note
A different profile can be selected using the --profile option, just as for all other verdi commands.
In addition to automatically loading an AiiDA profile, certain modules from AiiDA’s API that are used very often are automatically imported. The modules that are pre-loaded can be configured using the verdi config command.
If, for whatever reason, you cannot use verdi shell, a profile can also be loaded directly through the API within the shell itself:
In [1]: from aiida import load_profile
In [2]: load_profile()
Out[2]: <aiida.manage.configuration.profile.Profile at 0x7fccfd6c50a0>
One can pass a particular profile name to load_profile(), otherwise the default profile is loaded.
Interactive notebooks#
Similar to interactive shells, AiiDA is also directly compatbile with interactive Python notebooks, such as Jupyter. To use AiiDA’s Python API in a notebook, first a profile has to be loaded:
In [1]: from aiida import load_profile
In [2]: load_profile()
Out[2]: <aiida.manage.configuration.profile.Profile at 0x7fccfd6c50a0>
One can pass a particular profile name to load_profile(), otherwise the default profile is loaded.
The same can be accomplished using the following magic statement:
%load_ext aiida
%aiida
This magic line will replicate the same environment as the interactive shell provided by verdi shell.
However, it does require some one-time installation, as detailed in the section on how to Using AiiDA in Jupyter.
REST API#
AiiDA ships with a built in REST API, that allows you to query the data of a particular profile. Refer to section Launching the REST API to learn how to start the REST API. The section Querying the REST API provides information on how to interact with a running REST API.