The following instructions are how to update from
Each version increase may come with its own necessary migrations and you should only ever update the version by one at a time.
To find the instructions for older versions, refer to the table below.
Finish all running calculations. After migrating your database, you will not be able to resume unfinished calculations. Data of finished calculations will of course be automatically migrated.
Finish all running legacy workflows. The legacy workflows are completely deprecated and all data will be removed from your database, so make sure to create a backup (see point 5).
Enter the python environment where AiiDA is installed
Stop the daemon using
verdi daemon stop
Create a backup of your database and repository
Once you have migrated your database, you can no longer go back to an older version of
aiida-core, unless you restore your database and repository from a backup of course.
In addition, the data migration can take quite some time depending on the size of your database, so please be patient.
Big databases of multiple millions of nodes can take up to a few hours to migrate.
If you have installed AiiDA through
pip install --upgrade aiida-core
If you have installed from the git repository using
pip install -e ., first delete all the
find . -name "*.pyc" -delete) before updating your branch.
Finally, after having upgraded the installation, migrate your database with
verdi -p <profile_name> database migrate
After the database migration finishes, you will be able to continue working with your existing data. However, backwards incompatible changes were introduced in the python API, so you probably will have to update your code and installed plugins.
Backwards incompatible changes¶
The following list covers the most important backward incompatible changes between
aiida.workhas been renamed to
aiida.engineand reorganized significantly [#2524]
aiida.schedulerhas been renamed to
aiida.transporthas been renamed to
aiida.utilshas been removed and its contents have been placed in other places where appropriate [#2357]
Requirements were moved from
In order to define a clearer interface for users to the AiiDA entities, and allow (in the future) to swap between different profiles, the underlying hierarchy of nodes and links has been reworked (and a new paradigm has been implemented, with a “frontend” class that all users will interact with, and a “backend” class that users should never use directly, that implements the interaction to the database with a common interface, independent of the underlying ORM). The reorganisation of nodes and linktypes is mostly invisible to the user, but existing import statements will need to be updated.
Renamed the node classes for the various process types
Codea real sub class of
Implement new link types [#2220]
CalculationNode -> Data
WorkflowNode -> Data
Data -> CalculationNode
Data -> WorkflowNode
WorkflowNode -> CalculationNode
WorkflowNode -> WorkflowNode
Moved the plugin factories to
Methods that operated on the repository of a
Nodeinstance have been moved to a
Repositoryutility that is exposed through the
Errordata sub class and its entry point [#2529]
FrozenDictdata sub class and its entry point [#2532]
ParameterDatadata sub class to
Change group type strings [#2329]
custom ones to
Group.group_querymethods have been removed [#2329]
Groupdatabase model to
Groupdatabase model to
Group.get_or_createhas been removed, use the collection method
Group.get_from_stringhas been removed, use the class method
typehas been renamed to
get_outputs_dicthave been removed and replace by
Removed the link manager methods
Node.outand the functionality has partially been replaced by: [#2569]
The link manager properties
Functionality to traverse the graph with tab completion when there is no uniqueness on the label is no longer supported and
get_outgoingshould be used instead.
ProcessNodecan no longer be stored but only their sub classes [#2301]
Kind.is_alloy()has been changed to a property
Kind.has_vacancies()has been changed to a property
StructureData.is_alloy()has been changed to a property
StructureData.has_vacancies()has been changed to a property
CifData._get_aiida_structure()has been renamed to
CifDatadefault library used in
get_structureto convert to
StructureDatahas been changed from
remove_pathhave been removed in favor of
ArrayData.iterarrays()has been renamed to
TrajectoryData._get_cif()has been renamed to
TrajectoryData._get_aiida_structure()has been renamed to
StructureData._get_cif()has been renamed to
Code.full_text_info()has been renamed to
Code.is_hidden()has been renamed and changed to
RemoteData.is_empty()has been changed to a property
TrajectoryData.set_trajectory()method are made optional which has implications on the ordering of the arguments passed to this method. [#2422]
The list of atomic symbols for
TrajectoryDatais no longer stored as array data but is now accessible through the
Removed deprecated methods
Removed deprecated method KpoinstData.bravais_lattice [#3114]
Removed deprecated method KpoinstData._set_bravais_lattice [#3114]
Removed deprecated method KpoinstData._get_or_create_bravais_lattice [#3114]
Removed deprecated method KpoinstData.set_kpoints_path [#3114]
Removed deprecated method KpoinstData._find_bravais_info [#3114]
Removed deprecated method KpoinstData.find_bravais_lattice [#3114]
Removed deprecated method KpoinstData.get_special_kpoints [#3114]
optional_inlinedecorators have been replaced by
In the new engine, it is not possible to launch calculation jobs by first creating an instance of the Calculation and then calling the
calculation.use_xxx methods, as it was common in early versions of AiiDA.
Instead, you need to pass the correct Calculation class to the
submit function, passing the nodes to link as input as
For the past few versions, we have kept back-compatibility by supporting both ways of submitting. In version 1.0 we have decided to keep only one single way of submitting calculations for simplicity.
JobCalculationhas been replaced by
CalcJobprocess class [#2389]
Custom methods on the node class should now be implemented through a
set_methods of the
JobCalculationhave been replaced with generic
get_methods of the
JobCalculationhave been replaced with generic
New calculation job states have been introduced set as an attribute, only to be used for querying [#2389]
DbCalcStatetable that recorded the old job state of
JobCalculationshas been removed [#2389]
parse_from_retrievedhas been renamed to
parse. In addition the arguments and return signatures have changed, for details see the PR [#2397]
The free function
WorkChainshould be replaced with
The future returned by
submitno longer has the
pidattribute but rather
workfunctiondecorator can only be used for functions that return one of the inputs they receive, for all other use the
get_inputs_template classmethod has been replaced by
get_builder. See the section on the process builder in the documentation on how to use it.
input_grouphas been deprecated and been replaced by namespaces. See the section on ports in the documentation on how to use them.
The use of a
.(period) in output keys is not supported in
Process.outbecause that is now reserved to indicate namespaces.
verdi command line interface has been migrated over to a new system (called
click), making the interface of all
verdi commands consistent: now the way to specify a node (via a PK, a UUID or a LABEL) is the same for all commands, and command-line options that have the same meaning use the same flags in all commands.
To make this possible, the interface of various verdi commands has been changed to ensure consistency.
Also the output of most commands has been homogenised (e.g. to print errors or warnings always in the same style).
Moreover, some of the commands have been renamed to be consistent with the new names of the classes in AiiDA.
verdi data pluginsin favor of
verdi plugin list[#3114]
verdi code renamein favor of
verdi code relabel[#3114]
verdi code updatein favor of
verdi code duplicate[#3114]
verdi workin favor of
verdi calculationin favor of
Deprecated the commands to set and get config options
verdi devel *property*in favor of
verdi code showno longer shows number of calculations by default to improve performance, with
--verboseflag to restore old behavior [#1428]
The tab-completion activation for
verdihas changed, simply replace the
eval "$(verdi completioncommand)"line in your activation script with
eval "$(_VERDI_COMPLETE-source verdi)"
JOB_STATES, conforming to python conventions [#1799]
New export archive format introduced
v0.6. Older archives will automatically be converted when using
verdi import, or alternatively can be manually exported using
verdi export migrate
To determine the current version of your installation use
If the command does not exist, you have an older version of AiiDA, in which case you need to get it from the
Update instructions for older versions can be found in the documentation of the corresponding version: