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.

README.md

@@ -122,14 +122,15 @@ Development notes
 -----------------
 
 ### Bugs, features and questions
-Please use the [Issue Tracker](https://github.com/WMD-group/smact/issues) to report bugs or request features in the first instance. While we hope that most questions can be answered by searching [the docs](https://smact.readthedocs.io/en/latest/), we welcome new questions on the issue tracker, especially if they helps us improve the docs! For other queries about any aspect of the code, please contact either Dan Davies (author) or Anthony Onwuli (maintainer) by e-mail: d.w.davies@imperial.ac.uk or [email protected] respectively.
+Please use the [Issue Tracker](https://github.com/WMD-group/smact/issues) to report bugs or request features in the first instance. While we hope that most questions can be answered by searching [the docs](https://smact.readthedocs.io/en/latest/), we welcome new questions on the issue tracker, especially if they help us improve the docs! For other queries about any aspect of the code, please contact either Aron Walsh on behalf of The SMACT Developers (author) or Anthony Onwuli (maintainer) by e-mail: a.walsh@imperial.ac.uk or [email protected] respectively.
 
 ### Code contributions
 We are always looking for ways to make SMACT better and more useful to the wider community; contributions are welcome. Please use the ["Fork and Pull"](https://guides.github.com/activities/forking/) workflow to make contributions and stick as closely as possible to the following:
 
 - Code style should comply with [PEP8](http://www.python.org/dev/peps/pep-0008) where possible. [Google's house style](https://google.github.io/styleguide/pyguide.html) is also helpful, including a good model for docstrings.
 - Please use comments liberally when adding nontrivial features, and take the chance to clean up other people's code while looking at it.
 - Add tests wherever possible, and use the test suite to check if you broke anything.
+- Look at the [contributing guide](CONTRIBUTING.md) for more information.
 
 ### Tests
 Testing modules should be pass/fail and wrapped into **tests/test_core.py** or another **tests/test_something.py** file added, if appropriate. 

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}")

requirements.txt

@@ -2,7 +2,7 @@
 # This file is autogenerated by pip-compile with Python 3.10
 # by the following command:
 #
-#    pip-compile
+#    pip-compile --output-file=requirements.txt setup.py
 #
 ase==3.23.0
     # via SMACT (setup.py)
@@ -20,8 +20,6 @@ dill==0.3.8
     #   pathos
 fonttools==4.53.0
     # via matplotlib
-future==1.0.0
-    # via uncertainties
 idna==3.7
     # via requests
 joblib==1.4.2
@@ -34,11 +32,11 @@ matplotlib==3.8.2
     # via
     #   ase
     #   pymatgen
-monty==2023.11.3
+monty==2024.7.30
     # via pymatgen
 mpmath==1.3.0
     # via sympy
-multiprocess==0.70.15
+multiprocess==0.70.16
     # via pathos
 networkx==3.2.1
     # via pymatgen
@@ -74,7 +72,7 @@ ppft==1.7.6.8
     # via pathos
 pybtex==0.24.0
     # via pymatgen
-pymatgen==2023.11.12
+pymatgen==2024.5.1
     # via SMACT (setup.py)
 pyparsing==3.1.1
     # via matplotlib
@@ -114,6 +112,8 @@ tenacity==8.2.3
     # via plotly
 tqdm==4.66.4
     # via pymatgen
+typing-extensions==4.12.2
+    # via SMACT (setup.py)
 tzdata==2024.1
     # via pandas
 uncertainties==3.2.2

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)