`aiida.orm`#

Main module to expose all orm classes and methods

Package Contents#

Classes#

`AbstractCode`	Abstract data plugin representing an executable code.
`AbstractNodeMeta`	Some python black magic to set correctly the logger also in subclasses.
`ArrayData`	Store a set of arrays on disk (rather than on the database) in an efficient way using numpy.save() (therefore, this class requires numpy to be installed).
`AttributeManager`	An object used internally to return the attributes as a dictionary. This is currently used in `Dict`, for instance.
`AuthInfo`	ORM class that models the authorization information that allows a User to connect to a Computer.
`AutoGroup`	Group to be used to contain selected nodes generated, whilst autogrouping is enabled.
`BandsData`	Class to handle bands data
`BaseType`	Data sub class to be used as a base for data containers that represent base python data types.
`Bool`	Data sub class to represent a boolean value.
`CalcFunctionNode`	ORM class for all nodes representing the execution of a calcfunction.
`CalcJobNode`	ORM class for all nodes representing the execution of a CalcJob.
`CalcJobResultManager`	Utility class to easily access the contents of the ‘default output’ node of a CalcJobNode.
`CalculationEntityLoader`	Loader for the Calculation entity and sub classes.
`CalculationNode`	Base class for all nodes representing the execution of a calculation process.
`CifData`	Wrapper for Crystallographic Interchange File (CIF)
`Code`	A code entity. It can either be ‘local’, or ‘remote’.
`CodeEntityLoader`	Loader for the Code entity and sub classes.
`Collection`	Container class that represents the collection of objects of a particular entity type.
`Comment`	Base class to map a DbComment that represents a comment attached to a certain Node.
`Computer`	Computer entity.
`ComputerEntityLoader`	Loader for the Computer entity and sub classes.
`ContainerizedCode`	Data plugin representing an executable code in container on a remote computer.
`Data`	The base class for all Data nodes.
`Dict`	Data sub class to represent a dictionary.
`Entity`	An AiiDA entity
`EntityExtras`	Interface to the extras of a node or group instance.
`EntityTypes`	Enum for referring to ORM entities in a backend-agnostic manner.
`EnumData`	Data plugin that allows to easily wrap an `enum.Enum` member.
`Float`	Data sub class to represent a float value.
`FolderData`	Data sub class to represent a folder on a file system.
`Group`	An AiiDA ORM implementation of group of nodes.
`GroupEntityLoader`	Loader for the Group entity and sub classes.
`ImportGroup`	Group to be used to contain all nodes from an export archive that has been imported.
`InstalledCode`	Data plugin representing an executable code on a remote computer.
`Int`	Data sub class to represent an integer value.
`JsonableData`	Data plugin that allows to easily wrap objects that are JSON-able.
`Kind`	This class contains the information about the species (kinds) of the system.
`KpointsData`	Class to handle array of kpoints in the Brillouin zone. Provide methods to generate either user-defined k-points or path of k-points along symmetry lines. Internally, all k-points are defined in terms of crystal (fractional) coordinates. Cell and lattice vector coordinates are in Angstroms, reciprocal lattice vectors in Angstrom^-1 . :note: The methods setting and using the Bravais lattice info assume the PRIMITIVE unit cell is provided in input to the set_cell or set_cell_from_structure methods.
`LinkManager`	Class to convert a list of LinkTriple tuples into an iterator.
`LinkPair`
`LinkTriple`
`List`	Data sub class to represent a list.
`Log`	An AiiDA Log entity. Corresponds to a logged message against a particular AiiDA node.
`Node`	Base class for all nodes in AiiDA.
`NodeAttributes`	Interface to the attributes of a node instance.
`NodeEntityLoader`	Loader for the Node entity and sub classes.
`NodeLinksManager`	A manager that allows to inspect, with tab-completion, nodes linked to a given one. See an example of its use in CalculationNode.inputs.
`NodeRepository`	Interface to the file repository of a node instance.
`NumericType`	Sub class of Data to store numbers, overloading common operators (`+`, `*`, …).
`OrbitalData`	Used for storing collections of orbitals, as well as providing methods for accessing them internally.
`OrmEntityLoader`	Base class for entity loaders.
`PortableCode`	Data plugin representing an executable code stored in AiiDA’s storage.
`ProcessNode`	Base class for all nodes representing the execution of a process
`ProjectionData`	A class to handle arrays of projected wavefunction data. That is projections of a orbitals, usually an atomic-hydrogen orbital, onto a given bloch wavefunction, the bloch wavefunction being indexed by s, n, and k. E.g. the elements are the projections described as < orbital \| Bloch wavefunction (s,n,k) >
`QueryBuilder`	The class to query the AiiDA database.
`RemoteData`	Store a link to a file or folder on a remote machine.
`RemoteStashData`	Data plugin that models an archived folder on a remote computer.
`RemoteStashFolderData`	Data plugin that models a folder with files of a completed calculation job that has been stashed through a copy.
`SinglefileData`	Data class that can be used to store a single file in its repository.
`Site`	This class contains the information about a given site of the system.
`Str`	Data sub class to represent a string value.
`StructureData`	This class contains the information about a given structure, i.e. a collection of sites together with a cell, the boundary conditions (whether they are periodic or not) and other related useful information.
`TrajectoryData`	Stores a trajectory (a sequence of crystal structures with timestamps, and possibly with velocities).
`UpfData`	Data sub class to represent a pseudopotential single file in UPF format.
`UpfFamily`	Group that represents a pseudo potential family containing UpfData nodes.
`User`	AiiDA User
`WorkChainNode`	ORM class for all nodes representing the execution of a WorkChain.
`WorkFunctionNode`	ORM class for all nodes representing the execution of a workfunction.
`WorkflowNode`	Base class for all nodes representing the execution of a workflow process.
`XyData`	A subclass designed to handle arrays that have an “XY” relationship to each other. That is there is one array, the X array, and there are several Y arrays, which can be considered functions of X.

Functions#

`OrderSpecifier`
`cif_from_ase`	Construct a CIF datablock from the ASE structure. The code is taken from https://wiki.fysik.dtu.dk/ase/ase/io/formatoptions.html#ase.io.cif.write_cif, as the original ASE code contains a bug in printing the Hermann-Mauguin symmetry space group symbol.
`find_bandgap`	Tries to guess whether the bandsdata represent an insulator. This method is meant to be used only for electronic bands (not phonons) By default, it will try to use the occupations to guess the number of electrons and find the Fermi Energy, otherwise, it can be provided explicitely. Also, there is an implicit assumption that the kpoints grid is “sufficiently” dense, so that the bandsdata are not missing the intersection between valence and conduction band if present. Use this function with care!
`get_loader`	Return the correct OrmEntityLoader for the given orm class.
`get_query_type_from_type_string`	Take the type string of a Node and create the queryable type string
`get_type_string_from_class`	Given the module and name of a class, determine the orm_class_type string, which codifies the orm class that is to be used. The returned string will always have a terminating period, which is required to query for the string in the database
`has_pycifrw`	return: True if the PyCifRW module can be imported, False otherwise.
`load_code`	Load a Code instance by one of its identifiers: pk, uuid or label
`load_computer`	Load a Computer instance by one of its identifiers: pk, uuid or label
`load_entity`	Load an entity instance by one of its identifiers: pk, uuid or label
`load_group`	Load a Group instance by one of its identifiers: pk, uuid or label
`load_node`	Load a node by one of its identifiers: pk or uuid. If the type of the identifier is unknown simply pass it without a keyword and the loader will attempt to infer the type
`load_node_class`	Return the Node sub class that corresponds to the given type string.
`pycifrw_from_cif`	Constructs PyCifRW’s CifFile from an array of CIF datablocks.
`to_aiida_type`	Turns basic Python types (str, int, float, bool) into the corresponding AiiDA types.
`validate_link`	Validate adding a link of the given type and label from a given node to ourself.

Data#

`ASCENDING`
`DESCENDING`

API#

aiida.orm.ASCENDING = 'asc'#

class aiida.orm.AbstractCode(default_calc_job_plugin: str | None = None, append_text: str = '', prepend_text: str = '', use_double_quotes: bool = False, is_hidden: bool = False, **kwargs)#

Bases: aiida.orm.nodes.data.data.Data

Abstract data plugin representing an executable code.

Initialization

Construct a new instance.

Parameters:

default_calc_job_plugin – The entry point name of the default CalcJob plugin to use.
append_text – The text that should be appended to the run line in the job script.
prepend_text – The text that should be prepended to the run line in the job script.
use_double_quotes – Whether the command line invocation of this code should be escaped with double quotes.
is_hidden – Whether the code is hidden.

_KEY_ATTRIBUTE_DEFAULT_CALC_JOB_PLUGIN: str = 'input_plugin'#

_KEY_ATTRIBUTE_APPEND_TEXT: str = 'append_text'#

_KEY_ATTRIBUTE_PREPEND_TEXT: str = 'prepend_text'#

_KEY_ATTRIBUTE_USE_DOUBLE_QUOTES: str = 'use_double_quotes'#

_KEY_EXTRA_IS_HIDDEN: str = 'hidden'#

abstract can_run_on_computer(computer: aiida.orm.Computer) → bool#

Return whether the code can run on a given computer.

Parameters:: computer – The computer.
Returns:: True if the code can run on computer, False otherwise.

abstract get_executable() → pathlib.PurePosixPath#

Return the executable that the submission script should execute to run the code.

Returns:: The executable to be called in the submission script.

get_executable_cmdline_params(cmdline_params: list[str] | None = None) → list#

Return the list of executable with its command line parameters.

Parameters:: cmdline_params – List of command line parameters provided by the CalcJob plugin.
Returns:: List of the executable followed by its command line parameters.

get_prepend_cmdline_params(mpi_args: list[str] | None = None, extra_mpirun_params: list[str] | None = None) → list[str]#

Return List of command line parameters to be prepended to the executable in submission line. These command line parameters are typically parameters related to MPI invocations.

Parameters:

mpi_args – List of MPI parameters provided by the Computer.get_mpirun_command method.
extra_mpiruns_params – List of MPI parameters provided by the metadata.options.extra_mpirun_params input of the CalcJob.

Returns:

List of command line parameters to be prepended to the executable in submission line.

validate_working_directory(folder: aiida.common.folders.Folder)#

Validate content of the working directory created by the CalcJob plugin.

This method will be called by presubmit() when a new calculation job is launched, passing the Folder that was used by the plugin used for the calculation to create the input files for the working directory. This method can be overridden by implementations of the AbstractCode class that need to validate the contents of that folder.

Parameters:: folder – A sandbox folder that the CalcJob plugin wrote input files to that will be copied to the working directory for the corresponding calculation job instance.
Raises:: PluginInternalError – If the content of the sandbox folder is not valid.

abstract property full_label: str#

Return the full label of this code.

The full label can be just the label itself but it can be something else. However, it at the very least has to include the label of the code.

Returns:: The full label of the code.

property label: str#

Return the label.

Returns:: The label.

property default_calc_job_plugin: str | None#

Return the optional default CalcJob plugin.

Returns:: The entry point name of the default CalcJob plugin to use.

property append_text: str#

Return the text that should be appended to the run line in the job script.

Returns:: The text that should be appended to the run line in the job script.

property prepend_text: str#

Return the text that should be prepended to the run line in the job script.

Returns:: The text that should be prepended to the run line in the job script.

property use_double_quotes: bool#

Return whether the command line invocation of this code should be escaped with double quotes.

Returns:: True if to escape with double quotes, False otherwise.

property is_hidden: bool#

Return whether the code is hidden.

Returns:: True if the code is hidden, False otherwise, which is also the default.

get_builder() → aiida.engine.ProcessBuilder#

Create and return a new ProcessBuilder for the CalcJob class of the plugin configured for this code.

The configured calculation plugin class is defined by the default_calc_job_plugin property.

Note

it also sets the builder.code value.

Returns:

a ProcessBuilder instance with the code input already populated with ourselves

Raises:

aiida.common.EntryPointError – if the specified plugin does not exist.
ValueError – if no default plugin was specified.

static cli_validate_label_uniqueness(_, __, value)#: Validate the uniqueness of the label of the code.

classmethod get_cli_options() → collections.OrderedDict#: Return the CLI options that would allow to create an instance of this class.

classmethod _get_cli_options() → dict#: Return the CLI options that would allow to create an instance of this class.

class aiida.orm.AbstractNodeMeta#

Bases: abc.ABCMeta

Some python black magic to set correctly the logger also in subclasses.

__new__(name, bases, namespace, **kwargs)#

class aiida.orm.ArrayData(*args, source=None, **kwargs)#

Bases: aiida.orm.nodes.data.data.Data

Store a set of arrays on disk (rather than on the database) in an efficient way using numpy.save() (therefore, this class requires numpy to be installed).

Each array is stored within the Node folder as a different .npy file.

Note:: Before storing, no caching is done: if you perform a get_array() call, the array will be re-read from disk. If instead the ArrayData node has already been stored, the array is cached in memory after the first read, and the cached array is used thereafter. If too much RAM memory is used, you can clear the cache with the clear_internal_cache() method.

Initialization

Construct a new instance, setting the source attribute if provided as a keyword argument.

array_prefix = 'array|'#

_cached_arrays = None#

initialize()#

delete_array(name)#

Delete an array from the node. Can only be called before storing.

Parameters:: name – The name of the array to delete from the node.

get_arraynames()#: Return a list of all arrays stored in the node, listing the files (and not relying on the properties).

New in version 0.7: Renamed from arraynames

_arraynames_from_files()#: Return a list of all arrays stored in the node, listing the files (and not relying on the properties).

_arraynames_from_properties()#: Return a list of all arrays stored in the node, listing the attributes starting with the correct prefix.

get_shape(name)#

Return the shape of an array (read from the value cached in the properties for efficiency reasons).

Parameters:: name – The name of the array.

get_iterarrays()#: Iterator that returns tuples (name, array) for each array stored in the node.

New in version 1.0: Renamed from iterarrays

get_array(name)#

Return an array stored in the node

Parameters:: name – The name of the array to return.

clear_internal_cache()#: Clear the internal memory cache where the arrays are stored after being read from disk (used in order to reduce at minimum the readings from disk). This function is useful if you want to keep the node in memory, but you do not want to waste memory to cache the arrays in RAM.

set_array(name, array)#

Store a new numpy array inside the node. Possibly overwrite the array if it already existed.

Internally, it stores a name.npy file in numpy format.

Parameters:

name – The name of the array.
array – The numpy array to store.

_validate()#: Check if the list of .npy files stored inside the node and the list of properties match. Just a name check, no check on the size since this would require to reload all arrays and this may take time and memory.

_get_array_entries()#

Return a dictionary with the different array entries.

The idea is that this dictionary contains the array name as a key and the value is the numpy array transformed into a list. This is so that it can be transformed into a json object.

_prepare_json(main_file_name='', comments=True)#

Dump the content of the arrays stored in this node into JSON format.

Parameters:: comments – if True, includes comments (if it makes sense for the given format)

class aiida.orm.AttributeManager(node)#

An object used internally to return the attributes as a dictionary. This is currently used in Dict, for instance.

Note:: Important! It cannot be used to change variables, just to read them. To change values (of unstored nodes), use the proper Node methods.

Initialization

Parameters:: node – the node object.

__dir__()#: Allow to list the keys of the dictionary

__iter__()#: Return the keys as an iterator

_get_dict()#: Return the internal dictionary

__getattr__(name)#

Interface to get to dictionary values, using the key as an attribute.

Note:: it works only for attributes that only contain letters, numbers and underscores, and do not start with a number.
Parameters:: name – name of the key whose value is required.

__setattr__(name, value)#

__getitem__(name)#

Interface to get to dictionary values as a dictionary.

Parameters:: name – name of the key whose value is required.

class aiida.orm.AuthInfo(computer: aiida.orm.Computer, user: aiida.orm.User, backend: Optional[aiida.orm.implementation.StorageBackend] = None)#

Bases: aiida.orm.entities.Entity[aiida.orm.implementation.BackendAuthInfo, aiida.orm.authinfos.AuthInfoCollection]

ORM class that models the authorization information that allows a User to connect to a Computer.

Initialization

Create an AuthInfo instance for the given computer and user.

Parameters:

computer – a Computer instance
user – a User instance
backend – the backend to use for the instance, or use the default backend if None

_CLS_COLLECTION = None#

PROPERTY_WORKDIR = 'workdir'#

__str__() → str#

property enabled: bool#

Return whether this instance is enabled.

Returns:: True if enabled, False otherwise

property computer: aiida.orm.Computer#: Return the computer associated with this instance.

property user: aiida.orm.User#: Return the user associated with this instance.

get_auth_params() → Dict[str, Any]#

Return the dictionary of authentication parameters

Returns:: a dictionary with authentication parameters

set_auth_params(auth_params: Dict[str, Any]) → None#

Set the dictionary of authentication parameters

Parameters:: auth_params – a dictionary with authentication parameters

get_metadata() → Dict[str, Any]#

Return the dictionary of metadata

Returns:: a dictionary with metadata

set_metadata(metadata: Dict[str, Any]) → None#

Set the dictionary of metadata

Parameters:: metadata – a dictionary with metadata

get_workdir() → str#

Return the working directory.

If no explicit work directory is set for this instance, the working directory of the computer will be returned.

Returns:: the working directory

get_transport() → aiida.transports.Transport#: Return a fully configured transport that can be used to connect to the computer set for this instance.

class aiida.orm.AutoGroup(label: Optional[str] = None, user: Optional[aiida.orm.User] = None, description: str = '', type_string: Optional[str] = None, backend: Optional[aiida.orm.implementation.StorageBackend] = None)#

Bases: aiida.orm.groups.Group

Group to be used to contain selected nodes generated, whilst autogrouping is enabled.

Initialization

Create a new group. Either pass a dbgroup parameter, to reload a group from the DB (and then, no further parameters are allowed), or pass the parameters for the Group creation.

Parameters:

label – The group label, required on creation
description – The group description (by default, an empty string)
user – The owner of the group (by default, the automatic user)
type_string – a string identifying the type of group (by default, an empty string, indicating an user-defined group.

class aiida.orm.BandsData#

Bases: aiida.orm.nodes.data.array.kpoints.KpointsData

Class to handle bands data

set_kpointsdata(kpointsdata)#: Load the kpoints from a kpoint object. :param kpointsdata: an instance of KpointsData class

_validate_bands_occupations(bands, occupations=None, labels=None)#: Validate the list of bands and of occupations before storage. Kpoints must be set in advance. Bands and occupations must be convertible into arrays of Nkpoints x Nbands floats or Nspins x Nkpoints x Nbands; Nkpoints must correspond to the number of kpoints.

set_bands(bands, units=None, occupations=None, labels=None)#: Set an array of band energies of dimension (nkpoints x nbands). Kpoints must be set in advance. Can contain floats or None. :param bands: a list of nkpoints lists of nbands bands, or a 2D array of shape (nkpoints x nbands), with band energies for each kpoint :param units: optional, energy units :param occupations: optional, a 2D list or array of floats of same shape as bands, with the occupation associated to each band

property array_labels#: Get the labels associated with the band arrays

property units#: Units in which the data in bands were stored. A string

_set_pbc(value)#: validate the pbc, then store them

get_bands(also_occupations=False, also_labels=False)#: Returns an array (nkpoints x num_bands or nspins x nkpoints x num_bands) of energies. :param also_occupations: if True, returns also the occupations array. Default = False

_get_bandplot_data(cartesian, prettify_format=None, join_symbol=None, get_segments=False, y_origin=0.0)#

Get data to plot a band structure

Parameters:

cartesian – if True, distances (for the x-axis) are computed in cartesian coordinates, otherwise they are computed in reciprocal coordinates. cartesian=True will fail if no cell has been set.
prettify_format – by default, strings are not prettified. If you want to prettify them, pass a valid prettify_format string (see valid options in the docstring of :py:func:prettify_labels).
join_symbols – by default, strings are not joined. If you pass a string, this is used to join strings that are much closer than a given threshold. The most typical string is the pipe symbol: |.
get_segments – if True, also computes the band split into segments
y_origin – if present, shift bands so to set the value specified at y=0

Returns:

a plot_info dictiorary, whose keys are x (array of distances for the x axis of the plot); y (array of bands), labels (list of tuples in the format (float x value of the label, label string), band_type_idx (array containing an index for each band: if there is only one spin, then it’s an array of zeros, of length equal to the number of bands at each point; if there are two spins, then it’s an array of zeros or ones depending on the type of spin; the length is always equalt to the total number of bands per kpoint).

_prepare_agr_batch(main_file_name='', comments=True, prettify_format=None)#

Prepare two files, data and batch, to be plot with xmgrace as: xmgrace -batch file.dat

Parameters:

main_file_name – if the user asks to write the main content on a file, this contains the filename. This should be used to infer a good filename for the additional files. In this case, we remove the extension, and add ‘_data.dat’
comments – if True, print comments (if it makes sense for the given format)
prettify_format – if None, use the default prettify format. Otherwise specify a string with the prettifier to use.

_prepare_dat_multicolumn(main_file_name='', comments=True)#

Write an N x M matrix. First column is the distance between kpoints, The other columns are the bands. Header contains number of kpoints and the number of bands (commented).

Parameters:: comments – if True, print comments (if it makes sense for the given format)

_prepare_dat_blocks(main_file_name='', comments=True)#

Format suitable for gnuplot using blocks. Columns with x and y (path and band energy). Several blocks, separated by two empty lines, one per energy band.

Parameters:: comments – if True, print comments (if it makes sense for the given format)

_matplotlib_get_dict(main_file_name='', comments=True, title='', legend=None, legend2=None, y_max_lim=None, y_min_lim=None, y_origin=0.0, prettify_format=None, **kwargs)#

Prepare the data to send to the python-matplotlib plotting script.

Parameters:

comments – if True, print comments (if it makes sense for the given format)
plot_info – a dictionary
setnumber_offset – an offset to be applied to all set numbers (i.e. s0 is replaced by s[offset], s1 by s[offset+1], etc.)
color_number – the color number for lines, symbols, error bars and filling (should be less than the parameter MAX_NUM_AGR_COLORS defined below)
title – the title
legend – the legend (applied only to the first of the set)
legend2 – the legend for second-type spins (applied only to the first of the set)
y_max_lim – the maximum on the y axis (if None, put the maximum of the bands)
y_min_lim – the minimum on the y axis (if None, put the minimum of the bands)
y_origin – the new origin of the y axis -> all bands are replaced by bands-y_origin
prettify_format – if None, use the default prettify format. Otherwise specify a string with the prettifier to use.
kwargs – additional customization variables; only a subset is accepted, see internal variable ‘valid_additional_keywords

_prepare_mpl_singlefile(*args, **kwargs)#

Prepare a python script using matplotlib to plot the bands

For the possible parameters, see documentation of _matplotlib_get_dict()

_prepare_mpl_withjson(main_file_name='', *args, **kwargs)#

Prepare a python script using matplotlib to plot the bands, with the JSON returned as an independent file.

For the possible parameters, see documentation of _matplotlib_get_dict()

_prepare_mpl_pdf(main_file_name='', *args, **kwargs)#

Prepare a python script using matplotlib to plot the bands, with the JSON returned as an independent file.

For the possible parameters, see documentation of _matplotlib_get_dict()

_prepare_mpl_png(main_file_name='', *args, **kwargs)#

Prepare a python script using matplotlib to plot the bands, with the JSON returned as an independent file.

For the possible parameters, see documentation of _matplotlib_get_dict()

static _get_mpl_body_template(paths)#

Parameters:: paths – paths of k-points

show_mpl(**kwargs)#

Call a show() command for the band structure using matplotlib. This uses internally the ‘mpl_singlefile’ format, with empty main_file_name.

Other kwargs are passed to self._exportcontent.

_prepare_gnuplot(main_file_name=None, title='', comments=True, prettify_format=None, y_max_lim=None, y_min_lim=None, y_origin=0.0)#

Prepare an gnuplot script to plot the bands, with the .dat file returned as an independent file.

Parameters:

main_file_name – if the user asks to write the main content on a file, this contains the filename. This should be used to infer a good filename for the additional files. In this case, we remove the extension, and add ‘_data.dat’
title – if specified, add a title to the plot
comments – if True, print comments (if it makes sense for the given format)
prettify_format – if None, use the default prettify format. Otherwise specify a string with the prettifier to use.

_prepare_agr(main_file_name='', comments=True, setnumber_offset=0, color_number=1, color_number2=2, legend='', title='', y_max_lim=None, y_min_lim=None, y_origin=0.0, prettify_format=None)#

Prepare an xmgrace agr file.

Parameters:

comments – if True, print comments (if it makes sense for the given format)
plot_info – a dictionary
setnumber_offset – an offset to be applied to all set numbers (i.e. s0 is replaced by s[offset], s1 by s[offset+1], etc.)
color_number – the color number for lines, symbols, error bars and filling (should be less than the parameter MAX_NUM_AGR_COLORS defined below)
color_number2 – the color number for lines, symbols, error bars and filling for the second-type spins (should be less than the parameter MAX_NUM_AGR_COLORS defined below)
legend – the legend (applied only to the first set)
title – the title
y_max_lim – the maximum on the y axis (if None, put the maximum of the bands); applied after shifting the origin by y_origin
y_min_lim – the minimum on the y axis (if None, put the minimum of the bands); applied after shifting the origin by y_origin
y_origin – the new origin of the y axis -> all bands are replaced by bands-y_origin
prettify_format – if None, use the default prettify format. Otherwise specify a string with the prettifier to use.

_get_band_segments(cartesian)#: Return the band segments.

_prepare_json(main_file_name='', comments=True)#

Prepare a json file in a format compatible with the AiiDA band visualizer

Parameters:: comments – if True, print comments (if it makes sense for the given format)

class aiida.orm.BaseType(value=None, **kwargs)#

Bases: aiida.orm.nodes.data.data.Data

Data sub class to be used as a base for data containers that represent base python data types.

Initialization

property value#

__str__()#

__eq__(other)#

new(value=None)#

class aiida.orm.Bool(value=None, **kwargs)#

Bases: aiida.orm.nodes.data.base.BaseType

Data sub class to represent a boolean value.

Initialization

_type = None#

__int__()#

__bool__()#

class aiida.orm.CalcFunctionNode(backend: Optional[aiida.orm.implementation.StorageBackend] = None, user: Optional[aiida.orm.users.User] = None, computer: Optional[aiida.orm.computers.Computer] = None, **kwargs: Any)#

Bases: aiida.orm.utils.mixins.FunctionCalculationMixin, aiida.orm.nodes.process.calculation.calculation.CalculationNode

ORM class for all nodes representing the execution of a calcfunction.

Initialization

Parameters:: backend_entity – the backend model supporting this entity

_CLS_NODE_LINKS = None#

class aiida.orm.CalcJobNode(backend: Optional[aiida.orm.implementation.StorageBackend] = None, user: Optional[aiida.orm.users.User] = None, computer: Optional[aiida.orm.computers.Computer] = None, **kwargs: Any)#

Bases: aiida.orm.nodes.process.calculation.calculation.CalculationNode

ORM class for all nodes representing the execution of a CalcJob.

Initialization

Parameters:: backend_entity – the backend model supporting this entity

CALC_JOB_STATE_KEY = 'state'#

IMMIGRATED_KEY = 'imported'#

REMOTE_WORKDIR_KEY = 'remote_workdir'#

RETRIEVE_LIST_KEY = 'retrieve_list'#

RETRIEVE_TEMPORARY_LIST_KEY = 'retrieve_temporary_list'#

SCHEDULER_JOB_ID_KEY = 'job_id'#

SCHEDULER_STATE_KEY = 'scheduler_state'#

SCHEDULER_LAST_CHECK_TIME_KEY = 'scheduler_lastchecktime'#

SCHEDULER_LAST_JOB_INFO_KEY = 'last_job_info'#

SCHEDULER_DETAILED_JOB_INFO_KEY = 'detailed_job_info'#

_tools = None#

property tools: aiida.tools.calculations.CalculationTools#

Return the calculation tools that are registered for the process type associated with this calculation.

If the entry point name stored in the process_type of the CalcJobNode has an accompanying entry point in the aiida.tools.calculations entry point category, it will attempt to load the entry point and instantiate it passing the node to the constructor. If the entry point does not exist, cannot be resolved or loaded, a warning will be logged and the base CalculationTools class will be instantiated and returned.

Returns:: CalculationTools instance

_updatable_attributes() → Tuple[str, ...]#

_hash_ignored_attributes() → Tuple[str, ...]#

get_builder_restart() → aiida.engine.processes.builder.ProcessBuilder#

Return a ProcessBuilder that is ready to relaunch the same CalcJob that created this node.

The process class will be set based on the process_type of this node and the inputs of the builder will be prepopulated with the inputs registered for this node. This functionality is very useful if a process has completed and you want to relaunch it with slightly different inputs.

In addition to prepopulating the input nodes, which is implemented by the base ProcessNode class, here we also add the options that were passed in the metadata input of the CalcJob process.

property is_imported: bool#: Return whether the calculation job was imported instead of being an actual run.

get_option(name: str) → Optional[Any]#

Retun the value of an option that was set for this CalcJobNode

Parameters:: name – the option name
Returns:: the option value or None
Raises:: ValueError for unknown option

set_option(name: str, value: Any) → None#

Set an option to the given value

Parameters:

name – the option name
value – the value to set

Raises:

ValueError for unknown option

Raises:

TypeError for values with invalid type

get_options() → Dict[str, Any]#

Return the dictionary of options set for this CalcJobNode

Returns:: dictionary of the options and their values

set_options(options: Dict[str, Any]) → None#

Set the options for this CalcJobNode

Parameters:: options – dictionary of option and their values to set

get_state() → Optional[aiida.common.datastructures.CalcJobState]#

Return the calculation job active sub state.

The calculation job state serves to give more granular state information to CalcJobs, in addition to the generic process state, while the calculation job is active. The state can take values from the enumeration defined in aiida.common.datastructures.CalcJobState and can be used to query for calculation jobs in specific active states.

Returns:: instance of aiida.common.datastructures.CalcJobState or None if invalid value, or not set

set_state(state: aiida.common.datastructures.CalcJobState) → None#

Set the calculation active job state.

Raise:: ValueError if state is invalid

delete_state() → None#: Delete the calculation job state attribute if it exists.

set_remote_workdir(remote_workdir: str) → None#

Set the absolute path to the working directory on the remote computer where the calculation is run.

Parameters:: remote_workdir – absolute filepath to the remote working directory

get_remote_workdir() → Optional[str]#

Return the path to the remote (on cluster) scratch folder of the calculation.

Returns:: a string with the remote path

static _validate_retrieval_directive(directives: Sequence[Union[str, Tuple[str, str, str]]]) → None#

Validate a list or tuple of file retrieval directives.

Parameters:: directives – a list or tuple of file retrieval directives
Raises:: ValueError – if the format of the directives is invalid

set_retrieve_list(retrieve_list: Sequence[Union[str, Tuple[str, str, str]]]) → None#

Set the retrieve list.

This list of directives will instruct the daemon what files to retrieve after the calculation has completed. list or tuple of files or paths that should be retrieved by the daemon.

Parameters:: retrieve_list – list or tuple of with filepath directives

get_retrieve_list() → Optional[Sequence[Union[str, Tuple[str, str, str]]]]#

Return the list of files/directories to be retrieved on the cluster after the calculation has completed.

Returns:: a list of file directives

set_retrieve_temporary_list(retrieve_temporary_list: Sequence[Union[str, Tuple[str, str, str]]]) → None#

Set the retrieve temporary list.

The retrieve temporary list stores files that are retrieved after completion and made available during parsing and are deleted as soon as the parsing has been completed.

Parameters:: retrieve_temporary_list – list or tuple of with filepath directives

get_retrieve_temporary_list() → Optional[Sequence[Union[str, Tuple[str, str, str]]]]#

Return list of files to be retrieved from the cluster which will be available during parsing.

Returns:: a list of file directives

set_job_id(job_id: Union[int, str]) → None#

Set the job id that was assigned to the calculation by the scheduler.

Note

the id will always be stored as a string

Parameters:: job_id – the id assigned by the scheduler after submission

get_job_id() → Optional[str]#

Return job id that was assigned to the calculation by the scheduler.

Returns:: the string representation of the scheduler job id

set_scheduler_state(state: aiida.schedulers.datastructures.JobState) → None#

Set the scheduler state.

Parameters:: state – an instance of JobState

get_scheduler_state() → Optional[aiida.schedulers.datastructures.JobState]#

Return the status of the calculation according to the cluster scheduler.

Returns:: a JobState enum instance.

get_scheduler_lastchecktime() → Optional[datetime.datetime]#

Return the time of the last update of the scheduler state by the daemon or None if it was never set.

Returns:: a datetime object or None

set_detailed_job_info(detailed_job_info: Optional[dict]) → None#

Set the detailed job info dictionary.

Parameters:: detailed_job_info – a dictionary with metadata with the accounting of a completed job

get_detailed_job_info() → Optional[dict]#

Return the detailed job info dictionary.

The scheduler is polled for the detailed job info after the job is completed and ready to be retrieved.

Returns:: the dictionary with detailed job info if defined or None

set_last_job_info(last_job_info: aiida.schedulers.datastructures.JobInfo) → None#

Set the last job info.

Parameters:: last_job_info – a JobInfo object

get_last_job_info() → Optional[aiida.schedulers.datastructures.JobInfo]#

Return the last information asked to the scheduler about the status of the job.

The last job info is updated on every poll of the scheduler, except for the final poll when the job drops from the scheduler’s job queue. For completed jobs, the last job info therefore contains the “second-to-last” job info that still shows the job as running. Please use get_detailed_job_info() instead.

Returns:: a JobInfo object (that closely resembles a dictionary) or None.

get_authinfo() → aiida.orm.authinfos.AuthInfo#

Return the AuthInfo that is configured for the Computer set for this node.

Returns:: AuthInfo

get_transport() → aiida.transports.Transport#

Return the transport for this calculation.

Returns:: Transport configured with the AuthInfo associated to the computer of this node

get_parser_class() → Optional[Type[aiida.parsers.Parser]]#

Return the output parser object for this calculation or None if no parser is set.

Returns:: a Parser class.
Raises:: aiida.common.exceptions.EntryPointError – if the parser entry point can not be resolved.

property link_label_retrieved: str#: Return the link label used for the retrieved FolderData node.

get_retrieved_node() → Optional[aiida.orm.FolderData]#

Return the retrieved data folder.

Returns:: the retrieved FolderData node or None if not found

property res: aiida.orm.utils.calcjob.CalcJobResultManager#

To be used to get direct access to the parsed parameters.

Returns:: an instance of the CalcJobResultManager.
Note:: a practical example on how it is meant to be used: let’s say that there is a key ‘energy’ in the dictionary of the parsed results which contains a list of floats. The command calc.res.energy will return such a list.

get_scheduler_stdout() → Optional[AnyStr]#

Return the scheduler stderr output if the calculation has finished and been retrieved, None otherwise.

Returns:: scheduler stderr output or None

get_scheduler_stderr() → Optional[AnyStr]#

Return the scheduler stdout output if the calculation has finished and been retrieved, None otherwise.

Returns:: scheduler stdout output or None

get_description() → str#: Return a description of the node based on its properties.

class aiida.orm.CalcJobResultManager(node)#

Utility class to easily access the contents of the ‘default output’ node of a CalcJobNode.

A CalcJob process can mark one of its outputs as the ‘default output’. The default output node will always be returned by the CalcJob and will always be a Dict node.

If a CalcJob defines such a default output node, this utility class will simplify retrieving the result of said node through the CalcJobNode instance produced by the execution of the CalcJob.

The default results are only defined if the CalcJobNode has a process_type that can be successfully used to load the corresponding CalcJob process class and if its process spec defines a default_output_node. If both these conditions are met, the results are defined as the dictionary contained within the default output node.

Initialization

Construct an instance of the CalcJobResultManager.

Parameters:: calc – the CalcJobNode instance.

property node#: Return the CalcJobNode associated with this result manager instance.

_load_results()#

Try to load the results for the CalcJobNode of this result manager.

Raises:: ValueError – if no default output node could be loaded

get_results()#

Return the results dictionary of the default results node of the calculation node.

This property will lazily load the dictionary.

Returns:: the dictionary of the default result node

__dir__()#: Add the keys of the results dictionary such that they can be autocompleted.

__iter__()#: Return an iterator over the keys of the result dictionary.

__getattr__(name)#

Return an attribute from the results dictionary.

Parameters:: name – name of the result return
Returns:: value of the attribute
Raises:: AttributeError – if the results node cannot be retrieved or it does not contain the name attribute

__getitem__(name)#

Return an attribute from the results dictionary.

Parameters:: name – name of the result return
Returns:: value of the attribute
Raises:: KeyError – if the results node cannot be retrieved or it does not contain the name attribute

class aiida.orm.CalculationEntityLoader#

Bases: aiida.orm.utils.loaders.OrmEntityLoader

Loader for the Calculation entity and sub classes.

orm_base_class()#

Return the orm base class to which loaded entities should be mapped. Actual queries to load an entity may further narrow the query set by defining a more specific set of orm classes, as long as each of those is a strict sub class of the orm base class.

Returns:: the orm base class

classmethod _get_query_builder_label_identifier(identifier, classes, operator='==', project='*')#

Return the query builder instance that attempts to map the identifier onto an entity of the orm class, defined for this loader class, interpreting the identifier as a LABEL like identifier

Parameters:

identifier – the LABEL identifier
classes – a tuple of orm classes to which the identifier should be mapped
operator – the operator to use in the query
project – the property or properties to project for entities matching the query

Returns:

the query builder instance that should retrieve the entity corresponding to the identifier

Raises:

ValueError – if the identifier is invalid
aiida.common.NotExistent – if the orm base class does not support a LABEL like identifier

class aiida.orm.CalculationNode(backend: Optional[aiida.orm.implementation.StorageBackend] = None, user: Optional[aiida.orm.users.User] = None, computer: Optional[aiida.orm.computers.Computer] = None, **kwargs: Any)#

Bases: aiida.orm.nodes.process.process.ProcessNode

Base class for all nodes representing the execution of a calculation process.

Initialization

Parameters:: backend_entity – the backend model supporting this entity

_storable = True#

_cachable = True#

_unstorable_message = 'storing for this node has been disabled'#

property inputs: aiida.orm.utils.managers.NodeLinksManager#

Return an instance of NodeLinksManager to manage incoming INPUT_CALC links

The returned Manager allows you to easily explore the nodes connected to this node via an incoming INPUT_CALC link. The incoming nodes are reachable by their link labels which are attributes of the manager.

property outputs: aiida.orm.utils.managers.NodeLinksManager#

Return an instance of NodeLinksManager to manage outgoing CREATE links

The returned Manager allows you to easily explore the nodes connected to this node via an outgoing CREATE link. The outgoing nodes are reachable by their link labels which are attributes of the manager.

class aiida.orm.CifData(ase=None, file=None, filename=None, values=None, scan_type=None, parse_policy=None, **kwargs)#

Bases: aiida.orm.nodes.data.singlefile.SinglefileData

Wrapper for Crystallographic Interchange File (CIF)

Note

the file (physical) is held as the authoritative source of information, so all conversions are done through the physical file: when setting ase or values, a physical CIF file is generated first, the values are updated from the physical CIF file.

Initialization

Construct a new instance and set the contents to that of the file.

Parameters:

file – an absolute filepath or filelike object for CIF. Hint: Pass io.BytesIO(b”my string”) to construct the SinglefileData directly from a string.
filename – specify filename to use (defaults to name of provided file).
ase – ASE Atoms object to construct the CifData instance from.
values – PyCifRW CifFile object to construct the CifData instance from.
scan_type – scan type string for parsing with PyCIFRW (‘standard’ or ‘flex’). See CifFile.ReadCif
parse_policy – ‘eager’ (parse CIF file on set_file) or ‘lazy’ (defer parsing until needed)

_SET_INCOMPATIBILITIES = [('ase', 'file'), ('ase', 'values'), ('file', 'values')]#

_SCAN_TYPES = ('standard', 'flex')#

_SCAN_TYPE_DEFAULT = 'standard'#

_PARSE_POLICIES = ('eager', 'lazy')#

_PARSE_POLICY_DEFAULT = 'eager'#

_values = None#

_ase = None#

static read_cif(fileobj, index=-1, **kwargs)#

A wrapper method that simulates the behavior of the old function ase.io.cif.read_cif by using the new generic ase.io.read function.

Somewhere from 3.12 to 3.17 the tag concept was bundled with each Atom object. When reading a CIF file, this is incremented and signifies the atomic species, even though the CIF file do not have specific tags embedded. On reading CIF files we thus force the ASE tag to zero for all Atom elements.

classmethod from_md5(md5, backend=None)#: Return a list of all CIF files that match a given MD5 hash.

Note

the hash has to be stored in a _md5 attribute, otherwise the CIF file will not be found.

classmethod get_or_create(filename, use_first=False, store_cif=True)#

Pass the same parameter of the init; if a file with the same md5 is found, that CifData is returned.

Parameters:

filename – an absolute filename on disk
use_first – if False (default), raise an exception if more than one CIF file is found. If it is True, instead, use the first available CIF file.
store_cif (bool) – If false, the CifData objects are not stored in the database. default=True.

Return (cif, created):

where cif is the CifData object, and create is either True if the object was created, or False if the object was retrieved from the DB.

property ase#: ASE object, representing the CIF.

Note

requires ASE module.

get_ase(**kwargs)#: Returns ASE object, representing the CIF. This function differs from the property ase by the possibility to pass the keyworded arguments (kwargs) to ase.io.cif.read_cif().

Note

requires ASE module.

set_ase(aseatoms)#

Set the contents of the CifData starting from an ASE atoms object

Parameters:: aseatoms – the ASE atoms object

property values#: PyCifRW structure, representing the CIF datablocks.

Note

requires PyCifRW module.

set_values(values)#

Set internal representation to values.

Warning: This also writes a new CIF file.

Parameters:: values – PyCifRW CifFile object

Note

requires PyCifRW module.

parse(scan_type=None)#

Parses CIF file and sets attributes.

Parameters:: scan_type – See set_scan_type

store(*args, **kwargs)#: Store the node.

set_file(file, filename=None)#

Set the file.

If the source is set and the MD5 checksum of new file is different from the source, the source has to be deleted.

Parameters:

file – filepath or filelike object of the CIF file to store. Hint: Pass io.BytesIO(b”my string”) to construct the file directly from a string.
filename – specify filename to use (defaults to name of provided file).

set_scan_type(scan_type)#

Set the scan_type for PyCifRW.

The ‘flex’ scan_type of PyCifRW is faster for large CIF files but does not yet support the CIF2 format as of 02/2018. See the CifFile.ReadCif function

Parameters:: scan_type – Either ‘standard’ or ‘flex’ (see _scan_types)

set_parse_policy(parse_policy)#

Set the parse policy.

Parameters:: parse_policy – Either ‘eager’ (parse CIF file on set_file) or ‘lazy’ (defer parsing until needed)

get_formulae(mode='sum', custom_tags=None)#

Return chemical formulae specified in CIF file.

Note: This does not compute the formula, it only reads it from the appropriate tag. Use refine_inline to compute formulae.

get_spacegroup_numbers()#: Get the spacegroup international number.

property has_partial_occupancies#

Return if the cif data contains partial occupancies

A partial occupancy is defined as site with an occupancy that differs from unity, within a precision of 1E-6

Returns:: True if there are partial occupancies, False otherwise

property has_attached_hydrogens#

Check if there are hydrogens without coordinates, specified as attached to the atoms of the structure.

Returns:: True if there are attached hydrogens, False otherwise.

property has_undefined_atomic_sites#

Return whether the cif data contains any undefined atomic sites.

An undefined atomic site is defined as a site where at least one of the fractional coordinates specified in the _atom_site_fract_* tags, cannot be successfully interpreted as a float. If the cif data contains any site that matches this description, or it does not contain any atomic site tags at all, the cif data is said to have undefined atomic sites.

Returns:: boolean, True if no atomic sites are defined or if any of the defined sites contain undefined positions and False otherwise

property has_atomic_sites#

Returns whether there are any atomic sites defined in the cif data. That is to say, it will check all the values for the _atom_site_fract_* tags and if they are all equal to ? that means there are no relevant atomic sites defined and the function will return False. In all other cases the function will return True

Returns:: False when at least one atomic site fractional coordinate is not equal to ? and True otherwise

property has_unknown_species#

Returns whether the cif contains atomic species that are not recognized by AiiDA.

The known species are taken from the elements dictionary in aiida.common.constants, with the exception of the “unknown” placeholder element with symbol ‘X’, as this could not be used to construct a real structure. If any of the formula of the cif data contain species that are not in that elements dictionary, the function will return True and False in all other cases. If there is no formulae to be found, it will return None

Returns:: True when there are unknown species in any of the formulae, False if not, None if no formula found

generate_md5()#: Computes and returns MD5 hash of the CIF file.

get_structure(converter='pymatgen', store=False, **kwargs)#

Creates aiida.orm.nodes.data.structure.StructureData.

New in version 1.0: Renamed from _get_aiida_structure

Parameters:

converter – specify the converter. Default ‘pymatgen’.
store – if True, intermediate calculation gets stored in the AiiDA database for record. Default False.
primitive_cell – if True, primitive cell is returned, conventional cell if False. Default False.
occupancy_tolerance – If total occupancy of a site is between 1 and occupancy_tolerance, the occupancies will be scaled down to 1. (pymatgen only)
site_tolerance – This tolerance is used to determine if two sites are sitting in the same position, in which case they will be combined to a single disordered site. Defaults to 1e-4. (pymatgen only)

Returns:

aiida.orm.nodes.data.structure.StructureData node.

_prepare_cif(**kwargs)#

Return CIF string of CifData object.

If parsed values are present, a CIF string is created and written to file. If no parsed values are present, the CIF string is read from file.

_get_object_ase()#

Converts CifData to ase.Atoms

Returns:: an ase.Atoms object

_get_object_pycifrw()#

Converts CifData to PyCIFRW.CifFile

Returns:: a PyCIFRW.CifFile object

_validate()#: Validates MD5 hash of CIF file.

class aiida.orm.Code(remote_computer_exec=None, local_executable=None, input_plugin_name=None, files=None, **kwargs)#

Bases: aiida.orm.nodes.data.code.abstract.AbstractCode

A code entity. It can either be ‘local’, or ‘remote’.

Local code: it is a collection of files/dirs (added using the add_path() method), where one file is flagged as executable (using the set_local_executable() method).
Remote code: it is a pair (remotecomputer, remotepath_of_executable) set using the set_remote_computer_exec() method.

For both codes, one can set some code to be executed right before or right after the execution of the code, using the set_preexec_code() and set_postexec_code() methods (e.g., the set_preexec_code() can be used to load specific modules required for the code to be run).

Initialization

HIDDEN_KEY = 'hidden'#

can_run_on_computer(computer: aiida.orm.Computer) → bool#

Return whether the code can run on a given computer.

Parameters:: computer – The computer.
Returns:: True if the code can run on computer, False otherwise.

get_executable() → pathlib.PurePosixPath#

Return the executable that the submission script should execute to run the code.

Returns:: The executable to be called in the submission script.

hide()#: Hide the code (prevents from showing it in the verdi code list)

reveal()#: Reveal the code (allows to show it in the verdi code list) By default, it is revealed

property hidden#: Determines whether the Code is hidden or not

set_files(files)#

Given a list of filenames (or a single filename string), add it to the path (all at level zero, i.e. without folders). Therefore, be careful for files with the same name!

Todo:: decide whether to check if the Code must be a local executable to be able to call this function.

__str__()#

get_computer_label()#: Get label of this code’s computer.

property full_label#

Get full label of this code.

Returns label of the form <code-label>@<computer-name>.

relabel(new_label)#

Relabel this code.

Parameters:: new_label – new code label

get_description()#

Return a string description of this Code instance.

Returns:: string description of this Code instance

classmethod get_code_helper(label, machinename=None, backend=None)#

Parameters:

label – the code label identifying the code to load
machinename – the machine name where code is setup

Raises:

aiida.common.NotExistent – if no code identified by the given string is found
aiida.common.MultipleObjectsError – if the string cannot identify uniquely a code

classmethod get(pk=None, label=None, machinename=None)#

Get a Computer object with given identifier string, that can either be the numeric ID (pk), or the label (and computername) (if unique).

Parameters:

pk – the numeric ID (pk) for code
label – the code label identifying the code to load
machinename – the machine name where code is setup

Raises:

aiida.common.NotExistent – if no code identified by the given string is found
aiida.common.MultipleObjectsError – if the string cannot identify uniquely a code
ValueError – if neither a pk nor a label was passed in

classmethod get_from_string(code_string)#

Get a Computer object with given identifier string in the format label@machinename. See the note below for details on the string detection algorithm.

Note

the (leftmost) ‘@’ symbol is always used to split code and computername. Therefore do not use ‘@’ in the code name if you want to use this function (‘@’ in the computer name are instead valid).

Parameters:

code_string – the code string identifying the code to load

Raises:

aiida.common.NotExistent – if no code identified by the given string is found
aiida.common.MultipleObjectsError – if the string cannot identify uniquely a code
TypeError – if code_string is not of string type

classmethod list_for_plugin(plugin, labels=True, backend=None)#

Return a list of valid code strings for a given plugin.

Parameters:

plugin – The string of the plugin.
labels – if True, return a list of code names, otherwise return the code PKs (integers).

Returns:

a list of string, with the code names if labels is True, otherwise a list of integers with the code PKs.

_validate()#

validate_remote_exec_path()#

Validate the remote_exec_path attribute.

Checks whether the executable exists on the remote computer if a transport can be opened to it. This method is intentionally not called in _validate as to allow the creation of Code instances whose computers can not yet be connected to and as to not require the overhead of opening transports in storing a new code.

Raises:: ValidationError – if no transport could be opened or if the defined executable does not exist on the remote computer.

set_prepend_text(code)#: Pass a string of code that will be put in the scheduler script before the execution of the code.

get_prepend_text()#: Return the code that will be put in the scheduler script before the execution, or an empty string if no pre-exec code was defined.

set_input_plugin_name(input_plugin)#: Set the name of the default input plugin, to be used for the automatic generation of a new calculation.

get_input_plugin_name()#: Return the name of the default input plugin (or None if no input plugin was set.

set_use_double_quotes(use_double_quotes: bool)#

Set whether the command line invocation of this code should be escaped with double quotes.

Parameters:: use_double_quotes – True if to escape with double quotes, False otherwise.

get_use_double_quotes() → bool#

Return whether the command line invocation of this code should be escaped with double quotes.

Returns:: True if to escape with double quotes, False otherwise which is also the default.

set_append_text(code)#: Pass a string of code that will be put in the scheduler script after the execution of the code.

get_append_text()#: Return the postexec_code, or an empty string if no post-exec code was defined.

set_local_executable(exec_name)#: Set the filename of the local executable. Implicitly set the code as local.

get_local_executable()#

set_remote_computer_exec(remote_computer_exec)#

Set the code as remote, and pass the computer on which it resides and the absolute path on that computer.

Parameters:: remote_computer_exec – a tuple (computer, remote_exec_path), where computer is a aiida.orm.Computer and remote_exec_path is the absolute path of the main executable on remote computer.

get_remote_exec_path()#

get_remote_computer()#: Return the remote computer associated with this code.

_set_local()#

Set the code as a ‘local’ code, meaning that all the files belonging to the code will be copied to the cluster, and the file set with set_exec_filename will be run.

It also deletes the flags related to the local case (if any)

_set_remote()#

Set the code as a ‘remote’ code, meaning that the code itself has no files attached, but only a location on a remote computer (with an absolute path of the executable on the remote computer).

It also deletes the flags related to the local case (if any)

is_local()#: Return True if the code is ‘local’, False if it is ‘remote’ (see also documentation of the set_local and set_remote functions).

can_run_on(computer)#

Return True if this code can run on the given computer, False otherwise.

Local codes can run on any machine; remote codes can run only on the machine on which they reside.

TODO: add filters to mask the remote machines on which a local code can run.

get_execname()#: Return the executable string to be put in the script. For local codes, it is ./LOCAL_EXECUTABLE_NAME For remote codes, it is the absolute path to the executable.

class aiida.orm.CodeEntityLoader#

Bases: aiida.orm.utils.loaders.OrmEntityLoader

Loader for the Code entity and sub classes.

orm_base_class()#

Returns:: the orm base class

classmethod _get_query_builder_label_identifier(identifier, classes, operator='==', project='*')#

Return the query builder instance that attempts to map the identifier onto an entity of the orm class, defined for this loader class, interpreting the identifier as a LABEL like identifier

Parameters:

identifier – the LABEL identifier
classes – a tuple of orm classes to which the identifier should be mapped
operator – the operator to use in the query
project – the property or properties to project for entities matching the query

Returns:

the query builder instance that should retrieve the entity corresponding to the identifier

Raises:

ValueError – if the identifier is invalid
aiida.common.NotExistent – if the orm base class does not support a LABEL like identifier

class aiida.orm.Collection(entity_class: Type[aiida.orm.entities.EntityType], backend: Optional[aiida.orm.implementation.StorageBackend] = None)#

Bases: abc.ABC, typing.Generic[aiida.orm.entities.EntityType]

Container class that represents the collection of objects of a particular entity type.

Initialization

Construct a new entity collection.

Parameters:

entity_class – the entity type e.g. User, Computer, etc
backend – the backend instance to get the collection for, or use the default

abstract static _entity_base_cls() → Type[aiida.orm.entities.EntityType]#: The allowed entity class or subclasses thereof.

classmethod get_cached(entity_class: Type[aiida.orm.entities.EntityType], backend: aiida.orm.implementation.StorageBackend)#

Get the cached collection instance for the given entity class and backend.

Parameters:: backend – the backend instance to get the collection for

__call__(backend: aiida.orm.implementation.StorageBackend) → aiida.orm.entities.CollectionType#: Get or create a cached collection using a new backend.

property entity_type: Type[aiida.orm.entities.EntityType]#: The entity type for this instance.

property backend: aiida.orm.implementation.StorageBackend#: Return the backend.

query(filters: Optional[aiida.orm.querybuilder.FilterType] = None, order_by: Optional[aiida.orm.querybuilder.OrderByType] = None, limit: Optional[int] = None, offset: Optional[int] = None) → aiida.orm.querybuilder.QueryBuilder#

Get a query builder for the objects of this collection.

Parameters:

filters – the keyword value pair filters to match
order_by – a list of (key, direction) pairs specifying the sort order
limit – the maximum number of results to return
offset – number of initial results to be skipped

get(**filters: Any) → aiida.orm.entities.EntityType#

Get a single collection entry that matches the filter criteria.

Parameters:: filters – the filters identifying the object to get
Returns:: the entry

find(filters: Optional[aiida.orm.querybuilder.FilterType] = None, order_by: Optional[aiida.orm.querybuilder.OrderByType] = None, limit: Optional[int] = None) → List[aiida.orm.entities.EntityType]#

Find collection entries matching the filter criteria.

Parameters:

filters – the keyword value pair filters to match
order_by – a list of (key, direction) pairs specifying the sort order
limit – the maximum number of results to return

Returns:

a list of resulting matches

all() → List[aiida.orm.entities.EntityType]#

Get all entities in this collection.

Returns:: A list of all entities

count(filters: Optional[aiida.orm.querybuilder.FilterType] = None) → int#

Count entities in this collection according to criteria.

Parameters:: filters – the keyword value pair filters to match
Returns:: The number of entities found using the supplied criteria

class aiida.orm.Comment(node: aiida.orm.Node, user: aiida.orm.User, content: Optional[str] = None, backend: Optional[aiida.orm.implementation.StorageBackend] = None)#

Bases: aiida.orm.entities.Entity[aiida.orm.implementation.BackendComment, aiida.orm.comments.CommentCollection]

Base class to map a DbComment that represents a comment attached to a certain Node.

Initialization

Create a Comment for a given node and user

Parameters:

node – a Node instance
user – a User instance
content – the comment content
backend – the backend to use for the instance, or use the default backend if None

Returns:

a Comment object associated to the given node and user

_CLS_COLLECTION = None#

__str__() → str#

property uuid: str#

Return the UUID for this comment.

This identifier is unique across all entities types and backend instances.

Returns:: the entity uuid

property ctime: datetime.datetime#

property mtime: datetime.datetime#

set_mtime(value: datetime.datetime) → None#

property node: aiida.orm.Node#

property user: aiida.orm.User#

set_user(value: aiida.orm.User) → None#

property content: str#

set_content(value: str) → None#

class aiida.orm.Computer(label: Optional[str] = None, hostname: str = '', description: str = '', transport_type: str = '', scheduler_type: str = '', workdir: Optional[str] = None, backend: Optional[aiida.orm.implementation.StorageBackend] = None)#

Bases: aiida.orm.entities.Entity[aiida.orm.implementation.BackendComputer, aiida.orm.computers.ComputerCollection]

Computer entity.

Initialization

Construct a new computer.

_logger = 'getLogger(...)'#

PROPERTY_MINIMUM_SCHEDULER_POLL_INTERVAL = 'minimum_scheduler_poll_interval'#

PROPERTY_MINIMUM_SCHEDULER_POLL_INTERVAL__DEFAULT = 10.0#

PROPERTY_WORKDIR = 'workdir'#

PROPERTY_SHEBANG = 'shebang'#

_CLS_COLLECTION = None#

__repr__()#

__str__()#

property uuid: str#

Return the UUID for this computer.

This identifier is unique across all entities types and backend instances.

Returns:: the entity uuid

property logger: logging.Logger#

classmethod _label_validator(label: str) → None#: Validates the label.

classmethod _hostname_validator(hostname: str) → None#: Validates the hostname.

classmethod _description_validator(description: str) → None#: Validates the description.

classmethod _transport_type_validator(transport_type: str) → None#: Validates the transport string.

classmethod _scheduler_type_validator(scheduler_type: str) → None#: Validates the transport string.

classmethod _prepend_text_validator(prepend_text: str) → None#: Validates the prepend text string.

classmethod _append_text_validator(append_text: str) → None#: Validates the append text string.

classmethod _workdir_validator(workdir: str) → None#: Validates the transport string.

_mpirun_command_validator(mpirun_cmd: Union[List[str], Tuple[str, ...]]) → None#: Validates the mpirun_command variable. MUST be called after properly checking for a valid scheduler.

validate() → None#

Check if the attributes and files retrieved from the DB are valid. Raise a ValidationError if something is wrong.

Must be able to work even before storing: therefore, use the get_attr and similar methods that automatically read either from the DB or from the internal attribute cache.

For the base class, this is always valid. Subclasses will reimplement this. In the subclass, always call the super().validate() method first!

classmethod _default_mpiprocs_per_machine_validator(def_cpus_per_machine: Optional[int]) → None#: Validates the default number of CPUs per machine (node)

classmethod default_memory_per_machine_validator(def_memory_per_machine: Optional[int]) → None#: Validates the default amount of memory (kB) per machine (node)

copy() → aiida.orm.computers.Computer#: Return a copy of the current object to work with, not stored yet.

store() → aiida.orm.computers.Computer#

Store the computer in the DB.

Differently from Nodes, a computer can be re-stored if its properties are to be changed (e.g. a new mpirun command, etc.)

property label: str#

Return the computer label.

Returns:: the label.

property description: str#

Return the computer computer.

Returns:: the description.

property hostname: str#

Return the computer hostname.

Returns:: the hostname.

property scheduler_type: str#

Return the computer scheduler type.

Returns:: the scheduler type.

property transport_type: str#

Return the computer transport type.

Returns:: the transport_type.

property metadata: Dict[str, Any]#

Return the computer metadata.

Returns:: the metadata.

delete_property(name: str, raise_exception: bool = True) → None#

Delete a property from this computer

Parameters:

name – the name of the property
raise_exception – if True raise if the property does not exist, otherwise return None

set_property(name: str, value: Any) → None#

Set a property on this computer

Parameters:

name – the property name
value – the new value

get_property(name: str, *args: Any) → Any#

Get a property of this computer

Parameters:

name – the property name
args – additional arguments

Returns:

the property value

get_prepend_text() → str#

set_prepend_text(val: str) → None#

get_append_text() → str#

set_append_text(val: str) → None#

get_use_double_quotes() → bool#

Return whether the command line parameters of this computer should be escaped with double quotes.

Returns:: True if to escape with double quotes, False otherwise which is also the default.

set_use_double_quotes(val: bool) → None#

Set whether the command line parameters of this computer should be escaped with double quotes.

Parameters:: use_double_quotes – True if to escape with double quotes, False otherwise.

get_mpirun_command() → List[str]#

Return the mpirun command. Must be a list of strings, that will be then joined with spaces when submitting.

I also provide a sensible default that may be ok in many cases.

set_mpirun_command(val: Union[List[str], Tuple[str, ...]]) → None#: Set the mpirun command. It must be a list of strings (you can use string.split() if you have a single, space-separated string).

get_default_mpiprocs_per_machine() → Optional[int]#: Return the default number of CPUs per machine (node) for this computer, or None if it was not set.

set_default_mpiprocs_per_machine(def_cpus_per_machine: Optional[int]) → None#: Set the default number of CPUs per machine (node) for this computer. Accepts None if you do not want to set this value.

get_default_memory_per_machine() → Optional[int]#: Return the default amount of memory (kB) per machine (node) for this computer, or None if it was not set.

set_default_memory_per_machine(def_memory_per_machine: Optional[int]) → None#: Set the default amount of memory (kB) per machine (node) for this computer. Accepts None if you do not want to set this value.

get_minimum_job_poll_interval() → float#

Get the minimum interval between subsequent requests to poll the scheduler for job status.

Note

If no value was ever set for this computer it will fall back on the default provided by the associated transport class in the DEFAULT_MINIMUM_JOB_POLL_INTERVAL attribute. If the computer doesn’t have a transport class, or it cannot be loaded, or it doesn’t provide a job poll interval default, then this will fall back on the PROPERTY_MINIMUM_SCHEDULER_POLL_INTERVAL__DEFAULT attribute of this class.

Returns:: The minimum interval (in seconds).

set_minimum_job_poll_interval(interval: float) → None#

Set the minimum interval between subsequent requests to update the list of jobs currently running on this computer.

Parameters:: interval – The minimum interval in seconds

get_workdir() → str#: Get the working directory for this computer :return: The currently configured working directory

set_workdir(val: str) → None#

get_shebang() → str#

set_shebang(val: str) → None#

Parameters:: val (str) – A valid shebang line

get_authinfo(user: aiida.orm.User) → aiida.orm.AuthInfo#

Return the aiida.orm.authinfo.AuthInfo instance for the given user on this computer, if the computer is configured for the given user.

Parameters:: user – a User instance.
Returns:: a AuthInfo instance
Raises:: aiida.common.NotExistent – if the computer is not configured for the given user.

property is_configured: bool#

Return whether the computer is configured for the current default user.

Returns:: Boolean, True if the computer is configured for the current default user, False otherwise.

is_user_configured(user: aiida.orm.User) → bool#

Is the user configured on this computer?

Parameters:: user – the user to check
Returns:: True if configured, False otherwise

is_user_enabled(user: aiida.orm.User) → bool#

Is the given user enabled to run on this computer?

Parameters:: user – the user to check
Returns:: True if enabled, False otherwise

get_transport(user: Optional[aiida.orm.User] = None) → aiida.transports.Transport#

Return a Transport class, configured with all correct parameters. The Transport is closed (meaning that if you want to run any operation with it, you have to open it first (i.e., e.g. for a SSH transport, you have to open a connection). To do this you can call transports.open(), or simply run within a with statement:

transport = Computer.get_transport()
with transport:
    print(transports.whoami())

Parameters:: user – if None, try to obtain a transport for the default user. Otherwise, pass a valid User.
Returns:: a (closed) Transport, already configured with the connection parameters to the supercomputer, as configured with verdi computer configure for the user specified as a parameter user.

get_transport_class() → Type[aiida.transports.Transport]#: Get the transport class for this computer. Can be used to instantiate a transport instance.

get_scheduler() → aiida.schedulers.Scheduler#: Get a scheduler instance for this computer

configure(user: Optional[aiida.orm.User] = None, **kwargs: Any) → aiida.orm.AuthInfo#

Configure a computer for a user with valid auth params passed via kwargs

Parameters:: user – the user to configure the computer for
Kwargs:: the configuration keywords with corresponding values
Returns:: the authinfo object for the configured user

get_configuration(user: Optional[aiida.orm.User] = None) → Dict[str, Any]#

Get the configuration of computer for the given user as a dictionary

Parameters:: user – the user to to get the configuration for, otherwise default user

class aiida.orm.ComputerEntityLoader#

Bases: aiida.orm.utils.loaders.OrmEntityLoader

Loader for the Computer entity and sub classes.

orm_base_class()#

Returns:: the orm base class

classmethod _get_query_builder_label_identifier(identifier, classes, operator='==', project='*')#

Return the query builder instance that attempts to map the identifier onto an entity of the orm class, defined for this loader class, interpreting the identifier as a LABEL like identifier

Parameters:

identifier – the LABEL identifier
classes – a tuple of orm classes to which the identifier should be mapped
operator – the operator to use in the query
project – the property or properties to project for entities matching the query

Returns:

the query builder instance that should retrieve the entity corresponding to the identifier

Raises:

ValueError – if the identifier is invalid
aiida.common.NotExistent – if the orm base class does not support a LABEL like identifier

class aiida.orm.ContainerizedCode(engine_command: str, image_name: str, **kwargs)#

Bases: aiida.orm.nodes.data.code.installed.InstalledCode

Data plugin representing an executable code in container on a remote computer.

Initialization

_KEY_ATTRIBUTE_ENGINE_COMMAND: str = 'engine_command'#

_KEY_ATTRIBUTE_IMAGE_NAME: str = 'image_name'#

property filepath_executable: pathlib.PurePosixPath#

Return the filepath of the executable that this code represents.

Note

This is overridden from the base class since the path does not have to be absolute.

Returns:: The filepath of the executable.

property engine_command: str#

Return the engine command with image as template field of the containerized code

Returns:: The engine command of the containerized code

property image_name: str#

The image name of container

Returns:: The image name of container.

get_prepend_cmdline_params(mpi_args: list[str] | None = None, extra_mpirun_params: list[str] | None = None) → list[str]#

Return the list of prepend cmdline params for mpi seeting

Returns:: list of prepend cmdline parameters.

classmethod _get_cli_options() → dict#: Return the CLI options that would allow to create an instance of this class.

aiida.orm.DESCENDING = 'desc'#

class aiida.orm.Data(*args, source=None, **kwargs)#

Bases: aiida.orm.nodes.node.Node

The base class for all Data nodes.

AiiDA Data classes are subclasses of Node and must support multiple inheritance.

Architecture note: Calculation plugins are responsible for converting raw output data from simulation codes to Data nodes. Nodes are responsible for validating their content (see _validate method).

Initialization

Construct a new instance, setting the source attribute if provided as a keyword argument.

_source_attributes = ['db_name', 'db_uri', 'uri', 'id', 'version', 'extras', 'source_md5', 'description', 'license']#

_export_format_replacements: Dict[str, str] = None#

_storable = True#

_unstorable_message = 'storing for this node has been disabled'#

__copy__()#: Copying a Data node is not supported, use copy.deepcopy or call Data.clone().

__deepcopy__(memo)#

Create a clone of the Data node by piping through to the clone method and return the result.

Returns:: an unstored clone of this Data node

clone()#

Create a clone of the Data node.

Returns:: an unstored clone of this Data node

property source#

Gets the dictionary describing the source of Data object. Possible fields:

db_name: name of the source database.
db_uri: URI of the source database.
uri: URI of the object’s source. Should be a permanent link.
id: object’s source identifier in the source database.
version: version of the object’s source.
extras: a dictionary with other fields for source description.
source_md5: MD5 checksum of object’s source.
description: human-readable free form description of the object’s source.
license: a string with a type of license.

Note

some limitations for setting the data source exist, see _validate method.

Returns:: dictionary describing the source of Data object.

set_source(source)#: Sets the dictionary describing the source of Data object.

property creator#

Return the creator of this node or None if it does not exist.

Returns:: the creating node or None

_exportcontent(fileformat, main_file_name='', **kwargs)#

Converts a Data node to one (or multiple) files.

Note: Export plugins should return utf8-encoded bytes, which can be directly dumped to file.

Parameters:

fileformat (str) – the extension, uniquely specifying the file format.
main_file_name (str) – (empty by default) Can be used by plugin to infer sensible names for additional files, if necessary. E.g. if the main file is ‘../myplot.gnu’, the plugin may decide to store the dat file under ‘../myplot_data.dat’.
kwargs – other parameters are passed down to the plugin

Returns:

a tuple of length 2. The first element is the content of the otuput file. The second is a dictionary (possibly empty) in the format {filename: filecontent} for any additional file that should be produced.

Return type:

(bytes, dict)

export(path, fileformat=None, overwrite=False, **kwargs)#

Save a Data object to a file.

Parameters:

fname – string with file name. Can be an absolute or relative path.
fileformat – kind of format to use for the export. If not present, it will try to use the extension of the file name.
overwrite – if set to True, overwrites file found at path. Default=False
kwargs – additional parameters to be passed to the _exportcontent method

Returns:

the list of files created

_get_exporters()#: Get all implemented export formats. The convention is to find all _prepare_… methods. Returns a dictionary of method_name: method_function

classmethod get_export_formats()#

Get the list of valid export format strings

Returns:: a list of valid formats

importstring(inputstring, fileformat, **kwargs)#

Converts a Data object to other text format.

Parameters:: fileformat – a string (the extension) to describe the file format.
Returns:: a string with the structure description.

importfile(fname, fileformat=None)#

Populate a Data object from a file.

Parameters:

fname – string with file name. Can be an absolute or relative path.
fileformat – kind of format to use for the export. If not present, it will try to use the extension of the file name.

_get_importers()#: Get all implemented import formats. The convention is to find all _parse_… methods. Returns a list of strings.

convert(object_format=None, *args)#

Convert the AiiDA StructureData into another python object

Parameters:: object_format – Specify the output format

_get_converters()#: Get all implemented converter formats. The convention is to find all _get_object_… methods. Returns a list of strings.

class aiida.orm.Dict(value=None, **kwargs)#

Bases: aiida.orm.nodes.data.data.Data

Data sub class to represent a dictionary.

The dictionary contents of a Dict node are stored in the database as attributes. The dictionary can be initialized through the dict argument in the constructor. After construction, values can be retrieved and updated through the item getters and setters, respectively:

node[‘key’] = ‘value’

Alternatively, the dict property returns an instance of the AttributeManager that can be used to get and set values through attribute notation:

node.dict.key = ‘value’

Note that trying to set dictionary values directly on the node, e.g. node.key = value, will not work as intended. It will merely set the key attribute on the node instance, but will not be stored in the database. As soon as the node goes out of scope, the value will be lost.

It is also relevant to note here the difference in something being an “attribute of a node” (in the sense that it is stored in the “attribute” column of the database when the node is stored) and something being an “attribute of a python object” (in the sense of being able to modify and access it as if it was a property of the variable, e.g. node.key = value). This is true of all types of nodes, but it becomes more relevant for Dict nodes where one is constantly manipulating these attributes.

Finally, all dictionary mutations will be forbidden once the node is stored.

Initialization

Initialise a Dict node instance.

Usual rules for attribute names apply, in particular, keys cannot start with an underscore, or a ValueError will be raised.

Initial attributes can be changed, deleted or added as long as the node is not stored.

Parameters:: value – dictionary to initialise the Dict node from

__getitem__(key)#

__setitem__(key, value)#

__eq__(other)#

__contains__(key: str) → bool#: Return whether the node contains a key.

set_dict(dictionary)#

Replace the current dictionary with another one.

Parameters:: dictionary – dictionary to set

update_dict(dictionary)#

Update the current dictionary with the keys provided in the dictionary.

Note

works exactly as dict.update() where new keys are simply added and existing keys are overwritten.

Parameters:: dictionary – a dictionary with the keys to substitute

get_dict()#

Return a dictionary with the parameters currently set.

Returns:: dictionary

keys()#

Iterator of valid keys stored in the Dict object.

Returns:: iterator over the keys of the current dictionary

items()#: Iterator of all items stored in the Dict node.

property dict#

Return an instance of AttributeManager that transforms the dictionary into an attribute dict.

Note

this will allow one to do node.dict.key as well as node.dict[key].

Returns:: an instance of the AttributeResultManager.

class aiida.orm.Entity(backend_entity: aiida.orm.entities.BackendEntityType)#

Bases: abc.ABC, typing.Generic[aiida.orm.entities.BackendEntityType, aiida.orm.entities.CollectionType]

An AiiDA entity

Initialization

Parameters:: backend_entity – the backend model supporting this entity

_CLS_COLLECTION: Type[aiida.orm.entities.CollectionType] = None#

objects() → aiida.orm.entities.CollectionType#

Get a collection for objects of this type, with the default backend.

Deprecated since version This: will be removed in v3, use collection instead.

Returns:: an object that can be used to access entities of this type

collection() → aiida.orm.entities.CollectionType#

Get a collection for objects of this type, with the default backend.

Returns:: an object that can be used to access entities of this type

classmethod get(**kwargs)#: Get an entity of the collection matching the given filters.

classmethod from_backend_entity(backend_entity: aiida.orm.entities.BackendEntityType) → aiida.orm.entities.EntityType#

Construct an entity from a backend entity instance

Parameters:: backend_entity – the backend entity
Returns:: an AiiDA entity instance

__getstate__()#: Prevent an ORM entity instance from being pickled.

initialize() → None#

Initialize instance attributes.

This will be called after the constructor is called or an entity is created from an existing backend entity.

property id: int#

Return the id for this entity.

This identifier is guaranteed to be unique amongst entities of the same type for a single backend instance.

Returns:: the entity’s id

property pk: int#

Return the primary key for this entity.

This identifier is guaranteed to be unique amongst entities of the same type for a single backend instance.

Returns:: the entity’s principal key

store() → aiida.orm.entities.EntityType#: Store the entity.

property is_stored: bool#: Return whether the entity is stored.

property backend: aiida.orm.implementation.StorageBackend#: Get the backend for this entity

property backend_entity: aiida.orm.entities.BackendEntityType#: Get the implementing class for this object

class aiida.orm.EntityExtras(entity: Union[aiida.orm.nodes.node.Node, aiida.orm.groups.Group])#

Interface to the extras of a node or group instance.

Extras are a JSONable dictionary, stored on each entity, allowing for arbitrary data to be stored by users.

Extras are mutable, even after storing the entity, and as such are not deemed a core part of the provenance graph.

Initialization

Initialize the interface.

__contains__(key: str) → bool#: Check if the extras contain the given key.

property all: Dict[str, Any]#

Return the complete extras dictionary.

Warning

While the entity is unstored, this will return references of the extras on the database model, meaning that changes on the returned values (if they are mutable themselves, e.g. a list or dictionary) will automatically be reflected on the database model as well. As soon as the entity is stored, the returned extras will be a deep copy and mutations of the database extras will have to go through the appropriate set methods. Therefore, once stored, retrieving a deep copy can be a heavy operation. If you only need the keys or some values, use the iterators extras_keys and extras_items, or the getters get_extra and get_extra_many instead.

Returns:: the extras as a dictionary

get(key: str, default: Any = _NO_DEFAULT) → Any#

Return the value of an extra.

Warning

While the entity is unstored, this will return a reference of the extra on the database model, meaning that changes on the returned value (if they are mutable themselves, e.g. a list or dictionary) will automatically be reflected on the database model as well. As soon as the entity is stored, the returned extra will be a deep copy and mutations of the database extras will have to go through the appropriate set methods.

Parameters:

key – name of the extra
default – return this value instead of raising if the attribute does not exist

Returns:

the value of the extra

Raises:

AttributeError – if the extra does not exist and no default is specified

get_many(keys: List[str]) → List[Any]#

Return the values of multiple extras.

Warning

Parameters:: keys – a list of extra names
Returns:: a list of extra values
Raises:: AttributeError – if at least one extra does not exist

set(key: str, value: Any) → None#

Set an extra to the given value.

Parameters:

key – name of the extra
value – value of the extra

Raises:

aiida.common.ValidationError – if the key is invalid, i.e. contains periods

set_many(extras: Dict[str, Any]) → None#

Set multiple extras.

Note

This will override any existing extras that are present in the new dictionary.

Parameters:: extras – a dictionary with the extras to set
Raises:: aiida.common.ValidationError – if any of the keys are invalid, i.e. contain periods

reset(extras: Dict[str, Any]) → None#

Reset the extras.

Note

This will completely clear any existing extras and replace them with the new dictionary.

Parameters:: extras – a dictionary with the extras to set
Raises:: aiida.common.ValidationError – if any of the keys are invalid, i.e. contain periods

delete(key: str) → None#

Delete an extra.

Parameters:: key – name of the extra
Raises:: AttributeError – if the extra does not exist

delete_many(keys: List[str]) → None#

Delete multiple extras.

Parameters:: keys – names of the extras to delete
Raises:: AttributeError – if at least one of the extra does not exist

clear() → None#: Delete all extras.

items() → Iterable[Tuple[str, Any]]#

Return an iterator over the extras.

Returns:: an iterator with extra key value pairs

keys() → Iterable[str]#

Return an iterator over the extra keys.

Returns:: an iterator with extra keys

class aiida.orm.EntityTypes#

Bases: enum.Enum

Enum for referring to ORM entities in a backend-agnostic manner.

AUTHINFO = 'authinfo'#

COMMENT = 'comment'#

COMPUTER = 'computer'#

GROUP = 'group'#

LOG = 'log'#

NODE = 'node'#

USER = 'user'#

LINK = 'link'#

GROUP_NODE = 'group_node'#

class aiida.orm.EnumData(member: enum.Enum, *args, **kwargs)#

Bases: aiida.orm.nodes.data.data.Data

Data plugin that allows to easily wrap an enum.Enum member.

The enum member is stored in the database by storing the value, name and the identifier (string that represents the class of the enumeration) in the KEY_NAME, KEY_VALUE and KEY_IDENTIFIER attribute, respectively. The original enum member can be reconstructured from the (loaded) node through the get_member method. The enum itself can be retrieved from the get_enum method. Like a normal enum member, the EnumData plugin provides the name and value properties which return the name and value of the enum member, respectively.

Initialization

Construct the node for the to enum member that is to be wrapped.

KEY_NAME = 'name'#

KEY_VALUE = 'value'#

KEY_IDENTIFIER = 'identifier'#

property name: str#: Return the name of the enum member.

property value: Any#: Return the value of the enum member.

get_enum() → Type[aiida.orm.nodes.data.enum.EnumType]#

Return the enum class reconstructed from the serialized identifier stored in the database.

Raises:: ImportError – if the enum class represented by the stored identifier cannot be imported.

get_member() → aiida.orm.nodes.data.enum.EnumType#

Return the enum member reconstructed from the serialized data stored in the database.

For the enum member to be successfully reconstructed, the class of course has to still be importable and its implementation should not have changed since the node was stored. That is to say, the value of the member when it was stored, should still be a valid value for the enum class now.

Raises:

ImportError – if the enum class represented by the stored identifier cannot be imported.
ValueError – if the stored enum member value is no longer valid for the imported enum class.

__eq__(other: Any) → bool#: Return whether the other object is equivalent to ourselves.

class aiida.orm.Float#

Bases: aiida.orm.nodes.data.numeric.NumericType

Data sub class to represent a float value.

_type = None#

class aiida.orm.FolderData(**kwargs)#

Bases: aiida.orm.nodes.data.data.Data

Data sub class to represent a folder on a file system.

Initialization

Construct a new FolderData to which any files and folders can be added.

Use the tree keyword to simply wrap a directory:

folder = FolderData(tree=’/absolute/path/to/directory’)

Alternatively, one can construct the node first and then use the various repository methods to add objects:

folder = FolderData() folder.put_object_from_tree(‘/absolute/path/to/directory’) folder.put_object_from_filepath(‘/absolute/path/to/file.txt’) folder.put_object_from_filelike(filelike_object)

Parameters:: tree (str) – absolute path to a folder to wrap

class aiida.orm.Group(label: Optional[str] = None, user: Optional[aiida.orm.User] = None, description: str = '', type_string: Optional[str] = None, backend: Optional[aiida.orm.implementation.StorageBackend] = None)#

Bases: aiida.orm.entities.Entity[aiida.orm.implementation.BackendGroup, aiida.orm.groups.GroupCollection]

An AiiDA ORM implementation of group of nodes.

Initialization

Create a new group. Either pass a dbgroup parameter, to reload a group from the DB (and then, no further parameters are allowed), or pass the parameters for the Group creation.

Parameters:

label – The group label, required on creation
description – The group description (by default, an empty string)
user – The owner of the group (by default, the automatic user)
type_string – a string identifying the type of group (by default, an empty string, indicating an user-defined group.

_type_string: ClassVar[Optional[str]] = None#

_CLS_COLLECTION = None#

base() → aiida.orm.groups.GroupBase#: Return the group base namespace.

__repr__() → str#

__str__() → str#

store() → aiida.orm.groups.SelfType#: Verify that the group is allowed to be stored, which is the case along as type_string is set.

entry_point() → Optional[aiida.plugins.entry_point.EntryPoint]#

Return the entry point associated this group type.

Returns:: the associated entry point or None if it isn’t known.

property uuid: str#

Return the UUID for this group.

This identifier is unique across all entities types and backend instances.

Returns:: the entity uuid

property label: str#

Returns:: the label of the group as a string

property description: str#

Returns:: the description of the group as a string

property type_string: str#

Returns:: the string defining the type of the group

property user: aiida.orm.User#

Returns:: the user associated with this group

count() → int#

Return the number of entities in this group.

Returns:: integer number of entities contained within the group

property nodes: aiida.orm.convert.ConvertIterator#: Return a generator/iterator that iterates over all nodes and returns the respective AiiDA subclasses of Node, and also allows to ask for the number of nodes in the group using len().

property is_empty: bool#

Return whether the group is empty, i.e. it does not contain any nodes.

Returns:: True if it contains no nodes, False otherwise

clear() → None#: Remove all the nodes from this group.

add_nodes(nodes: Union[aiida.orm.nodes.Node, Sequence[aiida.orm.nodes.Node]]) → None#

Add a node or a set of nodes to the group.

Note:: all the nodes and the group itself have to be stored.
Parameters:: nodes – a single Node or a list of Nodes

remove_nodes(nodes: Union[aiida.orm.nodes.Node, Sequence[aiida.orm.nodes.Node]]) → None#

Remove a node or a set of nodes to the group.

Note:: all the nodes and the group itself have to be stored.
Parameters:: nodes – a single Node or a list of Nodes

is_user_defined() → bool#

Returns:: True if the group is user defined, False otherwise

_deprecated_extra_methods = None#

__getattr__(name: str) → Any#

This method is called when an extras is not found in the instance.

It allows for the handling of deprecated mixin methods.

class aiida.orm.GroupEntityLoader#

Bases: aiida.orm.utils.loaders.OrmEntityLoader

Loader for the Group entity and sub classes.

orm_base_class()#

Returns:: the orm base class

classmethod _get_query_builder_label_identifier(identifier, classes, operator='==', project='*')#

Return the query builder instance that attempts to map the identifier onto an entity of the orm class, defined for this loader class, interpreting the identifier as a LABEL like identifier

Parameters:

identifier – the LABEL identifier
classes – a tuple of orm classes to which the identifier should be mapped
operator – the operator to use in the query
project – the property or properties to project for entities matching the query

Returns:

the query builder instance that should retrieve the entity corresponding to the identifier

Raises:

ValueError – if the identifier is invalid
aiida.common.NotExistent – if the orm base class does not support a LABEL like identifier

class aiida.orm.ImportGroup(label: Optional[str] = None, user: Optional[aiida.orm.User] = None, description: str = '', type_string: Optional[str] = None, backend: Optional[aiida.orm.implementation.StorageBackend] = None)#

Bases: aiida.orm.groups.Group

Group to be used to contain all nodes from an export archive that has been imported.

Initialization

Create a new group. Either pass a dbgroup parameter, to reload a group from the DB (and then, no further parameters are allowed), or pass the parameters for the Group creation.

Parameters:

label – The group label, required on creation
description – The group description (by default, an empty string)
user – The owner of the group (by default, the automatic user)
type_string – a string identifying the type of group (by default, an empty string, indicating an user-defined group.

class aiida.orm.InstalledCode(computer: aiida.orm.Computer, filepath_executable: str, **kwargs)#

Bases: aiida.orm.nodes.data.code.legacy.Code

Data plugin representing an executable code on a remote computer.

Initialization

Construct a new instance.

Parameters:

computer – The remote computer on which the executable is located.
filepath_executable – The absolute filepath of the executable on the remote computer.

_KEY_ATTRIBUTE_FILEPATH_EXECUTABLE: str = 'filepath_executable'#

_validate()#

Validate the instance by checking that a computer has been defined.

:raises aiida.common.exceptions.ValidationError: If the state of the node is invalid.

validate_filepath_executable()#

Validate the filepath_executable attribute.

Raises:: ValidationError – if no transport could be opened or if the defined executable does not exist on the remote computer.

can_run_on_computer(computer: aiida.orm.Computer) → bool#

Return whether the code can run on a given computer.

Parameters:: computer – The computer.
Returns:: True if the provided computer is the same as the one configured for this code.

get_executable() → pathlib.PurePosixPath#

Return the executable that the submission script should execute to run the code.

Returns:: The executable to be called in the submission script.

property computer: aiida.orm.Computer#: Return the computer of this code.

property full_label: str#

Return the full label of this code.

The full label can be just the label itself but it can be something else. However, it at the very least has to include the label of the code.

Returns:: The full label of the code.

property filepath_executable: pathlib.PurePosixPath#

Return the absolute filepath of the executable that this code represents.

Returns:: The absolute filepath of the executable.

static cli_validate_label_uniqueness(ctx, _, value)#: Validate the uniqueness of the label of the code.

classmethod _get_cli_options() → dict#: Return the CLI options that would allow to create an instance of this class.

class aiida.orm.Int#

Bases: aiida.orm.nodes.data.numeric.NumericType

Data sub class to represent an integer value.

_type = None#

class aiida.orm.JsonableData(obj: aiida.orm.nodes.data.jsonable.JsonSerializableProtocol, *args, **kwargs)#

Bases: aiida.orm.nodes.data.data.Data

Data plugin that allows to easily wrap objects that are JSON-able.

Any class that implements the as_dict method, returning a dictionary that is a JSON serializable representation of the object, can be wrapped and stored by this data plugin.

As an example, take the Molecule class of the pymatgen library, which respects the spec described above. To store an instance as a JsonableData simply pass an instance as an argument to the constructor as follows:

from pymatgen.core import Molecule
molecule = Molecule(['H']. [0, 0, 0])
node = JsonableData(molecule)
node.store()

Since Molecule.as_dict returns a dictionary that is JSON-serializable, the data plugin will call it and store the dictionary as the attributes of the JsonableData node in the database.

Note

A JSON-serializable dictionary means a dictionary that when passed to json.dumps does not except but produces a valid JSON string representation of the dictionary.

If the wrapped class implements a class-method from_dict, the wrapped instance can easily be recovered from a previously stored node that was optionally loaded from the database. The from_dict method should simply accept a single argument which is the dictionary that is returned by the as_dict method. If this criteria is satisfied, an instance wrapped and stored in a JsonableData node can be recovered through the obj property:

loaded = load_node(node.pk)
molecule = loaded.obj

Of course, this requires that the class of the originally wrapped instance can be imported in the current environment, or an ImportError will be raised.

Initialization

Construct the node for the to be wrapped object.

classmethod _deserialize_float_constants(data: Any)#

Deserialize the contents of a dictionary data deserializing infinity and NaN string constants.

The data dictionary is recursively checked for the Infinity, -Infinity and NaN strings, which are the Javascript string equivalents to the Python float('inf'), -float('inf') and float('nan') float constants. If one of the strings is encountered, the Python float constant is returned and otherwise the original value is returned.

_get_object() → aiida.orm.nodes.data.jsonable.JsonSerializableProtocol#: Return the cached wrapped object.

Note

If the object is not yet present in memory, for example if the node was loaded from the database, the object will first be reconstructed from the state stored in the node attributes.

property obj: aiida.orm.nodes.data.jsonable.JsonSerializableProtocol#: Return the wrapped object.

Note

This property caches the deserialized object, this means that when the node is loaded from the database, the object is deserialized only once and stored in memory as an attribute. Subsequent calls will simply return this cached object and not reload it from the database. This is fine, since nodes that are loaded from the database are by definition stored and therefore immutable, making it safe to assume that the object that is represented can not change. Note, however, that the caching also applies to unstored nodes. That means that manually changing the attributes of an unstored JsonableData can lead to inconsistencies with the object returned by this property.

class aiida.orm.Kind(**kwargs)#

This class contains the information about the species (kinds) of the system.

It can be a single atom, or an alloy, or even contain vacancies.

Initialization

Create a site. One can either pass:

Parameters:

raw – the raw python dictionary that will be converted to a Kind object.
ase – an ase Atom object
kind – a Kind object (to get a copy)

Or alternatively the following parameters:

Parameters:

symbols – a single string for the symbol of this site, or a list of symbol strings
weights – (optional) the weights for each atomic species of this site. If only a single symbol is provided, then this value is optional and the weight is set to 1.
mass – (optional) the mass for this site in atomic mass units. If not provided, the mass is set by the self.reset_mass() function.
name – a string that uniquely identifies the kind, and that is used to identify the sites.

get_raw()#

Return the raw version of the site, mapped to a suitable dictionary. This is the format that is actually used to store each kind of the structure in the DB.

Returns:: a python dictionary with the kind.

reset_mass()#

Reset the mass to the automatic calculated value.

The mass can be set manually; by default, if not provided, it is the mass of the constituent atoms, weighted with their weight (after the weight has been normalized to one to take correctly into account vacancies).

This function uses the internal _symbols and _weights values and thus assumes that the values are validated.

It sets the mass to None if the sum of weights is zero.

property name#

Return the name of this kind. The name of a kind is used to identify the species of a site.

Returns:: a string

set_automatic_kind_name(tag=None)#: Set the type to a string obtained with the symbols appended one after the other, without spaces, in alphabetical order; if the site has a vacancy, a X is appended at the end too.

compare_with(other_kind)#

Compare with another Kind object to check if they are different.

Note

This does NOT check the ‘type’ attribute. Instead, it compares (with reasonable thresholds, where applicable): the mass, and the list of symbols and of weights. Moreover, it compares the _internal_tag, if defined (at the moment, defined automatically only when importing the Kind from ASE, if the atom has a non-zero tag). Note that the _internal_tag is only used while the class is loaded, but is not persisted on the database.

Returns:: A tuple with two elements. The first one is True if the two sites are ‘equivalent’ (same mass, symbols and weights), False otherwise. The second element of the tuple is a string, which is either None (if the first element was True), or contains a ‘human-readable’ description of the first difference encountered between the two sites.

property mass#

The mass of this species kind.

Returns:: a float

property weights#: Weights for this species kind. Refer also to :func:validate_symbols_tuple for the validation rules on the weights.

get_symbols_string()#: Return a string that tries to match as good as possible the symbols of this kind. If there is only one symbol (no alloy) with 100% occupancy, just returns the symbol name. Otherwise, groups the full string in curly brackets, and try to write also the composition (with 2 precision only).

Note

If there is a vacancy (sum of weights<1), we indicate it with the X symbol followed by 1-sum(weights) (still with 2 digits precision, so it can be 0.00)

Note

Note the difference with respect to the symbols and the symbol properties!

property symbol#: If the kind has only one symbol, return it; otherwise, raise a ValueError.

property symbols#: List of symbols for this site. If the site is a single atom, pass a list of one element only, or simply the string for that atom. For alloys, a list of elements.

Note

Note that if you change the list of symbols, the kind name remains unchanged.

set_symbols_and_weights(symbols, weights)#: Set the chemical symbols and the weights for the site.

Note

Note that the kind name remains unchanged.

property is_alloy#

Return whether the Kind is an alloy, i.e. contains more than one element

Returns:: boolean, True if the kind has more than one element, False otherwise.

property has_vacancies#

Return whether the Kind contains vacancies, i.e. when the sum of the weights is less than one.

Note

the property uses the internal variable _SUM_THRESHOLD as a threshold.

Returns:: boolean, True if the sum of the weights is less than one, False otherwise

__repr__()#

__str__()#

class aiida.orm.KpointsData(*args, source=None, **kwargs)#

Bases: aiida.orm.nodes.data.array.array.ArrayData

Class to handle array of kpoints in the Brillouin zone. Provide methods to generate either user-defined k-points or path of k-points along symmetry lines. Internally, all k-points are defined in terms of crystal (fractional) coordinates. Cell and lattice vector coordinates are in Angstroms, reciprocal lattice vectors in Angstrom^-1 . :note: The methods setting and using the Bravais lattice info assume the PRIMITIVE unit cell is provided in input to the set_cell or set_cell_from_structure methods.

Initialization

Construct a new instance, setting the source attribute if provided as a keyword argument.

get_description()#: Returns a string with infos retrieved from kpoints node’s properties. :param node: :return: retstr

property cell#: The crystal unit cell. Rows are the crystal vectors in Angstroms. :return: a 3x3 numpy.array

_set_cell(value)#: Validate if ‘value’ is a allowed crystal unit cell :param value: something compatible with a 3x3 tuple of floats

property pbc#

The periodic boundary conditions along the vectors a1,a2,a3.

Returns:: a tuple of three booleans, each one tells if there are periodic boundary conditions for the i-th real-space direction (i=1,2,3)

_set_pbc(value)#: validate the pbc, then store them

property labels#: Labels associated with the list of kpoints. List of tuples with kpoint index and kpoint name: [(0,'G'),(13,'M'),...]

_set_labels(value)#: set label names. Must pass in input a list like: [[0,'X'],[34,'L'],... ]

_change_reference(kpoints, to_cartesian=True)#: Change reference system, from cartesian to crystal coordinates (units of b1,b2,b3) or viceversa. :param kpoints: a list of (3) point coordinates :return kpoints: a list of (3) point coordinates in the new reference

set_cell_from_structure(structuredata)#

Set a cell to be used for symmetry analysis from an AiiDA structure. Inherits both the cell and the pbc’s. To set manually a cell, use “set_cell”

Parameters:: structuredata – an instance of StructureData

set_cell(cell, pbc=None)#

Set a cell to be used for symmetry analysis. To set a cell from an AiiDA structure, use “set_cell_from_structure”.

Parameters:

cell – 3x3 matrix of cell vectors. Orientation: each row represent a lattice vector. Units are Angstroms.
pbc – list of 3 booleans, True if in the nth crystal direction the structure is periodic. Default = [True,True,True]

property reciprocal_cell#

Compute reciprocal cell from the internally set cell.

Returns:: reciprocal cell in units of 1/Angstrom with cell vectors stored as rows. Use e.g. reciprocal_cell[0] to access the first reciprocal cell vector.

set_kpoints_mesh(mesh, offset=None)#

Set KpointsData to represent a uniformily spaced mesh of kpoints in the Brillouin zone. This excludes the possibility of set/get kpoints

Parameters:

mesh – a list of three integers, representing the size of the kpoint mesh along b1,b2,b3.
offset – (optional) a list of three floats between 0 and 1. [0.,0.,0.] is Gamma centered mesh [0.5,0.5,0.5] is half shifted [1.,1.,1.] by periodicity should be equivalent to [0.,0.,0.] Default = [0.,0.,0.].

get_kpoints_mesh(print_list=False)#

Get the mesh of kpoints.

Parameters:: print_list – default=False. If True, prints the mesh of kpoints as a list
Raises:: AttributeError – if no mesh has been set
Return mesh,offset:: (if print_list=False) a list of 3 integers and a list of three floats 0<x<1, representing the mesh and the offset of kpoints
Return kpoints:: (if print_list = True) an explicit list of kpoints coordinates, similar to what returned by get_kpoints()

set_kpoints_mesh_from_density(distance, offset=None, force_parity=False)#

Set a kpoints mesh using a kpoints density, expressed as the maximum distance between adjacent points along a reciprocal axis

Parameters:

distance – distance (in 1/Angstrom) between adjacent kpoints, i.e. the number of kpoints along each reciprocal axis i is \(|b_i|/distance\) where \(|b_i|\) is the norm of the reciprocal cell vector.
offset – (optional) a list of three floats between 0 and 1. [0.,0.,0.] is Gamma centered mesh [0.5,0.5,0.5] is half shifted Default = [0.,0.,0.].
force_parity – (optional) if True, force each integer in the mesh to be even (except for the non-periodic directions).

Note:

a cell should be defined first.

Note:

the number of kpoints along non-periodic axes is always 1.

property _dimension#: Dimensionality of the structure, found from its pbc (i.e. 1 if it’s a 1D structure, 2 if its 2D, 3 if it’s 3D …). :return dimensionality: 0, 1, 2 or 3 :note: will return 3 if pbc has not been set beforehand

_validate_kpoints_weights(kpoints, weights)#: Validate the list of kpoints and of weights before storage. Kpoints and weights must be convertible respectively to an array of N x dimension and N floats

set_kpoints(kpoints, cartesian=False, labels=None, weights=None, fill_values=0)#

Set the list of kpoints. If a mesh has already been stored, raise a ModificationNotAllowed

Parameters:

kpoints –
a list of kpoints, each kpoint being a list of one, two or three coordinates, depending on self.pbc: if structure is 1D (only one True in self.pbc) one allows singletons or scalars for each k-point, if it’s 2D it can be a length-2 list, and in all cases it can be a length-3 list. Examples:
- [[0.,0.,0.],[0.1,0.1,0.1],…] for 1D, 2D or 3D
- [[0.,0.],[0.1,0.1,],…] for 1D or 2D
- [[0.],[0.1],…] for 1D
- [0., 0.1, …] for 1D (list of scalars)
For 0D (all pbc are False), the list can be any of the above or empty - then only Gamma point is set. The value of k for the non-periodic dimension(s) is set by fill_values
cartesian – if True, the coordinates given in input are treated as in cartesian units. If False, the coordinates are crystal, i.e. in units of b1,b2,b3. Default = False
labels – optional, the list of labels to be set for some of the kpoints. See labels for more info
weights – optional, a list of floats with the weight associated to the kpoint list
fill_values – scalar to be set to all non-periodic dimensions (indicated by False in self.pbc), or list of values for each of the non-periodic dimensions.

get_kpoints(also_weights=False, cartesian=False)#

Return the list of kpoints

Parameters:

also_weights – if True, returns also the list of weights. Default = False
cartesian – if True, returns points in cartesian coordinates, otherwise, returns in crystal coordinates. Default = False.

class aiida.orm.LinkManager(link_triples: List[aiida.orm.utils.links.LinkTriple])#

Class to convert a list of LinkTriple tuples into an iterator.

It defines convenience methods to retrieve certain subsets of LinkTriple while checking for consistency. For example:

LinkManager.one(): returns the only entry in the list or it raises an exception
LinkManager.first(): returns the first entry from the list
LinkManager.all(): returns all entries from list

The methods all_nodes and all_link_labels are syntactic sugar wrappers around all to get a list of only the incoming nodes or link labels, respectively.

Initialization

Initialise the collection.

__iter__() → Iterator[aiida.orm.utils.links.LinkTriple]#

Return an iterator of LinkTriple instances.

Returns:: iterator of LinkTriple instances

__next__() → Generator[aiida.orm.utils.links.LinkTriple, None, None]#

Return the next element in the iterator.

Returns:: LinkTriple

__bool__()#

next() → Generator[aiida.orm.utils.links.LinkTriple, None, None]#

Return the next element in the iterator.

Returns:: LinkTriple

one() → aiida.orm.utils.links.LinkTriple#

Return a single entry from the iterator.

If the iterator contains no or more than one entry, an exception will be raised :return: LinkTriple instance :raises ValueError: if the iterator contains anything but one entry

first() → Optional[aiida.orm.utils.links.LinkTriple]#

Return the first entry from the iterator.

Returns:: LinkTriple instance or None if no entries were matched

all() → List[aiida.orm.utils.links.LinkTriple]#

Return all entries from the list.

Returns:: list of LinkTriple instances

all_nodes() → List[aiida.orm.Node]#

Return a list of all nodes.

Returns:: list of nodes

all_link_pairs() → List[aiida.orm.utils.links.LinkPair]#

Return a list of all link pairs.

Returns:: list of LinkPair instances

all_link_labels() → List[str]#

Return a list of all link labels.

Returns:: list of link labels

get_node_by_label(label: str) → aiida.orm.Node#

Return the node from list for given label.

Returns:: node that corresponds to the given label
Raises:: aiida.common.NotExistent – if the label is not present among the link_triples

nested(sort=True)#

Construct (nested) dictionary of matched nodes that mirrors the original nesting of link namespaces.

Process input and output namespaces can be nested, however the link labels that represent them in the database have a flat hierarchy, and so the link labels are flattened representations of the nested namespaces. This function reconstructs the original node nesting based on the flattened links.

Returns:: dictionary of nested namespaces
Raises:: KeyError – if there are duplicate link labels in a namespace

class aiida.orm.LinkPair#

Bases: typing.NamedTuple

link_type: aiida.common.links.LinkType = None#

link_label: str = None#

class aiida.orm.LinkTriple#

Bases: typing.NamedTuple

node: aiida.orm.Node = None#

link_type: aiida.common.links.LinkType = None#

link_label: str = None#

class aiida.orm.List(value=None, **kwargs)#

Bases: aiida.orm.nodes.data.data.Data, collections.abc.MutableSequence

Data sub class to represent a list.

Initialization

Initialise a List node instance.

Parameters:: value – list to initialise the List node from

_LIST_KEY = 'list'#

__getitem__(item)#

__setitem__(key, value)#

__delitem__(key)#

__len__()#

__str__()#

__eq__(other)#

append(value)#

extend(value)#

insert(i, value)#

remove(value)#

pop(**kwargs)#: Remove and return item at index (default last).

index(value)#: Return first index of value..

count(value)#: Return number of occurrences of value.

sort(key=None, reverse=False)#

reverse()#

get_list()#

Return the contents of this node.

Returns:: a list

set_list(data)#

Set the contents of this node.

Parameters:: data – the list to set

_using_list_reference()#

This function tells the class if we are using a list reference. This means that calls to self.get_list return a reference rather than a copy of the underlying list and therefore self.set_list need not be called. This knwoledge is essential to make sure this class is performant.

Currently the implementation assumes that if the node needs to be stored then it is using the attributes cache which is a reference.

Returns:: True if using self.get_list returns a reference to the underlying sequence. False otherwise.
Return type:: bool

class aiida.orm.Log(time: datetime.datetime, loggername: str, levelname: str, dbnode_id: int, message: str = '', metadata: Optional[Dict[str, Any]] = None, backend: Optional[aiida.orm.implementation.StorageBackend] = None)#

Bases: aiida.orm.entities.Entity[aiida.orm.implementation.BackendLog, aiida.orm.logs.LogCollection]

An AiiDA Log entity. Corresponds to a logged message against a particular AiiDA node.

Initialization

Construct a new log

Parameters:

time – time
loggername – name of logger
levelname – name of log level
dbnode_id – id of database node
message – log message
metadata – metadata
backend – database backend

_CLS_COLLECTION = None#

property uuid: str#

Return the UUID for this log.

This identifier is unique across all entities types and backend instances.

Returns:: the entity uuid

property time: datetime.datetime#

Get the time corresponding to the entry

Returns:: The entry timestamp

property loggername: str#

The name of the logger that created this entry

Returns:: The entry loggername

property levelname: str#

The name of the log level

Returns:: The entry log level name

property dbnode_id: int#

Get the id of the object that created the log entry

Returns:: The id of the object that created the log entry

property message: str#

Get the message corresponding to the entry

Returns:: The entry message

property metadata: Dict[str, Any]#

Get the metadata corresponding to the entry

Returns:: The entry metadata

class aiida.orm.Node(backend: Optional[aiida.orm.implementation.StorageBackend] = None, user: Optional[aiida.orm.users.User] = None, computer: Optional[aiida.orm.computers.Computer] = None, **kwargs: Any)#

Bases: aiida.orm.entities.Entity[aiida.orm.implementation.BackendNode, aiida.orm.nodes.node.NodeCollection]

Base class for all nodes in AiiDA.

Stores attributes starting with an underscore.

Caches files and attributes before the first save, and saves everything only on store(). After the call to store(), attributes cannot be changed.

Only after storing (or upon loading from uuid) extras can be modified and in this case they are directly set on the db.

In the plugin, also set the _plugin_type_string, to be set in the DB in the ‘type’ field.

Initialization

Parameters:: backend_entity – the backend model supporting this entity

_CLS_COLLECTION = None#

_CLS_NODE_LINKS = None#

_CLS_NODE_CACHING = None#

_plugin_type_string: ClassVar[str] = None#

_query_type_string: ClassVar[str] = None#

_logger: Optional[logging.Logger] = None#

_updatable_attributes: Tuple[str, ...] = 'tuple(...)'#

_hash_ignored_attributes: Tuple[str, ...] = 'tuple(...)'#

_cachable = False#

_storable = False#

_unstorable_message = 'only Data, WorkflowNode, CalculationNode or their subclasses can be stored'#

base() → aiida.orm.nodes.node.NodeBase#: Return the node base namespace.

_check_mutability_attributes(keys: Optional[List[str]] = None) → None#

Check if the entity is mutable and raise an exception if not.

This is called from NodeAttributes methods that modify the attributes.

Parameters:: keys – the keys that will be mutated, or all if None

__eq__(other: Any) → bool#: Fallback equality comparison by uuid (can be overwritten by specific types)

__hash__() → int#: Python-Hash: Implementation that is compatible with __eq__

__repr__() → str#

__str__() → str#

__copy__()#: Copying a Node is not supported in general, but only for the Data sub class.

__deepcopy__(memo)#: Deep copying a Node is not supported in general, but only for the Data sub class.

_validate() → bool#

Validate information stored in Node object.

For the Node base class, this check is always valid. Subclasses can override this method to perform additional checks and should usually call super()._validate() first!

This method is called automatically before storing the node in the DB. Therefore, use get() and similar methods that automatically read either from the DB or from the internal attribute cache.

_validate_storability() → None#

Verify that the current node is allowed to be stored.

Raises:: aiida.common.exceptions.StoringNotAllowed – if the node does not match all requirements for storing

class_node_type() → str#: Returns the node type of this node (sub) class.

entry_point() → Optional[aiida.plugins.entry_point.EntryPoint]#

Return the entry point associated this node class.

Returns:: the associated entry point or None if it isn’t known.

property logger: Optional[logging.Logger]#

Return the logger configured for this Node.

Returns:: Logger object

property uuid: str#

Return the node UUID.

Returns:: the string representation of the UUID

property node_type: str#

Return the node type.

Returns:: the node type

property process_type: Optional[str]#

Return the node process type.

Returns:: the process type

property label: str#

Return the node label.

Returns:: the label

property description: str#

Return the node description.

Returns:: the description

property computer: Optional[aiida.orm.computers.Computer]#: Return the computer of this node.

property user: aiida.orm.users.User#: Return the user of this node.

property ctime: datetime.datetime#

Return the node ctime.

Returns:: the ctime

property mtime: datetime.datetime#

Return the node mtime.

Returns:: the mtime

store_all(with_transaction: bool = True) → aiida.orm.nodes.node.Node#

Store the node, together with all input links.

Unstored nodes from cached incoming linkswill also be stored.

Parameters:: with_transaction – if False, do not use a transaction because the caller will already have opened one.

store(with_transaction: bool = True) → aiida.orm.nodes.node.Node#

Store the node in the database while saving its attributes and repository directory.

After being called attributes cannot be changed anymore! Instead, extras can be changed only AFTER calling this store() function.

Note:: After successful storage, those links that are in the cache, and for which also the parent node is already stored, will be automatically stored. The others will remain unstored.
Parameters:: with_transaction – if False, do not use a transaction because the caller will already have opened one.

_store(with_transaction: bool = True, clean: bool = True) → aiida.orm.nodes.node.Node#

Store the node in the database while saving its attributes and repository directory.

Parameters:

with_transaction – if False, do not use a transaction because the caller will already have opened one.
clean – boolean, if True, will clean the attributes and extras before attempting to store

_verify_are_parents_stored() → None#

Verify that all parent nodes are already stored.

Raises:: aiida.common.ModificationNotAllowed – if one of the source nodes of incoming links is not stored.

_store_from_cache(cache_node: aiida.orm.nodes.node.Node, with_transaction: bool) → None#: Store this node from an existing cache node.

Note

With the current implementation of the backend repository, which automatically deduplicates the content that it contains, we do not have to copy the contents of the source node. Since the content should be exactly equal, the repository will already contain it and there is nothing to copy. We simply replace the current repository instance with a clone of that of the source node, which does not actually copy any files.

_add_outputs_from_cache(cache_node: aiida.orm.nodes.node.Node) → None#: Replicate the output links and nodes from the cached node onto this node.

get_description() → str#

Return a string with a description of the node.

Returns:: a description string

property is_valid_cache: bool#

Hook to exclude certain Node classes from being considered a valid cache.

The base class assumes that all node instances are valid to cache from, unless the _VALID_CACHE_KEY extra has been set to False explicitly. Subclasses can override this property with more specific logic, but should probably also consider the value returned by this base class.

_deprecated_repo_methods = None#

_deprecated_attr_methods = None#

_deprecated_extra_methods = None#

_deprecated_comment_methods = None#

_deprecated_caching_methods = None#

_deprecated_links_methods = None#

Collection()#

Return the collection type for this class.

This used to be a class argument with the value NodeCollection. The argument is deprecated and this property is here for backwards compatibility to print the deprecation warning.

__getattr__(name: str) → Any#

This method is called when an attribute is not found in the instance.

It allows for the handling of deprecated mixin methods.

class aiida.orm.NodeAttributes(node: aiida.orm.nodes.node.Node)#

Interface to the attributes of a node instance.

Attributes are a JSONable dictionary, stored on each node, allowing for arbitrary data to be stored by node subclasses (and thus data plugins).

Once the node is stored, the attributes are generally deemed immutable (except for some updatable keys on process nodes, which can be mutated whilst the node is not “sealed”).

Initialization

Initialize the interface.

__contains__(key: str) → bool#: Check if the node contains an attribute with the given key.

property all: Dict[str, Any]#

Return the complete attributes dictionary.

Warning

While the entity is unstored, this will return references of the attributes on the database model, meaning that changes on the returned values (if they are mutable themselves, e.g. a list or dictionary) will automatically be reflected on the database model as well. As soon as the entity is stored, the returned attributes will be a deep copy and mutations of the database attributes will have to go through the appropriate set methods. Therefore, once stored, retrieving a deep copy can be a heavy operation. If you only need the keys or some values, use the iterators keys and items, or the getters get and get_many instead.

Returns:: the attributes as a dictionary

get(key: str, default=_NO_DEFAULT) → Any#

Return the value of an attribute.

Warning

While the entity is unstored, this will return a reference of the attribute on the database model, meaning that changes on the returned value (if they are mutable themselves, e.g. a list or dictionary) will automatically be reflected on the database model as well. As soon as the entity is stored, the returned attribute will be a deep copy and mutations of the database attributes will have to go through the appropriate set methods.

Parameters:

key – name of the attribute
default – return this value instead of raising if the attribute does not exist

Returns:

the value of the attribute

Raises:

AttributeError – if the attribute does not exist and no default is specified

get_many(keys: List[str]) → List[Any]#

Return the values of multiple attributes.

Warning

Parameters:: keys – a list of attribute names
Returns:: a list of attribute values
Raises:: AttributeError – if at least one attribute does not exist

set(key: str, value: Any) → None#

Set an attribute to the given value.

Parameters:

key – name of the attribute
value – value of the attribute

Raises:

aiida.common.ValidationError – if the key is invalid, i.e. contains periods
aiida.common.ModificationNotAllowed – if the entity is stored

set_many(attributes: Dict[str, Any]) → None#

Set multiple attributes.

Note

This will override any existing attributes that are present in the new dictionary.

Parameters:

attributes – a dictionary with the attributes to set

Raises:

aiida.common.ValidationError – if any of the keys are invalid, i.e. contain periods
aiida.common.ModificationNotAllowed – if the entity is stored

reset(attributes: Dict[str, Any]) → None#

Reset the attributes.

Note

This will completely clear any existing attributes and replace them with the new dictionary.

Parameters:

attributes – a dictionary with the attributes to set

Raises:

aiida.common.ValidationError – if any of the keys are invalid, i.e. contain periods
aiida.common.ModificationNotAllowed – if the entity is stored

delete(key: str) → None#

Delete an attribute.

Parameters:

key – name of the attribute

Raises:

AttributeError – if the attribute does not exist
aiida.common.ModificationNotAllowed – if the entity is stored

delete_many(keys: List[str]) → None#

Delete multiple attributes.

Parameters:

keys – names of the attributes to delete

Raises:

AttributeError – if at least one of the attribute does not exist
aiida.common.ModificationNotAllowed – if the entity is stored

clear() → None#: Delete all attributes.

items() → Iterable[Tuple[str, Any]]#

Return an iterator over the attributes.

Returns:: an iterator with attribute key value pairs

keys() → Iterable[str]#

Return an iterator over the attribute keys.

Returns:: an iterator with attribute keys

class aiida.orm.NodeEntityLoader#

Bases: aiida.orm.utils.loaders.OrmEntityLoader

Loader for the Node entity and sub classes.

orm_base_class()#

Returns:: the orm base class

classmethod _get_query_builder_label_identifier(identifier, classes, operator='==', project='*')#

Return the query builder instance that attempts to map the identifier onto an entity of the orm class, defined for this loader class, interpreting the identifier as a LABEL like identifier

Parameters:

identifier – the LABEL identifier
classes – a tuple of orm classes to which the identifier should be mapped
operator – the operator to use in the query
project – the property or properties to project for entities matching the query

Returns:

the query builder instance that should retrieve the entity corresponding to the identifier

Raises:

ValueError – if the identifier is invalid
aiida.common.NotExistent – if the orm base class does not support a LABEL like identifier

class aiida.orm.NodeLinksManager(node, link_type, incoming)#

A manager that allows to inspect, with tab-completion, nodes linked to a given one. See an example of its use in CalculationNode.inputs.

Initialization

Initialise the link manager.

Parameters:

node – the reference node object
link_type – the link_type to inspect
incoming – if True, inspect incoming links, otherwise inspect outgoing links

_namespace_separator = '__'#

_construct_attribute_dict(incoming)#

Construct an attribute dict from all links of the node, recreating nested namespaces from flat link labels.

Parameters:: incoming – if True, inspect incoming links, otherwise inspect outgoing links.

_get_keys()#: Return the valid link labels, used e.g. to make getattr() work

_get_node_by_link_label(label)#

Return the linked node with a given link label.

Nested namespaces in link labels get represented by double underscores in the database. Up until now, the link manager didn’t automatically unroll these again into nested namespaces and so a user was forced to pass the link with double underscores to dereference the corresponding node. For example, when used with the inputs attribute of a ProcessNode one had to do:

node.inputs.nested__sub__namespace

Now it is possible to do

node.inputs.nested.sub.namespace

which is more intuitive since the double underscore replacement is just for the database and the user shouldn’t even have to know about it. For compatibility we support the old version a bit longer and it will emit a deprecation warning.

Parameters:: label – the link label connecting the current node to the node to get.

__dir__()#: Allow to list all valid input links

__iter__()#

__getattr__(name)#

Parameters:: name – name of the attribute to be asked to the parser results.

__contains__(key)#: Override the operator of the base class to emit deprecation warning if double underscore is used in key.

__getitem__(name)#

interface to get to the parser results as a dictionary.

Parameters:: name – name of the attribute to be asked to the parser results.

__str__()#: Return a string representation of the manager

__repr__()#

class aiida.orm.NodeRepository(node: aiida.orm.nodes.node.Node)#

Interface to the file repository of a node instance.

This is the compatibility layer between the Node class and the Repository class. The repository in principle has no concept of immutability, so it is implemented here. Any mutating operations will raise a ModificationNotAllowed exception if the node is stored. Otherwise the operation is just forwarded to the repository instance.

The repository instance keeps an internal mapping of the file hierarchy that it maintains, starting from an empty hierarchy if the instance was constructed normally, or from a specific hierarchy if reconstructred through the Repository.from_serialized classmethod. This is only the case for stored nodes, because unstored nodes do not have any files yet when they are constructed. Once the node get’s stored, the repository is asked to serialize its metadata contents which is then stored in the repository_metadata field of the backend node. This layer explicitly does not update the metadata of the node on a mutation action. The reason is that for stored nodes these actions are anyway forbidden and for unstored nodes, the final metadata will be stored in one go, once the node is stored, so there is no need to keep updating the node metadata intermediately. Note that this does mean that repository_metadata does not give accurate information, as long as the node is not yet stored.

Initialization

Construct a new instance of the repository interface.

property metadata: Dict[str, Any]#

Return the repository metadata, representing the virtual file hierarchy.

Note, this is only accurate if the node is stored.

Returns:: the repository metadata

_update_repository_metadata()#: Refresh the repository metadata of the node if it is stored.

_check_mutability()#

Check if the node is mutable.

Raises:: ModificationNotAllowed – when the node is stored and therefore immutable.

property _repository: aiida.repository.Repository#

Return the repository instance, lazily constructing it if necessary.

Note

this property is protected because a node’s repository should not be accessed outside of its scope.

Returns:: the file repository instance.

_store() → None#: Store the repository in the backend.

_copy(repo: aiida.orm.nodes.repository.NodeRepository) → None#

Copy a repository from another instance.

This is used when storing cached nodes.

Parameters:: repo – the repository to clone.

_clone(repo: aiida.orm.nodes.repository.NodeRepository) → None#

Clone the repository from another instance.

This is used when cloning a node.

Parameters:: repo – the repository to clone.

serialize() → Dict#

Serialize the metadata of the repository content into a JSON-serializable format.

Returns:: dictionary with the content metadata.

hash() → str#

Generate a hash of the repository’s contents.

Returns:: the hash representing the contents of the repository.

list_objects(path: Optional[str] = None) → List[aiida.repository.File]#

Return a list of the objects contained in this repository sorted by name, optionally in given sub directory.

Parameters:

path – the relative path where to store the object in the repository.

Returns:

a list of File named tuples representing the objects present in directory with the given key.

Raises:

TypeError – if the path is not a string and relative path.
FileNotFoundError – if no object exists for the given path.
NotADirectoryError – if the object at the given path is not a directory.

list_object_names(path: Optional[str] = None) → List[str]#

Return a sorted list of the object names contained in this repository, optionally in the given sub directory.

Parameters:

path – the relative path where to store the object in the repository.

Returns:

a list of File named tuples representing the objects present in directory with the given key.

Raises:

TypeError – if the path is not a string and relative path.
FileNotFoundError – if no object exists for the given path.
NotADirectoryError – if the object at the given path is not a directory.

open(path: str, mode='r') → Iterator[Union[BinaryIO, TextIO]]#

Open a file handle to an object stored under the given key.

Note

this should only be used to open a handle to read an existing file. To write a new file use the method put_object_from_filelike instead.

Parameters:

path – the relative path of the object within the repository.

Returns:

yield a byte stream object.

Raises:

TypeError – if the path is not a string and relative path.
FileNotFoundError – if the file does not exist.
IsADirectoryError – if the object is a directory and not a file.
OSError – if the file could not be opened.

get_object(path: Optional[aiida.orm.nodes.repository.FilePath] = None) → aiida.repository.File#

Return the object at the given path.

Parameters:

path – the relative path where to store the object in the repository.

Returns:

the File representing the object located at the given relative path.

Raises:

TypeError – if the path is not a string or Path, or is an absolute path.
FileNotFoundError – if no object exists for the given path.

get_object_content(path: str, mode='r') → Union[str, bytes]#

Return the content of a object identified by key.

Parameters:

key – fully qualified identifier for the object within the repository.

Raises:

TypeError – if the path is not a string and relative path.
FileNotFoundError – if the file does not exist.
IsADirectoryError – if the object is a directory and not a file.
OSError – if the file could not be opened.

put_object_from_bytes(content: bytes, path: str) → None#

Store the given content in the repository at the given path.

Parameters:

path – the relative path where to store the object in the repository.
content – the content to store.

Raises:

TypeError – if the path is not a string and relative path.
FileExistsError – if an object already exists at the given path.

put_object_from_filelike(handle: io.BufferedReader, path: str)#

Store the byte contents of a file in the repository.

Parameters:

handle – filelike object with the byte content to be stored.
path – the relative path where to store the object in the repository.

Raises:

TypeError – if the path is not a string and relative path.
ModificationNotAllowed – when the node is stored and therefore immutable.

put_object_from_file(filepath: str, path: str)#

Store a new object under path with contents of the file located at filepath on the local file system.

Parameters:

filepath – absolute path of file whose contents to copy to the repository
path – the relative path where to store the object in the repository.

Raises:

TypeError – if the path is not a string and relative path, or the handle is not a byte stream.
ModificationNotAllowed – when the node is stored and therefore immutable.

put_object_from_tree(filepath: str, path: Optional[str] = None)#

Store the entire contents of filepath on the local file system in the repository with under given path.

Parameters:

filepath – absolute path of the directory whose contents to copy to the repository.
path – the relative path where to store the objects in the repository.

Raises:

TypeError – if the path is not a string and relative path.
ModificationNotAllowed – when the node is stored and therefore immutable.

walk(path: Optional[aiida.orm.nodes.repository.FilePath] = None) → Iterable[Tuple[pathlib.PurePosixPath, List[str], List[str]]]#

Walk over the directories and files contained within this repository.

Note

the order of the dirname and filename lists that are returned is not necessarily sorted. This is in line with the os.walk implementation where the order depends on the underlying file system used.

Parameters:: path – the relative path of the directory within the repository whose contents to walk.
Returns:: tuples of root, dirnames and filenames just like os.walk, with the exception that the root path is always relative with respect to the repository root, instead of an absolute path and it is an instance of pathlib.PurePosixPath instead of a normal string

glob() → Iterable[pathlib.PurePosixPath]#: Yield a recursive list of all paths (files and directories).

copy_tree(target: Union[str, pathlib.Path], path: Optional[aiida.orm.nodes.repository.FilePath] = None) → None#

Copy the contents of the entire node repository to another location on the local file system.

Parameters:

target – absolute path of the directory where to copy the contents to.
path – optional relative path whose contents to copy.

delete_object(path: str)#

Delete the object from the repository.

Parameters:

key – fully qualified identifier for the object within the repository.

Raises:

TypeError – if the path is not a string and relative path.
FileNotFoundError – if the file does not exist.
IsADirectoryError – if the object is a directory and not a file.
OSError – if the file could not be deleted.
ModificationNotAllowed – when the node is stored and therefore immutable.

erase()#

Delete all objects from the repository.

Raises:: ModificationNotAllowed – when the node is stored and therefore immutable.

class aiida.orm.NumericType#

Bases: aiida.orm.nodes.data.base.BaseType

Sub class of Data to store numbers, overloading common operators (+, *, …).

__add__(other)#

__radd__(other)#

__sub__(other)#

__rsub__(other)#

__mul__(other)#

__rmul__(other)#

__div__(other)#

__rdiv__(other)#

__truediv__(other)#

__rtruediv__(other)#

__floordiv__(other)#

__rfloordiv__(other)#

__pow__(power)#

__lt__(other)#

__le__(other)#

__gt__(other)#

__ge__(other)#

__mod__(other)#

__rmod__(other)#

__float__()#

__int__()#

class aiida.orm.OrbitalData#

Bases: aiida.orm.nodes.data.data.Data

Used for storing collections of orbitals, as well as providing methods for accessing them internally.

clear_orbitals()#: Remove all orbitals that were added to the class Cannot work if OrbitalData has been already stored

get_orbitals(**kwargs)#

Returns all orbitals by default. If a site is provided, returns all orbitals cooresponding to the location of that site, additional arguments may be provided, which act as filters on the retrieved orbitals.

Parameters:: site – if provided, returns all orbitals with position of site
Kwargs:: attributes than can filter the set of returned orbitals
Return list_of_outputs:: a list of orbitals

set_orbitals(orbitals)#

Sets the orbitals into the database. Uses the orbital’s inherent set_orbital_dict method to generate a orbital dict string.

Parameters:: orbital – an orbital or list of orbitals to be set

aiida.orm.OrderSpecifier(field, direction)#

class aiida.orm.OrmEntityLoader#

Base class for entity loaders.

label_ambiguity_breaker = '!'#

abstract orm_base_class()#

Returns:: the orm base class

abstract classmethod _get_query_builder_label_identifier(identifier, classes, operator='==', project='*')#

Return the query builder instance that attempts to map the identifier onto an entity of the orm class, defined for this loader class, interpreting the identifier as a LABEL like identifier

Parameters:

identifier – the LABEL identifier
classes – a tuple of orm classes to which the identifier should be mapped
operator – the operator to use in the query
project – the property or properties to project for entities matching the query

Returns:

the query builder instance

Raises:

ValueError – if the identifier is invalid
aiida.common.NotExistent – if the orm base class does not support a LABEL like identifier

classmethod _get_query_builder_id_identifier(identifier, classes)#

Return the query builder instance that attempts to map the identifier onto an entity of the orm class, defined for this loader class, interpreting the identifier as an ID like identifier

Parameters:

identifier – the ID identifier
classes – a tuple of orm classes to which the identifier should be mapped

Returns:

the query builder instance

classmethod _get_query_builder_uuid_identifier(identifier, classes, query_with_dashes)#

Return the query builder instance that attempts to map the identifier onto an entity of the orm class, defined for this loader class, interpreting the identifier as a UUID like identifier

Parameters:

identifier – the UUID identifier
classes – a tuple of orm classes to which the identifier should be mapped

Returns:

the query builder instance

classmethod get_query_builder(identifier, identifier_type=None, sub_classes=None, query_with_dashes=True, operator='==', project='*')#

Return the query builder instance that attempts to map the identifier onto an entity of the orm class, defined for this loader class, inferring the identifier type if it is not defined.

Parameters:

identifier – the identifier
identifier_type – the type of the identifier
sub_classes – an optional tuple of orm classes, that should each be strict sub classes of the base orm class of the loader, that will narrow the queryset
operator – the operator to use in the query
project – the property or properties to project for entities matching the query

Returns:

the query builder instance and a dictionary of used query parameters

classmethod get_options(incomplete, project='*')#

Return the list of entities that match the incomplete identifier.

Note

For the time being only LABEL auto-completion is supported so the identifier type is not inferred but hard-coded to be IdentifierType.LABEL

Parameters:

incomplete – the incomplete identifier
project – the field(s) to project for each entity that matches the incomplete identifier

Returns:

list of entities matching the incomplete identifier

classmethod load_entity(identifier, identifier_type=None, sub_classes=None, query_with_dashes=True)#

Load an entity that uniquely corresponds to the provided identifier of the identifier type.

Parameters:

identifier – the identifier
identifier_type – the type of the identifier
sub_classes – an optional tuple of orm classes, that should each be strict sub classes of the base orm class of the loader, that will narrow the queryset

Returns:

the loaded entity

Raises:

aiida.common.MultipleObjectsError – if the identifier maps onto multiple entities
aiida.common.NotExistent – if the identifier maps onto not a single entity

classmethod get_query_classes(sub_classes=None)#

Get the tuple of classes to be used for the entity query. If sub_classes is defined, each class will be validated by verifying that it is a sub class of the loader’s orm base class. Validate a tuple of classes if a user passes in a specific one when attempting to load an entity. Each class should be a sub class of the entity loader’s orm base class

Parameters:: sub_classes – an optional tuple of orm classes, that should each be strict sub classes of the base orm class of the loader, that will narrow the queryset
Returns:: the tuple of orm classes to be used for the entity query
Raises:: ValueError – if any of the classes are not a sub class of the entity loader’s orm base class

classmethod infer_identifier_type(value)#

This method will attempt to automatically distinguish which identifier type is implied for the given value, if the value itself has no type from which it can be inferred.

The strategy is to first attempt to convert the value to an integer. If successful, it is assumed that the value represents an ID. If that fails, we attempt to interpret the value as a base 16 encoded integer, after having removed any dashes from the string. If that succeeds, it is most likely a UUID. If it seems to be neither an ID nor a UUID, it is assumed to be a LABEL like identifier.

With this approach there is the possibility for ambiguity. Since it is allowed to pass a partial UUID, it is possible that the partial UUID is also a valid ID. Likewise, a LABEL identifier might also be a valid ID, or a valid (partial) UUID. Fortunately, these ambiguities can be solved though:

ID/UUID: can always be solved by passing a partial UUID with at least one dash

ID/LABEL: appending an exclamation point ! to the identifier, will force LABEL interpretation

UUID/LABEL: appending an exclamation point ! to the identifier, will force LABEL interpretation

As one can see, the user will always be able to include at least one dash of the UUID identifier to prevent it from being interpreted as an ID. For the potential ambiguities in LABEL identifiers, we had to introduce a special marker to provide a surefire way of breaking any ambiguity that may arise. Adding an exclamation point will break the normal strategy and the identifier will directly be interpreted as a LABEL identifier.

Parameters:: value – the value of the identifier
Returns:: the identifier and identifier type
Raises:: ValueError – if the value is an invalid identifier

class aiida.orm.PortableCode(filepath_executable: str, filepath_files: pathlib.Path, **kwargs)#

Bases: aiida.orm.nodes.data.code.legacy.Code

Data plugin representing an executable code stored in AiiDA’s storage.

Initialization

Construct a new instance.

Note

If the files necessary for this code are not all located in a single directory or the directory contains files that should not be uploaded, and so the filepath_files cannot be used. One can use the methods of the aiida.orm.nodes.repository.NodeRepository class. This can be accessed through the base.repository attribute of the instance after it has been constructed. For example:

code = PortableCode(filepath_executable='some_name.exe')
code.put_object_from_file()
code.put_object_from_filelike()
code.put_object_from_tree()

Parameters:

filepath_executable – The relative filepath of the executable within the directory of uploaded files.
filepath_files – The filepath to the directory containing all the files of the code.

_KEY_ATTRIBUTE_FILEPATH_EXECUTABLE: str = 'filepath_executable'#

_validate()#

Validate the instance by checking that an executable is defined and it is part of the repository files.

:raises aiida.common.exceptions.ValidationError: If the state of the node is invalid.

can_run_on_computer(computer: aiida.orm.Computer) → bool#

Return whether the code can run on a given computer.

A PortableCode should be able to be run on any computer in principle.

Parameters:: computer – The computer.
Returns:: True if the provided computer is the same as the one configured for this code.

get_executable() → pathlib.PurePosixPath#

Return the executable that the submission script should execute to run the code.

Returns:: The executable to be called in the submission script.

validate_working_directory(folder: aiida.common.folders.Folder)#

Validate content of the working directory created by the CalcJob plugin.

Parameters:: folder – A sandbox folder that the CalcJob plugin wrote input files to that will be copied to the working directory for the corresponding calculation job instance.
Raises:: PluginInternalError – The CalcJob plugin created a file that has the same relative filepath as the executable for this portable code.

property full_label: str#

Return the full label of this code.

The full label can be just the label itself but it can be something else. However, it at the very least has to include the label of the code.

Returns:: The full label of the code.

property filepath_executable: pathlib.PurePosixPath#

Return the relative filepath of the executable that this code represents.

Returns:: The relative filepath of the executable.

classmethod _get_cli_options() → dict#: Return the CLI options that would allow to create an instance of this class.

class aiida.orm.ProcessNode(backend: Optional[aiida.orm.implementation.StorageBackend] = None, user: Optional[aiida.orm.users.User] = None, computer: Optional[aiida.orm.computers.Computer] = None, **kwargs: Any)#

Bases: aiida.orm.utils.mixins.Sealable, aiida.orm.nodes.node.Node

Base class for all nodes representing the execution of a process

This class and its subclasses serve as proxies in the database, for actual Process instances being run. The Process instance in memory will leverage an instance of this class (the exact sub class depends on the sub class of Process) to persist important information of its state to the database. This serves as a way for the user to inspect the state of the Process during its execution as well as a permanent record of its execution in the provenance graph, after the execution has terminated.

Initialization

Parameters:: backend_entity – the backend model supporting this entity

_CLS_NODE_LINKS = None#

_CLS_NODE_CACHING = None#

CHECKPOINT_KEY = 'checkpoints'#

EXCEPTION_KEY = 'exception'#

EXIT_MESSAGE_KEY = 'exit_message'#

EXIT_STATUS_KEY = 'exit_status'#

PROCESS_PAUSED_KEY = 'paused'#

PROCESS_LABEL_KEY = 'process_label'#

PROCESS_STATE_KEY = 'process_state'#

PROCESS_STATUS_KEY = 'process_status'#

_unstorable_message = 'only Data, WorkflowNode, CalculationNode or their subclasses can be stored'#

__str__() → str#

_updatable_attributes() → Tuple[str, ...]#

property logger#

Get the logger of the Calculation object, so that it also logs to the DB.

Returns:: LoggerAdapter object, that works like a logger, but also has the ‘extra’ embedded

get_builder_restart() → aiida.engine.processes.builder.ProcessBuilder#

Return a ProcessBuilder that is ready to relaunch the process that created this node.

Returns:: ~aiida.engine.processes.builder.ProcessBuilder instance

property process_class: Type[aiida.engine.processes.Process]#

Return the process class that was used to create this node.

Returns:: Process class
Raises:: ValueError – if no process type is defined, it is an invalid process type string or cannot be resolved to load the corresponding class

set_process_type(process_type_string: str) → None#

Set the process type string.

Parameters:: process_type – the process type string identifying the class using this process node as storage.

property process_label: Optional[str]#

Return the process label

Returns:: the process label

set_process_label(label: str) → None#

Set the process label

Parameters:: label – process label string

property process_state: Optional[plumpy.process_states.ProcessState]#

Return the process state

Returns:: the process state instance of ProcessState enum

set_process_state(state: Union[str, plumpy.process_states.ProcessState, None])#

Set the process state

Parameters:: state – value or instance of ProcessState enum

property process_status: Optional[str]#

Return the process status

The process status is a generic status message e.g. the reason it might be paused or when it is being killed

Returns:: the process status

set_process_status(status: Optional[str]) → None#

Set the process status

The process status is a generic status message e.g. the reason it might be paused or when it is being killed. If status is None, the corresponding attribute will be deleted.

Parameters:: status – string process status

property is_terminated: bool#

Return whether the process has terminated

Terminated means that the process has reached any terminal state.

Returns:: True if the process has terminated, False otherwise
Return type:: bool

property is_excepted: bool#

Return whether the process has excepted

Excepted means that during execution of the process, an exception was raised that was not caught.

Returns:: True if during execution of the process an exception occurred, False otherwise
Return type:: bool

property is_killed: bool#

Return whether the process was killed

Killed means the process was killed directly by the user or by the calling process being killed.

Returns:: True if the process was killed, False otherwise
Return type:: bool

property is_finished: bool#

Return whether the process has finished

Finished means that the process reached a terminal state nominally. Note that this does not necessarily mean successfully, but there were no exceptions and it was not killed.

Returns:: True if the process has finished, False otherwise
Return type:: bool

property is_finished_ok: bool#

Return whether the process has finished successfully

Finished successfully means that it terminated nominally and had a zero exit status.

Returns:: True if the process has finished successfully, False otherwise
Return type:: bool

property is_failed: bool#

Return whether the process has failed

Failed means that the process terminated nominally but it had a non-zero exit status.

Returns:: True if the process has failed, False otherwise
Return type:: bool

property exit_status: Optional[int]#

Return the exit status of the process

Returns:: the exit status, an integer exit code or None

set_exit_status(status: Union[None, enum.Enum, int]) → None#

Set the exit status of the process

Parameters:: state – an integer exit code or None, which will be interpreted as zero

property exit_message: Optional[str]#

Return the exit message of the process

Returns:: the exit message

set_exit_message(message: Optional[str]) → None#

Set the exit message of the process, if None nothing will be done

Parameters:: message – a string message

property exception: Optional[str]#

Return the exception of the process or None if the process is not excepted.

If the process is marked as excepted yet there is no exception attribute, an empty string will be returned.

Returns:: the exception message or None

set_exception(exception: str) → None#

Set the exception of the process

Parameters:: exception – the exception message

property checkpoint: Optional[Dict[str, Any]]#

Return the checkpoint bundle set for the process

Returns:: checkpoint bundle if it exists, None otherwise

set_checkpoint(checkpoint: Dict[str, Any]) → None#

Set the checkpoint bundle set for the process

Parameters:: state – string representation of the stepper state info

delete_checkpoint() → None#: Delete the checkpoint bundle set for the process

property paused: bool#

Return whether the process is paused

Returns:: True if the Calculation is marked as paused, False otherwise

pause() → None#

Mark the process as paused by setting the corresponding attribute.

This serves only to reflect that the corresponding Process is paused and so this method should not be called by anyone but the Process instance itself.

unpause() → None#

Mark the process as unpaused by removing the corresponding attribute.

This serves only to reflect that the corresponding Process is unpaused and so this method should not be called by anyone but the Process instance itself.

property called: List[aiida.orm.nodes.process.process.ProcessNode]#

Return a list of nodes that the process called

Returns:: list of process nodes called by this process

property called_descendants: List[aiida.orm.nodes.process.process.ProcessNode]#

Return a list of all nodes that have been called downstream of this process

This will recursively find all the called processes for this process and its children.

property caller: Optional[aiida.orm.nodes.process.process.ProcessNode]#

Return the process node that called this process node, or None if it does not have a caller

Returns:: process node that called this process node instance or None

class aiida.orm.ProjectionData(*args, source=None, **kwargs)#

Bases: aiida.orm.nodes.data.orbital.OrbitalData, aiida.orm.nodes.data.array.array.ArrayData

A class to handle arrays of projected wavefunction data. That is projections of a orbitals, usually an atomic-hydrogen orbital, onto a given bloch wavefunction, the bloch wavefunction being indexed by s, n, and k. E.g. the elements are the projections described as < orbital | Bloch wavefunction (s,n,k) >

Initialization

Construct a new instance, setting the source attribute if provided as a keyword argument.

_check_projections_bands(projection_array)#

Checks to make sure that a reference bandsdata is already set, and that projection_array is of the same shape of the bands data

Parameters:: projwfc_arrays – nk x nb x nwfc array, to be checked against bands
Raise:: AttributeError if energy is not already set
Raise:: AttributeError if input_array is not of same shape as dos_energy

set_reference_bandsdata(value)#

Sets a reference bandsdata, creates a uuid link between this data object and a bandsdata object, must be set before any projection arrays

Parameters:: value – a BandsData instance, a uuid or a pk
Raise:: exceptions.NotExistent if there was no BandsData associated with uuid or pk

get_reference_bandsdata()#

Returns the reference BandsData, using the set uuid via set_reference_bandsdata

Returns:

a BandsData instance

Raises:

AttributeError – if the bandsdata has not been set yet
exceptions.NotExistent – if the bandsdata uuid did not retrieve bandsdata

_find_orbitals_and_indices(**kwargs)#

Finds all the orbitals and their indicies associated with kwargs essential for retrieving the other indexed array parameters

Parameters:: kwargs – kwargs that can call orbitals as in get_orbitals()
Returns:: retrieve_indexes, list of indicicies of orbitals corresponding to the kwargs
Returns:: all_orbitals, list of orbitals to which the indexes correspond

get_pdos(**kwargs)#

Retrieves all the pdos arrays corresponding to the input kwargs

Parameters:: kwargs – inputs describing the orbitals associated with the pdos arrays
Returns:: a list of tuples containing the orbital, energy array and pdos array associated with all orbitals that correspond to kwargs

get_projections(**kwargs)#

Retrieves all the pdos arrays corresponding to the input kwargs

Parameters:: kwargs – inputs describing the orbitals associated with the pdos arrays
Returns:: a list of tuples containing the orbital, and projection arrays associated with all orbitals that correspond to kwargs

static _from_index_to_arrayname(index)#: Used internally to determine the array names.

set_projectiondata(list_of_orbitals, list_of_projections=None, list_of_energy=None, list_of_pdos=None, tags=None, bands_check=True)#

Stores the projwfc_array using the projwfc_label, after validating both.

Parameters:

list_of_orbitals – list of orbitals, of class orbital data. They should be the ones up on which the projection array corresponds with.
list_of_projections – list of arrays of projections of a atomic wavefunctions onto bloch wavefunctions. Since the projection is for every bloch wavefunction which can be specified by its spin (if used), band, and kpoint the dimensions must be nspin x nbands x nkpoints for the projwfc array. Or nbands x nkpoints if spin is not used.
energy_axis – list of energy axis for the list_of_pdos
list_of_pdos – a list of projected density of states for the atomic wavefunctions, units in states/eV
tags – A list of tags, not supported currently.
bands_check – if false, skips checks of whether the bands has been already set, and whether the sizes match. For use in parsers, where the BandsData has not yet been stored and therefore get_reference_bandsdata cannot be called

abstract set_orbitals(**kwargs)#: This method is inherited from OrbitalData, but is blocked here. If used will raise a NotImplementedError

class aiida.orm.QueryBuilder(backend: Optional[aiida.orm.implementation.StorageBackend] = None, *, debug: bool = False, path: Optional[Sequence[Union[str, Dict[str, Any], aiida.orm.querybuilder.EntityClsType]]] = (), filters: Optional[Dict[str, aiida.orm.querybuilder.FilterType]] = None, project: Optional[Dict[str, aiida.orm.querybuilder.ProjectType]] = None, limit: Optional[int] = None, offset: Optional[int] = None, order_by: Optional[aiida.orm.querybuilder.OrderByType] = None, distinct: bool = False)#

The class to query the AiiDA database.

Usage:

from aiida.orm.querybuilder import QueryBuilder
qb = QueryBuilder()
# Querying nodes:
qb.append(Node)
# retrieving the results:
results = qb.all()

Initialization

Instantiates a QueryBuilder instance.

Which backend is used decided here based on backend-settings (taken from the user profile). This cannot be overridden so far by the user.

Parameters:

debug – Turn on debug mode. This feature prints information on the screen about the stages of the QueryBuilder. Does not affect results.
path – A list of the vertices to traverse. Leave empty if you plan on using the method QueryBuilder.append().
filters – The filters to apply. You can specify the filters here, when appending to the query using QueryBuilder.append() or even later using QueryBuilder.add_filter(). Check latter gives API-details.
project – The projections to apply. You can specify the projections here, when appending to the query using QueryBuilder.append() or even later using QueryBuilder.add_projection(). Latter gives you API-details.
limit – Limit the number of rows to this number. Check QueryBuilder.limit() for more information.
offset – Set an offset for the results returned. Details in QueryBuilder.offset().
order_by – How to order the results. As the 2 above, can be set also at later stage, check QueryBuilder.order_by() for more information.
distinct – Whether to return de-duplicated rows

_EDGE_TAG_DELIM = '--'#

_VALID_PROJECTION_KEYS = ('func', 'cast')#

property backend: aiida.orm.implementation.StorageBackend#: Return the backend used by the QueryBuilder.

as_dict(copy: bool = True) → aiida.orm.implementation.querybuilder.QueryDictType#: Convert to a JSON serialisable dictionary representation of the query.

property queryhelp: aiida.orm.implementation.querybuilder.QueryDictType#: “Legacy name for as_dict method.

classmethod from_dict(dct: Dict[str, Any]) → aiida.orm.querybuilder.QueryBuilder#: Create an instance from a dictionary representation of the query.

__repr__() → str#: Return an unambiguous string representation of the instance.

__str__() → str#: Return a readable string representation of the instance.

__deepcopy__(memo) → aiida.orm.querybuilder.QueryBuilder#: Create deep copy of the instance.

get_used_tags(vertices: bool = True, edges: bool = True) → List[str]#

Returns a list of all the vertices that are being used.

Parameters:

vertices – If True, adds the tags of vertices to the returned list
edges – If True, adds the tags of edges to the returnend list.

Returns:

A list of tags

_get_unique_tag(classifiers: List[aiida.orm.querybuilder.Classifier]) → str#

Using the function get_tag_from_type, I get a tag. I increment an index that is appended to that tag until I have an unused tag. This function is called in QueryBuilder.append() when no tag is given.

Parameters:

classifiers (dict) –

Classifiers, containing the string that defines the type of the AiiDA ORM class. For subclasses of Node, this is the Node._plugin_type_string, for other they are as defined as returned by QueryBuilder._get_ormclass().

Can also be a list of dictionaries, when multiple classes are passed to QueryBuilder.append

Returns:

A tag as a string (it is a single string also when passing multiple classes).

append(cls: Optional[Union[aiida.orm.querybuilder.EntityClsType, Sequence[aiida.orm.querybuilder.EntityClsType]]] = None, entity_type: Optional[Union[str, Sequence[str]]] = None, tag: Optional[str] = None, filters: Optional[aiida.orm.querybuilder.FilterType] = None, project: Optional[aiida.orm.querybuilder.ProjectType] = None, subclassing: bool = True, edge_tag: Optional[str] = None, edge_filters: Optional[aiida.orm.querybuilder.FilterType] = None, edge_project: Optional[aiida.orm.querybuilder.ProjectType] = None, outerjoin: bool = False, joining_keyword: Optional[str] = None, joining_value: Optional[Any] = None, orm_base: Optional[str] = None, **kwargs: Any) → aiida.orm.querybuilder.QueryBuilder#

Any iterative procedure to build the path for a graph query needs to invoke this method to append to the path.

Parameters:

cls –
The Aiida-class (or backend-class) defining the appended vertice. Also supports a tuple/list of classes. This results in an all instances of this class being accepted in a query. However the classes have to have the same orm-class for the joining to work. I.e. both have to subclasses of Node. Valid is:
```
cls=(StructureData, Dict)
```
This is invalid:

cls=(Group, Node)
entity_type – The node type of the class, if cls is not given. Also here, a tuple or list is accepted.
tag – A unique tag. If none is given, I will create a unique tag myself.
filters – Filters to apply for this vertex. See add_filter(), the method invoked in the background, or usage examples for details.
project – Projections to apply. See usage examples for details. More information also in add_projection().
subclassing – Whether to include subclasses of the given class (default True). E.g. Specifying a ProcessNode as cls will include CalcJobNode, WorkChainNode, CalcFunctionNode, etc..
edge_tag – The tag that the edge will get. If nothing is specified (and there is a meaningful edge) the default is tag1–tag2 with tag1 being the entity joining from and tag2 being the entity joining to (this entity).
edge_filters – The filters to apply on the edge. Also here, details in add_filter().
edge_project – The project from the edges. API-details in add_projection().
outerjoin – If True, (default is False), will do a left outerjoin instead of an inner join

Joining can be specified in two ways:

Specifying the ‘joining_keyword’ and ‘joining_value’ arguments

Specify a single keyword argument

The joining keyword wil be with_* or direction, depending on the joining entity type. The joining value is the tag name or class of the entity to join to.

A small usage example how this can be invoked:

qb = QueryBuilder()             # Instantiating empty querybuilder instance
qb.append(cls=StructureData)    # First item is StructureData node
# The
# next node in the path is a PwCalculation, with
# the structure joined as an input
qb.append(
    cls=PwCalculation,
    with_incoming=StructureData
)

Returns:: self

order_by(order_by: aiida.orm.querybuilder.OrderByType) → aiida.orm.querybuilder.QueryBuilder#

Set the entity to order by

Parameters:: order_by – This is a list of items, where each item is a dictionary specifies what to sort for an entity

In each dictionary in that list, keys represent valid tags of entities (tables), and values are list of columns.

Usage:

#Sorting by id (ascending):
qb = QueryBuilder()
qb.append(Node, tag='node')
qb.order_by({'node':['id']})

# or
#Sorting by id (ascending):
qb = QueryBuilder()
qb.append(Node, tag='node')
qb.order_by({'node':[{'id':{'order':'asc'}}]})

# for descending order:
qb = QueryBuilder()
qb.append(Node, tag='node')
qb.order_by({'node':[{'id':{'order':'desc'}}]})

# or (shorter)
qb = QueryBuilder()
qb.append(Node, tag='node')
qb.order_by({'node':[{'id':'desc'}]})

add_filter(tagspec: Union[str, aiida.orm.querybuilder.EntityClsType], filter_spec: aiida.orm.querybuilder.FilterType) → aiida.orm.querybuilder.QueryBuilder#

Adding a filter to my filters.

Parameters:

tagspec – A tag string or an ORM class which maps to an existing tag
filter_spec – The specifications for the filter, has to be a dictionary

Usage:

qb = QueryBuilder()         # Instantiating the QueryBuilder instance
qb.append(Node, tag='node') # Appending a Node
#let's put some filters:
qb.add_filter('node',{'id':{'>':12}})
# 2 filters together:
qb.add_filter('node',{'label':'foo', 'uuid':{'like':'ab%'}})
# Now I am overriding the first filter I set:
qb.add_filter('node',{'id':13})

static _process_filters(filters: aiida.orm.querybuilder.FilterType) → Dict[str, Any]#: Process filters.

_add_node_type_filter(tagspec: str, classifiers: List[aiida.orm.querybuilder.Classifier], subclassing: bool)#

Add a filter based on node type.

Parameters:

tagspec – The tag, which has to exist already as a key in self._filters
classifiers – a dictionary with classifiers
subclassing – if True, allow for subclasses of the ormclass

_add_process_type_filter(tagspec: str, classifiers: List[aiida.orm.querybuilder.Classifier], subclassing: bool) → None#

Add a filter based on process type.

Parameters:

tagspec – The tag, which has to exist already as a key in self._filters
classifiers – a dictionary with classifiers
subclassing – if True, allow for subclasses of the process type

Note: This function handles the case when process_type_string is None.

_add_group_type_filter(tagspec: str, classifiers: List[aiida.orm.querybuilder.Classifier], subclassing: bool) → None#

Add a filter based on group type.

Parameters:

tagspec – The tag, which has to exist already as a key in self._filters
classifiers – a dictionary with classifiers
subclassing – if True, allow for subclasses of the ormclass

add_projection(tag_spec: Union[str, aiida.orm.querybuilder.EntityClsType], projection_spec: aiida.orm.querybuilder.ProjectType) → None#

Adds a projection

Parameters:

tag_spec – A tag string or an ORM class which maps to an existing tag
projection_spec – The specification for the projection. A projection is a list of dictionaries, with each dictionary containing key-value pairs where the key is database entity (e.g. a column / an attribute) and the value is (optional) additional information on how to process this database entity.

If the given projection_spec is not a list, it will be expanded to a list. If the listitems are not dictionaries, but strings (No additional processing of the projected results desired), they will be expanded to dictionaries.

Usage:

qb = QueryBuilder()
qb.append(StructureData, tag='struc')

# Will project the uuid and the kinds
qb.add_projection('struc', ['uuid', 'attributes.kinds'])

The above example will project the uuid and the kinds-attribute of all matching structures. There are 2 (so far) special keys.

The single star * will project the ORM-instance:

qb = QueryBuilder()
qb.append(StructureData, tag='struc')
# Will project the ORM instance
qb.add_projection('struc', '*')
print type(qb.first()[0])
# >>> aiida.orm.nodes.data.structure.StructureData

The double star ** projects all possible projections of this entity:

QueryBuilder().append(StructureData,tag=’s’, project=’**’).limit(1).dict()[0][‘s’].keys()

# >>> ‘user_id, description, ctime, label, extras, mtime, id, attributes, dbcomputer_id, type, uuid’

Be aware that the result of ** depends on the backend implementation.

set_debug(debug: bool) → aiida.orm.querybuilder.QueryBuilder#

Run in debug mode. This does not affect functionality, but prints intermediate stages when creating a query on screen.

Parameters:: debug – Turn debug on or off

debug(msg: str, *objects: Any) → None#

Log debug message.

objects will passed to the format string, e.g. msg % objects

limit(limit: Optional[int]) → aiida.orm.querybuilder.QueryBuilder#

Set the limit (nr of rows to return)

Parameters:: limit – integers of number of rows of rows to return

offset(offset: Optional[int]) → aiida.orm.querybuilder.QueryBuilder#

Set the offset. If offset is set, that many rows are skipped before returning. offset = 0 is the same as omitting setting the offset. If both offset and limit appear, then offset rows are skipped before starting to count the limit rows that are returned.

Parameters:: offset – integers of nr of rows to skip

distinct(value: bool = True) → aiida.orm.querybuilder.QueryBuilder#

Asks for distinct rows, which is the same as asking the backend to remove duplicates. Does not execute the query!

If you want a distinct query:

qb = QueryBuilder()
# append stuff!
qb.append(...)
qb.append(...)
...
qb.distinct().all() #or
qb.distinct().dict()

Returns:: self

inputs(**kwargs: Any) → aiida.orm.querybuilder.QueryBuilder#

Join to inputs of previous vertice in path.

Returns:: self

outputs(**kwargs: Any) → aiida.orm.querybuilder.QueryBuilder#

Join to outputs of previous vertice in path.

Returns:: self

children(**kwargs: Any) → aiida.orm.querybuilder.QueryBuilder#

Join to children/descendants of previous vertice in path.

Returns:: self

parents(**kwargs: Any) → aiida.orm.querybuilder.QueryBuilder#

Join to parents/ancestors of previous vertice in path.

Returns:: self

as_sql(inline: bool = False) → str#

Convert the query to an SQL string representation.

Warning

This method should be used for debugging purposes only, since normally sqlalchemy will handle this process internally.

Params inline:: Inline bound parameters (this is normally handled by the Python DB-API).

analyze_query(execute: bool = True, verbose: bool = False) → str#

Return the query plan, i.e. a list of SQL statements that will be executed.

See: https://www.postgresql.org/docs/11/sql-explain.html

Params execute:: Carry out the command and show actual run times and other statistics.
Params verbose:: Display additional information regarding the plan.

static _get_aiida_entity_res(value) → Any#

Convert a projected query result to front end class if it is an instance of a BackendEntity.

Values that are not an BackendEntity instance will be returned unaltered

Parameters:: value – a projected query result to convert
Returns:: the converted value

first(flat: bool = False) → Optional[list[Any] | Any]#

Return the first result of the query.

Calling first results in an execution of the underlying query.

Note, this may change if several rows are valid for the query, as persistent ordering is not guaranteed unless explicitly specified.

Parameters:: flat – if True, return just the projected quantity if there is just a single projection.
Returns:: One row of results as a list, or None if no result returned.

count() → int#

Counts the number of rows returned by the backend.

Returns:: the number of rows as an integer

iterall(batch_size: Optional[int] = 100) → Iterable[List[Any]]#

Same as all(), but returns a generator. Be aware that this is only safe if no commit will take place during this transaction. You might also want to read the SQLAlchemy documentation on https://docs.sqlalchemy.org/en/14/orm/query.html#sqlalchemy.orm.Query.yield_per

Parameters:: batch_size – The size of the batches to ask the backend to batch results in subcollections. You can optimize the speed of the query by tuning this parameter.
Returns:: a generator of lists

iterdict(batch_size: Optional[int] = 100) → Iterable[Dict[str, Dict[str, Any]]]#

Same as dict(), but returns a generator. Be aware that this is only safe if no commit will take place during this transaction. You might also want to read the SQLAlchemy documentation on https://docs.sqlalchemy.org/en/14/orm/query.html#sqlalchemy.orm.Query.yield_per

Parameters:: batch_size – The size of the batches to ask the backend to batch results in subcollections. You can optimize the speed of the query by tuning this parameter.
Returns:: a generator of dictionaries

all(batch_size: Optional[int] = None, flat: bool = False) → Union[List[List[Any]], List[Any]]#

Executes the full query with the order of the rows as returned by the backend.

The order inside each row is given by the order of the vertices in the path and the order of the projections for each vertex in the path.

Parameters:

batch_size – the size of the batches to ask the backend to batch results in subcollections. You can optimize the speed of the query by tuning this parameter. Leave the default None if speed is not critical or if you don’t know what you’re doing.
flat – return the result as a flat list of projected entities without sub lists.

Returns:

a list of lists of all projected entities.

one() → List[Any]#

Executes the query asking for exactly one results.

Will raise an exception if this is not the case:

Raises:: MultipleObjectsError if more then one row can be returned
Raises:: NotExistent if no result was found

dict(batch_size: Optional[int] = None) → List[Dict[str, Dict[str, Any]]]#

Executes the full query with the order of the rows as returned by the backend. the order inside each row is given by the order of the vertices in the path and the order of the projections for each vertice in the path.

Parameters:: batch_size – The size of the batches to ask the backend to batch results in subcollections. You can optimize the speed of the query by tuning this parameter. Leave the default (None) if speed is not critical or if you don’t know what you’re doing!
Returns:: A list of dictionaries of all projected entities: tag -> field -> value

Usage:

qb = QueryBuilder()
qb.append(
    StructureData,
    tag='structure',
    filters={'uuid':{'==':myuuid}},
)
qb.append(
    Node,
    with_ancestors='structure',
    project=['entity_type', 'id'],  # returns entity_type (string) and id (string)
    tag='descendant'
)

# Return the dictionaries:
print "qb.iterdict()"
for d in qb.iterdict():
    print '>>>', d

results in the following output:

qb.iterdict()
>>> {'descendant': {
        'entity_type': 'calculation.job.quantumespresso.pw.PwCalculation.',
        'id': 7716}
    }
>>> {'descendant': {
        'entity_type': 'data.remote.RemoteData.',
        'id': 8510}
    }

class aiida.orm.RemoteData(remote_path=None, **kwargs)#

Bases: aiida.orm.nodes.data.data.Data

Store a link to a file or folder on a remote machine.

Remember to pass a computer!

Initialization

Construct a new instance, setting the source attribute if provided as a keyword argument.

KEY_EXTRA_CLEANED = 'cleaned'#

get_remote_path()#

set_remote_path(val)#

property is_empty#: Check if remote folder is empty

getfile(relpath, destpath)#

Connects to the remote folder and retrieves the content of a file.

Parameters:

relpath – The relative path of the file on the remote to retrieve.
destpath – The absolute path of where to store the file on the local machine.

listdir(relpath='.')#

Connects to the remote folder and lists the directory content.

Parameters:: relpath – If ‘relpath’ is specified, lists the content of the given subfolder.
Returns:: a flat list of file/directory names (as strings).

listdir_withattributes(path='.')#

Connects to the remote folder and lists the directory content.

Parameters:: relpath – If ‘relpath’ is specified, lists the content of the given subfolder.
Returns:: a list of dictionaries, where the documentation is in :py:class:Transport.listdir_withattributes.

_clean(transport=None)#

Remove all content of the remote folder on the remote computer.

When the cleaning operation is successful, the extra with the key RemoteData.KEY_EXTRA_CLEANED is set.

Parameters:: transport – Provide an optional transport that is already open. If not provided, a transport will be automatically opened, based on the current default user and the computer of this data node. Passing in the transport can be used for efficiency if a great number of nodes need to be cleaned for the same computer. Note that the user should take care that the correct transport is passed.
Raises:: ValueError – If the hostname of the provided transport does not match that of the node’s computer.

_validate()#

get_authinfo()#

class aiida.orm.RemoteStashData(stash_mode: aiida.common.datastructures.StashMode, **kwargs)#

Bases: aiida.orm.nodes.data.data.Data

Data plugin that models an archived folder on a remote computer.

A stashed folder is essentially an instance of RemoteData that has been archived. Archiving in this context can simply mean copying the content of the folder to another location on the same or another filesystem as long as it is on the same machine. In addition, the folder may have been compressed into a single file for efficiency or even written to tape. The stash_mode attribute will distinguish how the folder was stashed which will allow the implementation to also unstash it and transform it back into a RemoteData such that it can be used as an input for new CalcJobs.

This class is a non-storable base class that merely registers the stash_mode attribute. Only its subclasses, that actually implement a certain stash mode, can be instantiated and therefore stored. The reason for this design is that because the behavior of the class can change significantly based on the mode employed to stash the files and implementing all these variants in the same class will lead to an unintuitive interface where certain properties or methods of the class will only be available or function properly based on the stash_mode.

Initialization

Construct a new instance

Parameters:: stash_mode – the stashing mode with which the data was stashed on the remote.

_storable = False#

property stash_mode: aiida.common.datastructures.StashMode#

Return the mode with which the data was stashed on the remote.

Returns:: the stash mode.

class aiida.orm.RemoteStashFolderData(stash_mode: aiida.common.datastructures.StashMode, target_basepath: str, source_list: List, **kwargs)#

Bases: aiida.orm.nodes.data.remote.stash.base.RemoteStashData

Data plugin that models a folder with files of a completed calculation job that has been stashed through a copy.

This data plugin can and should be used to stash files if and only if the stash mode is StashMode.COPY.

Initialization

Construct a new instance

Parameters:

stash_mode – the stashing mode with which the data was stashed on the remote.
target_basepath – the target basepath.
source_list – the list of source files.

_storable = True#

property target_basepath: str#

Return the target basepath.

Returns:: the target basepath.

property source_list: Union[List, Tuple]#

Return the list of source files that were stashed.

Returns:: the list of source files.

class aiida.orm.SinglefileData(file, filename=None, **kwargs)#

Bases: aiida.orm.nodes.data.data.Data

Data class that can be used to store a single file in its repository.

Initialization

Construct a new instance and set the contents to that of the file.

Parameters:

file – an absolute filepath or filelike object whose contents to copy. Hint: Pass io.BytesIO(b”my string”) to construct the SinglefileData directly from a string.
filename – specify filename to use (defaults to name of provided file).

DEFAULT_FILENAME = 'file.txt'#

property filename#

Return the name of the file stored.

Returns:: the filename under which the file is stored in the repository

open(path=None, mode='r')#

Return an open file handle to the content of this data node.

Parameters:

path – the relative path of the object within the repository.
mode – the mode with which to open the file handle (default: read mode)

Returns:

a file handle

get_content()#

Return the content of the single file stored for this data node.

Returns:: the content of the file as a string

set_file(file, filename=None)#

Store the content of the file in the node’s repository, deleting any other existing objects.

Parameters:

file – an absolute filepath or filelike object whose contents to copy Hint: Pass io.BytesIO(b”my string”) to construct the file directly from a string.
filename – specify filename to use (defaults to name of provided file).

_validate()#: Ensure that there is one object stored in the repository, whose key matches value set for filename attr.

class aiida.orm.Site(**kwargs)#

This class contains the information about a given site of the system.

It can be a single atom, or an alloy, or even contain vacancies.

Initialization

Create a site.

Parameters:

kind_name – a string that identifies the kind (species) of this site. This has to be found in the list of kinds of the StructureData object. Validation will be done at the StructureData level.
position – the absolute position (three floats) in angstrom

get_raw()#

Return the raw version of the site, mapped to a suitable dictionary. This is the format that is actually used to store each site of the structure in the DB.

Returns:: a python dictionary with the site.

get_ase(kinds)#

Return a ase.Atom object for this site.

Parameters:: kinds – the list of kinds from the StructureData object.

Note

If any site is an alloy or has vacancies, a ValueError is raised (from the site.get_ase() routine).

property kind_name#

Return the kind name of this site (a string).

The type of a site is used to decide whether two sites are identical (same mass, symbols, weights, …) or not.

property position#: Return the position of this site in absolute coordinates, in angstrom.

__repr__()#

__str__()#

class aiida.orm.Str(value=None, **kwargs)#

Bases: aiida.orm.nodes.data.base.BaseType

Data sub class to represent a string value.

Initialization

_type = None#

class aiida.orm.StructureData(cell=None, pbc=None, ase=None, pymatgen=None, pymatgen_structure=None, pymatgen_molecule=None, **kwargs)#

Bases: aiida.orm.nodes.data.data.Data

This class contains the information about a given structure, i.e. a collection of sites together with a cell, the boundary conditions (whether they are periodic or not) and other related useful information.

Initialization

Construct a new instance, setting the source attribute if provided as a keyword argument.

_set_incompatibilities = [('ase', 'cell'), ('ase', 'pbc'), ('ase', 'pymatgen'), ('ase', 'pymatgen_molecule'), ('ase', 'pymatg...#

_dimensionality_label = None#

_internal_kind_tags = None#

get_dimensionality()#

Return the dimensionality of the structure and its length/surface/volume.

Zero-dimensional structures are assigned “volume” 0.

Returns:: returns a dictionary with keys “dim” (dimensionality integer), “label” (dimensionality label) and “value” (numerical length/surface/volume).

set_ase(aseatoms)#: Load the structure from a ASE object

set_pymatgen(obj, **kwargs)#: Load the structure from a pymatgen object.

Note

Requires the pymatgen module (version >= 3.0.13, usage of earlier versions may cause errors).

set_pymatgen_molecule(mol, margin=5)#

Load the structure from a pymatgen Molecule object.

Parameters:: margin – the margin to be added in all directions of the bounding box of the molecule.

Note

Requires the pymatgen module (version >= 3.0.13, usage of earlier versions may cause errors).

set_pymatgen_structure(struct)#

Load the structure from a pymatgen Structure object.

Note

periodic boundary conditions are set to True in all three directions.

Note

Requires the pymatgen module (version >= 3.3.5, usage of earlier versions may cause errors).

Raises:: ValueError – if there are partial occupancies together with spins.

_validate()#: Performs some standard validation tests.

_prepare_xsf(main_file_name='')#: Write the given structure to a string of format XSF (for XCrySDen).

_prepare_cif(main_file_name='')#: Write the given structure to a string of format CIF.

_prepare_chemdoodle(main_file_name='')#: Write the given structure to a string of format required by ChemDoodle.

_prepare_xyz(main_file_name='')#: Write the given structure to a string of format XYZ.

_parse_xyz(inputstring)#: Read the structure from a string of format XYZ.

_adjust_default_cell(vacuum_factor=1.0, vacuum_addition=10.0, pbc=(False, False, False))#: If the structure was imported from an xyz file, it lacks a cell. This method will adjust the cell

get_description()#

Returns a string with infos retrieved from StructureData node’s properties

Parameters:: self – the StructureData node
Returns:: retsrt: the description string

get_symbols_set()#

Return a set containing the names of all elements involved in this structure (i.e., for it joins the list of symbols for each kind k in the structure).

Returns:: a set of strings of element names.

get_formula(mode='hill', separator='')#

Return a string with the chemical formula.

Parameters:

mode –
a string to specify how to generate the formula, can assume one of the following values:
- ’hill’ (default): count the number of atoms of each species, then use Hill notation, i.e. alphabetical order with C and H first if one or several C atom(s) is (are) present, e.g. ['C','H','H','H','O','C','H','H','H'] will return 'C2H6O' ['S','O','O','H','O','H','O'] will return 'H2O4S' From E. A. Hill, J. Am. Chem. Soc., 22 (8), pp 478–494 (1900)
- ’hill_compact’: same as hill but the number of atoms for each species is divided by the greatest common divisor of all of them, e.g. ['C','H','H','H','O','C','H','H','H','O','O','O'] will return 'CH3O2'
- ’reduce’: group repeated symbols e.g. ['Ba', 'Ti', 'O', 'O', 'O', 'Ba', 'Ti', 'O', 'O', 'O', 'Ba', 'Ti', 'Ti', 'O', 'O', 'O'] will return 'BaTiO3BaTiO3BaTi2O3'
- ’group’: will try to group as much as possible parts of the formula e.g. ['Ba', 'Ti', 'O', 'O', 'O', 'Ba', 'Ti', 'O', 'O', 'O', 'Ba', 'Ti', 'Ti', 'O', 'O', 'O'] will return '(BaTiO3)2BaTi2O3'
- ’count’: same as hill (i.e. one just counts the number of atoms of each species) without the re-ordering (take the order of the atomic sites), e.g. ['Ba', 'Ti', 'O', 'O', 'O','Ba', 'Ti', 'O', 'O', 'O'] will return 'Ba2Ti2O6'
- ’count_compact’: same as count but the number of atoms for each species is divided by the greatest common divisor of all of them, e.g. ['Ba', 'Ti', 'O', 'O', 'O','Ba', 'Ti', 'O', 'O', 'O'] will return 'BaTiO3'
separator – a string used to concatenate symbols. Default empty.

Returns:

a string with the formula

Note

in modes reduce, group, count and count_compact, the initial order in which the atoms were appended by the user is used to group and/or order the symbols in the formula

get_site_kindnames()#

Return a list with length equal to the number of sites of this structure, where each element of the list is the kind name of the corresponding site.

Note

This is NOT necessarily a list of chemical symbols! Use [ self.get_kind(s.kind_name).get_symbols_string() for s in self.sites] for chemical symbols

Returns:: a list of strings

get_composition()#

Returns the chemical composition of this structure as a dictionary, where each key is the kind symbol (e.g. H, Li, Ba), and each value is the number of occurences of that element in this structure. For BaZrO3 it would return {‘Ba’:1, ‘Zr’:1, ‘O’:3}. No reduction with smallest common divisor!

Returns:: a dictionary with the composition

get_ase()#

Get the ASE object. Requires to be able to import ase.

Returns:: an ASE object corresponding to this StructureData object.

Note

If any site is an alloy or has vacancies, a ValueError is raised (from the site.get_ase() routine).

get_pymatgen(**kwargs)#

Get pymatgen object. Returns Structure for structures with periodic boundary conditions (in three dimensions) and Molecule otherwise. :param add_spin: True to add the spins to the pymatgen structure. Default is False (no spin added).

Note

The spins are set according to the following rule:

if the kind name ends with 1 -> spin=+1
if the kind name ends with 2 -> spin=-1

Note

Requires the pymatgen module (version >= 3.0.13, usage of earlier versions may cause errors).

get_pymatgen_structure(**kwargs)#

Get the pymatgen Structure object. :param add_spin: True to add the spins to the pymatgen structure. Default is False (no spin added).

Note

The spins are set according to the following rule:

if the kind name ends with 1 -> spin=+1
if the kind name ends with 2 -> spin=-1

Note

Requires the pymatgen module (version >= 3.0.13, usage of earlier versions may cause errors).

Returns:: a pymatgen Structure object corresponding to this StructureData object.
Raises:: ValueError – if periodic boundary conditions do not hold in at least one dimension of real space.

get_pymatgen_molecule()#

Get the pymatgen Molecule object.

Note

Requires the pymatgen module (version >= 3.0.13, usage of earlier versions may cause errors).

Returns:: a pymatgen Molecule object corresponding to this StructureData object.

append_kind(kind)#

Append a kind to the StructureData. It makes a copy of the kind.

Parameters:: kind – the site to append, must be a Kind object.

append_site(site)#

Append a site to the StructureData. It makes a copy of the site.

Parameters:: site – the site to append. It must be a Site object.

append_atom(**kwargs)#

Append an atom to the Structure, taking care of creating the corresponding kind.

Parameters:

ase – the ase Atom object from which we want to create a new atom (if present, this must be the only parameter)
position – the position of the atom (three numbers in angstrom)
symbols – passed to the constructor of the Kind object.
weights – passed to the constructor of the Kind object.
name – passed to the constructor of the Kind object. See also the note below.

Note

Note on the ‘name’ parameter (that is, the name of the kind):

if specified, no checks are done on existing species. Simply, a new kind with that name is created. If there is a name clash, a check is done: if the kinds are identical, no error is issued; otherwise, an error is issued because you are trying to store two different kinds with the same name.
if not specified, the name is automatically generated. Before adding the kind, a check is done. If other species with the same properties already exist, no new kinds are created, but the site is added to the existing (identical) kind. (Actually, the first kind that is encountered). Otherwise, the name is made unique first, by adding to the string containing the list of chemical symbols a number starting from 1, until an unique name is found

Note

checks of equality of species are done using the compare_with() method.

clear_kinds()#: Removes all kinds for the StructureData object.

Note

Also clear all sites!

clear_sites()#: Removes all sites for the StructureData object.

property sites#: Returns a list of sites.

property kinds#: Returns a list of kinds.

get_kind(kind_name)#

Return the kind object associated with the given kind name.

Parameters:: kind_name – String, the name of the kind you want to get
Returns:: The Kind object associated with the given kind_name, if a Kind with the given name is present in the structure.
Raise:: ValueError if the kind_name is not present.

get_kind_names()#

Return a list of kind names (in the same order of the self.kinds property, but return the names rather than Kind objects)

Note

This is NOT necessarily a list of chemical symbols! Use get_symbols_set for chemical symbols

Returns:: a list of strings.

property cell#

Returns the cell shape.

Returns:: a 3x3 list of lists.

set_cell(value)#: Set the cell.

reset_cell(new_cell)#

Reset the cell of a structure not yet stored to a new value.

Parameters:: new_cell – list specifying the cell vectors
Raises:: ModificationNotAllowed: if object is already stored

reset_sites_positions(new_positions, conserve_particle=True)#

Replace all the Site positions attached to the Structure

Parameters:

new_positions – list of (3D) positions for every sites.
conserve_particle – if True, allows the possibility of removing a site. currently not implemented.

Raises:

aiida.common.ModificationNotAllowed – if object is stored already
ValueError – if positions are invalid

Note

it is assumed that the order of the new_positions is given in the same order of the one it’s substituting, i.e. the kind of the site will not be checked.

property pbc#

Get the periodic boundary conditions.

Returns:: a tuple of three booleans, each one tells if there are periodic boundary conditions for the i-th real-space direction (i=1,2,3)

set_pbc(value)#: Set the periodic boundary conditions.

property cell_lengths#: Get the lengths of cell lattice vectors in angstroms.

abstract set_cell_lengths(value)#

property cell_angles#: Get the angles between the cell lattice vectors in degrees.

abstract set_cell_angles(value)#

property is_alloy#

Return whether the structure contains any alloy kinds.

Returns:: a boolean, True if at least one kind is an alloy

property has_vacancies#

Return whether the structure has vacancies in the structure.

Returns:: a boolean, True if at least one kind has a vacancy

get_cell_volume()#

Returns the three-dimensional cell volume in Angstrom^3.

Use the get_dimensionality method in order to get the area/length of lower-dimensional cells.

Returns:: a float.

get_cif(converter='ase', store=False, **kwargs)#

Creates aiida.orm.nodes.data.cif.CifData.

New in version 1.0: Renamed from _get_cif

Parameters:

converter – specify the converter. Default ‘ase’.
store – If True, intermediate calculation gets stored in the AiiDA database for record. Default False.

Returns:

aiida.orm.nodes.data.cif.CifData node.

_get_object_phonopyatoms()#

Converts StructureData to PhonopyAtoms

Returns:: a PhonopyAtoms object

_get_object_ase()#

Converts StructureData to ase.Atoms

Returns:: an ase.Atoms object

_get_object_pymatgen(**kwargs)#

Converts StructureData to pymatgen object

Returns:: a pymatgen Structure for structures with periodic boundary conditions (in three dimensions) and Molecule otherwise

Note

Requires the pymatgen module (version >= 3.0.13, usage of earlier versions may cause errors).

_get_object_pymatgen_structure(**kwargs)#

Converts StructureData to pymatgen Structure object :param add_spin: True to add the spins to the pymatgen structure. Default is False (no spin added).

Note

The spins are set according to the following rule:

if the kind name ends with 1 -> spin=+1
if the kind name ends with 2 -> spin=-1

Returns:: a pymatgen Structure object corresponding to this StructureData object
Raises:: ValueError – if periodic boundary conditions does not hold in at least one dimension of real space; if there are partial occupancies together with spins (defined by kind names ending with ‘1’ or ‘2’).

Note

Requires the pymatgen module (version >= 3.0.13, usage of earlier versions may cause errors)

_get_object_pymatgen_molecule(**kwargs)#

Converts StructureData to pymatgen Molecule object

Returns:: a pymatgen Molecule object corresponding to this StructureData object.

Note

Requires the pymatgen module (version >= 3.0.13, usage of earlier versions may cause errors)

class aiida.orm.TrajectoryData(structurelist=None, **kwargs)#

Bases: aiida.orm.nodes.data.array.array.ArrayData

Stores a trajectory (a sequence of crystal structures with timestamps, and possibly with velocities).

Initialization

_internal_validate(stepids, cells, symbols, positions, times, velocities)#: Internal function to validate the type and shape of the arrays. See the documentation of py:meth:.set_trajectory for a description of the valid shape and type of the parameters.

set_trajectory(symbols, positions, stepids=None, cells=None, times=None, velocities=None)#

Store the whole trajectory, after checking that types and dimensions are correct.

Parameters stepids, cells and velocities are optional variables. If nothing is passed for cells or velocities nothing will be stored. However, if no input is given for stepids a consecutive sequence [0,1,2,…,len(positions)-1] will be assumed.

Parameters:

symbols – string list with dimension n, where n is the number of atoms (i.e., sites) in the structure. The same list is used for each step. Normally, the string should be a valid chemical symbol, but actually any unique string works and can be used as the name of the atomic kind (see also the get_step_structure() method).
positions – float array with dimension \(s \times n \times 3\), where s is the length of the stepids array and n is the length of the symbols array. Units are angstrom. In particular, positions[i,j,k] is the k-th component of the j-th atom (or site) in the structure at the time step with index i (identified by step number step[i] and with timestamp times[i]).
stepids – integer array with dimension s, where s is the number of steps. Typically represents an internal counter within the code. For instance, if you want to store a trajectory with one step every 10, starting from step 65, the array will be [65,75,85,...]. No checks are done on duplicate elements or on the ordering, but anyway this array should be sorted in ascending order, without duplicate elements. (If not specified, stepids will be set to numpy.arange(s) by default) It is internally stored as an array named ‘steps’.
cells – if specified float array with dimension \(s \times 3 \times 3\), where s is the length of the stepids array. Units are angstrom. In particular, cells[i,j,k] is the k-th component of the j-th cell vector at the time step with index i (identified by step number stepid[i] and with timestamp times[i]).
times – if specified, float array with dimension s, where s is the length of the stepids array. Contains the timestamp of each step in picoseconds (ps).
velocities – if specified, must be a float array with the same dimensions of the positions array. The array contains the velocities in the atoms.

set_structurelist(structurelist)#

Create trajectory from the list of aiida.orm.nodes.data.structure.StructureData instances.

Parameters:: structurelist – a list of aiida.orm.nodes.data.structure.StructureData instances.
Raises:: ValueError – if symbol lists of supplied structures are different

_validate()#: Verify that the required arrays are present and that their type and dimension are correct.

property numsteps#: Return the number of stored steps, or zero if nothing has been stored yet.

property numsites#: Return the number of stored sites, or zero if nothing has been stored yet.

get_stepids()#

Return the array of steps, if it has already been set.

New in version 0.7: Renamed from get_steps

Raises:: KeyError – if the trajectory has not been set yet.

get_times()#

Return the array of times (in ps), if it has already been set.

Raises:: KeyError – if the trajectory has not been set yet.

get_cells()#

Return the array of cells, if it has already been set.

Raises:: KeyError – if the trajectory has not been set yet.

property symbols#

Return the array of symbols, if it has already been set.

Raises:: KeyError – if the trajectory has not been set yet.

get_positions()#

Return the array of positions, if it has already been set.

Raises:: KeyError – if the trajectory has not been set yet.

get_velocities()#: Return the array of velocities, if it has already been set.

Note

This function (differently from all other get_* functions, will not raise an exception if the velocities are not set, but rather return None (both if no trajectory was not set yet, and if it the trajectory was set but no velocities were specified).

get_index_from_stepid(stepid)#

Given a value for the stepid (i.e., a value among those of the steps array), return the array index of that stepid, that can be used in other methods such as get_step_data() or get_step_structure().

New in version 0.7: Renamed from get_step_index

Note

Note that this function returns the first index found (i.e. if multiple steps are present with the same value, only the index of the first one is returned).

Raises:: ValueError – if no step with the given value is found.

get_step_data(index)#

Return a tuple with all information concerning the stepid with given index (0 is the first step, 1 the second step and so on). If you know only the step value, use the get_index_from_stepid() method to get the corresponding index.

If no velocities, cells, or times were specified, None is returned as the corresponding element.

Returns:

A tuple in the format (stepid, time, cell, symbols, positions, velocities), where stepid is an integer, time is a float, cell is a \(3 imes 3\) matrix, symbols is an array of length n, positions is a \(n imes 3\) array, and velocities is either None or a \(n imes 3\) array

Parameters:

index – The index of the step that you want to retrieve, from 0 to self.numsteps - 1.

Raises:

IndexError – if you require an index beyond the limits.
KeyError – if you did not store the trajectory yet.

get_step_structure(index, custom_kinds=None)#

Return an AiiDA aiida.orm.nodes.data.structure.StructureData node (not stored yet!) with the coordinates of the given step, identified by its index. If you know only the step value, use the get_index_from_stepid() method to get the corresponding index.

Note

The periodic boundary conditions are always set to True.

New in version 0.7: Renamed from step_to_structure

Parameters:

index – The index of the step that you want to retrieve, from 0 to self.numsteps- 1.
custom_kinds – (Optional) If passed must be a list of aiida.orm.nodes.data.structure.Kind objects. There must be one kind object for each different string in the symbols array, with kind.name set to this string. If this parameter is omitted, the automatic kind generation of AiiDA aiida.orm.nodes.data.structure.StructureData nodes is used, meaning that the strings in the symbols array must be valid chemical symbols.

Returns:

aiida.orm.nodes.data.structure.StructureData node.

_prepare_xsf(index=None, main_file_name='')#: Write the given trajectory to a string of format XSF (for XCrySDen).

_prepare_cif(trajectory_index=None, main_file_name='')#: Write the given trajectory to a string of format CIF.

get_structure(store=False, **kwargs)#

Creates aiida.orm.nodes.data.structure.StructureData.

New in version 1.0: Renamed from _get_aiida_structure

Parameters:

store – If True, intermediate calculation gets stored in the AiiDA database for record. Default False.
index – The index of the step that you want to retrieve, from 0 to self.numsteps- 1.
custom_kinds – (Optional) If passed must be a list of aiida.orm.nodes.data.structure.Kind objects. There must be one kind object for each different string in the symbols array, with kind.name set to this string. If this parameter is omitted, the automatic kind generation of AiiDA aiida.orm.nodes.data.structure.StructureData nodes is used, meaning that the strings in the symbols array must be valid chemical symbols.
custom_cell – (Optional) The cell matrix of the structure. If omitted, the cell will be read from the trajectory, if present, otherwise the default cell of aiida.orm.nodes.data.structure.StructureData will be used.

Returns:

aiida.orm.nodes.data.structure.StructureData node.

get_cif(index=None, **kwargs)#: Creates aiida.orm.nodes.data.cif.CifData

New in version 1.0: Renamed from _get_cif

_parse_xyz_pos(inputstring)#

Load positions from a XYZ file.

Note

The steps and symbols must be set manually before calling this import function as a consistency measure. Even though the symbols and steps could be extracted from the XYZ file, the data present in the XYZ file may or may not be correct and the same logic would have to be present in the XYZ-velocities function. It was therefore decided not to implement it at all but require it to be set explicitly.

Usage:

from aiida.orm.nodes.data.array.trajectory import TrajectoryData

t = TrajectoryData()
# get sites and number of timesteps
t.set_array('steps', arange(ntimesteps))
t.set_array('symbols', array([site.kind for site in s.sites]))
t.importfile('some-calc/AIIDA-PROJECT-pos-1.xyz', 'xyz_pos')

_parse_xyz_vel(inputstring)#: Load velocities from a XYZ file.

Note

The steps and symbols must be set manually before calling this import function as a consistency measure. See also comment for _parse_xyz_pos()

show_mpl_pos(**kwargs)#

Shows the positions as a function of time, separate for XYZ coordinates

Parameters:

stepsize (int) – The stepsize for the trajectory, set higher than 1 to reduce number of points
mintime (int) – Time to start from
maxtime (int) – Maximum time
elements (list) – A list of atomic symbols that should be displayed. If not specified, all atoms are displayed.
indices (list) – A list of indices of that atoms that can be displayed. If not specified, all atoms of the correct species are displayed.
dont_block (bool) – If True, interpreter is not blocked when figure is displayed.

show_mpl_heatmap(**kwargs)#: Show a heatmap of the trajectory with matplotlib.

class aiida.orm.UpfData#

Bases: aiida.orm.nodes.data.singlefile.SinglefileData

Data sub class to represent a pseudopotential single file in UPF format.

classmethod get_or_create(filepath, use_first=False, store_upf=True)#

Get the UpfData with the same md5 of the given file, or create it if it does not yet exist.

Parameters:

filepath – an absolute filepath on disk
use_first – if False (default), raise an exception if more than one potential is found. If it is True, instead, use the first available pseudopotential.
store_upf – boolean, if false, the UpfData if created will not be stored.

Returns:

tuple of UpfData and boolean indicating whether it was created.

store(*args, **kwargs)#: Store the node, reparsing the file so that the md5 and the element are correctly reset.

classmethod from_md5(md5, backend=None)#

Return a list of all UpfData that match the given md5 hash.

Note

assumes hash of stored UpfData nodes is stored in the md5 attribute

Parameters:: md5 – the file hash
Returns:: list of existing UpfData nodes that have the same md5 hash

set_file(file, filename=None)#

Store the file in the repository and parse it to set the element and md5 attributes.

Parameters:

file – filepath or filelike object of the UPF potential file to store. Hint: Pass io.BytesIO(b”my string”) to construct the file directly from a string.
filename – specify filename to use (defaults to name of provided file).

get_upf_family_names()#: Get the list of all upf family names to which the pseudo belongs.

property element#

Return the element of the UPF pseudopotential.

Returns:: the element

property md5sum#

Return the md5 checksum of the UPF pseudopotential file.

Returns:: the md5 checksum

_validate()#: Validate the UPF potential file stored for this node.

_prepare_upf(main_file_name='')#: Return UPF content.

classmethod get_upf_group(group_label)#

Return the UPF family group with the given label.

Parameters:: group_label – the family group label
Returns:: the Group with the given label, if it exists

classmethod get_upf_groups(filter_elements=None, user=None, backend=None)#

Return all names of groups of type UpfFamily, possibly with some filters.

Parameters:

filter_elements – A string or a list of strings. If present, returns only the groups that contains one UPF for every element present in the list. The default is None, meaning that all families are returned.
user – if None (default), return the groups for all users. If defined, it should be either a User instance or the user email.

Returns:

list of Group entities of type UPF.

_prepare_json(main_file_name='')#: Returns UPF PP in json format.

class aiida.orm.UpfFamily(label: Optional[str] = None, user: Optional[aiida.orm.User] = None, description: str = '', type_string: Optional[str] = None, backend: Optional[aiida.orm.implementation.StorageBackend] = None)#

Bases: aiida.orm.groups.Group

Group that represents a pseudo potential family containing UpfData nodes.

Initialization

Create a new group. Either pass a dbgroup parameter, to reload a group from the DB (and then, no further parameters are allowed), or pass the parameters for the Group creation.

Parameters:

label – The group label, required on creation
description – The group description (by default, an empty string)
user – The owner of the group (by default, the automatic user)
type_string – a string identifying the type of group (by default, an empty string, indicating an user-defined group.

class aiida.orm.User(email: str, first_name: str = '', last_name: str = '', institution: str = '', backend: Optional[aiida.orm.implementation.StorageBackend] = None)#

Bases: aiida.orm.entities.Entity[aiida.orm.implementation.BackendUser, aiida.orm.users.UserCollection]

AiiDA User

Initialization

Create a new User.

_CLS_COLLECTION = None#

__str__() → str#

static normalize_email(email: str) → str#: Normalize the address by lowercasing the domain part of the email address (taken from Django).

property email: str#

property first_name: str#

property last_name: str#

property institution: str#

get_full_name() → str#

Return the user full name

Returns:: the user full name

get_short_name() → str#

Return the user short name (typically, this returns the email)

Returns:: The short name

property uuid: None#: For now users do not have UUIDs so always return None

class aiida.orm.WorkChainNode#

Bases: aiida.orm.nodes.process.workflow.workflow.WorkflowNode

ORM class for all nodes representing the execution of a WorkChain.

STEPPER_STATE_INFO_KEY = 'stepper_state_info'#

_updatable_attributes() → Tuple[str, ...]#

property stepper_state_info: Optional[str]#

Return the stepper state info

Returns:: string representation of the stepper state info

set_stepper_state_info(stepper_state_info: str) → None#

Set the stepper state info

Parameters:: state – string representation of the stepper state info

class aiida.orm.WorkFunctionNode#

Bases: aiida.orm.utils.mixins.FunctionCalculationMixin, aiida.orm.nodes.process.workflow.workflow.WorkflowNode

ORM class for all nodes representing the execution of a workfunction.

_CLS_NODE_LINKS = None#

class aiida.orm.WorkflowNode(backend: Optional[aiida.orm.implementation.StorageBackend] = None, user: Optional[aiida.orm.users.User] = None, computer: Optional[aiida.orm.computers.Computer] = None, **kwargs: Any)#

Bases: aiida.orm.nodes.process.process.ProcessNode

Base class for all nodes representing the execution of a workflow process.

Initialization

Parameters:: backend_entity – the backend model supporting this entity

_CLS_NODE_LINKS = None#

_storable = True#

_unstorable_message = 'storing for this node has been disabled'#

property inputs: aiida.orm.utils.managers.NodeLinksManager#

Return an instance of NodeLinksManager to manage incoming INPUT_WORK links

The returned Manager allows you to easily explore the nodes connected to this node via an incoming INPUT_WORK link. The incoming nodes are reachable by their link labels which are attributes of the manager.

Returns:: NodeLinksManager

property outputs: aiida.orm.utils.managers.NodeLinksManager#

Return an instance of NodeLinksManager to manage outgoing RETURN links

The returned Manager allows you to easily explore the nodes connected to this node via an outgoing RETURN link. The outgoing nodes are reachable by their link labels which are attributes of the manager.

Returns:: NodeLinksManager

class aiida.orm.XyData(*args, source=None, **kwargs)#

Bases: aiida.orm.nodes.data.array.array.ArrayData

A subclass designed to handle arrays that have an “XY” relationship to each other. That is there is one array, the X array, and there are several Y arrays, which can be considered functions of X.

Initialization

Construct a new instance, setting the source attribute if provided as a keyword argument.

static _arrayandname_validator(array, name, units)#: Validates that the array is an numpy.ndarray and that the name is of type str. Raises TypeError or ValueError if this not the case.

set_x(x_array, x_name, x_units)#

Sets the array and the name for the x values.

Parameters:

x_array – A numpy.ndarray, containing only floats
x_name – a string for the x array name
x_units – the units of x

set_y(y_arrays, y_names, y_units)#: Set array(s) for the y part of the dataset. Also checks if the x_array has already been set, and that, the shape of the y_arrays agree with the x_array. :param y_arrays: A list of y_arrays, numpy.ndarray :param y_names: A list of strings giving the names of the y_arrays :param y_units: A list of strings giving the units of the y_arrays

get_x()#: Tries to retrieve the x array and x name raises a NotExistent exception if no x array has been set yet. :return x_name: the name set for the x_array :return x_array: the x array set earlier :return x_units: the x units set earlier

get_y()#: Tries to retrieve the y arrays and the y names, raises a NotExistent exception if they have not been set yet, or cannot be retrieved :return y_names: list of strings naming the y_arrays :return y_arrays: list of y_arrays :return y_units: list of strings giving the units for the y_arrays

aiida.orm.cif_from_ase(ase, full_occupancies=False, add_fake_biso=False)#

Construct a CIF datablock from the ASE structure. The code is taken from https://wiki.fysik.dtu.dk/ase/ase/io/formatoptions.html#ase.io.cif.write_cif, as the original ASE code contains a bug in printing the Hermann-Mauguin symmetry space group symbol.

Parameters:: ase – ASE “images”
Returns:: array of CIF datablocks

aiida.orm.find_bandgap(bandsdata, number_electrons=None, fermi_energy=None)#

Tries to guess whether the bandsdata represent an insulator. This method is meant to be used only for electronic bands (not phonons) By default, it will try to use the occupations to guess the number of electrons and find the Fermi Energy, otherwise, it can be provided explicitely. Also, there is an implicit assumption that the kpoints grid is “sufficiently” dense, so that the bandsdata are not missing the intersection between valence and conduction band if present. Use this function with care!

Parameters:

number_electrons – (optional, float) number of electrons in the unit cell
fermi_energy – (optional, float) value of the fermi energy.

Note:

By default, the algorithm uses the occupations array to guess the number of electrons and the occupied bands. This is to be used with care, because the occupations could be smeared so at a non-zero temperature, with the unwanted effect that the conduction bands might be occupied in an insulator. Prefer to pass the number_of_electrons explicitly

Note:

Only one between number_electrons and fermi_energy can be specified at the same time.

Returns:

(is_insulator, gap), where is_insulator is a boolean, and gap a float. The gap is None in case of a metal, zero when the homo is equal to the lumo (e.g. in semi-metals).

aiida.orm.get_loader(orm_class)#

Return the correct OrmEntityLoader for the given orm class.

Parameters:: orm_class – the orm class
Returns:: a subclass of OrmEntityLoader
Raises:: ValueError – if no OrmEntityLoader subclass can be found for the given orm class

aiida.orm.get_query_type_from_type_string(type_string)#

Take the type string of a Node and create the queryable type string

Parameters:: type_string – the plugin_type_string attribute of a Node
Returns:: the type string that can be used to query for

aiida.orm.get_type_string_from_class(class_module, class_name)#

Given the module and name of a class, determine the orm_class_type string, which codifies the orm class that is to be used. The returned string will always have a terminating period, which is required to query for the string in the database

Parameters:

class_module – module of the class
class_name – name of the class

aiida.orm.has_pycifrw()#

Returns:: True if the PyCifRW module can be imported, False otherwise.

aiida.orm.load_code(identifier=None, pk=None, uuid=None, label=None, sub_classes=None, query_with_dashes=True) → aiida.orm.Code#

Load a Code instance by one of its identifiers: pk, uuid or label

If the type of the identifier is unknown simply pass it without a keyword and the loader will attempt to automatically infer the type.

Parameters:

identifier – pk (integer), uuid (string) or label (string) of a Code
pk – pk of a Code
uuid – uuid of a Code, or the beginning of the uuid
label – label of a Code
sub_classes – an optional tuple of orm classes to narrow the queryset. Each class should be a strict sub class of the ORM class of the given entity loader.
query_with_dashes (bool) – allow to query for a uuid with dashes

Returns:

the Code instance

Raises:

ValueError – if none or more than one of the identifiers are supplied
TypeError – if the provided identifier has the wrong type
aiida.common.NotExistent – if no matching Code is found
aiida.common.MultipleObjectsError – if more than one Code was found

aiida.orm.load_computer(identifier=None, pk=None, uuid=None, label=None, sub_classes=None, query_with_dashes=True) → aiida.orm.Computer#

Load a Computer instance by one of its identifiers: pk, uuid or label

If the type of the identifier is unknown simply pass it without a keyword and the loader will attempt to automatically infer the type.

Parameters:

identifier – pk (integer), uuid (string) or label (string) of a Computer
pk – pk of a Computer
uuid – uuid of a Computer, or the beginning of the uuid
label – label of a Computer
sub_classes – an optional tuple of orm classes to narrow the queryset. Each class should be a strict sub class of the ORM class of the given entity loader.
query_with_dashes (bool) – allow to query for a uuid with dashes

Returns:

the Computer instance

Raises:

ValueError – if none or more than one of the identifiers are supplied
TypeError – if the provided identifier has the wrong type
aiida.common.NotExistent – if no matching Computer is found
aiida.common.MultipleObjectsError – if more than one Computer was found

aiida.orm.load_entity(entity_loader=None, identifier=None, pk=None, uuid=None, label=None, sub_classes=None, query_with_dashes=True)#

Load an entity instance by one of its identifiers: pk, uuid or label

If the type of the identifier is unknown simply pass it without a keyword and the loader will attempt to automatically infer the type.

Parameters:

identifier – pk (integer), uuid (string) or label (string) of a Code
pk – pk of a Code
uuid – uuid of a Code, or the beginning of the uuid
label – label of a Code
sub_classes – an optional tuple of orm classes to narrow the queryset. Each class should be a strict sub class of the ORM class of the given entity loader.
query_with_dashes (bool) – allow to query for a uuid with dashes

Returns:

the Code instance

Raises:

ValueError – if none or more than one of the identifiers are supplied
TypeError – if the provided identifier has the wrong type
aiida.common.NotExistent – if no matching Code is found
aiida.common.MultipleObjectsError – if more than one Code was found

aiida.orm.load_group(identifier=None, pk=None, uuid=None, label=None, sub_classes=None, query_with_dashes=True) → aiida.orm.Group#

Load a Group instance by one of its identifiers: pk, uuid or label

If the type of the identifier is unknown simply pass it without a keyword and the loader will attempt to automatically infer the type.

Parameters:

identifier – pk (integer), uuid (string) or label (string) of a Group
pk – pk of a Group
uuid – uuid of a Group, or the beginning of the uuid
label – label of a Group
sub_classes – an optional tuple of orm classes to narrow the queryset. Each class should be a strict sub class of the ORM class of the given entity loader.
query_with_dashes (bool) – allow to query for a uuid with dashes

Returns:

the Group instance

Raises:

ValueError – if none or more than one of the identifiers are supplied
TypeError – if the provided identifier has the wrong type
aiida.common.NotExistent – if no matching Group is found
aiida.common.MultipleObjectsError – if more than one Group was found

aiida.orm.load_node(identifier=None, pk=None, uuid=None, label=None, sub_classes=None, query_with_dashes=True) → aiida.orm.Node#

Load a node by one of its identifiers: pk or uuid. If the type of the identifier is unknown simply pass it without a keyword and the loader will attempt to infer the type

Parameters:

identifier – pk (integer) or uuid (string)
pk – pk of a node
uuid – uuid of a node, or the beginning of the uuid
label – label of a Node
sub_classes – an optional tuple of orm classes to narrow the queryset. Each class should be a strict sub class of the ORM class of the given entity loader.
query_with_dashes (bool) – allow to query for a uuid with dashes

Returns:

the node instance

Raises:

ValueError – if none or more than one of the identifiers are supplied
TypeError – if the provided identifier has the wrong type
aiida.common.NotExistent – if no matching Node is found
aiida.common.MultipleObjectsError – if more than one Node was found

aiida.orm.load_node_class(type_string)#

Return the Node sub class that corresponds to the given type string.

Parameters:: type_string – the type string of the node
Returns:: a sub class of Node

aiida.orm.pycifrw_from_cif(datablocks, loops=None, names=None)#

Constructs PyCifRW’s CifFile from an array of CIF datablocks.

Parameters:

datablocks – an array of CIF datablocks
loops – optional dict of lists of CIF tag loops.
names – optional list of datablock names

Returns:

CifFile

aiida.orm.to_aiida_type(value)#: Turns basic Python types (str, int, float, bool) into the corresponding AiiDA types.

aiida.orm.validate_link(source: aiida.orm.Node, target: aiida.orm.Node, link_type: aiida.common.links.LinkType, link_label: str, backend: Optional[aiida.orm.implementation.storage_backend.StorageBackend] = None) → None#

Validate adding a link of the given type and label from a given node to ourself.

This function will first validate the class types of the inputs and will subsequently validate whether a link of the specified type is allowed at all between the nodes types of the source and target.

Subsequently, the validity of the “indegree” and “outdegree” of the proposed link is validated, which means validating that the uniqueness constraints of the incoming links into the target node and the outgoing links from the source node are not violated. In AiiDA’s provenance graph each link type has one of the following three types of “degree” character:

* unique
* unique pair
* unique triple

Each degree character has a different unique constraint on its links, here defined for the indegree:

* unique: any target node, it can only have a single incoming link of this type, regardless of the link label.
* unique pair: a node can have an infinite amount of incoming links of this type, as long as the labels within
    that sub set, are unique. In short, it is the link pair, i.e. the tuple of the link type and label, that has
    a uniquess constraint for the incoming links to a given node.
* unique triple: a node can have an infinite amount of incoming links of this type, as long as the triple tuple
    of source node, link type and link label is unique. In other words, it is the link triple that has a
    uniqueness constraint for the incoming links.

The same holds for outdegree, but then it concerns outgoing links from the source node to the target node.

For illustration purposes, consider the following example provenance graphs that are considered legal, where WN, DN and CN represent a WorkflowNode, a DataNode and a CalculationNode, respectively:

         1                    2                    3
 ______     ______          ______          ______     ______
|      |   |      |        |      |        |      |   |      |
|  WN  |   |  DN  |        |  DN  |        |  WN  |   |  WN  |
|______|   |______|        |______|        |______|   |______|
     |     /                |   |               |     /
   a |    / a             a |   | b           a |    / a
    _|___/                  |___|_             _|___/
   |      |                |      |           |      |
   |  CN  |                |  CN  |           |  DN  |
   |______|                |______|           |______|

In example 1, the link uniqueness constraint is not violated because despite the labels having the same label a, their link types, CALL_CALC and INPUT_CALC, respectively, are different and their unique_pair indegree is not violated.

Similarly, in the second example, the constraint is not violated, because despite both links having the same link type INPUT_CALC, the have different labels, so the unique_pair indegree of the INPUT_CALC is not violated.

Finally, in the third example, we see two WorkflowNodes both returning the same DataNode and with the same label. Despite the two incoming links here having both the same type as well as the same label, the uniqueness constraint is not violated, because the indegree for RETURN links is unique_triple which means that the triple of source node and link type and label should be unique.

Parameters:

source – the node from which the link is coming
target – the node to which the link is going
link_type – the type of link
link_label – link label

Raises:

TypeError – if source or target is not a Node instance, or link_type is not a LinkType enum
ValueError – if the proposed link is invalid

aiida.orm#

Package Contents#

Classes#

Functions#

Data#

API#

`aiida.orm`#