From acfc5e0b98bf4b3cf3c5d73c692f45563ddcc54e Mon Sep 17 00:00:00 2001 From: Spyros Zoupanos Date: Wed, 21 Feb 2018 19:58:33 +0100 Subject: [PATCH 1/3] Adding documentation on link types --- docs/source/link_types/index.rst | 69 ++++++++++++++++++++++++ docs/source/working_with_aiida/index.rst | 8 +++ 2 files changed, 77 insertions(+) create mode 100644 docs/source/link_types/index.rst diff --git a/docs/source/link_types/index.rst b/docs/source/link_types/index.rst new file mode 100644 index 0000000000..1886c73ba3 --- /dev/null +++ b/docs/source/link_types/index.rst @@ -0,0 +1,69 @@ +Node classes +----------- +There are two *Node* sub-classes, *Data* and *Calculation*. The *Code* nodes +can be considered as sub-classes of *Data* nodes. *JobCalculations*, +*InlineCalulations* and the *WorkCalculations* are subclasses of the +*Calculation* class. + +AiIDA graph +----------- +The AiIDA graph is a `directed graph `_. +The links of the graph are arrows connecting two nodes. An arrow (x, y) is +considered to be directed from x to y; y is called the **head** and x is called +the **tail** of the arrow; y is said to be a **direct successor** of x and x +is said to be a **direct predecessor** of y. If a path leads from x to y, then +y is said to be a **successor** of x and reachable from x, and x is said to be a +**predecessor** of y. The arrow (y, x) is called the inverted arrow of (x, y). + +AiiDA links +----------- +The following table summarises the available AiiDA links and their properties. +Each line of the table corresponds to a different link, it mentions the tail +of the arrow (from column), the head of the arrow (to column) and finally +the constraints that are related to the label of the link and the nodes involved. + +========= =================== ================= ========================================== +Link type Tail of link (from) Head of link (to) Unique condition (combinations that should + be unique in the link table) +========= =================== ================= ========================================== +INPUT Data Calculation (head Calculation node, link label) +CREATE Calculation Data (head Data node) +RETURN Calculation Data (tail Calculation node, label) +CALL Calculation Calculation (head Calculation node) +========= =================== ================= ========================================== + + +There are four different links available: **INPUT**, **CREATE**, **RETURN** +and **CALL**. + +* The **INPUT** link is always from a *Data* node (tail of the link) to + a *Calculation* node (head of the link). The unique constraint means that + each *Calculation* node can have only one input *Data* node with given label + (i.e., a calculation cannot accept two inputs with the same label). + +* The **CREATE** link is always from a *Calculation* node (tail of the link) + to a *Data* node (head of the link). The unique constraint means that each + *Data* node can be created by one and only one *Calculation* node. + +* The **RETURN** link is always from a *Calculation* node (tail of the link) + to a *Data* node (head of the link). The unique constraint means that a + *Calculation* cannot return two or more *Data* nodes with the same label. Code + implementation detail: For the moment there is always and only a **CREATE** + link from a *JobCalculation* to the generated *Data*. A **RETURN** link is + implied with the conditions of a **RETURN** link (the implementation will be + corrected to comply shortly). + +* The **CALL** link is always from a *Calculation* to another *Calculation* + node. A given *Calculation* node cannot be called by more than one + *Calculation* node. In practice, the caller cannot be a *JobCalculation* but + it is always a *WorkCalculation*. Instead called calculations can be of any + subclass of *Calculation*. + +Graph navigation +---------------- +The links can be followed in both possible directions (forward & reverse) using +the QueryBuilder. This requires to define additional “names” for each direction +of the link, and they are documented at the +:doc:`QueryBuilder section <../querying/querybuilder/usage>`. For example, +if there is an **INPUT** link from data D to calculation C, D is the +“input_of” C, or equivalently D is the “output_of” C. diff --git a/docs/source/working_with_aiida/index.rst b/docs/source/working_with_aiida/index.rst index 75a3b90239..d7c65f8fc4 100644 --- a/docs/source/working_with_aiida/index.rst +++ b/docs/source/working_with_aiida/index.rst @@ -127,6 +127,14 @@ Interfaces have been written for some of the most used schedulers. ../scheduler/index +========== +Link types +========== + +.. toctree:: + :maxdepth: 4 + + ../link_types/index.rst ============= Querying data From 618d0860675e0f7260c55e4cc63bae8dd521f6b2 Mon Sep 17 00:00:00 2001 From: Spyros Zoupanos Date: Thu, 22 Feb 2018 11:08:24 +0100 Subject: [PATCH 2/3] Minor correction --- docs/source/link_types/index.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/link_types/index.rst b/docs/source/link_types/index.rst index 1886c73ba3..14c413e1b6 100644 --- a/docs/source/link_types/index.rst +++ b/docs/source/link_types/index.rst @@ -1,5 +1,5 @@ Node classes ------------ +------------ There are two *Node* sub-classes, *Data* and *Calculation*. The *Code* nodes can be considered as sub-classes of *Data* nodes. *JobCalculations*, *InlineCalulations* and the *WorkCalculations* are subclasses of the From 56079584b07ed950d7fafb4c6e24494b20da448a Mon Sep 17 00:00:00 2001 From: Spyros Zoupanos Date: Thu, 22 Feb 2018 11:37:43 +0100 Subject: [PATCH 3/3] More clarifications --- docs/source/link_types/index.rst | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/source/link_types/index.rst b/docs/source/link_types/index.rst index 14c413e1b6..e04686d8d0 100644 --- a/docs/source/link_types/index.rst +++ b/docs/source/link_types/index.rst @@ -66,4 +66,6 @@ the QueryBuilder. This requires to define additional “names” for each direct of the link, and they are documented at the :doc:`QueryBuilder section <../querying/querybuilder/usage>`. For example, if there is an **INPUT** link from data D to calculation C, D is the -“input_of” C, or equivalently D is the “output_of” C. +“input_of” C, or equivalently D is the “output_of” C. Currently, in the +QueryBuilder, input_of and output_of refer to any link type, where C is the +head of the arrow and D is the tail.