Update develop branch in line with master branch

.github/workflows/check-live-links.yml

@@ -0,0 +1,16 @@
+name: Check Markdown links
+
+on:
+  push:
+    branches:
+      - master
+  schedule:
+    # Every Monday at 00:00 UTC
+    - cron: "0 0 * * 1"
+
+jobs:
+  markdown-link-check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@master
+      - uses: gaurav-nelson/github-action-markdown-link-check@v1

.github/workflows/ci.yml

@@ -23,22 +23,27 @@ jobs:
 
     runs-on: ${{matrix.os}}
     steps:
-      - uses: actions/checkout@v4
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
       - name: Set up Python ${{ matrix.python-version }}
         uses: actions/setup-python@v5
         with:
           python-version: ${{ matrix.python-version }}
+          cache: pip
+          cache-dependency-path: pyproject.toml
+
       - name: Install dependencies
         run: |
-          python -m pip install --upgrade pip wheel setuptools
-          pip install -e ".[crystal_space,dev]"
-          pip install pytest-cov
+          pip install uv
+          uv pip install -e ".[optional,dev]" --system
+
       - name: Run tests and collect coverage
         env:
           MP_API_KEY: ${{ secrets.MP_API_KEY }}
         run: python -m pytest --cov=smact --cov-report=xml -v
       - name: Upload coverage reports to CodeCov
-        uses: codecov/codecov-action@v4
+        uses: codecov/codecov-action@v5
         with:
           token: ${{ secrets.CODECOV_TOKEN }}
           #files: ./coverage.xml

.readthedocs.yaml

@@ -13,3 +13,4 @@ sphinx:
 python:
   install:
     - requirements: docs/requirements.txt
+    - requirements: requirements.txt

CONTRIBUTING.md

@@ -35,7 +35,7 @@ Recommended reading: [How to Write the Perfect Pull Request](https://github.blog
 When developing locally, it is recommended to install the python packages in `requirements-dev.txt`.
 
 ```bash
-pip install -r requirements-dev.txt
+pip install -e ".[dev,docs]"
 ```
 
 This will allow you to run the tests locally with pytest as described in the main README,

README.md

@@ -17,7 +17,7 @@
 **Semiconducting Materials from Analogy and Chemical Theory** (SMACT) is a collection of rapid screening and informatics tools that uses data about chemical elements.
 
 - **Documentation:** <https://smact.readthedocs.io/en/latest/>
-- **Examples:** <https://github.com/WMD-group/SMACT/tree/master/examples>
+- **Examples:** <https://smact.readthedocs.io/en/latest/examples.html>
 
 ![A blue interface with the text "SMACT v3" at the top. Below that, there is a label "Materials Search" followed by two radio buttons: "Hi-fi" and "Lo-fi". The "Lo-fi" button is currently selected](SMACT.png)
 
@@ -33,15 +33,15 @@ There is a strong demand for functional materials across a wide range of technol
 
 Features are accessed through Python scripts, importing classes and functions as needed.
 The best place to start is looking at [the docs](https://smact.readthedocs.io/en/latest/), which highlight some simple examples of how these classes and functions can be usede
-Use cases are available in our [examples](https://github.com/WMD-group/SMACT/tree/master/examples) and [tutorials](https://github.com/WMD-group/SMACT/tree/master/tutorials) folders.
+Use cases are available in our [examples](https://smact.readthedocs.io/en/latest/examples.html) and [tutorials](https://smact.readthedocs.io/en/latest/tutorials.html) folders.
 
 ## Code features
 
 - At the core of SMACT are [Element](https://smact.readthedocs.io/en/latest/smact.html#smact.Element) and [Species](https://smact.readthedocs.io/en/latest/smact.html#smact.Species) (element in a given oxidation state) classes that have various properties associated with them.
 
 - Oxidation states that are accessible to each element are included in their properties.
 
-- Element compositions can be screened through based on the heuristic filters of charge neutrality and electronegativity order. This is handled using the [screening module](https://smact.readthedocs.io/en/latest/smact.screening.html) and [this publication](<https://www.cell.com/chem/fulltext/S2451-9294(16)30155-3>) describes the underlying theory. An example procedure is [outlined in the docs](https://smact.readthedocs.io/en/latest/examples.html#neutral-combinations) and more examples can be found in the [counting examples subfolder](https://github.com/WMD-group/SMACT/tree/master/examples/Counting).
+- Element compositions can be screened through based on the heuristic filters of charge neutrality and electronegativity order. This is handled using the [screening module](https://smact.readthedocs.io/en/latest/smact.screening.html) and [this publication](<https://www.cell.com/chem/fulltext/S2451-9294(16)30155-3>) describes the underlying theory. An example procedure is [outlined in the docs](https://smact.readthedocs.io/en/latest/examples/filter.html).
 
 - Further filters can be applied to generated lists of compositions in order to screen for particular properties. These properties are either intrinsic properties of elements or are calculated for compositions using the [properties module](https://smact.readthedocs.io/en/latest/smact.properties.html). For example:
 
@@ -50,7 +50,7 @@ Use cases are available in our [examples](https://github.com/WMD-group/SMACT/tre
 
 - Compositions can also be filtered based on sustainability via the abundance of elements in the Earth's crust or via the [HHI scale](https://pubs.acs.org/doi/10.1021/cm400893e).
 
-- Compositions can be converted for use in Pymatgen or for representation to machine learning algorithms ([see "next steps" in this example](https://github.com/WMD-group/SMACT/blob/master/examples/Counting/Generate_compositions_lists.ipynb)) and the related [ElementEmbeddings](https://github.com/WMD-group/ElementEmbeddings) package.
+- Compositions can be converted for use in Pymatgen or for representation to machine learning algorithms ([see this example](https://smact.readthedocs.io/en/latest/tutorials/smact_generation_of_solar_oxides.html)) and the related [ElementEmbeddings](https://github.com/WMD-group/ElementEmbeddings) package.
 
 - The code also has tools for manipulating common crystal lattice types:
   - Certain structure types can be built using the [builder module](https://smact.readthedocs.io/en/latest/smact.builder.html)
@@ -77,6 +77,7 @@ Use cases are available in our [examples](https://github.com/WMD-group/SMACT/tre
   - **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 dopants.
+  - **utils.py** A collection of utility functions used throughout the codebase.
 
 ## Requirements
 
@@ -90,6 +91,10 @@ The latest stable release can be installed via pip which will automatically set
 
     pip install smact
 
+Optional dependencies can also be installed. These enable full replication of the examples and tutorials
+
+    pip install "smact[optional]"
+
 SMACT is also available via conda through the conda-forge channel on Anaconda Cloud:
 
     conda install -c conda-forge smact

docs/conf.py

@@ -45,7 +45,7 @@
     "html_image",
 ]
 myst_url_schemes = ("http", "https", "mailto")
-jupyter_execute_notebooks = "off"
+nb_execution_mode = "off"
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]
@@ -71,9 +71,9 @@
 # built documents.
 #
 # The short X.Y version.
-version = "2.8"
+version = "3.0"
 # The full version, including alpha/beta/rc tags.
-release = "2.8.0"
+release = "3.0.0"
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
@@ -154,7 +154,7 @@
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ["_static"]
+# html_static_path = ["_static"]
 
 # Add any extra paths that contain custom files (such as robots.txt or
 # .htaccess) here, relative to this directory. These files are copied
@@ -418,5 +418,8 @@ def __getattr__(cls, name):
     "pymatgen.analysis.structure_prediction",
     "pymatgen.transformations.standard_transformations",
     "tabulate",
+    "mp_api",
+    "mp_api.client",
+    "emmet",
 ]
 sys.modules.update((mod_name, Mock()) for mod_name in MOCK_MODULES)

docs/examples.rst

@@ -15,7 +15,6 @@ For workflows that have been used in real examples and in published work, visit
    examples/filter
    examples/validity
    examples/lists
-   examples/neutral_combos
    examples/oxidation_states
    examples/compound_electroneg
    examples/valence_electron_count

docs/examples/doper.ipynb

@@ -11,7 +11,8 @@
     "\n",
     "By default, the top five p-type and n-type candidates are reported. Use the `num_dopants` input to modify the number of outputs.\n",
     "\n",
-    "### Output Format\n",
+    "**Output Format**\n",
+    "\n",
     "The output is a dictionary with keys:\n",
     "- \"n_type_cation\"\n",
     "- \"p_type_cation\"\n",

docs/requirements.in

@@ -1,6 +1,6 @@
 # Defining the exact version will make sure things don't break
-sphinx==5.3.0
-sphinx_rtd_theme==2.0.0
+sphinx==8.1.3
+sphinx_rtd_theme==3.0.2
 readthedocs-sphinx-search==0.3.2
 sphinx-book-theme==1.1.3
-myst-nb==1.1.1
+myst-nb==1.1.2

docs/smact.utils.crystal_space.download_compounds_with_mp_api.rst

@@ -0,0 +1,8 @@
+Crystal Space Materials Project Data Retrieval Module
+===========================
+
+
+.. automodule:: smact.utils.crystal_space.download_compounds_with_mp_api
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/smact.utils.crystal_space.generate_composition_with_smact.rst

@@ -0,0 +1,7 @@
+Crystal Space SMACT Generation Module
+===========================
+
+.. automodule:: smact.utils.crystal_space.generate_composition_with_smact
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/smact.utils.crystal_space.plot_embedding.rst

@@ -0,0 +1,8 @@
+Crystal Space Embedding Module
+===========================
+
+
+.. automodule:: smact.utils.crystal_space.plot_embedding
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/smact.utils.crystal_space.rst

@@ -0,0 +1,14 @@
+SMACT Utilities Crystal Space Module
+===========================
+
+Utility functions associated with our `Faraday Discussions publication 'Mapping Inorganic Crystal Space' <https://doi.org/10.1039/D4FD00063C>`_  using SMACT
+
+
+Submodules
+----------
+
+.. toctree::
+
+    smact.utils.crystal_space.download_compounds_with_mp_api
+    smact.utils.crystal_space.generate_composition_with_smact
+    smact.utils.crystal_space.plot_embedding

docs/smact.utils.oxidation.rst

@@ -0,0 +1,9 @@
+SMACT Utilities Oxidation Module
+=====================================
+
+Miscellaneous utilities for creating SMACT compatible oxidation states list
+
+.. automodule:: smact.utils.oxidation
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/smact.utils.rst

@@ -9,7 +9,5 @@ Submodules
 .. toctree::
 
     smact.utils.composition
-    smact.utils.band_gap_simple
-    smact.utils.download_compounds_with_mp_api
-    smact.utils.generate_composition_with_smact
-    smact.utils.plot_embeddings
+    smact.utils.crystal_space
+    smact.utils.oxidation

docs/tutorials.rst

@@ -11,6 +11,7 @@ Tutorials are intended as a more complete example of `smact` being applied in re
    tutorials/smact_generation_of_solar_oxides
    tutorials/oxidation_states
    tutorials/smact_validity_of_GNoMe
+   tutorials/structure_prediction
    tutorials/crystal_space
    tutorials/crystal_space_visualisation
    tutorials/filtering_icsd_oxidation_states.ipynb

docs/tutorials/crystal_space.ipynb

@@ -44,7 +44,7 @@
     "\n",
     "First, we'll create binary chemical compositions using the SMACT filter. The SMACT filter is a smart tool that helps us select compositions based on important chemical rules, such as oxidation states and electronegativity.\n",
     "\n",
-    "To generate these compositions, we'll use a function called [`generate_composition_with_smact`](../smact/utils/generate_composition_with_smact.py). This function allows us to enumerate all possible binary compositions and filter them based on the SMACT rules. \n",
+    "To generate these compositions, we'll use a function called [`generate_composition_with_smact`](../../smact/utils/crystal_space/generate_composition_with_smact.py). This function allows us to enumerate all possible binary compositions and filter them based on the SMACT rules. \n",
     "\n",
     "### Key parameters:\n",
     "- `num_elements`: Number of elements in the composition (e.g., 2 for binary).\n",
@@ -102,6 +102,7 @@
     "    max_atomic_num=103,\n",
     "    num_processes=8,\n",
     "    save_path=\"data/binary/df_binary_label.pkl\",\n",
+    "    oxidation_states_set=\"smact14\"\n",
     ")"
    ]
   },
@@ -127,7 +128,7 @@
    "source": [
     "Next, we download data from the `Materials Project api` using the `download_mp_data` function. This function allows us to download data for a given number of elements and maximum stoichiometry. The data includes the chemical formula, energy, and other properties of the compounds.\n",
     "\n",
-    "[`download_mp_data`](../smact/utils/download_compounds_with_mp_api.py) function takes in the following parameters:\n",
+    "[`download_mp_data`](../../smact/utils/crystal_space/download_compounds_with_mp_api.py) function takes in the following parameters:\n",
     "\n",
     "### Key parameters:\n",
     "- `mp_api_key`: your Materials Project API key\n",

docs/tutorials/crystal_space_visualisation.ipynb

@@ -11,7 +11,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "(prerequisite: [crystal_space_with_smact.ipynb](./crystal_space_with_smact.ipynb))\n",
+    "(prerequisite: [crystal_space.ipynb](./crystal_space.ipynb))\n",
     "\n",
     "In this tutorial, we will use the dimension reduction techniques to visualise a large crystal space. We will use the following techniques:\n",
     "\n",