# aiida.tools package¶

Tools to operate on AiiDA ORM class instances

What functionality should go directly in the ORM class in aiida.orm and what in aiida.tools?

• The ORM class should define basic functions to set and get data from the object

• More advanced functionality to operate on the ORM class instances can be placed in aiida.tools

to prevent the ORM namespace from getting too cluttered.

Note

Modules in this sub package may require the database environment to be loaded

class aiida.tools.CalculationTools(node)[source]

Bases: object

Base class for CalculationTools.

__dict__ = mappingproxy({'__module__': 'aiida.tools.calculations.base', '__doc__': 'Base class for CalculationTools.', '__init__': <function CalculationTools.__init__>, '__dict__': <attribute '__dict__' of 'CalculationTools' objects>, '__weakref__': <attribute '__weakref__' of 'CalculationTools' objects>})
__init__(node)[source]

Initialize self. See help(type(self)) for accurate signature.

__module__ = 'aiida.tools.calculations.base'
__weakref__

list of weak references to the object (if defined)

class aiida.tools.DbImporter[source]

Bases: object

Base class implementation for an external database importer.

__dict__ = mappingproxy({'__module__': 'aiida.tools.dbimporters.baseclasses', '__doc__': 'Base class implementation for an external database importer.', 'query': <function DbImporter.query>, 'setup_db': <function DbImporter.setup_db>, 'get_supported_keywords': <function DbImporter.get_supported_keywords>, '__dict__': <attribute '__dict__' of 'DbImporter' objects>, '__weakref__': <attribute '__weakref__' of 'DbImporter' objects>})
__module__ = 'aiida.tools.dbimporters.baseclasses'
__weakref__

list of weak references to the object (if defined)

get_supported_keywords()[source]

Returns the list of all supported query keywords.

Returns

list of strings

query(**kwargs)[source]

Method to query the database.

Parameters
• id – database-specific entry identificator

• element – element name from periodic table of elements

• number_of_elements – number of different elements

• mineral_name – name of mineral

• chemical_name – chemical name of substance

• formula – chemical formula

• volume – volume of the unit cell in cubic angstroms

• spacegroup – symmetry space group symbol in Hermann-Mauguin notation

• spacegroup_hall – symmetry space group symbol in Hall notation

• a – length of lattice vector in angstroms

• b – length of lattice vector in angstroms

• c – length of lattice vector in angstroms

• alpha – angles between lattice vectors in degrees

• beta – angles between lattice vectors in degrees

• gamma – angles between lattice vectors in degrees

• z – number of the formula units in the unit cell

• measurement_temp – temperature in kelvins at which the unit-cell parameters were measured

• measurement_pressure – pressure in kPa at which the unit-cell parameters were measured

• diffraction_temp – mean temperature in kelvins at which the intensities were measured

• diffraction_pressure – mean pressure in kPa at which the intensities were measured

• authors – authors of the publication

• journal – name of the journal

• title – title of the publication

• year – year of the publication

• journal_volume – journal volume of the publication

• journal_issue – journal issue of the publication

• first_page – first page of the publication

• last_page – last page of the publication

• doi – digital object identifyer (DOI), refering to the publication

Raises

NotImplementedError – if search using given keyword is not implemented.

setup_db(**kwargs)[source]

Sets the database parameters. The method should reconnect to the database using updated parameters, if already connected.

aiida.tools.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.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)

aiida.tools.get_explicit_kpoints_path(structure, method='seekpath', **kwargs)[source]

Returns a dictionary whose contents depend on the method but includes at least the following keys

• parameters: Dict node

• explicit_kpoints: KpointsData node with explicit kpoints path

The contents of the parameters depends on the method but contains at least the keys

• ‘point_coords’: a dictionary with ‘kpoints-label’: [float coordinates]

• ‘path’: a list of length-2 tuples, with the labels of the starting

and ending point of each label section

The ‘seekpath’ method which is the default also returns the following additional nodes

• primitive_structure: StructureData with the primitive cell

• conv_structure: StructureData with the conventional cell

Note that the generated kpoints for the seekpath method only apply on the returned primitive_structure and not on the input structure that was provided

Parameters
• structure – a StructureData node

• method – the method to use for kpoint generation, options are ‘seekpath’ and ‘legacy’. It is strongly advised to use the default ‘seekpath’ as the ‘legacy’ implementation is known to have bugs for certain structure cells

• kwargs – optional keyword arguments that depend on the selected method

Returns

dictionary as described above in the docstring

aiida.tools.get_kpoints_path(structure, method='seekpath', **kwargs)[source]

Returns a dictionary whose contents depend on the method but includes at least the following keys

• parameters: Dict node

The contents of the parameters depends on the method but contains at least the keys

• ‘point_coords’: a dictionary with ‘kpoints-label’: [float coordinates]

• ‘path’: a list of length-2 tuples, with the labels of the starting

and ending point of each label section

The ‘seekpath’ method which is the default also returns the following additional nodes

• primitive_structure: StructureData with the primitive cell

• conv_structure: StructureData with the conventional cell

Note that the generated kpoints for the seekpath method only apply on the returned primitive_structure and not on the input structure that was provided

Parameters
• structure – a StructureData node

• method – the method to use for kpoint generation, options are ‘seekpath’ and ‘legacy’. It is strongly advised to use the default ‘seekpath’ as the ‘legacy’ implementation is known to have bugs for certain structure cells

• kwargs – optional keyword arguments that depend on the selected method

Returns

dictionary as described above in the docstring

aiida.tools.spglib_tuple_to_structure(structure_tuple, kind_info=None, kinds=None)[source]

Convert a tuple of the format (cell, scaled_positions, element_numbers) to an AiiDA structure.

Unless the element_numbers are identical to the Z number of the atoms, you should pass both kind_info and kinds, with the same format as returned by get_tuple_from_aiida_structure.

Parameters
• structure_tuple – the structure in format (structure_tuple, kind_info)

• kind_info – a dictionary mapping the kind_names to the numbers used in element_numbers. If not provided, assumes {element_name: element_Z}

• kinds – a list of the kinds of the structure.

aiida.tools.structure_to_spglib_tuple(structure)[source]

Convert an AiiDA structure to a tuple of the format (cell, scaled_positions, element_numbers).

Parameters

structure – the AiiDA structure

Returns

(structure_tuple, kind_info, kinds) where structure_tuple is a tuple of format (cell, scaled_positions, element_numbers); kind_info is a dictionary mapping the kind_names to the numbers used in element_numbers. When possible, it uses the Z number of the element, otherwise it uses numbers > 1000; kinds is a list of the kinds of the structure.