Analysis & plotting

Parsing

To parse the final energies of the geometry optimisations for a specific defect, we can simply run the command snb-parse within the defect folder:

$ snb-parse

Alternatively, we can run from a different directory and specify the defect to parse (as well as other options, see snb-parse -h):

$ snb-parse --defect v_Cd_0 --path defects_folder --code FHI-aims

Where defects_folder is the path to the top level directory containing the defect folder, and is only required if different from the current directory.

Instead of a single defect, we can parse the results for all defects present in a given/current directory using the -a/--all flag:

$ snb-parse -a

This generates a yaml file for each defect, mapping each distortion to the final energy of the relaxed structures (in eV). These files are saved to the corresponding defect directory (e.g. defects_folder/v_Cd_0/v_Cd_0.yaml).

distortions:
    -0.6: -187.70
    -0.3: -187.45
    ...
Unperturbed: -186.70

Analysis

To analyse the structures obtained from the relaxations, we can use snb-analyse. It will generate csv files for a given/all defects with the final energies and structural similarities between the final configurations and a reference one (by default the undistorted one). Structural similarity is measured with two metrics: a) the sum of atomic displacements between matched sites and b) the maximum distance between matched sites. For instance, to analyse the results obtained with VASP for a specific defect, we can simply run the command snb-analyse from within the defect directory:

$ snb-analyse

Again we can alternatively run the command from a different directory and specify which defect to analyse, which code was used (if not VASP) and which reference structure to use (default = Unperturbed):

$ snb-analyse --defect v_Cd_0 --code FHI-aims --path defects_folder --ref_struct -0.4 --verbose

Again if we want to analyse the results for all defects present in a given/current directory, we can use the -a/--all flag:

$ snb-analyse -a

Note

Further analysis tools are provided through the python API. These are documented in the section shakenbreak.analysis and exemplified in the Analysis section of the Python API tutorial.

Plotting

Energy lowering distortions can be quickly identified by plotting the final energies of the relaxed structures versus the distortion factor, using snb-plot. To plot the results obtained with VASP for a specific defect, we can simply run the command snb-plot from within the defect directory:

$ snb-plot

which will generate a figure like the one below:

We can make these plots more informative by adding a colorbar measuring the structural similarity between the structures, using the -cb/--colorbar flag:

$ snb-plot -cb

Again we can alternatively run the command from a different directory and specify which defect to plot, which code was used (if not VASP) and other options (what metric to use for colorbar etc – see snb-plot -h):

$ snb-plot --defect v_Cd_0 --code FHI-aims --path defects_folder --colorbar -0.4 --metric disp --units meV --verbose

Again if we want to plot the results for all defects present in a given/current directory, we can use the -a/--all flag:

$ snb-plot -a

Tip

See snb-plot -h or the CLI docs for details on the options available for this command.

Second round of structure searching

After the defects undergoing energy lowering distortions have been identified, we can test these favourable configurations for the other charge states of the same defect - in case these are favourable for them too and have not been previously identified. By calling snb-regenerate, the code will perform structure comparisons for all defects present in the specified/current directory, to determine which distortions should be tested in other charge states and which have already been found. For the distortions to test, it will generate additional distortion folders with the structure and relaxation input files.

For example, if we have the following directory structure

./
|--- v_Cd_0/ <-- Neutral Cd vacancy
|       |--- Unperturbed
|       |
|       |--- Bond_Distortion_-30.0% <-- Favourable distortion
|       |
|       |--- Bond_Distortion_30.0%
|       | ...
|
|--- v_Cd_-1/ <-- Negatively charged Cd vacancy
        |--- Unperturbed
        | ...
        |--- Bond_Distortion_50% <-- Favourable distortion

and two different energy lowering distortion have been identified for the neutral (with a distortion of -0.3) and for the negatively charged vacancy (with a distortion of 0.5), the code below will ensure that these configurations are indeed different and, if so, generate the input files for both of them.

$ snb-regenerate

As a result, two new distortion folders are generated, with the relaxation input files for the code specified with the flag --code (default = VASP).

./
|--- v_Cd_0/
|       |--- Unperturbed
|       |
|       |--- Bond_Distortion_-30.0% <-- Favourable distortion
|       |
|       |--- Bond_Distortion_30.0%
|       | ...
|       |--- Bond_Distortion_50.0%_from_-1 <-- Distortion from the -1 charge state
|
|--- v_Cd_-1/
        |--- Unperturbed
        | ...
        |--- Bond_Distortion_50% <-- Favourable distortion
        |
        |--- Bond_Distortion_-30.0%_from_0 <-- Distortion from the neutral charge state

Tip

See snb-regenerate -h or the CLI docs for details on the options available for this command.

Saving the ground state structures

Finally, to continue our defect workflow, we want to save the ground state defect structures to continue our calculations with these structures. This can be achieved with the snb-groundstate command, e.g.:

$ snb-groundstate -d vasp_std

This command above will save our ground-state structures to POSCAR files in vasp_std subdirectories of the defect folder(s).

Tip

When using ShakeNBreak with doped for defect calculations, we would typically use -d vasp_nkred_std or -d vasp_std to save our SnB-calculated ground-state structures to POSCAR files in these sub-directories used by default with doped, before continuing with our final fully-converged defect calculations.

The name of the ground state directory and of the structure file can be customised with the --directory (-d) and --groundstate_filename (-gsf) flags, respectively:

$ snb-groundstate --path ./defects_folder --directory Groundstate --groundstate_filename POSCAR

This command will generate a Groundstate directory within each defect folder, e.g.:

./
|--- v_Cd_0/
|       |--- Unperturbed
|       |
|       |--- Bond_Distortion_-30.0%
|       |
|       |--- Bond_Distortion_30.0%
|       | ...
|       |--- Groundstate
|               |--- POSCAR <-- Ground state structure
|
|--- v_Cd_-1/
        |--- Unperturbed
        | ...
        |--- Bond_Distortion_50%
        |
        |--- Groundstate
                |--- POSCAR <-- Ground state structure

Tip

See snb-groundstate -h or the CLI docs for details on the options available for this command.

Further Defect Analysis

Once the ground state (and metastable) defect structures have been identified, we will want to compute their formation energies using our final fully-converged calculation parameters (i.e. plane-wave cutoff and k-point sampling). This can be done using doped, manually (not recommended) or using the other defect codes listed on the Code Compatibility page.

As shown in the doped tutorials and docs, you may want to further analyse the behaviour and impact on material properties of your defects using advanced defect analysis codes such as easyunfold (to analyse the electronic structure of defects in your material), py-sc-fermi (to analyse defect concentrations, doping and Fermi level tuning), or nonrad / `CarrierCapture.jl<https://wmd-group.github.io/CarrierCapture.jl/dev/>`_ (to analyse non-radiative electron-hole recombination at defects).

Note

Metastable structures can also be important to defect behaviour! This is particularly the case for defect/ion migration, electron-hole recombination at defects and non-equilibrium situations such as under illumination or ion bombardment. For example, see these papers on the impact of metastable defects in CdTe: ACS Energy Lett. 2021, 6, 4, 1392–1398 and Faraday Discuss. 2022, 239, 339-356.

In particular, symmetry-breaking as a result of structural reconstruction from the initial (Unperturbed) high-symmetry structure can result in an increase in configurational degeneracy for the defect, which should be accounted for when later computing concentrations and Fermi level position. These considerations, as well as the importance of metastability and temperature effects for the free energies (and thus concentrations) for certain defects/systems are discussed in this Tutorial Review paper: Imperfections are not 0 K: free energy of point defects in crystals (Chem Soc Rev 2023).