ORM documentation: generic aiida.orm

Some generic methods of the module aiida.orm.utils

Utilities related to the ORM.

aiida.orm.utils.load_code(identifier=None, pk=None, uuid=None, label=None, sub_classes=None, query_with_dashes=True)[source]

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:
aiida.orm.utils.load_computer(identifier=None, pk=None, uuid=None, label=None, sub_classes=None, query_with_dashes=True)[source]

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:
aiida.orm.utils.load_group(identifier=None, pk=None, uuid=None, label=None, sub_classes=None, query_with_dashes=True)[source]

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:
aiida.orm.utils.load_node(identifier=None, pk=None, uuid=None, label=None, sub_classes=None, query_with_dashes=True)[source]

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:

Computer

Module for Computer entities

class aiida.orm.computers.Computer(name, hostname, description='', transport_type='', scheduler_type='', workdir=None, backend=None)[source]

Base class to map a node in the DB + its permanent repository counterpart.

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) metadata 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.

class Collection(backend, entity_class)[source]

The collection of Computer entries.

delete(id)[source]

Delete the computer with the given id

list_names()[source]

Return a list with all the names of the computers in the DB.

classmethod _append_text_validator(append_text)[source]

Validates the append text string.

classmethod _default_mpiprocs_per_machine_validator(def_cpus_per_machine)[source]

Validates the default number of CPUs per machine (node)

classmethod _description_validator(description)[source]

Validates the description.

classmethod _hostname_validator(hostname)[source]

Validates the hostname.

_mpirun_command_validator(mpirun_cmd)[source]

Validates the mpirun_command variable. MUST be called after properly checking for a valid scheduler.

classmethod _name_validator(name)[source]

Validates the name.

classmethod _prepend_text_validator(prepend_text)[source]

Validates the prepend text string.

classmethod _scheduler_type_validator(scheduler_type)[source]

Validates the transport string.

classmethod _transport_type_validator(transport_type)[source]

Validates the transport string.

classmethod _workdir_validator(workdir)[source]

Validates the transport string.

configure(user=None, **kwargs)[source]

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
Return type:aiida.orm.AuthInfo
copy()[source]

Return a copy of the current object to work with, not stored yet.

delete_property(name, raise_exception=True)[source]

Delete a property from this computer

Parameters:
  • name (str) – the name of the property
  • raise_exception (bool) – if True raise if the property does not exist, otherwise return None
description

Get a description of the computer

Returns:the description
Return type:str
full_text_info

Return a (multiline) string with a human-readable detailed information on this computer.

Return type:str
get_authinfo(user)[source]

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.
get_configuration(user=None)[source]

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

Parameters:user (aiida.orm.User) – the user to to get the configuration for. Uses default user if None
get_default_mpiprocs_per_machine()[source]

Return the default number of CPUs per machine (node) for this computer, or None if it was not set.

get_description()[source]

Get the description for this computer

Returns:the description
Return type:str
get_hostname()[source]

Get this computer hostname :rtype: str

get_minimum_job_poll_interval()[source]

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

Returns:The minimum interval (in seconds)
Return type:float
get_mpirun_command()[source]

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.

get_property(name, *args)[source]

Get a property of this computer

Parameters:
  • name (str) – the property name
  • args – additional arguments
Returns:

the property value

get_scheduler()[source]

Get a scheduler instance for this computer

Returns:the scheduler instance
Return type:aiida.schedulers.Scheduler
get_scheduler_type()[source]

Get the scheduler type for this computer

Returns:the scheduler type
Return type:str
static get_schema()[source]
Every node property contains:
  • display_name: display name of the property
  • help text: short help text of the property
  • is_foreign_key: is the property foreign key to other type of the node
  • type: type of the property. e.g. str, dict, int
Returns:get schema of the computer
get_transport(user=None)[source]

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()[source]

Get the transport class for this computer. Can be used to instantiate a transport instance.

Returns:the transport class
get_transport_type()[source]

Get the current transport type for this computer

Returns:the transport type
Return type:str
get_workdir()[source]

Get the working directory for this computer :return: The currently configured working directory :rtype: str

is_user_configured(user)[source]

Is the user configured on this computer?

Parameters:user – the user to check
Returns:True if configured, False otherwise
Return type:bool
is_user_enabled(user)[source]

Is the given user enabled to run on this computer?

Parameters:user – the user to check
Returns:True if enabled, False otherwise
Return type:bool
label

The computer label

set_default_mpiprocs_per_machine(def_cpus_per_machine)[source]

Set the default number of CPUs per machine (node) for this computer. Accepts None if you do not want to set this value.

set_description(val)[source]

Set the description for this computer

Parameters:val (str) – the new description
set_hostname(val)[source]

Set the hostname of this computer :param val: The new hostname :type val: str

set_metadata(metadata)[source]

Set the metadata.

set_minimum_job_poll_interval(interval)[source]

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

Parameters:interval (float) – The minimum interval in seconds
set_mpirun_command(val)[source]

Set the mpirun command. It must be a list of strings (you can use string.split() if you have a single, space-separated string).

set_property(name, value)[source]

Set a property on this computer

Parameters:
  • name – the property name
  • value – the new value
set_scheduler_type(scheduler_type)[source]
Parameters:scheduler_type – the new scheduler type
set_shebang(val)[source]
Parameters:val (str) – A valid shebang line
set_transport_type(transport_type)[source]

Set the transport type for this computer

Parameters:transport_type (str) – the new transport type
store()[source]

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

validate()[source]

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!

Group

AiiDA Group entites

class aiida.orm.groups.Group(label=None, user=None, description='', type_string='user', backend=None)[source]

An AiiDA ORM implementation of group of nodes.

class Collection(backend, entity_class)[source]

Collection of Groups

delete(id)[source]

Delete a group

Parameters:id – the id of the group to delete
get_or_create(label=None, **kwargs)[source]

Try to retrieve a group from the DB with the given arguments; create (and store) a new group if such a group was not present yet.

Parameters:label (str) – group label
Returns:(group, created) where group is the group (new or existing, in any case already stored) and created is a boolean saying
Return type:(aiida.orm.Group, bool)
add_nodes(nodes)[source]

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 (aiida.orm.Node or list) – a single Node or a list of Nodes
clear()[source]

Remove all the nodes from this group.

count()[source]

Return the number of entities in this group.

Returns:integer number of entities contained within the group
Return type:int
description
Returns:the description of the group as a string
Return type:str
classmethod get(**kwargs)[source]

Custom get for group which can be used to get a group with the given attributes

Parameters:kwargs – the attributes to match the group to
Returns:the group
static get_schema()[source]
Every node property contains:
  • display_name: display name of the property
  • help text: short help text of the property
  • is_foreign_key: is the property foreign key to other type of the node
  • type: type of the property. e.g. str, dict, int
Returns:schema of the group
Return type:dict
is_empty

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

Returns:True if it contains no nodes, False otherwise
Return type:bool
is_user_defined()[source]
Returns:True if the group is user defined, False otherwise
Return type:bool
label
Returns:the label of the group as a string
nodes

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().

Return type:aiida.orm.convert.ConvertIterator
remove_nodes(nodes)[source]

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 (aiida.orm.Node or list) – a single Node or a list of Nodes
type_string
Returns:the string defining the type of the group
user
Returns:the user associated with this group
uuid
Returns:a string with the uuid
Return type:str
class aiida.orm.groups.GroupTypeString[source]

A simple enum of allowed group type strings.

User

Module for the ORM user class.

class aiida.orm.users.User(email, first_name='', last_name='', institution='', backend=None)[source]

AiiDA User

class Collection(*args, **kwargs)[source]

The collection of users stored in a backend.

get_default()[source]

Get the current default user

Returns:The default user
Return type:aiida.orm.User
get_or_create(email, **kwargs)[source]

Get the existing user with a given email address or create an unstored one

Parameters:kwargs – The properties of the user to get or create
Returns:The corresponding user object
Return type:aiida.orm.User
Raises:aiida.common.exceptions.MultipleObjectsError, aiida.common.exceptions.NotExistent
get_full_name()[source]

Return the user full name

Returns:the user full name
static get_schema()[source]

Every node property contains:

  • display_name: display name of the property
  • help text: short help text of the property
  • is_foreign_key: is the property foreign key to other type of the node
  • type: type of the property. e.g. str, dict, int
Returns:schema of the user
get_short_name()[source]

Return the user short name (typically, this returns the email)

Returns:The short name
static normalize_email(email)[source]

Normalize the address by lowercasing the domain part of the email address (taken from Django).

Node

Module with Node sub classes for data and processes.

class aiida.orm.nodes.Data(backend=None, user=None, computer=None, **kwargs)[source]

This class is base class for all data objects.

Specifications of the Data class: AiiDA Data objects are subclasses of Node and should have

Multiple inheritance must be supported, i.e. Data should have methods for querying and be able to inherit other library objects such as ASE for structures.

Architecture note: The code plugin is responsible for converting a raw data object produced by code to AiiDA standard object format. The data object then validates itself according to its method. This is done independently in order to allow cross-validation of plugins.

clone()[source]

Create a clone of the Data node.

Returns:an unstored clone of this Data node
convert(object_format=None, *args)[source]

Convert the AiiDA StructureData into another python object

Parameters:object_format – Specify the output format
creator

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

Returns:the creating node or None
export(path, fileformat=None, overwrite=False, **kwargs)[source]

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

classmethod get_export_formats()[source]

Get the list of valid export format strings

Returns:a list of valid formats
importfile(fname, fileformat=None)[source]

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.
importstring(inputstring, fileformat, **kwargs)[source]

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.
set_source(source)[source]

Sets the dictionary describing the source of Data object.

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.
class aiida.orm.nodes.BaseType(*args, **kwargs)[source]

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

class aiida.orm.nodes.ArrayData(backend=None, user=None, computer=None, **kwargs)[source]

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.
clear_internal_cache()[source]

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.

delete_array(name)[source]

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_array(name)[source]

Return an array stored in the node

Parameters:name – The name of the array to return.
get_arraynames()[source]

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

get_iterarrays()[source]

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

New in version 1.0: Renamed from iterarrays

get_shape(name)[source]

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

Parameters:name – The name of the array.
initialize()[source]

Initialize internal variables for the backend node

This needs to be called explicitly in each specific subclass implementation of the init.

set_array(name, array)[source]

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.
class aiida.orm.nodes.BandsData(backend=None, user=None, computer=None, **kwargs)[source]

Class to handle bands data

array_labels

Get the labels associated with the band arrays

get_bands(also_occupations=False, also_labels=False)[source]

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

set_bands(bands, units=None, occupations=None, labels=None)[source]

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

set_kpointsdata(kpointsdata)[source]

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

show_mpl(**kwargs)[source]

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.

units

Units in which the data in bands were stored. A string

class aiida.orm.nodes.KpointsData(backend=None, user=None, computer=None, **kwargs)[source]

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.

cell

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

get_description()[source]

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

get_kpoints(also_weights=False, cartesian=False)[source]

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.
get_kpoints_mesh(print_list=False)[source]

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()
labels

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

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)
reciprocal_cell

Return the reciprocal cell in units of 1/Angstrom from the internally set cell

set_cell(cell, pbc=None)[source]

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]
set_cell_from_structure(structuredata)[source]

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_kpoints(kpoints, cartesian=False, labels=None, weights=None, fill_values=0)[source]

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.
set_kpoints_mesh(mesh, offset=None)[source]

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.].
set_kpoints_mesh_from_density(distance, offset=None, force_parity=False)[source]

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.

class aiida.orm.nodes.ProjectionData(backend=None, user=None, computer=None, **kwargs)[source]

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) >

get_pdos(**kwargs)[source]

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)[source]

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
get_reference_bandsdata()[source]

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
set_orbitals(**kwargs)[source]

This method is inherited from OrbitalData, but is blocked here. If used will raise a NotImplementedError

set_projectiondata(list_of_orbitals, list_of_projections=None, list_of_energy=None, list_of_pdos=None, tags=None, bands_check=True)[source]

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
set_reference_bandsdata(value)[source]

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
class aiida.orm.nodes.TrajectoryData(structurelist=None, **kwargs)[source]

Stores a trajectory (a sequence of crystal structures with timestamps, and possibly with velocities).

get_cells()[source]

Return the array of cells, if it has already been set.

Raises:KeyError – if the trajectory has not been set yet.
get_cif(index=None, **kwargs)[source]

Creates aiida.orm.nodes.data.cif.CifData

New in version 1.0: Renamed from _get_cif

get_index_from_stepid(stepid)[source]

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_positions()[source]

Return the array of positions, if it has already been set.

Raises:KeyError – if the trajectory has not been set yet.
get_step_data(index)[source]

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 were specified, None is returned as the last 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 \times 3 matrix, symbols is an array of length n, positions is a n \times 3 array, and velocities is either None or a n \times 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)[source]

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.
get_stepids()[source]

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_structure(store=False, **kwargs)[source]

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

New in version 1.0: Renamed from _get_aiida_structure

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.structure.StructureData node.

get_times()[source]

Return the array of times (in ps), if it has already been set.

Raises:KeyError – if the trajectory has not been set yet.
get_velocities()[source]

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

numsites

Return the number of stored sites, or zero if nothing has been stored yet.

numsteps

Return the number of stored steps, or zero if nothing has been stored yet.

set_structurelist(structurelist)[source]

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
set_trajectory(symbols, positions, stepids=None, cells=None, times=None, velocities=None)[source]

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.

Todo

Choose suitable units for velocities

show_mpl_heatmap(**kwargs)[source]

Show a heatmap of the trajectory with matplotlib.

show_mpl_pos(**kwargs)[source]

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.
symbols

Return the array of symbols, if it has already been set.

Raises:KeyError – if the trajectory has not been set yet.
class aiida.orm.nodes.XyData(backend=None, user=None, computer=None, **kwargs)[source]

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.

get_x()[source]

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()[source]

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

set_x(x_array, x_name, x_units)[source]

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)[source]

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

class aiida.orm.nodes.Bool(*args, **kwargs)[source]

Data sub class to represent a boolean value.

class aiida.orm.nodes.CifData(ase=None, file=None, values=None, source=None, scan_type='standard', parse_policy='eager', **kwargs)[source]

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.

ase

ASE object, representing the CIF.

Note

requires ASE module.

classmethod from_md5(md5)[source]

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.

generate_md5()[source]

Computes and returns MD5 hash of the CIF file.

get_ase(**kwargs)[source]

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.

get_formulae(mode='sum')[source]

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.

classmethod get_or_create(filename, use_first=False, store_cif=True)[source]

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.

get_spacegroup_numbers()[source]

Get the spacegroup international number.

get_structure(converter='pymatgen', store=False, **kwargs)[source]

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.

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
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.
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
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
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
parse(scan_type=None)[source]

Parses CIF file and sets attributes.

Parameters:scan_type – See set_scan_type
static read_cif(fileobj, index=-1, **kwargs)[source]

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.

set_ase(aseatoms)[source]

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

Parameters:aseatoms – the ASE atoms object
set_file(file)[source]

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.

set_parse_policy(parse_policy)[source]

Set the parse policy.

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

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_values(values)[source]

Set internal representation to values.

Warning: This also writes a new CIF file.

Parameters:values – PyCifRW CifFile object

Note

requires PyCifRW module.

store(*args, **kwargs)[source]

Store the node.

values

PyCifRW structure, representing the CIF datablocks.

Note

requires PyCifRW module.

class aiida.orm.nodes.Code(remote_computer_exec=None, local_executable=None, input_plugin_name=None, files=None, **kwargs)[source]

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

can_run_on(computer)[source]

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.

full_label

Get full label of this code.

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

classmethod get(pk=None, label=None, machinename=None)[source]

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:
get_append_text()[source]

Return the postexec_code, or an empty string if no post-exec code was defined.

get_builder()[source]

Create and return a new ProcessBuilder for the default Calculation plugin, as obtained by the self.get_input_plugin_name() method.

Note:

it also sets the builder.code value.

Raises:
Returns:

classmethod get_code_helper(label, machinename=None)[source]
Parameters:
  • label – the code label identifying the code to load
  • machinename – the machine name where code is setup
Raises:
get_computer_name()[source]

Get name of this code’s computer.

get_description()[source]

Return a string description of this Code instance.

Returns:string description of this Code instance
get_execname()[source]

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.

classmethod get_from_string(code_string)[source]

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:
get_full_text_info(verbose=False)[source]

Return a (multiline) string with a human-readable detailed information on this computer

get_input_plugin_name()[source]

Return the name of the default input plugin (or None if no input plugin was set.

get_prepend_text()[source]

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.

hidden

Determines whether the Code is hidden or not

hide()[source]

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

is_local()[source]

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

classmethod list_for_plugin(plugin, labels=True)[source]

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.

relabel(new_label, raise_error=True)[source]

Relabel this code.

Parameters:
  • new_label – new code label
  • raise_error – Set to False in order to return a list of errors instead of raising them.
reveal()[source]

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

set_append_text(code)[source]

Pass a string of code that will be put in the scheduler script after the execution of the code.

set_files(files)[source]

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.
set_input_plugin_name(input_plugin)[source]

Set the name of the default input plugin, to be used for the automatic generation of a new calculation.

set_local_executable(exec_name)[source]

Set the filename of the local executable. Implicitly set the code as local.

set_prepend_text(code)[source]

Pass a string of code that will be put in the scheduler script before the execution of the code.

set_remote_computer_exec(remote_computer_exec)[source]

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.
class aiida.orm.nodes.Float(*args, **kwargs)[source]

Data sub class to represent a float value.

class aiida.orm.nodes.FolderData(backend=None, user=None, computer=None, **kwargs)[source]

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

class aiida.orm.nodes.Int(*args, **kwargs)[source]

Data sub class to represent an integer value.

class aiida.orm.nodes.List(**kwargs)[source]

Data sub class to represent a list.

append(value)[source]

S.append(value) – append value to the end of the sequence

count(value) → integer -- return number of occurrences of value[source]
extend(value)[source]

S.extend(iterable) – extend sequence by appending elements from the iterable

get_list()[source]

Return the contents of this node.

Returns:a list
index(value[, start[, stop]]) → integer -- return first index of value.[source]

Raises ValueError if the value is not present.

Supporting start and stop arguments is optional, but recommended.

insert(i, value)[source]

S.insert(index, value) – insert value before index

pop([index]) → item -- remove and return item at index (default last).[source]

Raise IndexError if list is empty or index is out of range.

remove(value)[source]

S.remove(value) – remove first occurrence of value. Raise ValueError if the value is not present.

reverse()[source]

S.reverse() – reverse IN PLACE

set_list(data)[source]

Set the contents of this node.

Parameters:data – the list to set
class aiida.orm.nodes.OrbitalData(backend=None, user=None, computer=None, **kwargs)[source]

Used for storing collections of orbitals, as well as providing methods for accessing them internally.

clear_orbitals()[source]

Remove all orbitals that were added to the class Cannot work if OrbitalData has been already stored

get_orbitals(**kwargs)[source]

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)[source]

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
class aiida.orm.nodes.Dict(**kwargs)[source]

Data sub class to represent a dictionary.

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.
get_dict()[source]

Return a dictionary with the parameters currently set.

Returns:dictionary
keys()[source]

Iterator of valid keys stored in the Dict object.

Returns:iterator over the keys of the current dictionary
set_dict(dictionary)[source]

Replace the current dictionary with another one.

Parameters:dictionary – dictionary to set
update_dict(dictionary)[source]

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
class aiida.orm.nodes.RemoteData(remote_path=None, **kwargs)[source]

Store a link to a file or folder on a remote machine.

Remember to pass a computer!

getfile(relpath, destpath)[source]

Connects to the remote folder and gets a string with the (full) content of the file.

Parameters:
  • relpath – The relative path of the file to show.
  • destpath – A path on the local computer to get the file
Returns:

a string with the file content

is_empty

Check if remote folder is empty

listdir(relpath='.')[source]

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='.')[source]

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.
class aiida.orm.nodes.SinglefileData(file, **kwargs)[source]

Data class that can be used to store a single file in its repository.

filename

Return the name of the file stored.

Returns:the filename under which the file is stored in the repository
get_content()[source]

Return the content of the single file stored for this data node.

Returns:the content of the file as a string
open(key=None, mode='r')[source]

Return an open file handle to the content of this data node.

Parameters:
  • key – optional key within the repository, by default is the filename set in the attributes
  • mode – the mode with which to open the file handle (default: read mode)
Returns:

a file handle

set_file(file)[source]

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.StringIO(“my string”) to construct the file directly from a string.
class aiida.orm.nodes.Str(*args, **kwargs)[source]

Data sub class to represent a string value.

class aiida.orm.nodes.StructureData(cell=None, pbc=None, ase=None, pymatgen=None, pymatgen_structure=None, pymatgen_molecule=None, **kwargs)[source]

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.

append_atom(**kwargs)[source]

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.

append_kind(kind)[source]

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)[source]

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.
cell

Returns the cell shape.

Returns:a 3x3 list of lists.
cell_angles

Get the angles between the cell lattice vectors in degrees.

cell_lengths

Get the lengths of cell lattice vectors in angstroms.

clear_kinds()[source]

Removes all kinds for the StructureData object.

Note

Also clear all sites!

clear_sites()[source]

Removes all sites for the StructureData object.

get_ase()[source]

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_cell_volume()[source]

Returns the cell volume in Angstrom^3.

Returns:a float.
get_cif(converter='ase', store=False, **kwargs)[source]

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_composition()[source]

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_description()[source]

Returns a string with infos retrieved from StructureData node’s properties

Parameters:self – the StructureData node
Returns:retsrt: the description string
get_dimensionality()[source]

This function checks the dimensionality of the structure and calculates its length/surface/volume :return: returns the dimensionality and length/surface/volume

get_formula(mode='hill', separator='')[source]

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_kind(kind_name)[source]

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()[source]

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.
get_pymatgen(**kwargs)[source]

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_molecule()[source]

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.
get_pymatgen_structure(**kwargs)[source]

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_site_kindnames()[source]

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_symbols_set()[source]

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.
has_vacancies

Return whether the structure has vacancies in the structure.

Returns:a boolean, True if at least one kind has a vacancy
is_alloy

Return whether the structure contains any alloy kinds.

Returns:a boolean, True if at least one kind is an alloy
kinds

Returns a list of kinds.

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)
reset_cell(new_cell)[source]

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)[source]

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:

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.

set_ase(aseatoms)[source]

Load the structure from a ASE object

set_pymatgen(obj, **kwargs)[source]

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)[source]

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)[source]

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.
sites

Returns a list of sites.

class aiida.orm.nodes.UpfData(file=None, source=None, **kwargs)[source]

Function not yet documented.

classmethod from_md5(md5)[source]

Return a list of all UPF pseudopotentials that match a given MD5 hash.

Note that the hash has to be stored in a _md5 attribute, otherwise the pseudo will not be found.

classmethod get_or_create(filepath, use_first=False, store_upf=True)[source]

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

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 (bool) – If false, the UpfData objects are not stored in the database. default=True.
Return (upf, created):
 

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

get_upf_family_names()[source]

Get the list of all upf family names to which the pseudo belongs.

classmethod get_upf_group(group_label)[source]

Return the UpfFamily group with the given name.

classmethod get_upf_groups(filter_elements=None, user=None)[source]

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. Default=None, meaning that all families are returned.
  • user – if None (default), return the groups for all users. If defined, it should be either a DbUser instance, or a string for the username (that is, the user email).
set_file(file)[source]

I pre-parse the file to store the attributes.

store(*args, **kwargs)[source]

Store the node, reparsing the file so that the md5 and the element are correctly reset.

class aiida.orm.nodes.NumericType(*args, **kwargs)[source]

Sub class of Data to store numbers, overloading common operators (+, *, …).

class aiida.orm.nodes.CalculationNode(backend=None, user=None, computer=None, **kwargs)[source]

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

inputs

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.

Returns:NodeLinksManager
outputs

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.

Returns:NodeLinksManager
class aiida.orm.nodes.CalcFunctionNode(backend=None, user=None, computer=None, **kwargs)[source]

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

validate_outgoing(target, link_type, link_label)[source]

Validate adding a link of the given type from ourself to a given node.

A calcfunction cannot return Data, so if we receive an outgoing link to a stored Data node, that means the user created a Data node within our function body and stored it themselves or they are returning an input node. The latter use case is reserved for @workfunctions, as they can have RETURN links.

Parameters:
  • target – the node to which the link is going
  • link_type – the link type
  • link_label – the link label
Raises:
  • TypeError – if target is not a Node instance or link_type is not a LinkType enum
  • ValueError – if the proposed link is invalid
class aiida.orm.nodes.CalcJobNode(backend=None, user=None, computer=None, **kwargs)[source]

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

delete_state()[source]

Delete the calculation job state attribute if it exists.

get_authinfo()[source]

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

Returns:AuthInfo
get_builder_restart()[source]

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.

Returns:~aiida.engine.processes.builder.ProcessBuilder instance
get_description()[source]

Return a string with a description of the node based on its properties.

get_hash(ignore_errors=True, ignored_folder_content=('raw_input', ), **kwargs)[source]

Return the hash for this node based on its attributes.

get_job_id()[source]

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

Returns:the string representation of the scheduler job id
get_last_job_info()[source]

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

Returns:a JobInfo object (that closely resembles a dictionary) or None.
get_option(name)[source]

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
get_options()[source]

Return the dictionary of options set for this CalcJobNode

Returns:dictionary of the options and their values
get_parser_class()[source]

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.
get_remote_workdir()[source]

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

Returns:a string with the remote path
get_retrieve_list()[source]

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

Returns:a list of file directives
get_retrieve_singlefile_list()[source]

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

Returns:list of single file retrieval directives

Deprecated since version 1.0.0: Will be removed in v2.0.0, use aiida.orm.nodes.process.calculation.calcjob.CalcJobNode.get_retrieve_temporary_list() instead.

get_retrieve_temporary_list()[source]

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

Returns:a list of file directives
get_retrieved_node()[source]

Return the retrieved data folder.

Returns:the retrieved FolderData node or None if not found
get_scheduler_lastchecktime()[source]

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
get_scheduler_state()[source]

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

Returns:a JobState enum instance.
get_scheduler_stderr()[source]

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

Returns:scheduler stdout output or None
get_scheduler_stdout()[source]

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

Returns:scheduler stderr output or None
get_state()[source]

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
get_transport()[source]

Return the transport for this calculation.

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

Return the link label used for the retrieved FolderData node.

res

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.
set_job_id(job_id)[source]

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
set_last_job_info(last_job_info)[source]

Set the last job info.

Parameters:last_job_info – a JobInfo object
set_option(name, value)[source]

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

set_options(options)[source]

Set the options for this CalcJobNode

Parameters:options – dictionary of option and their values to set
set_remote_workdir(remote_workdir)[source]

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
set_retrieve_list(retrieve_list)[source]

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
set_retrieve_singlefile_list(retrieve_singlefile_list)[source]

Set the retrieve singlefile list.

The files will be stored as SinglefileData instances and added as output nodes to this calculation node. The format of a single file directive is a tuple or list of length 3 with the following entries:

  1. the link label under which the file should be added
  2. the SinglefileData class or sub class to use to store
  3. the filepath relative to the remote working directory of the calculation
Parameters:retrieve_singlefile_list – list or tuple of single file directives

Deprecated since version 1.0.0: Will be removed in v2.0.0. Use set_retrieve_temporary_list() instead.

set_retrieve_temporary_list(retrieve_temporary_list)[source]

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
set_scheduler_state(state)[source]

Set the scheduler state.

Parameters:state – an instance of JobState
set_state(state)[source]

Set the calculation active job state.

Parameters:state – a string with the state from aiida.common.datastructures.CalcJobState.
Raise:ValueError if state is invalid
tools

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
class aiida.orm.nodes.ProcessNode(backend=None, user=None, computer=None, **kwargs)[source]

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.

called

Return a list of nodes that the process called

Returns:list of process nodes called by this process
called_descendants

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.

caller

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
checkpoint

Return the checkpoint bundle set for the process

Returns:checkpoint bundle if it exists, None otherwise
delete_checkpoint()[source]

Delete the checkpoint bundle set for the process

exception

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
exit_message

Return the exit message of the process

Returns:the exit message
exit_status

Return the exit status of the process

Returns:the exit status, an integer exit code or None
get_builder_restart()[source]

Return a ProcessBuilder that is ready to relaunch the process 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.

Returns:~aiida.engine.processes.builder.ProcessBuilder instance
is_excepted

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
is_failed

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
is_finished

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
is_finished_ok

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
is_killed

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
is_terminated

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
is_valid_cache

Return whether the node is valid for caching

Returns:True if this process node is valid to be used for caching, False otherwise
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
pause()[source]

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.

paused

Return whether the process is paused

Returns:True if the Calculation is marked as paused, False otherwise
process_class

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
process_label

Return the process label

Returns:the process label
process_state

Return the process state

Returns:the process state instance of ProcessState enum
process_status

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_checkpoint(checkpoint)[source]

Set the checkpoint bundle set for the process

Parameters:state – string representation of the stepper state info
set_exception(exception)[source]

Set the exception of the process

Parameters:exception – the exception message
set_exit_message(message)[source]

Set the exit message of the process, if None nothing will be done

Parameters:message – a string message
set_exit_status(status)[source]

Set the exit status of the process

Parameters:state – an integer exit code or None, which will be interpreted as zero
set_process_label(label)[source]

Set the process label

Parameters:label – process label string
set_process_state(state)[source]

Set the process state

Parameters:state – value or instance of ProcessState enum
set_process_status(status)[source]

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
set_process_type(process_type_string)[source]

Set the process type string.

Parameters:process_type – the process type string identifying the class using this process node as storage.
unpause()[source]

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.

validate_incoming(source, link_type, link_label)[source]

Validate adding a link of the given type from a given node to ourself.

Adding an input link to a ProcessNode once it is stored is illegal because this should be taken care of by the engine in one go. If a link is being added after the node is stored, it is most likely not by the engine and it should not be allowed.

Parameters:
  • source – the node from which the link is coming
  • link_type – the link type
  • link_label – the link label
Raises:
  • TypeError – if source is not a Node instance or link_type is not a LinkType enum
  • ValueError – if the proposed link is invalid
class aiida.orm.nodes.WorkflowNode(backend=None, user=None, computer=None, **kwargs)[source]

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

inputs

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
outputs

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
validate_outgoing(target, link_type, link_label)[source]

Validate adding a link of the given type from ourself to a given node.

A workflow cannot ‘create’ Data, so if we receive an outgoing link to an unstored Data node, that means the user created a Data node within our function body and tries to attach it as an output. This is strictly forbidden and can cause provenance to be lost.

Parameters:
  • target – the node to which the link is going
  • link_type – the link type
  • link_label – the link label
Raises:
  • TypeError – if target is not a Node instance or link_type is not a LinkType enum
  • ValueError – if the proposed link is invalid
class aiida.orm.nodes.WorkChainNode(backend=None, user=None, computer=None, **kwargs)[source]

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

set_stepper_state_info(stepper_state_info)[source]

Set the stepper state info

Parameters:state – string representation of the stepper state info
stepper_state_info

Return the stepper state info

Returns:string representation of the stepper state info
class aiida.orm.nodes.WorkFunctionNode(backend=None, user=None, computer=None, **kwargs)[source]

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

validate_outgoing(target, link_type, link_label)[source]

Validate adding a link of the given type from ourself to a given node.

A workfunction cannot create Data, so if we receive an outgoing RETURN link to an unstored Data node, that means the user created a Data node within our function body and is trying to return it. This use case should be reserved for @calcfunctions, as they can have CREATE links.

Parameters:
  • target – the node to which the link is going
  • link_type – the link type
  • link_label – the link label
Raises:
  • TypeError – if target is not a Node instance or link_type is not a LinkType enum
  • ValueError – if the proposed link is invalid
class aiida.orm.nodes.Node(backend=None, user=None, computer=None, **kwargs)[source]

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.

class Collection(backend, entity_class)[source]

The collection of AuthInfo entries.

delete(node_id)[source]

Delete a Node from the collection with the given id

Parameters:node_id – the node id
add_comment(content, user=None)[source]

Add a new comment.

Parameters:
  • content – string with comment
  • user – the user to associate with the comment, will use default if not supplied
Returns:

the newly created comment

add_incoming(source, link_type, link_label)[source]

Add a link of the given type from a given node to ourself.

Parameters:
  • source – the node from which the link is coming
  • link_type – the link type
  • link_label – the link label
Raises:
  • TypeError – if source is not a Node instance or link_type is not a LinkType enum
  • ValueError – if the proposed link is invalid
attributes

Return the complete attributes dictionary.

Warning

While the node 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 node 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 attributes_keys and attributes_items, or the getters get_attribute and get_attribute_many instead.

Returns:the attributes as a dictionary
attributes_items()[source]

Return an iterator over the attributes.

Returns:an iterator with attribute key value pairs
attributes_keys()[source]

Return an iterator over the attribute keys.

Returns:an iterator with attribute keys
clear_attributes()[source]

Delete all attributes.

clear_extras()[source]

Delete all extras.

clear_hash()[source]

Sets the stored hash of the Node to None.

computer

Return the computer of this node.

Returns:the computer or None
Return type:Computer or None
ctime

Return the node ctime.

Returns:the ctime
delete_attribute(key)[source]

Delete an attribute.

Parameters:

key – name of the attribute

Raises:
delete_attribute_many(keys)[source]

Delete multiple attributes.

Parameters:

keys – names of the attributes to delete

Raises:
delete_extra(key)[source]

Delete an extra.

Parameters:key – name of the extra
Raises:AttributeError – if the extra does not exist
delete_extra_many(keys)[source]

Delete multiple extras.

Parameters:keys – names of the extras to delete
Raises:AttributeError – if at least one of the extra does not exist
delete_object(key, force=False)[source]

Delete the object from the repository.

Warning

If the repository belongs to a stored node, a ModificationNotAllowed exception will be raised. This check can be avoided by using the force flag, but this should be used with extreme caution!

Parameters:
  • key – fully qualified identifier for the object within the repository
  • force – boolean, if True, will skip the mutability check
Raises:

aiida.common.ModificationNotAllowed – if repository is immutable and force=False

description

Return the node description.

Returns:the description
extras

Return the complete extras dictionary.

Warning

While the node 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 node 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
extras_items()[source]

Return an iterator over the extras.

Returns:an iterator with extra key value pairs
extras_keys()[source]

Return an iterator over the extra keys.

Returns:an iterator with extra keys
classmethod from_backend_entity(backend_entity)[source]

Construct an entity from a backend entity instance

Parameters:backend_entity – the backend entity
Returns:an AiiDA entity instance
get_all_same_nodes()[source]

Return a list of stored nodes which match the type and hash of the current node.

All returned nodes are valid caches, meaning their _aiida_hash extra matches self.get_hash().

Note: this can be called only after storing a Node (since at store time attributes will be cleaned with clean_value and the hash should become idempotent to the action of serialization/deserialization)

get_attribute(key, default=())[source]

Return the value of an attribute.

Warning

While the node 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 node 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_attribute_many(keys)[source]

Return the values of multiple attributes.

Warning

While the node 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 node 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 attributes_keys and attributes_items, or the getters get_attribute and get_attribute_many instead.

Parameters:keys – a list of attribute names
Returns:a list of attribute values
Raises:AttributeError – if at least one attribute does not exist
get_cache_source()[source]

Return the UUID of the node that was used in creating this node from the cache, or None if it was not cached.

Returns:source node UUID or None
get_comment(identifier)[source]

Return a comment corresponding to the given identifier.

Parameters:

identifier – the comment pk

Raises:
Returns:

the comment

get_comments()[source]

Return a sorted list of comments for this node.

Returns:the list of comments, sorted by pk
get_description()[source]

Return a string with a description of the node.

Returns:a description string
Return type:str
get_extra(key, default=())[source]

Return the value of an extra.

Warning

While the node 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 node 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_extra_many(keys)[source]

Return the values of multiple extras.

Warning

While the node 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 node 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.

Parameters:keys – a list of extra names
Returns:a list of extra values
Raises:AttributeError – if at least one extra does not exist
get_hash(ignore_errors=True, **kwargs)[source]

Return the hash for this node based on its attributes.

get_incoming(node_class=None, link_type=(), link_label_filter=None, only_uuid=False)[source]

Return a list of link triples that are (directly) incoming into this node.

Parameters:
  • node_class – If specified, should be a class or tuple of classes, and it filters only elements of that specific type (or a subclass of ‘type’)
  • link_type – If specified should be a string or tuple to get the inputs of this link type, if None then returns all inputs of all link types.
  • link_label_filter – filters the incoming nodes by its link label. Here wildcards (% and _) can be passed in link label filter as we are using “like” in QB.
  • only_uuid – project only the node UUID instead of the instance onto the NodeTriple.node entries
get_object(key)[source]

Return the object identified by key.

Parameters:key – fully qualified identifier for the object within the repository
Returns:a File named tuple representing the object located at key
get_object_content(key, mode='r')[source]

Return the content of a object identified by key.

Parameters:key – fully qualified identifier for the object within the repository
get_outgoing(node_class=None, link_type=(), link_label_filter=None, only_uuid=False)[source]

Return a list of link triples that are (directly) outgoing of this node.

Parameters:
  • node_class – If specified, should be a class or tuple of classes, and it filters only elements of that specific type (or a subclass of ‘type’)
  • link_type – If specified should be a string or tuple to get the inputs of this link type, if None then returns all outputs of all link types.
  • link_label_filter – filters the outgoing nodes by its link label. Here wildcards (% and _) can be passed in link label filter as we are using “like” in QB.
  • only_uuid – project only the node UUID instead of the instance onto the NodeTriple.node entries
static get_schema()[source]
Every node property contains:
  • display_name: display name of the property
  • help text: short help text of the property
  • is_foreign_key: is the property foreign key to other type of the node
  • type: type of the property. e.g. str, dict, int
Returns:get schema of the node
get_stored_link_triples(node_class=None, link_type=(), link_label_filter=None, link_direction='incoming', only_uuid=False)[source]

Return the list of stored link triples directly incoming to or outgoing of this node.

Note this will only return link triples that are stored in the database. Anything in the cache is ignored.

Parameters:
  • node_class – If specified, should be a class, and it filters only elements of that (subclass of) type
  • link_type – Only get inputs of this link type, if empty tuple then returns all inputs of all link types.
  • link_label_filter – filters the incoming nodes by its link label. This should be a regex statement as one would pass directly to a QuerBuilder filter statement with the ‘like’ operation.
  • link_directionincoming or outgoing to get the incoming or outgoing links, respectively.
  • only_uuid – project only the node UUID instead of the instance onto the NodeTriple.node entries
has_cached_links()[source]

Feturn whether there are unstored incoming links in the cache.

Returns:boolean, True when there are links in the incoming cache, False otherwise
initialize()[source]

Initialize internal variables for the backend node

This needs to be called explicitly in each specific subclass implementation of the init.

is_created_from_cache

Return whether this node was created from a cached node.

Returns:boolean, True if the node was created by cloning a cached node, False otherwise
is_valid_cache

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

label

Return the node label.

Returns:the label
list_object_names(key=None)[source]

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

Parameters:key – fully qualified identifier for the object within the repository
Returns:a list of File named tuples representing the objects present in directory with the given key
list_objects(key=None)[source]

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

Parameters:key – fully qualified identifier for the object within the repository
Returns:a list of File named tuples representing the objects present in directory with the given key
logger

Return the logger configured for this Node.

Returns:Logger object
mtime

Return the node mtime.

Returns:the mtime
node_type

Return the node type.

Returns:the node type
open(key, mode='r')[source]

Open a file handle to an object stored under the given key.

Parameters:
  • key – fully qualified identifier for the object within the repository
  • mode – the mode under which to open the handle
process_type

Return the node process type.

Returns:the process type
put_object_from_file(path, key, mode='w', encoding='utf8', force=False)[source]

Store a new object under key with contents of the file located at path on this file system.

Warning

If the repository belongs to a stored node, a ModificationNotAllowed exception will be raised. This check can be avoided by using the force flag, but this should be used with extreme caution!

Parameters:
  • path – absolute path of file whose contents to copy to the repository
  • key – fully qualified identifier for the object within the repository
  • mode – the file mode with which the object will be written
  • encoding – the file encoding with which the object will be written
  • force – boolean, if True, will skip the mutability check
Raises:

aiida.common.ModificationNotAllowed – if repository is immutable and force=False

put_object_from_filelike(handle, key, mode='w', encoding='utf8', force=False)[source]

Store a new object under key with contents of filelike object handle.

Warning

If the repository belongs to a stored node, a ModificationNotAllowed exception will be raised. This check can be avoided by using the force flag, but this should be used with extreme caution!

Parameters:
  • handle – filelike object with the content to be stored
  • key – fully qualified identifier for the object within the repository
  • mode – the file mode with which the object will be written
  • encoding – the file encoding with which the object will be written
  • force – boolean, if True, will skip the mutability check
Raises:

aiida.common.ModificationNotAllowed – if repository is immutable and force=False

put_object_from_tree(path, key=None, contents_only=True, force=False)[source]

Store a new object under key with the contents of the directory located at path on this file system.

Warning

If the repository belongs to a stored node, a ModificationNotAllowed exception will be raised. This check can be avoided by using the force flag, but this should be used with extreme caution!

Parameters:
  • path – absolute path of directory whose contents to copy to the repository
  • key – fully qualified identifier for the object within the repository
  • contents_only – boolean, if True, omit the top level directory of the path and only copy its contents.
  • force – boolean, if True, will skip the mutability check
Raises:

aiida.common.ModificationNotAllowed – if repository is immutable and force=False

rehash()[source]

Regenerate the stored hash of the Node.

remove_comment(identifier)[source]

Delete an existing comment.

Parameters:identifier – the comment pk
reset_attributes(attributes)[source]

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:
reset_extras(extras)[source]

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
set_attribute(key, value)[source]

Set an attribute to the given value.

Parameters:
  • key – name of the attribute
  • value – value of the attribute
Raises:
set_attribute_many(attributes)[source]

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:
set_extra(key, value)[source]

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_extra_many(extras)[source]

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
store(with_transaction=True, use_cache=None)[source]

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_all(with_transaction=True, use_cache=None)[source]

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.
update_comment(identifier, content)[source]

Update the content of an existing comment.

Parameters:
  • identifier – the comment pk
  • content – the new comment content
Raises:
user

Return the user of this node.

Returns:the user
Return type:User
uuid

Return the node UUID.

Returns:the string representation of the UUID
Return type:str
validate_incoming(source, link_type, link_label)[source]

Validate adding a link of the given type from a given node to ourself.

This function will first validate the types of the inputs, followed by the node and link types and validate whether in principle a link of that type between the nodes of these types is allowed.the

Subsequently, the validity of the “degree” of the proposed link is validated, which means validating the number of links of the given type from the given node type is allowed.

Parameters:
  • source – the node from which the link is coming
  • link_type – the link type
  • link_label – the link label
Raises:
  • TypeError – if source is not a Node instance or link_type is not a LinkType enum
  • ValueError – if the proposed link is invalid
validate_outgoing(target, link_type, link_label)[source]

Validate adding a link of the given type from ourself to a given node.

The validity of the triple (source, link, target) should be validated in the validate_incoming call. This method will be called afterwards and can be overriden by subclasses to add additional checks that are specific to that subclass.

Parameters:
  • target – the node to which the link is going
  • link_type – the link type
  • link_label – the link label
Raises:
  • TypeError – if target is not a Node instance or link_type is not a LinkType enum
  • ValueError – if the proposed link is invalid
verify_are_parents_stored()[source]

Verify that all parent nodes are already stored.

Raises:aiida.common.ModificationNotAllowed – if one of the source nodes of incoming links is not stored.
class aiida.orm.nodes.node.Node(backend=None, user=None, computer=None, **kwargs)[source]

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.

Code

class aiida.orm.nodes.data.code.Code(remote_computer_exec=None, local_executable=None, input_plugin_name=None, files=None, **kwargs)[source]

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

__init__(remote_computer_exec=None, local_executable=None, input_plugin_name=None, files=None, **kwargs)[source]
Parameters:backend_entity (aiida.orm.implementation.BackendEntity) – the backend model supporting this entity
can_run_on(computer)[source]

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.

full_label

Get full label of this code.

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

classmethod get(pk=None, label=None, machinename=None)[source]

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:
get_append_text()[source]

Return the postexec_code, or an empty string if no post-exec code was defined.

get_builder()[source]

Create and return a new ProcessBuilder for the default Calculation plugin, as obtained by the self.get_input_plugin_name() method.

Note:

it also sets the builder.code value.

Raises:
Returns:

classmethod get_code_helper(label, machinename=None)[source]
Parameters:
  • label – the code label identifying the code to load
  • machinename – the machine name where code is setup
Raises:
get_computer_name()[source]

Get name of this code’s computer.

get_description()[source]

Return a string description of this Code instance.

Returns:string description of this Code instance
get_execname()[source]

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.

classmethod get_from_string(code_string)[source]

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:
get_full_text_info(verbose=False)[source]

Return a (multiline) string with a human-readable detailed information on this computer

get_input_plugin_name()[source]

Return the name of the default input plugin (or None if no input plugin was set.

get_prepend_text()[source]

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.

hidden

Determines whether the Code is hidden or not

hide()[source]

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

is_local()[source]

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

classmethod list_for_plugin(plugin, labels=True)[source]

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.

relabel(new_label, raise_error=True)[source]

Relabel this code.

Parameters:
  • new_label – new code label
  • raise_error – Set to False in order to return a list of errors instead of raising them.
reveal()[source]

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

set_append_text(code)[source]

Pass a string of code that will be put in the scheduler script after the execution of the code.

set_files(files)[source]

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.
set_input_plugin_name(input_plugin)[source]

Set the name of the default input plugin, to be used for the automatic generation of a new calculation.

set_local_executable(exec_name)[source]

Set the filename of the local executable. Implicitly set the code as local.

set_prepend_text(code)[source]

Pass a string of code that will be put in the scheduler script before the execution of the code.

set_remote_computer_exec(remote_computer_exec)[source]

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.

Mixins

Mixin classes for ORM classes.

class aiida.orm.utils.mixins.FunctionCalculationMixin[source]

This mixin should be used for ProcessNode subclasses that are used to record the execution of a python function. For example the process nodes that are used for a function that was wrapped by the workfunction or calcfunction function decorators. The store_source_info method can then be called with the wrapped function to store information about that function in the calculation node through the inspect module. Various property getters are defined to later retrieve that information from the node

function_name

Return the function name of the wrapped function.

Returns:the function name or None
function_namespace

Return the function namespace of the wrapped function.

Returns:the function namespace or None
function_starting_line_number

Return the starting line number of the wrapped function in its source file.

Returns:the starting line number or None
get_function_source_code()[source]

Return the absolute path to the source file in the repository.

Returns:the absolute path of the source file in the repository, or None if it does not exist
store_source_info(func)[source]

Retrieve source information about the wrapped function func through the inspect module, and store it in the attributes and repository of the node. The function name, namespace and the starting line number in the source file will be stored in the attributes. The source file itself will be copied into the repository

Parameters:func – the function to inspect and whose information to store in the node
class aiida.orm.utils.mixins.Sealable[source]

Mixin to mark a Node as sealable.

delete_attribute(key)[source]

Delete an attribute.

Parameters:

key – name of the attribute

Raises:
is_sealed

Returns whether the node is sealed, i.e. whether the sealed attribute has been set to True.

seal()[source]

Seal the node by setting the sealed attribute to True.

set_attribute(key, value)[source]

Set an attribute to the given value.

Parameters:
  • key – name of the attribute
  • value – value of the attribute
Raises:

aiida.common.exceptions.ModificationNotAllowed – if the node is already sealed or if the node is already stored and the attribute is not updatable.

validate_incoming(source, link_type, link_label)[source]

Validate adding a link of the given type from a given node to ourself.

Adding an incoming link to a sealed node is forbidden.

Parameters:
  • source – the node from which the link is coming
  • link_type – the link type
  • link_label – the link label
Raises:

aiida.common.ModificationNotAllowed – if the target node (self) is sealed

validate_outgoing(target, link_type, link_label)[source]

Validate adding a link of the given type from ourself to a given node.

Adding an outgoing link from a sealed node is forbidden.

Parameters:
  • target – the node to which the link is going
  • link_type – the link type
  • link_label – the link label
Raises:

aiida.common.ModificationNotAllowed – if the source node (self) is sealed

class aiida.orm.utils.mixins.Sealable[source]

Mixin to mark a Node as sealable.

ORM documentation: Data

Note

This list only includes the classes included in AiiDA-core. For all the plugin subclasses, check the corresponding plugin repositories.

Module with Node sub classes for data structures.

class aiida.orm.nodes.data.Data(backend=None, user=None, computer=None, **kwargs)[source]

This class is base class for all data objects.

Specifications of the Data class: AiiDA Data objects are subclasses of Node and should have

Multiple inheritance must be supported, i.e. Data should have methods for querying and be able to inherit other library objects such as ASE for structures.

Architecture note: The code plugin is responsible for converting a raw data object produced by code to AiiDA standard object format. The data object then validates itself according to its method. This is done independently in order to allow cross-validation of plugins.

_exportcontent(fileformat, main_file_name='', **kwargs)[source]

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)

_get_converters()[source]

Get all implemented converter formats. The convention is to find all _get_object_… methods. Returns a list of strings.

_get_exporters()[source]

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

_get_importers()[source]

Get all implemented import formats. The convention is to find all _parse_… methods. Returns a list of strings.

_validate()[source]

Perform validation of the Data object.

Note

validation of data source checks license and requires attribution to be provided in field ‘description’ of source in the case of any CC-BY* license. If such requirement is too strict, one can remove/comment it out.

clone()[source]

Create a clone of the Data node.

Returns:an unstored clone of this Data node
convert(object_format=None, *args)[source]

Convert the AiiDA StructureData into another python object

Parameters:object_format – Specify the output format
creator

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

Returns:the creating node or None
export(path, fileformat=None, overwrite=False, **kwargs)[source]

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

classmethod get_export_formats()[source]

Get the list of valid export format strings

Returns:a list of valid formats
importfile(fname, fileformat=None)[source]

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.
importstring(inputstring, fileformat, **kwargs)[source]

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.
set_source(source)[source]

Sets the dictionary describing the source of Data object.

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.
class aiida.orm.nodes.data.BaseType(*args, **kwargs)[source]

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

class aiida.orm.nodes.data.ArrayData(backend=None, user=None, computer=None, **kwargs)[source]

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.
_arraynames_from_files()[source]

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

_arraynames_from_properties()[source]

Return a list of all arrays stored in the node, listing the attributes starting with the correct prefix.

_validate()[source]

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.

clear_internal_cache()[source]

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.

delete_array(name)[source]

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_array(name)[source]

Return an array stored in the node

Parameters:name – The name of the array to return.
get_arraynames()[source]

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

get_iterarrays()[source]

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

New in version 1.0: Renamed from iterarrays

get_shape(name)[source]

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

Parameters:name – The name of the array.
initialize()[source]

Initialize internal variables for the backend node

This needs to be called explicitly in each specific subclass implementation of the init.

set_array(name, array)[source]

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.
class aiida.orm.nodes.data.BandsData(backend=None, user=None, computer=None, **kwargs)[source]

Class to handle bands data

_get_bandplot_data(cartesian, prettify_format=None, join_symbol=None, get_segments=False, y_origin=0.0)[source]

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

_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)[source]

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_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)[source]

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.
_prepare_agr_batch(main_file_name='', comments=True, prettify_format=None)[source]

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_blocks(main_file_name='', comments=True)[source]

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)
_prepare_dat_multicolumn(main_file_name='', comments=True)[source]

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_gnuplot(main_file_name='', title='', comments=True, prettify_format=None, y_max_lim=None, y_min_lim=None, y_origin=0.0)[source]

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_json(main_file_name='', comments=True)[source]

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)
_prepare_mpl_pdf(main_file_name='', *args, **kwargs)[source]

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)[source]

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_singlefile(*args, **kwargs)[source]

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)[source]

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()

_set_pbc(value)[source]

validate the pbc, then store them

_validate_bands_occupations(bands, occupations=None, labels=None)[source]

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.

array_labels

Get the labels associated with the band arrays

get_bands(also_occupations=False, also_labels=False)[source]

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

set_bands(bands, units=None, occupations=None, labels=None)[source]

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

set_kpointsdata(kpointsdata)[source]

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

show_mpl(**kwargs)[source]

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.

units

Units in which the data in bands were stored. A string

class aiida.orm.nodes.data.KpointsData(backend=None, user=None, computer=None, **kwargs)[source]

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.

_change_reference(kpoints, to_cartesian=True)[source]

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

_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

_set_cell(value)[source]

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

_set_labels(value)[source]

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

_set_pbc(value)[source]

validate the pbc, then store them

_validate_kpoints_weights(kpoints, weights)[source]

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

cell

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

get_description()[source]

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

get_kpoints(also_weights=False, cartesian=False)[source]

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.
get_kpoints_mesh(print_list=False)[source]

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()
labels

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

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)
reciprocal_cell

Return the reciprocal cell in units of 1/Angstrom from the internally set cell

set_cell(cell, pbc=None)[source]

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]
set_cell_from_structure(structuredata)[source]

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_kpoints(kpoints, cartesian=False, labels=None, weights=None, fill_values=0)[source]

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.
set_kpoints_mesh(mesh, offset=None)[source]

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.].
set_kpoints_mesh_from_density(distance, offset=None, force_parity=False)[source]

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.

class aiida.orm.nodes.data.ProjectionData(backend=None, user=None, computer=None, **kwargs)[source]

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) >

_check_projections_bands(projection_array)[source]

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
_find_orbitals_and_indices(**kwargs)[source]

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
_from_index_to_arrayname(index)[source]

Used internally to determine the array names.

get_pdos(**kwargs)[source]

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)[source]

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
get_reference_bandsdata()[source]

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
set_orbitals(**kwargs)[source]

This method is inherited from OrbitalData, but is blocked here. If used will raise a NotImplementedError

set_projectiondata(list_of_orbitals, list_of_projections=None, list_of_energy=None, list_of_pdos=None, tags=None, bands_check=True)[source]

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
set_reference_bandsdata(value)[source]

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
class aiida.orm.nodes.data.TrajectoryData(structurelist=None, **kwargs)[source]

Stores a trajectory (a sequence of crystal structures with timestamps, and possibly with velocities).

_internal_validate(stepids, cells, symbols, positions, times, velocities)[source]

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.

_parse_xyz_pos(inputstring)[source]

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)[source]

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()

_prepare_cif(trajectory_index=None, main_file_name='')[source]

Write the given trajectory to a string of format CIF.

_prepare_xsf(index=None, main_file_name='')[source]

Write the given trajectory to a string of format XSF (for XCrySDen).

_validate()[source]

Verify that the required arrays are present and that their type and dimension are correct.

get_cells()[source]

Return the array of cells, if it has already been set.

Raises:KeyError – if the trajectory has not been set yet.
get_cif(index=None, **kwargs)[source]

Creates aiida.orm.nodes.data.cif.CifData

New in version 1.0: Renamed from _get_cif

get_index_from_stepid(stepid)[source]

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_positions()[source]

Return the array of positions, if it has already been set.

Raises:KeyError – if the trajectory has not been set yet.
get_step_data(index)[source]

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 were specified, None is returned as the last 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 \times 3 matrix, symbols is an array of length n, positions is a n \times 3 array, and velocities is either None or a n \times 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)[source]

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.
get_stepids()[source]

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_structure(store=False, **kwargs)[source]

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

New in version 1.0: Renamed from _get_aiida_structure

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.structure.StructureData node.

get_times()[source]

Return the array of times (in ps), if it has already been set.

Raises:KeyError – if the trajectory has not been set yet.
get_velocities()[source]

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

numsites

Return the number of stored sites, or zero if nothing has been stored yet.

numsteps

Return the number of stored steps, or zero if nothing has been stored yet.

set_structurelist(structurelist)[source]

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
set_trajectory(symbols, positions, stepids=None, cells=None, times=None, velocities=None)[source]

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.

Todo

Choose suitable units for velocities

show_mpl_heatmap(**kwargs)[source]

Show a heatmap of the trajectory with matplotlib.

show_mpl_pos(**kwargs)[source]

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.
symbols

Return the array of symbols, if it has already been set.

Raises:KeyError – if the trajectory has not been set yet.
class aiida.orm.nodes.data.XyData(backend=None, user=None, computer=None, **kwargs)[source]

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.

_arrayandname_validator(array, name, units)[source]

Validates that the array is an numpy.ndarray and that the name is of type basestring. Raises InputValidationError if this not the case.

get_x()[source]

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()[source]

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

set_x(x_array, x_name, x_units)[source]

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)[source]

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

class aiida.orm.nodes.data.Bool(*args, **kwargs)[source]

Data sub class to represent a boolean value.

_type

alias of builtins.bool

class aiida.orm.nodes.data.CifData(ase=None, file=None, values=None, source=None, scan_type='standard', parse_policy='eager', **kwargs)[source]

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.

_get_object_ase()[source]

Converts CifData to ase.Atoms

Returns:an ase.Atoms object
_get_object_pycifrw()[source]

Converts CifData to PyCIFRW.CifFile

Returns:a PyCIFRW.CifFile object
_prepare_cif(main_file_name='')[source]

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.

_validate()[source]

Validates MD5 hash of CIF file.

ase

ASE object, representing the CIF.

Note

requires ASE module.

classmethod from_md5(md5)[source]

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.

generate_md5()[source]

Computes and returns MD5 hash of the CIF file.

get_ase(**kwargs)[source]

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.

get_formulae(mode='sum')[source]

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.

classmethod get_or_create(filename, use_first=False, store_cif=True)[source]

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.

get_spacegroup_numbers()[source]

Get the spacegroup international number.

get_structure(converter='pymatgen', store=False, **kwargs)[source]

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.

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
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.
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
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
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
parse(scan_type=None)[source]

Parses CIF file and sets attributes.

Parameters:scan_type – See set_scan_type
static read_cif(fileobj, index=-1, **kwargs)[source]

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.

set_ase(aseatoms)[source]

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

Parameters:aseatoms – the ASE atoms object
set_file(file)[source]

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.

set_parse_policy(parse_policy)[source]

Set the parse policy.

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

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_values(values)[source]

Set internal representation to values.

Warning: This also writes a new CIF file.

Parameters:values – PyCifRW CifFile object

Note

requires PyCifRW module.

store(*args, **kwargs)[source]

Store the node.

values

PyCifRW structure, representing the CIF datablocks.

Note

requires PyCifRW module.

class aiida.orm.nodes.data.Code(remote_computer_exec=None, local_executable=None, input_plugin_name=None, files=None, **kwargs)[source]

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

_set_local()[source]

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()[source]

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)

_validate()[source]

Perform validation of the Data object.

Note

validation of data source checks license and requires attribution to be provided in field ‘description’ of source in the case of any CC-BY* license. If such requirement is too strict, one can remove/comment it out.

can_run_on(computer)[source]

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.

full_label

Get full label of this code.

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

classmethod get(pk=None, label=None, machinename=None)[source]

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:
get_append_text()[source]

Return the postexec_code, or an empty string if no post-exec code was defined.

get_builder()[source]

Create and return a new ProcessBuilder for the default Calculation plugin, as obtained by the self.get_input_plugin_name() method.

Note:

it also sets the builder.code value.

Raises:
Returns:

classmethod get_code_helper(label, machinename=None)[source]
Parameters:
  • label – the code label identifying the code to load
  • machinename – the machine name where code is setup
Raises:
get_computer_name()[source]

Get name of this code’s computer.

get_description()[source]

Return a string description of this Code instance.

Returns:string description of this Code instance
get_execname()[source]

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.

classmethod get_from_string(code_string)[source]

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:
get_full_text_info(verbose=False)[source]

Return a (multiline) string with a human-readable detailed information on this computer

get_input_plugin_name()[source]

Return the name of the default input plugin (or None if no input plugin was set.

get_prepend_text()[source]

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.

hidden

Determines whether the Code is hidden or not

hide()[source]

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

is_local()[source]

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

classmethod list_for_plugin(plugin, labels=True)[source]

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.

relabel(new_label, raise_error=True)[source]

Relabel this code.

Parameters:
  • new_label – new code label
  • raise_error – Set to False in order to return a list of errors instead of raising them.
reveal()[source]

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

set_append_text(code)[source]

Pass a string of code that will be put in the scheduler script after the execution of the code.

set_files(files)[source]

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.
set_input_plugin_name(input_plugin)[source]

Set the name of the default input plugin, to be used for the automatic generation of a new calculation.

set_local_executable(exec_name)[source]

Set the filename of the local executable. Implicitly set the code as local.

set_prepend_text(code)[source]

Pass a string of code that will be put in the scheduler script before the execution of the code.

set_remote_computer_exec(remote_computer_exec)[source]

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.
class aiida.orm.nodes.data.Float(*args, **kwargs)[source]

Data sub class to represent a float value.

_type

alias of builtins.float

class aiida.orm.nodes.data.FolderData(backend=None, user=None, computer=None, **kwargs)[source]

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

class aiida.orm.nodes.data.Int(*args, **kwargs)[source]

Data sub class to represent an integer value.

_type

alias of builtins.int

class aiida.orm.nodes.data.List(**kwargs)[source]

Data sub class to represent a list.

_using_list_reference()[source]

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
append(value)[source]

S.append(value) – append value to the end of the sequence

count(value) → integer -- return number of occurrences of value[source]
extend(value)[source]

S.extend(iterable) – extend sequence by appending elements from the iterable

get_list()[source]

Return the contents of this node.

Returns:a list
index(value[, start[, stop]]) → integer -- return first index of value.[source]

Raises ValueError if the value is not present.

Supporting start and stop arguments is optional, but recommended.

insert(i, value)[source]

S.insert(index, value) – insert value before index

pop([index]) → item -- remove and return item at index (default last).[source]

Raise IndexError if list is empty or index is out of range.

remove(value)[source]

S.remove(value) – remove first occurrence of value. Raise ValueError if the value is not present.

reverse()[source]

S.reverse() – reverse IN PLACE

set_list(data)[source]

Set the contents of this node.

Parameters:data – the list to set
class aiida.orm.nodes.data.OrbitalData(backend=None, user=None, computer=None, **kwargs)[source]

Used for storing collections of orbitals, as well as providing methods for accessing them internally.

clear_orbitals()[source]

Remove all orbitals that were added to the class Cannot work if OrbitalData has been already stored

get_orbitals(**kwargs)[source]

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)[source]

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
class aiida.orm.nodes.data.Dict(**kwargs)[source]

Data sub class to represent a dictionary.

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.
get_dict()[source]

Return a dictionary with the parameters currently set.

Returns:dictionary
keys()[source]

Iterator of valid keys stored in the Dict object.

Returns:iterator over the keys of the current dictionary
set_dict(dictionary)[source]

Replace the current dictionary with another one.

Parameters:dictionary – dictionary to set
update_dict(dictionary)[source]

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
class aiida.orm.nodes.data.RemoteData(remote_path=None, **kwargs)[source]

Store a link to a file or folder on a remote machine.

Remember to pass a computer!

_clean()[source]

Remove all content of the remote folder on the remote computer

_validate()[source]

Perform validation of the Data object.

Note

validation of data source checks license and requires attribution to be provided in field ‘description’ of source in the case of any CC-BY* license. If such requirement is too strict, one can remove/comment it out.

getfile(relpath, destpath)[source]

Connects to the remote folder and gets a string with the (full) content of the file.

Parameters:
  • relpath – The relative path of the file to show.
  • destpath – A path on the local computer to get the file
Returns:

a string with the file content

is_empty

Check if remote folder is empty

listdir(relpath='.')[source]

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='.')[source]

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.
class aiida.orm.nodes.data.SinglefileData(file, **kwargs)[source]

Data class that can be used to store a single file in its repository.

_validate()[source]

Ensure that there is one object stored in the repository, whose key matches value set for filename attr.

filename

Return the name of the file stored.

Returns:the filename under which the file is stored in the repository
get_content()[source]

Return the content of the single file stored for this data node.

Returns:the content of the file as a string
open(key=None, mode='r')[source]

Return an open file handle to the content of this data node.

Parameters:
  • key – optional key within the repository, by default is the filename set in the attributes
  • mode – the mode with which to open the file handle (default: read mode)
Returns:

a file handle

set_file(file)[source]

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.StringIO(“my string”) to construct the file directly from a string.
class aiida.orm.nodes.data.Str(*args, **kwargs)[source]

Data sub class to represent a string value.

_type

alias of builtins.str

class aiida.orm.nodes.data.StructureData(cell=None, pbc=None, ase=None, pymatgen=None, pymatgen_structure=None, pymatgen_molecule=None, **kwargs)[source]

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.

_adjust_default_cell(vacuum_factor=1.0, vacuum_addition=10.0, pbc=(False, False, False))[source]

If the structure was imported from an xyz file, it lacks a defined cell, and the default cell is taken ([[1,0,0], [0,1,0], [0,0,1]]), leading to an unphysical definition of the structure. This method will adjust the cell

_get_object_ase()[source]

Converts StructureData to ase.Atoms

Returns:an ase.Atoms object
_get_object_phonopyatoms()[source]

Converts StructureData to PhonopyAtoms

Returns:a PhonopyAtoms object
_get_object_pymatgen(**kwargs)[source]

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_molecule(**kwargs)[source]

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)

_get_object_pymatgen_structure(**kwargs)[source]

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)

_parse_xyz(inputstring)[source]

Read the structure from a string of format XYZ.

_prepare_chemdoodle(main_file_name='')[source]

Write the given structure to a string of format required by ChemDoodle.

_prepare_cif(main_file_name='')[source]

Write the given structure to a string of format CIF.

_prepare_xsf(main_file_name='')[source]

Write the given structure to a string of format XSF (for XCrySDen).

_prepare_xyz(main_file_name='')[source]

Write the given structure to a string of format XYZ.

_validate()[source]

Performs some standard validation tests.

append_atom(**kwargs)[source]

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.

append_kind(kind)[source]

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)[source]

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.
cell

Returns the cell shape.

Returns:a 3x3 list of lists.
cell_angles

Get the angles between the cell lattice vectors in degrees.

cell_lengths

Get the lengths of cell lattice vectors in angstroms.

clear_kinds()[source]

Removes all kinds for the StructureData object.

Note

Also clear all sites!

clear_sites()[source]

Removes all sites for the StructureData object.

get_ase()[source]

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_cell_volume()[source]

Returns the cell volume in Angstrom^3.

Returns:a float.
get_cif(converter='ase', store=False, **kwargs)[source]

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_composition()[source]

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_description()[source]

Returns a string with infos retrieved from StructureData node’s properties

Parameters:self – the StructureData node
Returns:retsrt: the description string
get_dimensionality()[source]

This function checks the dimensionality of the structure and calculates its length/surface/volume :return: returns the dimensionality and length/surface/volume

get_formula(mode='hill', separator='')[source]

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_kind(kind_name)[source]

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()[source]

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.
get_pymatgen(**kwargs)[source]

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_molecule()[source]

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.
get_pymatgen_structure(**kwargs)[source]

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_site_kindnames()[source]

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_symbols_set()[source]

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.
has_vacancies

Return whether the structure has vacancies in the structure.

Returns:a boolean, True if at least one kind has a vacancy
is_alloy

Return whether the structure contains any alloy kinds.

Returns:a boolean, True if at least one kind is an alloy
kinds

Returns a list of kinds.

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)
reset_cell(new_cell)[source]

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)[source]

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:

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.

set_ase(aseatoms)[source]

Load the structure from a ASE object

set_pymatgen(obj, **kwargs)[source]

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)[source]

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)[source]

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.
sites

Returns a list of sites.

class aiida.orm.nodes.data.UpfData(file=None, source=None, **kwargs)[source]

Function not yet documented.

_validate()[source]

Ensure that there is one object stored in the repository, whose key matches value set for filename attr.

classmethod from_md5(md5)[source]

Return a list of all UPF pseudopotentials that match a given MD5 hash.

Note that the hash has to be stored in a _md5 attribute, otherwise the pseudo will not be found.

classmethod get_or_create(filepath, use_first=False, store_upf=True)[source]

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

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 (bool) – If false, the UpfData objects are not stored in the database. default=True.
Return (upf, created):
 

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

get_upf_family_names()[source]

Get the list of all upf family names to which the pseudo belongs.

classmethod get_upf_group(group_label)[source]

Return the UpfFamily group with the given name.

classmethod get_upf_groups(filter_elements=None, user=None)[source]

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. Default=None, meaning that all families are returned.
  • user – if None (default), return the groups for all users. If defined, it should be either a DbUser instance, or a string for the username (that is, the user email).
set_file(file)[source]

I pre-parse the file to store the attributes.

store(*args, **kwargs)[source]

Store the node, reparsing the file so that the md5 and the element are correctly reset.

class aiida.orm.nodes.data.NumericType(*args, **kwargs)[source]

Sub class of Data to store numbers, overloading common operators (+, *, …).

Structure

This module defines the classes for structures and all related functions to operate on them.

class aiida.orm.nodes.data.structure.StructureData(cell=None, pbc=None, ase=None, pymatgen=None, pymatgen_structure=None, pymatgen_molecule=None, **kwargs)[source]

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.

__init__(cell=None, pbc=None, ase=None, pymatgen=None, pymatgen_structure=None, pymatgen_molecule=None, **kwargs)[source]
Parameters:backend_entity (aiida.orm.implementation.BackendEntity) – the backend model supporting this entity
append_atom(**kwargs)[source]

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.

append_kind(kind)[source]

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)[source]

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.
cell

Returns the cell shape.

Returns:a 3x3 list of lists.
cell_angles

Get the angles between the cell lattice vectors in degrees.

cell_lengths

Get the lengths of cell lattice vectors in angstroms.

clear_kinds()[source]

Removes all kinds for the StructureData object.

Note

Also clear all sites!

clear_sites()[source]

Removes all sites for the StructureData object.

get_ase()[source]

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_cell_volume()[source]

Returns the cell volume in Angstrom^3.

Returns:a float.
get_cif(converter='ase', store=False, **kwargs)[source]

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_composition()[source]

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_description()[source]

Returns a string with infos retrieved from StructureData node’s properties

Parameters:self – the StructureData node
Returns:retsrt: the description string
get_dimensionality()[source]

This function checks the dimensionality of the structure and calculates its length/surface/volume :return: returns the dimensionality and length/surface/volume

get_formula(mode='hill', separator='')[source]

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_kind(kind_name)[source]

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()[source]

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.
get_pymatgen(**kwargs)[source]

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_molecule()[source]

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.
get_pymatgen_structure(**kwargs)[source]

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_site_kindnames()[source]

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_symbols_set()[source]

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.
has_vacancies

Return whether the structure has vacancies in the structure.

Returns:a boolean, True if at least one kind has a vacancy
is_alloy

Return whether the structure contains any alloy kinds.

Returns:a boolean, True if at least one kind is an alloy
kinds

Returns a list of kinds.

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)
reset_cell(new_cell)[source]

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)[source]

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:

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.

set_ase(aseatoms)[source]

Load the structure from a ASE object

set_pymatgen(obj, **kwargs)[source]

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)[source]

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)[source]

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.
sites

Returns a list of sites.

class aiida.orm.nodes.data.structure.Kind(**kwargs)[source]

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.

__init__(**kwargs)[source]

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.
compare_with(other_kind)[source]

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.
get_raw()[source]

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.
get_symbols_string()[source]

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!

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
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.
mass

The mass of this species kind.

Returns:a float
name

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

Returns:a string
reset_mass()[source]

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.

set_automatic_kind_name(tag=None)[source]

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.

set_symbols_and_weights(symbols, weights)[source]

Set the chemical symbols and the weights for the site.

Note

Note that the kind name remains unchanged.

symbol

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

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.

weights

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

class aiida.orm.nodes.data.structure.Site(**kwargs)[source]

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.

__init__(**kwargs)[source]

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_ase(kinds)[source]

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

get_raw()[source]

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.
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.

position

Return the position of this site in absolute coordinates, in angstrom.

Folder

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

class aiida.orm.nodes.data.folder.FolderData(backend=None, user=None, computer=None, **kwargs)[source]

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

Singlefile

Data class that can be used to store a single file in its repository.

class aiida.orm.nodes.data.singlefile.SinglefileData(file, **kwargs)[source]

Data class that can be used to store a single file in its repository.

filename

Return the name of the file stored.

Returns:the filename under which the file is stored in the repository
get_content()[source]

Return the content of the single file stored for this data node.

Returns:the content of the file as a string
open(key=None, mode='r')[source]

Return an open file handle to the content of this data node.

Parameters:
  • key – optional key within the repository, by default is the filename set in the attributes
  • mode – the mode with which to open the file handle (default: read mode)
Returns:

a file handle

set_file(file)[source]

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.StringIO(“my string”) to construct the file directly from a string.

Upf

This module manages the UPF pseudopotentials in the local repository.

class aiida.orm.nodes.data.upf.UpfData(file=None, source=None, **kwargs)[source]

Function not yet documented.

classmethod from_md5(md5)[source]

Return a list of all UPF pseudopotentials that match a given MD5 hash.

Note that the hash has to be stored in a _md5 attribute, otherwise the pseudo will not be found.

classmethod get_or_create(filepath, use_first=False, store_upf=True)[source]

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

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 (bool) – If false, the UpfData objects are not stored in the database. default=True.
Return (upf, created):
 

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

get_upf_family_names()[source]

Get the list of all upf family names to which the pseudo belongs.

classmethod get_upf_group(group_label)[source]

Return the UpfFamily group with the given name.

classmethod get_upf_groups(filter_elements=None, user=None)[source]

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. Default=None, meaning that all families are returned.
  • user – if None (default), return the groups for all users. If defined, it should be either a DbUser instance, or a string for the username (that is, the user email).
set_file(file)[source]

I pre-parse the file to store the attributes.

store(*args, **kwargs)[source]

Store the node, reparsing the file so that the md5 and the element are correctly reset.

Cif

Tools for handling Crystallographic Information Files (CIF)

class aiida.orm.nodes.data.cif.CifData(ase=None, file=None, values=None, source=None, scan_type='standard', parse_policy='eager', **kwargs)[source]

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.

ase

ASE object, representing the CIF.

Note

requires ASE module.

classmethod from_md5(md5)[source]

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.

generate_md5()[source]

Computes and returns MD5 hash of the CIF file.

get_ase(**kwargs)[source]

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.

get_formulae(mode='sum')[source]

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.

classmethod get_or_create(filename, use_first=False, store_cif=True)[source]

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.

get_spacegroup_numbers()[source]

Get the spacegroup international number.

get_structure(converter='pymatgen', store=False, **kwargs)[source]

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.

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
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.
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
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
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
parse(scan_type=None)[source]

Parses CIF file and sets attributes.

Parameters:scan_type – See set_scan_type
static read_cif(fileobj, index=-1, **kwargs)[source]

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.

set_ase(aseatoms)[source]

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

Parameters:aseatoms – the ASE atoms object
set_file(file)[source]

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.

set_parse_policy(parse_policy)[source]

Set the parse policy.

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

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_values(values)[source]

Set internal representation to values.

Warning: This also writes a new CIF file.

Parameters:values – PyCifRW CifFile object

Note

requires PyCifRW module.

store(*args, **kwargs)[source]

Store the node.

values

PyCifRW structure, representing the CIF datablocks.

Note

requires PyCifRW module.

aiida.orm.nodes.data.cif.cif_from_ase(ase, full_occupancies=False, add_fake_biso=False)[source]

Construct a CIF datablock from the ASE structure. The code is taken from https://wiki.fysik.dtu.dk/ase/epydoc/ase.io.cif-pysrc.html#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.nodes.data.cif.has_pycifrw()[source]
Returns:True if the PyCifRW module can be imported, False otherwise.
aiida.orm.nodes.data.cif.parse_formula(formula)[source]

Parses the Hill formulae, written with spaces for separators.

aiida.orm.nodes.data.cif.pycifrw_from_cif(datablocks, loops=None, names=None)[source]

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

Parameter

Data sub class to represent a dictionary.

class aiida.orm.nodes.data.dict.Dict(**kwargs)[source]

Data sub class to represent a dictionary.

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.
get_dict()[source]

Return a dictionary with the parameters currently set.

Returns:dictionary
keys()[source]

Iterator of valid keys stored in the Dict object.

Returns:iterator over the keys of the current dictionary
set_dict(dictionary)[source]

Replace the current dictionary with another one.

Parameters:dictionary – dictionary to set
update_dict(dictionary)[source]

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

Remote

class aiida.orm.nodes.data.remote.RemoteData(remote_path=None, **kwargs)[source]

Store a link to a file or folder on a remote machine.

Remember to pass a computer!

getfile(relpath, destpath)[source]

Connects to the remote folder and gets a string with the (full) content of the file.

Parameters:
  • relpath – The relative path of the file to show.
  • destpath – A path on the local computer to get the file
Returns:

a string with the file content

is_empty

Check if remote folder is empty

listdir(relpath='.')[source]

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='.')[source]

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.

OrbitalData

class aiida.orm.nodes.data.orbital.OrbitalData(backend=None, user=None, computer=None, **kwargs)[source]

Used for storing collections of orbitals, as well as providing methods for accessing them internally.

clear_orbitals()[source]

Remove all orbitals that were added to the class Cannot work if OrbitalData has been already stored

get_orbitals(**kwargs)[source]

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)[source]

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

ArrayData

Module with Node sub classes for array based data structures.

class aiida.orm.nodes.data.array.ArrayData(backend=None, user=None, computer=None, **kwargs)[source]

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.
clear_internal_cache()[source]

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.

delete_array(name)[source]

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_array(name)[source]

Return an array stored in the node

Parameters:name – The name of the array to return.
get_arraynames()[source]

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

get_iterarrays()[source]

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

New in version 1.0: Renamed from iterarrays

get_shape(name)[source]

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

Parameters:name – The name of the array.
initialize()[source]

Initialize internal variables for the backend node

This needs to be called explicitly in each specific subclass implementation of the init.

set_array(name, array)[source]

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.
class aiida.orm.nodes.data.array.BandsData(backend=None, user=None, computer=None, **kwargs)[source]

Class to handle bands data

array_labels

Get the labels associated with the band arrays

get_bands(also_occupations=False, also_labels=False)[source]

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

set_bands(bands, units=None, occupations=None, labels=None)[source]

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

set_kpointsdata(kpointsdata)[source]

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

show_mpl(**kwargs)[source]

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.

units

Units in which the data in bands were stored. A string

class aiida.orm.nodes.data.array.KpointsData(backend=None, user=None, computer=None, **kwargs)[source]

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.

cell

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

get_description()[source]

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

get_kpoints(also_weights=False, cartesian=False)[source]

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.
get_kpoints_mesh(print_list=False)[source]

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()
labels

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

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)
reciprocal_cell

Return the reciprocal cell in units of 1/Angstrom from the internally set cell

set_cell(cell, pbc=None)[source]

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]
set_cell_from_structure(structuredata)[source]

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_kpoints(kpoints, cartesian=False, labels=None, weights=None, fill_values=0)[source]

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.
set_kpoints_mesh(mesh, offset=None)[source]

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.].
set_kpoints_mesh_from_density(distance, offset=None, force_parity=False)[source]

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.

class aiida.orm.nodes.data.array.ProjectionData(backend=None, user=None, computer=None, **kwargs)[source]

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) >

get_pdos(**kwargs)[source]

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)[source]

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
get_reference_bandsdata()[source]

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
set_orbitals(**kwargs)[source]

This method is inherited from OrbitalData, but is blocked here. If used will raise a NotImplementedError

set_projectiondata(list_of_orbitals, list_of_projections=None, list_of_energy=None, list_of_pdos=None, tags=None, bands_check=True)[source]

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
set_reference_bandsdata(value)[source]

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
class aiida.orm.nodes.data.array.TrajectoryData(structurelist=None, **kwargs)[source]

Stores a trajectory (a sequence of crystal structures with timestamps, and possibly with velocities).

get_cells()[source]

Return the array of cells, if it has already been set.

Raises:KeyError – if the trajectory has not been set yet.
get_cif(index=None, **kwargs)[source]

Creates aiida.orm.nodes.data.cif.CifData

New in version 1.0: Renamed from _get_cif

get_index_from_stepid(stepid)[source]

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_positions()[source]

Return the array of positions, if it has already been set.

Raises:KeyError – if the trajectory has not been set yet.
get_step_data(index)[source]

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 were specified, None is returned as the last 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 \times 3 matrix, symbols is an array of length n, positions is a n \times 3 array, and velocities is either None or a n \times 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)[source]

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.
get_stepids()[source]

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_structure(store=False, **kwargs)[source]

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

New in version 1.0: Renamed from _get_aiida_structure

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.structure.StructureData node.

get_times()[source]

Return the array of times (in ps), if it has already been set.

Raises:KeyError – if the trajectory has not been set yet.
get_velocities()[source]

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

numsites

Return the number of stored sites, or zero if nothing has been stored yet.

numsteps

Return the number of stored steps, or zero if nothing has been stored yet.

set_structurelist(structurelist)[source]

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
set_trajectory(symbols, positions, stepids=None, cells=None, times=None, velocities=None)[source]

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.

Todo

Choose suitable units for velocities

show_mpl_heatmap(**kwargs)[source]

Show a heatmap of the trajectory with matplotlib.

show_mpl_pos(**kwargs)[source]

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.
symbols

Return the array of symbols, if it has already been set.

Raises:KeyError – if the trajectory has not been set yet.
class aiida.orm.nodes.data.array.XyData(backend=None, user=None, computer=None, **kwargs)[source]

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.

get_x()[source]

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()[source]

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

set_x(x_array, x_name, x_units)[source]

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)[source]

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

ArrayData subclasses

The following are Data classes inheriting from ArrayData.

KpointsData

Module of the KpointsData class, defining the AiiDA data type for storing lists and meshes of k-points (i.e., points in the reciprocal space of a periodic crystal structure).

class aiida.orm.nodes.data.array.kpoints.KpointsData(backend=None, user=None, computer=None, **kwargs)[source]

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.

_change_reference(kpoints, to_cartesian=True)[source]

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

_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

_set_cell(value)[source]

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

_set_labels(value)[source]

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

_set_pbc(value)[source]

validate the pbc, then store them

_validate_kpoints_weights(kpoints, weights)[source]

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

cell

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

get_description()[source]

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

get_kpoints(also_weights=False, cartesian=False)[source]

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.
get_kpoints_mesh(print_list=False)[source]

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()
labels

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

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)
reciprocal_cell

Return the reciprocal cell in units of 1/Angstrom from the internally set cell

set_cell(cell, pbc=None)[source]

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]
set_cell_from_structure(structuredata)[source]

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_kpoints(kpoints, cartesian=False, labels=None, weights=None, fill_values=0)[source]

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.
set_kpoints_mesh(mesh, offset=None)[source]

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.].
set_kpoints_mesh_from_density(distance, offset=None, force_parity=False)[source]

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.

BandsData

This module defines the classes related to band structures or dispersions in a Brillouin zone, and how to operate on them.

class aiida.orm.nodes.data.array.bands.BandsData(backend=None, user=None, computer=None, **kwargs)[source]

Class to handle bands data

array_labels

Get the labels associated with the band arrays

get_bands(also_occupations=False, also_labels=False)[source]

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

set_bands(bands, units=None, occupations=None, labels=None)[source]

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

set_kpointsdata(kpointsdata)[source]

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

show_mpl(**kwargs)[source]

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.

units

Units in which the data in bands were stored. A string

aiida.orm.nodes.data.array.bands.find_bandgap(bandsdata, number_electrons=None, fermi_energy=None)[source]

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

ProjectionData

class aiida.orm.nodes.data.array.projection.ProjectionData(backend=None, user=None, computer=None, **kwargs)[source]

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) >

get_pdos(**kwargs)[source]

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)[source]

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
get_reference_bandsdata()[source]

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
set_orbitals(**kwargs)[source]

This method is inherited from OrbitalData, but is blocked here. If used will raise a NotImplementedError

set_projectiondata(list_of_orbitals, list_of_projections=None, list_of_energy=None, list_of_pdos=None, tags=None, bands_check=True)[source]

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
set_reference_bandsdata(value)[source]

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

TrajectoryData

AiiDA class to deal with crystal structure trajectories.

class aiida.orm.nodes.data.array.trajectory.TrajectoryData(structurelist=None, **kwargs)[source]

Stores a trajectory (a sequence of crystal structures with timestamps, and possibly with velocities).

get_cells()[source]

Return the array of cells, if it has already been set.

Raises:KeyError – if the trajectory has not been set yet.
get_cif(index=None, **kwargs)[source]

Creates aiida.orm.nodes.data.cif.CifData

New in version 1.0: Renamed from _get_cif

get_index_from_stepid(stepid)[source]

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_positions()[source]

Return the array of positions, if it has already been set.

Raises:KeyError – if the trajectory has not been set yet.
get_step_data(index)[source]

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 were specified, None is returned as the last 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 \times 3 matrix, symbols is an array of length n, positions is a n \times 3 array, and velocities is either None or a n \times 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)[source]

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.
get_stepids()[source]

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_structure(store=False, **kwargs)[source]

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

New in version 1.0: Renamed from _get_aiida_structure

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.structure.StructureData node.

get_times()[source]

Return the array of times (in ps), if it has already been set.

Raises:KeyError – if the trajectory has not been set yet.
get_velocities()[source]

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

numsites

Return the number of stored sites, or zero if nothing has been stored yet.

numsteps

Return the number of stored steps, or zero if nothing has been stored yet.

set_structurelist(structurelist)[source]

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
set_trajectory(symbols, positions, stepids=None, cells=None, times=None, velocities=None)[source]

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.

Todo

Choose suitable units for velocities

show_mpl_heatmap(**kwargs)[source]

Show a heatmap of the trajectory with matplotlib.

show_mpl_pos(**kwargs)[source]

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.
symbols

Return the array of symbols, if it has already been set.

Raises:KeyError – if the trajectory has not been set yet.
aiida.orm.nodes.data.array.trajectory.plot_positions_XYZ(times, positions, indices_to_show, color_list, label, positions_unit='A', times_unit='ps', dont_block=False, mintime=None, maxtime=None, label_sparsity=10)[source]

Plot with matplotlib the positions of the coordinates of the atoms over time for a trajectory

Parameters:
  • times – array of times
  • positions – array of positions
  • indices_to_show – list of indices of to show (0, 1, 2 for X, Y, Z)
  • color_list – list of valid color specifications for matplotlib
  • label – label for this plot to put in the title
  • positions_unit – label for the units of positions (for the x label)
  • times_unit – label for the units of times (for the y label)
  • dont_block – passed to plt.show() as block=not dont_block
  • mintime – if specified, cut the time axis at the specified min value
  • maxtime – if specified, cut the time axis at the specified max value
  • label_sparsity – how often to put a label with the pair (t, coord)

XyData

This module defines the classes related to Xy data. That is data that contains collections of y-arrays bound to a single x-array, and the methods to operate on them.

class aiida.orm.nodes.data.array.xy.XyData(backend=None, user=None, computer=None, **kwargs)[source]

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.

get_x()[source]

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()[source]

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

set_x(x_array, x_name, x_units)[source]

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)[source]

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

aiida.orm.nodes.data.array.xy.check_convert_single_to_tuple(item)[source]

Checks if the item is a list or tuple, and converts it to a list if it is not already a list or tuple

Parameters:item – an object which may or may not be a list or tuple
Returns:item_list: the input item unchanged if list or tuple and [item] otherwise

Base data types

BaseType and NumericType

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

class aiida.orm.nodes.data.base.BaseType(*args, **kwargs)[source]

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

aiida.orm.nodes.data.base.to_aiida_type(value)[source]

Turns basic Python types (str, int, float, bool) into the corresponding AiiDA types.

List

class aiida.orm.nodes.data.list.List(**kwargs)[source]

Data sub class to represent a list.

append(value)[source]

S.append(value) – append value to the end of the sequence

count(value) → integer -- return number of occurrences of value[source]
extend(value)[source]

S.extend(iterable) – extend sequence by appending elements from the iterable

get_list()[source]

Return the contents of this node.

Returns:a list
index(value[, start[, stop]]) → integer -- return first index of value.[source]

Raises ValueError if the value is not present.

Supporting start and stop arguments is optional, but recommended.

insert(i, value)[source]

S.insert(index, value) – insert value before index

pop([index]) → item -- remove and return item at index (default last).[source]

Raise IndexError if list is empty or index is out of range.

remove(value)[source]

S.remove(value) – remove first occurrence of value. Raise ValueError if the value is not present.

reverse()[source]

S.reverse() – reverse IN PLACE

set_list(data)[source]

Set the contents of this node.

Parameters:data – the list to set

Bool

Data sub class to represent a boolean value.

class aiida.orm.nodes.data.bool.Bool(*args, **kwargs)[source]

Data sub class to represent a boolean value.

Float

Data sub class to represent a float value.

class aiida.orm.nodes.data.float.Float(*args, **kwargs)[source]

Data sub class to represent a float value.

Int

Data sub class to represent an integer value.

class aiida.orm.nodes.data.int.Int(*args, **kwargs)[source]

Data sub class to represent an integer value.

Str

Data sub class to represent a string value.

class aiida.orm.nodes.data.str.Str(*args, **kwargs)[source]

Data sub class to represent a string value.

ORM documentation: Calculations

Note

This list only includes the classes included in AiiDA-core. For all the plugin subclasses, check the corresponding plugin repositories.

Module with Node sub classes for processes.

class aiida.orm.nodes.process.CalculationNode(backend=None, user=None, computer=None, **kwargs)[source]

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

inputs

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.

Returns:NodeLinksManager
outputs

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.

Returns:NodeLinksManager
class aiida.orm.nodes.process.CalcFunctionNode(backend=None, user=None, computer=None, **kwargs)[source]

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

validate_outgoing(target, link_type, link_label)[source]

Validate adding a link of the given type from ourself to a given node.

A calcfunction cannot return Data, so if we receive an outgoing link to a stored Data node, that means the user created a Data node within our function body and stored it themselves or they are returning an input node. The latter use case is reserved for @workfunctions, as they can have RETURN links.

Parameters:
  • target – the node to which the link is going
  • link_type – the link type
  • link_label – the link label
Raises:
  • TypeError – if target is not a Node instance or link_type is not a LinkType enum
  • ValueError – if the proposed link is invalid
class aiida.orm.nodes.process.CalcJobNode(backend=None, user=None, computer=None, **kwargs)[source]

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

delete_state()[source]

Delete the calculation job state attribute if it exists.

get_authinfo()[source]

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

Returns:AuthInfo
get_builder_restart()[source]

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.

Returns:~aiida.engine.processes.builder.ProcessBuilder instance
get_description()[source]

Return a string with a description of the node based on its properties.

get_hash(ignore_errors=True, ignored_folder_content=('raw_input', ), **kwargs)[source]

Return the hash for this node based on its attributes.

get_job_id()[source]

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

Returns:the string representation of the scheduler job id
get_last_job_info()[source]

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

Returns:a JobInfo object (that closely resembles a dictionary) or None.
get_option(name)[source]

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
get_options()[source]

Return the dictionary of options set for this CalcJobNode

Returns:dictionary of the options and their values
get_parser_class()[source]

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.
get_remote_workdir()[source]

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

Returns:a string with the remote path
get_retrieve_list()[source]

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

Returns:a list of file directives
get_retrieve_singlefile_list()[source]

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

Returns:list of single file retrieval directives

Deprecated since version 1.0.0: Will be removed in v2.0.0, use aiida.orm.nodes.process.calculation.calcjob.CalcJobNode.get_retrieve_temporary_list() instead.

get_retrieve_temporary_list()[source]

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

Returns:a list of file directives
get_retrieved_node()[source]

Return the retrieved data folder.

Returns:the retrieved FolderData node or None if not found
get_scheduler_lastchecktime()[source]

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
get_scheduler_state()[source]

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

Returns:a JobState enum instance.
get_scheduler_stderr()[source]

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

Returns:scheduler stdout output or None
get_scheduler_stdout()[source]

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

Returns:scheduler stderr output or None
get_state()[source]

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
get_transport()[source]

Return the transport for this calculation.

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

Return the link label used for the retrieved FolderData node.

res

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.
set_job_id(job_id)[source]

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
set_last_job_info(last_job_info)[source]

Set the last job info.

Parameters:last_job_info – a JobInfo object
set_option(name, value)[source]

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

set_options(options)[source]

Set the options for this CalcJobNode

Parameters:options – dictionary of option and their values to set
set_remote_workdir(remote_workdir)[source]

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
set_retrieve_list(retrieve_list)[source]

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
set_retrieve_singlefile_list(retrieve_singlefile_list)[source]

Set the retrieve singlefile list.

The files will be stored as SinglefileData instances and added as output nodes to this calculation node. The format of a single file directive is a tuple or list of length 3 with the following entries:

  1. the link label under which the file should be added
  2. the SinglefileData class or sub class to use to store
  3. the filepath relative to the remote working directory of the calculation
Parameters:retrieve_singlefile_list – list or tuple of single file directives

Deprecated since version 1.0.0: Will be removed in v2.0.0. Use set_retrieve_temporary_list() instead.

set_retrieve_temporary_list(retrieve_temporary_list)[source]

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
set_scheduler_state(state)[source]

Set the scheduler state.

Parameters:state – an instance of JobState
set_state(state)[source]

Set the calculation active job state.

Parameters:state – a string with the state from aiida.common.datastructures.CalcJobState.
Raise:ValueError if state is invalid
tools

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
class aiida.orm.nodes.process.ProcessNode(backend=None, user=None, computer=None, **kwargs)[source]

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.

called

Return a list of nodes that the process called

Returns:list of process nodes called by this process
called_descendants

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.

caller

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
checkpoint

Return the checkpoint bundle set for the process

Returns:checkpoint bundle if it exists, None otherwise
delete_checkpoint()[source]

Delete the checkpoint bundle set for the process

exception

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
exit_message

Return the exit message of the process

Returns:the exit message
exit_status

Return the exit status of the process

Returns:the exit status, an integer exit code or None
get_builder_restart()[source]

Return a ProcessBuilder that is ready to relaunch the process 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.

Returns:~aiida.engine.processes.builder.ProcessBuilder instance
is_excepted

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
is_failed

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
is_finished

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
is_finished_ok

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
is_killed

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
is_terminated

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
is_valid_cache

Return whether the node is valid for caching

Returns:True if this process node is valid to be used for caching, False otherwise
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
pause()[source]

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.

paused

Return whether the process is paused

Returns:True if the Calculation is marked as paused, False otherwise
process_class

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
process_label

Return the process label

Returns:the process label
process_state

Return the process state

Returns:the process state instance of ProcessState enum
process_status

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_checkpoint(checkpoint)[source]

Set the checkpoint bundle set for the process

Parameters:state – string representation of the stepper state info
set_exception(exception)[source]

Set the exception of the process

Parameters:exception – the exception message
set_exit_message(message)[source]

Set the exit message of the process, if None nothing will be done

Parameters:message – a string message
set_exit_status(status)[source]

Set the exit status of the process

Parameters:state – an integer exit code or None, which will be interpreted as zero
set_process_label(label)[source]

Set the process label

Parameters:label – process label string
set_process_state(state)[source]

Set the process state

Parameters:state – value or instance of ProcessState enum
set_process_status(status)[source]

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
set_process_type(process_type_string)[source]

Set the process type string.

Parameters:process_type – the process type string identifying the class using this process node as storage.
unpause()[source]

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.

validate_incoming(source, link_type, link_label)[source]

Validate adding a link of the given type from a given node to ourself.

Adding an input link to a ProcessNode once it is stored is illegal because this should be taken care of by the engine in one go. If a link is being added after the node is stored, it is most likely not by the engine and it should not be allowed.

Parameters:
  • source – the node from which the link is coming
  • link_type – the link type
  • link_label – the link label
Raises:
  • TypeError – if source is not a Node instance or link_type is not a LinkType enum
  • ValueError – if the proposed link is invalid
class aiida.orm.nodes.process.WorkflowNode(backend=None, user=None, computer=None, **kwargs)[source]

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

inputs

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
outputs

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
validate_outgoing(target, link_type, link_label)[source]

Validate adding a link of the given type from ourself to a given node.

A workflow cannot ‘create’ Data, so if we receive an outgoing link to an unstored Data node, that means the user created a Data node within our function body and tries to attach it as an output. This is strictly forbidden and can cause provenance to be lost.

Parameters:
  • target – the node to which the link is going
  • link_type – the link type
  • link_label – the link label
Raises:
  • TypeError – if target is not a Node instance or link_type is not a LinkType enum
  • ValueError – if the proposed link is invalid
class aiida.orm.nodes.process.WorkChainNode(backend=None, user=None, computer=None, **kwargs)[source]

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

set_stepper_state_info(stepper_state_info)[source]

Set the stepper state info

Parameters:state – string representation of the stepper state info
stepper_state_info

Return the stepper state info

Returns:string representation of the stepper state info
class aiida.orm.nodes.process.WorkFunctionNode(backend=None, user=None, computer=None, **kwargs)[source]

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

validate_outgoing(target, link_type, link_label)[source]

Validate adding a link of the given type from ourself to a given node.

A workfunction cannot create Data, so if we receive an outgoing RETURN link to an unstored Data node, that means the user created a Data node within our function body and is trying to return it. This use case should be reserved for @calcfunctions, as they can have CREATE links.

Parameters:
  • target – the node to which the link is going
  • link_type – the link type
  • link_label – the link label
Raises:
  • TypeError – if target is not a Node instance or link_type is not a LinkType enum
  • ValueError – if the proposed link is invalid

Module with Node sub class for calculation job processes.

class aiida.orm.nodes.process.calculation.calcjob.CalcJobNode(backend=None, user=None, computer=None, **kwargs)[source]

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

delete_state()[source]

Delete the calculation job state attribute if it exists.

get_authinfo()[source]

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

Returns:AuthInfo
get_builder_restart()[source]

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.

Returns:~aiida.engine.processes.builder.ProcessBuilder instance
get_description()[source]

Return a string with a description of the node based on its properties.

get_hash(ignore_errors=True, ignored_folder_content=('raw_input', ), **kwargs)[source]

Return the hash for this node based on its attributes.

get_job_id()[source]

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

Returns:the string representation of the scheduler job id
get_last_job_info()[source]

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

Returns:a JobInfo object (that closely resembles a dictionary) or None.
get_option(name)[source]

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
get_options()[source]

Return the dictionary of options set for this CalcJobNode

Returns:dictionary of the options and their values
get_parser_class()[source]

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.
get_remote_workdir()[source]

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

Returns:a string with the remote path
get_retrieve_list()[source]

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

Returns:a list of file directives
get_retrieve_singlefile_list()[source]

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

Returns:list of single file retrieval directives

Deprecated since version 1.0.0: Will be removed in v2.0.0, use aiida.orm.nodes.process.calculation.calcjob.CalcJobNode.get_retrieve_temporary_list() instead.

get_retrieve_temporary_list()[source]

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

Returns:a list of file directives
get_retrieved_node()[source]

Return the retrieved data folder.

Returns:the retrieved FolderData node or None if not found
get_scheduler_lastchecktime()[source]

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
get_scheduler_state()[source]

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

Returns:a JobState enum instance.
get_scheduler_stderr()[source]

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

Returns:scheduler stdout output or None
get_scheduler_stdout()[source]

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

Returns:scheduler stderr output or None
get_state()[source]

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
get_transport()[source]

Return the transport for this calculation.

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

Return the link label used for the retrieved FolderData node.

res

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.
set_job_id(job_id)[source]

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
set_last_job_info(last_job_info)[source]

Set the last job info.

Parameters:last_job_info – a JobInfo object
set_option(name, value)[source]

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

set_options(options)[source]

Set the options for this CalcJobNode

Parameters:options – dictionary of option and their values to set
set_remote_workdir(remote_workdir)[source]

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
set_retrieve_list(retrieve_list)[source]

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
set_retrieve_singlefile_list(retrieve_singlefile_list)[source]

Set the retrieve singlefile list.

The files will be stored as SinglefileData instances and added as output nodes to this calculation node. The format of a single file directive is a tuple or list of length 3 with the following entries:

  1. the link label under which the file should be added
  2. the SinglefileData class or sub class to use to store
  3. the filepath relative to the remote working directory of the calculation
Parameters:retrieve_singlefile_list – list or tuple of single file directives

Deprecated since version 1.0.0: Will be removed in v2.0.0. Use set_retrieve_temporary_list() instead.

set_retrieve_temporary_list(retrieve_temporary_list)[source]

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
set_scheduler_state(state)[source]

Set the scheduler state.

Parameters:state – an instance of JobState
set_state(state)[source]

Set the calculation active job state.

Parameters:state – a string with the state from aiida.common.datastructures.CalcJobState.
Raise:ValueError if state is invalid
tools

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

TemplateReplacer

Implementation of CalcJobNode to replace a template for testing and demonstration purposes.

class aiida.calculations.plugins.templatereplacer.TemplatereplacerCalculation(*args, **kwargs)[source]

Simple stub of a plugin that can be used to replace some text in a given template. Can be used for many different codes, or as a starting point to develop a new plugin.

This simple plugin takes two node inputs, both of type Dict, with the labels ‘parameters’ and ‘template’

You can also add other SinglefileData nodes as input, that will be copied according to what is written in ‘template’ (see below).

  • parameters: a set of parameters that will be used for substitution.

  • template: can contain the following parameters:

    • input_file_template: a string with substitutions to be managed with the format() function of python, i.e. if you want to substitute a variable called ‘varname’, you write {varname} in the text. See http://www.python.org/dev/peps/pep-3101/ for more details. The replaced file will be the input file.
    • input_file_name: a string with the file name for the input. If it is not provided, no file will be created.
    • output_file_name: a string with the file name for the output. If it is not provided, no redirection will be done and the output will go in the scheduler output file.
    • cmdline_params: a list of strings, to be passed as command line parameters. Each one is substituted with the same rule of input_file_template. Optional
    • input_through_stdin: if True, the input file name is passed via stdin. Default is False if missing.
    • files_to_copy: if defined, a list of tuple pairs, with format (‘link_name’, ‘dest_rel_path’);
      for each tuple, an input link to this calculation is looked for, with link labeled ‘link_label’, and with file type ‘Singlefile’, and the content is copied to a remote file named ‘dest_rel_path’ Errors are raised in the input links are non-existent, or of the wrong type, or if there are unused input files.
    • retrieve_temporary_files: a list of relative filepaths, that if defined, will be retrieved and
      temporarily stored in an unstored FolderData node that will be available during the Parser.parser_with_retrieved call under the key specified by the Parser.retrieved_temporary_folder key
prepare_for_submission(folder)[source]

This is the routine to be called when you want to create the input files and related stuff with a plugin.

Parameters:folder – a aiida.common.folders.Folder subclass where the plugin should put all its files.