SMACT 2.5.2__tar.gz → 2.5.4__tar.gz

{SMACT-2.5.2 → SMACT-2.5.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: SMACT
-Version: 2.5.2
+Version: 2.5.4
 Summary: Semiconducting Materials by Analogy and Chemical Theory
 Home-page: https://github.com/WMD-group/SMACT
 Author: Daniel W. Davies
@@ -12,6 +12,7 @@ Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.8
 Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
 Classifier: Development Status :: 5 - Production/Stable
 Classifier: Intended Audience :: Science/Research
 Classifier: Operating System :: OS Independent
@@ -21,6 +22,13 @@ Classifier: Topic :: Scientific/Engineering :: Chemistry
 Requires-Python: >=3.8
 Description-Content-Type: text/markdown
 License-File: LICENSE
+Requires-Dist: scipy
+Requires-Dist: numpy
+Requires-Dist: spglib
+Requires-Dist: pymatgen
+Requires-Dist: ase
+Requires-Dist: pandas
+Requires-Dist: pathos
 
 [![DOI](http://joss.theoj.org/papers/10.21105/joss.01361/status.svg)](https://doi.org/10.21105/joss.01361)
 [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.5553202.svg)](https://doi.org/10.5281/zenodo.5553202)
@@ -29,6 +37,7 @@ License-File: LICENSE
 ![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)
@@ -83,7 +92,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
 -------
@@ -101,6 +112,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
 ------------
@@ -115,6 +129,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

SMACT-2.5.2/SMACT.egg-info/PKG-INFO → SMACT-2.5.4/README.md

@@ -1,27 +1,3 @@
-Metadata-Version: 2.1
-Name: SMACT
-Version: 2.5.2
-Summary: Semiconducting Materials by Analogy and Chemical Theory
-Home-page: https://github.com/WMD-group/SMACT
-Author: Daniel W. Davies
-Author-email: d.w.davies@imperial.ac.uk
-Maintainer: Anthony O. Onwuli
-Maintainer-email: anthony.onwuli16@imperial.ac.uk
-License: MIT
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.8
-Classifier: Programming Language :: Python :: 3.9
-Classifier: Programming Language :: Python :: 3.10
-Classifier: Development Status :: 5 - Production/Stable
-Classifier: Intended Audience :: Science/Research
-Classifier: Operating System :: OS Independent
-Classifier: License :: OSI Approved :: MIT License
-Classifier: Topic :: Scientific/Engineering
-Classifier: Topic :: Scientific/Engineering :: Chemistry
-Requires-Python: >=3.8
-Description-Content-Type: text/markdown
-License-File: LICENSE
-
 [![DOI](http://joss.theoj.org/papers/10.21105/joss.01361/status.svg)](https://doi.org/10.21105/joss.01361)
 [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.5553202.svg)](https://doi.org/10.5281/zenodo.5553202)
 [![Documentation Status](https://readthedocs.org/projects/smact/badge/?version=latest)](http://smact.readthedocs.org/en/latest/?badge=latest)
@@ -29,6 +5,7 @@ License-File: LICENSE
 ![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)
@@ -83,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
 -------
@@ -101,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
 ------------
@@ -115,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

SMACT-2.5.2/README.md → SMACT-2.5.4/SMACT.egg-info/PKG-INFO

@@ -1,3 +1,35 @@
+Metadata-Version: 2.1
+Name: SMACT
+Version: 2.5.4
+Summary: Semiconducting Materials by Analogy and Chemical Theory
+Home-page: https://github.com/WMD-group/SMACT
+Author: Daniel W. Davies
+Author-email: d.w.davies@imperial.ac.uk
+Maintainer: Anthony O. Onwuli
+Maintainer-email: anthony.onwuli16@imperial.ac.uk
+License: MIT
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Scientific/Engineering :: Chemistry
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: scipy
+Requires-Dist: numpy
+Requires-Dist: spglib
+Requires-Dist: pymatgen
+Requires-Dist: ase
+Requires-Dist: pandas
+Requires-Dist: pathos
+
 [![DOI](http://joss.theoj.org/papers/10.21105/joss.01361/status.svg)](https://doi.org/10.21105/joss.01361)
 [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.5553202.svg)](https://doi.org/10.5281/zenodo.5553202)
 [![Documentation Status](https://readthedocs.org/projects/smact/badge/?version=latest)](http://smact.readthedocs.org/en/latest/?badge=latest)
@@ -5,6 +37,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 +92,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 +112,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 +129,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

{SMACT-2.5.2 → SMACT-2.5.4}/setup.py

@@ -5,10 +5,10 @@ __author_email__ = "d.w.davies@imperial.ac.uk"
 __copyright__ = (
     "Copyright Daniel W. Davies, Adam J. Jackson, Keith T. Butler (2019)"
 )
-__version__ = "2.5.2"
+__version__ = "2.5.4"
 __maintainer__ = "Anthony O. Onwuli"
 __maintaier_email__ = "anthony.onwuli16@imperial.ac.uk"
-__date__ = "July 13 2023"
+__date__ = "November 30 2023"
 
 import os
 import unittest
@@ -61,6 +61,7 @@ if __name__ == "__main__":
             "Programming Language :: Python :: 3.8",
             "Programming Language :: Python :: 3.9",
             "Programming Language :: Python :: 3.10",
+            "Programming Language :: Python :: 3.11",
             "Development Status :: 5 - Production/Stable",
             "Intended Audience :: Science/Research",
             "Operating System :: OS Independent",

{SMACT-2.5.2 → SMACT-2.5.4}/smact/__init__.py

@@ -59,6 +59,8 @@ class Element:
 
         Element.oxidation_states_wiki (list): List of oxidation states that appear wikipedia (https://en.wikipedia.org/wiki/Template:List_of_oxidation_states_of_the_elements) Data retrieved: 2022-09-22
 
+        Element.oxidation_states_custom (list | None ): List of oxidation states that appear in the custom data file supplied (if any)
+
         Element.coord_envs (list): The allowed coordination enviroments for the ion
 
         Element.covalent_radius (float) : Covalent radius of the element
@@ -77,15 +79,35 @@ class Element:
 
     """
 
-    def __init__(self, symbol: str):
+    def __init__(
+        self, symbol: str, oxi_states_custom_filepath: Optional[str] = None
+    ):
         """Initialise Element class
 
         Args:
             symbol (str): Chemical element symbol (e.g. 'Fe')
+            oxi_states_custom_filepath (str): Path to custom oxidation states file
 
         """
+        # Get the oxidation states from the custom file if it exists
+        if oxi_states_custom_filepath:
+            try:
+                self._oxidation_states_custom = (
+                    data_loader.lookup_element_oxidation_states_custom(
+                        symbol, oxi_states_custom_filepath
+                    )
+                )
+                self.oxidation_states_custom = self._oxidation_states_custom
+            except TypeError:
+                warnings.warn(
+                    "Custom oxidation states file not found. Please check the file path."
+                )
+                self.oxidation_states_custom = None
+        else:
+            self.oxidation_states_custom = None
+        self.symbol = symbol
 
-        dataset = data_loader.lookup_element_data(symbol, copy=False)
+        dataset = data_loader.lookup_element_data(self.symbol, copy=False)
 
         if dataset == None:
             raise NameError(f"Elemental data for {symbol} not found.")
@@ -307,7 +329,10 @@ def ordered_elements(x: int, y: int) -> List[str]:
     return ordered_elements
 
 
-def element_dictionary(elements: Optional[Iterable[str]] = None):
+def element_dictionary(
+    elements: Optional[Iterable[str]] = None,
+    oxi_states_custom_filepath: Optional[str] = None,
+):
     """
     Create a dictionary of initialised smact.Element objects
 
@@ -317,13 +342,22 @@ def element_dictionary(elements: Optional[Iterable[str]] = None):
     Args:
         elements (iterable of strings) : Elements to include. If None,
             use all elements up to 103.
+        oxi_states_custom_filepath (str): Path to custom oxidation states file
+
+
     Returns:
         dict: Dictionary with element symbols as keys and smact.Element
             objects as data
     """
     if elements == None:
         elements = ordered_elements(1, 103)
-    return {symbol: Element(symbol) for symbol in elements}
+    if oxi_states_custom_filepath:
+        return {
+            symbol: Element(symbol, oxi_states_custom_filepath)
+            for symbol in elements
+        }
+    else:
+        return {symbol: Element(symbol) for symbol in elements}
 
 
 def are_eq(A: list, B: list, tolerance: float = 1e-4):

{SMACT-2.5.2 → SMACT-2.5.4}/smact/data/element_data.txt

@@ -97,7 +97,7 @@ Kr       Krypton      36    83.7980000000 1.16   None        -13.00    -26.50  1
 Rb       Rubidium     37    85.4678000000 2.20   0.485916      None     -3.94  9.00e+01  0.82    4.177128         316.20
 Sr       Strontium    38    87.6200000000 1.95   0.05206       None     -5.00  3.70e+02  0.95    5.69486720       190.82
 Y        Yttrium      39    88.9058400000 1.90   0.307         None     -5.53  3.30e+01  1.22    6.21726          153.00
-Zr       Zirconium    40    91.2240000000 1.75   0.426         None      None  1.65e+02  0.33    6.63390          121.00
+Zr       Zirconium    40    91.2240000000 1.75   0.426         None      None  1.65e+02  1.33    6.63390          121.00
 Nb       Niobium      41    92.9063700000 1.64   0.893         None      None  2.20e+02  1.6     6.75885          106.00
 Mo       Molybdenum   42    95.9500000000 1.54   0.7472        None      None  1.20e+00  2.16    7.09243          72.50
 Tc       Technetium   43    98.0000000000 1.47   0.55          None      None      None  2.10    7.11938          80.40

{SMACT-2.5.2 → SMACT-2.5.4}/smact/data_loader.py

@@ -269,6 +269,59 @@ def lookup_element_oxidation_states_wiki(symbol, copy=True):
         return None
 
 
+_el_ox_states_custom = None
+
+
+def lookup_element_oxidation_states_custom(symbol, filepath, copy=True):
+    """
+    Retrieve a list of known oxidation states for an element.
+    The oxidation states list is specified by the user in a text file.
+
+    Args:
+        symbol (str) : the atomic symbol of the element to look up.
+        copy (Optional(bool)): if True (default), return a copy of the
+            oxidation-state list, rather than a reference to the cached
+            data -- only use copy=False in performance-sensitive code
+            and where the list will not be modified!
+
+    Returns:
+        list: List of known oxidation states for the element.
+
+            Return None if oxidation states for the Element were not
+            found in the external data.
+    """
+
+    global _el_ox_states_custom
+
+    if _el_ox_states_custom is None:
+        _el_ox_states_custom = {}
+
+        for items in _get_data_rows(filepath):
+            _el_ox_states_custom[items[0]] = [
+                int(oxidationState) for oxidationState in items[1:]
+            ]
+
+    if symbol in _el_ox_states_custom:
+        if copy:
+            # _el_ox_states_custom stores lists -> if copy is set, make an implicit
+            # deep copy.  The elements of the lists are integers, which are
+            # "value types" in Python.
+
+            return [
+                oxidationState
+                for oxidationState in _el_ox_states_custom[symbol]
+            ]
+        else:
+            return _el_ox_states_custom[symbol]
+    else:
+        if _print_warnings:
+            print(
+                "WARNING: Oxidation states for element {} "
+                "not found.".format(symbol)
+            )
+        return None
+
+
 # Loader and cache for the element HHI scores.
 
 _element_hhis = None
@@ -367,9 +420,7 @@ def lookup_element_data(symbol, copy=True):
             # or, if not clearly a number, to None
             clean_items = items[0:2] + list(map(float_or_None, items[2:]))
 
-            _element_data.update(
-                {items[0]: dict(list(zip(keys, clean_items)))}
-            )
+            _element_data.update({items[0]: dict(list(zip(keys, clean_items)))})
 
     if symbol in _element_data:
         if copy:
@@ -384,9 +435,7 @@ def lookup_element_data(symbol, copy=True):
             return _element_data[symbol]
     else:
         if _print_warnings:
-            print(
-                "WARNING: Elemental data for {}" " not found.".format(symbol)
-            )
+            print("WARNING: Elemental data for {}" " not found.".format(symbol))
             print(_element_data)
         return None
 
@@ -471,9 +520,7 @@ def lookup_element_shannon_radius_data(symbol, copy=True):
             # function on each element.
             # The dictionary values are all Python "value types", so
             # nothing further is required to make a deep copy.
-            return [
-                item.copy() for item in _element_shannon_radii_data[symbol]
-            ]
+            return [item.copy() for item in _element_shannon_radii_data[symbol]]
         else:
             return _element_shannon_radii_data[symbol]
     else:

SMACT-2.5.4/smact/dopant_prediction/doper.py

@@ -0,0 +1,212 @@
+from typing import List, Tuple
+
+from pymatgen.util import plotting
+
+import smact
+from smact.structure_prediction import mutation, utilities
+
+
+class Doper:
+    """
+    A class to search for n & p type dopants
+    Methods: get_dopants, plot_dopants
+
+    Attributes:
+        _original_species: A tuple which describes the constituent species of a material. For example:
+
+            >>> test= Doper(("Zn2+","S2-"))
+            >>> test.original_species
+                ('Zn2+','S2-')
+
+    """
+
+    def __init__(
+        self, _original_species: Tuple[str, ...], filepath: str = None
+    ):
+        """
+        Intialise the `Doper` class with a tuple of species
+
+        Args:
+            _original_species: See :class:`~.Doper`.
+            filepath (str): lambda table json file
+
+        """
+        self._original_species = _original_species
+        self._filepath = filepath
+
+    @property
+    def original_species(self):
+        return self._original_species
+
+    @original_species.setter
+    def original_species(self, original_species):
+        self._original_species = original_species
+
+    @property
+    def filepath(self):
+        return self._filepath
+
+    @filepath.setter
+    def filepath(self, filepath):
+        self._filepath = filepath
+
+    def _get_cation_dopants(
+        self, element_objects: List[smact.Element], cations: List[str]
+    ):
+        poss_n_type_cat = set()
+        poss_p_type_cat = set()
+
+        for element in element_objects:
+            # [-2, -1, 0, +1, +2]
+            oxi_state = element.oxidation_states
+            el_symbol = element.symbol
+            for state in oxi_state:
+                for cation in cations:
+                    ele = utilities.unparse_spec((el_symbol, state))
+                    _, charge = utilities.parse_spec(cation)
+                    if state > charge:
+                        poss_n_type_cat.add(ele)
+                    elif state < charge and state > 0:
+                        poss_p_type_cat.add(ele)
+
+        return list(poss_n_type_cat), list(poss_p_type_cat)
+
+    def _get_anion_dopants(
+        self, element_objects: List[smact.Element], anions: List[str]
+    ):
+        poss_n_type_an = set()
+        poss_p_type_an = set()
+
+        for element in element_objects:
+            oxi_state = element.oxidation_states
+            el_symbol = element.symbol
+            for state in oxi_state:
+                for anion in anions:
+                    ele = utilities.unparse_spec((el_symbol, state))
+                    _, charge = utilities.parse_spec(anion)
+                    if state > charge and state < 0:
+                        poss_n_type_an.add(ele)
+                    elif state < charge:
+                        poss_p_type_an.add(ele)
+        return list(poss_n_type_an), list(poss_p_type_an)
+
+    def get_dopants(
+        self,
+        num_dopants: int = 5,
+    ) -> dict:
+        """
+        Args:
+            num_dopants (int): The number of suggestions to return for n- and p-type dopants.
+        Returns:
+            (dict): Dopant suggestions, given as a dictionary with keys
+            "n_type_cation", "p_type_cation", "n_type_anion", "p_type_anion".
+
+        Examples:
+            >>> test = Doper(('Ti4+','O2-'))
+            >>> print(test.get_dopants(num_dopants=2))
+                {'n-type cation substitutions': [('Ta5+', 8.790371775858281e-05),
+                ('Nb5+', 7.830035204694342e-05)],
+                'p-type cation substitutions': [('Na1+', 0.00010060400812977031),
+                ('Zn2+', 8.56373996146833e-05)],
+                'n-type anion substitutions': [('F1-', 0.01508116810515677),
+                ('Cl1-', 0.004737202729901607)],
+                'p-type anion substitutions': [('N3-', 0.0014663800608945628),
+                ('C4-', 9.31310255126729e-08)]}
+        """
+
+        cations = []
+        anions = []
+        try:
+            for ion in self._original_species:
+                _, charge = utilities.parse_spec(ion)
+                if charge > 0:
+                    cations.append(ion)
+                elif charge < 0:
+                    anions.append(ion)
+        except Exception as e:
+            print(f"{e}: charge is not defined for {ion}!")
+
+        CM = mutation.CationMutator.from_json(self._filepath)
+
+        # call all elements
+        element_objects = list(smact.element_dictionary().values())
+
+        poss_n_type_cat, poss_p_type_cat = self._get_cation_dopants(
+            element_objects, cations
+        )
+        poss_n_type_an, poss_p_type_an = self._get_anion_dopants(
+            element_objects, anions
+        )
+
+        n_type_cat, p_type_cat, n_type_an, p_type_an = [], [], [], []
+        for cation in cations:
+            cation_charge = utilities.parse_spec(cation)[1]
+            for n_specie in poss_n_type_cat:
+                n_specie_charge = utilities.parse_spec(n_specie)[1]
+                if cation_charge >= n_specie_charge:
+                    continue
+                n_type_cat.append(
+                    (n_specie, cation, CM.sub_prob(cation, n_specie))
+                )
+            for p_specie in poss_p_type_cat:
+                p_specie_charge = utilities.parse_spec(p_specie)[1]
+                if cation_charge <= p_specie_charge:
+                    continue
+                p_type_cat.append(
+                    (p_specie, cation, CM.sub_prob(cation, p_specie))
+                )
+
+        for anion in anions:
+            anion_charge = utilities.parse_spec(anion)[1]
+            for n_specie in poss_n_type_an:
+                n_specie_charge = utilities.parse_spec(n_specie)[1]
+                if anion == n_specie or anion_charge >= n_specie_charge:
+                    continue
+                n_type_an.append(
+                    (n_specie, anion, CM.sub_prob(anion, n_specie))
+                )
+            for p_specie in poss_p_type_an:
+                p_specie_charge = utilities.parse_spec(p_specie)[1]
+                if anion == p_specie or anion_charge <= p_specie_charge:
+                    continue
+                p_type_an.append(
+                    (p_specie, anion, CM.sub_prob(anion, p_specie))
+                )
+
+        # [('B3+', 0.003), ('C4+', 0.001), (), (), ...] : list(tuple(str, float))
+        # sort by probability
+        n_type_cat.sort(key=lambda x: x[-1], reverse=True)
+        p_type_cat.sort(key=lambda x: x[-1], reverse=True)
+        n_type_an.sort(key=lambda x: x[-1], reverse=True)
+        p_type_an.sort(key=lambda x: x[-1], reverse=True)
+
+        self.results = {
+            "n-type cation substitutions": n_type_cat[:num_dopants],
+            "p-type cation substitutions": p_type_cat[:num_dopants],
+            "n-type anion substitutions": n_type_an[:num_dopants],
+            "p-type anion substitutions": p_type_an[:num_dopants],
+        }
+        # return the top (num_dopants) results for each case
+        return self.results
+
+    def plot_dopants(self) -> None:
+        """
+        Uses pymatgen plotting utilities to plot the results of doping search
+        Args:
+            None
+        Returns:
+            None
+        """
+        try:
+            for val in self.results.values():
+                dict_results = {
+                    utilities.parse_spec(x)[0]: y for x, _, y in val
+                }
+                plotting.periodic_table_heatmap(
+                    elemental_data=dict_results,
+                    cmap="rainbow",
+                    blank_color="gainsboro",
+                    edge_color="white",
+                )
+        except AttributeError as e:
+            print(f"Dopants are not calculated. Run get_dopants first.")

{SMACT-2.5.2 → SMACT-2.5.4}/smact/screening.py

@@ -1,10 +1,14 @@
 import itertools
+import os
 import warnings
 from collections import namedtuple
 from itertools import combinations
 from typing import Iterable, List, Optional, Tuple, Union
 
 from smact import Element, neutral_ratios
+from smact.data_loader import (
+    lookup_element_oxidation_states_custom as oxi_custom,
+)
 
 # Use named tuple to improve readability of smact_filter outputs
 _allowed_compositions = namedtuple(
@@ -324,7 +328,7 @@ def smact_filter(
         threshold (int): Threshold for stoichiometry limit, default = 8
         stoichs (list[int]): A selection of valid stoichiometric ratios for each site.
         species_unique (bool): Whether or not to consider elements in different oxidation states as unique in the results.
-        oxidation_states_set (string): A string to choose which set of oxidation states should be chosen. Options are 'default', 'icsd', 'pymatgen' and 'wiki' for the default, icsd, pymatgen structure predictor and Wikipedia (https://en.wikipedia.org/wiki/Template:List_of_oxidation_states_of_the_elements) oxidation states respectively.
+        oxidation_states_set (string): A string to choose which set of oxidation states should be chosen. Options are 'default', 'icsd', 'pymatgen' and 'wiki' for the default, icsd, pymatgen structure predictor and Wikipedia (https://en.wikipedia.org/wiki/Template:List_of_oxidation_states_of_the_elements) oxidation states respectively. A filepath to an oxidation states text file can also be supplied as well.
         comp_tuple (bool): Whether or not to return the results as a named tuple of elements and stoichiometries (True) or as a normal tuple of elements and stoichiometries (False).
     Returns:
         allowed_comps (list): Allowed compositions for that chemical system
@@ -371,10 +375,12 @@ def smact_filter(
     }
     if oxidation_states_set in oxi_set:
         ox_combos = oxi_set[oxidation_states_set]
+    elif os.path.exists(oxidation_states_set):
+        ox_combos = [oxi_custom(e.symbol, oxidation_states_set) for e in els]
     else:
         raise (
             Exception(
-                f'{oxidation_states_set} is not valid. Enter either "default", "icsd", "pymatgen" or "wiki" for oxidation_states_set.'
+                f'{oxidation_states_set} is not valid. Enter either "default", "icsd", "pymatgen","wiki" or a filepath to a textfile of oxidation states.'
             )
         )
     if oxidation_states_set == "wiki":

{SMACT-2.5.2 → SMACT-2.5.4}/smact/structure_prediction/database.py

@@ -202,9 +202,7 @@ class StructureDB:
 
         return num
 
-    def get_structs(
-        self, composition: str, table: str
-    ) -> List[SmactStructure]:
+    def get_structs(self, composition: str, table: str) -> List[SmactStructure]:
         """Get SmactStructures for a given composition.
 
         Args:

{SMACT-2.5.2 → SMACT-2.5.4}/smact/structure_prediction/mutation.py

@@ -373,8 +373,7 @@ class CationMutator:
     def cond_sub_prob(self, s1: str, s2: str) -> float:
         """Calculate the probability of substitution of one species with another."""
         return (
-            np.exp(self.get_lambda(s1, s2))
-            / np.exp(self.get_lambdas(s2)).sum()
+            np.exp(self.get_lambda(s1, s2)) / np.exp(self.get_lambdas(s2)).sum()
         )
 
     def cond_sub_probs(self, s1: str) -> pd.Series:

{SMACT-2.5.2 → SMACT-2.5.4}/smact/structure_prediction/prediction.py

@@ -183,8 +183,7 @@ class StructurePredictor:
         sub_species = list(map(list, sub_species))
 
         potential_nary_parents: List[List[SmactStructure]] = list(
-            self.db.get_with_species(specs, self.table)
-            for specs in sub_species
+            self.db.get_with_species(specs, self.table) for specs in sub_species
         )
 
         for spec_idx, parents in enumerate(potential_nary_parents):

{SMACT-2.5.2 → SMACT-2.5.4}/smact/structure_prediction/structure.py

@@ -274,9 +274,12 @@ class SmactStructure:
                 )
                 struct = oxi_transform.apply_transformation(structure)
                 print("Oxidation states assigned based on ICSD statistics")
+        elif determine_oxi == "predecorated":
+            struct = structure
+
         else:
             raise ValueError(
-                f"Argument for 'determine_oxi', <{determine_oxi}> is not valid. Choose either 'BV','comp_ICSD' or 'both'."
+                f"Argument for 'determine_oxi', <{determine_oxi}> is not valid. Choose either 'BV','comp_ICSD','both' or 'predecorated'."
             )
 
         sites, species = SmactStructure.__parse_py_sites(struct)
@@ -433,10 +436,7 @@ class SmactStructure:
         lattice_param = float(lines[1])
 
         lattice = np.array(
-            [
-                [float(point) for point in line.split(" ")]
-                for line in lines[2:5]
-            ]
+            [[float(point) for point in line.split(" ")] for line in lines[2:5]]
         )
 
         sites = defaultdict(list)

{SMACT-2.5.2 → SMACT-2.5.4}/smact/tests/test_core.py

@@ -15,12 +15,17 @@ from smact import Species
 from smact.builder import wurtzite
 from smact.properties import band_gap_Harrison, compound_electroneg
 
+files_dir = os.path.join(os.path.dirname(os.path.realpath(__file__)), "files")
+TEST_OX_STATES = os.path.join(files_dir, "test_oxidation_states.txt")
+
 
 class TestSequenceFunctions(unittest.TestCase):
     # ---------------- TOP-LEVEL ----------------
 
     def test_Element_class_Pt(self):
-        Pt = smact.Element("Pt")
+        Pt = smact.Element(
+            "Pt",
+        )
         self.assertEqual(Pt.name, "Platinum")
         self.assertEqual(Pt.ionpot, 8.95883)
         self.assertEqual(Pt.number, 78)
@@ -34,9 +39,10 @@ class TestSequenceFunctions(unittest.TestCase):
 
     def test_element_dictionary(self):
         newlist = ["O", "Rb", "W"]
-        dictionary = smact.element_dictionary(newlist)
+        dictionary = smact.element_dictionary(newlist, TEST_OX_STATES)
         self.assertEqual(dictionary["O"].crustal_abundance, 461000.0)
         self.assertEqual(dictionary["Rb"].oxidation_states, [-1, 1])
+        self.assertEqual(dictionary["Rb"].oxidation_states_custom, [-1, 1])
         self.assertEqual(dictionary["W"].name, "Tungsten")
         self.assertTrue("Rn" in smact.element_dictionary())
 
@@ -46,9 +52,7 @@ class TestSequenceFunctions(unittest.TestCase):
                 [1.00, 2.00, 3.00], [1.001, 1.999, 3.00], tolerance=1e-2
             )
         )
-        self.assertFalse(
-            smact.are_eq([1.00, 2.00, 3.00], [1.001, 1.999, 3.00])
-        )
+        self.assertFalse(smact.are_eq([1.00, 2.00, 3.00], [1.001, 1.999, 3.00]))
 
     def test_gcd_recursive(self):
         self.assertEqual(smact._gcd_recursive(4, 12, 10, 32), 2)
@@ -346,6 +350,12 @@ class TestSequenceFunctions(unittest.TestCase):
                 (("Na", "Fe", "Cl"), (1, 1, -1), (1, 1, 2)),
             ],
         )
+        self.assertEqual(
+            result,
+            smact.screening.smact_filter(
+                [Na, Fe, Cl], threshold=2, oxidation_states_set=TEST_OX_STATES
+            ),
+        )
         result_comp_tuple = smact.screening.smact_filter(
             [Na, Fe, Cl], threshold=2, comp_tuple=True
         )

{SMACT-2.5.2 → SMACT-2.5.4}/smact/tests/test_structure.py

@@ -363,9 +363,7 @@ class CationMutatorTest(unittest.TestCase):
         """Set up the test initial structure and mutator."""
         cls.test_struct = SmactStructure.from_file(TEST_POSCAR)
 
-        cls.test_mutator = CationMutator.from_json(
-            lambda_json=TEST_LAMBDA_JSON
-        )
+        cls.test_mutator = CationMutator.from_json(lambda_json=TEST_LAMBDA_JSON)
         cls.test_pymatgen_mutator = CationMutator.from_json(
             lambda_json=None, alpha=lambda x, y: -5
         )

SMACT-2.5.2/smact/dopant_prediction/doper.py

@@ -1,186 +0,0 @@
-### This Jupyter notebook creates ntype ptype possiblie dopants for input species
-### using SMACT structure prediction
-### Working with Kieth from SCIML and Anthony
-
-###Doper ver 2
-
-# Now 'Doper' can generate possible n-type p-type dopants for multicomponent materials (i.e. Ternary, Quaternary etc).
-# Can plot the result of doping search within a single step
-# """ex) test= Doper(('Cu1+','Zn2+','Ge4+','S2-'))
-#         test.get_dopants(num_dopants = 10, plot_heatmap = True)"""
-
-
-from typing import List, Tuple
-
-from pymatgen.util import plotting
-
-import smact
-from smact.structure_prediction import mutation, utilities
-
-
-class Doper:
-    """
-    A class to search for n & p type dopants
-    Methods: get_dopants, plot_dopants
-
-    Attributes:
-        original_species: A tuple which describes the constituent species of a material. For example:
-
-            >>> test= Doper(('Cu1+','Zn2+','Ge4+','S2-'))
-            >>> test.original_species
-                ('Cu1+','Zn2+','Ge4+','S2-')
-
-    """
-
-    def __init__(self, original_species: Tuple[str, ...]):
-        """
-        Intialise the `Doper` class with a tuple of species
-
-        Args:
-            original_species: See :class:`~.Doper`.
-
-        """
-        self.original_species = original_species
-
-    def _get_cation_dopants(
-        self, element_objects: List[smact.Element], cations: List[str]
-    ):
-        poss_n_type_cat = []
-        poss_p_type_cat = []
-
-        for element in element_objects:
-            # [-2, -1, 0, +1, +2]
-            oxi_state = element.oxidation_states
-            el_symbol = element.symbol
-            for state in oxi_state:
-                for cation in cations:
-                    _, charge = utilities.parse_spec(cation)
-                    if state > charge:
-                        poss_n_type_cat.append(
-                            utilities.unparse_spec((el_symbol, state))
-                        )
-                    elif state < charge and state > 0:
-                        poss_p_type_cat.append(
-                            utilities.unparse_spec((el_symbol, state))
-                        )
-
-        return poss_n_type_cat, poss_p_type_cat
-
-    def _get_anion_dopants(
-        self, element_objects: List[smact.Element], anions: List[str]
-    ):
-        poss_n_type_an = []
-        poss_p_type_an = []
-
-        for element in element_objects:
-            oxi_state = element.oxidation_states
-            el_symbol = element.symbol
-            for state in oxi_state:
-                for anion in anions:
-                    _, charge = utilities.parse_spec(anion)
-                    if state > charge and state < 0:
-                        poss_n_type_an.append(
-                            utilities.unparse_spec((el_symbol, state))
-                        )
-                    elif state < charge:
-                        poss_p_type_an.append(
-                            utilities.unparse_spec((el_symbol, state))
-                        )
-        return poss_n_type_an, poss_p_type_an
-
-    def _plot_dopants(self, results: dict):
-        """
-        Uses pymatgen plotting utilities to plot the results of doping search
-        """
-        for key, val in results.items():
-            dict_results = {utilities.parse_spec(x)[0]: y for x, y in val}
-            plotting.periodic_table_heatmap(
-                elemental_data=dict_results,
-                cmap="rainbow",
-                blank_color="gainsboro",
-                edge_color="white",
-            )
-
-    def get_dopants(
-        self,
-        num_dopants: int = 5,
-        plot_heatmap: bool = False,
-    ) -> dict:
-        """
-        Args:
-            num_dopants (int): The number of suggestions to return for n- and p-type dopants.
-            plot_heatmap (bool): If True, the results of the doping search are plotted as heatmaps
-
-        Returns:
-            (dict): Dopant suggestions, given as a dictionary with keys
-            "n_type_cation", "p_type_cation", "n_type_anion", "p_type_anion".
-
-        Examples:
-            >>> test = Doper(('Ti4+','O2-'))
-            >>> print(test.get_dopants(num_dopants=2))
-                {'n-type cation substitutions': [('Ta5+', 8.790371775858281e-05),
-                ('Nb5+', 7.830035204694342e-05)],
-                'p-type cation substitutions': [('Na1+', 0.00010060400812977031),
-                ('Zn2+', 8.56373996146833e-05)],
-                'n-type anion substitutions': [('F1-', 0.01508116810515677),
-                ('Cl1-', 0.004737202729901607)],
-                'p-type anion substitutions': [('N3-', 0.0014663800608945628),
-                ('C4-', 9.31310255126729e-08)]}
-        """
-
-        cations = []
-        anions = []
-        try:
-            for ion in self.original_species:
-                _, charge = utilities.parse_spec(ion)
-                if charge > 0:
-                    cations.append(ion)
-                elif charge < 0:
-                    anions.append(ion)
-        except Exception as e:
-            print(e, "charge is not defined")
-
-        CM = mutation.CationMutator.from_json()
-
-        # call all elements
-        element_objects = list(smact.element_dictionary().values())
-
-        poss_n_type_cat, poss_p_type_cat = self._get_cation_dopants(
-            element_objects, cations
-        )
-        poss_n_type_an, poss_p_type_an = self._get_anion_dopants(
-            element_objects, anions
-        )
-
-        n_type_cat, p_type_cat, n_type_an, p_type_an = [], [], [], []
-        for cation in cations:
-            for n_specie, p_specie in zip(poss_n_type_cat, poss_p_type_cat):
-                n_type_cat.append((n_specie, CM.sub_prob(cation, n_specie)))
-                p_type_cat.append((p_specie, CM.sub_prob(cation, p_specie)))
-
-        for anion in anions:
-            for n_specie, p_specie in zip(poss_n_type_an, poss_p_type_an):
-                n_type_an.append((n_specie, CM.sub_prob(anion, n_specie)))
-                p_type_an.append((p_specie, CM.sub_prob(anion, p_specie)))
-
-        # [('B3+', 0.003), ('C4+', 0.001), (), (), ...] : list(tuple(str, float))
-        # sort by probability
-        n_type_cat.sort(key=lambda x: x[1], reverse=True)
-        p_type_cat.sort(key=lambda x: x[1], reverse=True)
-        n_type_an.sort(key=lambda x: x[1], reverse=True)
-        p_type_an.sort(key=lambda x: x[1], reverse=True)
-
-        results = {
-            "n-type cation substitutions": n_type_cat[:num_dopants],
-            "p-type cation substitutions": p_type_cat[:num_dopants],
-            "n-type anion substitutions": n_type_an[:num_dopants],
-            "p-type anion substitutions": p_type_an[:num_dopants],
-        }
-
-        # plot heatmap
-
-        if plot_heatmap:
-            self._plot_dopants(results)
-
-        # return the top (num_dopants) results for each case
-        return results