Skip to content

Latest commit

 

History

History
368 lines (216 loc) · 23.5 KB

internals.rst

File metadata and controls

368 lines (216 loc) · 23.5 KB
Raw

AiiDA internals

Node

The :py:class:`~aiida.orm.implementation.general.node.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 :py:class:`~aiida.orm.implementation.general.calculation.AbstractCalculation` class, representing computations that convert data into a different form, the :py:class:`~aiida.orm.implementation.general.code.AbstractCode` class representing executables and file collections that are used by calculations and the :py:class:`~aiida.orm.data.Data` class which represents data that can be input or output of calculations.

Methods & properties

In the sequel the most important methods and properties of the :py:class:`~aiida.orm.implementation.general.node.AbstractNode` class will be described.

Node subclasses organization

The :py:class:`~aiida.orm.implementation.general.node.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 :py:class:`~aiida.orm.implementation.general.node.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 :py:class:`~aiida.orm.data.array.ArrayData` and the :py:class:`~aiida.orm.data.array.kpoints.KpointsData`. :py:class:`~aiida.orm.data.array.ArrayData` is placed in aiida/orm/data/array/__init__.py and :py:class:`~aiida.orm.data.array.kpoints.KpointsData` which inherits from :py:class:`~aiida.orm.data.array.ArrayData` is placed in aiida/orm/data/array/kpoints.py

This is an implicit & quick way to check the inheritance of the :py:class:`~aiida.orm.implementation.general.node.AbstractNode` subclasses.

General purpose methods

Annotation methods

The :py:class:`~aiida.orm.implementation.general.node.AbstractNode` can be annotated with labels, description and comments. The following methods can be used for the management of these properties.

Label management:

Description management:

Comment management:

Link management methods

:py:class:`~aiida.orm.implementation.general.node.AbstractNode` objects and objects of its subclasses can have ancestors and descendants. These are connected with links. The following methods exist for the processing & management of these links.

Listing links example

Assume that the user wants to see the available links of a node in order to understand the structure of the graph and maybe traverse it. In the following example, we load a specific node and we list its input and output links. The returned dictionaries have as keys the link name and as value the linked node. Here is the code:

In [1]: # Let's load a node with a specific pk

In [2]: c = load_node(139168)

In [3]: c.get_inputs_dict()
Out[3]:
{u'code': <Code: Remote code 'cp-5.1' on daint, pk: 75709, uuid: 3c9cdb7f-0cda-402e-b898-4dd0d06aa5a4>,
 u'parameters': <ParameterData: uuid: 94efe64f-7f7e-46ea-922a-fe64a7fba8a5 (pk: 139166)>,
 u'parent_calc_folder': <RemoteData: uuid: becb4894-c50c-4779-b84f-713772eaceff (pk: 139118)>,
 u'pseudo_Ba': <UpfData: uuid: 5e53b22d-5757-4d50-bbe0-51f3b9ac8b7c (pk: 1905)>,
 u'pseudo_O': <UpfData: uuid: 5cccd0d9-7944-4c67-b3c7-a39a1f467906 (pk: 1658)>,
 u'pseudo_Ti': <UpfData: uuid: e5744077-8615-4927-9f97-c5f7b36ba421 (pk: 1660)>,
 u'settings': <ParameterData: uuid: a5a828b8-fdd8-4d75-b674-2e2d62792de0 (pk: 139167)>,
 u'structure': <StructureData: uuid: 3096f83c-6385-48c4-8cb2-24a427ce11b1 (pk: 139001)>}

In [4]: c.get_outputs_dict()
Out[4]:
{u'output_parameters': <ParameterData: uuid: f7a3ca96-4594-497f-a128-9843a1f12f7f (pk: 139257)>,
 u'output_parameters_139257': <ParameterData: uuid: f7a3ca96-4594-497f-a128-9843a1f12f7f (pk: 139257)>,
 u'output_trajectory': <TrajectoryData: uuid: 7c5b65bc-22bb-4b87-ac92-e8a78cf145c3 (pk: 139256)>,
 u'output_trajectory_139256': <TrajectoryData: uuid: 7c5b65bc-22bb-4b87-ac92-e8a78cf145c3 (pk: 139256)>,
 u'remote_folder': <RemoteData: uuid: 17642a1c-8cac-4e7f-8bd0-1dcebe974aa4 (pk: 139169)>,
 u'remote_folder_139169': <RemoteData: uuid: 17642a1c-8cac-4e7f-8bd0-1dcebe974aa4 (pk: 139169)>,
 u'retrieved': <FolderData: uuid: a9037dc0-3d84-494d-9616-42b8df77083f (pk: 139255)>,
 u'retrieved_139255': <FolderData: uuid: a9037dc0-3d84-494d-9616-42b8df77083f (pk: 139255)>}

Understanding link names

The nodes may have input and output links. Every input link of a node should have a unique name and this unique name is mapped to a specific node. On the other hand, given a node c, many output nodes may share the same output link name. To differentiate between the output nodes of c that have the same link name, the pk of the output node is added next to the link name (please see the input & output nodes in the above example).

Input/output related methods

The input/output links of the node can be accessed by the following methods.

Methods to get the input data

Methods to get the output data

Navigating in the ``node`` graph

The user can easily use the :py:meth:`~aiida.orm.implementation.general.node.NodeInputManager` and the :py:meth:`~aiida.orm.implementation.general.node.NodeOutputManager` objects of a node (provided by the :py:meth:`~aiida.orm.implementation.general.node.AbstractNode.inp` and :py:meth:`~aiida.orm.implementation.general.node.AbstractNode.out` respectively) to traverse the node graph and access other connected nodes. :py:meth:`~aiida.orm.implementation.general.node.AbstractNode.inp` will give us access to the input nodes and :py:meth:`~aiida.orm.implementation.general.node.AbstractNode.out` to the output nodes. For example:

In [1]: # Let's load a node with a specific pk

In [2]: c = load_node(139168)

In [3]: c
Out[3]: <CpCalculation: uuid: 49084dcf-c708-4422-8bcf-808e4c3382c2 (pk: 139168)>

In [4]: # Let's traverse the inputs of this node.

In [5]: # By typing c.inp. we get all the input links

In [6]: c.inp.
c.inp.code                c.inp.parent_calc_folder  c.inp.pseudo_O            c.inp.settings
c.inp.parameters          c.inp.pseudo_Ba           c.inp.pseudo_Ti           c.inp.structure

In [7]: # We may follow any of these links to access other nodes. For example, let's follow the parent_calc_folder

In [8]: c.inp.parent_calc_folder
Out[8]: <RemoteData: uuid: becb4894-c50c-4779-b84f-713772eaceff (pk: 139118)>

In [9]: # Let's assign to r the node reached by the parent_calc_folder link

In [10]: r = c.inp.parent_calc_folder

In [11]: r.inp.__dir__()
Out[11]:
['__class__',
 '__delattr__',
 '__dict__',
 '__dir__',
 '__doc__',
 '__format__',
 '__getattr__',
 '__getattribute__',
 '__getitem__',
 '__hash__',
 '__init__',
 '__iter__',
 '__module__',
 '__new__',
 '__reduce__',
 '__reduce_ex__',
 '__repr__',
 '__setattr__',
 '__sizeof__',
 '__str__',
 '__subclasshook__',
 '__weakref__',
 u'remote_folder']

In [12]: r.out.
r.out.parent_calc_folder         r.out.parent_calc_folder_139168

In [13]: # By following the same link from node r, you will get node c

In [14]: r.out.parent_calc_folder
Out[14]: <CpCalculation: uuid: 49084dcf-c708-4422-8bcf-808e4c3382c2 (pk: 139168)>

Attributes related methods

Each :py:meth:`~aiida.orm.implementation.general.node.AbstractNode` object can have attributes which are properties that characterize the node. Such properties can be the energy, the atom symbols or the lattice vectors. The following methods can be used for the management of the attributes.

Extras related methods

Extras are additional information that are added to the calculations. In contrast to files and attributes, extras are information added by the user (user specific).

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

DbNode

The :py:class:`~aiida.backends.djsite.db.models.DbNode` is the Django class that corresponds to the :py:class:`~aiida.orm.implementation.general.node.AbstractNode` class allowing to store and retrieve the needed information from and to the database. Other classes extending the :py:class:`~aiida.orm.implementation.general.node.AbstractNode` class, like :py:class:`~aiida.orm.data.Data`, :py:class:`~aiida.orm.implementation.general.calculation.AbstractCalculation` and :py:class:`~aiida.orm.implementation.general.code.AbstractCode` use the :py:class:`~aiida.backends.djsite.db.models.DbNode` code too to interact with the database. The main methods are:

Folders

AiiDA uses :py:class:`~aiida.common.folders.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).

:py:class:`~aiida.common.folders.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:

:py:class:`~aiida.common.folders.RepositoryFolder`

Objects of this class correspond to the repository folders. The :py:class:`~aiida.common.folders.RepositoryFolder` specific methods are:

:py:class:`~aiida.common.folders.SandboxFolder`

:py:class:`~aiida.common.folders.SandboxFolder` objects correspond to temporary ("sandbox") folders. The main methods are: