-
Notifications
You must be signed in to change notification settings - Fork 38
Home
In this page the aiida plugin developers can find all the guidelines to join the project. Also, we collect here the summary of the decisions we took during meetings and exchanges in the issues section.
The aim of the project consists in achieving a common interface for different codes to compute in an automated way common materials properties.
For a specific task (for instance the relaxation of a structure), we agree on the API of a "builder factory" (named for instance following the pattern <Code><Task>InputGenerator), i.e. a python class that is able to return an AiiDA builder containing the required inputs to submit an AiiDA process (typically a WorkChain) computing the property. With API we mean the name and signature of the methods that this "builder factory" has and its expected inputs. In other words, a line of the kind:
input_generator = <Code><Task>InputGenerator() builder = inputs_generator.get_builder(par1, par2, ...)
should return a builder for an AiiDA process able to complete the task <Task> and the inputs of get_builder (par1, par2, ...) must be the same for each <Code> (given a <Task>).
In addition to a method get_builder, the class <Code><Task>InputGenerator has additional methods, for instance to return information about the possible protocols available for the specific task. Rationale: one of the goals of this <Code><Task>InputGenerator classes is to be used to automatically generate GUIs. The GUI is specific to the property (e.g., one for structure relaxation, one for bands calculations, ...). However, given a task (relaxation, for instance), the GUI should be autogenerated for any <Code> implementation. Therefore, for instance, we define methods to get the list of valid protocols that the calculation accepts. The available protocols can differ between implementations, but the way to access the list must be the same for each code.
Finally, the AiiDA process to be run (whose builder is return by get_builder) should return standardized outputs among different codes, for a specific task. For instance, in the case of the relaxation of a structure, all should return a StructureData node, with an output return link labeled relaxed_structure, with the final structure obtained after a relaxation.
The first working example of a common interface among different plugins for the submission of a task is the relaxation of a structure.
We agreed that the relaxation should produce the following mandatory outputs:
- relaxed_structure (valid_type=StructureData). The structure obtained after the relaxation, all cell dimensions and atomic positions are in Ångstrom.
- forces (valid_type=ArrayData). The final forces on all atoms in eV/Å.
Some supported optional outputs are:
- stress (valid_type=ArrayData). The final stress tensor in eV/Å^3.
- trajectory (valid_type=TrajectoryData). The TrajectoryData is a flexible aiida data type that allows to include other quantities on top of the coordinates. We agreed that, for the moment, the trajectory output should contain the coordinates, the cell and, optionally, the total energy for each step. All cell dimensions and atomic positions are in Ångstrom. (Issue #2)
- total_energy (valid_type=Float). Total energy in eV. The total energy is not necessarily defined in a code-independent way (or with a properly defined zero). At least we should make sure that the quantity returned is such that its partial derivative with respect to the change of the coordinate i of atom j is the i-th coordinate of the force on the atom j. Also, it is important to warn the users that the energies obtained running calculations at different volumes with protocols, might not be comparable. For instance, the number of k-points might be chosen by the protocol to have a constant density of k-points in reciprocal space. Therefore, the k-point grid might depend on the volume, resulting in equations of states with discontinuities if (as it is always the case) we are not perfectly converged. (Issue #14)
Therefore, each plugin developer needs to implement a WorkChain that returns the above outputs with the correct link name (at least the mandatory outputs, optionally the others). To facilitate the task, a CommonRelaxWorkChain metaclass has been produced. It sets the outputs and it requires to define the attribute _process_class. This attribute should contain the AiiDA process that is designed to perform the relaxation. Each developer is invited to create a <Code>RelaxWorkChain, subclass of CommonRelaxWorkChain, where simply the _process_class and a method convert_outputs needs to be defined. The metaclass will take care to expose the inputs of the assigned _process_class, run it and check if it finished successfully. In convert_outputs the developer should convert the outputs produced by the selected _process_class into the agreed outputs.
In addition to the <Code>RelaxWorkChain, each plugin developer must implement a class <Code>RelaxInputGenerator with the main purpose to create a method get_builder that returns a builder of <Code>RelaxWorkChain. Through get_builder we create the common interface among plugins, therefore the signature of this method must be the same for each <Code>RelaxInputGenerator. In details the accepted inputs of get_builder are the following:
-
structure. The structure to be relaxed, an AiiDA StructureData
-
calc_engines. A python dictionary containing the code and computational resources to use for completing the task. Some implementations might require more then one step (eventually code) to complete the relaxation and the therefore developer should define an attribute _calc_types in their class that explains the schema to be passed to calc_engines.
-
protocol. With the name protocol we mean a string that summarizes a certain set of inputs of the AiiDA process to be submitted and intends to offer a desired balance of accuracy and efficiency. We agreed in Issue #1 that each plugin should support, at least, these three protocols:
- “fast” = return in a quick way a result that may not be reliable
- “moderate” = reliable result (could be published), but no emphasis on convergence
- “precise” = an high level of accuracy
Each plugin must implement these three protocols, but the specifications remain fully plugin-dependent. The specifications must be well documented. And we have a specific section here for this purpose.
-
relaxation_type. RelaxType, HERE NOT SURE WHAT WE WANT. At the moment we accept only attributes of RelaxType.
-
threshold_forces: target threshold for the forces in eV/Å. Optional. If not specified, the developers might think to add it to the protocol specifications, or at least write in the documentation what is the default.
-
threshold_stress: target threshold for the stress in eV/Å^3. Optional. If not specified, the developers might think to add it to the protocol specifications, or at least write in the documentation what is the default.
The get_builder accepts also `**kwargs for plugin specific inputs. We allow plugin-specific inputs to get_builder(), BUT they must be “not-required” in an environment where all the necessary data are installed in the database with the correct recipe. This means that an aiida user running in his local environment can pass, for instance, its own custom name of pseudo_family, however, in a future platform where everything will be available, the get_builder should work perfectly without any pseudo_family passed to it. We also identified the QuantumMobile as the environment where we want to run, at least initially, the common workflows. Therefore each plugin developer should start to think about the steps its interface requires in order to set up in the QuantumMobile all the necessary data to run the relaxation workchain without the "not-required" inputs. This set of instructions will become an ansible set for QuantumMobile. With appropriate adjustments (attention to idempotency, check on the already present data, etc..) this set of instructions can become, in the future, the core of a setup_aiida_profile() function (eventually a verdi command) that a user can run in its environment to set all the necessary data with the correct recipe and forget about "not-required" inputs.
To help developers, we provide a metaclass RelaxInputsGenerator that we expect to be parent of <Code>RelaxInputGenerator. It requires attributes ... It automatically generate the methods to explore these attributes, these is key for the GUI.
Collect the specifications.
- moderate Pseudopotential ONCVPSPv0.4 (norm-conserving) of Pseudo Dojo in psml format, scalar relativistic, PBE and with standard accuracy. See Pseudo Dojo website for more info (link). Basis set apply globally, with size DZ and energy-shift of 100 meV. Meshcutoff is 100 Ry, electronic temp 25 meV, and a kpoint mesh with distance 0.2 are implemented. Concerning the trashold for convergence, we implement 1.e-3 tolerance for the density matrix, 0.04 ev/ang for forces and 1 GPa for stress. This choice of parameters have been tested on crystal elements of the Delta test (link) and ...
- precise Pseudopotential ONCVPSPv0.4 (norm-conserving) of Pseudo Dojo in psml format, scalar relativistic, PBE and with stringent accuracy. See Pseudo Dojo website for more info (link). Basis set apply globally, with size DZP and energy-shift of 100 meV. Meshcutoff is 500 Ry, electronic temp 25 meV, and a kpoint mesh with distance 0.062 are implemented. Concerning the trashold for convergence, we implement 1.e-4 tolerance for the density matrix, 0.03 ev/ang for forces and 0.005 ev/ang^3 for stress. This choice op parameters have been tested on crystal elements of the Delta test (link) and ...