aiida.common
#
Common data structures, utility classes and functions
Note
Modules in this sub package have to run without a loaded database environment
Package Contents#
Classes#
This class internally stores values in a dictionary, but exposes the keys also as attributes, i.e. asking for attrdict.key will return the value of attrdict[‘key’] and so on. |
|
This object will store the data returned by the calculation plugin and to be passed to the ExecManager. |
|
The sub state of a CalcJobNode while its Process is in an active state (i.e. Running or Waiting). |
|
This attribute-dictionary contains the information needed to execute a code. Possible attributes are: |
|
Enum to indicate the way the codes of a calculation should be run. |
|
A dictionary with access to the keys as attributes, and with an internal value storing the ‘default’ keys to be distinguished from extra fields. |
|
A dictionary with access to the keys as attributes, and with filtering of valid attributes. This is only the base class, without valid attributes; use a derived class to do the actual work. E.g.: |
|
Graph traversal rules when deleting or exporting nodes. |
|
A simple enum of allowed link types. |
|
An abstract class for incrementing a progress reporter. |
|
Mode to use when stashing files from the working directory of a completed calculation job for safekeeping. |
Functions#
Create a callback function to update the progress reporter. |
|
Return the progress reporter |
|
Temporarily adjust the log-level of logger. |
|
Set a tqdm implementation of the progress reporter interface. |
|
Set the progress reporter implementation |
|
Validate the given link label. |
Data#
A namedtuple that defines a graph traversal rule. |
|
API#
- aiida.common.AIIDA_LOGGER = 'cast(...)'#
- exception aiida.common.AiidaException#
Bases:
Exception
Base class for all AiiDA exceptions.
Each module will have its own subclass, inherited from this (e.g. ExecManagerException, TransportException, …)
Initialization
Initialize self. See help(type(self)) for accurate signature.
- class aiida.common.AttributeDict(dictionary=None)#
Bases:
dict
This class internally stores values in a dictionary, but exposes the keys also as attributes, i.e. asking for attrdict.key will return the value of attrdict[‘key’] and so on.
Raises an AttributeError if the key does not exist, when called as an attribute, while the usual KeyError if the key does not exist and the dictionary syntax is used.
Initialization
Recursively turn the dict and all its nested dictionaries into AttributeDict instance.
- __repr__()#
Representation of the object.
- __getattr__(attr)#
Read a key as an attribute.
- Raises:
AttributeError – if the attribute does not correspond to an existing key.
- __setattr__(attr, value)#
Set a key as an attribute.
- __delattr__(attr)#
Delete a key as an attribute.
- Raises:
AttributeError – if the attribute does not correspond to an existing key.
- __deepcopy__(memo=None)#
Deep copy.
- __getstate__()#
Needed for pickling this class.
- __setstate__(dictionary)#
Needed for pickling this class.
- __dir__()#
- class aiida.common.CalcInfo#
Bases:
aiida.common.extendeddicts.DefaultFieldsAttributeDict
This object will store the data returned by the calculation plugin and to be passed to the ExecManager.
In the following descriptions all paths have to be considered relative
- retrieve_list: a list of strings or tuples that indicate files that are to be retrieved from the remote after the
calculation has finished and stored in the
retrieved_folder
output node of typeFolderData
. If the entry in the list is just a string, it is assumed to be the filepath on the remote and it will be copied to the base directory of the retrieved folder, where the name corresponds to the basename of the remote relative path. This means that any remote folder hierarchy is ignored entirely.Remote folder hierarchy can be (partially) maintained by using a tuple instead, with the following format
(source, target, depth)
The
source
andtarget
elements are relative filepaths in the remote and retrieved folder. The contents ofsource
(whether it is a file or folder) are copied in its entirety to thetarget
subdirectory in the retrieved folder. If no subdirectory should be created,'.'
should be specified fortarget
.The
source
filepaths support glob patterns*
in case the exact name of the files that are to be retrieved are not know a priori.The
depth
element can be used to control what level of nesting of the source folder hierarchy should be maintained. Ifdepth
equals0
or1
(they are equivalent), only the basename of thesource
filepath is kept. For each additional level, another subdirectory of the remote hierarchy is kept. For example:(‘path/sub/file.txt’, ‘.’, 2)
will retrieve the
file.txt
and store it under the path:sub/file.txt
- retrieve_temporary_list: a list of strings or tuples that indicate files that will be retrieved
and stored temporarily in a FolderData, that will be available only during the parsing call. The format of the list is the same as that of ‘retrieve_list’
local_copy_list: a list of tuples with format (‘node_uuid’, ‘filename’, relativedestpath’)
remote_copy_list: a list of tuples with format (‘remotemachinename’, ‘remoteabspath’, ‘relativedestpath’)
remote_symlink_list: a list of tuples with format (‘remotemachinename’, ‘remoteabspath’, ‘relativedestpath’)
- provenance_exclude_list: a sequence of relative paths of files in the sandbox folder of a CalcJob instance that
should not be stored permanantly in the repository folder of the corresponding CalcJobNode that will be created, but should only be copied to the remote working directory on the target computer. This is useful for input files that should be copied to the working directory but should not be copied as well to the repository either, for example, because they contain proprietary information or because they are big and their content is already indirectly present in the repository through one of the data nodes passed as input to the calculation.
codes_info: a list of dictionaries used to pass the info of the execution of a code
- codes_run_mode: the mode of execution in which the codes will be run (CodeRunMode.SERIAL by default,
but can also be CodeRunMode.PARALLEL)
- skip_submit: a flag that, when set to True, orders the engine to skip the submit/update steps (so no code will
run, it will only upload the files and then retrieve/parse).
- _default_fields = ('job_environment', 'email', 'email_on_started', 'email_on_terminated', 'uuid', 'prepend_text', 'app...#
- class aiida.common.CalcJobState#
Bases:
enum.Enum
The sub state of a CalcJobNode while its Process is in an active state (i.e. Running or Waiting).
- UPLOADING = 'uploading'#
- SUBMITTING = 'submitting'#
- WITHSCHEDULER = 'withscheduler'#
- STASHING = 'stashing'#
- RETRIEVING = 'retrieving'#
- PARSING = 'parsing'#
- exception aiida.common.ClosedStorage#
Bases:
aiida.common.exceptions.AiidaException
Raised when trying to access data from a closed storage backend.
Initialization
Initialize self. See help(type(self)) for accurate signature.
- class aiida.common.CodeInfo#
Bases:
aiida.common.extendeddicts.DefaultFieldsAttributeDict
This attribute-dictionary contains the information needed to execute a code. Possible attributes are:
cmdline_params
: a list of strings, containing parameters to be written on the command line right after the call to the code, as for example:code.x cmdline_params[0] cmdline_params[1] ... < stdin > stdout
stdin_name
: (optional) the name of the standard input file. Note, it is only possible to use the stdin with the syntax:code.x < stdin_name
If no stdin_name is specified, the string “< stdin_name” will not be passed to the code. Note: it is not possible to substitute/remove the ‘<’ if stdin_name is specified; if that is needed, avoid stdin_name and use instead the cmdline_params to specify a suitable syntax.
stdout_name
: (optional) the name of the standard output file. Note, it is only possible to pass output to stdout_name with the syntax:code.x ... > stdout_name
If no stdout_name is specified, the string “> stdout_name” will not be passed to the code. Note: it is not possible to substitute/remove the ‘>’ if stdout_name is specified; if that is needed, avoid stdout_name and use instead the cmdline_params to specify a suitable syntax.
stderr_name
: (optional) a string, the name of the error file of the code.join_files
: (optional) if True, redirects the error to the output file. If join_files=True, the code will be called as:code.x ... > stdout_name 2>&1
otherwise, if join_files=False and stderr is passed:
code.x ... > stdout_name 2> stderr_name
withmpi
: if True, executes the code with mpirun (or another MPI installed on the remote computer)code_uuid
: the uuid of the code associated to the CodeInfo
- _default_fields = ('cmdline_params', 'stdin_name', 'stdout_name', 'stderr_name', 'join_files', 'withmpi', 'code_uuid')#
- class aiida.common.CodeRunMode#
Bases:
enum.IntEnum
Enum to indicate the way the codes of a calculation should be run.
For PARALLEL, the codes for a given calculation will be run in parallel by running them in the background:
code1.x & code2.x &
For the SERIAL option, codes will be executed sequentially by running for example the following:
code1.x code2.x
Initialization
Initialize self. See help(type(self)) for accurate signature.
- SERIAL = 0#
- PARALLEL = 1#
- exception aiida.common.ConfigurationError#
Bases:
aiida.common.exceptions.AiidaException
Error raised when there is a configuration error in AiiDA.
Initialization
Initialize self. See help(type(self)) for accurate signature.
- exception aiida.common.ConfigurationVersionError#
Bases:
aiida.common.exceptions.ConfigurationError
Configuration error raised when the configuration file version is not compatible with the current version.
Initialization
Initialize self. See help(type(self)) for accurate signature.
- exception aiida.common.ContentNotExistent#
Bases:
aiida.common.exceptions.NotExistent
Raised when trying to access an attribute, a key or a file in the result nodes that is not present
Initialization
Initialize self. See help(type(self)) for accurate signature.
- exception aiida.common.CorruptStorage#
Bases:
aiida.common.exceptions.ConfigurationError
Raised when the storage is not found to be internally consistent on validation.
Initialization
Initialize self. See help(type(self)) for accurate signature.
- exception aiida.common.DbContentError#
Bases:
aiida.common.exceptions.AiidaException
Raised when the content of the DB is not valid. This should never happen if the user does not play directly with the DB.
Initialization
Initialize self. See help(type(self)) for accurate signature.
- class aiida.common.DefaultFieldsAttributeDict(dictionary=None)#
Bases:
aiida.common.extendeddicts.AttributeDict
A dictionary with access to the keys as attributes, and with an internal value storing the ‘default’ keys to be distinguished from extra fields.
Extra methods defaultkeys() and extrakeys() divide the set returned by keys() in default keys (i.e. those defined at definition time) and other keys. There is also a method get_default_fields() to return the internal list.
Moreover, for undefined default keys, it returns None instead of raising a KeyError/AttributeError exception.
Remember to define the _default_fields in a subclass! E.g.:
class TestExample(DefaultFieldsAttributeDict): _default_fields = ('a','b','c')
When the validate() method is called, it calls in turn all validate_KEY methods, where KEY is one of the default keys. If the method is not present, the field is considered to be always valid. Each validate_KEY method should accept a single argument ‘value’ that will contain the value to be checked.
It raises a ValidationError if any of the validate_KEY function raises an exception, otherwise it simply returns. NOTE: the validate_* functions are called also for unset fields, so if the field can be empty on validation, you have to start your validation function with something similar to:
if value is None: return
Initialization
Recursively turn the dict and all its nested dictionaries into AttributeDict instance.
- _default_fields = 'tuple(...)'#
- validate()#
Validate the keys, if any
validate_*
method is available.
- __setattr__(attr, value)#
Overridden to allow direct access to fields with underscore.
- __getitem__(key)#
Return None instead of raising an exception if the key does not exist but is in the list of default fields.
- classmethod get_default_fields()#
Return the list of default fields, either defined in the instance or not.
- defaultkeys()#
Return the default keys defined in the instance.
- extrakeys()#
Return the extra keys defined in the instance.
- exception aiida.common.EntryPointError#
Bases:
aiida.common.exceptions.AiidaException
Raised when an entry point cannot be uniquely resolved and imported.
Initialization
Initialize self. See help(type(self)) for accurate signature.
- exception aiida.common.FailedError#
Bases:
aiida.common.exceptions.AiidaException
Raised when accessing a calculation that is in the FAILED status
Initialization
Initialize self. See help(type(self)) for accurate signature.
- exception aiida.common.FeatureDisabled#
Bases:
aiida.common.exceptions.AiidaException
Raised when a feature is requested, but the user has chosen to disable it (e.g., for submissions on disabled computers).
Initialization
Initialize self. See help(type(self)) for accurate signature.
- exception aiida.common.FeatureNotAvailable#
Bases:
aiida.common.exceptions.AiidaException
Raised when a feature is requested from a plugin, that is not available.
Initialization
Initialize self. See help(type(self)) for accurate signature.
- class aiida.common.FixedFieldsAttributeDict(init=None)#
Bases:
aiida.common.extendeddicts.AttributeDict
A dictionary with access to the keys as attributes, and with filtering of valid attributes. This is only the base class, without valid attributes; use a derived class to do the actual work. E.g.:
class TestExample(FixedFieldsAttributeDict): _valid_fields = ('a','b','c')
Initialization
Recursively turn the dict and all its nested dictionaries into AttributeDict instance.
- _valid_fields = 'tuple(...)'#
- __setitem__(item, value)#
Set a key as an attribute.
- __setattr__(attr, value)#
Overridden to allow direct access to fields with underscore.
- classmethod get_valid_fields()#
Return the list of valid fields.
- __dir__()#
- aiida.common.GraphTraversalRule = 'namedtuple(...)'#
A namedtuple that defines a graph traversal rule.
When starting from a certain sub set of nodes, the graph traversal rules specify which links should be followed to add adjacent nodes to finally arrive at a set of nodes that represent a valid and consistent sub graph.
- Parameters:
link_type – the LinkType that the rule applies to
direction – whether the link type should be followed backwards or forwards
toggleable – boolean to indicate whether the rule can be changed from the default value. If this is False it means the default value can never be changed as it will result in an inconsistent graph.
default – boolean, the default value of the rule, if True means that the link type for the given direction should be followed.
- class aiida.common.GraphTraversalRules#
Bases:
enum.Enum
Graph traversal rules when deleting or exporting nodes.
- DEFAULT = None#
- DELETE = None#
- EXPORT = None#
- exception aiida.common.HashingError#
Bases:
aiida.common.exceptions.AiidaException
Raised when an attempt to hash an object fails via a known failure mode
Initialization
Initialize self. See help(type(self)) for accurate signature.
- exception aiida.common.IncompatibleStorageSchema#
Bases:
aiida.common.exceptions.IncompatibleDatabaseSchema
Raised when the storage schema is incompatible with that of the code.
Initialization
Initialize self. See help(type(self)) for accurate signature.
- exception aiida.common.InputValidationError#
Bases:
aiida.common.exceptions.ValidationError
The input data for a calculation did not validate (e.g., missing required input data, wrong data, …)
Initialization
Initialize self. See help(type(self)) for accurate signature.
- exception aiida.common.IntegrityError#
Bases:
aiida.common.exceptions.AiidaException
Raised when there is an underlying data integrity error. This can be database related or a general data integrity error. This can happen if, e.g., a foreign key check fails. See PEP 249 for details.
Initialization
Initialize self. See help(type(self)) for accurate signature.
- exception aiida.common.InternalError#
Bases:
aiida.common.exceptions.AiidaException
Error raised when there is an internal error of AiiDA.
Initialization
Initialize self. See help(type(self)) for accurate signature.
- exception aiida.common.InvalidEntryPointTypeError#
Bases:
aiida.common.exceptions.EntryPointError
Raised when a loaded entry point has a type that is not supported by the corresponding entry point group.
Initialization
Initialize self. See help(type(self)) for accurate signature.
- exception aiida.common.InvalidOperation#
Bases:
aiida.common.exceptions.AiidaException
The allowed operation is not valid (e.g., when trying to add a non-internal attribute before saving the entry), or deleting an entry that is protected (e.g., because it is referenced by foreign keys)
Initialization
Initialize self. See help(type(self)) for accurate signature.
- exception aiida.common.LicensingException#
Bases:
aiida.common.exceptions.AiidaException
Raised when requirements for data licensing are not met.
Initialization
Initialize self. See help(type(self)) for accurate signature.
- class aiida.common.LinkType#
Bases:
enum.Enum
A simple enum of allowed link types.
- CREATE = 'create'#
- RETURN = 'return'#
- INPUT_CALC = 'input_calc'#
- INPUT_WORK = 'input_work'#
- CALL_CALC = 'call_calc'#
- CALL_WORK = 'call_work'#
- exception aiida.common.LoadingEntryPointError#
Bases:
aiida.common.exceptions.EntryPointError
Raised when the resource corresponding to requested entry point cannot be imported.
Initialization
Initialize self. See help(type(self)) for accurate signature.
- exception aiida.common.LockedProfileError#
Bases:
aiida.common.exceptions.AiidaException
Raised if attempting to access a locked profile
Initialization
Initialize self. See help(type(self)) for accurate signature.
- exception aiida.common.LockingProfileError#
Bases:
aiida.common.exceptions.AiidaException
Raised if the profile can`t be locked
Initialization
Initialize self. See help(type(self)) for accurate signature.
- exception aiida.common.MissingConfigurationError#
Bases:
aiida.common.exceptions.ConfigurationError
Configuration error raised when the configuration file is missing.
Initialization
Initialize self. See help(type(self)) for accurate signature.
- exception aiida.common.MissingEntryPointError#
Bases:
aiida.common.exceptions.EntryPointError
Raised when the requested entry point is not registered with the entry point manager.
Initialization
Initialize self. See help(type(self)) for accurate signature.
- exception aiida.common.ModificationNotAllowed#
Bases:
aiida.common.exceptions.AiidaException
Raised when the user tries to modify a field, object, property, … that should not be modified.
Initialization
Initialize self. See help(type(self)) for accurate signature.
- exception aiida.common.MultipleEntryPointError#
Bases:
aiida.common.exceptions.EntryPointError
Raised when the requested entry point cannot uniquely be resolved by the entry point manager.
Initialization
Initialize self. See help(type(self)) for accurate signature.
- exception aiida.common.MultipleObjectsError#
Bases:
aiida.common.exceptions.AiidaException
Raised when more than one entity is found in the DB, but only one was expected.
Initialization
Initialize self. See help(type(self)) for accurate signature.
- exception aiida.common.NotExistent#
Bases:
aiida.common.exceptions.AiidaException
Raised when the required entity does not exist.
Initialization
Initialize self. See help(type(self)) for accurate signature.
- exception aiida.common.NotExistentAttributeError#
Bases:
AttributeError
,aiida.common.exceptions.NotExistent
Raised when the required entity does not exist, when fetched as an attribute.
Initialization
Initialize self. See help(type(self)) for accurate signature.
- exception aiida.common.NotExistentKeyError#
Bases:
KeyError
,aiida.common.exceptions.NotExistent
Raised when the required entity does not exist, when fetched as a dictionary key.
Initialization
Initialize self. See help(type(self)) for accurate signature.
- exception aiida.common.OutputParsingError#
Bases:
aiida.common.exceptions.ParsingError
Can be raised by a Parser when it fails to parse the output generated by a CalcJob process.
Initialization
Initialize self. See help(type(self)) for accurate signature.
- exception aiida.common.ParsingError#
Bases:
aiida.common.exceptions.AiidaException
Generic error raised when there is a parsing error
Initialization
Initialize self. See help(type(self)) for accurate signature.
- exception aiida.common.PluginInternalError#
Bases:
aiida.common.exceptions.InternalError
Error raised when there is an internal error which is due to a plugin and not to the AiiDA infrastructure.
Initialization
Initialize self. See help(type(self)) for accurate signature.
- exception aiida.common.ProfileConfigurationError#
Bases:
aiida.common.exceptions.ConfigurationError
Configuration error raised when a wrong/inexistent profile is requested.
Initialization
Initialize self. See help(type(self)) for accurate signature.
- class aiida.common.ProgressReporterAbstract(*, total: int, desc: Optional[str] = None, **kwargs: Any)#
An abstract class for incrementing a progress reporter.
This class provides the base interface for any ProgressReporter class.
Example Usage:
with ProgressReporter(total=10, desc="A process:") as progress: for i in range(10): progress.set_description_str(f"A process: {i}") progress.update()
Initialization
Initialise the progress reporting contextmanager.
- Parameters:
total – The number of expected iterations.
desc – A description of the process
- __enter__() aiida.common.progress_reporter.ProgressReporterAbstract #
Enter the contextmanager.
- __exit__(exctype: Optional[Type[BaseException]], excinst: Optional[BaseException], exctb: Optional[types.TracebackType])#
Exit the contextmanager.
- set_description_str(text: Optional[str] = None, refresh: bool = True)#
Set the text shown by the progress reporter.
- Parameters:
text – The text to show
refresh – Force refresh of the progress reporter
- exception aiida.common.RemoteOperationError#
Bases:
aiida.common.exceptions.AiidaException
Raised when an error in a remote operation occurs, as in a failed kill() of a scheduler job.
Initialization
Initialize self. See help(type(self)) for accurate signature.
- class aiida.common.StashMode#
Bases:
enum.Enum
Mode to use when stashing files from the working directory of a completed calculation job for safekeeping.
- COPY = 'copy'#
- exception aiida.common.StorageMigrationError#
Bases:
aiida.common.exceptions.DatabaseMigrationError
Raised if a critical error is encountered during a storage migration.
Initialization
Initialize self. See help(type(self)) for accurate signature.
- exception aiida.common.StoringNotAllowed#
Bases:
aiida.common.exceptions.AiidaException
Raised when the user tries to store an unstorable node (e.g. a base Node class)
Initialization
Initialize self. See help(type(self)) for accurate signature.
- aiida.common.TQDM_BAR_FORMAT = '{desc:40.40}{percentage:6.1f}%|{bar}| {n_fmt}/{total_fmt}'#
- exception aiida.common.TestsNotAllowedError#
Bases:
aiida.common.exceptions.AiidaException
Raised when tests are required to be run/loaded, but we are not in a testing environment.
This is to prevent data loss.
Initialization
Initialize self. See help(type(self)) for accurate signature.
- exception aiida.common.TransportTaskException#
Bases:
aiida.common.exceptions.AiidaException
Raised when a TransportTask, an task to be completed by the engine that requires transport, fails
Initialization
Initialize self. See help(type(self)) for accurate signature.
- exception aiida.common.UniquenessError#
Bases:
aiida.common.exceptions.AiidaException
Raised when the user tries to violate a uniqueness constraint (on the DB, for instance).
Initialization
Initialize self. See help(type(self)) for accurate signature.
- exception aiida.common.UnsupportedSpeciesError#
Bases:
ValueError
Raised when StructureData operations are fed species that are not supported by AiiDA such as Deuterium
Initialization
Initialize self. See help(type(self)) for accurate signature.
- exception aiida.common.ValidationError#
Bases:
aiida.common.exceptions.AiidaException
Error raised when there is an error during the validation phase of a property.
Initialization
Initialize self. See help(type(self)) for accurate signature.
- aiida.common.create_callback(progress_reporter: aiida.common.progress_reporter.ProgressReporterAbstract) Callable[[str, Any], None] #
Create a callback function to update the progress reporter.
- Returns:
a callback to report on the process,
callback(action, value)
, with the following callback signatures:callback('init', {'total': <int>, 'description': <str>})
,to reset the progress with a new total iterations and description
callback('update', <int>)
,to update the progress by a certain number of iterations
- aiida.common.get_progress_reporter() Type[aiida.common.progress_reporter.ProgressReporterAbstract] #
Return the progress reporter
Example Usage:
with get_progress_reporter()(total=10, desc="A process:") as progress: for i in range(10): progress.set_description_str(f"A process: {i}") progress.update()
- aiida.common.override_log_level(level=logging.CRITICAL)#
Temporarily adjust the log-level of logger.
- aiida.common.set_progress_bar_tqdm(bar_format: Optional[str] = TQDM_BAR_FORMAT, leave: Optional[bool] = False, **kwargs: Any)#
Set a tqdm implementation of the progress reporter interface.
See
set_progress_reporter()
for details.- Parameters:
bar_format – Specify a custom bar string format.
leave – If True, keeps all traces of the progressbar upon termination of iteration. If None, will leave only if position is 0.
kwargs – pass to the tqdm init
- aiida.common.set_progress_reporter(reporter: Optional[Type[aiida.common.progress_reporter.ProgressReporterAbstract]] = None, **kwargs: Any)#
Set the progress reporter implementation
- Parameters:
reporter – A progress reporter for a process. If None, reset to
ProgressReporterNull
.kwargs – If present, set a partial function with these kwargs
The reporter should be a context manager that implements the
ProgressReporterAbstract()
interface.Example Usage:
set_progress_reporter(ProgressReporterNull) with get_progress_reporter()(total=10, desc="A process:") as progress: for i in range(10): progress.set_description_str(f"A process: {i}") progress.update()
- aiida.common.validate_link_label(link_label)#
Validate the given link label.
Valid link labels adhere to the following restrictions:
Has to be a valid python identifier
Can only contain alphanumeric characters and underscores
Can not start or end with an underscore
- Raises:
TypeError – if the link label is not a string type
ValueError – if the link label is invalid