Merge pull request #31 from WMD-group/development(calysta)

Develop

.github/workflows/ci.yaml

@@ -23,7 +23,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        python-version: ["3.8","3.9","3.10","3.11"]
+        python-version: ["3.9", "3.10", "3.11"]
         os: [ubuntu-latest,]
 
     runs-on: ${{matrix.os}}

.readthedocs.yaml

@@ -17,4 +17,4 @@ sphinx:
 # Explicitly set the version of Python and its requirements
 python:
   install:
-    - requirements: docs/docs_requirements.txt
+    - requirements: docs/docs_requirements.txt

CHANGELOG.rst

@@ -1 +0,0 @@
-

JOSSpaper/JOSSpaper.bib

@@ -128,4 +128,4 @@ @article{Gale1997
   author = {Julian D. Gale},
   title = {{GULP}: A computer program for the symmetry-adapted simulation of solids},
   journal = {Journal of the Chemical Society,  Faraday Transactions}
-}
+}

JOSSpaper/JOSSpaper.md

@@ -1,61 +1,61 @@
 ---
-title: 'MacroDensity: Analysis of electrostatic potential and electron density landscapes of crystals'  
+title: 'MacroDensity: Analysis of electrostatic potential and electron density landscapes of crystals'
 tags:
   - python
   - density functional theory
   - DFT
   - electrostatic potentials
-  - electron density 
+  - electron density
   - ab initio
   - vasp
-  - 
+  -
 authors:
   - name: Calysta A. Tesiman
     orcid: 0009-0008-7784-4320
     equal-contrib: false
-    affiliation: "1" 
-  - name: Liam Harnett-Caulfield 
+    affiliation: "1"
+  - name: Liam Harnett-Caulfield
     equal-contrib: false
-    affiliation: "1" 
+    affiliation: "1"
   - name: Irea Mosquera-Lois
     equal-contrib: false
-    affiliation: "1" 
+    affiliation: "1"
   - name: Keith T. Butler
     equal-contrib: false
     corresponding: true
-	affiliation: "2" 
-  - name: Aron Walsh 
+	affiliation: "2"
+  - name: Aron Walsh
     orcid: 0000-0001-5460-7033
     equal-contrib: false
     corresponding: true
-	affiliation: "1" 
-	
+	affiliation: "1"
+
 affiliations:
  - name: Department of Materials, Imperial College London, London, United Kingdom
    index: 1
  - name: Department of Chemistry, University College London, London, United Kingdom
    index: 2
-   
+
 date: 31 August 2023
 bibliography: JOSSpaper.bib
 
 ---
 
 # Summary
 
-We report a Python package to simplify the analysis of electrostatic potentials and electron density of crystals. Macrodensity can read volumetric output files from the first-principles materials modelling codes VASP (LOCPOT format) and FHI-AIMS (cube format), as well as the classical electrostatic potentials from GULP (standard output). The code consists of functions that calculate and plot planar macroscopic and spherical averages, as well as calculating conduction and valence band alignments over a user-defined vector or plane. As a result, this code has been used to aid the data analysis and generation for several publications [@Butler:2014;@Walsh:2013]. 
+We report a Python package to simplify the analysis of electrostatic potentials and electron density of crystals. Macrodensity can read volumetric output files from the first-principles materials modelling codes VASP (LOCPOT format) and FHI-AIMS (cube format), as well as the classical electrostatic potentials from GULP (standard output). The code consists of functions that calculate and plot planar macroscopic and spherical averages, as well as calculating conduction and valence band alignments over a user-defined vector or plane. As a result, this code has been used to aid the data analysis and generation for several publications [@Butler:2014;@Walsh:2013].
 
 # Statement of need
 
 To assess the potential utility of novel semiconducting devices (like p-n junctions, heterostructures, surface terminations), it is key to understand how the electrostatic potential and electron density change across the system [@Politzer:2002]. However, analysing this data from the raw output of simulations can prove cumbersome and often requires manually extracting data and using visualisation software. This can result in bottlenecks in high throughput screening projects, where the same data extraction procedure is repeatedly applied to large databases of candidate structures.
 
-The general approach for processing electrostatic potential and electron density data as well as its translation to a grid mesh is discussed in @Butler:2014. Withing the framework of Kohn-Sham density functional theory, this approach samples the spherical averages over points within the system onto a matrix, where our raw data is generated. To process this data appropriately, ``MacroDensity`` was developed to simplify the data extraction and visualisation processes. By defining planes or vectors along the landscape of electrostatic potentials and electronic density matrix, it becomes straightforward to produce meaningful analysis and visualisation plots across a user-defined area. 
+The general approach for processing electrostatic potential and electron density data as well as its translation to a grid mesh is discussed in @Butler:2014. Withing the framework of Kohn-Sham density functional theory, this approach samples the spherical averages over points within the system onto a matrix, where our raw data is generated. To process this data appropriately, ``MacroDensity`` was developed to simplify the data extraction and visualisation processes. By defining planes or vectors along the landscape of electrostatic potentials and electronic density matrix, it becomes straightforward to produce meaningful analysis and visualisation plots across a user-defined area.
 
 # MacroDensity
 
 ``MacroDensity`` is a set of Python modules developed to read and analyse electrostatic potentials and electron density data from electronic structure calculations derived from Density Functional Theory (DFT) [@Kohn:1996]. The package allows users to read from VASP [@vasp] LOCPOT and CHGCAR files, FHI-AIMS [@fhi_aims] (cube file), and GULP [@Gale1997] (standard output files) and format the data into physically meaningful quantities, which can then be plotted for user interpretation.
 
-The package formats datasets containing information about a system's lattice parameters, electron density, and electrostatic potentials. ``MacroDensity`` contains some high-level tools and functions to calculate and plot the planar and macroscopic average as defined in Jackson's Electrodynamics [@Jackson:2003] (Figure 1a). The determination of the lattice vector settings and how the macroscopic averaging is calculated in this package is best described from the work of @Peressi:1998. 
+The package formats datasets containing information about a system's lattice parameters, electron density, and electrostatic potentials. ``MacroDensity`` contains some high-level tools and functions to calculate and plot the planar and macroscopic average as defined in Jackson's Electrodynamics [@Jackson:2003] (Figure 1a). The determination of the lattice vector settings and how the macroscopic averaging is calculated in this package is best described from the work of @Peressi:1998.
 
 \begin{equation}
 \label{eq:Planar-average}
@@ -64,17 +64,17 @@ The package formats datasets containing information about a system's lattice par
 
 ``MacroDensity`` can also calculate and plot the localised potential around a certain atomic nucleus of a system. The approach to calculating this on-site (Hartree) potential is similar to calculating the Madelung potential (Figure 1b). This is useful for electron energy level predictions [@Walsh:2013]. In addition, the spherical average around a user-defined point within the system can be calculated using an approach akin to the planar average function (integrating over a sphere instead of a plane). Similarly, instead of averaging over a sphere, ``MacroDensity`` can also calculate the average and macroscopic potentials within a specified volume of a cube which moves along a plane of the system's lattice.
 
-Calculations and averaging at different points in space can be used to quantify the valence band and conduction band positions relative to this average. This is a convenience function that is included within the package, which calculates the bulk interstitial alignment similarly to that from @Frensley:1976. 
+Calculations and averaging at different points in space can be used to quantify the valence band and conduction band positions relative to this average. This is a convenience function that is included within the package, which calculates the bulk interstitial alignment similarly to that from @Frensley:1976.
 
 \begin{equation}
 \label{eq:Madelung-potential}
   V_M = \sum_{i,j} \frac{(-1)^{n_i + n_j}}{4\pi \varepsilon_0 r_{ij}}
 \end{equation}
 
-``MacroDensity`` has been used to rapidly generate data for the publications @Butler:2014 and @Walsh:2013 amongst others. 
+``MacroDensity`` has been used to rapidly generate data for the publications @Butler:2014 and @Walsh:2013 amongst others.
 
 ![Example analysis done with the package for AlAs, CsPbI<sub>3</sub>, and MgO: a) plots of the planar (blue) and macroscopic (orange) averages of the potential, b) plots of the mean potential along the [111] vector, c) onsite (Hartree) potentials of the constituent atoms of the compounds analysed. \label{fig1}](figure.png){ width=70% }
 
 # Acknowledgements
 
-We acknowledge input from Adam J. Jackson and Jarvist M. Frost in the early stages of the project. The work received financial support by Samsung Advanced Institute of Technology.     
+We acknowledge input from Adam J. Jackson and Jarvist M. Frost in the early stages of the project. The work received financial support by Samsung Advanced Institute of Technology.

JOSSpaper/apa.csl

@@ -320,8 +320,8 @@
   <!-- General categories of item types:
        Periodical: article-journal article-magazine article-newspaper post-weblog review review-book
        Periodical or Booklike: paper-conference
-       Booklike: article book broadcast chapter dataset entry entry-dictionary entry-encyclopedia figure 
-                 graphic interview manuscript map motion_picture musical_score pamphlet patent 
+       Booklike: article book broadcast chapter dataset entry entry-dictionary entry-encyclopedia figure
+                 graphic interview manuscript map motion_picture musical_score pamphlet patent
                  personal_communication report song speech thesis post webpage
        Legal: bill legal_case legislation treaty
   -->
@@ -389,7 +389,7 @@
       </if>
       <else-if type="interview personal_communication">
         <choose>
-          <!-- These variables indicate that the letter is retrievable by the reader. 
+          <!-- These variables indicate that the letter is retrievable by the reader.
                 If not, then use the APA in-text-only personal communication format -->
           <if variable="archive container-title DOI publisher URL" match="none">
             <group delimiter=", ">
@@ -470,7 +470,7 @@
                   </if>
                 </choose>
               </else-if>
-              <!-- Only year: article article-journal book chapter entry entry-dictionary entry-encyclopedia dataset figure graphic 
+              <!-- Only year: article article-journal book chapter entry entry-dictionary entry-encyclopedia dataset figure graphic
                    manuscript map musical_score paper-conference[published] patent report review review-book thesis -->
             </choose>
           </if>
@@ -546,7 +546,7 @@
                 <if type="interview personal_communication">
                   <choose>
                     <if variable="archive container-title DOI publisher URL" match="none">
-                      <!-- These variables indicate that the communication is retrievable by the reader. 
+                      <!-- These variables indicate that the communication is retrievable by the reader.
                            If not, then use the in-text-only personal communication format -->
                       <date variable="issued" form="text"/>
                     </if>
@@ -1311,7 +1311,7 @@
   <macro name="reviewed-title">
     <choose>
       <if variable="reviewed-title">
-        <!-- Not possible to distinguish TV series episode from other reviewed 
+        <!-- Not possible to distinguish TV series episode from other reviewed
               works [Ex. 69] -->
         <text variable="reviewed-title" font-style="italic"/>
       </if>
@@ -1594,7 +1594,7 @@
         <group prefix="(" suffix=")">
           <choose>
             <if variable="references">
-              <!-- This provides the option for more elaborate description 
+              <!-- This provides the option for more elaborate description
                    of publication history, such as full "reprinted" references
                    (examples 11, 43, 44) or retracted references -->
               <text variable="references"/>

LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2013 Keith Butler and others 
+Copyright (c) 2013 Keith Butler and others
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
@@ -18,4 +18,4 @@ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+SOFTWARE.

docs/conf.py

@@ -35,8 +35,8 @@
     'sphinx.ext.intersphinx',
     'sphinx.ext.mathjax',  # to show equations in html output
     'sphinx.ext.githubpages',
-    'sphinx.ext.doctest', 
-    'sphinx_autodoc_annotation', 
+    'sphinx.ext.doctest',
+    'sphinx_autodoc_annotation',
     'myst_nb',  # for jupyter notebooks
 ]
 
@@ -50,7 +50,7 @@
 }
 
 myst_enable_extensions = [
-    "html_admonition", 
+    "html_admonition",
     "amsmath",
     "dollarmath", # to recognize latex $$ syntax
 ]
@@ -103,4 +103,4 @@ def setup(app):
             'url_resolver': lambda url: github_doc_root + url,
             'auto_toc_tree_section': 'Contents',
             }, True)
-    app.add_transform(AutoStructify)
+    app.add_transform(AutoStructify)

docs/index.rst

@@ -6,26 +6,25 @@
 Welcome to MacroDensity
 =======================
 
-``MacroDensity`` is a Python package to post-process electrostatic potential and 
-electron density files from electronic structure calculations and plot in a number of ways, including:
-
-1. Planar average
-2. Spherical average
-3. Atom centred average
+``MacroDensity`` is a Python package to post-process electrostatic potential and
+electron density files from electronic structure calculations and plot them a number of ways, including
+planar, sperical and atom centred averages.
 
 Statement of Need
 -----------------
-To assess the potential utility of novel semiconducting devices (like p-n junctions, heterostructures, surface terminations), 
-it is key to understand how the electrostatic potential and electron density change across the system. 
-However, extraction and useful presentation of this data from the raw output of the simulation can prove cumbersome and often requires the use of visualisation software followed by manual data extraction. 
-This can result in bottlenecks in high throughput screening projects, where the same data extraction procedure is repeatedly applied to large databases of candidate structures.
-
-To address this, the Macrodensity package has been developed to post-process the output of ab-initio codes like ``VASP``, ``FHI-AIMS`` and ``GULP``. 
-The package contains functions that enable the user to format the data from the ``VASP`` ``LOCPOT`` and ``CHGCAR`` files, the ``FHI-AIMS`` ``*.cube`` file, 
+To assess the potential utility of novel semiconducting devices (like p-n junctions, heterostructures,
+surface terminations), it is key to understand how the electrostatic potential and electron density
+change across the system. However, extraction and post-proccessing of this data from the raw output
+of the simulation can prove cumbersome and often requires the use of visualisation software followed
+by manual data extraction. This can result in bottlenecks in high throughput screening projects,
+where the same data extraction procedure is repeatedly applied to large databases of candidate structures.
+
+To address this, the Macrodensity package has been developed to post-process the output of ab-initio codes like ``VASP``, ``FHI-AIMS`` and ``GULP``.
+The package contains functions to format the data from the ``VASP`` ``LOCPOT`` and ``CHGCAR`` files, the ``FHI-AIMS`` ``*.cube`` file,
 and ``GULP`` ``*.out`` file into physically meaningful quantities, which can then be plotted for user interpretation.
 
 
-Installation 
+Installation
 ================
 
 User installation:
@@ -59,7 +58,7 @@ Literature
 For more information on the theory behind the package, please see the following references:
 
 - General Approach: Butler, K. T., Hendon, C. H., & Walsh, A. `Electronic chemical potentials of porous Metal–Organic frameworks. <https://doi.org/10.1021/ja4110073>`_ *Journal of the American Chemical Society*, 136(7), 2703–2706, **2014**
-- Theoretical Background: 
+- Theoretical Background:
    * Politzer, P., & Murray, J. S. `The fundamental nature and role of the electrostatic potential in atoms and molecules. <https://link.springer.com/article/10.1007/s00214-002-0363-9>`_ *Theoretical Chemistry Accounts*, 108(3), 134–142, **2002**
    * Peressi, M., Binggeli, N. & Baldereschi, A. `Band engineering at interfaces: theory and numerical experiments. <https://iopscience.iop.org/article/10.1088/0022-3727/31/11/002/meta>`_ *Journal of Physics D: Applied Physics*,31(11), 1273, **1998**
 - Application to MOFs:
@@ -113,4 +112,4 @@ Indices and tables
    installation
    Python API <modules>
    tutorials
-   studies
+   studies

docs/installation.rst

@@ -34,4 +34,4 @@ To use ``MacroDensity`` you will need the following Python packages:
 - `Matplotlib <https://matplotlib.org/>`_
 - `Pandas <https://pandas.pydata.org/>`_
 - `Ase <https://wiki.fysik.dtu.dk/ase/>`_
-- `Spglib <https://spglib.readthedocs.io/en/latest/>`_
+- `Spglib <https://spglib.readthedocs.io/en/latest/>`_

docs/macrodensity.averages.rst

@@ -6,4 +6,4 @@ Module Description
 .. automodule:: macrodensity.averages
    :members:
    :undoc-members:
-   :show-inheritance:
+   :show-inheritance:

docs/macrodensity.io.rst

@@ -6,4 +6,4 @@ Module Description
 .. automodule:: macrodensity.io
    :members:
    :undoc-members:
-   :show-inheritance:
+   :show-inheritance:

docs/macrodensity.rst

@@ -15,6 +15,6 @@ Submodules
    macrodensity.tools
    macrodensity.averages
    macrodensity.density
-   macrodensity.plotting 
+   macrodensity.plotting
    macrodensity.io
-   macrodensity.utils
+   macrodensity.utils

docs/macrodensity.utils.rst

@@ -6,4 +6,4 @@ Module Description
 .. automodule:: macrodensity.utils
    :members:
    :undoc-members:
-   :show-inheritance:
+   :show-inheritance:

docs/modules.rst

@@ -4,4 +4,4 @@ MacroDensity
 .. toctree::
    :maxdepth: 4
 
-   macrodensity
+   macrodensity

docs/tutorials.rst

@@ -3,8 +3,8 @@ Tutorials
 
 .. toctree::
    :maxdepth: 2
-
-   tutorials/MD_workbook.ipynb
+
    tutorials/Slab/SlabCalculation.ipynb
    tutorials/Porous/Porous.ipynb
+   tutorials/HeteroJunction/HeteroJunction.ipynb
    tutorials/Band_Alignment/Band_Alignment.ipynb