SMACT 3.2.0__tar.gz → 4.0.1__tar.gz

{smact-3.2.0 → smact-4.0.1}/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2019 The SMACT Developers
+Copyright (c) 2026 The SMACT Developers
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
@@ -19,3 +19,6 @@ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
+
+This project bundles third-party material under its own license terms;
+see THIRD_PARTY_NOTICES.md.

{smact-3.2.0/SMACT.egg-info → smact-4.0.1}/PKG-INFO

@@ -1,9 +1,9 @@
 Metadata-Version: 2.4
 Name: SMACT
-Version: 3.2.0
+Version: 4.0.1
 Summary: Semiconducting Materials by Analogy and Chemical Theory
 Author-email: The SMACT Developers <a.walsh@imperial.ac.uk>
-Maintainer-email: "Anthony O. Onwuli" <anthony.onwuli16@imperial.ac.uk>
+Maintainer-email: "Kinga O. Mastej" <k.mastej24@imperial.ac.uk>
 License-Expression: MIT
 Project-URL: Homepage, https://github.com/WMD-group/SMACT
 Project-URL: Documentation, https://smact.readthedocs.io/en/latest/
@@ -15,23 +15,24 @@ Classifier: Development Status :: 5 - Production/Stable
 Classifier: Intended Audience :: Science/Research
 Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Scientific/Engineering
 Classifier: Topic :: Scientific/Engineering :: Chemistry
-Requires-Python: <3.14,>=3.10
+Requires-Python: <3.14,>=3.11
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: ase
 Requires-Dist: numpy<3
-Requires-Dist: pandarallel[optional]>=1.6.5
+Requires-Dist: pandarallel>=1.6.5
 Requires-Dist: pandas
 Requires-Dist: pathos
 Requires-Dist: pymatgen>=2024.2.20
 Requires-Dist: scipy
 Requires-Dist: spglib>=2.6.0
+Requires-Dist: tabulate
+Requires-Dist: tqdm
 Requires-Dist: typing-extensions
 Provides-Extra: dev
 Requires-Dist: pytest; extra == "dev"
@@ -46,7 +47,8 @@ Requires-Dist: sphinx==8.1.3; extra == "docs"
 Requires-Dist: sphinx_rtd_theme==3.0.2; extra == "docs"
 Requires-Dist: readthedocs-sphinx-search==0.3.2; extra == "docs"
 Requires-Dist: sphinx-book-theme==1.1.3; extra == "docs"
-Requires-Dist: myst-nb==1.1.2; extra == "docs"
+Requires-Dist: tornado>=6.5.3; extra == "docs"
+Requires-Dist: myst-nb==1.3.0; extra == "docs"
 Provides-Extra: mp
 Requires-Dist: mp-api>=0.45.3; extra == "mp"
 Provides-Extra: crystal-space
@@ -65,6 +67,10 @@ Provides-Extra: ml
 Requires-Dist: xgboost; extra == "ml"
 Requires-Dist: shap; extra == "ml"
 Requires-Dist: smact[featurisers]; extra == "ml"
+Provides-Extra: property-prediction
+Requires-Dist: aviary-models>=1.2.1; extra == "property-prediction"
+Requires-Dist: requests; extra == "property-prediction"
+Requires-Dist: torch<2.11,>=2.0.0; extra == "property-prediction"
 Provides-Extra: optional
 Requires-Dist: pydantic>=2.9.2; extra == "optional"
 Requires-Dist: smact[mp]; extra == "optional"
@@ -82,8 +88,7 @@ Requires-Dist: matplotlib-venn[shapely]>=1.1.2; extra == "optional"
 Provides-Extra: strict
 Requires-Dist: pydantic==2.9.2; extra == "strict"
 Requires-Dist: mp-api==0.45.5; extra == "strict"
-Requires-Dist: pymatviz==0.15.1; extra == "strict"
-Requires-Dist: mp-api==0.45.5; extra == "strict"
+Requires-Dist: pymatviz==0.16.0; extra == "strict"
 Requires-Dist: seaborn==0.13.2; extra == "strict"
 Requires-Dist: pymatgen==2025.4.24; extra == "strict"
 Requires-Dist: matminer==0.9.3; extra == "strict"
@@ -92,15 +97,17 @@ Requires-Dist: kaleido==0.2.1; extra == "strict"
 Requires-Dist: ase==3.24.0; extra == "strict"
 Requires-Dist: numpy; extra == "strict"
 Requires-Dist: ElementEmbeddings==0.6.1; extra == "strict"
-Requires-Dist: dash==3.0.2; extra == "strict"
+Requires-Dist: dash==3.3.0; extra == "strict"
+Requires-Dist: tabulate==0.9.0; extra == "strict"
+Requires-Dist: tqdm==4.67.1; extra == "strict"
 Dynamic: license-file
 
 [![DOI](https://joss.theoj.org/papers/10.21105/joss.01361/status.svg)](https://doi.org/10.21105/joss.01361)
-[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.5553202.svg)](https://doi.org/10.5281/zenodo.5553202)
-[![Documentation Status](https://readthedocs.org/projects/smact/badge/?version=latest)](http://smact.readthedocs.org/en/latest/?badge=latest)
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.595853.svg)](https://doi.org/10.5281/zenodo.595853)
+[![Documentation Status](https://readthedocs.org/projects/smact/badge/?version=latest)](https://smact.readthedocs.org/en/latest/?badge=latest)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 ![python version](https://img.shields.io/pypi/pyversions/smact)
-[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
 [![PyPi](https://img.shields.io/pypi/v/smact)](https://pypi.org/project/SMACT/)
 [![Conda](https://anaconda.org/conda-forge/smact/badges/version.svg)](https://anaconda.org/conda-forge/smact)
 [![GitHub issues](https://img.shields.io/github/issues-raw/WMD-Group/SMACT)](https://github.com/WMD-group/SMACT/issues)
@@ -111,12 +118,12 @@ Dynamic: license-file
 
 # SMACT
 
-**Semiconducting Materials from Analogy and Chemical Theory** (SMACT) is a collection of rapid screening and informatics tools that uses data about chemical elements.
+**Semiconducting Materials by 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://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)
+![A blue interface with the text "SMACT v4" 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)
 
 _If you torture the data enough, nature will always confess_ - Roland Coase (from 'How should economists choose?')
 
@@ -129,7 +136,7 @@ There is a strong demand for functional materials across a wide range of technol
 ## Getting started
 
 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
+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 used.
 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
@@ -148,6 +155,12 @@ Use cases are available in our [examples](https://smact.readthedocs.io/en/latest
 
 - 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.
 
+- Charge neutrality screening supports **mixed-valence compounds** via the `mixed_valence=True` flag in `smact_validity`, enabling correct handling of materials like Fe₃O₄ and Mn₃O₄.
+
+- Oxidation state data is sourced from **ICSD 2024**, providing an updated and stricter set of experimentally observed oxidation states per element.
+
+- The [property prediction module](https://smact.readthedocs.io/en/latest/smact.property_prediction.html) enables composition-to-property prediction using pretrained deep learning models, including a ROOST-based band gap predictor trained on the Materials Project database.
+
 - 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)
   - Lattice parameters can be estimated using ionic radii of the elements for various common crystal structure types using the [lattice_parameters module](https://smact.readthedocs.io/en/latest/smact.lattice_parameters.html).
@@ -155,6 +168,88 @@ Use cases are available in our [examples](https://smact.readthedocs.io/en/latest
   - The [structure prediction](https://smact.readthedocs.io/en/latest/smact.structure_prediction.html) module can be used to predict the structure of hypothetical compositions using species similarity measures.
   - The [dopant prediction](https://smact.readthedocs.io/en/latest/smact.dopant_prediction.html) module can be used to facilitate high-throughput predictions of p-type and n-type dopants of multicomponent solids.
 
+## Package structure
+
+**Legend:** 🟢 new in v4 — 🟡 improved in v4
+
+```mermaid
+graph TD
+    classDef new fill:#c8e6c9,stroke:#388e3c,color:#000
+    classDef improved fill:#fff9c4,stroke:#f9a825,color:#000
+
+    SMACT(["smact"])
+
+    SMACT --> core["Core modules"]
+    SMACT --> SP["structure_prediction"]
+    SMACT --> DP["dopant_prediction"]
+    SMACT --> PP["🟢 property_prediction"]
+    SMACT --> IO["🟢 io"]
+    SMACT --> UT["utils"]
+
+    core --> init["init.py — Element, Species, neutral_ratios"]
+    core --> dl["data_loader.py — elemental and oxidation state data loading"]
+    core --> sc["🟡 screening.py — compositional screening"]
+    core --> pr["properties.py — band gap, electronegativity, valence electron count"]
+    core --> ox["oxidation_states.py — oxidation state combination likelihood"]
+    core --> mt["metallicity.py — metallic character scoring"]
+    core --> la["lattice.py — Site and Lattice representations"]
+    core --> bld["🟡 builder.py — perovskite and wurtzite structure builders"]
+    core --> lp["🟡 lattice_parameters.py — lattice parameter estimation from ionic radii"]
+    core --> di["distorter.py — inequivalent site enumeration and substitution"]
+
+    sc --> sc1["smact_validity — charge neutrality and Pauling electronegativity test"]
+    sc --> sc2["smact_filter — compositional search space generation"]
+    sc --> sc3["🟢 mixed_valence flag — correct handling of Fe3O4, Mn3O4"]
+    sc --> sc4["🟢 ICSD 2024 oxidation states — stricter, updated elemental data"]
+
+    bld --> bld1["cubic_perovskite — parameterized oxidation state tiling"]
+    bld --> bld2["wurtzite — corrected default cell parameters"]
+
+    lp --> lp1["corrected geometric formulae for all structure types"]
+
+    SP --> spst["structure.py — SmactStructure"]
+    SP --> spdb["database.py — StructureDB SQLite interface"]
+    SP --> spmu["mutation.py — CationMutator from lambda tables"]
+    SP --> sppd["🟡 prediction.py — StructurePredictor"]
+
+    spst --> spst1["from_file, from_mp, from_pymatgen constructors"]
+    sppd --> sppd1["ionic substitution-based crystal structure prediction"]
+    sppd --> sppd2["🟢 updated to mp_api.client.MPRester interface"]
+
+    DP --> doper["🟡 doper.py — Doper"]
+    doper --> doper1["get_dopants — p-type and n-type candidates"]
+    doper --> doper2["to_table — ranked candidates as a formatted table"]
+    doper --> doper3["plot_dopants — periodic table heatmap visualisation"]
+
+    PP --> base["base_predictor.py — BasePropertyPredictor, PredictionResult"]
+    PP --> roost["roost/ — RoostPropertyPredictor"]
+    PP --> conv["convenience.py — predict_band_gap"]
+    PP --> reg["registry.py — model discovery and resolution"]
+
+    roost --> roost1["pretrained ROOST model for band gap prediction"]
+    roost --> roost2["uncertainty estimates alongside predictions"]
+    roost --> roost3["trained on Materials Project 2024 database"]
+    base --> base1["PredictionResult — value, uncertainty, metadata"]
+
+    IO --> ee["🟢 elementembeddings.py — ElementEmbeddings interface"]
+    ee --> ee1["composition_featuriser — composition-level feature vectors"]
+    ee --> ee2["species_featuriser — species-level feature vectors"]
+
+    UT --> comp["composition.py — parse_formula, comp_maker, formula_maker"]
+    UT --> uox["🟢 oxidation.py — ICSD24OxStatesFilter"]
+    UT --> sp2["species.py — parse_spec, unparse_spec"]
+    UT --> cs["crystal_space/"]
+
+    uox --> uox1["consensus and commonality-based filtering of oxidation states"]
+    cs --> cs1["generate_composition_with_smact.py — SMACT-based composition generation"]
+    cs --> cs2["download_compounds_with_mp_api.py — Materials Project bulk download"]
+    cs --> cs3["plot_embedding.py — crystal space visualisation"]
+
+    class PP,IO new
+    class sc,bld,lp,sppd,doper,uox improved
+    class sc3,sc4,sppd2,ee,uox new
+```
+
 ## List of modules
 
 - **smact** library containing:
@@ -172,44 +267,75 @@ Use cases are available in our [examples](https://smact.readthedocs.io/en/latest
     substituting on inequivalent sites of a sub-lattice.
   - **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.
+  - **dopant_prediction**: A submodule which contains a collection of tools for predicting dopants.
+  - **property_prediction**: A submodule for composition-to-property prediction using pretrained deep learning models (e.g. ROOST band gap predictor).
+  - **utils**: A submodule containing utility functions for composition parsing, species handling, oxidation state filtering, and crystal space generation and download.
 
 ## Requirements
 
-The main language is Python 3 and has been tested using Python 3.10 - 3.13 (Windows is not officially supported for Python 3.13 as of yet).
-Basic requirements are Numpy and Scipy.
-The [Atomic Simulation Environment](https://wiki.fysik.dtu.dk/ase) (ASE), [spglib](http://atztogo.github.io/spglib), and [pymatgen](https://pymatgen.org) are also required for many components.
+The main language is Python 3 and has been tested using Python 3.11 - 3.13.
+Core dependencies include NumPy, SciPy, pandas, [pymatgen](https://pymatgen.org), [ASE](https://wiki.fysik.dtu.dk/ase), and [spglib](https://spglib.readthedocs.io). A full list is in [`pyproject.toml`](pyproject.toml).
 
 ## Installation
 
-The latest stable release can be installed via pip which will automatically set up other Python packages as required:
+The latest stable release can be installed via pip:
+
+```bash
+pip install smact
+```
+
+Optional dependencies, needed by most of the examples and tutorials:
+
+```bash
+pip install "smact[optional]"
+```
 
-    pip install smact
+The band-gap prediction example additionally needs the pre-trained ROOST models, which
+bring in PyTorch. To run every example and tutorial:
 
-Optional dependencies can also be installed. These enable full replication of the examples and tutorials
+```bash
+pip install "smact[optional,property_prediction]"
+```
 
-    pip install "smact[optional]"
+SMACT is also available via conda-forge:
 
-SMACT is also available via conda through the conda-forge channel on Anaconda Cloud:
+```bash
+conda install -c conda-forge smact
+```
 
-    conda install -c conda-forge smact
+The optional functionality is available as conda-forge feature packages. Install
+only the feature you need; for example, the pre-trained property-prediction
+models can be installed with:
 
-Alternatively, the very latest version can be installed using:
+```bash
+conda install -c conda-forge smact-property-prediction
+```
 
-    pip install git+https://github.com/WMD-group/SMACT.git
+The other feature packages are `smact-mp`, `smact-crystal-space`,
+`smact-featurisers`, `smact-visualisation`, `smact-ml`, and `smact-optional`.
+`smact-optional` matches the `smact[optional]` pip extra. To install all
+documented examples and tutorials, including property prediction:
 
-For developer installation SMACT can be installed from a copy of the source
-repository (<https://github.com/wmd-group/smact>); this will be preferred if using experimental code branches.
+```bash
+conda install -c conda-forge smact-optional smact-property-prediction
+```
 
-To clone the project from GitHub and make a local installation:
+Conda feature packages use conda-forge builds of compiled dependencies such as
+`pytorch` (the package is named `torch` on PyPI). Select any GPU-specific
+`pytorch` configuration separately for your platform.
 
-    git clone https://github.com/wmd-group/smact.git
-    cd smact
-    pip install --user -e .
+### Developer installation
 
-With -e pip will create links to the source folder so that that changes
-to the code will be immediately reflected on the PATH.
+We use [uv](https://docs.astral.sh/uv/) for dependency management. To set up a development environment:
+
+```bash
+git clone https://github.com/wmd-group/smact.git
+cd smact
+uv sync --extra optional --extra property_prediction --dev
+pre-commit install
+```
+
+This installs SMACT in editable mode with all optional and development dependencies, and sets up pre-commit hooks. See [CONTRIBUTING.md](CONTRIBUTING.md) for the full workflow.
 
 ## License and attribution
 
@@ -219,24 +345,38 @@ Python code and original data tables are licensed under the MIT License.
 
 ### 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 Anthony Onwuli (maintainer) by [e-mail](mailto:anthony.onwuli16@imperial.ac.uk).
+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 Kinga Mastej (maintainer) by [e-mail](mailto:k.mastej24@imperial.ac.uk).
 
 ### 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:
+We are always looking for ways to make SMACT better and more useful to the wider community; contributions are welcome. As of v4.0.0, we use [GitHub Flow](https://docs.github.com/en/get-started/using-github/github-flow): branch from `master`, open a pull request against `master`, and releases are tagged from `master`. 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.
+- Code style is enforced by [ruff](https://docs.astral.sh/ruff/) (linting and formatting) and [pyright](https://github.com/microsoft/pyright) (type checking). Pre-commit hooks run these automatically on commit.
+- Use [Google-style docstrings](https://google.github.io/styleguide/pyguide.html#38-comments-and-docstrings).
 - 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
 
-We use integrated testing on GitHub via [GitHub Actions](https://github.com/features/actions). Testing modules should be pass/fail and wrapped into **tests/test_core.py** or another **tests/test_something.py** file added, if appropriate.
-Run the tests using `python -m pytest -v`.(The final `-v` is optional and adds more detail to the output.)
+We use [GitHub Actions](https://github.com/features/actions) for CI. Tests should be added to **smact/tests/test_core.py** or another **smact/tests/test_something.py** file.
+
+Run the tests locally:
+
+```bash
+make test
+```
+
+Or to run the full CI pipeline (pre-commit hooks and tests):
+
+```bash
+make ci-local
+```
 
 ## References
 
+[K. O. Mastej et al.,
+"Chemical filters for ultra-high-throughput materials screening and generation" _arXiv_ (2026)](https://doi.org/10.48550/arXiv.2607.17910)
+
 [H. Park et al.,
 "Mapping inorganic crystal chemical space" _Faraday Discuss._ (2024)](https://pubs.rsc.org/en/content/articlelanding/2024/fd/d4fd00063c)