{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Introduction\n",
    "\n",
    "This notebook demonstrates how to predict likely n- and p-type dopant atoms using pymatgen. This example uses the Materials API to download the structure of interest but any `Structure` object can be used. Two methods for choosing dopants are demonstrated. The first uses a simple Shannon radii comparison, whereas the second is based on the substitution probability of two atoms calculated using the `SubstitutionPredictor` utility in pymatgen. This code requires knowledge of the oxidation state of all elements in the structure. These can be guessed using pymatgen but should be checked to ensure the validity of the results.\n",
    "\n",
    "*Author: Alex Ganose (10/06/18)*"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Uncomment the subsequent lines in this cell to install dependencies for Google Colab.\n",
    "# !pip install pymatgen==2022.7.19"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Imports we need for generating dopant suggestions\n",
    "from __future__ import annotations\n",
    "\n",
    "from pprint import pprint\n",
    "\n",
    "from pymatgen.analysis.local_env import CrystalNN\n",
    "from pymatgen.analysis.structure_prediction.dopant_predictor import (\n",
    "    get_dopants_from_shannon_radii,\n",
    "    get_dopants_from_substitution_probabilities,\n",
    ")\n",
    "from pymatgen.ext.matproj import MPRester"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Establish rester for accessing Materials API\n",
    "\n",
    "api_key = None  # INSERT YOUR OWN API KEY\n",
    "\n",
    "mpr = MPRester()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Here we define a variable -- `num_dopants` for how many dopants you wish to explore."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "num_dopants = 5  # number of highest probability dopants you wish to see"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Download a structure and add oxidation states\n",
    "\n",
    "In this section, we use the Materials API to download a structure and add information on the oxidation states of the atoms."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "application/vnd.jupyter.widget-view+json": {
       "model_id": "6824bbbb8edf4c28a90729fb01f910c7",
       "version_major": 2,
       "version_minor": 0
      },
      "text/plain": [
       "Retrieving MaterialsDoc documents:   0%|          | 0/1 [00:00<?, ?it/s]"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "mp_id = \"mp-856\"  # Materials Project id for rutile SnO2\n",
    "\n",
    "structure = mpr.get_structure_by_material_id(mp_id)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The downloaded structure does not contain oxidation state information. There are two ways to add this information. The first is to specify the oxidation state of the elements manually."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "Structure Summary\n",
       "Lattice\n",
       "    abc : 3.20749977 4.76383605 4.76580004\n",
       " angles : 90.0 90.0 90.0\n",
       " volume : 72.82143907393863\n",
       "      A : 3.20749977 0.0 0.0\n",
       "      B : 0.0 4.76383605 -0.0\n",
       "      C : 0.0 -0.0 4.76580004\n",
       "    pbc : True True True\n",
       "PeriodicSite: Sn (Sn4+) (1.604, 2.382, 2.383) [0.5, 0.5, 0.5]\n",
       "PeriodicSite: Sn (Sn4+) (0.0, 0.0, 0.0) [0.0, -0.0, 0.0]\n",
       "PeriodicSite: O (O2-) (1.604, 0.9252, 3.842) [0.5, 0.1942, 0.8062]\n",
       "PeriodicSite: O (O2-) (1.604, 3.839, 0.9238) [0.5, 0.8058, 0.1938]\n",
       "PeriodicSite: O (O2-) (0.0, 1.457, 1.459) [-0.0, 0.3058, 0.3062]\n",
       "PeriodicSite: O (O2-) (0.0, 3.307, 3.307) [-0.0, 0.6942, 0.6938]"
      ]
     },
     "execution_count": null,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "structure.add_oxidation_state_by_element({\"Sn\": 4, \"O\": -2})"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Alternatively, we can use pymatgen to guess the oxidation states. If using this method you should check that the oxidation states are what you expect."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "Structure Summary\n",
       "Lattice\n",
       "    abc : 3.20749977 4.76383605 4.76580004\n",
       " angles : 90.0 90.0 90.0\n",
       " volume : 72.82143907393863\n",
       "      A : 3.20749977 0.0 0.0\n",
       "      B : 0.0 4.76383605 -0.0\n",
       "      C : 0.0 -0.0 4.76580004\n",
       "    pbc : True True True\n",
       "PeriodicSite: Sn (Sn4+) (1.604, 2.382, 2.383) [0.5, 0.5, 0.5]\n",
       "PeriodicSite: Sn (Sn4+) (0.0, 0.0, 0.0) [0.0, -0.0, 0.0]\n",
       "PeriodicSite: O (O2-) (1.604, 0.9252, 3.842) [0.5, 0.1942, 0.8062]\n",
       "PeriodicSite: O (O2-) (1.604, 3.839, 0.9238) [0.5, 0.8058, 0.1938]\n",
       "PeriodicSite: O (O2-) (0.0, 1.457, 1.459) [-0.0, 0.3058, 0.3062]\n",
       "PeriodicSite: O (O2-) (0.0, 3.307, 3.307) [-0.0, 0.6942, 0.6938]"
      ]
     },
     "execution_count": null,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "structure.add_oxidation_state_by_guess()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Let's check what oxidation states pymatgen guessed."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "[Species Sn4+, Species O2-]\n"
     ]
    }
   ],
   "source": [
    "species = structure.composition.elements\n",
    "\n",
    "print(species)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Finding dopants by Shannon radii\n",
    "\n",
    "In this section, we use the known Shannon radii to predict likely dopants. We will prefer dopants which have the smallest difference in radius to the host atoms. As the Shannon radii depend on the coordination number of the site, we must first calculate the bonding in the structure. In this example, we do this using the `CrystalNN` class."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "cnn = CrystalNN()\n",
    "bonded_structure = cnn.get_bonded_structure(structure)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Pymatgen has a function to take a bonded structure with oxidation states and report the closest n- and p-type dopants, sorted by the difference in Shannon radii. Let's run this on our bonded structure:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "{'n_type': [{'dopant_species': Species U6+,\n",
      "             'original_species': Species Sn4+,\n",
      "             'radii_diff': 0.040000000000000036},\n",
      "            {'dopant_species': Species Nb5+,\n",
      "             'original_species': Species Sn4+,\n",
      "             'radii_diff': -0.04999999999999993},\n",
      "            {'dopant_species': Species Ta5+,\n",
      "             'original_species': Species Sn4+,\n",
      "             'radii_diff': -0.04999999999999993},\n",
      "            {'dopant_species': Species F-,\n",
      "             'original_species': Species O2-,\n",
      "             'radii_diff': -0.06000000000000005},\n",
      "            {'dopant_species': Species Np5+,\n",
      "             'original_species': Species Sn4+,\n",
      "             'radii_diff': 0.06000000000000005}],\n",
      " 'p_type': [{'dopant_species': Species Ni2+,\n",
      "             'original_species': Species Sn4+,\n",
      "             'radii_diff': 0.0},\n",
      "            {'dopant_species': Species Ru3+,\n",
      "             'original_species': Species Sn4+,\n",
      "             'radii_diff': -0.009999999999999898},\n",
      "            {'dopant_species': Species Ir3+,\n",
      "             'original_species': Species Sn4+,\n",
      "             'radii_diff': -0.009999999999999898},\n",
      "            {'dopant_species': Species Rh3+,\n",
      "             'original_species': Species Sn4+,\n",
      "             'radii_diff': -0.02499999999999991},\n",
      "            {'dopant_species': Species Mg2+,\n",
      "             'original_species': Species Sn4+,\n",
      "             'radii_diff': 0.030000000000000027}]}\n"
     ]
    }
   ],
   "source": [
    "dopants = get_dopants_from_shannon_radii(bonded_structure, num_dopants=num_dopants)\n",
    "\n",
    "pprint(dopants)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The most favoured n-type dopant is U on a Sn site. Unfortunately, this is not a sustainable or safe choice of dopant. The most common industrial n-type dopant for SnO2 is fluorine. While F is present in our list of suggested dopants, it found way down at suggestion number 4.\n",
    "\n",
    "Another limitation of the Shannon radii approach to choosing dopants is that the radii depend on both the coordination number and charge state. For many elements, the radii for many charge state/coordination number combinations have not been tabulated, meaning this approach is incomplete.\n",
    "\n",
    "Instead we should use a more robust approach to determine possible dopants. "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Finding dopants by substitution probability\n",
    "\n",
    "In this section, we use the statistics provided by `SubstitutionPredictor` to predict likely dopants substitutions using a data-mined approach from ICSD data. Based on the species in the structure, we get a list of which species are likely to substitute in but have different charge states. The substitution prediction methodology is presented in: \n",
    "*Hautier, G., Fischer, C., Ehrlacher, V., Jain, A., and Ceder, G. (2011) Data Mined Ionic Substitutions for the Discovery of New Compounds. Inorganic Chemistry, 50(2), 656-663. doi:10.1021/ic102031h*"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Here, we define a variable -- `threshold` for the threshold probability in making substitution/structure predictions."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "threshold = 0.001  # probability threshold for substitution/structure predictions"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Pymatgen provides a function to filter the predicted substitutions by their charge states and return a list of n- and p-type dopants. Let's run the function on the structure we downloaded earlier:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "{'n_type': [{'dopant_species': Species F-,\n",
      "             'original_species': Species O2-,\n",
      "             'probability': 0.06692682583342514},\n",
      "            {'dopant_species': Species Cl-,\n",
      "             'original_species': Species O2-,\n",
      "             'probability': 0.02102263828843219},\n",
      "            {'dopant_species': Species Ta5+,\n",
      "             'original_species': Species Sn4+,\n",
      "             'probability': 0.019486221245908535},\n",
      "            {'dopant_species': Species Sb5+,\n",
      "             'original_species': Species Sn4+,\n",
      "             'probability': 0.010380692735493776},\n",
      "            {'dopant_species': Species Nb5+,\n",
      "             'original_species': Species Sn4+,\n",
      "             'probability': 0.009988531781437172}],\n",
      " 'p_type': [{'dopant_species': Species Co2+,\n",
      "             'original_species': Species Sn4+,\n",
      "             'probability': 0.023398867249112977},\n",
      "            {'dopant_species': Species Cd2+,\n",
      "             'original_species': Species Sn4+,\n",
      "             'probability': 0.022644061067779386},\n",
      "            {'dopant_species': Species Li+,\n",
      "             'original_species': Species Sn4+,\n",
      "             'probability': 0.0223941018301471},\n",
      "            {'dopant_species': Species Fe2+,\n",
      "             'original_species': Species Sn4+,\n",
      "             'probability': 0.02097177766283143},\n",
      "            {'dopant_species': Species Ca2+,\n",
      "             'original_species': Species Sn4+,\n",
      "             'probability': 0.01948719558132902}]}\n"
     ]
    }
   ],
   "source": [
    "dopants = get_dopants_from_substitution_probabilities(\n",
    "    structure, num_dopants=num_dopants, threshold=threshold\n",
    ")\n",
    "\n",
    "pprint(dopants)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The function returns a list of potential dopants sorted by their substitution probability. The most likely n-type dopant is F on a O site. Fluorine doped SnO2 (FTO) is one of the most widely used transparent conducting oxides, therefore validating this approach."
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "language": "python",
   "name": "python3"
  },
  "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.11.5"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}