AiiDA internals

Node

The AbstractNode class is the basic class that represents all the possible objects at the AiiDA world. More precisely it is inherited by many classes including (among others) the AbstractCalculation class, representing computations that convert data into a different form, the AbstractCode class representing executables and file collections that are used by calculations and the Data class which represents data that can be input or output of calculations.

Immutability concept

A node can store information through attributes. Since AiiDA guarantees a certain level of provenance, these attributes become immutable as soon as the node is stored. This means that as soon as a node is stored any attempt to alter its attributes, changing its value or deleting it altogether, shall be met with a raised exception. Certain subclasses of nodes need to adapt this behavior however, as for example in the case of the AbstractCalculation class (see calculation updatable attributes), but since the immutability of stored nodes is a core concept of AiiDA, this behavior is nonetheless enforced on the node level. This guarantees that any subclasses of the Node class will respect this behavior unless it is explicitly overriden.

Methods & properties

In the sequel the most important methods and properties of the AbstractNode class will be described.

Node subclasses organization

The AbstractNode class has two important variables:

  • ~aiida.orm.implementation.general.node.AbstractNode._plugin_type_string characterizes the class of the object.
  • ~aiida.orm.implementation.general.node.AbstractNode._query_type_string characterizes the class and all its subclasses (by pointing to the package or Python file that contain the class).

The convention for all the AbstractNode subclasses is that if a class B is inherited by a class A then there should be a package A under aiida/orm that has a file __init__.py and a B.py in that directory (or a B package with the corresponding __init__.py)

An example of this is the ArrayData and the KpointsData. ArrayData is placed in aiida/orm/data/array/__init__.py and KpointsData which inherits from ArrayData is placed in aiida/orm/data/array/kpoints.py

This is an implicit & quick way to check the inheritance of the AbstractNode subclasses.

General purpose methods

  • __init__(): The initialization of the Node class can be done by not providing any attributes or by providing a DbNode as initialization. E.g.:

    dbn = a_dbnode_object
    n = Node(dbnode=dbn.dbnode)
    
  • ctime() and mtime() provide the creation and the modification time of the node.

  • is_stored() informs whether a node is already stored to the database.

  • query() queries the database by filtering for the results for similar nodes (if the used object is a subclass of AbstractNode) or with no filtering if it is a AbstractNode class. Note that for this check _plugin_type_string should be properly set.

  • get_computer() returns the computer associated to this node.

  • _validate() does a validation check for the node. This is important for AbstractNode subclasses where various attributes should be checked for consistency before storing.

  • get_user() returns the user that created the node.

  • _increment_version_number_db(): increment the version number of the node on the DB. This happens when adding an attribute or an extra to the node. This method should not be called by the users.

  • copy() returns a not stored copy of the node with new UUID that can be edited directly.

  • uuid() returns the universally unique identifier (UUID) of the node.

  • pk() returns the principal key (ID) of the node.

  • dbnode() returns the corresponding Django object.

  • get_computer() & set_computer() get and set the computer to be used & is associated to the node.

Annotation methods

The AbstractNode can be annotated with labels, description and comments. The following methods can be used for the management of these properties.

Label management:

  • label() returns the label of the node. The setter method can be used for the update of the label.
  • _update_db_label_field() updates the label in the database. This is used by the setter method of the label.

Description management:

Comment management:

Folder management

Folder objects represent directories on the disk (virtual or not) where extra information for the node are stored. These folders can be temporary or permanent.

Store & deletion

  • store_all() stores all the input nodes, then it stores the current node and in the end, it stores the cached input links.
  • _store_input_nodes() stores the input nodes.
  • _check_are_parents_stored() checks that the parents are stored.
  • _store_cached_input_links() stores the input links that are in memory.
  • store() method checks that the node data is valid, then check if node’s parents are stored, then moves the contents of the temporary folder to the repository folder and in the end, it stores in the database the information that are in the cache. The latter happens with a database transaction. In case this transaction fails, then the data transfered to the repository folder are moved back to the temporary folder.
  • __del__() deletes temporary folder and it should be called when an in-memory object is deleted.

DbNode

The DbNode is the Django class that corresponds to the AbstractNode class allowing to store and retrieve the needed information from and to the database. Other classes extending the AbstractNode class, like Data, AbstractCalculation and AbstractCode use the DbNode code too to interact with the database. The main methods are:

  • get_aiida_class() which returns the corresponding AiiDA class instance.
  • get_simple_name() which returns a string with the type of the class (by stripping the path before the class name).
  • attributes() which returns the all the attributes of the specific node as a dictionary.
  • extras() which returns all the extras of the specific node as a dictionary.

Folders

AiiDA uses Folder and its subclasses to add an abstraction layer between the functions and methods working directly on the file-system and AiiDA. This is particularly useful when we want to easily change between different folder options (temporary, permanent etc) and storage options (plain local directories, compressed files, remote files & directories etc).

Folder

This is the main class of the available Folder classes. Apart from the abstraction provided to the OS operations needed by AiiDA, one of its main features is that it can restrict all the available operations within a given folder limit. The available methods are:

RepositoryFolder

Objects of this class correspond to the repository folders. The RepositoryFolder specific methods are:

  • __init__() initializes the object with the necessary folder names and limits.
  • get_topdir() returns the top directory.
  • section() returns the section to which the folder belongs. This can be for the moment a workflow or node.
  • subfolder() returns the subfolder within the section/uuid folder.
  • uuid() the UUID of the corresponding node or workflow.

SandboxFolder

SandboxFolder objects correspond to temporary (“sandbox”) folders. The main methods are:

Calculation

Updatable attributes

The AbstractCalculation class is a subclass of the AbstractNode class, which means that its attributes become immutable once stored. However, for a Calculation to be runnable it needs to be stored, but that would mean that its state, which is stored in an attribute can no longer be updated. To solve this issue the Sealable mixin is introduced. This mixin can be used for subclasses of Node that need to have updatable attributes even after the node has been stored in the database. The mixin defines the _updatable_attributes tuple, which defines the attributes that are considered to be mutable even when the node is stored. It also allows the node to be sealed, after which even the updatable attributes become immutable.

ORM overview

Below you find an overview of the main classes in the AiiDA object-relational mapping. For the complete API documentation see aiida.orm.