Fleur self-consistency field workflow — AiiDA-FLEUR 1.1.0 documentation

# 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

Contents

- Fleur self-consistency field workflow

  - Description/Purpose

  - Input nodes

    - Workchain parameters and its defaults

  - Returns nodes

  - Layout

  - Error handling

  - Plot_fleur visualization

  - Database Node graph

  - Example usage

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
>       '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. remote_data (FLEUR):

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

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

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.

## 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)

> Multi node

>     from aiida_fleur.tools.plot import plot_fleur

>     plot_fleur(scf_pk_list)

## Database Node graph

>     from aiida_fleur.tools.graph_fleur import draw_graph

>     draw_graph(50816)

## 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})

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