Skip to content
PYthon Space-Charge Site-Explicit Solver
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
docs
paper
pyscses
resources Added logo PDF to resources directory Jan 10, 2019
tests rephrased to remove the repetitive calculation Mar 19, 2019
userguides Added check for missing generated_outputs directories Mar 19, 2019
.coverage Editing coverage setup Feb 4, 2019
.coveragerc
.gitignore
.travis.yml
.zenodo.json Updated zenodo metadata Mar 20, 2019
LICENSE
README.md
codemeta.json
logo.png
requirements.txt Initial changes to Test Notebooks Mar 19, 2019
setup.py

README.md

pyscses - PYthon Space-Charge Site-Explicit Solver

status PyPI version DOI Documentation Status

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.

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.
You can’t perform that action at this time.