pyscses - PYthon Space-Charge Site-Explicit Solver

pyscses is a Python package for modelling ionic space-charges in solid electrolytes. Its primary use is to calculate equilibrium distributions of point-charge atomic defects within one-dimensional “Poisson-Boltzmann”-like mean-field models. These calculations take as inputs a set of defect site positions, within a specific crystal structure, and the associated defect segregation energies. pyscses can also be used to calculate ionic transport properties (space-charge resistivities and activation energies) for these equilibrium defect distributions.

One approach to modelling space-charge formation in solid electrolytes is to consider defects as ideal point-charges embedded in a continuum dielectric, and to calculate equilibrium defect distributions by solving mean-field “Poisson-Boltzmann”-like equations. While numerical solutions to the 1D Poisson-Boltzmann equation are relatively simple to implement, published results are typically obtained using private closed-source codes, making it difficult to reproduce results or to test the effect of different approximations included in specific models. pyscses provides an open-source Python package for modelling space-charge formation in solid electrolytes, within a 1D Poisson-Boltzmann-like formalism.We are currently using pyscses in our own research into space-charge formation in solid electrolytes for fuel cells and lithium-ion batteries, and hope that this open-source resource will support reproducible research practices in future studies in this area [1].

pyscses implements a range of numerical models within the general scheme of solving a modified Poisson-Boltzmann equation on a 1D grid:

• Continuum (regular grid) and site-explicit (irregular grid) models.
• Periodic and Dirichlet boundary conditions.
• “Mott-Schottky” and “Gouy-Champman” condtions. These are implemented by setting the mobilities of different defect species. In the case of Mott-Schottky conditions, all but one defect species have a mobility of zero.
• Inclusion of “lattice”site charges to account for non-defective species in the crystal structure.

Properties that can be calculated include:

• Defect mole fractions.
• Charge density.
• Electrostatic potential.
• Parallel and perpendicular grain boundary resistivities [2].
• Grain boundary activation energies [3].

Full mathematical derivations, definitions and example code can be found in the userguide.

A more detailed overview of the code and its capabilities, and of the scientific context of modelling space-charge regions in solids, are given in the JOSS paper.

Documentation

Userguides

Introductory userguides are contained in the userguide. Each guide is presented as a Jupyter notebook. The userguides cover the theory behind the Poisson-Boltzmann solver, how to set up a Jupyter notebook to run a calculation and examples of running the calculation under different approximations. These examples include site-explicit versus continuum models, Mott-Schottky (single mobile defect species) and Gouy-Chapman (all defect species mobile) conditions, and running the solver on real data.

These userguides can also be found in the directory:

pyscses/userguides/userguide.ipynb

For online viewing of these userguides, we recommend using nbviewer. The links below open nbviewer versions of each userguide notebook.

• Theory
• Setting up the notebook
• Running the calculation
• Example 1 - continuum vs. site explicit and boundary conditions
• Example 2 - Mott-Schottky vs. Gouy-Chapman conditions
• Example 3 - Calculating the grain boundary resistivity and activation energy
• Example 4 - Comparison with “experimental” values
• Example 5 - Using the pyscses with real data
• Example 6 - Storing the output data

API Documentation

API documentation can be found here

Installation

Source code is available as a git repository at https://github.com/bjmorgan/pyscses/tree/master/pyscses

The simplest way to install pyscses is to use pip to install from PyPI

pip install pyscses

Alternatively, you can download the latest release from GitHub, and install directly:

cd pyscses
pip install -e .

which installs an editable (-e) version of pyscses in your userspace.

Or clone the latest version from GitHub with

git clone git@github.com:bjmorgan/pyscses.git

and install the same way.

cd pyscses
pip install -e .

Tests

The directory tests/test_notebooks contains a set of Jupyter notebooks with specified outputs, that can be run to test code functionality. The test notebooks can be found on GitHub here.

There are four directories with varying conditions. In each there is a Jupyter notebook which can be run. The input for the calculations is stored in the input_data directory and the output for the calculations will be stored in the generated_data directory and can be compared to the verified data in the expected_outputs directory. A list of the input parameters used in the notebooks is reiterated in each of the four test folders in the input_parameters file.

Unit tests

Limited unit tests are contained in the top tests directory. These can be run using

cd tests
python -m unittest discover

Automated unit testing of the latest commit happens here.

Contributing

Bugs reports and feature requests

If you think you have found a bug, please report it on the Issue Tracker. This is also the place to propose ideas for new features or ask questions about the design of pyscses. Poor documentation is considered a bug, but please be as specific as possible when asking for improvements.

Code contributions

We welcome your help in improving and extending the package with your own contributions. This is managed through GitHub pull requests; for external contributions we prefer the "fork and pull" workflow, while core developers use branches in the main repository:

• First open an Issue to discuss the proposed contribution. This discussion might include how the changes fit pyscses' scope and a general technical approach.
• Make your own project fork and implement the changes there. Please keep your code style compliant with PEP8.
• Open a pull request to merge the changes into the main project. A more detailed discussion can take place there before the changes are accepted.

Citing pyscses

This code can be cited as:

Wellock G. L. & Morgan, B. J., (2019). pyscses: a PYthon Space-Charge Site-Explicit Solver. Journal of Open Source Software, 4(35), 1209, https://doi.org/10.21105/joss.01209

BibTeX

@article{WellockAndMorgan_JOSS2019,
  author       = {Wellock, Georgina L. and
                  Morgan, Benjamin J.},
  title        = {{pyscses: a PYthon Space-Charge Site-Explicit 
                   Solver}},
  journal      = {J. Open Source Soft.},
  volume       = 4,
  pages        = 1209,
  month        = mar,
  year         = 2019,
  doi          = {10.21105/joss.01209},
}

References

1. Sandve, G. K., Nekrutenko, A., Taylor, J., & Hovig, E. (2013). Ten simple rules for reproducible computational research. PLoS Comput. Biol., 9(10), e1003285–4.
2. Hwang, J.-H., McLachlan, D. S., & Mason, T. O. (1999). Brick layer model analysis of nanoscale-to-microscale cerium dioxide. J. Electroceram., 3 (1), 7–16.
3. Kim, S., & Maier, J. (2002). On the conductivity mechanism of nanocrystalline ceria. J. Electrochem. Soc., 149(10), J73–J83.