typos and changes to jupyter notebooks

examples/analysis/analysis_example.ipynb

@@ -21,7 +21,7 @@
    "metadata": {},
    "source": [
     "### Bond analysis \n",
-    "words"
+    "Consistent bond lengths in c-direction in the relaxed slab are an indicator of a sufficient slab thickness. The `bond_analysis` function takes the slab structure file and the atom pairs under consideration to asses the bonding distance using the `CrystalNN` algorithm. The validity of the nearest neighbour finding algorithm should be checked on the bulk structure as some struggle with more complex systems - `CrystalNN` and `MinimumDistanceNN` are a good start. As in other modules, oxidation states are added by guess by default, but can be added by element or site as well. "
    ]
   },
   {
@@ -33,6 +33,13 @@
     "a.bond_analysis('./CONTCAR_LTA_010', atoms=[('Ti', 'O'), ('Ag', 'S')])"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "The data collected can then be plotted using `plot_bond_analysis` where only the atom pairs need to be supplied to produce the following figure. Some deviation is expected in bond length close to the surface - however the extrapolated line should be relatively flat in the bulk-like region. "
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": 5,
@@ -60,7 +67,10 @@
    "metadata": {},
    "source": [
     "### Electrostatic potential\n",
-    "more words"
+    "\n",
+    "`Surfaxe` can plot the electrostatic potential going through the slab using the aptly named `electrostatic_potential` function. It calculates both the planar and macroscopic potential - if the latter is flat it can be used to derive the ionisation potential and electron affintity directly. Along with the plot, a .csv file is produced to allow for easier extraction of the vacuum energy. \n",
+    "\n",
+    "The planar potential is just the average along one axis, calculated with pymatgen. The default axis specified here is c (but can be a or b as well) because we are interested in the potential in the vacuum region. The macroscopic potential is a rolling average of the planar potential with the periodicity of the unit cell as the window of the rolling average. The window is calculated as the ratio of the periodicity of the bulk system (`lattice_vector`) and the resolution of the raw potential data in that direction. The latter is calculated by diving the lattice parameter by the dimension of the potential data in a specified direction. \n"
    ]
   },
   {
@@ -89,8 +99,11 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "### Nearest neighbours \n",
-    "more more words "
+    "### Coordination environment\n",
+    "The analysis of coordination environment is an important for various reasons in both bulk and surface calculations. \n",
+    "This [paper](https://chemrxiv.org/articles/Benchmarking_Coordination_Number_Prediction_Algorithms_on_Inorganic_Crystal_Structures/12508229?file=23211761) explains how the coordination number prediction algorithms work and why `CrystalNN` is a good start for most purposes. It is recommended the vaidity of the algorithms is checked with bulk structure before using it in slabs, in particular in the case of metal-sulphur bonding in solid state. Based on anecdotal evidence, most algorithms struggle with bonding environments near the surface in quaternary and quinary systems.  \n",
+    "\n",
+    "In `Surfaxe` the coordination environment is separated into `simple_nn` and `complex_nn`. The `simple_nn` function uses `CrystalNN` by default but it can be used with any local environment algorithm. It is fast and intended for simple binaries and ternaries and bulk structures. The `complex_nn` uses the `CutOffDictNN` algorithm where the maximum bond distance needs to be specified in form of a dictionary of bond lengths. It is a slightly slower approach more suited for systems with complex bonding structure, or where other algorithms fail. "
    ]
   },
   {

examples/generation/generation_example.ipynb

@@ -4,7 +4,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "`slabby stabby` `generation` module allows for easy generation of zero-dipole symmetric slabs for convergence testing purposes either up to a maximum Miller index or for a specific Miller index. By passing the structure, required Miller index variable, and lists of slab and vacuum thicknesses, `get_all_slabs` and `get_one_hkl_slabs` can generate unique zero-dipole symmetric surface slabs for all combinations of slab and vacuum thickness. "
+    "`surfaxe` `generation` module allows for easy generation of zero-dipole symmetric slabs for convergence testing purposes either up to a maximum Miller index or for a specific Miller index. By passing the structure, required Miller index variable, and lists of slab and vacuum thicknesses, `get_all_slabs` and `get_one_hkl_slabs` can generate unique zero-dipole symmetric surface slabs for all combinations of slab and vacuum thickness. "
    ]
   },
   {

slabbystabby/analysis.py

@@ -129,14 +129,15 @@ def bond_analysis(structure, atoms, nn_method=CrystalNN(), ox_states=None,
     if return_df is True:
         return df
 
-def plot_bond_analysis(atoms, plt_fname='bond_analysis.png', **kwargs):
+def plot_bond_analysis(atoms, plt_fname='bond_analysis.png', dpi=300, **kwargs):
     """
     Plots the bond distance with respect to fractional coordinate graph from the
     csv file generated with `bond_analysis`
 
     Args:
         atoms (list of tuples) in the same order as in bond_analysis
         plt_fname (str): filename of the plot
+        dpi (int): dots per inch; default=300
 
     Returns:
         Plot
@@ -158,11 +159,11 @@ def plot_bond_analysis(atoms, plt_fname='bond_analysis.png', **kwargs):
         axs[i].legend(['{}-{} bond'.format(atom1, atom2)])
         i+=1
     plt.xlabel("Fractional coordinates")
-    plt.savefig(plt_fname)
+    plt.savefig(plt_fname, dpi=dpi)
 
 def electrostatic_potential(lattice_vector, filename='./LOCPOT', axis=2,
                             make_csv=True, csv_fname='potential.csv',
-                            plt_fname='potential.png', **kwargs):
+                            plt_fname='potential.png', dpi=300, **kwargs):
     """
     Reads LOCPOT to get the planar and macroscopic potential in specified direction
 
@@ -176,6 +177,7 @@ def electrostatic_potential(lattice_vector, filename='./LOCPOT', axis=2,
         csv_fname (str): filename of the csv file, default='potential.csv'
         plt_fname (str): filename of the plot of potentials, controls the format,
         default='potential.png'
+        dpi (int): dots per inch; default=300
 
     Returns:
         csv file and plot of planar and macroscopic potential
@@ -217,8 +219,8 @@ def electrostatic_potential(lattice_vector, filename='./LOCPOT', axis=2,
     ax.plot(planar, label='planar')
     ax.plot(macroscopic, label='macroscopic')
     ax.legend()
-    plt.ylabel('potential / eV')
-    plt.savefig(plt_fname)
+    plt.ylabel('Potential / eV')
+    plt.savefig(plt_fname, dpi=dpi)
 
 
 def simple_nn(start, elements, end=None, ox_states=None, nn_method=CrystalNN(),

slabbystabby/convergence.py

@@ -136,7 +136,8 @@ def plot_surfen(hkl, time_taken=True, cmap='Wistia', fmt='png', dpi=300, **kwarg
     if len(indices) == 1:
         mpl.rcParams['figure.figsize'] = (6.0,6.0)
         fig, ax = plt.subplots(1,1)
-        fig.suptitle('{} surface energies'.format(hkl))
+        ax.set_title('{} surface energies'.format(hkl))
+
         for (index, val, time, df) in zip(indices, vals, times, dfs):
             ax.set_yticks(list(range(len(df.index))))
             ax.set_yticklabels(df.columns)
@@ -261,7 +262,7 @@ def plot_enatom(hkl, time_taken=True, cmap='Wistia', fmt='png', dpi=300, **kwarg
     if len(indices) == 1:
         mpl.rcParams['figure.figsize'] = (6.0,6.0)
         fig, ax = plt.subplots(1,1)
-        fig.suptitle('{} energies per atom'.format(hkl))
+        ax.set_title('{} energies per atom'.format(hkl))
 
         # Iterate through the values for plotting, create each plot on a separate ax,
         # add the colourbar to each ax