docs/source/content/formation-energy.ipynb

{
 "cells": [
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Formation Energy Diagrams\n",
    "\n",
    "The formation energy diagram is perhaps the most important tool in analyzing the defect properties.\n",
    "It informs both the likelihood of a defect forming and the transition level where the charge state of the defect changes.\n",
    "\n",
    "The formation energy of a defect is determined by the chemical potential of everything that goes into forming the defect.\n",
    "While all of the different chemical potentials are interconnected, it is conceptually easier to separate them into two groups: the chemical potential of the elements and the chemical potential of the electron.\n",
    "The chemical potential of the electron often called the *Fermi level*, accounts for how all of the external conditions, including the presence of other defects, affect the thermodynamics of adding or removing an electron from the defect.\n",
    "Since the electrons in the system can be manipulated after the defect is formed, the *Fermi level* is often considered a free variable and is shown as the x-axis in the formation energy diagram.\n",
    "The chemical potentials of the different atoms added or removed to form the defect are less dynamic and assumed to be fixed after the defect is formed.\n",
    "\n",
    "The expression for the formation energy of a defect is given by:\n",
    "\n",
    "$$E^f[X^q] = E_{\\rm tot}[X^q] - E_{\\rm tot}[{\\rm bulk}] + \\sum_i n_i \\mu_i + qE_{\\rm F} + \\Delta^q \\, ,$$\n",
    "\n",
    "where $E^f[X^q]$ is the formation energy of the defect, $E_{\\rm tot}[X^q]$ is the total energy of the defect, $E_{\\rm tot}[{\\rm bulk}]$ is the total energy of the bulk, $n_i$ is the number of atoms of type $i$ in the defect, $\\mu_i$ is the chemical potential of atom type $i$, $q$ is the charge of the defect, $E_{\\rm F}$ is the Fermi level, and $\\Delta^q$ is finite-size correction which we have to add to account for image effects of simulating the defect in a periodic simulation cell.\n",
    "\n",
    "A schematic of the formation energy diagram for the $q=0$ and $q=-1$ charge states of a hypothetical defect is shown below.\n",
    "\n",
    "\n",
    "<img src=\"https://raw.githubusercontent.com/materialsproject/pymatgen-analysis-defects/main/docs/source/_static/img/formation_schematic.png\" width=\"300\"/>\n"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Defining a Formation Energy Diagram\n",
    "\n",
    "The class responsible for analyzing the formation energy is described by the following fields.\n",
    "\n",
    "```python\n",
    "FormationEnergyDiagram(\n",
    "    bulk_entry: 'ComputedStructureEntry',\n",
    "    defect_entries: 'List[DefectEntry]',\n",
    "    pd_entries: 'list[ComputedEntry]',\n",
    "    vbm: 'float',\n",
    "    band_gap: 'Optional[float]' = None,\n",
    "    inc_inf_values: 'bool' = False,\n",
    ")\n",
    "```\n",
    "\n",
    "<div class=\"alert alert-block alert-info\"><b>Note:</b> For now, the bulk entry and all the defect entries need to have the exact same supercell shape.\n",
    "</div>\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import warnings\n",
    "\n",
    "from monty.serialization import loadfn\n",
    "from pymatgen.analysis.defects.thermo import FormationEnergyDiagram\n",
    "\n",
    "warnings.filterwarnings(\"ignore\")\n",
    "\n",
    "from pathlib import Path\n",
    "\n",
    "from pymatgen.analysis.defects.core import Substitution\n",
    "from pymatgen.core import PeriodicSite, Species, Structure\n",
    "\n",
    "TEST_FILES = Path(\"../../../tests/test_files\")\n",
    "\n",
    "gan_struct = Structure.from_file(TEST_FILES / \"GaN.vasp\")\n",
    "# make a substitution site\n",
    "ga_site = gan_struct[0]\n",
    "mg_site = PeriodicSite(\n",
    "    species=Species(\"Mg\"), coords=ga_site.frac_coords, lattice=gan_struct.lattice\n",
    ")\n",
    "# instantiate the defect object\n",
    "mg_ga = Substitution(structure=gan_struct, site=mg_site)\n",
    "\n",
    "sc_dir = TEST_FILES / \"Mg_Ga\"\n",
    "# ents = MPRester().get_entries_in_chemsys(\"Mg-Ga-N\") # Query from MPRester\n",
    "ents = loadfn(TEST_FILES / \"Ga_Mg_N.json\")  # Load from local\n",
    "fed = FormationEnergyDiagram.with_directories(\n",
    "    directory_map={\n",
    "        \"bulk\": sc_dir / \"bulk_sc\",\n",
    "        0: sc_dir / \"q=0\",\n",
    "        -1: sc_dir / \"q=-1\",\n",
    "        1: sc_dir / \"q=1\",\n",
    "    },\n",
    "    defect=mg_ga,\n",
    "    pd_entries=ents,\n",
    "    dielectric=10,\n",
    ")"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Getting the Elemental Chemical Potentials\n",
    "\n",
    "All of the chemical potentials are, in principle, free variables that indicate the conditions of the surrounding environment while the defect is formed.\n",
    "These free variables are bound by the enthalpies of formation of the various compounds that share the same elements as the defect and bulk material.\n",
    "These competing compounds essentially establish the boundaries of the allowed chemical potentials, while the VBM and CBM of the bulk material determine the allowed range of the Fermi level.\n",
    "As such, first-principles calculations can be used to determine the limits of the various chemical potentials. \n",
    "As an example, the elemental chemical potentials for the Mg$_{\\rm Ga}$ defect in GaN are shown below:\n",
    "\n",
    "$$\n",
    "\\begin{aligned}\n",
    "\\Delta\\mu_{\\rm Ga} + \\Delta\\mu_{\\rm N} &= \\Delta H_{\\rm GaN} \\\\\n",
    "5\\Delta\\mu_{\\rm Mg} + 2\\Delta\\mu_{\\rm Ga} + \\Delta\\mu_{\\rm N} &\\leq \\Delta H_{\\rm Mg_5Ga_2} \\\\\n",
    "3\\Delta\\mu_{\\rm Mg} + 2\\Delta\\mu_{\\rm N} &\\leq \\Delta H_{\\rm Mg_3N_2} \\\\\n",
    "\\end{aligned}\n",
    "$$\n",
    "\n",
    "Here since the defect must form in GaN the chemical potentials are pinned by the plane defined by the enthalpy of formation of GaN.\n",
    "The limits imposed by the competing compounds are shown by the additional inequalities.\n",
    "The points of interest are usually vertex points in the constrained chemical potential space so we report the full set of vertex points in `FormationEnergyDiagram.chempot_limits`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "for _i, p in enumerate(fed.chempot_limits):\n",
    "    for _k, _v in p.items():\n",
    "        pass"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Finite-size corrections\n",
    "\n",
    "Finite-size corrections are necessary to account for the fact that we are simulating a charged defect in a periodic simulation cell.\n",
    "The standard approach was developed by Freysoldt and co-workers and is described in the following paper:\n",
    "\n",
    "{cite:p}`Freysoldt2009Jan`.\n",
    "\n",
    "> Freysoldt, C., Neugebauer, J., & Van de Walle, C. G. (2009). Fully Ab Initio Finite-Size Corrections for Charged-Defect Supercell Calculations. Phys Rev Lett, 102(1), 016402. doi: 10.1103/PhysRevLett.102.016402\n",
    "\n",
    "This method requires calculating the the long range term from the Coulomb interaction and a short range term from the electrostatic potential in the `LOCPOT` file.\n",
    "While the final result of the finite-size correction is just a single number $\\Delta^q$ for each charge state, the intermediate results can still be analyzed.\n",
    "This is still useful, since the defect position is automatically determined from the `LOCPOT` files alone, to check the planar-averaged potential plots to make sure that the defect is indeed in the correct position.\n",
    "This will be evident if the planar-averaged potential difference is peaked at the two ends of the plot since the automatically determined defect position is chosen as the origin of the plot.\n",
    "The short range contribution is set to zero far away from the defect, which is accomplished by average the planar electrostatic potential far away from the defect in the `sampling region` shown below.\n",
    "The intermediate analysis (planar-averaged potentials) for calculating the Freysoldt correction for each of the the three lattice directions is shown below.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from pymatgen.analysis.defects.corrections.freysoldt import plot_plnr_avg\n",
    "\n",
    "plot_data = fed.defect_entries[1].corrections_metadata[\"freysoldt\"][\"plot_data\"]\n",
    "plot_plnr_avg(plot_data[0], title=\"Lattice Direction 1\")\n",
    "plot_plnr_avg(plot_data[1], title=\"Lattice Direction 2\")\n",
    "plot_plnr_avg(plot_data[2], title=\"Lattice Direction 3\")"
   ]
  }
 ],
 "metadata": {
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.9.16"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}