Package: pyscses
pyscses- PYthon Space-Charge Site-Explicit Solverpyscsesis 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.pyscsescan 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 obtined using private closed-source codes, making it difficult to reproduce results or to test the effect of different approximations included in specific models.pyscsesprovides an open-source Python package for modelling space-charge formation in solid electrolytes, within a 1D Poisson-Boltzmann-like formalism.We are currently usingpyscsesin 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].pyscsesimplements 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 theuserguide.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 theJOSS paper.DocumentationUserguidesIntroductory userguides are contained in theuserguide. Each guide is presented as aJupyter 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.ipynbFor online viewing of these userguides, we recommend usingnbviewer. The links below open nbviewer versions of each userguide notebook.TheorySetting up the notebookRunning the calculationExample 1 - continuum vs. site explicit and boundary conditionsExample 2 - Mott-Schottky vs. Gouy-Chapman conditionsExample 3 - Calculating the grain boundary resistivity and activation energyExample 4 - Comparison with “experimental” valuesExample 5 - Using the pyscses with real dataExample 6 - Storing the output dataAPI DocumentationAPI documentation can be foundhereInstallationSource code is available as a git repository athttps://github.com/bjmorgan/pyscses/tree/master/pyscsesThe simplest way to installpyscsesis to usepipto install fromPyPIpip install pyscsesAlternatively, you can download the latest release fromGitHub, and install directly:cd pyscses
pip install -e .which installs an editable (-e) version of pyscses in your userspace.Or clone the latest version fromGitHubwithgit clone git@github.com:bjmorgan/pyscses.gitand install the same way.cd pyscses
pip install -e .TestsThe directorytests/test_notebookscontains a set of Jupyter notebooks with specified outputs, that can be run to test code functionality. The test notebooks can be found on GitHubhere.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 theinput_datadirectory and the output for the calculations will be stored in thegenerated_datadirectory and can be compared to the verified data in theexpected_outputsdirectory. A list of the input parameters used in the notebooks is reiterated in each of the four test folders in theinput_parametersfile.Unit testsLimited unit tests are contained in the toptestsdirectory. These can be run usingcd tests
python -m unittest discoverAutomated unit testing of the latest commit happenshere.ContributingBugs reports and feature requestsIf you think you have found a bug, please report it on theIssue 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 contributionsWe 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 anIssueto 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 apull requestto merge the changes into the main project. A more detailed discussion can take place there before the changes are accepted.CitingpyscsesThis code can be cited as:Wellock, Georgina L., & Morgan, Benjamin J. (2019).pyscses - a PYthon Space-Charge Site-Explicit SolverZenodo.http://doi.org/10.5281/zenodo.2536867BibTeX@misc{wellock_georgina_l_2019_2536901,
  author       = {Wellock, Georgina L. and
                  Morgan, Benjamin J.},
  title        = {{pyscses - a PYthon Space-Charge Site-Explicit 
                   Solver}},
  month        = jan,
  year         = 2019,
  doi          = {10.5281/zenodo.2536901},
  url          = {https://doi.org/10.5281/zenodo.2536867}
}ReferencesSandve, G. K., Nekrutenko, A., Taylor, J., & Hovig, E. (2013). Ten simple rules for reproducible computational research. PLoS Comput. Biol., 9(10), e1003285–4.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.Kim, S., & Maier, J. (2002). On the conductivity mechanism of nanocrystalline ceria.J. Electrochem. Soc.,149(10), J73–J83.