In this module, AiiDA provides REST API to access different AiiDA nodes stored in database. The REST API is implemented using Flask RESTFul framework.
Implementation of RESTful API for AiiDA based on flask and flask_restful.
Author: Snehal P. Waychal and Fernando Gargiulo @ Theos, EPFL
aiida.restapi.api.
AiidaApi
Bases: flask_restful.Api
flask_restful.Api
AiiDA customized version of the flask_restful Api class
__init__
The need to have a special constructor is to include directly the addition of resources with the parameters required to initialize the resource classes.
kwargs – parameters to be passed to the resources for configuration and PREFIX
__module__
handle_error
this method handles the 404 “URL not found” exception and return custom message :param e: raised exception :return: list of available endpoints
App
Bases: flask.app.Flask
flask.app.Flask
Basic Flask App customized for this REST Api purposes
Initialize self. See help(type(self)) for accurate signature.
Resources for REST API
aiida.restapi.resources.
BaseResource
Bases: flask_restful.Resource
flask_restful.Resource
Each derived class will instantiate a different type of translator. This is the only difference in the classes.
BaseTranslator
Bases: object
object
Generic class for translator. It contains the methods required to build a related QueryBuilder object
__dict__
Initialise the parameters. Create the basic query_help
keyword Class (default None but becomes this class): is the class from which one takes the initial values of the attributes. By default is this class so that class atributes are translated into object attributes. In case of inheritance one cane use the same constructore but pass the inheriting class to pass its attributes.
__label__
__repr__
This function is required for the caching system to be able to compare two NodeTranslator objects. Comparison is done on the value returned by __repr__
representation of NodeTranslator objects. Returns nothing because the inputs of self.get_nodes are sufficient to determine the identity of two queries.
__weakref__
list of weak references to the object (if defined)
_aiida_class
_aiida_type
_check_id_validity
Checks whether id corresponds to an object of the expected type, whenever type is a valid column of the database (ex. for nodes, but not for users)
node_id – id (or id starting pattern)
True if node_id valid, False if invalid. If True, sets the id filter attribute correctly
RestValidationError – if no node is found or id pattern does not identify a unique node
_default
_default_projections
_has_uuid
_is_id_query
_is_qb_initialized
_result_type
_total_count
count
Count the number of rows returned by the query and set total_count
get_default_projections
method to get default projections of the node :return: self._default_projections
get_formatted_result
Runs the query and retrieves results tagged as “label”.
label (str) – the tag of the results to be extracted out of the query rows.
a list of the query results
get_projectable_properties
This method is extended in specific translators classes. It returns a dict as follows: dict(fields=projectable_properties, ordering=ordering) where projectable_properties is a dict and ordering is a list
get_query_help
return QB json dictionary
get_results
Returns either list of nodes or details of single node from database.
either list of nodes or details of single node from database
get_total_count
Returns the number of rows of the query.
total_count
init_qb
Initialize query builder object by means of _query_help
set_default_projections
It calls the set_projections() methods internally to add the default projections in query_help
None
set_filters
Add filters in query_help.
filters –
it is a dictionary where keys are the tag names given in the path in query_help and their values are the dictionary of filters want to add for that tag name. Format for the Filters dictionary:
filters = { "tag1" : {k1:v1, k2:v2}, "tag2" : {k1:v1, k2:v2}, }
query_help dict including filters if any.
set_limit_offset
sets limits and offset directly to the query_builder object
limit –
offset –
set_order
Add order_by clause in query_help :param orders: dictionary of orders you want to apply on final results :return: None or exception if any.
set_projections
add the projections in query_help
projections – it is a dictionary where keys are the tag names given in the path in query_help and values are the list of the names you want to project in the final output
updated query_help with projections
set_query
Adds filters, default projections, order specs to the query_help, and initializes the qb object
filters – dictionary with the filters
orders – dictionary with the order for each tag
projections – dictionary with the projection. It is discarded if query_type==’attributes’/’extras’
query_type – (string) specify the result or the content (“attr”)
id – (integer) id of a specific node
filename – name of the file to return its content
attributes – flag to show attributes in nodes endpoint
attributes_filter – list of node attributes to query
extras – flag to show attributes in nodes endpoint
extras_filter – list of node extras to query
_load_and_verify
Load node and verify it is of the required type
_parse_pk_uuid
_translator_class
alias of aiida.restapi.translator.base.BaseTranslator
aiida.restapi.translator.base.BaseTranslator
get
Get method for the resource :param id: node identifier :param page: page no, used for pagination :return: http response
method_decorators
methods
parse_pk_uuid
CalcJobNode
Bases: aiida.restapi.resources.ProcessNode
aiida.restapi.resources.ProcessNode
Resource for CalcJobNode
CalcJobTranslator
Bases: aiida.restapi.translator.nodes.process.process.ProcessTranslator
aiida.restapi.translator.nodes.process.process.ProcessTranslator
Translator relative to resource ‘calculations’ and aiida class Calculation
Bases: aiida.orm.nodes.process.calculation.calculation.CalculationNode
aiida.orm.nodes.process.calculation.calculation.CalculationNode
ORM class for all nodes representing the execution of a CalcJob.
CALC_JOB_STATE_KEY
REMOTE_WORKDIR_KEY
RETRIEVE_LIST_KEY
RETRIEVE_SINGLE_FILE_LIST_KEY
RETRIEVE_TEMPORARY_LIST_KEY
SCHEDULER_DETAILED_JOB_INFO_KEY
SCHEDULER_JOB_ID_KEY
SCHEDULER_LAST_CHECK_TIME_KEY
SCHEDULER_LAST_JOB_INFO_KEY
SCHEDULER_STATE_KEY
__abstractmethods__
_abc_impl
_get_objects_to_hash
Return a list of objects which should be included in the hash.
This method is purposefully overridden from the base Node class, because we do not want to include the repository folder in the hash. The reason is that the hash of this node is computed in the store method, at which point the input files that will be stored in the repository have not yet been generated. Including these anyway in the computation of the hash would mean that the hash of the node would change as soon as the process has started and the input files have been written to the repository.
_hash_ignored_attributes
_logger
_plugin_type_string
_query_type_string
_raw_input_folder
Get the input folder object.
the input folder object.
NotExistent: if the raw folder hasn’t been created yet
_repository_base_path
_tools
_updatable_attributes
_validate_retrieval_directive
Validate a list or tuple of file retrieval directives.
directives – a list or tuple of file retrieveal directives
ValueError – if the format of the directives is invalid
delete_state
Delete the calculation job state attribute if it exists.
get_authinfo
Return the AuthInfo that is configured for the Computer set for this node.
AuthInfo
get_builder_restart
Return a ProcessBuilder that is ready to relaunch the same CalcJob that created this node.
The process class will be set based on the process_type of this node and the inputs of the builder will be prepopulated with the inputs registered for this node. This functionality is very useful if a process has completed and you want to relaunch it with slightly different inputs.
In addition to prepopulating the input nodes, which is implemented by the base ProcessNode class, here we also add the options that were passed in the metadata input of the CalcJob process.
~aiida.engine.processes.builder.ProcessBuilder instance
get_description
Return a string with a description of the node based on its properties.
get_detailed_job_info
Return the detailed job info dictionary.
the dictionary with detailed job info if defined or None
get_job_id
Return job id that was assigned to the calculation by the scheduler.
the string representation of the scheduler job id
get_last_job_info
Return the last information asked to the scheduler about the status of the job.
a JobInfo object (that closely resembles a dictionary) or None.
get_option
Retun the value of an option that was set for this CalcJobNode
name – the option name
the option value or None
ValueError for unknown option
get_options
Return the dictionary of options set for this CalcJobNode
dictionary of the options and their values
get_parser_class
Return the output parser object for this calculation or None if no parser is set.
a Parser class.
aiida.common.exceptions.EntryPointError – if the parser entry point can not be resolved.
get_remote_workdir
Return the path to the remote (on cluster) scratch folder of the calculation.
a string with the remote path
get_retrieve_list
Return the list of files/directories to be retrieved on the cluster after the calculation has completed.
a list of file directives
get_retrieve_singlefile_list
Return the list of files to be retrieved on the cluster after the calculation has completed.
list of single file retrieval directives
Deprecated since version 1.0.0: Will be removed in v2.0.0, use aiida.orm.nodes.process.calculation.calcjob.CalcJobNode.get_retrieve_temporary_list() instead.
aiida.orm.nodes.process.calculation.calcjob.CalcJobNode.get_retrieve_temporary_list()
get_retrieve_temporary_list
Return list of files to be retrieved from the cluster which will be available during parsing.
get_retrieved_node
Return the retrieved data folder.
the retrieved FolderData node or None if not found
get_scheduler_lastchecktime
Return the time of the last update of the scheduler state by the daemon or None if it was never set.
a datetime object or None
get_scheduler_state
Return the status of the calculation according to the cluster scheduler.
a JobState enum instance.
get_scheduler_stderr
Return the scheduler stdout output if the calculation has finished and been retrieved, None otherwise.
scheduler stdout output or None
get_scheduler_stdout
Return the scheduler stderr output if the calculation has finished and been retrieved, None otherwise.
scheduler stderr output or None
get_state
Return the calculation job active sub state.
The calculation job state serves to give more granular state information to CalcJobs, in addition to the generic process state, while the calculation job is active. The state can take values from the enumeration defined in aiida.common.datastructures.CalcJobState and can be used to query for calculation jobs in specific active states.
instance of aiida.common.datastructures.CalcJobState or None if invalid value, or not set
get_transport
Return the transport for this calculation.
Transport configured with the AuthInfo associated to the computer of this node
link_label_retrieved
Return the link label used for the retrieved FolderData node.
res
To be used to get direct access to the parsed parameters.
an instance of the CalcJobResultManager.
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_detailed_job_info
Set the detailed job info dictionary.
detailed_job_info – a dictionary with metadata with the accounting of a completed job
set_job_id
Set the job id that was assigned to the calculation by the scheduler.
Note
the id will always be stored as a string
job_id – the id assigned by the scheduler after submission
set_last_job_info
Set the last job info.
last_job_info – a JobInfo object
set_option
Set an option to the given value
value – the value to set
TypeError for values with invalid type
set_options
Set the options for this CalcJobNode
options – dictionary of option and their values to set
set_remote_workdir
Set the absolute path to the working directory on the remote computer where the calculation is run.
remote_workdir – absolute filepath to the remote working directory
set_retrieve_list
Set the retrieve list.
This list of directives will instruct the daemon what files to retrieve after the calculation has completed. list or tuple of files or paths that should be retrieved by the daemon.
retrieve_list – list or tuple of with filepath directives
set_retrieve_singlefile_list
Set the retrieve singlefile list.
The files will be stored as SinglefileData instances and added as output nodes to this calculation node. The format of a single file directive is a tuple or list of length 3 with the following entries:
the link label under which the file should be added the SinglefileData class or sub class to use to store the filepath relative to the remote working directory of the calculation
the link label under which the file should be added
the SinglefileData class or sub class to use to store
the filepath relative to the remote working directory of the calculation
retrieve_singlefile_list – list or tuple of single file directives
Deprecated since version 1.0.0: Will be removed in v2.0.0. Use set_retrieve_temporary_list() instead.
set_retrieve_temporary_list()
set_retrieve_temporary_list
Set the retrieve temporary list.
The retrieve temporary list stores files that are retrieved after completion and made available during parsing and are deleted as soon as the parsing has been completed.
retrieve_temporary_list – list or tuple of with filepath directives
set_scheduler_state
Set the scheduler state.
state – an instance of JobState
set_state
Set the calculation active job state.
state – a string with the state from aiida.common.datastructures.CalcJobState.
aiida.common.datastructures.CalcJobState
ValueError if state is invalid
tools
Return the calculation tools that are registered for the process type associated with this calculation.
If the entry point name stored in the process_type of the CalcJobNode has an accompanying entry point in the aiida.tools.calculations entry point category, it will attempt to load the entry point and instantiate it passing the node to the constructor. If the entry point does not exist, cannot be resolved or loaded, a warning will be logged and the base CalculationTools class will be instantiated and returned.
CalculationTools instance
alias of aiida.orm.nodes.process.calculation.calcjob.CalcJobNode
aiida.orm.nodes.process.calculation.calcjob.CalcJobNode
get_derived_properties
Generic function extended for calcjob. Currently it is not implemented.
node – node object
empty dict
get_input_files
Get the submitted input files for job calculation :param node: aiida node :return: the retrieved input files for job calculation
get_output_files
Get the retrieved output files for job calculation :param node: aiida node :return: the retrieved output files for job calculation
alias of aiida.restapi.translator.nodes.process.calculation.calcjob.CalcJobTranslator
aiida.restapi.translator.nodes.process.calculation.calcjob.CalcJobTranslator
Get method for the Process resource.
id – node identifier
http response
Computer
Bases: aiida.restapi.resources.BaseResource
aiida.restapi.resources.BaseResource
Resource for Computer
ComputerTranslator
Bases: aiida.restapi.translator.base.BaseTranslator
Translator relative to resource ‘computers’ and aiida class Computer
alias of aiida.orm.computers.Computer
aiida.orm.computers.Computer
Get projectable properties specific for Computer :return: dict of projectable properties and column_order list
alias of aiida.restapi.translator.computer.ComputerTranslator
aiida.restapi.translator.computer.ComputerTranslator
Group
Resource for Group
GroupTranslator
Translator relative to resource ‘groups’ and aiida class Group
alias of aiida.orm.groups.Group
aiida.orm.groups.Group
Get projectable properties specific for Group :return: dict of projectable properties and column_order list
alias of aiida.restapi.translator.group.GroupTranslator
aiida.restapi.translator.group.GroupTranslator
Node
Differs from BaseResource in trans.set_query() mostly because it takes query_type as an input and the presence of additional result types like “tree”
NodeTranslator
Translator relative to resource ‘nodes’ and aiida class Node
alias of aiida.orm.nodes.node.Node
aiida.orm.nodes.node.Node
_attributes_filter
_content_type
_download
_download_format
_extras_filter
_filename
_get_content
Used by get_results() in case of endpoint include “content” option :return: data: a dictionary containing the results obtained by running the query
_get_subclasses
Import all submodules of the package containing the present class. Includes subpackages recursively, if specified.
parent – package/class. If package looks for the classes in submodules. If class, first looks for the package where it is contained
parent_class – class of which to look for subclasses
recursive – True/False (go recursively into submodules)
get_all_download_formats
returns dict of possible node formats for all available node types
get_comments
node comments
Generic function to get the derived properties of the node. Actual definition is in child classes as the content to be returned depends on the plugin specific to the resource
node – node object that has to be visualized
derived properties of the node
If this method is called by Node resource it will look for the type of object and invoke the correct method in the lowest-compatible subclass
get_downloadable_data
Generic function to download file in specified format. Actual definition is in child classes as the content to be returned and its format depends on the download plugin specific to the resource
download_format – file extension format
data in selected format to download
If this method is called for a Data node resource it will invoke the get_downloadable_data method in the Data transaltor. Otherwise it raises RestFeatureNotAvailable exception
get_file_content
It reads the file from directory and returns its content.
Instead of using “send_from_directory” from flask, this method is written because in next aiida releases the file can be stored locally or in object storage.
node – aiida folderData node which contains file
file_name – name of the file to return its contents
get_io_tree
json data to display nodes in tree format :param uuid_pattern: main node uuid :return: json data to display node tree
get_namespace
return full_types of the nodes
Get projectable properties specific for Node :return: dict of projectable properties and column_order list
get_repo_contents
Every node in AiiDA is having repo folder. This function returns the metadata using get_object() method :param node: node object :param filename: folder or file name (optional) :return: file content in bytes to download
get_repo_list
Every node in AiiDA is having repo folder. This function returns the metadata using list_objects() method :param node: node object :param filename: folder name (optional) :return: folder list
Returns either a list of nodes or details of single node from database
either a list of nodes or the details of single node from the database
get_statistics
Return statistics for a given node
download_format – file format to download e.g. cif, xyz
attributes – flag to show attributes for nodes
attributes_filter – list of attributes to query
extras – flag to show extras for nodes
extras_filter – list of extras to query
set_query_type
sets one of the mutually exclusive values for self._result_type and self._content_type.
:param query_type:(string) the value assigned to either variable.
alias of aiida.restapi.translator.nodes.node.NodeTranslator
aiida.restapi.translator.nodes.node.NodeTranslator
Get method for the Node resource.
page – page no, used for pagination
ProcessNode
Bases: aiida.restapi.resources.Node
aiida.restapi.resources.Node
Resource for ProcessNode
ProcessTranslator
Bases: aiida.restapi.translator.nodes.node.NodeTranslator
Translator relative to resource ‘data’ and aiida class ~aiida.orm.nodes.data.data.Data
Bases: aiida.orm.utils.mixins.Sealable, aiida.orm.nodes.node.Node
aiida.orm.utils.mixins.Sealable
Base class for all nodes representing the execution of a process
This class and its subclasses serve as proxies in the database, for actual Process instances being run. The Process instance in memory will leverage an instance of this class (the exact sub class depends on the sub class of Process) to persist important information of its state to the database. This serves as a way for the user to inspect the state of the Process during its execution as well as a permanent record of its execution in the provenance graph, after the execution has terminated.
CHECKPOINT_KEY
EXCEPTION_KEY
EXIT_MESSAGE_KEY
EXIT_STATUS_KEY
PROCESS_LABEL_KEY
PROCESS_PAUSED_KEY
PROCESS_STATE_KEY
PROCESS_STATUS_KEY
__str__
Return str(self).
_hash_ignored_inputs
_unstorable_message
called
Return a list of nodes that the process called
list of process nodes called by this process
called_descendants
Return a list of all nodes that have been called downstream of this process
This will recursively find all the called processes for this process and its children.
caller
Return the process node that called this process node, or None if it does not have a caller
process node that called this process node instance or None
checkpoint
Return the checkpoint bundle set for the process
checkpoint bundle if it exists, None otherwise
delete_checkpoint
Delete the checkpoint bundle set for the process
exception
Return the exception of the process or None if the process is not excepted.
If the process is marked as excepted yet there is no exception attribute, an empty string will be returned.
the exception message or None
exit_message
Return the exit message of the process
the exit message
exit_status
Return the exit status of the process
the exit status, an integer exit code or None
Return a ProcessBuilder that is ready to relaunch the process that created this node.
is_excepted
Return whether the process has excepted
Excepted means that during execution of the process, an exception was raised that was not caught.
True if during execution of the process an exception occurred, False otherwise
bool
is_failed
Return whether the process has failed
Failed means that the process terminated nominally but it had a non-zero exit status.
True if the process has failed, False otherwise
is_finished
Return whether the process has finished
Finished means that the process reached a terminal state nominally. Note that this does not necessarily mean successfully, but there were no exceptions and it was not killed.
True if the process has finished, False otherwise
is_finished_ok
Return whether the process has finished successfully
Finished successfully means that it terminated nominally and had a zero exit status.
True if the process has finished successfully, False otherwise
is_killed
Return whether the process was killed
Killed means the process was killed directly by the user or by the calling process being killed.
True if the process was killed, False otherwise
is_terminated
Return whether the process has terminated
Terminated means that the process has reached any terminal state.
True if the process has terminated, False otherwise
is_valid_cache
Return whether the node is valid for caching
True if this process node is valid to be used for caching, False otherwise
logger
Get the logger of the Calculation object, so that it also logs to the DB.
LoggerAdapter object, that works like a logger, but also has the ‘extra’ embedded
pause
Mark the process as paused by setting the corresponding attribute.
This serves only to reflect that the corresponding Process is paused and so this method should not be called by anyone but the Process instance itself.
paused
Return whether the process is paused
True if the Calculation is marked as paused, False otherwise
process_class
Return the process class that was used to create this node.
Process class
ValueError – if no process type is defined, it is an invalid process type string or cannot be resolved to load the corresponding class
process_label
Return the process label
the process label
process_state
Return the process state
the process state instance of ProcessState enum
process_status
Return the process status
The process status is a generic status message e.g. the reason it might be paused or when it is being killed
the process status
set_checkpoint
Set the checkpoint bundle set for the process
state – string representation of the stepper state info
set_exception
Set the exception of the process
exception – the exception message
set_exit_message
Set the exit message of the process, if None nothing will be done
message – a string message
set_exit_status
Set the exit status of the process
state – an integer exit code or None, which will be interpreted as zero
set_process_label
Set the process label
label – process label string
set_process_state
Set the process state
state – value or instance of ProcessState enum
set_process_status
Set the process status
The process status is a generic status message e.g. the reason it might be paused or when it is being killed. If status is None, the corresponding attribute will be deleted.
status – string process status
set_process_type
Set the process type string.
process_type – the process type string identifying the class using this process node as storage.
unpause
Mark the process as unpaused by removing the corresponding attribute.
This serves only to reflect that the corresponding Process is unpaused and so this method should not be called by anyone but the Process instance itself.
validate_incoming
Validate adding a link of the given type from a given node to ourself.
Adding an input link to a ProcessNode once it is stored is illegal because this should be taken care of by the engine in one go. If a link is being added after the node is stored, it is most likely not by the engine and it should not be allowed.
source – the node from which the link is coming
link_type – the link type
link_label – the link label
TypeError – if source is not a Node instance or link_type is not a LinkType enum
ValueError – if the proposed link is invalid
alias of aiida.orm.nodes.process.process.ProcessNode
aiida.orm.nodes.process.process.ProcessNode
Get projectable properties specific for Process nodes :return: dict of projectable properties and column_order list
get_report
Show the log report for one or multiple processes.
alias of aiida.restapi.translator.nodes.process.process.ProcessTranslator
ServerInfo
Endpoint to return general server info
It returns the general info about the REST API :return: returns current AiiDA version defined in aiida/__init__.py
User
Resource for User
UserTranslator
Translator relative to resource ‘users’ and aiida class User
alias of aiida.orm.users.User
aiida.orm.users.User
Get projectable properties specific for User :return: dict of projectable properties and column_order list
alias of aiida.restapi.translator.user.UserTranslator
aiida.restapi.translator.user.UserTranslator
It defines the method with all required parameters to run restapi locally.
aiida.restapi.run_api.
configure_api
Configures a flask.Flask instance and returns it.
flask_app (flask.Flask) – Class inheriting from flask app class
flask.Flask
flask_api (flask_restful.Api) – flask_restful API class to be used to wrap the app
config – directory containing the config.py configuration file
catch_internal_server – If true, catch and print internal server errors with full python traceback. Useful during app development.
wsgi_profile – use WSGI profiler middleware for finding bottlenecks in the web application
Flask RESTful API
run_api
Takes a flask.Flask instance and runs it.
hostname – hostname to run app on (only when using built-in server)
port – port to run app on (only when using built-in server)
config – directory containing the config.py file used to configure the RESTapi
catch_internal_server – If true, catch and print all inter server errors
debug – enable debugging
wsgi_profile – use WSGI profiler middleware for finding bottlenecks in web application
hookup – If true, hook up application to built-in server, else just return it. This parameter is deprecated as of AiiDA 1.2.1. If you don’t intend to run the API (hookup=False) use configure_api instead.
tuple (app, api) if hookup==False or runs app if hookup==True