# aiida.tools.graph package¶

Provides tools for traversing the provenance graph.

aiida.tools.graph.delete_group_nodes(pks: Iterable[int], dry_run: Union[bool, Callable[[Set[int]], bool]] = True, **traversal_rules: bool) → Tuple[Set[int], bool][source]

Delete nodes contained in a list of groups (not the groups themselves!).

This command will delete not only the nodes, but also the ones that are linked to these and should be also deleted in order to keep a consistent provenance according to the rules explained in the concepts section of the documentation. In summary:

1. If a DATA node is deleted, any process nodes linked to it will also be deleted.

2. If a CALC node is deleted, any incoming WORK node (callers) will be deleted as well whereas any incoming DATA node (inputs) will be kept. Outgoing DATA nodes (outputs) will be deleted by default but this can be disabled.

3. If a WORK node is deleted, any incoming WORK node (callers) will be deleted as well, but all DATA nodes will be kept. Outgoing WORK or CALC nodes will be kept by default, but deletion of either of both kind of connected nodes can be enabled.

These rules are ‘recursive’, so if a CALC node is deleted, then its output DATA nodes will be deleted as well, and then any CALC node that may have those as inputs, and so on.

Parameters
• pks – a list of the groups

• dry_run – If True, return the pks to delete without deleting anything. If False, delete the pks without confirmation If callable, a function that return True/False, based on the pks, e.g. dry_run=lambda pks: True

• traversal_rules – graph traversal rules. See aiida.common.links.GraphTraversalRules what rule names are toggleable and what the defaults are.

Returns

(node pks to delete, whether they were deleted)

aiida.tools.graph.delete_nodes(pks: Iterable[int], verbosity: Optional[int] = None, dry_run: Union[bool, Callable[[Set[int]], bool]] = True, force: Optional[bool] = None, **traversal_rules: bool) → Tuple[Set[int], bool][source]

Delete nodes given a list of “starting” PKs.

This command will delete not only the specified nodes, but also the ones that are linked to these and should be also deleted in order to keep a consistent provenance according to the rules explained in the Topics - Provenance section of the documentation. In summary:

1. If a DATA node is deleted, any process nodes linked to it will also be deleted.

2. If a CALC node is deleted, any incoming WORK node (callers) will be deleted as well whereas any incoming DATA node (inputs) will be kept. Outgoing DATA nodes (outputs) will be deleted by default but this can be disabled.

3. If a WORK node is deleted, any incoming WORK node (callers) will be deleted as well, but all DATA nodes will be kept. Outgoing WORK or CALC nodes will be kept by default, but deletion of either of both kind of connected nodes can be enabled.

These rules are ‘recursive’, so if a CALC node is deleted, then its output DATA nodes will be deleted as well, and then any CALC node that may have those as inputs, and so on.

Deprecated since version 1.6.0: The verbosity keyword will be removed in v2.0.0, set the level of DELETE_LOGGER instead.

Deprecated since version 1.6.0: The force keyword will be removed in v2.0.0, use the dry_run option instead.

Parameters
• pks – a list of starting PKs of the nodes to delete (the full set will be based on the traversal rules)

• dry_run – If True, return the pks to delete without deleting anything. If False, delete the pks without confirmation If callable, a function that return True/False, based on the pks, e.g. dry_run=lambda pks: True

• traversal_rules – graph traversal rules. See aiida.common.links.GraphTraversalRules for what rule names are toggleable and what the defaults are.

Returns

(pks to delete, whether they were deleted)

## Submodules¶

Entities for the AiiDA Graph Explorer utility

class aiida.tools.graph.age_entities.AbstractSetContainer[source]

Bases: object

Abstract Class

This class defines a set that can be speciaized to contain either nodes (either AiiDA nodes or Aiida groups) or edges (AiiDA links, or records of the connections between groups and nodes). Instances of this class reference a subset of entities in a database via a unique identifier. There are also a few operators defined, for simplicity, to do set-additions (unions) and deletions. The underlying Python-class is set, which means that adding an instance to an AiidaEntitySet that is already contained by it will not create a duplicate.

__abstractmethods__ = frozenset({'_check_input_for_set', '_check_self_and_other', 'get_template'})
__add__(other)[source]

Addition (return = self + other): defined as the set union

__dict__ = mappingproxy({'__module__': 'aiida.tools.graph.age_entities', '__doc__': 'Abstract Class\n\n This class defines a set that can be speciaized to contain either\n nodes (either AiiDA nodes or Aiida groups) or edges (AiiDA links,\n or records of the connections between groups and nodes).\n Instances of this class reference a subset of entities in a database\n via a unique identifier.\n There are also a few operators defined, for simplicity, to do\n set-additions (unions) and deletions.\n The underlying Python-class is **set**, which means that adding\n an instance to an AiidaEntitySet that is already contained by it\n will not create a duplicate.\n ', '__init__': <function AbstractSetContainer.__init__>, '_check_self_and_other': <function AbstractSetContainer._check_self_and_other>, '_check_input_for_set': <function AbstractSetContainer._check_input_for_set>, 'get_template': <function AbstractSetContainer.get_template>, 'keyset': <property object>, 'additional_identifiers': <property object>, '__add__': <function AbstractSetContainer.__add__>, '__iadd__': <function AbstractSetContainer.__iadd__>, '__sub__': <function AbstractSetContainer.__sub__>, '__isub__': <function AbstractSetContainer.__isub__>, '__len__': <function AbstractSetContainer.__len__>, '__repr__': <function AbstractSetContainer.__repr__>, '__eq__': <function AbstractSetContainer.__eq__>, '__ne__': <function AbstractSetContainer.__ne__>, 'set_entities': <function AbstractSetContainer.set_entities>, 'add_entities': <function AbstractSetContainer.add_entities>, 'copy': <function AbstractSetContainer.copy>, 'empty': <function AbstractSetContainer.empty>, '__dict__': <attribute '__dict__' of 'AbstractSetContainer' objects>, '__weakref__': <attribute '__weakref__' of 'AbstractSetContainer' objects>, '__hash__': None, '__abstractmethods__': frozenset({'_check_self_and_other', '_check_input_for_set', 'get_template'}), '_abc_impl': <_abc_data object>})
__eq__(other)[source]

Return self==value.

__hash__ = None
__iadd__(other)[source]

__init__()[source]

Initialization method

__isub__(other)[source]

Subtraction inplace (self -= other)

__len__()[source]
__module__ = 'aiida.tools.graph.age_entities'
__ne__(other)[source]

Return self!=value.

__repr__()[source]

Return repr(self).

__sub__(other)[source]

Subtraction (return = self - other): defined as the set-difference

__weakref__

list of weak references to the object (if defined)

_abc_impl = <_abc_data object>
abstract _check_input_for_set(input_for_set)[source]

Utility function

When provinding input keys for the internal set, this utility function will check and process the input accordingly.

Parameters

input_for_set – input argument for the keyset (must be either an AiiDA instance of node or group, or an identifier of the type used by the container).

abstract _check_self_and_other(other)[source]

Utility function

When called, will check whether self and other instance are compatible. (i.e. if they contain the same AiiDA class, same identifiers, length of tuples, etc)

Parameters

other (aiida.tools.graph.age_entities.AbstractSetContainer) – the other entity to check for compatibility.

add_entities(new_entitites)[source]

Add new entitities to the existing set of self.

Parameters

new_entities – an iterable of new entities to add.

property additional_identifiers

copy()[source]

Create new instance with the same defining attributes and the same keyset.

empty()[source]

Resets the contained set to be an empty set

abstract get_template()[source]

Create new instance with the same defining attributes.

property keyset

Set containing the keys of the entities

set_entities(new_entitites)[source]

Replaces contained set with the new entities.

Parameters

new_entities – entities which will replace the ones contained by the EntitySet. Must be an AiiDA instance (Node or Group) or an appropriate identifier (ID).

class aiida.tools.graph.age_entities.AiidaEntitySet(aiida_cls)[source]

Extension of AbstractSetContainer

This class is used to store graph nodes (aidda nodes or aiida groups).

__abstractmethods__ = frozenset({})
__init__(aiida_cls)[source]

Initialization method

Parameters

aiida_cls – a valid AiiDA ORM class (Node or Group supported).

__module__ = 'aiida.tools.graph.age_entities'
_abc_impl = <_abc_data object>
_check_input_for_set(input_for_set)[source]

Utility function

When provinding input keys for the internal set, this utility function will check and process the input accordingly.

Parameters

input_for_set – input argument for the keyset (must be either an AiiDA instance of node or group, or an identifier of the type used by the container).

_check_self_and_other(other)[source]

Utility function

When called, will check whether self and other instance are compatible. (i.e. if they contain the same AiiDA class, same identifiers, length of tuples, etc)

Parameters

other (aiida.tools.graph.age_entities.AbstractSetContainer) – the other entity to check for compatibility.

property aiida_cls

Class of nodes contained in the entity set (node or group)

get_entities()[source]

Iterator that returns the AiiDA entities

get_template()[source]

Create new instance with the same defining attributes.

property identifier

Identifier used for the nodes or groups (currently always id)

property identifier_type

Type of identifier for the node or group (for id is int)

class aiida.tools.graph.age_entities.Basket(nodes=None, groups=None, nodes_nodes=None, groups_nodes=None)[source]

Bases: object

Container for several instances of aiida.tools.graph.age_entities.AiidaEntitySet .

In the current implementation, it contains one EntitySet for Nodes and one for Groups, and one EdgeSet for Node-Node edges (links) and one for Group-Node connections.

__add__(other)[source]
__dict__ = mappingproxy({'__module__': 'aiida.tools.graph.age_entities', '__doc__': 'Container for several instances of\n :py:class:aiida.tools.graph.age_entities.AiidaEntitySet .\n\n In the current implementation, it contains one EntitySet for Nodes and one for Groups,\n and one EdgeSet for Node-Node edges (links) and one for Group-Node connections.\n ', '__init__': <function Basket.__init__>, 'sets': <property object>, 'dict': <property object>, 'nodes': <property object>, 'groups': <property object>, '__getitem__': <function Basket.__getitem__>, '__setitem__': <function Basket.__setitem__>, '__add__': <function Basket.__add__>, '__iadd__': <function Basket.__iadd__>, '__sub__': <function Basket.__sub__>, '__isub__': <function Basket.__isub__>, '__len__': <function Basket.__len__>, '__eq__': <function Basket.__eq__>, '__ne__': <function Basket.__ne__>, '__repr__': <function Basket.__repr__>, 'empty': <function Basket.empty>, 'get_template': <function Basket.get_template>, 'copy': <function Basket.copy>, '__dict__': <attribute '__dict__' of 'Basket' objects>, '__weakref__': <attribute '__weakref__' of 'Basket' objects>, '__hash__': None})
__eq__(other)[source]

Return self==value.

__getitem__(key)[source]
__hash__ = None
__iadd__(other)[source]
__init__(nodes=None, groups=None, nodes_nodes=None, groups_nodes=None)[source]

Initialization method

During initialization of the basket, both the sets of nodes and the set of groups can be provided as one of the following: an AiidaEntitySet with the respective type (node or group) or a list/set/tuple with the ids of the respective node or group.

Parameters
• nodes – AiiDA nodes provided in an acceptable way.

• groups – AiiDA groups provided in an acceptable way.

__isub__(other)[source]
__len__()[source]
__module__ = 'aiida.tools.graph.age_entities'
__ne__(other)[source]

Return self!=value.

__repr__()[source]

Return repr(self).

__setitem__(key, val)[source]
__sub__(other)[source]
__weakref__

list of weak references to the object (if defined)

copy()[source]

Create new instance with the same defining attributes and content.

property dict

All sets in the basket returned as a dictionary. This includes the keys ‘nodes’, ‘groups’, ‘nodes_nodes’ and ‘nodes_groups’.

empty()[source]

Empty every subset from its content

get_template()[source]

Create new nasket with the same defining attributes for its internal containers.

property groups

Set of groups stored in the basket

property nodes

Set of nodes stored in the basket

property sets

All sets in the basket returned as an ordered list. The order is: ‘groups’, ‘groups_nodes’, ‘nodes’, ‘nodes_nodes’.

class aiida.tools.graph.age_entities.DirectedEdgeSet(aiida_cls_to, aiida_cls_from)[source]

Extension of AbstractSetContainer

This class is used to store graph edges (aidda nodes or aiida groups).

__abstractmethods__ = frozenset({})
__init__(aiida_cls_to, aiida_cls_from)[source]

Initialization method

The classes that the link connects must be provided.

Parameters
• aiida_cls_to – a valid AiiDA ORM class (Node or Group supported).

• aiida_cls_from – a valid AiiDA ORM class (Node supported).

__module__ = 'aiida.tools.graph.age_entities'
_abc_impl = <_abc_data object>
_check_input_for_set(input_for_set)[source]

Utility function

When provinding input keys for the internal set, this utility function will check and process the input accordingly.

Parameters

input_for_set – input argument for the keyset (must be either an AiiDA instance of node or group, or an identifier of the type used by the container).

_check_self_and_other(other)[source]

Utility function

When called, will check whether self and other instance are compatible. (i.e. if they contain the same AiiDA class, same identifiers, length of tuples, etc)

Parameters

other (aiida.tools.graph.age_entities.AbstractSetContainer) – the other entity to check for compatibility.

property aiida_cls_from

The class of nodes which the edge points from

property aiida_cls_to

The class of nodes which the edge points to

property edge_identifiers

The identifiers for the edges

property edge_namedtuple

The namedtuple type used for the edges identifiers

get_template()[source]

Create new instance with the same defining attributes.

class aiida.tools.graph.age_entities.GroupNodeEdge(node_id, group_id)

Bases: tuple

__getnewargs__()

Return self as a plain tuple. Used by copy and pickle.

__module__ = 'aiida.tools.graph.age_entities'
static __new__(_cls, node_id, group_id)

Create new instance of GroupNodeEdge(node_id, group_id)

__repr__()

Return a nicely formatted representation string

__slots__ = ()
_asdict()

Return a new dict which maps field names to their values.

_field_defaults = {}
_fields = ('node_id', 'group_id')
_fields_defaults = {}
classmethod _make(iterable)

Make a new GroupNodeEdge object from a sequence or iterable

_replace(**kwds)

Return a new GroupNodeEdge object replacing specified fields with new values

group_id

Alias for field number 1

node_id

Alias for field number 0

Rules for the AiiDA Graph Explorer utility

class aiida.tools.graph.age_rules.Operation(max_iterations, track_edges)[source]

Bases: object

Base class for all AGE explorer classes

__abstractmethods__ = frozenset({'run'})
__dict__ = mappingproxy({'__module__': 'aiida.tools.graph.age_rules', '__doc__': 'Base class for all AGE explorer classes', '__init__': <function Operation.__init__>, 'set_max_iterations': <function Operation.set_max_iterations>, 'iterations_done': <property object>, 'run': <function Operation.run>, '__dict__': <attribute '__dict__' of 'Operation' objects>, '__weakref__': <attribute '__weakref__' of 'Operation' objects>, '__abstractmethods__': frozenset({'run'}), '_abc_impl': <_abc_data object>})
__init__(max_iterations, track_edges)[source]

Initialization method

Parameters
• max_iterations – maximum number of iterations to perform.

• track_edges (bool) – if True, will also track and return the edges traversed.

__module__ = 'aiida.tools.graph.age_rules'
__weakref__

list of weak references to the object (if defined)

_abc_impl = <_abc_data object>
property iterations_done

Number of iterations performed

abstract run(operational_set)[source]

Takes the operational_set and overwrites it with the set of nodes that results from applying the rule (this might or not include the initial set of nodes as well depending on the rule).

Parameters

operational_set (aiida.tools.graph.age_entities.Basket) – initital set of nodes to be overwritten by the rule.

set_max_iterations(max_iterations)[source]

Sets the max iterations

class aiida.tools.graph.age_rules.QueryRule(querybuilder, max_iterations=1, track_edges=False)[source]

Parent class for every rule that implements a query.

QueryRules take a generic QueryBuilder instance and a set of starting nodes and then perform successive iterations of that query, each one from the set of nodes that the previous one found. Depending on the class of rule used the final result will be either the whole set of nodes traversed (UpdateRule), or only the final set of nodes found in the last iteration of the query (ReplaceRule).

__abstractmethods__ = frozenset({})
__init__(querybuilder, max_iterations=1, track_edges=False)[source]

Initialization method

Parameters
• querybuilder – an instance of the QueryBuilder class from which to take the procedure for traversal

• max_iterations (int) – the number of iterations to run this query on (must be a finite number for ReplaceRules)

• track_edges (bool) – whether to track which edges are traversed and store them

__module__ = 'aiida.tools.graph.age_rules'
_abc_impl = <_abc_data object>
_init_run(operational_set)[source]

Initialization Utility method

This method initializes a run. It initializes the accumulator_set in order for it to only contain the operational_set, and to be of the same kind. This function modifies the its QueryBuilder instance to give the right results.

Parameters

operational_set – input with which to initialize the accumulator_set.

_load_results(target_set, operational_set)[source]

Single application of the rules to the operational set

Parameters
• target_set – where the new results will be loaded (it will be first emptied of all previous content). There is no returned value for this method.

• operational_set – where the results originate from (walkers)

empty_accumulator()[source]
run(operational_set)[source]

Takes the operational_set and overwrites it with the set of nodes that results from applying the rule (this might or not include the initial set of nodes as well depending on the rule).

Parameters

operational_set (aiida.tools.graph.age_entities.Basket) – initital set of nodes to be overwritten by the rule.

set_accumulator(accumulator_set)[source]
set_edge_keys(edge_keys)[source]

Set the edge keys that are use to classify the edges during the run of this query.

Parameters

edge_keys – a list of projections on the edge itself, or a tuple that specifies (tag, project) if the projection is not on the edge

Example: For node-to-node graph traversals, it is often convenient to save the information on the links:

qb  = QueryBuilder().append(Node, tag='n1').append(Node, tag='n2')
rule = RuleSequence(qb, track_edges=True)
rule.set_edge_keys(['input_id', 'output_id', 'label', 'type'])

# Now for UUIDS:
qb  = QueryBuilder().append(Node, tag='n1').append(Node, tag='n2')
rule = RuleSequence(qb, track_edges=True)
rule.set_edge_keys([('n1','uuid'), ('n2','uuid'), 'label', 'type'])

class aiida.tools.graph.age_rules.ReplaceRule(querybuilder, max_iterations=1, track_edges=False)[source]

The ReplaceRule does not accumulate results, but just sets the operational_set to new results. Therefore it can only function using a finite number of iterations, since it does not keep track of which nodes where visited already (otherwise, if it was following a cycle, it would run indefinitely).

__abstractmethods__ = frozenset({})
__init__(querybuilder, max_iterations=1, track_edges=False)[source]

Initialization method

Parameters
• querybuilder – an instance of the QueryBuilder class from which to take the procedure for traversal

• max_iterations (int) – the number of iterations to run this query on (must be a finite number for ReplaceRules)

• track_edges (bool) – whether to track which edges are traversed and store them

__module__ = 'aiida.tools.graph.age_rules'
_abc_impl = <_abc_data object>
run(operational_set)[source]

Takes the operational_set and overwrites it with the set of nodes that results from applying the rule (this might or not include the initial set of nodes as well depending on the rule).

Parameters

operational_set (aiida.tools.graph.age_entities.Basket) – initital set of nodes to be overwritten by the rule.

class aiida.tools.graph.age_rules.RuleSaveWalkers(stash)[source]

Save the Walkers:

When initialized, this rule will save a pointer to an external stash variable. When run, this stash will be emptied and a given operational_set will be saved there instead.

__abstractmethods__ = frozenset({})
__init__(stash)[source]

Initialization method

Parameters

stash – external variable in which to save the operational_set

__module__ = 'aiida.tools.graph.age_rules'
_abc_impl = <_abc_data object>
run(operational_set)[source]

Takes the operational_set and overwrites it with the set of nodes that results from applying the rule (this might or not include the initial set of nodes as well depending on the rule).

Parameters

operational_set (aiida.tools.graph.age_entities.Basket) – initital set of nodes to be overwritten by the rule.

class aiida.tools.graph.age_rules.RuleSequence(rules, max_iterations=1)[source]

Rule for concatenation

Rule Sequence is used to concatenate a series of rules together. Concatenating querybuilders in a single rule its not enough because one might want to stash results to perform two independent operations in the starting set instead of a second operation from the results of the first (see RuleSetWalkers and RuleSaveWalkers).

__abstractmethods__ = frozenset({})
__init__(rules, max_iterations=1)[source]

Initialization method

Parameters
• max_iterations – maximum number of iterations to perform.

• track_edges (bool) – if True, will also track and return the edges traversed.

__module__ = 'aiida.tools.graph.age_rules'
_abc_impl = <_abc_data object>
empty_accumulator()[source]

Empties the accumulator set

empty_visits()[source]

Empties the visits set

run(operational_set)[source]

Takes the operational_set and overwrites it with the set of nodes that results from applying the rule (this might or not include the initial set of nodes as well depending on the rule).

Parameters

operational_set (aiida.tools.graph.age_entities.Basket) – initital set of nodes to be overwritten by the rule.

set_accumulator(accumulator_set)[source]

Set the accumulator set

set_visits(visits_set)[source]

Set the visits set

class aiida.tools.graph.age_rules.RuleSetWalkers(stash)[source]

Set the Walkers:

When initialized, this rule will save a pointer to an external stash variable. When run, the given operational_set will be emptied and the stash will be loaded in it.

__abstractmethods__ = frozenset({})
__init__(stash)[source]

Initialization method

Parameters

stash – external variable from which to load into the operational_set

__module__ = 'aiida.tools.graph.age_rules'
_abc_impl = <_abc_data object>
run(operational_set)[source]

Takes the operational_set and overwrites it with the set of nodes that results from applying the rule (this might or not include the initial set of nodes as well depending on the rule).

Parameters

operational_set (aiida.tools.graph.age_entities.Basket) – initital set of nodes to be overwritten by the rule.

class aiida.tools.graph.age_rules.UpdateRule(querybuilder, max_iterations=1, track_edges=False)[source]

The UpdateRule will accumulate every node visited and return it as a set of nodes (and thus, without duplication). It can be used requesting both a finite number of iterations or an infinite number of iterations (in which case it will stop once no new nodes are added to the accumulation set).

__abstractmethods__ = frozenset({})
__module__ = 'aiida.tools.graph.age_rules'
_abc_impl = <_abc_data object>
run(operational_set)[source]

Takes the operational_set and overwrites it with the set of nodes that results from applying the rule (this might or not include the initial set of nodes as well depending on the rule).

Parameters

operational_set (aiida.tools.graph.age_entities.Basket) – initital set of nodes to be overwritten by the rule.

Functions to delete entities from the database, preserving provenance integrity.

aiida.tools.graph.deletions.delete_group_nodes(pks: Iterable[int], dry_run: Union[bool, Callable[[Set[int]], bool]] = True, **traversal_rules: bool) → Tuple[Set[int], bool][source]

Delete nodes contained in a list of groups (not the groups themselves!).

This command will delete not only the nodes, but also the ones that are linked to these and should be also deleted in order to keep a consistent provenance according to the rules explained in the concepts section of the documentation. In summary:

1. If a DATA node is deleted, any process nodes linked to it will also be deleted.

2. If a CALC node is deleted, any incoming WORK node (callers) will be deleted as well whereas any incoming DATA node (inputs) will be kept. Outgoing DATA nodes (outputs) will be deleted by default but this can be disabled.

3. If a WORK node is deleted, any incoming WORK node (callers) will be deleted as well, but all DATA nodes will be kept. Outgoing WORK or CALC nodes will be kept by default, but deletion of either of both kind of connected nodes can be enabled.

These rules are ‘recursive’, so if a CALC node is deleted, then its output DATA nodes will be deleted as well, and then any CALC node that may have those as inputs, and so on.

Parameters
• pks – a list of the groups

• dry_run – If True, return the pks to delete without deleting anything. If False, delete the pks without confirmation If callable, a function that return True/False, based on the pks, e.g. dry_run=lambda pks: True

• traversal_rules – graph traversal rules. See aiida.common.links.GraphTraversalRules what rule names are toggleable and what the defaults are.

Returns

(node pks to delete, whether they were deleted)

aiida.tools.graph.deletions.delete_nodes(pks: Iterable[int], verbosity: Optional[int] = None, dry_run: Union[bool, Callable[[Set[int]], bool]] = True, force: Optional[bool] = None, **traversal_rules: bool) → Tuple[Set[int], bool][source]

Delete nodes given a list of “starting” PKs.

This command will delete not only the specified nodes, but also the ones that are linked to these and should be also deleted in order to keep a consistent provenance according to the rules explained in the Topics - Provenance section of the documentation. In summary:

1. If a DATA node is deleted, any process nodes linked to it will also be deleted.

2. If a CALC node is deleted, any incoming WORK node (callers) will be deleted as well whereas any incoming DATA node (inputs) will be kept. Outgoing DATA nodes (outputs) will be deleted by default but this can be disabled.

3. If a WORK node is deleted, any incoming WORK node (callers) will be deleted as well, but all DATA nodes will be kept. Outgoing WORK or CALC nodes will be kept by default, but deletion of either of both kind of connected nodes can be enabled.

These rules are ‘recursive’, so if a CALC node is deleted, then its output DATA nodes will be deleted as well, and then any CALC node that may have those as inputs, and so on.

Deprecated since version 1.6.0: The verbosity keyword will be removed in v2.0.0, set the level of DELETE_LOGGER instead.

Deprecated since version 1.6.0: The force keyword will be removed in v2.0.0, use the dry_run option instead.

Parameters
• pks – a list of starting PKs of the nodes to delete (the full set will be based on the traversal rules)

• dry_run – If True, return the pks to delete without deleting anything. If False, delete the pks without confirmation If callable, a function that return True/False, based on the pks, e.g. dry_run=lambda pks: True

• traversal_rules – graph traversal rules. See aiida.common.links.GraphTraversalRules for what rule names are toggleable and what the defaults are.

Returns

(pks to delete, whether they were deleted)

Module for functions to traverse AiiDA graphs.

class aiida.tools.graph.graph_traversers.TraverseGraphOutput(*args, **kwargs)[source]

Bases: dict

__annotations__ = {'links': typing.Union[typing.Set[aiida.orm.utils.links.LinkQuadruple], NoneType], 'nodes': typing.Set[int], 'rules': typing.Dict[str, bool]}
__dict__ = mappingproxy({'__module__': 'aiida.tools.graph.graph_traversers', '__annotations__': {'nodes': typing.Set[int], 'links': typing.Union[typing.Set[aiida.orm.utils.links.LinkQuadruple], NoneType], 'rules': typing.Dict[str, bool]}, '__new__': <staticmethod object>, '__dict__': <attribute '__dict__' of 'TraverseGraphOutput' objects>, '__weakref__': <attribute '__weakref__' of 'TraverseGraphOutput' objects>, '__doc__': None, '__total__': False})
__module__ = 'aiida.tools.graph.graph_traversers'
static __new__(cls, /, *args, **kwargs)

Create and return a new object. See help(type) for accurate signature.

__total__ = False
__weakref__

list of weak references to the object (if defined)

nodes: Set[int]
rules: Dict[str, bool]
aiida.tools.graph.graph_traversers.get_nodes_delete(starting_pks: Iterable[int], get_links: bool = False, missing_callback: Optional[Callable[[Iterable[int]], None]] = None, **traversal_rules: bool)aiida.tools.graph.graph_traversers.TraverseGraphOutput[source]

This function will return the set of all nodes that can be connected to a list of initial nodes through any sequence of specified authorized links and directions for deletion.

Parameters
• starting_pks – Contains the (valid) pks of the starting nodes.

• get_links – Pass True to also return the links between all nodes (found + initial).

• missing_callback – A callback to handle missing starting_pks or if None raise NotExistent For example to ignore them: missing_callback=lambda missing_pks: None

• traversal_rules – graph traversal rules. See aiida.common.links.GraphTraversalRules what rule names are toggleable and what the defaults are.

aiida.tools.graph.graph_traversers.get_nodes_export(starting_pks: Iterable[int], get_links: bool = False, **traversal_rules: bool)aiida.tools.graph.graph_traversers.TraverseGraphOutput[source]

This function will return the set of all nodes that can be connected to a list of initial nodes through any sequence of specified authorized links and directions for export. This will also return the links and the traversal rules parsed.

Parameters
• starting_pks – Contains the (valid) pks of the starting nodes.

• get_links – Pass True to also return the links between all nodes (found + initial).

• input_calc_forward – will traverse INPUT_CALC links in the forward direction.

• create_backward – will traverse CREATE links in the backward direction.

• return_backward – will traverse RETURN links in the backward direction.

• input_work_forward – will traverse INPUT_WORK links in the forward direction.

• call_calc_backward – will traverse CALL_CALC links in the backward direction.

• call_work_backward – will traverse CALL_WORK links in the backward direction.

aiida.tools.graph.graph_traversers.traverse_graph(starting_pks: Iterable[int], max_iterations: Optional[int] = None, get_links: bool = False, links_forward: Iterable[aiida.common.links.LinkType] = (), links_backward: Iterable[aiida.common.links.LinkType] = (), missing_callback: Optional[Callable[[Iterable[int]], None]] = None)aiida.tools.graph.graph_traversers.TraverseGraphOutput[source]

This function will return the set of all nodes that can be connected to a list of initial nodes through any sequence of specified links. Optionally, it may also return the links that connect these nodes.

Parameters
• starting_pks – Contains the (valid) pks of the starting nodes.

• max_iterations – The number of iterations to apply the set of rules (a value of ‘None’ will iterate until no new nodes are added).

• get_links – Pass True to also return the links between all nodes (found + initial).

• links_forward – List with all the links that should be traversed in the forward direction.

• links_backward – List with all the links that should be traversed in the backward direction.

• missing_callback – A callback to handle missing starting_pks or if None raise NotExistent

aiida.tools.graph.graph_traversers.validate_traversal_rules`(ruleset: aiida.common.links.GraphTraversalRules = <GraphTraversalRules.DEFAULT: {'input_calc_forward': GraphTraversalRule(link_type=<LinkType.INPUT_CALC: 'input_calc'>, direction='forward', toggleable=True, default=False), 'input_calc_backward': GraphTraversalRule(link_type=<LinkType.INPUT_CALC: 'input_calc'>, direction='backward', toggleable=True, default=False), 'create_forward': GraphTraversalRule(link_type=<LinkType.CREATE: 'create'>, direction='forward', toggleable=True, default=False), 'create_backward': GraphTraversalRule(link_type=<LinkType.CREATE: 'create'>, direction='backward', toggleable=True, default=False), 'return_forward': GraphTraversalRule(link_type=<LinkType.RETURN: 'return'>, direction='forward', toggleable=True, default=False), 'return_backward': GraphTraversalRule(link_type=<LinkType.RETURN: 'return'>, direction='backward', toggleable=True, default=False), 'input_work_forward': GraphTraversalRule(link_type=<LinkType.INPUT_WORK: 'input_work'>, direction='forward', toggleable=True, default=False), 'input_work_backward': GraphTraversalRule(link_type=<LinkType.INPUT_WORK: 'input_work'>, direction='backward', toggleable=True, default=False), 'call_calc_forward': GraphTraversalRule(link_type=<LinkType.CALL_CALC: 'call_calc'>, direction='forward', toggleable=True, default=False), 'call_calc_backward': GraphTraversalRule(link_type=<LinkType.CALL_CALC: 'call_calc'>, direction='backward', toggleable=True, default=False), 'call_work_forward': GraphTraversalRule(link_type=<LinkType.CALL_WORK: 'call_work'>, direction='forward', toggleable=True, default=False), 'call_work_backward': GraphTraversalRule(link_type=<LinkType.CALL_WORK: 'call_work'>, direction='backward', toggleable=True, default=False)}>, **traversal_rules: bool)dict[source]

Validates the keywords with a ruleset template and returns a parsed dictionary ready to be used.

Parameters
• ruleset – Ruleset template used to validate the set of rules.

• input_calc_forward – will traverse INPUT_CALC links in the forward direction.

• input_calc_backward – will traverse INPUT_CALC links in the backward direction.

• create_forward – will traverse CREATE links in the forward direction.

• create_backward – will traverse CREATE links in the backward direction.

• return_forward – will traverse RETURN links in the forward direction.

• return_backward – will traverse RETURN links in the backward direction.

• input_work_forward – will traverse INPUT_WORK links in the forward direction.

• input_work_backward – will traverse INPUT_WORK links in the backward direction.

• call_calc_forward – will traverse CALL_CALC links in the forward direction.

• call_calc_backward – will traverse CALL_CALC links in the backward direction.

• call_work_forward – will traverse CALL_WORK links in the forward direction.

• call_work_backward – will traverse CALL_WORK links in the backward direction.