{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Setting up the notebook to run calculations\n",
    "\n",
    "\n",
    "The classes and functions required to run the calculation in a Jupyter notebook are imported from the source code, along with numpy, pandas and matplotlib."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from pyscses.defect_species import DefectSpecies\n",
    "from pyscses.set_of_sites import SetOfSites\n",
    "from pyscses.constants import boltzmann_eV\n",
    "from pyscses.calculation import Calculation, calculate_activation_energies\n",
    "from pyscses.set_up_calculation import calculate_grid_offsets\n",
    "from pyscses.grid import Grid\n",
    "\n",
    "import numpy as np\n",
    "import pandas as pd\n",
    "import matplotlib.pyplot as plt\n",
    "%matplotlib inline"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Defining the model\n",
    "\n",
    "The approximations that are to be applied to the calculation are defined.\n",
    "\n",
    "```boundary_conditions``` - Either ```'dirichlet'``` where the boundaries of the calculation are fixed to 0.0, or ```'periodic'``` where the boundaries of the calculation are equivalent. \n",
    "\n",
    "```site_charges``` - Either ```False``` where only the charge of the defect species is considered or ```True``` where the charge of all species is considered.\n",
    "\n",
    "```systems``` - Either ```'mott-schottky'``` where certain defect species are considered immobile and are fixed to their bulk defect distribution or ```'gouy-chapman'``` where all defect species are considered mobile and are able to redistribute.\n",
    "\n",
    "```core_models``` - Either ```'single'```, where the core is considered using a single segregation energy at the center of the grain boundary. ```'multi-site'```, where the core is divided into layers with fixed segregation energies, when the segregation energy of a site is less that $k_BT$ or greater than $-k_BT$, the segregation energy is fixed to 0.0. Or ```False```, where all segregation energies are considered. \n",
    "\n",
    "```site_models``` - Either ```'site_explicit```, where all sites are considered at their lattice positions or ```continuum``` where the segregation energies are interpolated onto a regular grid."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "boundary_conditions = 'dirichlet'\n",
    "site_charges = False\n",
    "systems = 'gouy-chapman'\n",
    "core_models = False\n",
    "site_models = 'continuum'"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Defining variables\n",
    "The variables that the calculation requires are defined.\n",
    "\n",
    "```alpha``` - is a damping parameter used to damp the updates to the potential during every iteration to help convergence and numerical stability.\n",
    "\n",
    "```conv``` -  is the convergence limit that the difference between the calculated potential and the damped potential must be before convergence is accepted. \n",
    "\n",
    "```grid_x_min / grid_x_max``` - define the region either side of the grain boundary that will be included in the calculation.\n",
    "\n",
    "```bulk_x_min / bulk_x_max ``` - define a region of bulk which can be used to calculate bulk properties\n",
    "\n",
    "```dielectric``` - The relative permittivity of the material. In this case Gd-doped CeO2.\n",
    "\n",
    "```index``` - The grain boundary orientation selected for the calculation.\n",
    "\n",
    "```b / c``` - The width and height of the cell used in the atomistic simulation when defect segreagtion energies were calculated. Specific to the grain boundary orientation.\n",
    "\n",
    "```temp``` - Temperature (K)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "alpha = 0.0005\n",
    "\n",
    "conv = 1e-8\n",
    "grid_x_min = -2.0e-8\n",
    "grid_x_max = +2.0e-8\n",
    "bulk_x_min = -2.0e-8\n",
    "bulk_x_max = -1.0e-8\n",
    "\n",
    "dielectric = 1\n",
    "\n",
    "index = 111\n",
    "\n",
    "b = 5e-9\n",
    "c = 5e-9\n",
    "\n",
    "temp = [773.15]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Defining system specific constants.\n",
    "\n",
    "The code that is imported calculates the grain boundary properties for any system. In the cell below the properties for a given system are defined. \n",
    "\n",
    "```valence``` - defect charge\n",
    "\n",
    "```site_labels``` - ```site_1``` / ```site_2``` - labels defining the species that would be occupying the site in the pure material\n",
    "\n",
    "```defect_labels``` - ```defect_1``` / ```defect_2``` - labels defining the defect species occupying the site in the defective material\n",
    "\n",
    "```mole_fractions``` - the bulk mole fractions of the defect species\n",
    "\n",
    "```initial_guess``` - an initial guess for the bulk defect mole fractions, used in a minimisation to correct the output mole fractions when ```gouy_chapman``` conditions are applied. \n",
    "\n",
    "The values must be input in the order [ mobile defect property, immobile defect property ].\n",
    "\n",
    "#### Example\n",
    "To demonstrate how the system specific constants would be implemented using real data an example system of gadolinium doped ceria is shown.\n",
    "\n",
    "```python\n",
    "valence = [ +2.0, -1.0 ]\n",
    "site labels = [ 'O', 'Ce' ]\n",
    "defect_labels = [ 'Vo', 'Gd' ]\n",
    "mole_fractions = [ [ 0.05, 0.2 ] ]\n",
    "initial_guess = [ [ 0.05, 0.2 ] ]\n",
    "```\n",
    "\n",
    "However for the purpose of this example notebook we are not using any particular system. The site labels are defined as site_1/site_2 and the defect labels are defined as defect_1/defect_2 with equal but opposite valence and equal mole fractions."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "valence = [ +1.0, -1.0 ]\n",
    "site_labels = ['site_1', 'site_2']\n",
    "defect_labels = ['defect_1', 'defect_2']\n",
    "mole_fractions = [ [ 0.2, 0.2 ] ]\n",
    "initial_guess = [ [ 0.2, 0.2 ] ]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Input data\n",
    "\n",
    "The path to the data file is defined and stored in ```data```."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "data = '../input_data/example_data_2_one_seg_energies.txt'"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The input for the solver is a .txt file where each line in the file corresponds to a different site.\n",
    "\n",
    "Each line in the .txt file needs to be a string containing the following information:\n",
    "\n",
    "**Site label** - site_1 / site_2 - A label defining the species that would be occupying the site in pure ceria. \n",
    "\n",
    "**Site charge** - The charge of the non-defective site species.\n",
    "\n",
    "**$x$ coordinate** - float - The x coordinate for the position of the site.\n",
    "\n",
    "**Defect label** - defect_1 / defect_2 -  A label defining the defect species occupying the site.\n",
    "\n",
    "**Segregation energy** The defect segregation energy for that defect occupying that site.\n",
    "\n",
    "For example:\n",
    "\n",
    "```\n",
    "site_2   +1.0   -2e-09    defect_2    0.0\n",
    "site_1   -1.0   -2e-09    defect_1    0.0\n",
    "site_2   +1.0   -1e-09    defect_2    0.0\n",
    "site_1   -1.0   -1e-09    defect_1    0.0\n",
    "site_2   +1.0    0.0      defect_2    0.0\n",
    "site_1   -1.0    0.0      defect_1   -1.0\n",
    "site_1   +1.0    1e-09    defect_1    0.0\n",
    "site_2   -1.0    1e-09    defect_2    0.0\n",
    "site_1   +1.0    2e-09    defect_1    0.0\n",
    "site_2   -1.0    2e-09    defect_2    0.0\n",
    "```\n",
    "\n",
    "In this example system, each $x$ coordinate on a regularly spaced grid (-50 nm to +50 nm with 1 nm spacings) has one positively charged defect (```defect_one```) and one negatively charged defect (```defect_2```). These defects are equal and opposite in their valence and therefore the system is charge neutral. For simplicity, all of the defects have a segregation energy of zero, except the central positively charged defect which has a segregation energy of -1.0 eV."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 2",
   "language": "python",
   "name": "python2"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 2
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython2",
   "version": "2.7.15"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}