Develop branch updates in preparation for new release

docs/conf.py

@@ -60,9 +60,9 @@
 # built documents.
 #
 # The short X.Y version.
-version = "2.6"
+version = "2.7"
 # The full version, including alpha/beta/rc tags.
-release = "2.6.0"
+release = "2.7.0"
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

setup.py

@@ -1,14 +1,15 @@
 #!/usr/bin/env python
 
-__author__ = "Daniel W. Davies"
-__author_email__ = "d.w.davies@imperial.ac.uk"
+__author__ = "The SMACT Developers"
+__author_email__ = "a.walsh@imperial.ac.uk"
 __copyright__ = (
     "Copyright Daniel W. Davies, Adam J. Jackson, Keith T. Butler (2019)"
 )
-__version__ = "2.6"
+__version__ = "2.7"
 __maintainer__ = "Anthony O. Onwuli"
-__maintaier_email__ = "[email protected]"
-__date__ = "July 10 2024"
+__maintainer_email__ = "[email protected]"
+__date__ = "August 30 2024"
+
 
 import os
 import unittest
@@ -28,7 +29,7 @@
         author=__author__,
         author_email=__author_email__,
         maintainer=__maintainer__,
-        maintainer_email=__maintaier_email__,
+        maintainer_email=__maintainer_email__,
         license="MIT",
         packages=[
             "smact",

smact/__init__.py

@@ -53,9 +53,11 @@ class Element:
 
         Element.oxidation_states (list) : Default list of allowed oxidation states for use in SMACT
 
-        Element.oxidation_states_sp (list) : List of oxdation states recognised by the Pymatgen Structure Predictor
+        Element.oxidation_states_smact14 (list): Original list of oxidation states that were manually compiled for SMACT in 2014 (default in SMACT < 3.0)
 
-        Element.oxidation_states_icsd (list) : List of oxidation states that appear in the ICSD
+        Element.oxidation_states_sp (list) : List of oxidation states recognised by the Pymatgen Structure Predictor
+
+        Element.oxidation_states_icsd (list) : List of oxidation states that appear in the 2016 version of ICSD
 
         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
 
@@ -165,10 +167,9 @@ def __init__(
             num_valence = None
 
         valence_data = data_loader.lookup_element_valence_data(symbol)
-        if valence_data:
-            num_valence_modified = valence_data["NValence"]
-        else:
-            num_valence_modified = None
+        num_valence_modified = (
+            valence_data["NValence"] if valence_data else None
+        )
 
         for attribute, value in (
             ("coord_envs", coord_envs),
@@ -187,6 +188,10 @@ def __init__(
                 "oxidation_states",
                 data_loader.lookup_element_oxidation_states(symbol),
             ),
+            (
+                "oxidation_states_smact14",
+                data_loader.lookup_element_oxidation_states(symbol),
+            ),
             (
                 "oxidation_states_icsd",
                 data_loader.lookup_element_oxidation_states_icsd(symbol),

smact/properties.py

@@ -1,6 +1,3 @@
-import csv
-import re
-from collections import defaultdict
 from typing import List, Optional, Union
 
 import numpy as np
@@ -165,7 +162,7 @@ def compound_electroneg(
 
 def valence_electron_count(compound: str) -> float:
     """
-    Calculate the Valence Electron Count (VEC) for a given compound.
+    Calculate the Valence Electron Count (VEC) for a given chemical compound.
 
     This function parses the input compound, extracts the elements and their
     stoichiometries, and calculates the VEC using the valence electron data

smact/screening.py

@@ -321,19 +321,23 @@ def smact_filter(
     threshold: Optional[int] = 8,
     stoichs: Optional[List[List[int]]] = None,
     species_unique: bool = True,
-    oxidation_states_set: str = "default",
+    oxidation_states_set: str = "smact14",
     comp_tuple: bool = False,
 ) -> Union[List[Tuple[str, int, int]], List[Tuple[str, int]]]:
     """Function that applies the charge neutrality and electronegativity
     tests in one go for simple application in external scripts that
     wish to apply the general 'smact test'.
 
+     .. warning::
+        For backwards compatability in SMACT >=2.7, expllicitly set oxidation_states_set to 'smact14' if you wish to use the 2014 SMACT default oxidation states.
+        In SMACT 3.0, the smact_filter function will be set to use a new default oxidation states set.
+
     Args:
         els (tuple/list): A list of smact.Element objects
         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. A filepath to an oxidation states text file can also be supplied as well.
+        oxidation_states_set (string): A string to choose which set of oxidation states should be chosen. Options are 'smact14', 'icsd', 'pymatgen' and 'wiki' for the  2014 SMACT default, 2016 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
@@ -373,7 +377,7 @@ def smact_filter(
 
     # Select the specified oxidation states set:
     oxi_set = {
-        "default": [e.oxidation_states for e in els],
+        "smact14": [e.oxidation_states_smact14 for e in els],
         "icsd": [e.oxidation_states_icsd for e in els],
         "pymatgen": [e.oxidation_states_sp for e in els],
         "wiki": [e.oxidation_states_wiki for e in els],
@@ -385,7 +389,7 @@ def smact_filter(
     else:
         raise (
             Exception(
-                f'{oxidation_states_set} is not valid. Enter either "default", "icsd", "pymatgen","wiki" or a filepath to a textfile of oxidation states.'
+                f'{oxidation_states_set} is not valid. Enter either "smact14", "icsd", "pymatgen","wiki" or a filepath to a textfile of oxidation states.'
             )
         )
     if oxidation_states_set == "wiki":
@@ -430,19 +434,23 @@ def smact_validity(
     composition: Union[pymatgen.core.Composition, str],
     use_pauling_test: bool = True,
     include_alloys: bool = True,
-    oxidation_states_set: Union[str, bytes, os.PathLike] = "default",
+    oxidation_states_set: Union[str, bytes, os.PathLike] = "smact14",
 ) -> bool:
     """Check if a composition is valid according to the SMACT rules.
 
     Composition is considered valid if it passes the charge neutrality test and the Pauling electronegativity test.
 
+     .. warning::
+        For backwards compatability in SMACT >=2.7, expllicitly set oxidation_states_set to 'smact14' if you wish to use the 2014 SMACT default oxidation states.
+        In SMACT 3.0, the smact_filter function will be set to use a new default oxidation states set.
+
     Args:
         composition (Union[pymatgen.core.Composition, str]): Composition/formula to check. This can be a pymatgen Composition object or a string.
         use_pauling_test (bool): Whether to use the Pauling electronegativity test
         include_alloys (bool): If True, compositions which only contain metal elements will be considered valid without further checks.
         oxidation_states_set (Union[str, bytes, os.PathLike]): A string to choose which set of
-            oxidation states should be chosen for charge-balancing. Options are 'default', 'icsd',
-            'pymatgen' and 'wiki' for the default, icsd, pymatgen structure predictor and Wikipedia
+            oxidation states should be chosen for charge-balancing. Options are 'smact14', 'icsd',
+            'pymatgen' and 'wiki' for the 2014 SMACT default, 2016 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.
 
@@ -471,8 +479,8 @@ def smact_validity(
     smact_elems = [e[1] for e in space.items()]
     electronegs = [e.pauling_eneg for e in smact_elems]
 
-    if oxidation_states_set == "default" or oxidation_states_set is None:
-        ox_combos = [e.oxidation_states for e in smact_elems]
+    if oxidation_states_set == "smact14" or oxidation_states_set is None:
+        ox_combos = [e.oxidation_states_smact14 for e in smact_elems]
     elif oxidation_states_set == "icsd":
         ox_combos = [e.oxidation_states_icsd for e in smact_elems]
     elif oxidation_states_set == "pymatgen":
@@ -491,7 +499,7 @@ def smact_validity(
     else:
         raise (
             Exception(
-                f'{oxidation_states_set} is not valid. Enter either "default", "icsd", "pymatgen","wiki" or a filepath to a textfile of oxidation states.'
+                f'{oxidation_states_set} is not valid. Enter either "smact14", "icsd", "pymatgen","wiki" or a filepath to a textfile of oxidation states.'
             )
         )
 

smact/utils/composition.py

@@ -11,7 +11,7 @@
 
 # Adapted from ElementEmbeddings and Pymatgen
 def parse_formula(formula: str) -> dict[str, float]:
-    """Parse a formula into a dict of el:amt
+    """Parse a chemical formula into a dictionary of elements and their amounts.
 
     Args:
         formula (str): Chemical formula
@@ -56,7 +56,7 @@ def _get_sym_dict(formula: str, factor: float) -> dict[str, float]:
 def comp_maker(
     smact_filter_output: tuple[str, int, int] | tuple[str, int]
 ) -> Composition:
-    """Convert an output of smact.screening.smact_filer into a Pymatgen Compositions
+    """Convert an item in the output of smact.screening.smact_filer into a Pymatgen Composition.
 
     Args:
         smact_filter_output (tuple[str, int, int]|tuple[str, int]): An item in the list returned from smact_filter
@@ -71,21 +71,21 @@ def comp_maker(
             form.append(ammt)
         form = "".join(str(e) for e in form)
     else:
-        form = {}
-        for el, ox, ammt in zip(
-            smact_filter_output[0],
-            smact_filter_output[1],
-            smact_filter_output[2],
-        ):
-            sp = unparse_spec((el, ox))
-            form[sp] = ammt
+        form = {
+            unparse_spec((el, ox)): ammt
+            for el, ox, ammt in zip(
+                smact_filter_output[0],
+                smact_filter_output[1],
+                smact_filter_output[2],
+            )
+        }
     return Composition(form)
 
 
 def formula_maker(
     smact_filter_output: tuple[str, int, int] | tuple[str, int]
 ) -> str:
-    """Convert an output of smact.screening.smact_filter into a formula.
+    """Convert an item in the output of smact.screening.smact_filter into a chemical formula.
 
     Args:
         smact_filter_output (tuple[str, int, int]|tuple[str, int]): An item in the list returned from smact_filter