ORM documentation: generic aiida.orm

This section describes the aiida object-relational mapping.

Some generic methods of the module aiida.orm.utils

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 to 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.load_node(node_id=None, pk=None, uuid=None, parent_class=None)[source]

Return an AiiDA node given PK or UUID.

Parameters:
  • node_id – PK (integer) or UUID (string) or a node
  • pk – PK of a node
  • uuid – UUID of a node
  • parent_class – if specified, checks whether the node loaded is a subclass of parent_class
Returns:

an AiiDA node

Raises:
  • ValueError – if none or more than one of parameters is supplied or type of node_id is neither string nor integer.
  • NotExistent – if the parent_class is specified and no matching Node is found.
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 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)

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.

__init__(**kwargs)[source]

Initialize the object Node.

Parameters:uuid (optional) – if present, the Node with given uuid is loaded from the database. (It is not possible to assign a uuid to a new Node.)
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
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.

attrs()[source]

Returns the keys of the attributes.

Returns:a list of strings
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
ctime

Return the creation time of the node.

dbnode
Returns:the corresponding DbNode object.
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
description

Get the description of the node.

Returns:a string
extras()[source]

Get the keys of the extras.

Returns:a list of strings
folder

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

Returns:the RepositoryFolder object.
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)

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

Get the attribute.

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

attribute value

Raises:

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

get_attrs()[source]

Return a dictionary with all attributes of this node.

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

Get the computer associated to the node.

Returns:the Computer object or None.
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 (str) – key name
  • value (optional) – if no attribute key is found, returns value
Returns:

the key value

Raises:

ValueError – If more than two arguments are passed to get_extra

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

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

Parameters:subfolder (str,optional) – get the list of a subfolder
Returns:a list of strings.
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.
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}

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

Get the user.

Returns:a Django DbUser model object
has_children

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

has_parents

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

id
Returns:the principal key (the ID) as an integer, or None if the node was not stored yet
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

iterattrs()[source]

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

Todo:optimize! At the moment, the call is very slow because it is also calling attr.getvalue() for each attribute, that has to perform complicated queries to rebuild the object.
Parameters:also_updatable (bool) – if False, does not iterate over attributes that are updatable
iterextras()[source]

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

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

Get the label of the node.

Returns:a string.
logger

Get the logger of the Node object.

Returns:Logger object
mtime

Return the modification time of the node.

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

pk
Returns:the principal key (the ID) as an integer, or None if the node was not stored yet
classmethod 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.

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.

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.
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.
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
set_extra(key, value, exclusive=False)[source]

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

Parameters:
  • key (string) – 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.

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
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!
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!
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.
__init__(node)[source]
Parameters:node – the node object.
class aiida.orm.implementation.general.node.NodeInputManager(node)[source]

To document

__init__(node)[source]
Parameters:node – the node object.
class aiida.orm.implementation.general.node.NodeOutputManager(node)[source]

To document

__init__(node)[source]
Parameters:node – the node object.

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 (str,optional) – 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(label, computername=None, useremail=None)[source]

Get a code from its label.

Parameters:
  • label – the code label
  • computername – filter only codes on computers with this name
  • useremail – filter only codes belonging to a user with this email
Raises:
  • NotExistent – if no matches are found
  • MultipleObjectsError – if multiple matches are found. In this case you may want to pass the additional parameters to filter the codes, or relabel the codes.
get_append_text()[source]

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

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, that can either be the numeric ID (pk), or the label (if unique); the label can either be simply the label, or in the format label@machinename. See the note below for details on the string detection algorithm.

Note

If a string that can be converted to an integer is given, the numeric ID is verified first (therefore, is a code A with a label equal to the ID of another code B is present, code A cannot be referenced by label). Similarly, 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:
  • NotExistent – if no code identified by the given string is found
  • MultipleObjectsError – if the string cannot identify uniquely a code
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.

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

Convert the AiiDA StructureData into another python object

Parameters:object_format – Specify the output format
export(fname, fileformat=None)[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.
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().

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, weights, name (..) – any further parameter is passed to the constructor of the Kind object. For the ‘name’ parameter, see 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_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:
  • ModificationNotAllowed – if object is stored already
  • ValueError – if positions are invalid

Note

it is assumed that the order of the new_positions is given in the same order of the one it’s substituting, i.e. the kind of the site will not be checked.

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 pyspglib
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_structuredata_from_qeinput(filepath=None, text=None)[source]

Function that receives either :param filepath: the filepath storing or :param text: the string of a standard QE-input file. An instance of StructureData() is initialized with kinds, positions and cell as defined in the input file. This function can deal with ibrav being set different from 0 and the cell being defined with celldm(n) or A,B,C, cosAB etc.

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_pyspglib()[source]
Returns:True if the pyspglib 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_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 behaviour of the older versions of the read_cif. It behaves similarly with the older and newer versions of ase.io.cif.read_cif.

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, 0, 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

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.

cell

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

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

Return the list of kpoints

Parameters:
  • also_weights – if True, returns also the list of weights. Default = False
  • cartesian – if True, returns points in cartesian coordinates, otherwise, returns in crystal coordinates. Default = False.
get_kpoints_mesh(print_list=False)[source]

Get the mesh of kpoints.

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

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

pbc

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

Returns:a tuple of three booleans, each one tells if there are periodic boundary conditions for the i-th real-space direction (i=1,2,3)
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.

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

step_to_structure(index, custom_kinds=None)[source]

Deprecated since version 0.7: Use get_step_structure() instead.

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
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
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_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 explicitely by a user.

__init__(calc)[source]
Parameters:calc – the calculation object.

Quantum ESPRESSO

Quantum Espresso - pw.x

Plugin to create a Quantum Espresso pw.x file.

class aiida.orm.calculation.job.quantumespresso.pw.PwCalculation(**kwargs)[source]

Main DFT code (PWscf, pw.x) of the Quantum ESPRESSO distribution. For more information, refer to http://www.quantum-espresso.org/

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

Validate if the keywords are valid Quantum ESPRESSO pw.x keywords, and also helps in preparing the input parameter dictionary in a ‘standardized’ form (e.g., converts ints to floats when required, or if the flag flat_mode is specified, puts the keywords in the right namelists).

This function calls aiida.orm.calculation.job.quantumespresso.helpers.pw_input_helper(), see its docstring for further information.

exception aiida.orm.calculation.job.quantumespresso.helpers.QEInputValidationError[source]

This class is the exception that is generated by the parser when it encounters an error while creating the input file of Quantum ESPRESSO.

aiida.orm.calculation.job.quantumespresso.helpers.pw_input_helper(input_params, structure, stop_at_first_error=False, flat_mode=False, version='5.4.0')[source]

Validate if the input dictionary for Quantum ESPRESSO is valid. Return the dictionary (possibly with small variations: e.g. convert integer to float where necessary, recreate the proper structure if flat_mode is True, ...) to use as input parameters (use_parameters) for the pw.x calculation.

Parameters:
  • input_params
    If flat_mode is True, pass a dictionary
    with ‘key’ = value; use the correct type (int, bool, ...) for value. If an array is required:
    • if its length is fixed: pass a list of the required length
    • if its length is ‘ntyp’: pass a dictionary, associating each specie to its value.
    • (other lengths are not supported)

    Example:

    {
    'calculation': 'vc-relax',
    'ecutwfc': 30.,
    'hubbard_u': {'O': 1},
    }
    

    If instead flat_mode is False, pass a dictionary in the format expected by AiiDA (keys are namelists, values are in the format specified above, i.e. key/value pairs for all keywords in the given namelist). Example:

    {
        'CONTROL': {
            'calculation': 'vc-relax'
            }, 
        'SYSTEM': {
            'hubbard_u': {'O': 1.0}, 
            'ecutwfc': 30.,
            },
    },
    
  • structure – the StructureData object used as input for QE pw.x
  • stop_at_first_error – if True, stops at the first error. Otherwise, when, possible, continue and give a global error for all the issues encountered.
  • flat_mode – if True, instead of passing the dictionary of namelists, and inside the keywords, pass directly the keywords - this function will return the correct dictionary to pass to the PwCalculation, with the keywords arranged in the correct namelist.
  • version – string with version number, used to find the correct XML file descriptor. If not specified, uses the most recent version available in the validator. It reads the definitions from the XML files in the same folder as this python module. If the version is not recognised, the Exception message will also suggest a close-by version.
Raises:

QeInputValidationError – (subclass of InputValidationError) if the input is not considered valid.

Quantum Espresso - Dos

Quantum Espresso - Projwfc

Quantum Espresso - PW immigrant

Plugin to immigrate a Quantum Espresso pw.x job that was not run using AiiDa.

class aiida.orm.calculation.job.quantumespresso.pwimmigrant.PwimmigrantCalculation(**kwargs)[source]

Create a PwCalculation object that can be used to import old jobs.

This is a sublass of aiida.orm.calculation.quantumespresso.PwCalculation with slight modifications to some of the class variables and additional methods that

  1. parse the job’s input file to create the calculation’s input nodes that would exist if the calculation were submitted using AiiDa,
  2. bypass the functions of the daemon, and prepare the node’s attributes such that all the processes (copying of the files to the repository, results parsing, ect.) can be performed

Note

The keyword arguments of PwCalculation are also available.

Parameters:
  • remote_workdir (str) – Absolute path to the directory where the job was run. The transport of the computer you link ask input to the calculation is the transport that will be used to retrieve the calculation’s files. Therefore, remote_workdir should be the absolute path to the job’s directory on that computer.
  • input_file_name (str) – The file name of the job’s input file.
  • output_file_name (str) – The file name of the job’s output file (i.e. the file containing the stdout of QE).
create_input_nodes(open_transport, input_file_name=None, output_file_name=None, remote_workdir=None)[source]

Create calculation input nodes based on the job’s files.

Parameters:open_transport (aiida.transport.plugins.local.LocalTransport | aiida.transport.plugins.ssh.SshTransport) – An open instance of the transport class of the calculation’s computer. See the tutorial for more information.

This method parses the files in the job’s remote working directory to create the input nodes that would exist if the calculation were submitted using AiiDa. These nodes are

  • a 'parameters' ParameterData node, based on the namelists and their variable-value pairs;
  • a 'kpoints' KpointsData node, based on the K_POINTS card;
  • a 'structure' StructureData node, based on the ATOMIC_POSITIONS and CELL_PARAMETERS cards;
  • one 'pseudo_X' UpfData node for the pseudopotential used for the atomic species with name X, as specified in the ATOMIC_SPECIES card;
  • a 'settings' ParameterData node, if there are any fixed coordinates, or if the gamma kpoint is used;

and can be retrieved as a dictionary using the get_inputs_dict() method. These input links are cached-links; nothing is stored by this method (including the calculation node itself).

Note

QE stores the calculation’s pseudopotential files in the <outdir>/<prefix>.save/ subfolder of the job’s working directory, where outdir and prefix are QE CONTROL variables (see pw input file description). This method uses these files to either get–if the a node already exists for the pseudo–or create a UpfData node for each pseudopotential.

Keyword arguments

Note

These keyword arguments can also be set when instantiating the class or using the set_ methods (e.g. set_remote_workdir). Offering to set them here simply offers the user an additional place to set their values. Only the values that have not yet been set need to be specified.

Parameters:
  • input_file_name (str) – The file name of the job’s input file.
  • output_file_name (str) – The file name of the job’s output file (i.e. the file containing the stdout of QE).
  • remote_workdir (str) – Absolute path to the directory where the job was run. The transport of the computer you link ask input to the calculation is the transport that will be used to retrieve the calculation’s files. Therefore, remote_workdir should be the absolute path to the job’s directory on that computer.
Raises:
prepare_for_retrieval_and_parsing(open_transport)[source]

Tell the daemon that the calculation is computed and ready to be parsed.

Parameters:open_transport (aiida.transport.plugins.local.LocalTransport | aiida.transport.plugins.ssh.SshTransport) – An open instance of the transport class of the calculation’s computer. See the tutorial for more information.

The next time the daemon updates the status of calculations, it will see this job is in the ‘COMPUTED’ state and will retrieve its output files and parse the results.

If the daemon is not currently running, nothing will happen until it is started again.

This method also stores the calculation and all input nodes. It also copies the original input file to the calculation’s repository folder.

Raises:
set_input_file_name(input_file_name)[source]

Set the file name of the job’s input file (e.g. 'pw.in').

Parameters:input_file_name (str) – The file name of the job’s input file.
set_output_file_name(output_file_name)[source]

Set the file name of the job’s output file (e.g. 'pw.out').

Parameters:output_file_name (str) – The file name of file containing the job’s stdout.
set_output_subfolder(output_subfolder)[source]

Manually set the job’s outdir variable (e.g. './out/').

Note

The outdir variable is normally set automatically by

  1. looking for the outdir CONTROL namelist variable
  2. looking for the $ESPRESSO_TMPDIR environment variable on the calculation’s computer (using the transport)
  3. using the QE default, the calculation’s remote_workdir

but this method is made available to the user, in the event that they wish to set it manually.

Parameters:output_subfolder (str) – The job’s outdir variable.
set_prefix(prefix)[source]

Manually set the job’s prefix variable (e.g. 'pwscf').

Note

The prefix variable is normally set automatically by

  1. looking for the prefix CONTROL namelist variable
  2. using the QE default, 'pwscf'

but this method is made available to the user, in the event that they wish to set it manually.

Parameters:prefix (str) – The job’s prefix variable.
set_remote_workdir(remote_workdir)[source]

Set the job’s remote working directory.

Parameters:remote_workdir (str) – Absolute path of the job’s remote working directory.

Wannier90 - Wannier90

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.