Fleur self-consistency field workflow

  • Current version: 0.4.0
  • Class: FleurScfWorkChain
  • String to pass to the WorkflowFactory(): fleur.scf
  • Workflow type: Technical
  • Aim: Manage FLEUR SCF convergence
  • Computational demand: Corresponding to several FleurCalculation
  • Database footprint: Output node with information, full provenance, ~ 10+10*FLEUR Jobs nodes
  • File repository footprint: no addition to the CalcJob run

Import Example:

from aiida_fleur.workflows.scf import FleurScfWorkChain
#or
WorkflowFactory('fleur.scf')

Description/Purpose

Converges the charge density, the total energy or the largest force of a given structure, or stops because the maximum allowed retries are reached.

The workchain is designed to converge only one parameter independently on other parameters. Simultaneous convergence of two or three parameters is not implemented to simplify the code logic and because one almost always interested in a particular parameter. Moreover, it was shown that the total energy tend to converge faster than the charge density.

This workflow manages an inpgen calculation (if needed) and several Fleur calculations. It is one of the most core workchains and often deployed as a sub-workflow.

Input nodes

The table below shows all the possible input nodes of the SCF workchain.

name type description required
fleur Code Fleur code yes
inpgen Code Inpgen code no
wf_parameters Dict Settings of the workchain no
structure StructureData Structure data node no
calc_parameters Dict inpgen parameters no
fleurinp FleurinpData FLEUR input no
remote_data RemoteData Remote folder of another calculation no
options Dict AiiDA options (computational resources) no
settings Dict Special settings for Fleur calculation no

Only fleur input is required. However, it does not mean that it is enough to specify fleur only. One must keep one of the supported input configurations described in the Layout section.

Workchain parameters and its defaults

  • wf_parameters: Dict - Settings of the workflow behavior. All possible keys and their defaults are listed below:

    'fleur_runmax': 4,                   # Maximum number of fleur jobs/starts
    'density_converged': 0.00002,        # Charge density convergence criterion
    'energy_converged': 0.002,           # Total energy convergence criterion
    'force_converged': 0.002,            # Largest force convergence criterion
    'mode': 'density',                   # Parameter to converge: 'density', 'force' or 'energy'
    'serial': False,                     # Execute fleur with mpi or without
    'itmax_per_run': 30,                 # Maximum iterations run for one FleurCalculation
    'force_dict': {'qfix': 2,            # parameters required for the 'force' mode
                   'forcealpha': 0.5,
                   'forcemix': 'BFGS'},
    'inpxml_changes': [],                # Modifications to inp.xml
    
    

    ‘force_dict’ contains parameters that will be inserted into the inp.xml in case of force convergence mode. Usually this sub-dictionary does not affect the convergence, it affects only the generation of relax.xml file. Read more in FLEUR relaxation documentation.

    Note

    Only one of density_converged, energy_converged or force_converged is used by the workchain that corresponds to the ‘mode’. The other two are ignored.

  • options: Dict - AiiDA options (computational resources). Example:

    'resources': {"num_machines": 1, "num_mpiprocs_per_machine": 1},
    'max_wallclock_seconds': 6*60*60,
    'queue_name': '',
    'custom_scheduler_commands': '',
    'import_sys_environment': False,
    'environment_variables': {}
    

Returns nodes

The table below shows all the possible output nodes of the SCF workchain.

name type comment
output_scf_wc_para Dict results of the workchain
fleurinp FleurinpData FleurinpData that was used (after all modifications)
last_fleur_calc_output Dict Link to last FleurCalculation output dict

More comments:

  • fleurinp: FleurinpData - A FleurinpData that was actually used for last FleurCalculation. It usually differs from the input FleurinpData because there are some hard-coded modifications in the SCF workchain.

  • last_fleur_calc_output: Dict - A link to the output node of the last Fleur calculation.

  • output_scf_wc_para: Dict - Main results of the workchain. Contains errors, warnings, convergence history and other information. An example:

    {
        "conv_mode": "density",
        "distance_charge": 0.1406279038,
        "distance_charge_all": [
            61.1110641131,
            43.7556515683,
            ...
        ],
        "distance_charge_units": "me/bohr^3",
        "errors": [],
        "force_diff_last": "can not be determined",
        "force_largest": 0.0,
        "info": [],
        "iterations_total": 23,
        "last_calc_uuid": "b20b5b94-5d80-41a8-82bf-b4d8eee9bddc",
        "loop_count": 1,
        "material": "FePt2",
        "total_energy": -38166.176928494,
        "total_energy_all": [
            -38166.542950054,
            -38166.345602746,
            ...
        ],
        "total_energy_units": "Htr",
        "total_wall_time": 245,
        "total_wall_time_units": "s",
        "warnings": [],
        "workflow_name": "FleurScfWorkChain",
        "workflow_version": "0.4.0"
    }
    

Layout

Similarly to FleurCalculation, SCF workchain has several input combinations that implicitly define the behaviour of the workchains during inputs processing. Depending on the setup of the inputs, one of four supported scenarios will happen:

  1. fleurinp:

    Files, belonging to the fleurinp, will be used as input for the first FLEUR calculation.

  2. fleurinp + remote_data (FLEUR):

    Files, belonging to the fleurinp, will be used as input for the first FLEUR calculation. Moreover, initial charge density will be copied from the folder of the remote folder.

  3. remote_data (FLEUR):

    inp.xml file and initial charge density will be copied from the remote folder.

  4. structure:

    inpgen code will be used to generate a new fleurinp using a given structure. Generated fleurinp will be used as input for the first FLEUR calculation.

For example, if you want to continue converging charge density, use the option 3. If you want to change something in the inp.xml and use old charge density you should use option 2. To do this, you can retrieve a FleurinpData produced by the parent calculation and change it via FleurinpModifier, use it as an input together with the RemoteFolder.

Warning

One must keep one of the supported input configurations. In other case the workchain will stop throwing non-zero exit status or more dangerously, will make unexpected actions.

The general layout does not depend on the scenario, SCF workchain sequentially submits several FLEUR calculation to achieve a convergence criterion.

../../_images/Workchain_charts_scf_wc.png

Error handling

In case of failure the SCF WorkChain should throw one of the exit errors:

Exit code Reason
230 Invalid input, please check input configuration
231 Invalid code node specified, check inpgen and fleur code nodes.
232 Input file modification failed
233 Input file is corrupted after modifications
360 Inpgen calculation failed
361 Fleur calculation failed
362 SCF cycle did not lead to convergence, maximum number of iterations exceeded.

If your workchain crashes and stops in Excepted state, please open a new issue on the Github page and describe the details of the failure.

Plot_fleur visualization

Single node

from aiida_fleur.tools.plot import plot_fleur

plot_fleur(50816)
../../_images/plot_fleur_scf1.png
../../_images/plot_fleur_scf2.png

Multi node

from aiida_fleur.tools.plot import plot_fleur

plot_fleur(scf_pk_list)
../../_images/plot_fleur_scf_m1.png
../../_images/plot_fleur_scf_m2.png

Database Node graph

from aiida_fleur.tools.graph_fleur import draw_graph

draw_graph(50816)
../../_images/scf_50816.pdf

Example usage

from aiida_fleur.workflows.scf import FleurScfWorkChain
from aiida.orm import Dict, load_node

fleur_code = load_node(FLEUR_PK)
inpgen_code = load_node(INPGEN_PK)
structure = load_node(STRUCTURE_PK)

wf_para = Dict(dict={'fleur_runmax' : 3,
                     'density_converge' : 0.001,
                     'mode' : 'density',
                     'itmax_per_run' : 30,
                     'serial' : False})

options = Dict(dict={'resources' : {"num_machines": 1, "num_mpiprocs_per_machine" : 2},
                     'withmpi' : True,
                     'max_wallclock_seconds' : 600})

calc_parameters = Dict(dict={'kpt': {'div1': 2,
                                     'div2' : 2,
                                     'div3' : 2
                                    }})

SCF_workchain = submit(FleurScfWorkChain,
                       fleur=fleur_code,
                       inpgen=inpgen_code,
                       calc_parameters=calc_parameters,
                       structure=structure,
                       wf_parameters=wf_para,
                       options=options)