Merge 0732214 into be94ea9

CHANGELOG.md

@@ -0,0 +1,8 @@
+All notable changes to this project will be documented in the file.
+
+30 September 2020
+
+- Data is no longer stored in dictionaries. A new `surfinpy.data` module has been developed to store the information from ab initio calculations. 
+- `surfinpy.bulk_mu_vs_mu` and `surfinpy.bulk_mu_vs_t` have been added to allow phase diagrams of bulk phases to be generated.
+- `surfinpy.vibrational_data` has been added to allow the vibrational entropy and zero point energy to be calculated and added to the phase diagrams. 
+- `surfinpy.plotting` has been added and `surfinpy.chemical_potential_plot` and `surfinpy.pvt_plot` have been moved here. 

PULL_REQUEST_TEMPLATE.md

@@ -1,3 +1,3 @@
 We aspire to deal with all pull requests in a timely manner. Please be patient.
 
-Ideally pull requests will respect the underlying intrastructure of surfinpy and agree with PEP8, etc. However, please do not let this put novice programmers off contributing as we will do everything we can to help.
+Ideally pull requests will respect the underlying intrastructure of surfinpy and agree with PEP8, etc. However, please do not let this put novice programmers off contributing as we will do everything we can to help. 

README.md

@@ -12,7 +12,7 @@
 <a href='https://coveralls.io/github/symmy596/SurfinPy?branch=master'><img src='https://coveralls.io/repos/github/symmy596/SurfinPy/badge.svg?branch=master' alt='Coverage Status' /></a>
 <a href='https://gitter.im/Surfinpy/Lobby'>
 <img src='https://badges.gitter.im/gitterHQ/gitter.png' alt='Gitter chat' /></a>
-
+ 
 This is the documentation for the open-source Python project - `surfinpy`.
 A library designed to facilitate the generation of publication ready phase diagrams from ab initio calculations for both surface and bulk materials.
 surfinpy is built on existing Python packages that those in the solid state physics/chemistry community should already be familiar with. 
@@ -125,6 +125,13 @@ workflow while core developers use branches in the main repository:
 
 For further information please contact Adam Symington, ars44@bath.ac.uk
 
+## Research
+
+- [Strongly Bound Surface Water Affects the Shape Evolution of Cerium Oxide Nanoparticles](https://pubs.acs.org/doi/abs/10.1021/acs.jpcc.9b09046)
+- [The energetics of carbonated PuO2 surfaces affects nanoparticle morphology: a DFT+U study](https://pubs.rsc.org/lv/content/articlelanding/2020/cp/d0cp00021c/unauth#!divAbstract)
+
+- [Exploiting cationic vacancies for increased energy densities in dual-ion batteries](https://www.sciencedirect.com/science/article/abs/pii/S2405829719310153)
+
 ## Author
 
 * Adam R.Symington

appveyor.yml

@@ -0,0 +1,33 @@
+environment:
+  matrix:
+
+    # For Python versions available on Appveyor, see
+    # http://www.appveyor.com/docs/installed-software#python
+    # The list here is complete (excluding Python 2.6, which
+    # isn't covered by this document) at the time of writing.
+
+    - PYTHON: "C:\\Python36-x64"
+      MINICONDA: "C:\\Miniconda"
+    - PYTHON: "C:\\Python37-x64"
+      MINICONDA: "C:\\Miniconda"
+    - PYTHON: "C:\\Python38-x64"
+      MINICONDA: "C:\\Miniconda"
+
+install:
+  # We need wheel installed to build wheels
+  - "SET PATH=%MINICONDA%;%MINICONDA%\\Scripts;%PATH%"
+  - "%PYTHON%\\python.exe -m pip install -U twine wheel setuptools"
+  - "%PYTHON%\\python.exe -m pip install -r requirements.txt"
+  - "set PATH=%PATH%;C:\"%PYTHON%\\Scripts"
+
+build: off
+
+test_script:
+  # Put your test command here.
+  # If you don't need to build C extensions on 64-bit Python 3.3 or 3.4,
+  # you can remove "build.cmd" from the front of the command, as it's
+  # only needed to support those cases.
+  # Note that you must use the environment variable %PYTHON% to refer to
+  # the interpreter you're using - Appveyor does not do anything special
+  # to put the Python version you want to use on PATH.
+  - "%PYTHON%\\python.exe setup.py test"

docs/source/README.rst

@@ -12,38 +12,51 @@
     :alt: Build Status
 
 This is the documentation for the open-source Python project, `surfinpy`.
-A library designed to facilitate the generation of publication ready surface phase diagrams from ab initio calculations.
+A library designed to facilitate the generation of publication ready phase diagrams from ab initio calculations.
 `surfinpy` is built on existing Python packages that those in the solid state physics/chemistry community should already be familiar with. 
 It is hoped that this tool will bring some benfits to the solid state community and facilitate the generation of publication ready phase diagrams (powered by Matplotlib.)
 
 The main features include:
 
-1. **Method to generate 2D surface phase diagrams as a function of chemical potential.**  
-   
-   - Generate a diagram for two adsorbing species e.g. water and carbon dioxide.  
-   - Generate a diagram for an adsorbing species and a surface species e.g. water and oxygen vacancies.  
+1. **Method to generate surface phase diagrams as a function of chemical potential.**  
+
+   - Generate a diagram as a function of the chemical potential of two adsorbing species e.g. water and carbon dioxide.  
+   - Generate a diagram as a function of the chemical potential of one adsorbing species and a surface species e.g. water and oxygen vacancies.  
    - Use experimental data combined with ab initio data to generate a temperature dependent phase diagram.  
 
-2. **Method to generate 2D surface phase diagrams as a function of temperature and pressure.**  
-
-   - Use experimental data combined with ab initio data to generate a pvt plot showing the state of a surface.   
+2. **Method to generate surface phase diagrams as a function of temperature and pressure.**  
+
+   - Use experimental data combined with ab initio data to generate a pressure vs temperature plot showing the state of a surface as a function of temperature and pressure of one species.
+
+3. **Use calculated surface energies to built crystal morphologies.**  
 
-3. **Use calculated surface energies to build crystal morphologies.**  
-
    - Use the surface energies produced by `surfinpy` alongside Pymatgen to built particle morphologies.  
-   - Evaulate how a particles shape changes with temperature and pressure.   
+   - Evaulate how a particles shape changes with temperature and pressure.
+
+4. **Method to generate bulk phase diagrams as a function of chemical potential.**  
+
+   - Generate a diagram as a function of the chemical potential of two species e.g. water and carbon dioxide.  
+   - Use experimental data combined with ab initio data to generate a temperature dependent phase diagram.  
+
+5. **Method to generate 2D surface phase diagrams as a function of temperature and pressure.**  
+
+   - Use experimental data combined with ab initio data to generate a pressure vs temperature plot showing the phase space as a function of temperature and pressure.  
+
+6. **Method to include vibrational properties in a phase diagram**
+
+   - Module to calculate the zero point energy and vibrational entropy
+   - Encorporate the zero point energy and/or the vibrational entropy into a phase diagram.
 
-The code has been developed to analyse VASP calculations however should in theory be compatible with other ab initio codes. 
-`surfinpy` was developed during a PhD project and as such the functionality focuses on the research questions encountered during that project, which we should clarify 
+The code has been developed to analyse VASP calculations but is compatible with other ab initio codes. 
+`surfinpy` was developed across several PhD projects and as such the functionality focuses on the research questions encountered during those projects, which we should clarify 
 are wide ranging. Code contributions aimed at expanding the code to new problems are encouraged.
 
 `surfinpy` is free to use.
 
 Usage
 -----
 
-A full list of examples can be found in the examples folder of the git repository, these include both the Python scripts needed to generate each plot, and 
-jupyter notebook tutorials which combine the full theory with code examples.
+A full list of examples can be found in the examples folder of the git repository, these include jupyter notebook tutorials which combine the full theory with code examples.
 
 Installation
 ------------

docs/source/_static/my_styles.css

@@ -1,3 +1,15 @@
 body {
     font-family:"Arial", Helvetica, sans-serif;
 }
+
+.wy-side-nav-search, .wy-nav-top {
+    background: #2DABE3;
+}
+
+.wy-side-nav-search>div.version{
+    color: #2DABE3;
+}
+
+.fa-bars{
+    color: #2DABE3;
+}

docs/source/bulk_theory.rst

@@ -0,0 +1,88 @@
+Bulk Theory
+===========
+
+Bulk phase diagrams enable the comparison of the thermodynamic stability of various different bulk phases under different chemical potentials giving valuable insight in to the syntheis of solid phases.  
+This theory example will consider a series of bulk phases which can be defined through a reaction scheme across all phases, 
+thus for this example including MgO, :math:`H_2O` and :math:`CO_2` as reactions and A as a generic product.
+
+.. math::
+    x\text{MgO} + y\text{H}_2\text{O} + z\text{CO}_2 \rightarrow \text{A}
+
+The system is in equilibrium when the chemical potentials of the reactants and product are equal; i.e. the change in Gibbs free energy is :math:`$\delta G_{T,p} = 0$`.
+
+.. math::
+	\delta G_{T,p} = \mu_A - x\mu_{\text{MgO}} - y\mu_{\text{H}_2\text{O}} - z\mu_{\text{CO}_2} = 0
+
+Assuming that :math:`H_2O` and :math:`CO_2` are gaseous species, :math:`$\mu_{CO_2}$` and :math:`$\mu_{H_2O}$` can be written as
+
+.. math::
+	\mu_{\text{H}_2\text{O}} = \mu^0_{\text{H}_2\text{O}} + \Delta\mu_{\text{H}_2\text{O}}
+
+and 
+
+.. math::
+	\mu_{\text{CO}_2} = \mu^0_{\text{CO}_2} + \Delta\mu_{\text{CO}_2}
+
+The chemical potential :math:`$\mu^0_x$` is the partial molar free energy of any reactants or products (x) in their standard states, 
+in this example we assume all solid components can be expressed as
+
+.. math::
+    \mu_{\text{component}} = \mu^0_{\text{component}}
+
+Hence, we can now rearrange the equations to produce;
+
+.. math::
+	\mu^0_A - x\mu^0_{\text{MgO}} - y\mu^0_{\text{H}_2\text{O}} - z\mu^0_{CO_2} = y\Delta\mu_{H_2O} + z\Delta\mu_{CO_2}
+
+As :math:`$\mu^0_A$` corresponds to the partial molar free energy of product A, we can replace the left side with the Gibbs free energy (:math:`$\Delta G_{\text{f}}^0$`).
+
+.. math::
+	\delta G_{T,p} = \Delta G_{\text{f}}^0 - y\Delta\mu_{\text{H}_2\text{O}} - z\Delta\mu_{\text{CO}_2}
+
+At equilibrium :math:`$\delta G_{T,p} = 0$`, and hence
+
+.. math::
+	\Delta G_{\text{f}}^0 = y\Delta\mu_{\text{H}_2\text{O}} + z\Delta\mu_{\text{CO}_2}
+
+Thus, we can find the values of :math:`$\Delta\mu_{H_2O}$` and :math:`$\Delta\mu_{CO_2}$` (or :math:`$(p_{H_2O})^y$` and :math:`$p_{CO_2}^z$` when Mg-rich phases are in thermodynamic equilibrium; i.e. 
+they are more or less stable than MgO.  
+This procedure can then be applied to all phases to identify which is the most stable, provided that the free energy :math:`$\Delta G_f^0$` is known for each Mg-rich phase.
+
+The free energy can be calculated using
+
+.. math::
+    \Delta G^{0}_{f} = \sum\Delta G_{f}^{0,\text{products}} - \sum\Delta G_{f}^{0,\text{reactants}}
+
+Where for this example the free energy (G) is equal to the calculated DFT energy (:math:`U_0`).
+
+Temperature
+~~~~~~~~~~~
+
+The previous method will generate a phase diagram at 0 K. This is not representative of normal conditions.  
+Temperature is an important consideration for materials chemistry and we may wish to evaluate the phase thermodynamic stability at various synthesis conditions.  
+
+As before the free energy can be calculated using;
+
+.. math::
+    \Delta G^{0}_{f} = \sum\Delta G_{f}^{0,\text{products}} - \sum\Delta G_{f}^{0,\text{reactants}}
+
+Where for this exmaple the free energy (G) for solid phases is equal to is equal to the calculated DFT energy :math:`(U_0)`. 
+For gaseous species, the standard free energy varies significantly with temperature, and as DFT simulations are designed for condensed phase systems, 
+we use experimental data to determine the temperature dependent free energy term for gaseous species, where :math:`$S_{expt}(T)$` is specific entropy value for a given T and  :math:`$H-H^0(T)$` is the,
+both can be obtained from the NIST database and can be calculated as;
+
+.. math::
+    G =  U_0 + (H-H^0(T) - T S_{\text{expt}}(T))
+
+Pressure
+--------
+
+In the previous tutorials we went through the process of generating a simple phase diagram for bulk phases and introducing temperature dependence for gaseous species.  
+This useful however, sometimes it can be more beneficial to convert the chemical potenials (eVs) to partial presure (bar). 
+
+Chemical potential can be converted to pressure values using
+
+.. math::
+    P & = \frac{\mu_O}{k_B T} ,
+
+where P is the pressure, :math:`$\mu$` is the chemical potential of oxygen, $k_B$ is the Boltzmnann constant and T is the temperature.