1. Relaxation of a structure

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:

• forces (valid_type=ArrayData). The final forces on all atoms in eV/Å.
• 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. Thanks to the input argument "previous_workchain" we also sorted the problem of not having comparable energies at different volumes. In fact, 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, for instance, in equations of states with discontinuities if, as it is always the case, we are not perfectly converged - Issue #14). The "previous_workchain" input triggers some logic to overcome the problem, as explained in the corresponding section of this page. It is important to warn the users that, when comparison of energies is required, the input "previous_workchain" must be used.
• relaxed_structure (valid_type=StructureData). The structure obtained after the relaxation, all cell dimensions and atomic positions are in Ångstrom. This output is mandatory for each case except if the relaxation is selected to be None. We agreed in fact to support also single point calculations through this common interface.

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_magnetization (valid_type=Float). Total magnetization in Bohr magnetons.

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>CommonRelaxWorkChain, 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>CommonRelaxWorkChain, 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>CommonRelaxWorkChain. 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

• 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 developer should define an attribute _calc_types in their class that explains the schema to be passed to engines. A typical engines (accepted as input of get_builder) would be:

  engines ={
      “step1”: {“code” : codespec1, “options” : {}}, 
      “step2”: {“code” : codespec2, “options” : {}}
  }

  The codespec# should be a label@computer specification (therefore the get_builder should be implemented to understand it). For information about the corresponding _calc_types see below (where attributes of <Code>RelaxInputGenerator are explained).

• 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. We have a specific section for this purpose here.

• relaxation_type. One of the relax types defined in RelaxType

• threshold_forces. A python float indicating the 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 of their code.

• threshold_stress. A python float indicating the 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 of their code.

• previous_workchain. A <Code>RelaxWorkChain node. Optional. It is expected that each developer implements the logic in get_builder to return inputs that ensure to run a <Code>RelaxWorkChain that will results in energies comparable to “previous_workchain”. This is necessary to create, for instance, meaningful equations of state. The presence of this optional input, alone, trigger the process.

• electronic_type. An optional input to signal whether to perform the simulation for a metallic or an insulating system. It accepts only instances of ElectronicType. On top of insulator/metallic option we support AUTOMATIC which mean that the code itself is able to automatically chose the right option. Since these last feature is not easy to implement and it is not supported by many plugins, the default is METAL, meaning the material to simulate is assumed to be metallic.

• spin_type. An optional input to specify the spin degree of freedom for the calculation. It accepts only instances of SpinType. The default is to run calculation with no spin.

• magnetization_per_site. An input devoted to the initial magnetization specifications. It accepts a list where each element refers to a site in the structure. We agreed, for the moment, that the quantity must be passed as spin polarization in units of electrons, meaning the difference between spin up and spin down electrons in the site. This choice is suitable to support only collinear spin. Support for non-collinear situations will be added in the future. The default for this input is None. In case of calculations with spin, the None option signals the situation where the implementation automatically decides a default initial magnetization. This automatic choice is code specific!

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. In the first paper we detailed a list of instructions to create the prototype environment where to run the common workflows in the Quantum Mobile virtual machine. 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. All this was decided after discussion in Issue #4

To help developers, we provide a metaclass RelaxInputsGenerator that we expect to be parent of <Code>RelaxInputGenerator. In addition to the implementation of get_builder, it requires the definition of the following attributes:

• _calc_types, describing the schema of the calc_engines input. An example:

  _calc_types = {
      “step1”: {“code_plugin” : "code1.plugin", "description": "Bla bla"}
      “step2”: {“code_plugin” : "code2.plugin", "description": "Bla bla"}
  }

  Each step must allow one and only one code. The code_plugin entry for each step is mandatory in _calc_types (in fact CLI implementation will look at it in order to set the code for the calculation) and code#.plugin should be the entry point of the calculation plugin associated to the code.

• _relax_types, describing the supported relaxation_types the code can perform. An example:

  _relax_types = {
    RelaxType.ATOMS: 'Relax only the atomic positions while keeping the cell fixed.',
    RelaxType.ATOMS_CELL: 'Relax both atomic positions and the cell.'
   }
  

• _protocols, describing the available protocols. An example:

  _protocols = {'fast': {'description': ''}, 'moderate': {'description': ''}, 'precise': 'description': ''}}
  

• _default_protocol, the name of the default protocol, must be one of the available protocols

• _electronic_types, describing the supported electronic_types the code can perform.

• _spin_types, describing the supported spin_types the code can perform.

Once these attributes are specified, the metaclass will automatically take care of the methods to explore these attributes. This is key for the future creation of a GUI.