Fleur Create Magnetic Film workchain — AiiDA-FLEUR 1.1.1 documentation

# Fleur Create Magnetic Film workchain

- Current version: 0.1.1

- Class: FleurCreateMagneticWorkChain

- String to pass to the `WorkflowFactory()`: `fleur.create_magnetic`

- Workflow type: Scientific workchain

Contents

- Fleur Create Magnetic Film workchain

  - Description/Purpose

  - Input nodes

  - Output nodes

  - Supported input configurations

  - Error handling

  - Example usage

Import Example:

    from aiida_fleur.workflows.create_magnetic_film import FleurCreateMagneticWorkChain
    #or
    WorkflowFactory('fleur.create_magnetic')

## Description/Purpose

The workchain constructs a relaxed film structure which is ready-to-use in the subsequent magnetic workchains, such as DMI, MAE or SSDisp workchains.

The main inputs include information about the substrate (structure type, miller indices, element) and deposited material. The main logic of the workchain is depicted on the figure below:

First, the workchain uses EOS workchain to find the equilibrium lattice parameters for the substrate. For now only bcc and fcc substrate lattices are supported. Note, the algorithm always uses conventional unit cells e.g. one gets 4 atoms in the unit cell for fcc lattice (see the figure above).

After that, the workchain constructs a film which will be used for interlayer distance relaxation via the relaxation workchain. The algorithm creates a film using given miller indices and the ground state lattice constant and replaces some layers with another elements given in the input. For now only single-element layer replacements are possible i.e. each resulting layer can be made of a single element. It is not possible to create e.g. B-N monolayer using this workchain. If we refer to the figure above, in ideal case one constructs a structure with an inversion or z-reflection symmetry to calculate interlayer distances 1-4. However, the workchain does not ensure an inversion or z-reflection symmetry, that is user responsibility to make it. For instance, if you want to achieve one of these symmetries you should pass positive and negative numbers of layer in the replacements dictionary of the wf parameters, see an example in defaults.

Note

z-reflection or inversion symmetries are not ensured by the workchain even if you specify symmetric replacements. Sometimes you need to remove a few layers before replacements. For example, consider the case of fcc (110) film: if `size` is equal to (1, 1, 4) there are will be 8 layers in the template before the replacements since there are 2 layers in the unit cell. That means the x,y positions of the first atom are equal to (0.0, 0.0) when the 8th atom coordinates are equal to (0.5, 0.5). Thus, to achieve z-reflection symmetry one needs to remove the 8th layer by specifying `'pop_last_layers' : 1` in the wf parameters.

Finally, using the result of the relaxation workchain, a magnetic structure having no z-reflection symmetry is created. For this the workchain takes first N layers from the relaxed structure and attaches M substrate layers to the bottom. The final structure is z-centralised.

## Input nodes

The FleurCreateMagneticWorkChain employs exposed feature of the AiiDA-core, thus inputs for the EOS and relaxation workchains should be passed in the namespaces `eos` and `relax` correspondingly (see example of usage). Please note that the structure input node is excluded from the EOS namespace and from the Relax SCF namespace since corresponding input structures are created within the CreateMagnetic workchain.

name | type | description | required
--- | --- | --- | ---
eos | namespace | inputs for nested EOS WC. structure input is excluded. | no
relax | namespace | inputs for nested Relax WC. structure input of SCF sub-namespace is excluded | no
wf_parameters | `Dict` | Settings of the workchain | no
eos_output | `Dict` | EOS output dictionary | no
optimized_structure | `StructureData` | relaxed film structure | no
distance_suggestion | `Dict` | interatomic distance suggestion, output of py:func:~aiida_fleur.tools.StructureData_util.request_average_bond_length_store() | no

Similarly to other workchains, FleurCreateMagneticWorkChain behaves differently depending on the input nodes setup. The list of supported input configurations is given in the section Supported input configurations.

### Workchain parameters and its defaults

#### `wf_parameters`

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

    # -*- coding: utf-8 -*-
    'lattice': 'fcc',                  # type of the substrate lattice: 'bcc' or 'fcc'
    'miller': [[-1, 1, 0],             # miller indices to orient the lattice
               [0, 0, 1],
               [1, 1, 0]],
    'host_symbol': 'Pt',               # chemical element of the substrate
    'latticeconstant': 4.0,            # initial guess for the substrate lattice constant
    'size': (1, 1, 5),                 # sets the size of the film unit cell for relax step
    'replacements': {-2: 'Fe',         # sets the layer number to be replaced by another element
                     -1: 'Fe'},        # NOTE: negative number means that replacement will take place
                                       #       on layers on the other side from the held layers

    'decimals': 10,                    # set the accuracy of writing atom positions
    'pop_last_layers': 1,              # number of bottom layers to be removed before relaxation
    'hold_n_first_layers': 5,          # number of bottom layers to be held during the relaxation
                                       # (relaxXYZ = 'FFF')

    'total_number_layers': 4,          # use this total number of layers
    'num_relaxed_layers': 2,           # use this number of relaxed interlayer distances

## Output nodes

> - `magnetic_structure`: `StructureData`- the relaxed film structure.

## Supported input configurations

CreateMagnetic workchain has several input combinations that implicitly define the workchain layout. eos, relax, optimized_structure and eos_output are analysed. Depending on the given setup of the inputs, one of four supported scenarios will happen:

1. eos + relax + distance_suggestion:

   > The EOS will be used to calculate the equilibrium structure of the substrate, then Relax WC will be used to relax the interlayer distances. Finally, the non-symmetrical magnetic structure will be created. A good choice if there is nothing to begin with. distance_suggestion will be used to guess a better starting interlayer distances before submitting Relax WC.

2. eos_output + relax + distance_suggestion:

   > The equilibrium substrate structure will be extracted from the eos_output, then Relax WC will be used to relax the interlayer distances. Finally, the non-symmetrical magnetic structure will be created. A good choice if EOS was previously done for the substrate. distance_suggestion will be used to guess a better starting interlayer distances before submitting Relax WC.

3. optimized_structure:

   > optimized_structure will be treated as a result of Relax WC and directly used to construct the final non-symmetrical magnetic structure. A good choice if everything was done except the very last step.

4. relax:

   > Relax WC will be submitted using inputs of the namespace, which means one can for instance continue a relaxation procedure. After Relax WC is finished, the non-symmetrical magnetic structure will be created. A good choice if something wrong happened in one of the relaxation steps of another CreateMagnetic workchain submission.

All the other input configuration will end up with an exit code 231, protecting user from misunderstanding.

## Error handling

A list of implemented exit codes:

Code | Meaning
--- | ---
230 | Invalid workchain parameters
231 | Invalid input configuration
380 | Specified substrate is not bcc or fcc, only them are supported
382 | Relaxation calculation failed.
383 | EOS WorkChain failed.

## Example usage

>     # -*- coding: utf-8 -*-
>     from aiida.orm import load_node, Dict
>     from aiida.engine import submit

>     from aiida_fleur.workflows.create_magnetic_film import FleurCreateMagneticWorkChain

>     fleur_code = load_node(FLEUR_PK)
>     inpgen_code = load_node(INPGEN_PK)

>     wf_para = {
>         'lattice': 'fcc',
>         'miller': [[-1, 1, 0],
>                    [0, 0, 1],
>                    [1, 1, 0]],
>         'host_symbol': 'Pt',
>         'latticeconstant': 4.0,
>         'size': (1, 1, 5),
>         'replacements': {0: 'Fe', -1: 'Fe'},
>         'decimals': 10,
>         'pop_last_layers': 1,

>         'total_number_layers': 8,
>         'num_relaxed_layers': 3,
>     }

>     wf_para = Dict(dict=wf_para)

>     wf_eos = {'points': 15,
>               'step': 0.015,
>               'guess': 1.00
>               }

>     wf_eos_scf = {'fleur_runmax': 4,
>                   'density_converged': 0.0002,
>                   'serial': False,
>                   'itmax_per_run': 50,
>                   'inpxml_changes': []
>                   }

>     wf_eos_scf = Dict(dict=wf_eos_scf)

>     wf_eos = Dict(dict=wf_eos)

>     calc_eos = {'comp': {'kmax': 3.8,
>                          },
>                 'kpt': {'div1': 4,
>                         'div2': 4,
>                         'div3': 4
>                         }
>                 }

>     calc_eos = Dict(dict=calc_eos)

>     options_eos = {'resources': {'num_machines': 1, 'num_mpiprocs_per_machine': 4, 'num_cores_per_mpiproc': 6},
>                    'queue_name': 'devel',
>                    'custom_scheduler_commands': '',
>                    'max_wallclock_seconds':  1*60*60}

>     options_eos = Dict(dict=options_eos)

>     wf_relax = {'film_distance_relaxation': False,
>                 'force_criterion': 0.049,
>                 'relax_iter': 5
>                 }

>     wf_relax_scf = {'fleur_runmax': 5,
>                     'serial': False,
>                     'use_relax_xml': True,
>                     'itmax_per_run': 50,
>                     'alpha_mix': 0.015,
>                     'relax_iter': 25,
>                     'force_converged': 0.001,
>                     'force_dict': {'qfix': 2,
>                                    'forcealpha': 0.75,
>                                    'forcemix': 'straight'},
>                     'inpxml_changes': []
>                     }

>     wf_relax = Dict(dict=wf_relax)
>     wf_relax_scf = Dict(dict=wf_relax_scf)

>     calc_relax = {'comp': {'kmax': 4.0,
>                            },
>                   'kpt': {'div1': 24,
>                           'div2': 20,
>                           'div3': 1
>                           },
>                   'atom': {'element': 'Pt',
>                            'rmt': 2.2,
>                            'lmax': 10,
>                            'lnonsph': 6,
>                            'econfig': '[Kr] 5s2 4d10 4f14 5p6| 5d9 6s1',
>                            },
>                   'atom2': {'element': 'Fe',
>                             'rmt': 2.1,
>                             'lmax': 10,
>                             'lnonsph': 6,
>                             'econfig': '[Ne] 3s2 3p6| 3d6 4s2',
>                             },
>                   }

>     calc_relax = Dict(dict=calc_relax)

>     options_relax = {'resources': {'num_machines': 1, 'num_mpiprocs_per_machine': 4, 'num_cores_per_mpiproc': 6},
>                      'queue_name': 'devel',
>                      'custom_scheduler_commands': '',
>                      'max_wallclock_seconds':  1*60*60}

>     inputs = {
>         'eos': {
>             'scf': {
>                 'wf_parameters': wf_eos_scf,
>                 'calc_parameters': calc_eos,
>                 'options': options_eos,
>                 'inpgen': inpgen_code,
>                 'fleur': fleur_code
>             },
>             'wf_parameters': wf_eos
>         },
>         'relax': {
>             'scf': {
>                 'wf_parameters': wf_relax_scf,
>                 'calc_parameters': calc_relax,
>                 'options': options_relax,
>                 'inpgen': inpgen_code,
>                 'fleur': fleur_code
>             },
>             'wf_parameters': wf_relax,
>         },
>         'wf_parameters': wf_para
>     }

>     res = submit(FleurCreateMagneticWorkChain, **inputs)