Merge pull request #210 from jotelha/joss-review-issue-186

documentation addressing Joss review issue 186

Author: pastewka

.github/workflows/documentation.yml

@@ -25,6 +25,14 @@ jobs:
           # Upgrade to latest meson and ninja
           sudo pip install --upgrade meson ninja
 
+      # needs fenics to build fenics integration documentation snippet
+      - name: install_fenics
+        run: |
+          sudo apt-get install -y --no-install-recommends software-properties-common
+          sudo add-apt-repository -y ppa:fenics-packages/fenics
+          sudo apt-get update -qy
+          sudo apt-get install -y fenics python3-dolfin python3-mshr
+
       - name: install_package
         run: |
           sudo pip install .[docs]

docs/Makefile

@@ -46,6 +46,7 @@ help:
 	@echo "  pseudoxml  to make pseudoxml-XML files for display purposes"
 	@echo "  linkcheck  to check all external links for integrity"
 	@echo "  doctest    to run all doctests embedded in the documentation (if enabled)"
+	@echo "  spelling   to run spell check on documentation"
 
 clean:
 	rm -rf $(BUILDDIR)/*
@@ -176,3 +177,9 @@ pseudoxml:
 	$(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml
 	@echo
 	@echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml."
+
+spelling:
+	$(SPHINXBUILD) -b spelling $(ALLSPHINXOPTS) $(BUILDDIR)/spelling
+	@echo
+	@echo "Spell check finished. Results are in $(BUILDDIR)/spelling."
+

docs/applications/electrochemistry.rst

@@ -0,0 +1,22 @@
+Electrochemistry
+================
+
+The electrochemistry module provides three components for preparing atomistic
+configurations usually encountered in the context of soluted electrolytes.
+
+.. toctree::
+
+    electrochemistry_1
+    electrochemistry_2
+    electrochemistry_3
+
+Acknowledgements
+----------------
+
+We thank Lukas Elflein for supporting the development of
+`matscipy.electrochemistry` and the according example notebooks, Christian
+Seidl for early experimentation with the module's functionality, Andreas
+Greiner for discussions and inspirations on solving transport problems with
+controlled-volume and finte-elements methods, as well as Meng Yonggang and
+Zhang Jun for posing an interesting tribological problem that sparked the
+development of this module initially.

docs/applications/electrochemistry/.gitignore

@@ -0,0 +1,4 @@
+*.pdf
+*.gz
+*.log
+*.aux

docs/applications/electrochemistry/README

@@ -0,0 +1,13 @@
+Run
+
+    pdflatex file.tex
+    
+to build pdf and
+
+    pdf2svg file.pdf file.svg
+    
+to convert to svg, then
+
+    inkscape -h 1024 file.svg -o file.png
+
+to convert to png at 1024 px height.

docs/applications/electrochemistry/electrochemicalCellBazant1d.svg

@@ -0,0 +1,46 @@
+\documentclass[tikz,margin=0mm]{standalone}
+
+\usepackage{amsmath}
+
+\usetikzlibrary{arrows}
+\usetikzlibrary{decorations.pathreplacing}
+\usetikzlibrary{shadows,fadings}
+\usetikzlibrary{shadows.blur}
+\usetikzlibrary{fit}
+\usetikzlibrary{calc}
+
+\tikzset{geometry/.style=thick}
+\tikzset{feederElectrode/.style={fill=black!30!white, draw=black!80!white}}
+\tikzset{electrolyte/.style={fill=black!10!white, draw=black!80!white}}
+
+\begin{document}
+\begin{tikzpicture}[geometry]
+\def \sternLayerWidth{0.8}
+\fill[electrolyte,draw=none] (0,0) rectangle +(10,1) node[pos=0.5,anchor=center,align=center]{electrolyte};
+\draw[electrolyte] (0,0) -- +(10,0) +(10,1) -- +(0,1);
+\filldraw[feederElectrode] (-0.2,0) rectangle +(0.2,1);
+\filldraw[feederElectrode] (10,0) rectangle +(0.2,1);
+  
+% electrode BC
+\draw (0,2) node[node font=\footnotesize,anchor=south,align=center] {
+  	$\phi + \lambda_S \cdot \mathbf{\hat{n}} \cdot \nabla \phi = \phi_0$\\
+  	$-\mathbf{\hat{n}} \cdot ( -D_i \nabla c_i - z_i F u_i c_i \nabla \phi ) =  \sum_{j=1}^M \frac{\nu_{ij} i_j}{F n_j}$
+	};
+\draw (0,2) -- +(0,-0.8);
+  
+% bulk BC
+\draw (10,2) node[node font=\footnotesize,anchor=south,align=center] {
+  	$\phi + \lambda_S \cdot \mathbf{\hat{n}} \cdot \nabla \phi = 0$\\
+  	$-\mathbf{\hat{n}} \cdot ( -D_i \nabla c_i - z_i F u_i c_i \nabla \phi ) =  \sum_{j=1}^M \frac{\nu_{ij} i_j}{F n_j}$
+  	};
+\draw (10,2) -- +(0,-0.8);
+  
+\draw[->] (-1,0.5) -- (-0.5,0.5) node[pos=0,anchor=east,node font=\footnotesize] {$i_\text{cell} = \sum_{j=1}^M i_j$};
+\draw[->] (10.5,0.5) -- (11,0.5) node[anchor=west,node font=\footnotesize] {$i_\text{cell} = \sum_{j=1}^M i_j$};
+  
+%% governing eq
+\draw [decorate,decoration={brace,amplitude=10pt},xshift=0,yshift=0] (10,-0.2) -- +(-10,0) node [node font=\footnotesize,anchor=north,midway,yshift=-10pt,align=center]  {$ \nabla \cdot ( -D_i \nabla c_i - z_i F u_i c_i \nabla \phi ) = 0 $ \\
+  	$\nabla \cdot ( - \epsilon_r \epsilon_0 \nabla \phi ) - F \cdot \sum_{i=1}^N z_i c_i  = 0$ 
+  	}; 
+\end{tikzpicture}
+\end{document}

docs/applications/electrochemistry/electrochemicalCellBazant1d.tex

@@ -0,0 +1,46 @@
+\documentclass[tikz,margin=0mm]{standalone}
+
+\usepackage{amsmath}
+
+\usetikzlibrary{arrows}
+\usetikzlibrary{decorations.pathreplacing}
+\usetikzlibrary{shadows,fadings}
+\usetikzlibrary{shadows.blur}
+\usetikzlibrary{fit}
+\usetikzlibrary{calc}
+
+\tikzset{geometry/.style=thick}
+\tikzset{feederElectrode/.style={fill=black!30!white, draw=black!80!white}}
+\tikzset{electrolyte/.style={fill=black!10!white, draw=black!80!white}}
+
+\begin{document}
+\begin{tikzpicture}[geometry]
+\fill[electrolyte,draw=none] (0,0) rectangle +(10,1);
+\shade[left color=black!10,right color=white,draw=none] (9.5,0) rectangle +(0.5,1);
+\draw[electrolyte,fill=none] (0,0) -- +(10,0) +(10,1) -- +(0,1);
+\filldraw[feederElectrode] (-0.2,0) rectangle +(0.2,1);
+\draw (-0.2,0.5) node[anchor=east] {electrode};
+\draw (5,0.5) node[anchor=center] {electrolyte};
+\draw (10,0.5) node[anchor=west] {bulk};
+% 
+% electrode BC
+\draw (0,2) node[node font=\footnotesize,anchor=south,align=right] {
+  	%$\phi + \lambda_S \cdot \mathbf{\hat{n}} \cdot \nabla \phi = \phi_0$\\
+  	$\phi = \phi_0$\\
+  	$( -D_i \nabla c_i - z_i F u_i c_i \nabla \phi ) = 0$
+	};
+\draw[->] (0,2) -- +(0,-0.8);
+  
+% bulk BC
+\draw (10,2) node[node font=\footnotesize,anchor=south,align=center] {
+    	$\phi = 0$\\
+  	$c_i = c_i^\infty$
+  	};
+\draw[->] (10,2) -- +(0,-0.8);
+
+%% governing eq
+\draw [decorate,decoration={brace,amplitude=10pt},xshift=0,yshift=0] (10,-0.2) -- +(-10,0) node [node font=\footnotesize,anchor=north,midway,yshift=-10pt,align=center]  {\footnotesize  	$ \nabla \cdot ( -D_i \nabla c_i - z_i F u_i c_i \nabla \phi ) = 0 $ \\
+  	$\nabla \cdot ( - \epsilon_r \epsilon_0 \nabla \phi ) - F \cdot \sum_{i=1}^N z_i c_i  = 0$ 
+  	}; 
+\end{tikzpicture}
+\end{document}