Merge upstream commits from master to this branch

.github/release.yml

@@ -0,0 +1,28 @@
+changelog:
+  exclude:
+    authors: [dependabot, github-actions, pre-commit-ci]
+  categories:
+    - title: 🎉 New Features
+      labels: [feature]
+    - title: 🐛 Bug Fixes
+      labels: [fix]
+    - title: 🛠 Enhancements
+      labels: [enhancement, DX, UX]
+    - title: 📖 Documentation
+      labels: [docs]
+    - title: 🧹 House-Keeping
+      labels: [housekeeping]
+    - title: 🚀 Performance
+      labels: [performance]
+    - title: 💡 Refactoring
+      labels: [refactor]
+    - title: 🧪 Tests
+      labels: [tests]
+    - title: 💥 Breaking Changes
+      labels: [breaking]
+    - title: 🔒 Security Fixes
+      labels: [security]
+    - title: 🏥 Package Health
+      labels: [pkg]
+    - title: 🤷‍♂️ Other Changes
+      labels: ["*"]

.github/workflows/ci.yml

@@ -1,34 +1,38 @@
 name: SMACT CI
 
-on: [push]
+on:
+  pull_request:
+  push:
+    branches:
+      - master
 
 jobs:
 
   qa:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
       - uses: pre-commit/[email protected]
 
   test:
     needs: qa
     strategy:
       fail-fast: false
       matrix:
-        python-version: ["3.8","3.9","3.10"]
+        python-version: ["3.8","3.9","3.10","3.11"]
         os: [ubuntu-latest,macos-latest,windows-latest]
 
     runs-on: ${{matrix.os}}
     steps:
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v4
     - name: Set up Python ${{ matrix.python-version }}
       uses: actions/setup-python@v4
       with:
         python-version: ${{ matrix.python-version }}
     - name: Install dependencies
       run: |
         python -m pip install --upgrade pip wheel setuptools
-        pip install -r requirements.txt
+        pip install -e .
         pip install pytest-cov
     - name: Run tests and collect coverage
       run: python -m pytest --cov=smact --cov-report=xml -v
@@ -37,9 +41,9 @@ jobs:
       with:
         token: ${{ secrets.CODECOV_TOKEN }}
         #files: ./coverage.xml
-        fail_ci_if_error: true
+        fail_ci_if_error: False
         env_vars: OS,PYTHON
         verbose: true
 
 
-
+

.github/workflows/combine-prs.yml

@@ -30,7 +30,7 @@ jobs:
 
     # Steps represent a sequence of tasks that will be executed as part of the job
     steps:
-      - uses: actions/github-script@v6
+      - uses: actions/github-script@v7
         id: create-combined-pr
         name: Create Combined PR
         with:

.pre-commit-config.yaml

@@ -4,11 +4,12 @@ repos:
     hooks:
       - id: isort
         additional_dependencies: [toml]
-        args: ["--profile", "black", "--filter-files"]
+        args: ["--profile", "black", "--filter-files","--line-length=80"]
   - repo: https://github.com/psf/black
     rev: "23.1.0"
     hooks:
       - id: black-jupyter
+        args: [--line-length=80]
   - repo: https://github.com/asottile/pyupgrade
     rev: v3.3.1
     hooks:

.readthedocs.yaml

@@ -7,4 +7,9 @@ build:
 
 # Build documentation in the docs/ directory with Sphinx
 sphinx:
-   configuration: docs/conf.py
+   configuration: docs/conf.py
+
+# Explicitly set the version of Python and its requirements
+python:
+  install:
+    - requirements: docs/requirements.txt

README.md

@@ -5,6 +5,7 @@
 ![python version](https://img.shields.io/pypi/pyversions/smact)
 [![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
 [![PyPi](https://img.shields.io/pypi/v/smact)](https://pypi.org/project/SMACT/)
+[![Conda](https://anaconda.org/conda-forge/smact/badges/version.svg)](https://anaconda.org/conda-forge/smact)
 [![GitHub issues](https://img.shields.io/github/issues-raw/WMD-Group/SMACT)](https://github.com/WMD-group/SMACT/issues)
 ![dependencies](https://img.shields.io/librariesio/release/pypi/smact)
 [![CI Status](https://github.com/WMD-group/SMACT/actions/workflows/ci.yml/badge.svg)](https://github.com/WMD-group/SMACT/actions/workflows/ci.yml)
@@ -59,7 +60,9 @@ Code features
 - The code also has some tools for manipulating common crystal lattice types: 
  - Common crystal structure types can be built using the [builder module](https://smact.readthedocs.io/en/latest/smact.builder.html)
  - Lattice parameters can be quickly estimated using ionic radii of the elements for various common crystal structure types using the [lattice_parameters module](https://smact.readthedocs.io/en/latest/smact.lattice_parameters.html).
- - The [lattice module](https://smact.readthedocs.io/en/latest/smact.lattice.html) and [distorter module](https://smact.readthedocs.io/en/latest/smact.distorter.html) rely on the [Atomic Simulation Environment](https://wiki.fysik.dtu.dk/ase/) and can be used to generate unique atomic substitutions on a given crystal structure.  
+ - The [lattice module](https://smact.readthedocs.io/en/latest/smact.lattice.html) and [distorter module](https://smact.readthedocs.io/en/latest/smact.distorter.html) rely on the [Atomic Simulation Environment](https://wiki.fysik.dtu.dk/ase/) and can be used to generate unique atomic substitutions on a given crystal structure.
+ - The [structure  prediction](https://smact.readthedocs.io/en/latest/smact.structure_prediction.html) module can be used to predict the structure of hypothetical compositions using species similarity measures.
+ - The [dopant prediction](https://smact.readthedocs.io/en/latest/smact.dopant_prediction.html) module can be used to facilitate high-throughput predictions of p-type and n-type dopants of multicomponent solids.
 
 List of modules
 -------
@@ -77,6 +80,9 @@ List of modules
   * **lattice_parameters.py** Estimation of lattice parameters for various lattice types using covalent/ionic radii.
   * **distorter.py** A collection of functions for enumerating and then
     substituting on inequivalent sites of a sub-lattice.
+  * **oxidation_states.py**: Used for predicting the likelihood of species coexisting in a compound based on a statistical model.
+  * **structure_prediction**: A submodule which contains a collection of tools for facilitating crystal structure predictions via ionic substitutions
+  * **dopant_prediction**: A submodule which contains a collections of tools for predicting n-type and p-type dopants.
 
 Requirements
 ------------
@@ -91,6 +97,12 @@ The latest stable release of SMACT can be installed via pip which will automatic
 
     pip install smact  
 
+SMACT is also available via conda through the conda-forge channel on Anaconda Cloud:
+
+```
+conda install -c conda-forge smact
+```
+
 Alternatively, the very latest version can be installed using:
 
     pip install git+git://github.com/WMD-group/SMACT.git

docs/conf.py

@@ -52,8 +52,8 @@
 
 # General information about the project.
 project = "Smact"
-copyright = "2016, Walsh Materials Design Group"
-author = "Walsh Materials Design Group"
+copyright = "2016, Materials Design Group"
+author = "Materials Design Group"
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
@@ -62,7 +62,7 @@
 # The short X.Y version.
 version = "2.5"
 # The full version, including alpha/beta/rc tags.
-release = "2.5.1"
+release = "2.5.5"
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

docs/examples.rst

@@ -2,8 +2,8 @@
 Examples
 ========
 
-Here we will give a demonstration of how to use some of `smact`'s features. For a full set of
-work-through examples in Jupyter notebook form check out
+Here we will give a demonstration of how to use some `smact` features. For a full set of
+work-through examples in Jupyter Notebook form check out
 `the examples section of our GitHub repo <https://github.com/WMD-group/SMACT/tree/master/examples>`_.
 For workflows that have been used in real examples and in published work, visit our
 `separate repository <https://github.com/WMD-group/smact_workflows>`_.
@@ -12,7 +12,7 @@ For workflows that have been used in real examples and in published work, visit
 Element and species classes
 ===========================
 
-The element and species classes are at the heart of :mod:`smact`'s functionality. Elements are the
+The element and species classes are at the heart of :mod:`smact` functionality. Elements are the
 elements of the periodic table. Species are elements, with some additional information; the
 oxidation state and the coordination environment (if known). So for example the element iron
 can have many oxidation states and those oxidation states can have many coordination
@@ -29,7 +29,7 @@ environments.
     The element Fe has 8 oxidation states. They are [-2, -1, 1, 2, 3, 4, 5, 6].
 
 When an element has an oxidation state and coordination environment then it has additional
-features. For example the Shannon radius [1]_ of the element, this is often useful for calculating
+features. For example, the Shannon radius [1]_ of the element is useful for calculating
 radius ratio rules [2]_, or for training neural networks [3]_ .
 
 .. code:: python
@@ -43,7 +43,7 @@ radius ratio rules [2]_, or for training neural networks [3]_ .
 List building
 =============
 
-Often when using :mod:`smact` the aim will to be to search over combinations of a set of elements. This
+Often when using :mod:`smact` the aim will be to search over combinations of a set of elements. This
 is most efficiently achieved by setting up a dictionary of the elements that you want to search
 over. The easiest way to achieve this in :mod:`smact` is to first create a list of the symbols of the elements
 that you want to include, then to build a dictionary of the corresponding element objects.
@@ -88,7 +88,7 @@ the search.
 Neutral combinations
 ====================
 
-One of the most basic tests for establishing sensible combinations of elements is that they should form charge neutral
+One of the most basic tests for establishing sensible combinations of elements is that they should form charge-neutral
 combinations. This is a straightforward combinatorial problem of comparing oxidation states and allowed stoichiometries.
 
 :math:`\Sigma_i Q_in_i = 0`
@@ -211,32 +211,30 @@ in function to calculate this property for a given composition.
 Interfacing to machine learning
 ===============================
 
-When preparing to do machine learning, we have to convert the compositions that we have into
+When preparing to build machine learning models, we have to convert the chemical compositions into
 something that can be fed into an algorithm. Many of the properties provided in :mod:`smact` are suitable for this,
-one can take properties like electronegativity, mass, electron affinity etc etc (for the full list see
+one can take properties like electronegativity, mass, electron affinity, etc. (for the full list see
 :ref:`smact_module`).
 
-One useful representation that is often used in machine learning is the one-hot-vector formulation. A similar
-construction to this can be used to encode a chemical formula. A vector of length of the periodic table is
-set up and each element set to be a number corresponding to the stoichiometric ratio of that element in the compound.
+One useful representation in machine learning is the one-hot-vector formulation. A similar
+construction to this can be used to encode a chemical formula. A vector of length covering the periodic table is
+constructed and each element is set to a number corresponding to the stoichiometric ratio of that element in the compound.
 For example we could convert :math:`Ba(OH)_2`
 
 .. code:: python
 
    ml_vector = smact.screening.ml_rep_generator(['Ba', 'H', 'O'], stoichs=[1, 2, 2])
 
 There is also `an example <https://github.com/WMD-group/SMACT/blob/master/examples/Counting/Generate_compositions_lists.ipynb>`_
-demonstrating the conversion of charge neutral compositions produced by `smact` to a list of formulas using Pymatgen,
+demonstrating the conversion of charge-neutral compositions produced by `smact` to a list of formulas using Pymatgen,
 or to a Pandas dataframe, both of which could then be used as input for a machine learning algorithm.
 For a full machine learning example that uses `smact`, there is a repository `here <https://github.com/WMD-group/Solar_oxides_data>`_ 
 which demonstrates a search for solar energy materials from the four-component (quaternary) oxide materials space.
 
-.. [1]  "Revised effective ionic radii and systematic studies of interatomic distances in halides and chalcogenides".
-         Acta Crystallogr A. 32: 751–767, 1976
+.. [1]  "Revised effective ionic radii and systematic studies of interatomic distances in halides and chalcogenides" Acta Cryst. A. **32**, 751–767 (1976).
 
-.. [2]  "Crystal Structure and Chemical Constitution" Trans. Faraday Soc. 25, 253-283, 1929.
+.. [2]  "Crystal structure and chemical constitution" Trans. Faraday Soc. **25**, 253-283 (1929).
 
-.. [3] "Deep neural networks for accurate predictions of crystal stability" Nat. Comms. 9, 3800, 2018.
+.. [3] "Deep neural networks for accurate predictions of crystal stability" Nat. Comms. **9**, 3800 (2018).
 
-.. [4] "Prediction of Flatband Potentials at Semiconductor‐Electrolyte Interfaces from Atomic Electronegativities"
-       J. Electrochem. Soc. 125, 228-32, 1975.
+.. [4] "Prediction of flatband potentials at semiconductor‐electrolyte interfaces from atomic electronegativities" J. Electrochem. Soc. **125**, 228-232 (1975).

docs/getting_started.rst

@@ -15,7 +15,7 @@ and `pymatgen <http://pymatgen.org>`_ are also required for many components.
 Installation
 ============
 
-The latest stable release of SMACT can be installed via pip which will automatically setup other Python packages as required:
+The latest stable release of SMACT can be installed via pip, which will automatically setup other Python packages as required:
 
 .. code::
 

docs/introduction.rst

@@ -3,25 +3,25 @@ Introduction
 ============
 
 :mod:`smact` is a collection of tools and examples for "low-fi" screening of
-potential semiconducting materials through the use of simple chemical
+potential semiconducting materials through the use of chemical
 rules.
 
 :mod:`smact` uses a combination of heuristics and models derived from data to
 rapidly search large areas of chemical space. This combination of methods
 allows :mod:`smact` to identify new materials for applications such as photovoltaics,
 water splitting and thermoelectrics. Read more about :mod:`smact` in our publications:
 
-- `Computational Screening of All Stoichiometric Inorganic Materials <https://www.sciencedirect.com/science/article/pii/S2451929416301553>`_
+- `Computational screening of all stoichiometric inorganic materials <https://www.sciencedirect.com/science/article/pii/S2451929416301553>`_
 - `Computer-aided design of metal chalcohalide semiconductors: from chemical composition to crystal structure <http://pubs.rsc.org/en/content/articlehtml/2017/sc/c7sc03961a>`_
 - `Materials discovery by chemical analogy: role of oxidation states in structure prediction <http://pubs.rsc.org/en/content/articlehtml/2018/fd/c8fd00032h>`_
 
-This approach is heavily inspired by the work of Harrison [1]_ and
-Pamplin [2]_. The work is an active project in the `Walsh Materials Design Group <http://wmd-group.github.io>`_.
+This approach is inspired by the work of Harrison [1]_ and
+Pamplin [2]_. The work is an active project in the `Materials Design Group <http://wmd-group.github.io>`_.
 
-SMACT is now available *via* :code:`pip install smact`.
+The package is available *via* :code:`pip install smact`.
 
-We are also developing a set of Jupyter notebook examples `here <https://github.com/WMD-group/SMACT/tree/master/examples>`_.
+We are also developing a set of Jupyter Notebook examples `here <https://github.com/WMD-group/SMACT/tree/master/examples>`_.
 
 .. [1] http://www.worldcat.org/oclc/5170450 Harrison, W. A. *Electronic structure and the properties of solids: the physics of the chemical bond* (1980)
 
-.. [2] http://dx.doi.org/10.1016/0022-3697(64)90176-3 Pamplin, B. R. *J. Phys. Chem. Solids* (1964) **7** 675--684
+.. [2] http://dx.doi.org/10.1016/0022-3697(64)90176-3 Pamplin, B. R. *A systematic method of deriving new semiconducting compounds by structural analogy* J. Phys. Chem. Solids **7**, 675--684 (1964)

docs/requirements.in

@@ -0,0 +1,4 @@
+# Defining the exact version will make sure things don't break
+sphinx==5.3.0
+sphinx_rtd_theme==1.1.1
+readthedocs-sphinx-search==0.1.1

docs/requirements.txt

@@ -0,0 +1,56 @@
+#
+# This file is autogenerated by pip-compile with Python 3.8
+# by the following command:
+#
+#    pip-compile
+#
+alabaster==0.7.13
+    # via sphinx
+babel==2.12.1
+    # via sphinx
+certifi==2023.7.22
+    # via requests
+charset-normalizer==3.2.0
+    # via requests
+docutils==0.17.1
+    # via
+    #   sphinx
+    #   sphinx-rtd-theme
+idna==3.4
+    # via requests
+imagesize==1.4.1
+    # via sphinx
+jinja2==3.1.2
+    # via sphinx
+markupsafe==2.1.3
+    # via jinja2
+packaging==23.1
+    # via sphinx
+pygments==2.16.1
+    # via sphinx
+readthedocs-sphinx-search==0.1.1
+    # via -r requirements.in
+requests==2.31.0
+    # via sphinx
+snowballstemmer==2.2.0
+    # via sphinx
+sphinx==5.3.0
+    # via
+    #   -r requirements.in
+    #   sphinx-rtd-theme
+sphinx-rtd-theme==1.1.1
+    # via -r requirements.in
+sphinxcontrib-applehelp==1.0.4
+    # via sphinx
+sphinxcontrib-devhelp==1.0.2
+    # via sphinx
+sphinxcontrib-htmlhelp==2.0.1
+    # via sphinx
+sphinxcontrib-jsmath==1.0.1
+    # via sphinx
+sphinxcontrib-qthelp==1.0.3
+    # via sphinx
+sphinxcontrib-serializinghtml==1.1.5
+    # via sphinx
+urllib3==2.0.7
+    # via requests

docs/smact.builder.rst

@@ -2,7 +2,7 @@ smact.builder module
 ====================
 
 A collection of functions for building certain lattice types.
-Currently there are examples here for the Perovskite and Wurzite lattice types,
+Currently, there are examples here for the perovskite and wurtzite structure types,
 which rely on the Atomic Simulation Environment (ASE)
 :func:`spacegroup.crystal` function.
 

docs/smact.dopant_prediction.doper.rst

@@ -1,7 +1,8 @@
 smact.dopant_prediction.doper module
 =============================
 
-A class to create possible n-type and p-type dopants
+A class to create possible n-type and p-type dopants according to 
+their accessible oxidation states.
 
 .. automodule:: smact.dopant_prediction.doper
     :members: