Base workflow¶
Description¶
The SIESTA program is able to perform, in a single run, the computation of the electronic structure, the optional relaxation of the input structure, and a final analysis step in which a variety of magnitudes can be computed: band structures, projected densities of states, etc. The operations to be carried out are specified in a very flexible input format. Accordingly, the SiestaBaseWorkChain has been designed to be able to run the most general SIESTA calculation, with support for most of the available options (limited only by corresponding support in the parser plugin). The option specifications of the SiestaBaseWorkChain follow the conventions already presented in the Siesta plugin. Therefore, for instance, the addition of the input keyword bandskpoints triggers the calculation of the band structure of a system, while it is sufficient to add the SIESTA MD keywords to the parameters input in order to perforem the relaxation of a structure. In contarst to the SiestaCalculation plugin, however, the workchain is able to automatically restart a calculation in case of failure (lack of electronic-structure or geometry relaxation convergence, termination due to walltime restrictions, etc). Therefore, the SiestaBaseWorkChain is the suggested tool to run Siesta calculations in the AiiDA framework. In fact, it retains the same level of flexibility of the most general Siesta calculation, but it adds robusness thanks to its ability to automatically respond to erros. Examples on the use of the SiestaBaseWorkChain are presented in the folder /aiida_siesta/examples/workflows.
Supported Siesta versions¶
At least 4.0.1 of the 4.0 series, 4.1-b3 of the 4.1 series and the MaX-1.0 release, which can be found in the development platform (https://gitlab.com/siesta-project/siesta). For more up to date info on compatibility, please check the wiki.
Inputs¶
Most inputs of the WorkChain are mirroring the siesta plugin inputs. Therefore, more
detailed information on them can be found here.
The only difference is regarding the way the computational resources are passed.
The siesta plugin make use of metadada.options
for this task, here, instead, we have
a dedicated input node. This node is the first point in the following list, describing
all the inputs of the WorkChain.
options, class
Dict
, MandatoryExecution options. In this dictionary the computational resources and scheduler specifications (queue, account, etc ..) must be specified. An example is:
options = Dict( dict={ 'max_wallclock_seconds': 360, 'withmpi': True, 'account': 'tcphy113c', 'queue_name': 'DevQ', 'resources': {'num_machines': 1,'num_mpiprocs_per_machine': 2}, } )
The resources and max_wallclock_seconds are required by AiiDA, the rest of the options depend on the scheduler of the machine one is submitting to.
code, class
Code
, MandatoryA database object representing a Siesta executable. See the plugin documentation for more details.
structure, class
StructureData
, MandatoryA structure. See the plugin documentation for more details.
parameters, class
Dict
, MandatoryA dictionary with scalar fdf variables and blocks, which are the basic elements of any Siesta input file. A given Siesta fdf file can be cast almost directly into this dictionary form, except that some items (e.g. for structure data) are blocked. Any units are specified for now as part of the value string. Blocks are entered by using an appropriate key and Python’s multiline string constructor. For example:
{ "mesh-cutoff": "200 Ry", "dm-tolerance": "0.0001", "%block example-block": """ first line second line %endblock example-block""", ... }
Note that Siesta fdf keywords allow ‘.’, ‘-‘, or nothing as internal separators. AiiDA does not allow the use of ‘.’ in nodes to be inserted in the database, so it should not be used in the input script (or removed before assigning the dictionary to the Dict instance). For legibility, a single dash (‘-‘) is suggested, as in the examples above. See the plugin documentation for more details on the blocked items.
pseudos, input namespace of class
PsfData
OR classPsmlData
, OptionalA dictionary of PsfData <aiida_siesta.data.psf.PsfData> or PsmlData <aiida_siesta.data.psml.PsmlData> objects representing the pseudopotentials for the calculation. See the plugin documentation for more details. In contrast to the case of the siesta plugin, the pseudos input is not mandatory. The SiestaBaseWorkChain supports, in fact, the direct use of pseudo_family (see below). If pseudos is not in input, a pseudo_family specification must be used.
pseudo_family, class
Str
, OptionalString representing the name of a pseudopotential family stored in the database. Pseudofamilies can be uploaded in the database via the
verdi data psf uploadfamily
orverdi data psml uploadfamily
CLI interface.
basis, class
Dict
, OptionalA dictionary specifically intended for basis set information. It follows the same structure as the parameters element, including the allowed use of fdf-block items. This raw interface allows a direct translation of the myriad basis-set options supported by the Siesta program. If not specified, a calculation with only the gamma point is performed. See the plugin documentation for more details.
kpoints, class
KpointsData
, OptionalReciprocal space points for the full sampling of the BZ during the self-consistent-field iteration. It must be given in mesh form. There is no support yet for Siesta’s kgrid-cutoff keyword. See the plugin documentation for more details. If this node is not present, only the Gamma point is used for sampling.
bandskpoints, class
KpointsData
, OptionalReciprocal space points for the calculation of bands. They can be given as a simple list of k-points, as segments with start and end point and number of points, or as a complete automatic path, using the functionality of modern versions of the class. See the plugin documentation for more details. If this node is not present, no band structure is computed.
settings, class
Dict
, OptionalAn optional dictionary that activates non-default operations. For a list of possible values to pass, see the section on advanced features.
clean_workdir, class
Bool
, OptionalIf true, work directories of all called calculations will be cleaned out. Default is false.
max_iterations, class
Int
, OptionalThe maximum number of iterations allowed in the restart cycle for calculations. The SiestaBaseWorkChain tries to deal with some common siesta errors (see here <basewc-error>) and restart the calculation with appropriate modifications. The integer max_iterations is the maximum number of times the restart is performed no matter what error is recorded. The input is optional, if not specified, the default Int(5) is used.
parent_calc_folder, class
RemoteData
, OptionalOptional port used to activate the restart features, as explained in the plugin documentation.
Relaxation and bands¶
As already mentioned in the introduction, in addition to simple scf calculations, the SiestaBaseWorkChain can be used to perform the relaxation of a structure and the electronic bands calculations. For the electronic bands, however, we suggest the use of the BandgapWorkChain distributed in this package, because it adds the feature to automatically calculate the band gap. Concerning the relaxation of a structure, the SiestaBaseWorkChain simply exploits the internal relaxation implemented in Siesta in order to complete the task. The full set of a Siesta relaxation options can be accessed just adding the corresponding keyword and value in the parameters input dictionary. The only additional feature that the SiestaBaseWorkChain adds is that it requires to reach the target forces and stress to consider completed the task. If this does not happen in a single Siesta run, the workchain restarts automatically the relaxation. The maximum number of restarts is specified with the keyword max_iterations, as explained in the previous subsection.
Submitting the WorkChain¶
WorkChains are submitted in AiiDA exacly like any other calculation. Therefore:
from aiida_siesta.workflows.base import SiestaBaseWorkChain
from aiida.engine import
builder = SiestaBaseWorkChain.get_builder()
builder.options = options
... All the inputs here ...
submit(builder) #or run
There is no need to set the computational resources with the metadata as they are already
defined in the input options, however builder.metadata.label
and builder.metadata.description
could be used to label and describe the WorkChain.
Again, the use of the builder
is not mandatory, the inputs can be passed as arguments of
sumbit
/run
as explained in the siesta plugin section.
Outputs¶
The outputs of the SiestaBaseWorkChain mirror exactly the one of the siesta plugin. Therefore all the information can be obtained in the corresponding section. We list here the outputs.
output_parameters
Dict
A dictionary with metadata and scalar result values from the last calculation executed.
output_structure
StructureData
Present only if the workchain is modifying the geometry of the system.
bands,
BandsData
Present only if a band calculation is requested (signaled by the presence of a bandskpoints input node of class KpointsData) Contains an array with the list of electronic energies for every kpoint. For spin-polarized calculations, there is an extra dimension for spin.
forces_and_stress
ArrayData
Contains the final forces (eV/Angstrom) and stresses (GPa) in array form.
remote_folder,
RemoteData
The working remote folder for the last calculation executed. As the SiestaBaseWorkChain automatically restarts the calculation in case of common failures, the very last siesta calculation is considered the interesting one for a further manual restart. Therefore its folder is returned in this node.
Error handling¶
We list here the errors that are handled by the SiestaBaseWorkChain and the corresponding action taken. The error are actually detected by the siesta parser, in the WorkChain, the handling is performed.
SCF_NOT_CONV
When the convergence of the self-consistent cycle is not reached in
max-scf-iterations
or in the allocatedmax_walltime
, siesta raises the SCF_NOT_CONV error. The SiestaBaseWorkChain is able to detect this error and restart the calculation with no modifications on the input parameters.
GEOM_NOT_CONV
When the convergence of the geometry (during a relaxation) is not reached in the allocated
max_walltime
, siesta raises the GEOM_NOT_CONV error. The SiestaBaseWorkChain is able to detect this error and restart the calculation with no modifications on the input parameters.
SPLIT_NORM
The SiestaBaseWorkChain deals with problems connected to the basis set creation. If a “too small split-norm” error is detected, the WorkChains reacts in two ways. If a global split-norm was defined in input through
pao-split-norm
, its value is reset to the minimum acceptable. If no global split-norm was defined the optionpao-split-tail-norm = True
is set.
Two more errors are detected by the WorkChain, but not handled at the moment, only a specific error code is returned as output without attempting a restart.
BASIS_POLARIZ
If an error on the polarization of one orbital is detected, the error code 403 is returned. The solution to this problem is to set the “non-perturbative” polarization scheme for the element that presents an error, however this possibility is available only in recent versions of AiiDA, making inconvenient to treat automatically the resolution of this error.
ERROR_BANDS
If a calculation of the electronic bands is requested, but an error in the parsing of the bands file is detected, the error code 404 is returned. In this case, the WorkChain will anyway return all the other outputs because the checks on the bands file are always performed at the very end of the calculation.
The SiestaBaseWorkChain also inherits the error codes of the BaseRestartWorkChain of the aiida-core distribution. For instance, if an unexpected error is raised twice, the workchain finishes with exit code 402, if the maximum number of iterations is reached, error 401 is returned. More in the section BaseRestartWorkChain of the aiida-core package.
Protocol system¶
The protocol system is available for this WorkChain. The SiestaBaseWorkChain.inputs_generator()
makes available all the methods explained in the protocols documentation. For example:
from aiida_siesta.workflows.base import SiestaBaseWorkChain
inp_gen = SiestaBaseWorkChain.inputs_generator()
builder = inp_gen.get_filled_builder(structure, calc_engines, protocol)
#here user can modify builder befor submission.
submit(builder)
is sufficient to submit a SiestaBaseWorkChain on structure
following the specifications of
protocols
and computational resources collected in calc_engines
.
The structure of calc_engines
is the same as for the SiestaCalculation input generator
(again see protocols documentation).