Merge branch 'develop' of https://github.com/WMD-group/SMACT into doc…

…s_updates

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

@@ -127,6 +127,7 @@ We are always looking for ways to make SMACT better and more useful to the wider
 - 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
 

docs/conf.py

@@ -63,9 +63,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

docs/tutorials/crystal_space_visualisation.ipynb

@@ -77,7 +77,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

@@ -10,7 +10,8 @@
 __version__ = "2.6"
 __maintainer__ = "Anthony O. Onwuli"
 __maintainer_email__ = "[email protected]"
-__date__ = "July 10 2024"
+__date__ = "August 30 2024"
+
 
 import os
 
@@ -32,9 +33,11 @@
         author_email=__author_email__,
         maintainer=__maintainer__,
         maintainer_email=__maintainer_email__,
+        maintainer_email=__maintainer_email__,
         license="MIT",
         packages=[
             "smact",
+            "smact.utils",
             "smact.tests",
             "smact.structure_prediction",
             "smact.dopant_prediction",
@@ -56,7 +59,7 @@
             "scipy",
             "numpy<2",
             "spglib",
-            "pymatgen>=2024.2.20",
+            "pymatgen>=2024.2.20,<2024.8.8",
             "ase",
             "pandas",
             "pathos",

smact/__init__.py

@@ -60,9 +60,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
 
@@ -80,6 +82,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
@@ -133,6 +147,23 @@ def __init__(self, symbol: str, oxi_states_custom_filepath: str | None = None):
         sse_Pauling_data = data_loader.lookup_element_sse_pauling_data(symbol)
         sse_Pauling = sse_Pauling_data["SolidStateEnergyPauling"] if sse_Pauling_data else 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"]),
@@ -150,6 +181,10 @@ def __init__(self, symbol: str, oxi_states_custom_filepath: str | None = None):
                 "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),
@@ -167,6 +202,11 @@ def __init__(self, symbol: str, oxi_states_custom_filepath: str | None = None):
             ("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