CLI tutorial

Inputs

py-sc-fermi features a command line tool for calculating self consistent Fermi energies. In this case defect system is defined by a .yaml file structured like so:

bandgap: 1 # replace with your calculated bandgap
temperature: 300 # the temperature to be used in the solution for Fermi energy
nelect: 18 # number of electrons in the density of states calculation carried out on the unit cell
defect_species:
  - V_Na: # name of first defect species
      nsites: 1 # site degeneracy of the defect species
      charge_states:
        0: # charge of first charge state
          charge: 0
          formation_energy: 2 # formation energy of first charge state
          degeneracy: 1 # degeneracy of first charge state
        -1:
          charge: -1
          formation_energy: 1
          degeneracy: 2
  ... # repeat for each defect in your system

The dimension of the unit cell can be given within a .cif file (or a number of other common structure files), or as a file which is structured as:

# scaling factor for lattice vector components
1 0.0 0.0
0 4.1 0.0
0 0.0 4.1

where the matrix above defines the lattice vector of the unit cell. Alternatively, we can skip the definition of the full unit cell, and simply include volume: x (where x is the unit cell volume) in the .yaml file described above.

The density of states can either be specified in the .yaml file as:

...
edos: [energy values of the dos]
dos: [array of total dos values]
...

or the density of states can be read directly from a vasprun.xml file.

sc_fermi_solve

the command to solve for the self consistent Fermi energy once you have specifed the inputs as above is sc_fermi_solve [input .yaml]. If the .yaml file specifies the volume and dos information for your system, this is all you need to do. Otherwise, there are some additional arguments accepted by this command:

-s, --structure_file path to the structure file which defines the volume of the unit cell

-d, --dos_file path to the file which defines the dos

if this argument is specified, you must also specify -b, --band_gap which gives the bulk band-gap of the system.

frozen-concentration defects

You are able to specify the concentrations of different defects in the solver, just as with the API. In this case, you may either fix the concentration of the defect species by specifying e.g:

defect_species:
    - V_Na:
        fixed_concentration: 1e20
        ...

and specify the concentration of a defect charge state like so:

defect_species:
- V_Na:
    nsites: 1
    charge_states:
        -1:
            charge: -1
            formation_energy: 1
            fixed_concentration: 1e20
            degeneracy: 1
...

within the input .yaml file. If you do so, you must add the flag -f or --frozen_defects when you call sc_fermi_solve.