ORM documentation: generic aiida.orm

This section describes the aiida object-relational mapping.

Some generic methods of the module aiida.orm.utils

class aiida.orm.utils.BackendDelegateWithDefault(backend)[source]

This class is a helper to implement the delegation pattern [1] by delegating functionality (i.e. calling through) to the backend class which will do the actual work.

[1] https://en.wikipedia.org/wiki/Delegation_pattern

aiida.orm.utils.CalculationFactory(module, from_abstract=False)[source]

Return a suitable JobCalculation subclass.

Parameters:
  • module – a valid string recognized as a Calculation plugin
  • from_abstract – A boolean. If False (default), actually look only to subclasses of JobCalculation, not to the base Calculation class. If True, check for valid strings for plugins of the Calculation base class.
aiida.orm.utils.DataFactory(module)[source]

Return a suitable Data subclass.

aiida.orm.utils.WorkflowFactory(module)[source]

Return a suitable Workflow subclass.

aiida.orm.utils.create_node_id_qb(node_id=None, pk=None, uuid=None, parent_class=None, query_with_dashes=True)[source]

Returns the QueryBuilder instance set to retrieve AiiDA objects given their (parent)class and PK (in which case the object should be unique) or UUID or UUID starting pattern.

Parameters:
  • node_id – PK (integer) or UUID (string) or a node
  • pk – PK of a node
  • uuid – UUID of a node, or the beginning of the uuid
  • parent_class – if specified, looks only among objects that are instances of a subclass of parent_class, otherwise among nodes
  • query_with_dashes (bool) – Specific if uuid is passed, allows to put the uuid in the correct form. Default=True
Returns:

a QueryBuilder instance

aiida.orm.utils.load_node(node_id=None, pk=None, uuid=None, parent_class=None, query_with_dashes=True)[source]

Returns an AiiDA node given its PK or UUID.

Parameters:
  • node_id – PK (integer) or UUID (string) or a node
  • pk – PK of a node
  • uuid – UUID of a node, or the beginning of the uuid
  • parent_class – if specified, checks whether the node loaded is a subclass of parent_class
  • query_with_dashes (bool) – Specific if uuid is passed, allows to put the uuid in the correct form. Default=True
  • return_node (bool) – lets the function return the AiiDA node referred by the input. Default=False
Returns:

the required AiiDA node if existing, unique, and (sub)instance of parent_class

Raises:
aiida.orm.utils.load_workflow(wf_id=None, pk=None, uuid=None)[source]

Return an AiiDA workflow given PK or UUID.

Parameters:
  • wf_id – PK (integer) or UUID (string) or UUID instance or a workflow
  • pk – PK of a workflow
  • uuid – UUID of a workflow
Returns:

an AiiDA workflow

Raises:

ValueError if none or more than one of parameters is supplied or type of wf_id is neither string nor integer

Computer

class aiida.orm.implementation.general.computer.AbstractComputer(**kwargs)[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(), in general attributes cannot be changed, except for those listed in the self._updatable_attributes tuple (empty for this class, can be extended in a subclass).

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.

copy()[source]

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

full_text_info

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

classmethod get(computer)[source]

Return a computer from its name (or from another Computer or DbComputer instance)

static get_db_columns()[source]

This method returns a list with the column names and types of the table corresponding to this class. :return: a list with the names of the columns

get_dbauthinfo(user)[source]

Return the aiida.backends.djsite.db.models.DbAuthInfo instance for the given user on this computer, if the computer is not configured for the given user.

Parameters:user – a DbUser instance.
Returns:a aiida.backends.djsite.db.models.DbAuthInfo instance
Raises:NotExistent – if the computer is not configured for the given user.
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_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.

id

Return the principal key in the DB.

is_user_configured(user)[source]

Return True if the computer is configured for the given user, False otherwise.

Parameters:user – a DbUser instance.
Returns:a boolean.
is_user_enabled(user)[source]

Return True if the computer is enabled for the given user (looking only at the per-user setting: the computer could still be globally disabled).

Note:Return False also if the user is not configured for the computer.
Parameters:user – a DbUser instance.
Returns:a boolean.
classmethod list_names()[source]

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

pk

Return the principal key in the DB.

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

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

uuid

Return the UUID in the DB.

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!

Node

class aiida.orm.implementation.general.node.AbstractNode(**kwargs)[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(), in general attributes cannot be changed, except for those listed in the self._updatable_attributes tuple (empty for this class, can be extended in a subclass).

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.

__del__()[source]

Called only upon real object destruction from memory I just try to remove junk, whenever possible; do not trust too much this function!

__init__(**kwargs)[source]

Initialize the object Node.

Parameters:uuid – if present, the Node with given uuid is loaded from the database. (It is not possible to assign a uuid to a new Node.)
class __metaclass__[source]

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

AbstractNode.__weakref__

list of weak references to the object (if defined)

Add a link in the cache.

Add a link to the current node from the ‘src’ node. Both nodes must be a Node instance (or a subclass of Node)

Note:

this function should not be called directly; it acts directly on the database.

Parameters:
  • src – the source object
  • label (str) – the name of the label to set the link from src. Default = None.
AbstractNode._check_are_parents_stored()[source]

Check if all parents are already stored, otherwise raise.

Raises:ModificationNotAllowed – if one of the input nodes in not already stored.
AbstractNode._db_attrs()[source]

Returns the keys of the attributes as a generator, directly from the DB.

DO NOT USE DIRECTLY.

AbstractNode._db_iterattrs()[source]

Iterator over the attributes (directly in the DB!)

DO NOT USE DIRECTLY.

AbstractNode._del_all_attrs()[source]

Delete all attributes associated to this node.

Raises:ModificationNotAllowed – if the Node was already stored.
AbstractNode._del_attr(key)[source]

Delete an attribute.

Parameters:

key – attribute to delete.

Raises:
AbstractNode._del_db_attr(key)[source]

Delete an attribute directly from the DB

DO NOT USE DIRECTLY.

Parameters:key – The key of the attribute to delete
AbstractNode._del_db_extra(key)[source]

Delete an extra, directly on the DB.

DO NOT USE DIRECTLY.

Parameters:key (str) – key name
AbstractNode._get_db_attr(key)[source]

Return the attribute value, directly from the DB.

DO NOT USE DIRECTLY.

Parameters:key – the attribute key
Returns:the attribute value
Raises:AttributeError – if the attribute does not exist.
AbstractNode._get_db_extra(key)[source]

Get an extra, directly from the DB.

DO NOT USE DIRECTLY.

Parameters:key (str) – key name
Returns:the key value
Raises:AttributeError – if the key does not exist

Return a list of tuples (label, aiida_class) for each input link, possibly filtering only by those of a given type.

Parameters:link_type – if not None, a link type to filter results
Returns:a list of tuples (label, aiida_class)

Return a list of tuples (label, aiida_class) for each output link, possibly filtering only by those of a given type.

Parameters:link_type – if not None, a link type to filter results
Returns:a list of tuples (label, aiida_class)
AbstractNode._get_dbcomments(pk=None)[source]

Return a sorted list of DbComment associated with the Node.

Parameters:pk – integer or list of integers. If it is specified, returns the comment values with desired pks. (pk refers to DbComment.pk)
Returns:the list of DbComment, sorted by pk.
AbstractNode._get_folder_pathsubfolder

Get the subfolder in the repository.

Returns:a Folder object.
AbstractNode._get_temp_folder()[source]

Get the folder of the Node in the temporary repository.

Returns:a SandboxFolder object mapping the node in the repository.

Return True if there is at least one cached (input) link, that is a link that is not stored yet in the database. False otherwise.

AbstractNode._increment_version_number_db()[source]

This function increments the version number in the DB. This should be called every time you need to increment the version (e.g. on adding a extra or attribute).

Note:Do not manually increment the version number, because if two different threads are adding/changing an attribute concurrently, the version number would be incremented only once.
AbstractNode._init_internal_params()[source]

Set here the default values for this class; this method is automatically called by the init.

Note:if you inherit this function, ALWAYS remember to call super()._init_internal_params() as the first thing in your inherited function.
AbstractNode._linking_as_output(dest, link_type)[source]

Raise a ValueError if a link from self to dest is not allowed. Implement in subclasses.

Parameters:dest – the destination output Node
Returns:a boolean (True)
AbstractNode._remove_comment(comment_pk, user)[source]

Function called by verdi comment remove

Remove from the DB the input link with the given label.

Note:

this function should not be called directly; it acts directly on the database.

Note:

No checks are done to verify that the link actually exists.

Parameters:
  • label (str) – the label of the link from src to the current Node
  • link_type – The type of link, must be one of the enum values form LinkType

Remove from the DB the input link with the given label.

Note:

In subclasses, change only this. Moreover, remember to call the super() method in order to properly use the caching logic!

Note:

No error is raised if the link does not exist.

Parameters:
  • label (str) – the name of the label to set the link from src.
  • link_type – The type of link, must be one of the enum values form LinkType

Replace an input link with the given label and type, or simply creates it if it does not exist.

Note:

this function should not be called directly; it acts directly on the database.

Parameters:
  • src (str) – the source object.
  • label (str) – the label of the link from src to the current Node
  • link_type – The type of link, must be one of the enum values form LinkType

Replace an input link with the given label, or simply creates it if it does not exist.

Note:

In subclasses, change only this. Moreover, remember to call the super() method in order to properly use the caching logic!

Parameters:
  • src – the source object
  • label (str) – the name of the label to set the link from src.
AbstractNode._repository_folder

Get the permanent repository folder. Use preferentially the folder property.

Returns:the permanent RepositoryFolder object
AbstractNode._reset_db_extras(new_extras)[source]

Resets the extras (replacing existing ones) directly in the DB

DO NOT USE DIRECTLY!

Parameters:new_extras – dictionary with new extras
AbstractNode._set_attr(key, value)[source]

Set a new attribute to the Node (in the DbAttribute table).

Parameters:
  • key (str) – key name
  • value – its value
Raises:
  • ModificationNotAllowed – if such attribute cannot be added (e.g. because the node was already stored, and the attribute is not listed as updatable).
  • ValidationError – if the key is not valid (e.g. it contains the separator symbol).
AbstractNode._set_db_attr(key, value)[source]

Set the value directly in the DB, without checking if it is stored, or using the cache.

DO NOT USE DIRECTLY.

Parameters:
  • key (str) – key name
  • value – its value
AbstractNode._set_db_computer(computer)[source]

Set the computer directly inside the dbnode member, in the DB.

DO NOT USE DIRECTLY.

Parameters:computer – the computer object
AbstractNode._set_db_extra(key, value, exclusive)[source]

Store extra directly in the DB, without checks.

DO NOT USE DIRECTLY.

Parameters:
  • key – key name
  • value – key value
  • exclusive – (default=False). If exclusive is True, it raises a UniquenessError if an Extra with the same name already exists in the DB (useful e.g. to “lock” a node and avoid to run multiple times the same computation on it).
AbstractNode._set_defaults

Default values to set in the __init__, if no value is explicitly provided for the given key. It is a dictionary, with k=v; if the key k is not provided to the __init__, and a value is present here, this is set.

AbstractNode._set_internal(arguments, allow_hidden=False)[source]

Works as self.set(), but takes a dictionary as the ‘arguments’ variable, instead of reading it from the kwargs; moreover, it allows to specify allow_hidden to True. In this case, if a a key starts with and underscore, as for instance _state, it will not call the function set__state but rather _set_state.

AbstractNode._set_with_defaults(**kwargs)[source]

Calls the set() method, but also adds the class-defined default values (defined in the self._set_defaults attribute), if they are not provided by the user.

Note:for the default values, also allow to define ‘hidden’ methods, meaning that if a default value has a key “_state”, it will not call the function “set__state” but rather “_set_state”. This is not allowed, instead, for the standard set() method.

Store all input links that are in the local cache, transferring them to the DB.

Note:This can be called only if all parents are already stored.
Note:Links are stored only after the input nodes are stored. Moreover, link storage is done in a transaction, and if one of the links cannot be stored, an exception is raised and all links will remain in the cache.
Note:This function can be called only after the node is stored. After that, it can be called multiple times, and nothing will be executed if no links are still in the cache.
Parameters:with_transaction – if False, no transaction is used. This is meant to be used ONLY if the outer calling function has already a transaction open!
AbstractNode._store_input_nodes()[source]

Find all input nodes, and store them, checking that they do not have unstored inputs in turn.

Note:this function stores all nodes without transactions; always call it from within a transaction!
AbstractNode._update_comment(new_field, comment_pk, user)[source]

Function called by verdi comment update

AbstractNode._update_db_description_field(field_value)[source]

Update the description of this node, acting directly at the DB level

AbstractNode._update_db_label_field(field_value)[source]

Update the label field acting directly on the DB

AbstractNode._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!

AbstractNode.add_comment(content, user=None)[source]

Add a new comment.

Parameters:content – string with comment

Add a link to the current node from the ‘src’ node. Both nodes must be a Node instance (or a subclass of Node) :note: In subclasses, change only this. Moreover, remember to call the super() method in order to properly use the caching logic!

Parameters:
  • src – the source object
  • label (str) – the name of the label to set the link from src. Default = None.
  • link_type – The type of link, must be one of the enum values from LinkType
AbstractNode.add_path(src_abs, dst_path)[source]

Copy a file or folder from a local file inside the repository directory. If there is a subpath, folders will be created.

Copy to a cache directory if the entry has not been saved yet.

Parameters:
  • src_abs (str) – the absolute path of the file to copy.
  • dst_filename (str) – the (relative) path on which to copy.
Todo:

in the future, add an add_attachment() that has the same meaning of a extras file. Decide also how to store. If in two separate subfolders, remember to reset the limit.

AbstractNode.attrs()[source]

Returns the keys of the attributes as a generator.

Returns:a generator of a strings
AbstractNode.copy()[source]

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

This is a completely new entry in the DB, with its own UUID. Works both on stored instances and with not-stored ones.

Copies files and attributes, but not the extras. Does not store the Node to allow modification of attributes.

Returns:an object copy
AbstractNode.ctime

Return the creation time of the node.

AbstractNode.dbnode
Returns:the corresponding DbNode object.
AbstractNode.del_extra(key)[source]

Delete a extra, acting directly on the DB! The action is immediately performed on the DB. Since extras can be added only after storing the node, this function is meaningful to be called only after the .store() method.

Parameters:key (str) – key name
Raise:AttributeError: if key starts with underscore
Raise:ModificationNotAllowed: if the node is not stored yet
AbstractNode.description

Get the description of the node.

Returns:a string
AbstractNode.extras()[source]

Get the keys of the extras.

Returns:a list of strings
AbstractNode.folder

Get the folder associated with the node, whether it is in the temporary or the permanent repository.

Returns:the RepositoryFolder object.
AbstractNode.get_abs_path(path=None, section=None)[source]

Get the absolute path to the folder associated with the Node in the AiiDA repository.

Parameters:
  • path (str) – the name of the subfolder inside the section. If None returns the abspath of the folder. Default = None.
  • section – the name of the subfolder (‘path’ by default).
Returns:

a string with the absolute path

For the moment works only for one kind of files, ‘path’ (internal files)

AbstractNode.get_attr(key, default=())[source]

Get the attribute.

Parameters:
  • key – name of the attribute
  • default – if no attribute key is found, returns default
Returns:

attribute value

Raises:

AttributeError – If no attribute is found and there is no default

AbstractNode.get_attrs()[source]

Return a dictionary with all attributes of this node.

AbstractNode.get_comments(pk=None)[source]

Return a sorted list of comment values, one for each comment associated to the node.

Parameters:pk – integer or list of integers. If it is specified, returns the comment values with desired pks. (pk refers to DbComment.pk)
Returns:the list of comments, sorted by pk; each element of the list is a dictionary, containing (pk, email, ctime, mtime, content)
AbstractNode.get_computer()[source]

Get the computer associated to the node.

Returns:the Computer object or None.
static AbstractNode.get_db_columns()[source]

This method returns a list with the column names and types of the table corresponding to this class. :return: a list with the names of the columns

AbstractNode.get_desc()[source]

Returns a string with infos retrieved from a node’s properties. This method is actually overwritten by the inheriting classes

Returns:a description string
AbstractNode.get_extra(key, *args)[source]

Get the value of a extras, reading directly from the DB! Since extras can be added only after storing the node, this function is meaningful to be called only after the .store() method.

Parameters:
  • key – key name
  • value – if no attribute key is found, returns value
Returns:

the key value

Raises:

ValueError – If more than two arguments are passed to get_extra

AbstractNode.get_extras()[source]

Get the value of extras, reading directly from the DB! Since extras can be added only after storing the node, this function is meaningful to be called only after the .store() method.

Returns:the dictionary of extras ({} if no extras)
AbstractNode.get_folder_list(subfolder='.')[source]

Get the the list of files/directory in the repository of the object.

Parameters:subfolder – get the list of a subfolder
Returns:a list of strings.
AbstractNode.get_inputs(node_type=None, also_labels=False, only_in_db=False, link_type=None)[source]

Return a list of nodes that enter (directly) in this node

Parameters:
  • node_type – If specified, should be a class, and it filters only elements of that specific type (or a subclass of ‘type’)
  • also_labels – If False (default) only return a list of input nodes. If True, return a list of tuples, where each tuple has the following format: (‘label’, Node), with ‘label’ the link label, and Node a Node instance or subclass
  • only_in_db – Return only the inputs that are in the database, ignoring those that are in the local cache. Otherwise, return all links.
  • link_type – Only get inputs of this link type, if None then returns all inputs of all link types.
AbstractNode.get_inputs_dict(only_in_db=False, link_type=None)[source]

Return a dictionary where the key is the label of the input link, and the value is the input node.

Parameters:
  • only_in_db – If true only get stored links, not cached
  • link_type – Only get inputs of this link type, if None then returns all inputs of all link types.
Returns:

a dictionary {label:object}

AbstractNode.get_outputs(type=None, also_labels=False, link_type=None)[source]

Return a list of nodes that exit (directly) from this node

Parameters:
  • type – if specified, should be a class, and it filters only elements of that specific type (or a subclass of ‘type’)
  • also_labels – if False (default) only return a list of input nodes. If True, return a list of tuples, where each tuple has the following format: (‘label’, Node), with ‘label’ the link label, and Node a Node instance or subclass
  • link_type – Only return outputs connected by links of this type.
AbstractNode.get_outputs_dict(link_type=None)[source]

Return a dictionary where the key is the label of the output link, and the value is the input node. As some Nodes (Datas in particular) can have more than one output with the same label, all keys have the name of the link with appended the pk of the node in output. The key without pk appended corresponds to the oldest node.

Returns:a dictionary {linkname:object}
classmethod AbstractNode.get_subclass_from_pk(pk)[source]

Get a node object from the pk, with the proper subclass of Node. (integer primary key used in this database), but loading the proper subclass where appropriate.

Parameters:pk – a string with the pk of the object to be loaded.
Returns:the object of the proper subclass.
Raise:NotExistent: if there is no entry of the desired object kind with the given pk.
classmethod AbstractNode.get_subclass_from_uuid(uuid)[source]

Get a node object from the uuid, with the proper subclass of Node. (if Node(uuid=...) is called, only the Node class is loaded).

Parameters:uuid – a string with the uuid of the object to be loaded.
Returns:the object of the proper subclass.
Raise:NotExistent: if there is no entry of the desired object kind with the given uuid.
AbstractNode.get_user()[source]

Get the user.

Returns:a Django DbUser model object
AbstractNode.has_children

Property to understand if children are attached to the node :return: a boolean

AbstractNode.has_parents

Property to understand if parents are attached to the node :return: a boolean

AbstractNode.id
Returns:the principal key (the ID) as an integer, or None if the node was not stored yet
AbstractNode.inp

Traverse the graph of the database. Returns a databaseobject, linked to the current node, by means of the linkname. Example: B = A.inp.parameters: returns the object (B), with link from B to A, with linkname parameters C= A.inp: returns an InputManager, an object that is meant to be accessed as the previous example

AbstractNode.is_stored

Return True if the node is stored, False otherwise.

AbstractNode.iterattrs()[source]

Iterator over the attributes, returning tuples (key, value)

AbstractNode.iterextras()[source]

Iterator over the extras, returning tuples (key, value)

Todo:verify that I am not creating a list internally
AbstractNode.label

Get the label of the node.

Returns:a string.
AbstractNode.logger

Get the logger of the Node object.

Returns:Logger object
AbstractNode.mtime

Return the modification time of the node.

AbstractNode.out

Traverse the graph of the database. Returns a databaseobject, linked to the current node, by means of the linkname. Example: B = A.out.results: Returns the object B, with link from A to B, with linkname parameters

AbstractNode.pk
Returns:the principal key (the ID) as an integer, or None if the node was not stored yet
classmethod AbstractNode.query(*args, **kwargs)[source]

Map to the aiidaobjects manager of the DbNode, that returns Node objects (or their subclasses) instead of DbNode entities.

# TODO: VERY IMPORTANT: the recognition of a subclass from the type # does not work if the modules defining the subclasses are not # put in subfolders. # In the future, fix it either to make a cache and to store the # full dependency tree, or save also the path.

AbstractNode.querybuild(*args, **kwargs)[source]

Instantiates and :returns: a QueryBuilder instance.

The QueryBuilder’s path has one vertice so far, namely this class. Additional parameters (e.g. filters or a label), can be passes as keyword arguments.

Parameters:
  • label – Label to give
  • filters – filters to apply
  • project – projections

This class is a comboclass (see combomethod()) therefore the method can be called as class or instance method. If called as an instance method, adds a filter on the id.

AbstractNode.remove_path(path)[source]

Remove a file or directory from the repository directory. Can be called only before storing.

Parameters:path (str) – relative path to file/directory.
AbstractNode.reset_extras(new_extras)[source]

Deletes existing extras and creates new ones. :param new_extras: dictionary with new extras :return: nothing, an exceptions is raised in several circumnstances

AbstractNode.set(**kwargs)[source]

For each k=v pair passed as kwargs, call the corresponding set_k(v) method (e.g., calling self.set(property=5, mass=2) will call self.set_property(5) and self.set_mass(2). Useful especially in the __init__.

Note:it uses the _set_incompatibilities list of the class to check that we are not setting methods that cannot be set at the same time. _set_incompatibilities must be a list of tuples, and each tuple specifies the elements that cannot be set at the same time. For instance, if _set_incompatibilities = [(‘property’, ‘mass’)], then the call self.set(property=5, mass=2) will raise a ValueError. If a tuple has more than two values, it raises ValueError if all keys are provided at the same time, but it does not give any error if at least one of the keys is not present.
Note:If one element of _set_incompatibilities is a tuple with only one element, this element will not be settable using this function (and in particular,
Raises:ValueError – if the corresponding set_k method does not exist in self, or if the methods cannot be set at the same time.
AbstractNode.set_computer(computer)[source]

Set the computer to be used by the node.

Note that the computer makes sense only for some nodes: Calculation, RemoteData, ...

Parameters:computer – the computer object
AbstractNode.set_extra(key, value, exclusive=False)[source]

Sets an extra of a calculation. No .store() to be called. Can be used only after saving.

Parameters:
  • key – key name
  • value – key value
  • exclusive – (default=False). If exclusive is True, it raises a UniquenessError if an Extra with the same name already exists in the DB (useful e.g. to “lock” a node and avoid to run multiple times the same computation on it).
Raises:

UniquenessError – if extra already exists and exclusive is True.

AbstractNode.set_extra_exclusive(key, value)[source]

Set an extra in exclusive mode (stops if the attribute is already there). Deprecated, use set_extra() with exclusive=False

Parameters:
  • key – key name
  • value – key value
AbstractNode.set_extras(the_dict)[source]

Immediately sets several extras of a calculation, in the DB! No .store() to be called. Can be used only after saving.

Parameters:the_dict – a dictionary of key:value to be set as extras
AbstractNode.store(with_transaction=True)[source]

Store a new node in the DB, also saving its repository directory and attributes.

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, no transaction is used. This is meant to be used ONLY if the outer calling function has already a transaction open!
AbstractNode.store_all(with_transaction=True)[source]

Store the node, together with all input links, if cached, and also the linked nodes, if they were not stored yet.

Parameters:with_transaction – if False, no transaction is used. This is meant to be used ONLY if the outer calling function has already a transaction open!
AbstractNode.uuid
Returns:a string with the uuid
class aiida.orm.implementation.general.node.AttributeManager(node)[source]

An object used internally to return the attributes as a dictionary.

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

Allow to list the keys of the dictionary

__getattr__(name)[source]

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

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

Interface to get to dictionary values as a dictionary.

Parameters:name – name of the key whose value is required.
__init__(node)[source]
Parameters:node – the node object.
__iter__()[source]

Return the keys as an iterator

__weakref__

list of weak references to the object (if defined)

_get_dict()[source]

Return the internal dictionary

class aiida.orm.implementation.general.node.NodeInputManager(node)[source]

To document

__dir__()[source]

Allow to list all valid input links

__getattr__(name)[source]
Parameters:name – name of the attribute to be asked to the parser results.
__getitem__(name)[source]

interface to get to the parser results as a dictionary.

Parameters:name – name of the attribute to be asked to the parser results.
__init__(node)[source]
Parameters:node – the node object.
__weakref__

list of weak references to the object (if defined)

class aiida.orm.implementation.general.node.NodeOutputManager(node)[source]

To document

__dir__()[source]

Allow to list all valid output links

__getattr__(name)[source]
Parameters:name – name of the attribute to be asked to the parser results.
__getitem__(name)[source]

interface to get to the parser results as a dictionary.

Parameters:name – name of the attribute to be asked to the parser results.
__init__(node)[source]
Parameters:node – the node object.
__weakref__

list of weak references to the object (if defined)

aiida.orm.implementation.general.node.clean_value(value)[source]

Get value from input and (recursively) replace, if needed, all occurrences of BaseType AiiDA data nodes with their value, and List with a standard list.

It also makes a deep copy of everything.

Note however that there is no logic to avoid infinite loops when the user passes some perverse recursive dictionary or list. In any case, however, this would not be storable by AiiDA...

Parameters:value – A value to be set as an attribute or an extra
Returns:a “cleaned” value, potentially identical to value, but with values replaced where needed.
class aiida.orm.node.Node(**kwargs)[source]

Workflow

class aiida.orm.implementation.general.workflow.AbstractWorkflow(**kwargs)[source]

Base class to represent a workflow. This is the superclass of any workflow implementations, and provides all the methods necessary to interact with the database.

The typical use case are workflow stored in the aiida.workflow packages, that are initiated either by the user in the shell or by some scripts, and that are monitored by the aiida daemon.

Workflow can have steps, and each step must contain some calculations to be executed. At the end of the step’s calculations the workflow is reloaded in memory and the next methods is called.

add_attribute(_name, _value)[source]

Add one attributes to the Workflow. If another attribute is present with the same name it will be overwritten. :param name: a string with the attribute name to store :param value: a storable object to store

add_attributes(_params)[source]

Add a set of attributes to the Workflow. If another attribute is present with the same name it will be overwritten. :param name: a string with the attribute name to store :param value: a storable object to store

add_path(src_abs, dst_path)[source]

Copy a file or folder from a local file inside the repository directory. If there is a subpath, folders will be created.

Copy to a cache directory if the entry has not been saved yet. src_abs: the absolute path of the file to copy. dst_filename: the (relative) path on which to copy.

add_result(_name, _value)[source]

Add one result to the Workflow. If another result is present with the same name it will be overwritten. :param name: a string with the result name to store :param value: a storable object to store

add_results(_params)[source]

Add a set of results to the Workflow. If another result is present with the same name it will be overwritten. :param name: a string with the result name to store :param value: a storable object to store

append_to_report(text)[source]

Adds text to the Workflow report.

Note:Once, in case the workflow is a subworkflow of any other Workflow this method calls the parent append_to_report method; now instead this is not the case anymore
attach_calculation(calc)[source]

Adds a calculation to the caller step in the database. This is a lazy call, no calculations will be launched until the next method gets called. For a step to be completed all the calculations linked have to be in RETRIEVED state, after which the next method gets called from the workflow manager. :param calc: a JobCalculation object :raise: AiidaException: in case the input is not of JobCalculation type

attach_workflow(sub_wf)[source]

Adds a workflow to the caller step in the database. This is a lazy call, no workflow will be started until the next method gets called. For a step to be completed all the workflows linked have to be in FINISHED state, after which the next method gets called from the workflow manager. :param next_method: a Workflow object

clear_report()[source]

Wipe the Workflow report. In case the workflow is a subworflow of any other Workflow this method calls the parent clear_report method.

current_folder

Get the current repository folder, whether the temporary or the permanent.

Returns:the RepositoryFolder object.
dbworkflowinstance

Get the DbWorkflow object stored in the super class.

Returns:DbWorkflow object from the database
description

Get the description of the workflow.

Returns:a string
exit()[source]

This is the method to call in next to finish the Workflow. When exit is the next method, and no errors are found, the Workflow is set to FINISHED and removed from the execution manager duties.

get_abs_path(path, section=None)[source]

TODO: For the moment works only for one kind of files, ‘path’ (internal files)

get_all_calcs(calc_class=<class 'aiida.orm.implementation.django.calculation.job.JobCalculation'>, calc_state=None, depth=15)[source]

Get all calculations connected with this workflow and all its subworflows up to a given depth. The list of calculations can be restricted to a given calculation type and state :param calc_class: the calculation class to which the calculations should belong (default: JobCalculation)

Parameters:
  • calc_state – a specific state to filter the calculations to retrieve
  • depth – the maximum depth level the recursion on sub-workflows will try to reach (0 means we stay at the step level and don’t go into sub-workflows, 1 means we go down to one step level of the sub-workflows, etc.)
Returns:

a list of JobCalculation objects

get_attribute(_name)[source]

Get one Workflow attribute :param name: a string with the attribute name to retrieve :return: a dictionary of storable objects

get_attributes()[source]

Get the Workflow attributes :return: a dictionary of storable objects

get_folder_list(subfolder='.')[source]

Get the the list of files/directory in the repository of the object.

Parameters:subfolder – get the list of a subfolder
Returns:a list of strings.
get_parameter(_name)[source]

Get one Workflow paramenter :param name: a string with the parameters name to retrieve :return: a dictionary of storable objects

get_parameters()[source]

Get the Workflow paramenters :return: a dictionary of storable objects

get_report()[source]

Return the Workflow report.

Note:once, in case the workflow is a subworkflow of any other Workflow this method calls the parent get_report method. This is not the case anymore.
Returns:a list of strings
get_result(_name)[source]

Get one Workflow result :param name: a string with the result name to retrieve :return: a dictionary of storable objects

get_results()[source]

Get the Workflow results :return: a dictionary of storable objects

get_state()[source]

Get the Workflow’s state :return: a state from wf_states in aiida.common.datastructures

get_step(step_method)[source]

Retrieves by name a step from the Workflow. :param step_method: a string with the name of the step to retrieve or a method :raise: ObjectDoesNotExist: if there is no step with the specific name. :return: a DbWorkflowStep object.

get_step_calculations(step_method, calc_state=None)[source]

Retrieves all the calculations connected to a specific step in the database. If the step is not existent it returns None, useful for simpler grammatic in the workflow definition. :param next_method: a Workflow step (decorated) method :param calc_state: a specific state to filter the calculations to retrieve :return: a list of JobCalculations objects

get_step_workflows(step_method)[source]

Retrieves all the workflows connected to a specific step in the database. If the step is not existent it returns None, useful for simpler grammatic in the workflow definition. :param next_method: a Workflow step (decorated) method

get_steps(state=None)[source]

Retrieves all the steps from a specific workflow Workflow with the possibility to limit the list to a specific step’s state. :param state: a state from wf_states in aiida.common.datastructures :return: a list of DbWorkflowStep objects.

classmethod get_subclass_from_dbnode(wf_db)[source]

Loads the workflow object and reaoads the python script in memory with the importlib library, the main class is searched and then loaded. :param wf_db: a specific DbWorkflowNode object representing the Workflow :return: a Workflow subclass from the specific source code

classmethod get_subclass_from_pk(pk)[source]

Calls the get_subclass_from_dbnode selecting the DbWorkflowNode from the input pk. :param pk: a primary key index for the DbWorkflowNode :return: a Workflow subclass from the specific source code

classmethod get_subclass_from_uuid(uuid)[source]

Calls the get_subclass_from_dbnode selecting the DbWorkflowNode from the input uuid. :param uuid: a uuid for the DbWorkflowNode :return: a Workflow subclass from the specific source code

get_temp_folder()[source]

Get the folder of the Node in the temporary repository.

Returns:a SandboxFolder object mapping the node in the repository.
has_failed()[source]

Returns True is the Workflow’s state is ERROR

has_finished_ok()[source]

Returns True is the Workflow’s state is FINISHED

has_step(step_method)[source]

Return if the Workflow has a step with a specific name. :param step_method: a string with the name of the step to retrieve or a method

info()[source]

Returns an array with all the informations about the modules, file, class to locate the workflow source code

is_new()[source]

Returns True is the Workflow’s state is CREATED

is_running()[source]

Returns True is the Workflow’s state is RUNNING

is_subworkflow()[source]

Return True is this is a subworkflow (i.e., if it has a parent), False otherwise.

kill(verbose=False)[source]

Stop the Workflow execution and change its state to FINISHED.

This method calls the kill method for each Calculation and each subworkflow linked to each RUNNING step.

Parameters:verbose – True to print the pk of each subworkflow killed
Raises:InvalidOperation – if some calculations cannot be killed (the workflow will be also put to SLEEP so that it can be killed later on)
kill_step_calculations(step)[source]

Calls the kill method for each Calculation linked to the step method passed as argument. :param step: a Workflow step (decorated) method

label

Get the label of the workflow.

Returns:a string
logger

Get the logger of the Workflow object, so that it also logs to the DB.

Returns:LoggerAdapter object, that works like a logger, but also has the ‘extra’ embedded
next(next_method)[source]

Adds the a new step to be called after the completion of the caller method’s calculations and subworkflows.

This method must be called inside a Workflow step, otherwise an error is thrown. The code finds the caller method and stores in the database the input next_method as the next method to be called. At this point no execution in made, only configuration updates in the database.

If during the execution of the caller method the user launched calculations or subworkflows, this method will add them to the database, making them available to the workflow manager to be launched. In fact all the calculation and subworkflow submissions are lazy method, really executed by this call.

Parameters:next_method – a Workflow step method to execute after the caller method
Raise:AiidaException: in case the caller method cannot be found or validated
Returns:the wrapped methods, decorated with the correct step name
pk

Returns the DbWorkflow pk

classmethod query(*args, **kwargs)[source]

Map to the aiidaobjects manager of the DbWorkflow, that returns Workflow objects instead of DbWorkflow entities.

remove_path(path)[source]

Remove a file or directory from the repository directory.

Can be called only before storing.

repo_folder

Get the permanent repository folder. Use preferentially the current_folder method.

Returns:the permanent RepositoryFolder object
set_params(params, force=False)[source]

Adds parameters to the Workflow that are both stored and used every time the workflow engine re-initialize the specific workflow to launch the new methods.

set_state(state)[source]

Set the Workflow’s state :param name: a state from wf_states in aiida.common.datastructures

sleep()[source]

Changes the workflow state to SLEEP, only possible to call from a Workflow step decorated method.

classmethod step(fun)[source]

This method is used as a decorator for workflow steps, and handles the method’s execution, the state updates and the eventual errors.

The decorator generates a wrapper around the input function to execute, adding with the correct step name and a utility variable to make it distinguishable from non-step methods.

When a step is launched, the wrapper tries to run the function in case of error the state of the workflow is moved to ERROR and the traceback is stored in the report. In general the input method is a step obtained from the Workflow object, and the decorator simply handles a controlled execution of the step allowing the code not to break in case of error in the step’s source code.

The wrapper also tests not to run two times the same step, unless a Workflow is in ERROR state, in this case all the calculations and subworkflows of the step are killed and a new execution is allowed.

Parameters:fun – a methods to wrap, making it a Workflow step
Raise:AiidaException: in case the workflow state doesn’t allow the execution
Returns:the wrapped methods,
store()[source]

Stores the DbWorkflow object data in the database

uuid

Returns the DbWorkflow uuid

exception aiida.orm.implementation.general.workflow.WorkflowKillError(*args, **kwargs)[source]

An exception raised when a workflow failed to be killed. The error_message_list attribute contains the error messages from all the subworkflows.

exception aiida.orm.implementation.general.workflow.WorkflowUnkillable[source]

Raised when a workflow cannot be killed because it is in the FINISHED or ERROR state.

aiida.orm.implementation.general.workflow.get_workflow_info(w, tab_size=2, short=False, pre_string='', depth=16)[source]

Return a string with all the information regarding the given workflow and all its calculations and subworkflows. This is a recursive function (to print all subworkflows info as well).

Parameters:
  • w – a DbWorkflow instance
  • tab_size – number of spaces to use for the indentation
  • short – if True, provide a shorter output (only total number of calculations, rather than the state of each calculation)
  • pre_string – string appended at the beginning of each line
  • depth – the maximum depth level the recursion on sub-workflows will try to reach (0 means we stay at the step level and don’t go into sub-workflows, 1 means we go down to one step level of the sub-workflows, etc.)
Return lines:

list of lines to be outputed

aiida.orm.implementation.general.workflow.kill_all()[source]

Kills all the workflows not in FINISHED state running the kill_from_uuid method in a loop.

Parameters:uuid – the UUID of the workflow to kill
aiida.orm.implementation.general.workflow.kill_from_pk()[source]

Kills a workflow from its pk.

Parameters:pk – the Pkof the workflow to kill

Code

class aiida.orm.implementation.general.code.AbstractCode(**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_text_info

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

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.

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

Returns a string with infos retrieved from PwCalculation node’s properties. :param node: :return: retsrt:

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

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.

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

Create and return a new Calculation object (unstored) with the correct plugin subclass, as obtained by the self.get_input_plugin_name() method.

Parameters are passed to the calculation __init__ method.

Note:

it also directly creates the link to this code (that will of course be cached, since the new node is not stored yet).

Raises:
  • MissingPluginError – if the specified plugin does not exist.
  • ValueError – if no plugin was specified.
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.

Args:
remote_computer_exec: a tuple (computer, remote_exec_path), where
computer is a aiida.orm.Computer or an aiida.backends.djsite.db.models.DbComputer object, and remote_exec_path is the absolute path of the main executable on remote computer.
aiida.orm.implementation.general.code.delete_code(code)[source]

Delete a code from the DB. Check before that there are no output nodes.

NOTE! Not thread safe... Do not use with many users accessing the DB at the same time.

Implemented as a function on purpose, otherwise complicated logic would be needed to set the internal state of the object after calling computer.delete().

ORM documentation: Data

class aiida.orm.data.Data(**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 suppoted, 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.

_del_attr(key)[source]

Delete an attribute.

Parameters:

key – attribute to delete.

Raises:
_exportstring(fileformat, main_file_name='', **kwargs)[source]

Converts a Data object to other text format.

Parameters:
  • fileformat – a string (the extension) to describe the file format.
  • main_file_name – empty by default, contains the (full) path and filename of the main file, if any. This is not used directly, but is used to infer useful unique names for the additional files, if any. For instance, if the main file for gnuplot is ‘../myplot.gnu’, the plugin could decide to store the dat file under ‘../myplot_data.dat’. It is up to the plugin to properly deal with this filename (or ignore it, if not relevant, e.g. if no additional files need to be created)
  • kwargs – any other parameter is passed down to the specific 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.

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

_linking_as_output(dest, link_type)[source]

Raise a ValueError if a link from self to dest is not allowed.

An output of a data can only be a calculation

_set_attr(key, value)[source]

Set a new attribute to the Node (in the DbAttribute table).

Parameters:
  • key (str) – key name
  • value – its value
Raises:
  • ModificationNotAllowed – if such attribute cannot be added (e.g. because the node was already stored)
  • ValidationError – if the key is not valid (e.g. it contains the separator symbol).
_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.

convert(object_format=None, *args)[source]

Convert the AiiDA StructureData into another python object

Parameters:object_format – Specify the output format
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 _exportstring 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.

Structure

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

class aiida.orm.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
  • (optional) (mass) – 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.
  • (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()[source]

Returns True if the sum of the weights is less than one. It uses the internal variable _sum_threshold as a threshold.

Returns:a boolean
is_alloy()[source]

To understand if kind is an alloy.

Returns:True if the kind has more than one element (i.e., len(self.symbols) != 1), 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.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.

class aiida.orm.data.structure.StructureData(**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_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_desc()[source]

Returns a string with infos retrieved from StructureData node’s properties :param self: the StructureData node :return: retsrt: the description string

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

Get pymatgen object. Returns 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_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()[source]

Get the pymatgen Structure object.

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

To understand if there are vacancies in the structure.

Returns:a boolean, True if at least one kind has a vacancy
is_alloy()[source]

To understand if there are alloys in the structure.

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.0.13, usage of earlier versions may cause errors).

sites

Returns a list of sites.

aiida.orm.data.structure.ase_refine_cell(aseatoms, **kwargs)[source]

Detect the symmetry of the structure, remove symmetric atoms and refine unit cell.

Parameters:
  • aseatoms – an ase.atoms.Atoms instance
  • symprec – symmetry precision, used by spglib
Return newase:

refined cell with reduced set of atoms

Return symmetry:
 

a dictionary describing the symmetry space group

aiida.orm.data.structure.calc_cell_volume(cell)[source]

Calculates the volume of a cell given the three lattice vectors.

It is calculated as cell[0] . (cell[1] x cell[2]), where . represents a dot product and x a cross product.

Parameters:cell – the cell vectors; the must be a 3x3 list of lists of floats, no other checks are done.
Returns:the cell volume.
aiida.orm.data.structure.get_formula(symbol_list, mode='hill', separator='')[source]

Return a string with the chemical formula.

Parameters:
  • symbol_list – a list of symbols, e.g. ['H','H','O']
  • 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

aiida.orm.data.structure.get_formula_from_symbol_list(_list, separator='')[source]

Return a string with the formula obtained from the list of symbols. Examples: * [[1,'Ba'],[1,'Ti'],[3,'O']] will return 'BaTiO3' * [[2, [ [1, 'Ba'], [1, 'Ti'] ] ]] will return '(BaTi)2'

Parameters:
  • _list – a list of symbols and multiplicities as obtained from the function group_symbols
  • separator – a string used to concatenate symbols. Default empty.
Returns:

a string

aiida.orm.data.structure.get_formula_group(symbol_list, separator='')[source]

Return a string with the chemical formula from a list of chemical symbols. The formula is written in a compact” way, i.e. trying to group as much as possible parts of the formula.

Note

it works for instance very well if structure was obtained from an ASE supercell.

Example of result: ['Ba', 'Ti', 'O', 'O', 'O', 'Ba', 'Ti', 'O', 'O', 'O', 'Ba', 'Ti', 'Ti', 'O', 'O', 'O'] will return '(BaTiO3)2BaTi2O3'.

Parameters:
  • symbol_list – list of symbols (e.g. [‘Ba’,’Ti’,’O’,’O’,’O’])
  • separator – a string used to concatenate symbols. Default empty.
Returns:

a string with the chemical formula for the given structure.

aiida.orm.data.structure.get_pymatgen_version()[source]
Returns:string with pymatgen version, None if can not import.
aiida.orm.data.structure.get_symbols_string(symbols, weights)[source]

Return a string that tries to match as good as possible the symbols and weights. 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). If (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)

Parameters:
  • symbols – the symbols as obtained from <kind>._symbols
  • weights – the weights as obtained from <kind>._weights

Note

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

aiida.orm.data.structure.get_valid_pbc(inputpbc)[source]

Return a list of three booleans for the periodic boundary conditions, in a valid format from a generic input.

Raises:ValueError – if the format is not valid.
aiida.orm.data.structure.group_symbols(_list)[source]

Group a list of symbols to a list containing the number of consecutive identical symbols, and the symbol itself.

Examples:

  • ['Ba','Ti','O','O','O','Ba'] will return [[1,'Ba'],[1,'Ti'],[3,'O'],[1,'Ba']]
  • [ [ [1,'Ba'],[1,'Ti'] ],[ [1,'Ba'],[1,'Ti'] ] ] will return [[2, [ [1, 'Ba'], [1, 'Ti'] ] ]]
Parameters:_list – a list of elements representing a chemical formula
Returns:a list of length-2 lists of the form [ multiplicity , element ]
aiida.orm.data.structure.has_ase()[source]
Returns:True if the ase module can be imported, False otherwise.
aiida.orm.data.structure.has_pymatgen()[source]
Returns:True if the pymatgen module can be imported, False otherwise.
aiida.orm.data.structure.has_spglib()[source]
Returns:True if the spglib module can be imported, False otherwise.
aiida.orm.data.structure.has_vacancies(weights)[source]

Returns True if the sum of the weights is less than one. It uses the internal variable _sum_threshold as a threshold. :param weights: the weights :return: a boolean

aiida.orm.data.structure.is_ase_atoms(ase_atoms)[source]

Check if the ase_atoms parameter is actually a ase.Atoms object.

Parameters:ase_atoms – an object, expected to be an ase.Atoms.
Returns:a boolean.

Requires the ability to import ase, by doing ‘import ase’.

aiida.orm.data.structure.is_valid_symbol(symbol)[source]

Validates the chemical symbol name.

Returns:True if the symbol is a valid chemical symbol (with correct capitalization), False otherwise.

Recognized symbols are for elements from hydrogen (Z=1) to lawrencium (Z=103).

aiida.orm.data.structure.symop_fract_from_ortho(cell)[source]

Creates a matrix for conversion from fractional to orthogonal coordinates.

Taken from svn://www.crystallography.net/cod-tools/trunk/lib/perl5/Fractional.pm, revision 850.

Parameters:cell – array of cell parameters (three lengths and three angles)
aiida.orm.data.structure.symop_ortho_from_fract(cell)[source]

Creates a matrix for conversion from orthogonal to fractional coordinates.

Taken from svn://www.crystallography.net/cod-tools/trunk/lib/perl5/Fractional.pm, revision 850.

Parameters:cell – array of cell parameters (three lengths and three angles)
aiida.orm.data.structure.validate_symbols_tuple(symbols_tuple)[source]

Used to validate whether the chemical species are valid.

Parameters:symbols_tuple – a tuple (or list) with the chemical symbols name.
Raises:ValueError if any symbol in the tuple is not a valid chemical symbols (with correct capitalization).

Refer also to the documentation of :func:is_valid_symbol

aiida.orm.data.structure.validate_weights_tuple(weights_tuple, threshold)[source]

Validates the weight of the atomic kinds.

Raise:

ValueError if the weights_tuple is not valid.

Parameters:
  • weights_tuple – the tuple to validate. It must be a a tuple of floats (as created by :func:_create_weights_tuple).
  • threshold – a float number used as a threshold to check that the sum of the weights is <= 1.

If the sum is less than one, it means that there are vacancies. Each element of the list must be >= 0, and the sum must be <= 1.

Folder

class aiida.orm.data.folder.FolderData(**kwargs)[source]

Stores a folder with subfolders and files.

No special attributes are set.

get_file_content(path)[source]

Return the content of a path stored inside the folder as a string.

Raises:NotExistent – if the path does not exist.
replace_with_folder(folder, overwrite=True)[source]

Replace the data with another folder, always copying and not moving the original files.

Args:
folder: the folder to copy from overwrite: if to overwrite the current content or not

Singlefile

Implement subclass for a single file in the permanent repository files = [one_single_file] jsons = {}

methods: * get_content * get_path * get_aiidaurl (?) * get_md5 * ...

To discuss: do we also need a simple directory class for full directories in the perm repo?

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

Pass as input a file parameter with the (absolute) path of a file on the hard drive. It will get copied inside the node.

Internally must have a single file, and stores as internal attribute the filename in the ‘filename’ attribute.

add_path(src_abs, dst_filename=None)[source]

Add a single file

del_file(filename)[source]

Remove a file from SingleFileData :param filename: name of the file stored in the DB

filename

Returns the name of the file stored

get_file_abs_path()[source]

Return the absolute path to the file in the repository

set_file(filename)[source]

Add a file to the singlefiledata :param filename: absolute path to the file

Upf

This module manages the UPF pseudopotentials in the local repository.

class aiida.orm.data.upf.UpfData(**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(filename, 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:
  • filename – an absolute filename 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_name)[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(filename)[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.

aiida.orm.data.upf.get_pseudos_dict(structure, family_name)[source]

Get a dictionary of {kind: pseudo} for all the elements within the given structure using a the given pseudo family name.

Parameters:
  • structure – The structure that will be used.
  • family_name – the name of the group containing the pseudos
aiida.orm.data.upf.get_pseudos_from_structure(structure, family_name)[source]

Given a family name (a UpfFamily group in the DB) and a AiiDA structure, return a dictionary associating each kind name with its UpfData object.

Raises:
  • MultipleObjectsError – if more than one UPF for the same element is found in the group.
  • NotExistent – if no UPF for an element in the group is found in the group.
aiida.orm.data.upf.parse_upf(fname, check_filename=True)[source]

Try to get relevant information from the UPF. For the moment, only the element name. Note that even UPF v.2 cannot be parsed with the XML minidom! (e.g. due to the & characters in the human-readable section).

If check_filename is True, raise a ParsingError exception if the filename does not start with the element name.

aiida.orm.data.upf.upload_upf_family(folder, group_name, group_description, stop_if_existing=True)[source]

Upload a set of UPF files in a given group.

Parameters:
  • folder – a path containing all UPF files to be added. Only files ending in .UPF (case-insensitive) are considered.
  • group_name – the name of the group to create. If it exists and is non-empty, a UniquenessError is raised.
  • group_description – a string to be set as the group description. Overwrites previous descriptions, if the group was existing.
  • stop_if_existing – if True, check for the md5 of the files and, if the file already exists in the DB, raises a MultipleObjectsError. If False, simply adds the existing UPFData node to the group.

Cif

class aiida.orm.data.cif.CifData(**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]

Generate MD5 hash of the file’s contents on-the-fly.

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]

Get the formula.

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.

has_attached_hydrogens()[source]

Check if there are hydrogens without coordinates, specified as attached to the atoms of the structure. :return: True if there are attached hydrogens, False otherwise.

has_partial_occupancies()[source]

Check if there are float values in the atom occupancies. :return: True if there are partial occupancies, False otherwise.

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.

set_file(filename)[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.

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

Store the node.

values

PyCifRW structure, representing the CIF datablocks.

Note

requires PyCifRW module.

aiida.orm.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.data.cif.has_pycifrw()[source]
Returns:True if the PyCifRW module can be imported, False otherwise.
aiida.orm.data.cif.parse_formula(formula)[source]

Parses the Hill formulae, written with spaces for separators.

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

Constructs PyCifRW’s CifFile from an array of CIF datablocks.

Parameters:
  • datablocks – an array of CIF datablocks
  • loops – optional list of lists of CIF tag loops.
  • names – optional list of datablock names
Returns:

CifFile

aiida.orm.data.cif.symop_string_from_symop_matrix_tr(matrix, tr=(0, 0, 0), eps=0)[source]

Construct a CIF representation of symmetry operator plus translation. See International Tables for Crystallography Vol. A. (2002) for definition.

Parameters:
  • matrix – 3x3 matrix, representing the symmetry operator
  • tr – translation vector of length 3 (default 0)
  • eps – epsilon parameter for fuzzy comparison x == 0
Returns:

CIF representation of symmetry operator

Parameter

class aiida.orm.data.parameter.ParameterData(**kwargs)[source]

Pass as input in the init a dictionary, and it will get stored as internal attributes.

Usual rules for attribute names apply (in particular, keys cannot start with an underscore). If this is the case, a ValueError will be raised.

You can then change/delete/add more attributes before storing with the usual methods of aiida.orm.Node

dict

To be used to get direct access to the underlying dictionary with the syntax node.dict.key or node.dict[‘key’].

Returns:an instance of the AttributeResultManager.
get_dict()[source]

Return a dict with the parameters

keys()[source]

Iterator of valid keys stored in the ParameterData object

set_dict(dict)[source]

Replace the current dictionary with another one.

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

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

Parameters:dict – a dictionary with the keys to substitute. It works like dict.update(), adding new keys and overwriting existing keys.

Remote

class aiida.orm.data.remote.RemoteData(**kwargs)[source]

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

Remember to pass a computer!

add_path(src_abs, dst_filename=None)[source]

Disable adding files or directories to a RemoteData

is_empty()[source]

Check if remote folder is empty

OrbitalData

class aiida.orm.data.orbital.OrbitalData(**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(with_tags=False, **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
  • with_tags – if provided returns all tags stored
Kwargs:

attributes than can filter the set of returned orbitals

Return list_of_outputs:
 

a list of orbitals and also tags if with_tags was set to True

set_orbitals(orbital, tag=None)[source]

Sets the orbitals into the database. Uses the orbital’s inherent set_orbital_dict method to generate a orbital dict string at is stored along with the tags, if provided.

Parameters:
  • orbital – an orbital or list of orbitals to be set
  • tag – a list of strings must be of length orbital

ArrayData

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

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

Deprecated since version 0.7: Use get_arraynames() instead.

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

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

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.

ArrayData subclasses

The following are Data classes inheriting from ArrayData.

KpointsData

This module defines the classes related to band structures or dispersions in a Brillouin zone, and how to operate on them.

class aiida.orm.data.array.kpoints.KpointsData(*args, **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.

bravais_lattice

The dictionary containing informations about the cell symmetry

cell

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

find_bravais_lattice(epsilon_length=1e-05, epsilon_angle=1e-05)[source]

Analyze the symmetry of the cell. Allows to relax or tighten the thresholds used to compare angles and lengths of the cell. Save the information of the cell used for later use (like getting special points). It has to be used if the user wants to be sure the right symmetries are recognized. Otherwise, this function is automatically called with the default values.

If the right symmetry is not found, be sure also you are providing cells with enough digits.

If node is already stored, just returns the symmetry found before storing (if any).

Return (str) lattice_name:
 the name of the bravais lattice and its eventual variation
get_desc()[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()
get_special_points(cartesian=False, epsilon_length=1e-05, epsilon_angle=1e-05)[source]

Get the special point and path of a given structure.

In 2D, coordinates are based on the paper: R. Ramirez and M. C. Bohm, Int. J. Quant. Chem., XXX, pp. 391-411 (1986)

In 3D, coordinates are based on the paper: arXiv:1004.2974, W. Setyawan, S. Curtarolo

Parameters:
  • cartesian – If true, returns points in cartesian coordinates. Crystal coordinates otherwise. Default=False
  • epsilon_length – threshold on lengths comparison, used to get the bravais lattice info
  • epsilon_angle – threshold on angles comparison, used to get the bravais lattice info
Return special_points,path:
 

special_points: a dictionary of point_name:point_coords key,values.

path: the suggested path which goes through all high symmetry lines. A list of lists for all path segments. e.g. [(‘G’,’X’),(‘X’,’M’),...] It’s not necessarily a continuous line.

Note:

We assume that the cell given by the cell property is the primitive unit cell

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)
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=[0.0, 0.0, 0.0])[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=[0.0, 0.0, 0.0], 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.

set_kpoints_path(value=None, kpoint_distance=None, cartesian=False, epsilon_length=1e-05, epsilon_angle=1e-05)[source]

Set a path of kpoints in the Brillouin zone.

Parameters:
  • value

    description of the path, in various possible formats.

    None: automatically sets all irreducible high symmetry paths. Requires that a cell was set

    or

    [(‘G’,’M’), (...), ...] [(‘G’,’M’,30), (...), ...] [(‘G’,(0,0,0),’M’,(1,1,1)), (...), ...] [(‘G’,(0,0,0),’M’,(1,1,1),30), (...), ...]

  • cartesian (bool) – if set to true, reads the coordinates eventually passed in value as cartesian coordinates. Default: False.
  • kpoint_distance (float) – parameter controlling the distance between kpoints. Distance is given in crystal coordinates, i.e. the distance is computed in the space of b1,b2,b3. The distance set will be the closest possible to this value, compatible with the requirement of putting equispaced points between two special points (since extrema are included).
  • epsilon_length (float) – threshold on lengths comparison, used to get the bravais lattice info. It has to be used if the user wants to be sure the right symmetries are recognized.
  • epsilon_angle (float) – threshold on angles comparison, used to get the bravais lattice info. It has to be used if the user wants to be sure the right symmetries are recognized.

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.data.array.bands.BandsData(*args, **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._exportstring.

units

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

aiida.orm.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.data.array.projection.ProjectionData(*args, **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
  • 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:NotExistent if there was no BandsData associated with uuid or pk

TrajectoryData

class aiida.orm.data.array.trajectory.TrajectoryData(*args, **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_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_index(step)[source]

Deprecated since version 0.7: Use get_index_from_stepid() instead.

get_step_structure(index, custom_kinds=None)[source]

Return an AiiDA aiida.orm.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.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.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_steps()[source]

Deprecated since version 0.7: Use get_stepids() instead.

get_symbols()[source]

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

Raises:KeyError – if the trajectory has not been set yet.
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.data.structure.StructureData instances.

Parameters:structurelist – a list of aiida.orm.data.structure.StructureData instances.
Raises:ValueError – if symbol lists of supplied structures are different
set_trajectory(stepids, cells, symbols, positions, times=None, velocities=None)[source]

Store the whole trajectory, after checking that types and dimensions are correct. Velocities are optional, if they are not passed, nothing is stored.

Parameters:
  • 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 your code does not provide an internal counter, just provide for instance arange(s). It is internally stored as an array named ‘steps’.
  • cells – 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]).
  • symbols – string array with dimension n, where n is the number of atoms (i.e., sites) in the structure. The same array 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]).
  • 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_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.
Todo:

save to file?

step_to_structure(index, custom_kinds=None)[source]

Deprecated since version 0.7: Use get_step_structure() instead.

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.data.array.xy.XyData(*args, **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.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

ORM documentation: Calculations

class aiida.orm.implementation.general.calculation.AbstractCalculation[source]

This class provides the definition of an “abstract” AiiDA calculation. A calculation in this sense is any computation that converts data into data.

You will typically use one of its subclasses, often a JobCalculation for calculations run via a scheduler.

Add a link with a code as destination.

You can use the parameters of the base Node class, in particular the label parameter to label the link.

Parameters:
  • src – a node of the database. It cannot be a Calculation object.
  • label (str) – Name of the link. Default=None
  • link_type – The type of link, must be one of the enum values form LinkType
get_code()[source]

Return the code for this calculation, or None if the code was not set.

get_linkname(link, *args, **kwargs)[source]

Return the linkname used for a given input link

Pass as parameter “NAME” if you would call the use_NAME method. If the use_NAME method requires a further parameter, pass that parameter as the second parameter.

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
class aiida.orm.calculation.inline.InlineCalculation(**kwargs)[source]

Here I put all the attributes/method that are common to all backends

get_desc()[source]

Returns a string with infos retrieved from a InlineCalculation node’s properties. :return: description string

aiida.orm.calculation.inline.optional_inline(func)[source]

optional_inline wrapper/decorator takes a function, which can be called either as wrapped in InlineCalculation or a simple function, depending on ‘store’ keyworded argument (True stands for InlineCalculation, False for simple function). The wrapped function has to adhere to the requirements by make_inline wrapper/decorator.

Usage example:

@optional_inline
def copy_inline(source=None):
  return {'copy': source.copy()}

Function copy_inline will be wrapped in InlineCalculation when invoked in following way:

copy_inline(source=node,store=True)

while it will be called as a simple function when invoked:

copy_inline(source=node)

In any way the copy_inline will return the same results.

class aiida.orm.implementation.general.calculation.job.AbstractJobCalculation[source]

This class provides the definition of an AiiDA calculation that is run remotely on a job scheduler.

Add a link with a code as destination. Add the additional contraint that this is only possible if the calculation is in state NEW.

You can use the parameters of the base Node class, in particular the label parameter to label the link.

Parameters:
  • src – a node of the database. It cannot be a Calculation object.
  • label (str) – Name of the link. Default=None
  • link_type – The type of link, must be one of the enum values form LinkType
get_append_text()[source]

Get the calculation-specific append text, which is going to be appended in the scheduler-job script, just after the code execution.

get_custom_scheduler_commands()[source]

Return a (possibly multiline) string with the commands that the user wants to manually set for the scheduler. See also the documentation of the corresponding set_ method.

Returns:the custom scheduler command, or an empty string if no custom command was defined.
get_environment_variables()[source]

Return a dictionary of the environment variables that are set for this calculation.

Return an empty dictionary if no special environment variables have to be set for this calculation.

get_import_sys_environment()[source]

To check if it’s loading the system environment on the submission script.

Returns:a boolean. If True the system environment will be load.
get_job_id()[source]

Get the scheduler job id of the calculation.

Returns:a string
get_max_memory_kb()[source]

Get the memory (in KiloBytes) requested to the scheduler.

Returns:an integer
get_max_wallclock_seconds()[source]

Get the max wallclock time in seconds requested to the scheduler.

Returns:an integer
Return type:int
get_mpirun_extra_params()[source]

Return a list of strings, that are the extra params to pass to the mpirun (or equivalent) command after the one provided in computer.mpirun_command. Example: mpirun -np 8 extra_params[0] extra_params[1] ... exec.x

Return an empty list if no parameters have been defined.

get_parser_name()[source]

Return a string locating the module that contains the output parser of this calculation, that will be searched in the ‘aiida/parsers/plugins’ directory. None if no parser is needed/set.

Returns:a string.
get_parserclass()[source]

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

Returns:a Parser class.
Raise:MissingPluginError from ParserFactory no plugin is found.
get_prepend_text()[source]

Get the calculation-specific prepend text, which is going to be prepended in the scheduler-job script, just before the code execution.

get_priority()[source]

Get the priority, if set, of the job on the cluster.

Returns:a string or None
get_queue_name()[source]

Get the name of the queue on cluster.

Returns:a string or None.
get_resources(full=False)[source]

Returns the dictionary of the job resources set.

Parameters:full – if True, also add the default values, e.g. default_mpiprocs_per_machine
Returns:a dictionary
get_retrieved_node()[source]

Return the retrieved data folder, if present.

Returns:the retrieved data folder object, or None if no such output node is found.
Raises:MultipleObjectsError – if more than one output node is found.
get_scheduler_error()[source]

Return the output of the scheduler error (a string) if the calculation has finished, and output node is present, and the output of the scheduler was retrieved.

Return None otherwise.

get_scheduler_output()[source]

Return the output of the scheduler output (a string) if the calculation has finished, and output node is present, and the output of the scheduler was retrieved.

Return None otherwise.

get_scheduler_state()[source]

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

Returns:a string.
get_state(from_attribute=False)[source]

Get the state of the calculation.

Note

the ‘most recent’ state is obtained using the logic in the aiida.common.datastructures.sort_states function.

Todo

Understand if the state returned when no state entry is found in the DB is the best choice.

Parameters:from_attribute – if set to True, read it from the attributes (the attribute is also set with set_state, unless the state is set to IMPORTED; in this way we can also see the state before storing).
Returns:a string. If from_attribute is True and no attribute is found, return None. If from_attribute is False and no entry is found in the DB, also return None.
get_withmpi()[source]

Get whether the job is set with mpi execution.

Returns:a boolean. Default=True.
has_failed()[source]

Get whether the calculation is in a failed status, i.e. SUBMISSIONFAILED, RETRIEVALFAILED, PARSINGFAILED or FAILED.

Returns:a boolean
has_finished()[source]

Determine if the calculation is finished for whatever reason. This may be because it finished successfully or because of a failure.

Returns:True if the job has finished running, False otherwise.
Return type:bool
has_finished_ok()[source]

Get whether the calculation is in the FINISHED status.

Returns:a boolean
kill()[source]

Kill a calculation on the cluster.

Can only be called if the calculation is in status WITHSCHEDULER.

The command tries to run the kill command as provided by the scheduler, and raises an exception is something goes wrong. No changes of calculation status are done (they will be done later by the calculation manager).

res

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

Returns:an instance of the CalculationResultManager.
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_append_text(val)[source]

Set the calculation-specific append text, which is going to be appended in the scheduler-job script, just after the code execution.

Parameters:val – a (possibly multiline) string
set_custom_scheduler_commands(val)[source]

Set a (possibly multiline) string with the commands that the user wants to manually set for the scheduler.

The difference of this method with respect to the set_prepend_text is the position in the scheduler submission file where such text is inserted: with this method, the string is inserted before any non-scheduler command.

set_environment_variables(env_vars_dict)[source]

Set a dictionary of custom environment variables for this calculation.

Both keys and values must be strings.

In the remote-computer submission script, it’s going to export variables as export 'keys'='values'

set_import_sys_environment(val)[source]

If set to true, the submission script will load the system environment variables.

Parameters:val (bool) – load the environment if True
set_max_memory_kb(val)[source]

Set the maximum memory (in KiloBytes) to be asked to the scheduler.

Parameters:val – an integer. Default=None
set_max_wallclock_seconds(val)[source]

Set the wallclock in seconds asked to the scheduler.

Parameters:val – An integer. Default=None
set_mpirun_extra_params(extra_params)[source]

Set the extra params to pass to the mpirun (or equivalent) command after the one provided in computer.mpirun_command. Example: mpirun -np 8 extra_params[0] extra_params[1] ... exec.x

Parameters:extra_params – must be a list of strings, one for each extra parameter
set_parser_name(parser)[source]

Set a string for the output parser Can be None if no output plugin is available or needed.

Parameters:parser – a string identifying the module of the parser. Such module must be located within the folder ‘aiida/parsers/plugins’
set_prepend_text(val)[source]

Set the calculation-specific prepend text, which is going to be prepended in the scheduler-job script, just before the code execution.

See also set_custom_scheduler_commands

Parameters:val – a (possibly multiline) string
set_priority(val)[source]

Set the priority of the job to be queued.

Parameters:val – the values of priority as accepted by the cluster scheduler.
set_queue_name(val)[source]

Set the name of the queue on the remote computer.

Parameters:val (str) – the queue name
set_resources(resources_dict)[source]

Set the dictionary of resources to be used by the scheduler plugin, like the number of nodes, cpus, ... This dictionary is scheduler-plugin dependent. Look at the documentation of the scheduler. (scheduler type can be found with calc.get_computer().get_scheduler_type() )

set_withmpi(val)[source]

Set the calculation to use mpi.

Parameters:val – A boolean. Default=True
store(*args, **kwargs)[source]

Override the store() method to store also the calculation in the NEW state as soon as this is stored for the first time.

submit()[source]

Puts the calculation in the TOSUBMIT status.

Actual submission is performed by the daemon.

submit_test(folder=None, subfolder_name=None)[source]

Test submission, creating the files in a local folder.

Note:

this submit_test function does not require any node (neither the calculation nor the input links) to be stored yet.

Parameters:
  • folder – A Folder object, within which each calculation files are created; if not passed, a subfolder ‘submit_test’ of the current folder is used.
  • subfolder_name – the name of the subfolder to use for this calculation (within Folder). If not passed, a unique string starting with the date and time in the format yymmdd-HHMMSS- is used.
class aiida.orm.implementation.general.calculation.job.CalculationResultManager(calc)[source]

An object used internally to interface the calculation object with the Parser and consequentially with the ParameterData object result. It shouldn’t be used explicitly by a user.

__init__(calc)[source]
Parameters:calc – the calculation object.
class aiida.orm.implementation.general.calculation.inline.InlineCalculation(**kwargs)[source]

Subclass used for calculations that are automatically generated using the make_inline wrapper/decorator.

This is used to automatically create a calculation node for a simple calculation

get_function_name()[source]

Get the function name.

Returns:a string
aiida.orm.implementation.general.calculation.inline.make_inline(func)[source]

This make_inline wrapper/decorator takes a function with specific requirements, runs it and stores the result as an InlineCalculation node. It will also store all other nodes, including any possibly unstored input node! The return value of the wrapped calculation will also be slightly changed, see below.

The wrapper:

  • checks that the function name ends with the string '_inline'
  • checks that each input parameter is a valid Data node (can be stored or unstored)
  • runs the actual function
  • gets the result values
  • checks that the result value is a dictionary, where the key are all strings and the values are all unstored data nodes
  • creates an InlineCalculation node, links all the kwargs as inputs and the returned nodes as outputs, using the keys as link labels
  • stores all the nodes (including, possibly, unstored input nodes given as kwargs)
  • returns a length-two tuple, where the first element is the InlineCalculation node, and the second is the dictionary returned by the wrapped function

To use this function, you can use it as a decorator of a wrapped function:

@make_inline
def copy_inline(source):
    return {copy: source.copy()}

In this way, every time you call copy_inline, the wrapped version is actually called, and the return value will be a tuple with the InlineCalculation instance, and the returned dictionary. For instance, if s is a valid Data node, with the following lines:

c, s_copy_dict = copy_inline(source=s)
s_copy = s_copy_dict['copy']

c will contain the new InlineCalculation instance, s_copy the (stored) copy of s (with the side effect that, if s was not stored, after the function call it will be automatically stored).

Note:If you use a wrapper, make sure to write explicitly in the docstrings that the function is going to store the nodes.

The second possibility, if you want that by default the function does not store anything, but can be wrapped when it is necessary, is the following. You simply define the function you want to wrap (copy_inline in the example above) without decorator:

def copy_inline(source):
   return {copy: source.copy()}

This is a normal function, so to call it you will normally do:

s_copy_dict = copy_inline(s)

while if you want to wrap it, so that an InlineCalculation is created, and everything is stored, you will run:

c, s_copy_dict = make_inline(f)(s=s)

Note that, with the wrapper, all the parameters to f() have to be passed as keyworded arguments. Moreover, the return value is different, i.e. (c, s_copy_dict) instead of simply s_copy_dict.

Note

EXTREMELY IMPORTANT! The wrapped function MUST have the following requirements in order to be reproducible. These requirements cannot be enforced, but must be followed when writing the wrapped function.

  • The function MUST NOT USE information that is not passed in the kwargs. In particular, it cannot read files from the hard-drive (that will not be present in another user’s computer), it cannot connect to external databases and retrieve the current entries in that database (that could change over time), etc.
  • The only exception to the above rule is the access to the AiiDA database for the parents of the input nodes. That is, you can take the input nodes passed as kwargs, and use also the data given in their inputs, the inputs of their inputs, ... but you CANNOT use any output of any of the above-mentioned nodes (that could change over time).
  • The function MUST NOT have side effects (creating files on the disk, adding entries to an external database, ...).

Note

The function will also store:

  • the source of the function in an attribute “source_code”, and the first line at which the function appears (attribute “first_line_source_code”), as returned by inspect.getsourcelines;
  • the full source file in “source_file”, if it is possible to retrieve it (this will be set to None otherwise, e.g. if the function was defined in the interactive shell).

For this reason, try to keep, if possible, all the code to be run within the same file, so that it is possible to keep the provenance of the functions that were run (if you instead call a function in a different file, you will never know in the future what that function did). If you call external modules and you matter about provenance, if would be good to also return in a suitable dictionary the version of these modules (e.g., after importing a module XXX, you can check if the module defines a variable XXX.__version__ or XXX.VERSION or something similar, and store it in an output node).

Todo:

For the time being, I am storing the function source code and the full source code file in the attributes of the calculation. To be moved to an input Code node!

Note:

All nodes will be stored, including unstored input nodes!!

Parameters:

kwargs – all kwargs are passed to the wrapped function

Returns:

a length-two tuple, where the first element is the InlineCalculation node, and the second is the dictionary returned by the wrapped function. All nodes are stored.

Raises:
  • TypeError – if the return value is not a dictionary, the keys are not strings, or the values are not data nodes. Raise also if the input values are not data nodes.
  • ModificationNotAllowed – if the returned Data nodes are already stored.
  • Exception – All other exceptions from the wrapped function are not catched.

TemplateReplacer

This is a simple plugin that takes two node inputs, both of type ParameterData, with the following labels: template and parameters. 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.

TODO: probably use Python’s Template strings instead?? TODO: catch exceptions

class aiida.orm.calculation.job.simpleplugins.templatereplacer.TemplatereplacerCalculation(**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.