VaspBaseWorkChain¶

The VaspBaseWorkChain plays an essntial role in making VaspCalculation robust and reproducible. It subclasses BaseRestartWorkChain from aiida-core to give us the power in inspecting, fixing, and restarting the VaspCalculation.

The VaspBaseWorkChain() allows us to benefit from error handlers to spot errors, and provide possible solutions to mitigate them, and restart the calculation after applying necessary modifications.

How error handlers work¶

VaspBaseWorkChain parses the standard output (_scheduler-stdout.txt) and standard error (_scheduler-stdout.txt) files of the calculation and reports any pre-defined error messages. These are assigned to self.ctx.stdout_errors and self.ctx.stderr_errors. Then, we have separate functions which check for the existence of different error messages in the self.ctx.stdout_errors and self.ctx.stderr_errors and take appropriate action to mitigate them, if they exist. For example, let’s look at the handle_lreal handler:

@process_handler(priority=300, enabled=True)
def handle_lreal(self, calculation):
    """Handle ``ERROR_LREAL_SMALL_SUPERCELL`` exit code"""
    if 'lreal' in self.ctx.stdout_errors:
        self.ctx.modifications.update({'LREAL': False})
        action = 'ERROR_LREAL_SMALL_SUPERCELL: LREAL is set to False'
        self.report_error_handled(calculation, action)
        return ProcessHandlerReport(False)

If the supercell size would be small, VASP suggests to set LREAL = False. The handle_lreal handler is notified about this by the existence of lreal key in self.ctx.stdout_errors and updates a self.ctx.modifications dictionary which is constructured at the beginning of inspection and is updated continusly. Once all checkes are done, the apply_modifications handler:

@process_handler(priority=1, enabled=True)
def apply_modifications(self, calculation):
    """Apply all requested modifications"""
    if self.ctx.modifications:
        self.ctx.inputs.parameters = update_incar(self.ctx.parameters, Dict(dict=self.ctx.modifications))
        self.ctx.modifications = {}
        self.report('Applied all modifications for {}<{}>'.format(calculation.process_label, calculation.pk))
        return ProcessHandlerReport(False)

will update the INCAR with these modifications and makes it ready for the subsequent run.

The process_handler decorator enables us to assign different priorities to the handles and also enable/disable them.

Current error handlers¶

The current error handlers are taken from the custodian package and translated to the AiiDA compatibale methods.

How to add new `error handler`¶

We may come up with new situations where a new error handler is needed. If the error message already is defined in the package and only the action needs to be modified, it should be strightforward by finding the relevant handler in VaspBaseWorkChain() and updating it. However, if a new error message is reported by VASP, it first needs to be added to parsers() with a unique key. Then, a new handler can be added to the VaspBaseWorkChain().

Detailed inputs, outputs, and outline¶

workchainaiida_catmat.workchains.VaspBaseWorkChain

Workchain to run a ``VASP`` calculation with automated error handling and restarts.

Inputs:

clean_workdir, Bool, optional – If True, work directories of all called calculation jobs will be cleaned at the end of execution.
handler_overrides, Dict, optional – Mapping where keys are process handler names and the values are a boolean, where True will enable the corresponding handler and False will disable it. This overrides the default value set by the enabled keyword of the process_handler decorator with which the method is decorated.
max_iterations, Int, optional – Maximum number of iterations the work chain will restart the process to finish successfully.
metadata, Namespace
Namespace Ports
- call_link_label, str, optional, non_db – The label to use for the CALL link if the process is called by another process.
- description, str, optional, non_db – Description to set on the process node.
- label, str, optional, non_db – Label to set on the process node.
- store_provenance, bool, optional, non_db – If set to False provenance will not be stored in the database.
vasp, Namespace
Namespace Ports
- charge_density, ChargedensityData, optional – The charge density. (CHGCAR)
- code, Code, required – The Code to use for this job.
- dynamics, Dict, optional – The VASP parameters related to ionic dynamics, e.g. flags to set the selective dynamics
- kpoints, KpointsData, required – The kpoints to use (KPOINTS).
- metadata, Namespace
  Namespace Ports
  - call_link_label, str, optional, non_db – The label to use for the CALL link if the process is called by another process.
  - computer, Computer, optional, non_db – When using a “local” code, set the computer on which the calculation should be run.
  - description, str, optional, non_db – Description to set on the process node.
  - dry_run, bool, optional, non_db – When set to True will prepare the calculation job for submission but not actually launch it.
  - label, str, optional, non_db – Label to set on the process node.
  - options, Namespace
    
    Namespace Ports
    
    account, str, optional, non_db – Set the account to use in for the queue on the remote computer
    
    additional_retrieve_list, (list, tuple), optional, non_db – List of relative file paths that should be retrieved in addition to what the plugin specifies.
    
    append_text, str, optional, non_db – Set the calculation-specific append text, which is going to be appended in the scheduler-job script, just after the code execution
    
    custom_scheduler_commands, str, optional, non_db – Set a (possibly multiline) string with the commands that the user wants to manually set for the scheduler. The difference of this option with respect to the prepend_text is the position in the scheduler submission file where such text is inserted: with this option, the string is inserted before any non-scheduler command
    
    environment_variables, dict, optional, non_db – Set a dictionary of custom environment variables for this calculation
    
    import_sys_environment, bool, optional, non_db – If set to true, the submission script will load the system environment variables
    
    input_filename, str, optional, non_db – Filename to which the input for the code that is to be run is written.
    
    max_memory_kb, int, optional, non_db – Set the maximum memory (in KiloBytes) to be asked to the scheduler
    
    max_wallclock_seconds, int, optional, non_db – Set the wallclock in seconds asked to the scheduler
    
    mpirun_extra_params, (list, tuple), optional, non_db – Set the extra params to pass to the mpirun (or equivalent) command after the one provided in computer.mpirun_command. Example: mpirun -np 8 extra_params[0] extra_params[1] … exec.x
    
    output_filename, str, optional, non_db – Filename to which the content of stdout of the code that is to be run is written.
    
    parser_name, None, optional, non_db
    
    prepend_text, str, optional, non_db – Set the calculation-specific prepend text, which is going to be prepended in the scheduler-job script, just before the code execution
    
    priority, str, optional, non_db – Set the priority of the job to be queued
    
    qos, str, optional, non_db – Set the quality of service to use in for the queue on the remote computer
    
    queue_name, str, optional, non_db – Set the name of the queue on the remote computer
    
    resources, dict, required, non_db – Set the dictionary of resources to be used by the scheduler plugin, like the number of nodes, cpus etc. This dictionary is scheduler-plugin dependent. Look at the documentation of the scheduler for more details.
    
    scheduler_stderr, str, optional, non_db – Filename to which the content of stderr of the scheduler is written.
    
    scheduler_stdout, str, optional, non_db – Filename to which the content of stdout of the scheduler is written.
    
    stash, Namespace – Optional directives to stash files after the calculation job has completed.
    
    Namespace Ports
    
    source_list, (tuple, list), optional, non_db – Sequence of relative filepaths representing files in the remote directory that should be stashed.
    
    stash_mode, str, optional, non_db – Mode with which to perform the stashing, should be value of `aiida.common.datastructures.StashMode.
    
    target_base, str, optional, non_db – The base location to where the files should be stashd. For example, for the copy stash mode, this should be an absolute filepath on the remote computer.
    
    submit_script_filename, str, optional, non_db – Filename to which the job submission script is written.
    
    withmpi, bool, optional, non_db – Set the calculation to use mpi
  - store_provenance, bool, optional, non_db – If set to False provenance will not be stored in the database.
- parameters, Dict, required – The VASP input parameters (INCAR).
- potential, Namespace – The potentials (POTCAR).
- restart_folder, RemoteData, optional – A remote folder to restart from if need be
- settings, Dict, optional – Additional parameters not related to VASP itself.
- structure, (StructureData, CifData), required – The input structure (POSCAR).
- wavefunctions, WavefunData, optional – The wave function coefficients. (WAVECAR)

Outputs:

bands, BandsData, optional – The output band structure.
born_charges, ArrayData, optional – The output Born effective charges.
chgcar, ChargedensityData, optional – The output charge density.
dielectrics, ArrayData, optional – The output dielectric functions.
dos, ArrayData, optional – The output dos.
dynmat, ArrayData, optional – The output dynamical matrix.
energies, ArrayData, optional – The output total energies.
forces, ArrayData, optional – The output forces.
hessian, ArrayData, optional – The output Hessian matrix.
kpoints, KpointsData, optional – The output k-points.
misc, Dict, required – The output parameters containing smaller quantities that do not depend on system size.
occupancies, ArrayData, optional – The output band occupancies.
projectors, ArrayData, optional – The output projectors of decomposition.
remote_folder, RemoteData, required – Input files necessary to run the process will be stored in this folder node.
remote_stash, RemoteStashData, optional – Contents of the stash.source_list option are stored in this remote folder after job completion.
retrieved, FolderData, required – Files that are retrieved by the daemon will be stored in this node. By default the stdout and stderr of the scheduler will be added, but one can add more by specifying them in CalcInfo.retrieve_list.
site_magnetization, Dict, optional – The output of the site magnetization
stress, ArrayData, optional – The output stress.
structure, StructureData, optional – The output structure.
trajectory, TrajectoryData, optional – The output trajectory data.
wavecar, WavefunData, optional – The output file containing the plane wave coefficients.

Outline:

setup(Call the ``setup`` of the ``BaseRestartWorkChain`` and then create the inputs dictionary in ``self.ctx.inputs``. This ``self.ctx.inputs`` dictionary will be used by the ``BaseRestartWorkChain`` to submit the calculations in the internal loop.)
while(should_run_process)
    run_process(Run the next process, taking the input dictionary from the context at `self.ctx.inputs`.)
    inspect_process(Analyse the results of the previous process and call the handlers when necessary. If the process is excepted or killed, the work chain will abort. Otherwise any attached handlers will be called in order of their specified priority. If the process was failed and no handler returns a report indicating that the error was handled, it is considered an unhandled process failure and the process is relaunched. If this happens twice in a row, the work chain is aborted. In the case that at least one handler returned a report the following matrix determines the logic that is followed: Process  Handler    Handler     Action result   report?    exit code ----------------------------------------- Success      yes        == 0     Restart Success      yes        != 0     Abort Failed       yes        == 0     Restart Failed       yes        != 0     Abort If no handler returned a report and the process finished successfully, the work chain's work is considered done and it will move on to the next step that directly follows the `while` conditional, if there is one defined in the outline.)
results(Attach the outputs specified in the output specification from the last completed process.)

VaspBaseWorkChain¶

How error handlers work¶

Current error handlers¶

How to add new error handler¶

Detailed inputs, outputs, and outline¶

How to add new `error handler`¶