EMTO (Exact Muffin-Tin Orbitals) Helper

The EMTO helper is a CLI tool to ease the generation of EMTO-CPA input files.

Installation

Before installation, make sure the Python version linked to the python command in your terminal is no lower than 3.8. To check the Python version, run python --version. Then install click through python -m pip install click.

Now clone the remote EMTO-Helper repository to your local machine. All three of HTTPS, SSH, and GitHub CLI approaches are valid to clone the repository. For HTTPS, you can run

git clone https://github.com/ywuenthought/EMTO-Helper.git

Enter the root directory of the cloned repository, and then run the following CI command to set up the Python virtual environment.

python -m ci setup

This will create a virtual environment called emto_helper in the ~/.venv directory. To use the EMTO Helper CLI, you need to activate this virtual environment by running

source ~/.venv/emto_helper/bin/activate

For Windows run the following command in PowerShell (PS):

~\.venv\emto_helper\Scripts\Activate.ps1

To exit the current virtual environment, simply run deactivate.

Usage of emto-helper CLI

If the installation succeeded you should be able to reproduce the following after typing emto-helper in the terminal.

$ emto-helper
Usage: emto-helper [OPTIONS] COMMAND [ARGS]...

  Collect all the CLI groups.

Options:
  --help  Show this message and exit.

Commands:
  docker   Group all the docker-related CLI commands.
  lattice  Group all the lattice-related CLI commands.
  motif    Group all the motif-related CLI commands.

The lattice group

This group collects all the lattice-related commands. Running emto-helper lattice will give you

$ emto-helper lattice
Usage: emto-helper lattice [OPTIONS] COMMAND [ARGS]...

  Group all the lattice-related CLI commands.

Options:
  --help  Show this message and exit.

Commands:
  create  Create lattice folders and files.

The create command

This command creates the input lattice files (and any folders) required for the EMTO-CPA calculations. To show usage of this command, run emto-helper lattice create --help.

$ emto-helper lattice create --help
Usage: emto-helper lattice create [OPTIONS]

  Create lattice folders and files.

Options:
  -o, --output-dir TEXT           Path to the output directory storing the
                                  lattice input.  [default: .]
  -f, --lattice-family [b2|b2m|b2o|bcc|bccm|bcco|fcc|fccm|fcco|hcp|hcpm|hcpo|b2h]
                                  Family of the crystal lattice structure
                                  whose children types will be created. If not
                                  provided, all children lattice types
                                  regardless of their families will be
                                  created.
  --help                          Show this message and exit.

The motif group

This group collects all the motif-related commands instead. Running emto-helper motif will give

$ emto-helper motif
Usage: emto-helper motif [OPTIONS] COMMAND [ARGS]...

  Group all the motif-related CLI commands.

Options:
  --help  Show this message and exit.

Commands:
  checkout  Check out the example input files of the CLI.
  create    Create motif folders and files.

The checkout command

This command copies the example input files of the CLI into the given output directory. To show its help message, run emto-helper motif checkout --help and you should see

$ emto-helper motif checkout --help
Usage: emto-helper motif checkout [OPTIONS]

  Check out the example input files of the CLI.

Options:
  -o, --output-dir TEXT  Path to the output directory storing example input
                         files.  [default: .]
  --help                 Show this message and exit.

The create command

This command creates the input motif files (and any folders) required for the EMTO-CPA calculations. To show usage of this command, run emto-helper motif create --help.

$ emto-helper motif create --help
Usage: emto-helper motif create [OPTIONS] KGRN_OVERWRITE META_OVERWRITE

  Create motif folders and files.

Options:
  -f, --lattice-family [b2|b2m|b2o|bcc|bccm|bcco|fcc|fccm|fcco|hcp|hcpm|hcpo|b2h]
                                  Family of the crystal lattice structure
                                  whose children types will be created.
                                  [required]
  -r, --lattice-root TEXT         Path to the root directory storing the
                                  lattice input. ALERT: Do NOT change the
                                  default value if using Docker.   [default:
                                  /lattices]
  -o, --output-dir TEXT           Path to the output directory storing KFCD
                                  and KGRN folders.  [default: .]
  --relax                         Whether to relax the Wigner-Seitz radius.
  -d, --delta FLOAT               Fraction of radius change between adjacent
                                  steps.  [default: 0.01]
  -s, --steps INTEGER             Number of steps to change radius at each
                                  side. Relative to the original radius left
                                  and right sides both have this many steps.
                                  [default: 5]
  --help                          Show this message and exit.

The docker group

This group collects all the motif-related commands instead. Running emto-helper docker will give

$ emto-helper docker
Usage: emto-helper docker [OPTIONS] COMMAND [ARGS]...

  Group all the docker-related CLI commands.

Options:
  --help  Show this message and exit.

Commands:
  build    Build the EMTO-CPA image tagged as "emto".
  lattice  Run EMTO-CPA against the input lattice files.
  motif    Run EMTO-CPA against the input motif files.

The build command

This command builds the EMTO-CPA Docker image used for running computation jobs locally. Simply run emto-helper docker build and the image will be built automatically for you. Please make sure that Docker daemon is turned on before running this command.

The lattice command

This command starts a container of the EMTO-CPA image and runs computation jobs against the input lattice files. Run emto-helper docker lattice --help to show its usage.

$ emto-helper docker lattice --help
Usage: emto-helper docker lattice [OPTIONS]

  Run EMTO-CPA against the input lattice files.

Options:
  -l, --lattice-dir TEXT  Path to the lattice directory.  [default: .]
  --help                  Show this message and exit.

The motif command

This command starts a container of the EMTO-CPA image and runs computation jobs against the input motif files. Run emto-helper docker motif --help to show its usage.

$ emto-helper docker motif --help
Usage: emto-helper docker motif [OPTIONS]

  Run EMTO-CPA against the input motif files.

Options:
  -l, --lattice-dir TEXT  Path to the lattice directory.  [default: .]
  -m, --motif-dir TEXT    Path to the motif directory.  [default: .]
  --help                  Show this message and exit.

Use cases

This section presents a few use cases of the EMTO Helper CLI.

Create lattice files

Creation of EMTO-CPA lattice files is not as "simple" as that of VASP POSCARs. You have to think of a lattice to be filled by a number of overlapping spheres. These spheres can also be empty spheres! Also they cannot overlap too much because it leads to inaccuracy. Details can be found in this textbook. For the above reason, the EMTO Helper CLI offers a set of pre-defined lattice structures and they are

• b2: B2
• b2m[0:1:5]: used to calculate C44 of B2, epsilon=[0.00:0.01:0.05]
• b2o[0:1:5]: used to calculate (C11-C12) of B2, epsilon=[0.00:0.01:0.05]
• bcc: BCC
• bccm[0:1:5]: used to calculate C44 of BCC, epsilon=[0.00:0.01:0.05]
• bcco[0:1:5]: used to calculate (C11-C12) of BCC, epsilon=[0.00:0.01:0.05]
• fcc: FCC
• fccm[0:1:5]: used to calculate C44 of FCC, epsilon=[0.00:0.01:0.05]
• fcco[0:1:5]: used to calculate (C11-C12) of FCC, epsilon=[0.00:0.01:0.05]
• hcp: HCP
• hcpm[0:1:5]: used to calculate C44 of HCP, epsilon=[0.00:0.01:0.05]
• hcpo[0:1:5]: used to calculate C66 of HCP, epsilon=[0.00:0.01:0.05]
• b2h[00:01:10][00:01:10]: used to calculate bcc to hcp transformation.

For example, to create FCC lattice files and folders, run

emto-helper lattice create -f fcc -o <output-dir>

-o <output-dir> is optional as it defaults to the current working directory. Then, in the output directory, you should see the following directory tree

|____bmdl
   |____mdl
   |____fcc.dat
|____kstr
   |____smx
   |____fcc.dat
|____shape
   |____shp
   |____fcc.dat

Because the EMTO lattice files do not strict the lattice parameters, they can be re-used by different motif files as many times as you want.

Create motif files

To start, run the checkout command in the motif group mentioned in the above. There should be two yaml files in the output: kgrn_overwrite.yaml and meta_overwrite.yaml.

The kgrn_overwrite.yaml file specifies general parameters for EMTO-CPA calculations. The checked out example contains a set of most frequently used parameters.

# number of iterations >50
NITER: 200

# number of CPA iterations
NCPA: 20

# DOS (D), Fermi Surface (S) or none (N)
DOS: "N"

# ferro (F), paramagnetic (P), total fixed spin (M), atom-projected
# fixed spin (m, Fix=Y), and partial DLM (m, Fix=N) calculation
AFM: "F"

# soft core (Y), frozen core (N) or all electron
# with frozen core contribution (Z) calculation
SOFC: "Y"

# control number of k-points along x-axis
NKX: 13

# control number of k-points along y-axis
NKY: 13

# control number of k-points along z-axis
NKZ: 13

# complex energy mesh for the Green's function
# "F" to include the Fermi function
ZMSH: "C"

# energy points for DOS calculation
NZD: 200

# mixing coefficient (0.001-0.050)
AMIX: 0.05

# moment for total fixed spin calculation (AFM=M)
MMOM: 0.0

# Fermi temperature in K (ZMSH=F)
TFERMI: 500.0

# average Wigner-Seitz radius in Bohr units
SWS: 2.66

# SIM parameter for CPA (to be determined from supercell calculation)
ALPCPA: 0.602

SWS is the Wigner-Seitz radius that has a math relation with the lattice parameter, as discussed here.

The meta_overwrite.yaml file specifies motif parameters instead. The checked out file reads

1-[1]:
  # symbol of the element
  Symb: [    Fe,   Fe,   Cr,   Ni]
  # concentration (actually molar fraction)
  CONC: [  0.35, 0.35, 0.15, 0.15]
  # initial splitting <>0 with AFM = F, M
  # local magnetic moment for fixed spin calculation (AMF=m, Fix=Y)
  # for partial or full DLM calculation the two DLM components should
  # have opposite SPLT values (AFM=m, Fix=N)
  # NOTE: for many systems full DLM can also be obtained with AFM=F
  # and two opposite DLM components having 50-50% concentrations
  SPLT: [   1.0, -1.0,  0.0,  0.0]
  # site-projected fixed spin calculation
  Fix:  [   "N",  "N",  "N",  "N"]

In this example, 1-[1] means that sublattice 1 includes lattice point 1. A sublattice can include multiple lattice points e.g. 1-[1,2,3,4] means that sublattice 1 includes all four of lattice points 1, 2, 3, and 4. The sublattice and lattice point indexes can be found in the lattice files. Inside the 1-[1] tag, there are three fields with lists of values:

Here is another example for a B2 structure:

1-[1]:
  Symb: [ Al]
  CONC: [1.0]
  SPLT: [0.0]
2-[2]:
  Symb: [   Co,    Cr,    Ni]
  CONC: [0.333, 0.333, 0.334]
  SPLT: [  1.0,  -1.0,   1.0]

Here is another example for a L12 structure:

1-[1]:
  Symb: [  Cr]
  CONC: [ 1.0]
  SPLT: [-1.0]
2-[2,3,4]:
  Symb: [   Co,    Fe,    Ni]
  CONC: [0.333, 0.333, 0.334]
  SPLT: [  1.0,   1.0,   1.0]

With the input yaml files ready, run

emto-helper motif create \
    <kgrn_overwrite> \
    <meta_overwrite> \
    -f <lattice-family> \
    -r <lattice-root> \
    -o <output-dir>

-r <lattice-root> and -o <output-dir> are optional since they default to the current working directory. The lattice root is where the computed lattice files are.

If you want to perform volumetric relaxation of the crystal structure, run

emto-helper motif create \
    <kgrn_overwrite> \
    <meta_overwrite> \
    -f <lattice-family> \
    -r <lattice-root> \
    -o <output-dir> \
    --relax \
    -d <delta> \
    -s <steps>

The flag --relax tells the CLI that the structure needs to be relaxed. -d specifies the fractional change of the SWS per step, while -s specifies the number of steps for decreasing or increasing the SWS.

Run computation jobs

You are ready to start a container of the EMTO-CPA Docker image and run computation jobs against the input files created above.

Because the container uses a separate file system inside it, so currently you will have to save the lattice AND motif files into the same folder on the local host. That folder is the mounted volume. So, when running emto-helper motif create, -r <lattice-root> has to be set as a relative path.

About magnetism

The kind of magnetism is set through the AFM parameter in kgrn_overwrite.yaml. This parameter has four possible values

• P: Nonmagnetic, forcing magnetic moments of each constituent element to be zero
• F: Ferromagnetic, allowing for free changes in magnetic moments
• m: Local disordered local moment (DLM) approximation
• M: Global DLM approximation

AFM defaults to F.

To mimic paramagnetism, you should use m by default, and create a counterpart for the elements you want to use the DLM for in meta_overwrite.yaml. Counterpart is a pairing element with the same concentration but opposite spin direction. For instance,

1-[1]:
  Symb: [  Fe,   Fe,   Cr,   Ni]
  CONC: [0.35, 0.35, 0.15, 0.15]
  SPLT: [ 1.0, -1.0,  0.0,  0.0]

In this example, iron (Fe) is in the DLM approximation as it's split into two parts with opposite spin directions. The global molar fraction of Fe in this alloy is thus 0.7.

Sometimes, setting AFM to F will also work for DLM. However you should still use m by default as mentioned previously.

About HPC

To compute these input files on HPC you should have compiled EMTO-CPA executables ready. The input files must be computed in the following order.

/path/to/bmdl_executable < /path/to/bmdl/<lattice-type>.dat

/path/to/kstr_executable < /path/to/kstr/<lattice-type>.dat

/path/to/shape_executable < /path/to/shape/<lattice-type>.dat

/path/to/kgrn_executable < /path/to/kgrn/<lattice-type>.dat

/path/to/kfcd_executable < /path/to/kfcd/<lattice-type>.dat