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'
    'add_comp_para': {
        'serial': False,                 # False if use MPI version for the FT calc
        'only_even_MPI': False,          # True if suppress parallelisation having odd number of MPI
        'max_queue_nodes': 20,           # Max number of nodes allowed (used by automatic error fix)
        'max_queue_wallclock_sec': 86400 # Max number of walltime allowed (used by automatic error fix)
        },
    '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,
                     'add_comp_para': {
                                        'serial': False,
                                        'only_even_MPI': False,
                                        'max_queue_nodes': 20,
                                        'max_queue_wallclock_sec': 86400
                                        }})

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)