VaspConvergeWorkChain¶

The VaspConvergeWorkChain aims to automate the indentification of converged energy cutoff and kpoints mesh for a given structure. In short, it makes our lives much easier.

How it works¶

The VaspConvergeWorkChain() allows us to supply a list of ENCUT and KSPACING, provide a structure, hit the button, sit back, and get the converged results as:

{
    'ENCUT': 500,
    'KSPACING': 0.4
}

Under the hood, we use S_conv protocol with VaspMultiStageWorkChain. It first submits all calculations with different ENCUT values in parallel and waits for all to finish. It then, selects the converged ENCUT by considering a threshold:

{
    "converged_encut": 500,
    "converged_encut_conservative": 550,
    "energy_difference": 0.00023466671880001,
    "final_energy": {
        "500": -357.5085037,
        "550": -357.49348503,
        "600": -357.51247015,
        "650": -357.53935157,
        "700": -357.53571681,
        "750": -357.5267332
    },
    "final_energy_per_atom": {
        "500": -5.5860703703125,
        "550": -5.5858357035937,
        "600": -5.5861323460938,
        "650": -5.5865523682813,
        "700": -5.5864955751562,
        "750": -5.58635520625
    }
}

Then, it uses the selected ENCUT (ie, converged_encut) and submits (again in parallel) calculations with varying KSPACING and reports the energies:

{
    "converged_kspacing": 0.4,
    "converged_kspacing_conservative": 0.38,
    "energy_difference": 0.0,
    "final_energy": {
        "0.1": -357.5251117,
        "0.12": -357.52511238,
        "0.14": -357.52513287,
        "0.16": -357.5250471,
        "0.18": -357.52480178,
        "0.2": -357.52480178,
        "0.22": -357.52479079,
        "0.24": -357.52304064,
        "0.26": -357.52297048,
        "0.28": -357.52297048,
        "0.3": -357.5085037,
        "0.32": -357.5085037,
        "0.34": -357.5085037,
        "0.36": -357.5085037,
        "0.38": -357.5085037,
        "0.4": -357.5085037
    },
    "final_energy_per_atom": {
        "0.1": -5.5863298703125,
        "0.12": -5.5863298809375,
        "0.14": -5.5863302010937,
        "0.16": -5.5863288609375,
        "0.18": -5.5863250278125,
        "0.2": -5.5863250278125,
        "0.22": -5.5863248560937,
        "0.24": -5.58629751,
        "0.26": -5.58629641375,
        "0.28": -5.58629641375,
        "0.3": -5.5860703703125,
        "0.32": -5.5860703703125,
        "0.34": -5.5860703703125,
        "0.36": -5.5860703703125,
        "0.38": -5.5860703703125,
        "0.4": -5.5860703703125
    }
}

and finally reports the final Dict which we saw first. This can be loaded/linked in any other subsequent calculations to keep the provenance.

Deailed inputs, outputs, and outline¶

workchainaiida_catmat.workchains.VaspConvergeWorkChain

Convergence WorkChain

Inputs:

encut_list, List, required – list of ENCUT for convergence calcs.
force_parity, Bool, optional – set to True to force parity in generated kpoint mesh
hubbard_tag, Str, optional – The string that controls which set of U parameters user wants to use
kgamma, Bool, optional – gamma centered kpoints in kspacing case
kspacing, Float, optional – The kspacing tag to generate kpoints mesh
kspacing_list, List, required – list of kspacing for convergence calcs.
magmom, List, optional – List of user supplied MAGMOM tag
max_stage_iteration, Int, optional – Maximum number of iterations/trials in case of failure.
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.
offset, List, optional – Offest for kpoints generation
parameters, Dict, required – The input parameters.
potcar_set, Str, optional – Select which potcar set should be used to construct mappin. VASP or MPRelaxSet
potential_family, Str, required – The string which defines which potential (POTCAR) familiy we want to use
potential_mapping, Dict, optional – The disctionary which controls which specific POTCAR user wants to use for each atom type.
protocol_tag, Str, optional – The string which controls which protocol to use for setting up the calculations.
restart_folder, RemoteData, optional – Remote folder with data to use for restarting a calculation
settings, Dict, optional
structure, (StructureData, CifData), required – The input structue to perform calculations on
threshold, Float, optional – Threshold to consider energy per atom converged!
vasp_base, Namespace
Namespace Ports
- clean_workdir, Bool, optional – If True, work directories of all called calculation jobs will be cleaned at the end of execution.
- max_iterations, Int, optional – Maximum number of iterations the work chain will restart the process to finish successfully.
- vasp, Namespace
  Namespace Ports
  - code, Code, required – The Code to use for this job.
  - kpoints, KpointsData, optional – kpoints mesh
  - 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, str, optional, non_db – Parser of the calculation: the default is vasp_base_parser to get the necessary info
    
    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.
  - potential, Namespace – The potentials (POTCAR).
  - restart_folder, RemoteData, optional – A remote folder to restart from if need be

Outputs:

convergence_results, Namespace
final_incar, Namespace
magmom, List, optional – List of MAGMOM
output_parameters, Dict, required
structure, StructureData, optional

Outline:

initialize(Initialize inputs and settings)
while(should_converge_encut)
    run_encut_converge(Submit VaspMultiStageWorkChain with all items in ENCUT list)
    inspect_encut_converge(Asserts whether all ENCUT calculations are finished ok)
    process_encut_converge(Process and extract results of ENCUT convergence)
while(should_converge_kspacing)
    run_kspacing_converge(Submit VaspMultiStageWorkChain with all items in ENCUT list)
    inspect_kspacing_converge(Asserts whether all ENCUT calculations are finished ok)
    process_kspacing_converge(Process and extract results of ENCUT convergence)
results(Handle results)