Fleur self-consistency field workflow

  • Class: FleurScfWorkChain
  • String to pass to the WorkflowFactory(): fleur.scf
  • Workflow type: Basic
  • 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.

Note

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 none or one inpgen calculation and one to several Fleur calculations. It is one of the most core workflows and often deployed as a sub-workflow.

Note

The FleurScfWorkChain by default determines the calculation resources required for the given system and with what hybrid parallelisation to launch Fleur. The resources in the option node given are the maximum resources the workflow is allowed to allocate for one simulation (job). You can turn off this feature by setting determine_resources = False in the wf_parameters.

Input nodes

  • fleur: Code - Fleur code using the fleur.fleur plugin
  • inpgen: Code, optional - Inpgen code using the fleur.inpgen plugin
  • wf_parameters: Dict, optional - Settings of the workflow behavior
  • structure: StructureData, optional: Crystal structure data node.
  • calc_parameters: Dict, optional - FLAPW parameters, used by inpgen
  • fleurinp: FleurinpData, optional: Fleur input data object representing the FLEUR input files
  • remote_data: RemoteData, optional - The remote folder of the previous calculation
  • options: Dict, optional - AiiDA options (queues, cpus)
  • settings: Dict, optional - special settings for Fleur calculations.

As you can see the SCF workchain has a lot of optional inputs. However, it does not mean all of them can be left unspecified. You must to specify a pre-defined minimal set of inputs. The possible sets can be found below in the Layout section.

Returns nodes

  • output_scf_wc_para: Dict - Main results of the workflow
  • fleurinp: FleurinpData - An inp.xml that was actually used.
  • last_fleur_calc_output: Dict - Output node of the last Fleur calculation.

Default inputs

All possible workflow parameters and their defaults.

_wf_default = {'fleur_runmax': 4,                 # Maximum number of fleur jobs/starts
               'density_converged': 0.00002,      # Stop if charge density is converged below this value
               'energy_converged': 0.002,         # Stop if total energy is converged below this value
               'force_converged': 0.002,          # Stop if the largest force is converged below this value
               'mode': 'density',                 # which parameter to converge: 'density', 'force' or 'energy'
               'serial': False,                   # execute fleur with mpi or without
               'itmax_per_run': 30,               # Maximum iterations run for one Fleur job
               'force_dict': {'qfix': 2,          # parameters required for the 'force' mode
                              'forcealpha': 0.5,
                              'forcemix': 2},
               'inpxml_changes': [],              # (expert) List of further changes applied to the inp.xml after the inpgen run
              }                                   # tuples (function_name, [parameters]), have to be the function names supported by fleurinpmodifier

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.

Layout

Similarly to FleurCalculation, SCF workchain has several input combinations that implicitly define the workchain layout. 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 a charge density, use the option 3. If you want to change something in the inp.xml and use the 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.

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

Database Node graph

from aiida_fleur.tools.graph_fleur import draw_graph

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

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

Example usage

# -*- coding: utf-8 -*-
###############################################################################
# Copyright (c), Forschungszentrum Jülich GmbH, IAS-1/PGI-1, Germany.         #
#                All rights reserved.                                         #
# This file is part of the AiiDA-FLEUR package.                               #
#                                                                             #
# The code is hosted on GitHub at https://github.com/broeder-j/aiida-fleur    #
# For further information on the license, see the LICENSE.txt file            #
# For further information please visit http://www.flapw.de or                 #
# http://aiida-fleur.readthedocs.io/en/develop/                               #
###############################################################################

"""
Here we run the fleur_scf_wc for W or some other material
Layout:

1. Database env load, Import, create base classes
2. Creation of  input nodes
3. Lauch workchain
"""

#######################
# 1. Load the database environment. Imports and base class creation

from __future__ import absolute_import
from aiida import load_dbenv, is_dbenv_loaded
if not is_dbenv_loaded():
    load_dbenv()

from aiida.plugins import DataFactory
from aiida.orm import Code, load_node
from aiida.engine.launch import submit, run
from aiida_fleur.workflows.scf import FleurScfWorkChain

ParameterData = DataFactory('parameter')
StructureData = DataFactory('structure')

#######################    
# 2. Creation/loding of input nodes

# Load the codes, thwy have to be setup in your database.
fleur_label = 'fleur@localhost'
inpgen_label = 'inpgen@localhost'
fleur_code =  Code.get_from_string(fleur_label)
inpgen_code = Code.get_from_string(inpgen_label)

### Create wf_parameters (optional) and options
wf_para = Dict(dict={'fleur_runmax' : 4, 
                              'density_criterion' : 0.000001,
                              'serial' : False})

options = Dict(dict={'resources' : {"num_machines": 1},
                              'queue_name' : '',
                              'max_wallclock_seconds':  60*60})

# Create W bcc crystal structure 
bohr_a_0= 0.52917721092 # A
a = 3.013812049196*bohr_a_0
cell = [[-a,a,a],[a,-a,a],[a,a,-a]]
structure = StructureData(cell=cell)
structure.append_atom(position=(0.,0.,0.), symbols='W')

# (optional) We specifi some FLAPW parameters for W
parameters = Dict(dict={
                  'atom':{
                        'element' : 'W',
                        'jri' : 833,
                        'rmt' : 2.3,
                        'dx' : 0.015,
                        'lmax' : 8,
                        'lo' : '5p',
                        'econfig': '[Kr] 5s2 4d10 4f14| 5p6 5d4 6s2',
                        },
                  'comp': {
                        'kmax': 3.0,
                        },
                  'kpt': {
                        'nkpt': 100,
                        }})


################################
# 3. submit the workchain with its inputs.

inputs = {}
inputs['wf_parameters'] = wf_para
inputs['structure'] = structure
inputs['calc_parameters'] = parameters
inputs['fleur'] = fleur_code
inputs['inpgen'] = inpgen_code
inputs['description'] = 'test fleur_scf_wc run on W'
inputs['label'] = 'test on W'
inputs['options'] = options

# submit workchain to the daemon
# Noice that the nodes we created before are not yet stored in the database, 
# but AiiDA will do so automaticly when we launch the workchain. 
# To reuse nodes it might be a good idea, to save them before by hand and then load them 
res = submit(FleurScfWorkChain, **inputs)

# You can also run the workflow in the python interpreter as blocking
#res = run(fleur_scf_wc, **inputs)

Output node example

{
  "distance_charge": 4.8e-08, 
  "distance_charge_all": [
    14.0641263108, 
    12.8600114364, 
    6.8261429168, 
    2.8385734177, 
    1.7976439088, 
    0.3930232044, 
    0.3185748414, 
    0.0207838885, 
    0.0293630023, 
    0.0033425889, 
    0.0038933844, 
    0.0002397749, 
    6.58407e-05, 
    4.8137e-06, 
    1.8709e-06, 
    1.6308e-06, 
    4.8e-08
  ], 
  "distance_charge_units": "me/bohr^3", 
  "errors": [], 
  "info": [], 
  "iterations_total": 17, 
  "last_calc_uuid": "36177d08-8377-4c79-a38e-a45d9bd4bcd2", 
  "loop_count": 1, 
  "material": "W", 
  "successful": true, 
  "total_energy": -16166.1210541652, 
  "total_energy_all": [
    -16166.1261375671, 
    -16166.1245649923, 
    -16166.1192980126, 
    -16166.1206030359, 
    -16166.1209158221, 
    -16166.12103797, 
    -16166.1210144268, 
    -16166.1210421098, 
    -16166.1210512503, 
    -16166.1210530889, 
    -16166.1210542938, 
    -16166.1210540822, 
    -16166.1210541372, 
    -16166.1210541368, 
    -16166.1210541662, 
    -16166.1210541663, 
    -16166.1210541652
  ], 
  "total_energy_units": "Htr", 
  "total_wall_time": 19, 
  "total_wall_time_units": "hours", 
  "warnings": [], 
  "workflow_name": "fleur_scf_wc", 
  "workflow_version": "0.2.1"
}

Error handling

Still has to be documented