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 (largest force is an exception because FLEUR code first checks if density was converged). 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:

    # -*- coding: utf-8 -*-
'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
'only_even_MPI': False,              # True if suppress parallelisation having odd number of MPI
'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. Exception: force mode uses both density_converged and force_converged because FLEUR code always converges density before forces.

  • 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 details:

  • fleurinp: FleurinpData - A FleurinpData that was actually used for last FleurScfWorkChain. 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:

    # -*- coding: utf-8 -*-
{
    '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 workchain during inputs processing. Depending on the setup of the inputs, one of the four supported scenarios will happen:

  1. 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.

  2. fleurinp:

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

  3. structure + inpgen + calc_parameters:

    inpgen code and optional calc_parameters will be used to generate a new FleurinpData using a given structure. Generated FleurinpData will be used as an input for the first FLEUR calculation.

  1. structure + inpgen + calc_parameters + remote_data (FLEUR):

    inpgen code and optional calc_parameters will be used to generate a new FleurinpData using a given structure. Generated FleurinpData will be used as an input for the first FLEUR calculation. Initial charge density will be taken from given remote_data (FLEUR). Note: make sure that remote_data (FLEUR) corresponds to the same structure.

  1. remote_data (FLEUR):

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

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 exit code 230.

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 codes:

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 was 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

# -*- coding: utf-8 -*-
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_converged': 0.001,
                     'mode': 'density',
                     'itmax_per_run': 30,
                     'serial': False,
                     'only_even_MPI': 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)