Merge develop into master branch

.pre-commit-config.yaml

@@ -4,7 +4,7 @@ repos:
     hooks:
       - id: isort
         additional_dependencies: [toml]
-        args: ["--profile", "black", "--filter-files","--line-length=80"]
+        args: ["--profile", "black", "--filter-files", "--line-length=80"]
   - repo: https://github.com/psf/black
     rev: "23.1.0"
     hooks:
@@ -16,9 +16,8 @@ repos:
       - id: pyupgrade
         args: [--py38-plus]
   - repo: https://github.com/nbQA-dev/nbQA
-    rev: "1.6.1"
+    rev: "1.8.7"
     hooks:
       - id: nbqa-pyupgrade
         additional_dependencies: [pyupgrade==3.3.1]
-        args: [--py38-plus]
-
+        args: [--py39-plus]

CONTRIBUTING.md

@@ -0,0 +1,50 @@
+# Contributing
+
+This is a quick guide on how to follow best practice and contribute smoothly to `SMACT`.
+
+## Workflow
+
+We follow the [GitHub flow](<https://docs.github.com/en/get-started/using-github/github-flow>), using
+branches for new work and pull requests for verifying the work.
+
+The steps for a new piece of work can be summarised as follows:
+
+1. Push up or create [an issue](https://github.com/WMD-group/SMACT/issues).
+2. Create a branch from main, with a sensible name that relates to the issue.
+3. Do the work and commit changes to the branch. Push the branch
+   regularly to GitHub to make sure no work is accidentally lost.
+4. Write or update unit tests for the code you work on.
+5. When you are finished with the work, ensure that all of the unit
+   tests pass on your own machine.
+6. Open a pull request [on the pull request page](https://github.com/WMD-group/SMACT/pulls).
+7. If nobody acknowledges your pull request promptly, feel free to poke one of the main developers into action.
+
+## Pull requests
+
+For a general overview of using pull requests on GitHub look [in the GitHub docs](https://help.github.com/en/articles/about-pull-requests).
+
+When creating a pull request you should:
+
+- Ensure that the title succinctly describes the changes so it is easy to read on the overview page
+- Reference the issue which the pull request is closing
+
+Recommended reading: [How to Write the Perfect Pull Request](https://github.blog/2015-01-21-how-to-write-the-perfect-pull-request/)
+
+## Dev requirements
+
+When developing locally, it is recommended to install the python packages in `requirements-dev.txt`.
+
+```bash
+pip install -r requirements-dev.txt
+```
+
+This will allow you to run the tests locally with pytest as described in the main README,
+as well as run pre-commit hooks to automatically format python files with isort and black.
+To install the pre-commit hooks (only needs to be done once):
+
+```bash
+pre-commit install
+pre-commit run --all-files # optionally run hooks on all files
+```
+
+Pre-commit hooks will check all files when you commit changes, automatically fixing any files which are not formatted correctly. Those files will need to be staged again before re-attempting the commit.

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.

docs/smact.rst

@@ -25,6 +25,7 @@ Submodules
 
   smact.structure_prediction
   smact.dopant_prediction
+  smact.utils
   smact.properties
   smact.screening
   smact.oxidation_states

docs/smact.utils.composition.rst

@@ -0,0 +1,9 @@
+SMACT Utilities Composition Module
+=====================================
+
+Miscellaneous utilities for composition handling
+
+.. automodule:: smact.utils.composition
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/smact.utils.rst

@@ -0,0 +1,11 @@
+SMACT Utilities module
+===========================
+
+The utilities module provides some utilty functions to support the core functionalities of SMACT
+
+Submodules
+----------
+
+.. toctree::
+
+    smact.utils.composition

examples/Crystal_Space/1_reduction.ipynb

@@ -58,7 +58,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "from typing import Iterable\n",
+    "from collections.abc import Iterable\n",
     "from pathlib import Path\n",
     "\n",
     "from tqdm import tqdm\n",

examples/vec_example.py

@@ -0,0 +1,10 @@
+from smact.properties import valence_electron_count
+
+# Define the compound
+compound = "Fe2O3"
+
+# Calculate the Valence Electron Count (VEC)
+vec = valence_electron_count(compound)
+
+# Print the result
+print(f"The Valence Electron Count (VEC) for {compound} is: {vec:.2f}")

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,10 +29,11 @@
         author=__author__,
         author_email=__author_email__,
         maintainer=__maintainer__,
-        maintainer_email=__maintaier_email__,
+        maintainer_email=__maintainer_email__,
         license="MIT",
         packages=[
             "smact",
+            "smact.utils",
             "smact.tests",
             "smact.structure_prediction",
             "smact.dopant_prediction",

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
 
@@ -73,6 +75,18 @@ class Element:
 
         Element.HHI_r (float) : Hirfindahl-Hirschman Index for elemental reserves
 
+        Element.mendeleev (int): Mendeleev number
+
+        Element.AtomicWeight (float): Atomic weight
+
+        Element.MeltingT (float): Melting temperature in K
+
+        Element.num_valence (int): Number of valence electrons
+
+        Element.num_valence_modified (int): Number of valence electrons based on a modified definition
+
+
+
     Raises:
         NameError: Element not found in element.txt
         Warning: Element not found in Eigenvalues.csv
@@ -140,6 +154,23 @@ def __init__(
         else:
             sse_Pauling = None
 
+        magpie_data = data_loader.lookup_element_magpie_data(symbol)
+        if magpie_data:
+            mendeleev = magpie_data["MendeleevNumber"]
+            AtomicWeight = magpie_data["AtomicWeight"]
+            MeltingT = magpie_data["MeltingT"]
+            num_valence = magpie_data["NValence"]
+        else:
+            mendeleev = None
+            AtomicWeight = None
+            MeltingT = None
+            num_valence = None
+
+        valence_data = data_loader.lookup_element_valence_data(symbol)
+        num_valence_modified = (
+            valence_data["NValence"] if valence_data else None
+        )
+
         for attribute, value in (
             ("coord_envs", coord_envs),
             ("covalent_radius", dataset["r_cov"]),
@@ -157,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),
@@ -174,6 +209,11 @@ def __init__(
             ("SSE", sse),
             ("SSEPauling", sse_Pauling),
             ("symbol", symbol),
+            ("mendeleev", mendeleev),
+            ("AtomicWeight", AtomicWeight),
+            ("MeltingT", MeltingT),
+            ("num_valence", num_valence),
+            ("num_valence_modified", num_valence_modified),
             # ('vdw_radius', dataset['RVdW']),
         ):
             setattr(self, attribute, value)

smact/data/element_valence_modified.csv

@@ -0,0 +1,98 @@
+element,NValence
+H,1
+He,2
+Li,1
+Be,2
+B,3
+C,4
+N,5
+O,6
+F,7
+Ne,8
+Na,1
+Mg,2
+Al,3
+Si,4
+P,5
+S,6
+Cl,7
+Ar,8
+K,1
+Ca,2
+Sc,3
+Ti,4
+V,5
+Cr,6
+Mn,7
+Fe,8
+Co,9
+Ni,10
+Cu,11
+Zn,12
+Ga,3
+Ge,4
+As,5
+Se,6
+Br,7
+Kr,8
+Rb,1
+Sr,2
+Y,3
+Zr,4
+Nb,5
+Mo,6
+Tc,7
+Ru,8
+Rh,9
+Pd,10
+Ag,11
+Cd,12
+In,3
+Sn,4
+Sb,5
+Te,6
+I,7
+Xe,8
+Cs,1
+Ba,2
+La,3
+Ce,4
+Pr,5
+Nd,6
+Pm,7
+Sm,8
+Eu,9
+Gd,10
+Tb,11
+Dy,12
+Ho,13
+Er,14
+Tm,15
+Yb,16
+Lu,3
+Hf,4
+Ta,5
+W,6
+Re,7
+Os,8
+Ir,9
+Pt,10
+Au,11
+Hg,12
+Tl,3
+Pb,4
+Bi,5
+Po,6
+At,7
+Rn,8
+Fr,1
+Ra,2
+Ac,3
+Th,4
+Pa,5
+U,6
+Np,7
+Pu,8
+Am,9
+Cm,10
+Bk,11