Provides tools for traversing the provenance graph.
aiida.tools.graph.
delete_group_nodes
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:
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.
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
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.
aiida.common.links.GraphTraversalRules
(node pks to delete, whether they were deleted)
delete_nodes
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:
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.
pks – a list of starting PKs of the nodes to delete (the full set will be based on the traversal rules)
traversal_rules – graph traversal rules. See aiida.common.links.GraphTraversalRules for what rule names are toggleable and what the defaults are.
(pks to delete, whether they were deleted)
Entities for the AiiDA Graph Explorer utility
aiida.tools.graph.age_entities.
AbstractSetContainer
Bases: object
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__
__add__
Addition (return = self + other): defined as the set union
__dict__
__eq__
Return self==value.
__hash__
__iadd__
Addition inplace (self += other)
__init__
Initialization method
__isub__
Subtraction inplace (self -= other)
__len__
__module__
__ne__
Return self!=value.
__repr__
Return repr(self).
__sub__
Subtraction (return = self - other): defined as the set-difference
__weakref__
list of weak references to the object (if defined)
_abc_impl
_check_input_for_set
Utility function
When provinding input keys for the internal set, this utility function will check and process the input accordingly.
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
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)
other (aiida.tools.graph.age_entities.AbstractSetContainer) – the other entity to check for compatibility.
aiida.tools.graph.age_entities.AbstractSetContainer
add_entities
Add new entitities to the existing set of self.
new_entities – an iterable of new entities to add.
additional_identifiers
Additional identifiers for the entities
copy
Create new instance with the same defining attributes and the same keyset.
empty
Resets the contained set to be an empty set
get_template
Create new instance with the same defining attributes.
keyset
Set containing the keys of the entities
set_entities
Replaces contained set with the new entities.
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).
AiidaEntitySet
Bases: aiida.tools.graph.age_entities.AbstractSetContainer
Extension of AbstractSetContainer
This class is used to store graph nodes (aidda nodes or aiida groups).
aiida_cls – a valid AiiDA ORM class (Node or Group supported).
aiida_cls
Class of nodes contained in the entity set (node or group)
get_entities
Iterator that returns the AiiDA entities
identifier
Identifier used for the nodes or groups (currently always id)
identifier_type
Type of identifier for the node or group (for id is int)
Basket
Container for several instances of aiida.tools.graph.age_entities.AiidaEntitySet .
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.
__getitem__
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.
nodes – AiiDA nodes provided in an acceptable way.
groups – AiiDA groups provided in an acceptable way.
__setitem__
Create new instance with the same defining attributes and content.
dict
All sets in the basket returned as a dictionary. This includes the keys ‘nodes’, ‘groups’, ‘nodes_nodes’ and ‘nodes_groups’.
Empty every subset from its content
Create new nasket with the same defining attributes for its internal containers.
groups
Set of groups stored in the basket
nodes
Set of nodes stored in the basket
sets
All sets in the basket returned as an ordered list. The order is: ‘groups’, ‘groups_nodes’, ‘nodes’, ‘nodes_nodes’.
DirectedEdgeSet
This class is used to store graph edges (aidda nodes or aiida groups).
The classes that the link connects must be provided.
aiida_cls_to – a valid AiiDA ORM class (Node or Group supported).
aiida_cls_from – a valid AiiDA ORM class (Node supported).
aiida_cls_from
The class of nodes which the edge points from
aiida_cls_to
The class of nodes which the edge points to
edge_identifiers
The identifiers for the edges
edge_namedtuple
The namedtuple type used for the edges` identifiers
GroupNodeEdge
Bases: tuple
tuple
__getnewargs__
Return self as a plain tuple. Used by copy and pickle.
__new__
Create new instance of GroupNodeEdge(node_id, group_id)
Return a nicely formatted representation string
__slots__
_asdict
Return a new dict which maps field names to their values.
_field_defaults
_fields
_fields_defaults
_make
Make a new GroupNodeEdge object from a sequence or iterable
_replace
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
aiida.tools.graph.age_rules.
Operation
Base class for all AGE explorer classes
max_iterations – maximum number of iterations to perform.
track_edges (bool) – if True, will also track and return the edges traversed.
iterations_done
Number of iterations performed
run
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).
operational_set (aiida.tools.graph.age_entities.Basket) – initital set of nodes to be overwritten by the rule.
aiida.tools.graph.age_entities.Basket
set_max_iterations
Sets the max iterations
QueryRule
Bases: aiida.tools.graph.age_rules.Operation
aiida.tools.graph.age_rules.Operation
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).
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
_init_run
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.
operational_set – input with which to initialize the accumulator_set.
_load_results
Single application of the rules to the operational set
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
set_accumulator
set_edge_keys
Set the edge keys that are use to classify the edges during the run of this query.
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'])
ReplaceRule
Bases: aiida.tools.graph.age_rules.QueryRule
aiida.tools.graph.age_rules.QueryRule
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).
RuleSaveWalkers
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.
stash – external variable in which to save the operational_set
RuleSequence
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).
Empties the accumulator set
empty_visits
Empties the visits set
Set the accumulator set
set_visits
Set the visits set
RuleSetWalkers
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.
stash – external variable from which to load into the operational_set
UpdateRule
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).
Functions to delete entities from the database, preserving provenance integrity.
aiida.tools.graph.deletions.
Module for functions to traverse AiiDA graphs.
aiida.tools.graph.graph_traversers.
TraverseGraphOutput
Bases: dict
__annotations__
Create and return a new object. See help(type) for accurate signature.
__total__
links
rules
get_nodes_delete
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.
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
missing_callback=lambda missing_pks: None
get_nodes_export
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.
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.
traverse_graph
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.
max_iterations – The number of iterations to apply the set of rules (a value of ‘None’ will iterate until no new nodes are added).
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
validate_traversal_rules
Validates the keywords with a ruleset template and returns a parsed dictionary ready to be used.
ruleset – Ruleset template used to validate the set of rules.
input_calc_backward – will traverse INPUT_CALC links in the backward direction.
create_forward – will traverse CREATE links in the forward direction.
return_forward – will traverse RETURN 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_work_forward – will traverse CALL_WORK links in the forward direction.