SMACT 2.7__tar.gz → 3.0__tar.gz

{smact-2.7/SMACT.egg-info → smact-3.0}/PKG-INFO

@@ -1,37 +1,97 @@
 Metadata-Version: 2.1
 Name: SMACT
-Version: 2.7
+Version: 3.0
 Summary: Semiconducting Materials by Analogy and Chemical Theory
 Home-page: https://github.com/WMD-group/SMACT
 Author: The SMACT Developers
-Author-email: a.walsh@imperial.ac.uk
+Author-email: The SMACT Developers <a.walsh@imperial.ac.uk>
 Maintainer: Anthony O. Onwuli
-Maintainer-email: anthony.onwuli16@imperial.ac.uk
+Maintainer-email: "Anthony O. Onwuli" <anthony.onwuli16@imperial.ac.uk>
 License: MIT
+Project-URL: Homepage, https://github.com/WMD-group/SMACT
+Project-URL: Documentation, https://smact.readthedocs.io/en/latest/
+Project-URL: Repository, https://github.com/WMD-group/SMACT
+Project-URL: Issues, https://github.com/WMD-group/SMACT/issues
+Project-URL: Pypi, https://pypi.org/project/SMACT/
+Keywords: python,machine-learning,computational-chemistry,materials-science,materials-informatics,materials-screening,materials-design,materials
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
-Classifier: Development Status :: 5 - Production/Stable
-Classifier: Intended Audience :: Science/Research
-Classifier: Operating System :: OS Independent
-Classifier: License :: OSI Approved :: MIT License
 Classifier: Topic :: Scientific/Engineering
 Classifier: Topic :: Scientific/Engineering :: Chemistry
-Requires-Python: >=3.9
+Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: scipy
-Requires-Dist: numpy<2
-Requires-Dist: spglib
-Requires-Dist: pymatgen<2024.8.8,>=2024.2.20
 Requires-Dist: ase
+Requires-Dist: numpy<3
 Requires-Dist: pandas
 Requires-Dist: pathos
+Requires-Dist: pymatgen>=2024.2.20
+Requires-Dist: scipy
+Requires-Dist: spglib
 Requires-Dist: typing-extensions
-
-[![DOI](http://joss.theoj.org/papers/10.21105/joss.01361/status.svg)](https://doi.org/10.21105/joss.01361)
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: pyright; extra == "dev"
+Requires-Dist: codespell; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: blacken-docs; extra == "dev"
+Requires-Dist: nbstripout; extra == "dev"
+Provides-Extra: docs
+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"
+Provides-Extra: mp
+Requires-Dist: mp-api; extra == "mp"
+Provides-Extra: crystal-space
+Requires-Dist: mp-api; extra == "crystal-space"
+Requires-Dist: ElementEmbeddings; extra == "crystal-space"
+Requires-Dist: umap-learn==0.5.3; extra == "crystal-space"
+Requires-Dist: kaleido; extra == "crystal-space"
+Requires-Dist: pydantic<2.10.0; extra == "crystal-space"
+Provides-Extra: featurisers
+Requires-Dist: matminer; extra == "featurisers"
+Requires-Dist: ElementEmbeddings; extra == "featurisers"
+Provides-Extra: visualisation
+Requires-Dist: seaborn; extra == "visualisation"
+Requires-Dist: pymatviz; extra == "visualisation"
+Requires-Dist: dash; extra == "visualisation"
+Provides-Extra: optional
+Requires-Dist: pydantic>=2.9.2; extra == "optional"
+Requires-Dist: mp-api>=0.42.2; extra == "optional"
+Requires-Dist: pymatviz>=0.14; extra == "optional"
+Requires-Dist: seaborn>=0.13.2; extra == "optional"
+Requires-Dist: pymatgen>=2024.2.20; extra == "optional"
+Requires-Dist: matminer>=0.9.2; extra == "optional"
+Requires-Dist: umap-learn>=0.5.3; extra == "optional"
+Requires-Dist: kaleido>=0.2.1; extra == "optional"
+Requires-Dist: ase>=3.22.0; extra == "optional"
+Requires-Dist: numpy; extra == "optional"
+Requires-Dist: ElementEmbeddings>=0.4; extra == "optional"
+Requires-Dist: dash>=2.18.2; extra == "optional"
+Provides-Extra: strict
+Requires-Dist: pydantic==2.9.2; extra == "strict"
+Requires-Dist: mp-api==0.42.2; extra == "strict"
+Requires-Dist: pymatviz==0.14; extra == "strict"
+Requires-Dist: seaborn==0.13.2; extra == "strict"
+Requires-Dist: pymatgen==2024.11.13; extra == "strict"
+Requires-Dist: matminer==0.9.2; extra == "strict"
+Requires-Dist: umap-learn==0.5.3; extra == "strict"
+Requires-Dist: kaleido==0.2.1; extra == "strict"
+Requires-Dist: ase==3.23.0; extra == "strict"
+Requires-Dist: numpy; extra == "strict"
+Requires-Dist: ElementEmbeddings==0.6.1; extra == "strict"
+Requires-Dist: dash==2.18.2; extra == "strict"
+
+[![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)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
@@ -45,96 +105,99 @@ Requires-Dist: typing-extensions
 [![codecov](https://codecov.io/gh/WMD-group/SMACT/branch/master/graph/badge.svg?token=UtgVxjoYNP)](https://codecov.io/gh/WMD-group/SMACT)
 ![PyPI - Downloads](https://img.shields.io/pypi/dm/smact)
 
-SMACT
-=====
+# SMACT
 
 **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
+- **Documentation:** <https://smact.readthedocs.io/en/latest/>
+- **Examples:** <https://smact.readthedocs.io/en/latest/examples.html>
 
-![](SMACT.png)
+![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)
 
-*If you torture the data enough, nature will always confess* - Roland Coase (from 'How should economists choose?')
+_If you torture the data enough, nature will always confess_ - Roland Coase (from 'How should economists choose?')
 
-Statement of need
---------
-There is a strong demand for functional materials across a wide range of technologies. The motivation can include cost reduction, performance enhancement, or to enable a new application. We have developed low-cost procedures for screening hypothetical materials. This framework can be used for simple calculations on your own computer. SMACT follows a top-down approach where a set of element combinations is generated and then screened using rapid chemical filters. It can be used as part of a multi-technique workflow or to feed machine learning models for materials.
+## Statement of need
 
-![](smact_simple.gif)
+There is a strong demand for functional materials across a wide range of technologies. The motivation can include cost reduction, performance enhancement, or to enable a new application. We have developed low-cost procedures for screening hypothetical materials. This framework can be used for simple calculations on your own computer. SMACT follows a top-down approach where a set of element combinations is generated and then screened using rapid chemical filters. It can be used as part of a multi-technique workflow or to feed artificial intelligence models for materials.
+
+![A gif depicting using the SMACT code. The first lines of code show how SMACT can be used to access properties of Iron (Fe) by create an Fe Element object and then accessing the oxidation states, pauling electronegativity. The next line after these shows the use of the smact_filter function for the Fe-Cu-O chemical system followed by the lists of possible compositions. ](smact_simple.gif)
+
+## Getting started
 
-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 used.
-Extended examples are available in [our examples folder](https://github.com/WMD-group/SMACT/tree/master/examples).
+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://smact.readthedocs.io/en/latest/examples.html) and [tutorials](https://smact.readthedocs.io/en/latest/tutorials.html) folders.
+
+## Code features
 
-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. 
+- 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: 
-  - A use case is shown in [this publication](https://pubs.rsc.org/en/content/articlehtml/2018/sc/c7sc03961a), in which 160,000 chemical compositions are screened based on optical band gap calculated using the [solid-state energy scale](https://www.sciencedirect.com/science/article/pii/S0022459615300888).
+- 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:
+
+  - An application is shown in [this publication](https://pubs.rsc.org/en/content/articlehtml/2018/sc/c7sc03961a), in which 160,000 chemical compositions are screened based on optical band gap calculated using the [solid-state energy scale](https://www.sciencedirect.com/science/article/pii/S0022459615300888).
   - The [oxidation_states module](https://smact.readthedocs.io/en/latest/smact.oxidation_states.html) can be used to filter out compositions containing metals in unlikely oxidation states according to [a data-driven model](https://pubs.rsc.org/en/content/articlelanding/2018/fd/c8fd00032h#!divAbstract).
 
-- 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 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: 
+- 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).
   - The [lattice module](https://smact.readthedocs.io/en/latest/smact.lattice.html) and [distorter module](https://smact.readthedocs.io/en/latest/smact.distorter.html) rely on the [Atomic Simulation Environment](https://wiki.fysik.dtu.dk/ase/) and can be used to generate unique atomic substitutions on a given crystal structure.
-  - 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 [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.
 
-List of modules
--------
-* **smact** library containing:
-  * **\_\_init\_\_.py** Contains the core `Element` and `Species` classes.
-  *  **data_loader.py** Handles the loading of external data used to initialise the core `smact.Element` and `smact.Species` classes.
-  *  **screening.py** Used for generating and applying filters to compositional search spaces.
-  *  **properties.py** A collection of tools for estimating useful properties based on composition.
-  * **lattice.py** Given the sites, multiplicities and possible oxidation states
+## List of modules
+
+- **smact** library containing:
+  - **\_\_init\_\_.py** Contains the core `Element` and `Species` classes.
+  - **data_loader.py** Handles the loading of external data used to initialise the core `smact.Element` and `smact.Species` classes.
+  - **screening.py** Used for generating and applying filters to compositional search spaces.
+  - **properties.py** A collection of tools for estimating useful properties based on composition.
+  - **lattice.py** Given the sites, multiplicities and possible oxidation states
     at those sites, this reads from the database and generates all possible
     stoichiometries.
-  * **builder.py** Builds some common lattice structures, given the chemical
+  - **builder.py** Builds some common lattice structures, given the chemical
     composition.
-  * **lattice_parameters.py** Estimation of lattice parameters for various lattice types using covalent/ionic radii.
-  * **distorter.py** A collection of functions for enumerating and then
+  - **lattice_parameters.py** Estimation of lattice parameters for various lattice types using covalent/ionic radii.
+  - **distorter.py** A collection of functions for enumerating and then
     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.
+  - **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
 
-Requirements
-------------
-The main language is Python 3 and has been tested using Python 3.9+.
+The main language is Python 3 and has been tested using Python 3.10+.
 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 [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.
+
+## Installation
 
-Installation
-------------
 The latest stable release can be installed via pip which will automatically set up other Python packages as required:
 
-    pip install smact  
+    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
-```
+    conda install -c conda-forge smact
 
 Alternatively, the very latest version can be installed using:
 
     pip install git+https://github.com/WMD-group/SMACT.git
 
 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.
+repository (<https://github.com/wmd-group/smact>); this will be preferred if using experimental code branches.
 
 To clone the project from GitHub and make a local installation:
 
@@ -145,19 +208,18 @@ To clone the project from GitHub and make a local 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.
 
-
-License and attribution
------------------------
+## License and attribution
 
 Python code and original data tables are licensed under the MIT License.
 
-Development notes
------------------
+## 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 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 anthony.onwuli16@imperial.ac.uk 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 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).
 
 ### 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.
@@ -166,27 +228,23 @@ We are always looking for ways to make SMACT better and more useful to the wider
 - 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. 
-Run the tests using `python -m pytest -v`.
-(The final `-v` is optional and adds more detail to the output.)
 
-We also use integrated testing on GitHub via [GitHub Actions](hhttps://github.com/features/actions).
+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.)
 
-References
-----------
+## References
 
 [H. Park et al.,
-"Mapping inorganic crystal chemical space" *Faraday Discuss.* (2024)](https://pubs.rsc.org/en/content/articlelanding/2024/fd/d4fd00063c)
+"Mapping inorganic crystal chemical space" _Faraday Discuss._ (2024)](https://pubs.rsc.org/en/content/articlelanding/2024/fd/d4fd00063c)
 
 [D. W. Davies et al.,
-"SMACT: Semiconducting Materials by Analogy and Chemical Theory" *JOSS* **4**, 1361 (2019)](https://joss.theoj.org/papers/7efd2f2ad60d25bdccee3fbd3fc11448)
+"SMACT: Semiconducting Materials by Analogy and Chemical Theory" _JOSS_ **4**, 1361 (2019)](https://joss.theoj.org/papers/7efd2f2ad60d25bdccee3fbd3fc11448)
 
 [D. W. Davies et al.,
-"Materials discovery by chemical analogy: role of oxidation states in structure prediction" *Faraday Discuss.* **211**, 553 (2018)](https://pubs.rsc.org/en/Content/ArticleLanding/2018/FD/C8FD00032H)
+"Materials discovery by chemical analogy: role of oxidation states in structure prediction" _Faraday Discuss._ **211**, 553 (2018)](https://pubs.rsc.org/en/Content/ArticleLanding/2018/FD/C8FD00032H)
 
 [D. W. Davies et al.,
-"Computational screening of all stoichiometric inorganic materials" *Chem* **1**, 617 (2016)](http://www.cell.com/chem/abstract/S2451-9294(16)30155-3)
+"Computational screening of all stoichiometric inorganic materials" _Chem_ **1**, 617 (2016)](<http://www.cell.com/chem/abstract/S2451-9294(16)30155-3>)
 
-[B. R. Pamplin, "A systematic method of deriving new semiconducting
-compounds by structural analogy", *J. Phys. Chem. Solids*
+[B. R. Pamplin, "A systematic method of deriving new semiconducting compounds by structural analogy", _J. Phys. Chem. Solids_
 **25**, 675 (1964)](http://www.sciencedirect.com/science/article/pii/0022369764901763)

{smact-2.7 → smact-3.0}/README.md

@@ -1,4 +1,4 @@
-[![DOI](http://joss.theoj.org/papers/10.21105/joss.01361/status.svg)](https://doi.org/10.21105/joss.01361)
+[![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)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
@@ -12,96 +12,99 @@
 [![codecov](https://codecov.io/gh/WMD-group/SMACT/branch/master/graph/badge.svg?token=UtgVxjoYNP)](https://codecov.io/gh/WMD-group/SMACT)
 ![PyPI - Downloads](https://img.shields.io/pypi/dm/smact)
 
-SMACT
-=====
+# SMACT
 
 **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
+- **Documentation:** <https://smact.readthedocs.io/en/latest/>
+- **Examples:** <https://smact.readthedocs.io/en/latest/examples.html>
 
-![](SMACT.png)
+![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)
 
-*If you torture the data enough, nature will always confess* - Roland Coase (from 'How should economists choose?')
+_If you torture the data enough, nature will always confess_ - Roland Coase (from 'How should economists choose?')
 
-Statement of need
---------
-There is a strong demand for functional materials across a wide range of technologies. The motivation can include cost reduction, performance enhancement, or to enable a new application. We have developed low-cost procedures for screening hypothetical materials. This framework can be used for simple calculations on your own computer. SMACT follows a top-down approach where a set of element combinations is generated and then screened using rapid chemical filters. It can be used as part of a multi-technique workflow or to feed machine learning models for materials.
+## Statement of need
 
-![](smact_simple.gif)
+There is a strong demand for functional materials across a wide range of technologies. The motivation can include cost reduction, performance enhancement, or to enable a new application. We have developed low-cost procedures for screening hypothetical materials. This framework can be used for simple calculations on your own computer. SMACT follows a top-down approach where a set of element combinations is generated and then screened using rapid chemical filters. It can be used as part of a multi-technique workflow or to feed artificial intelligence models for materials.
+
+![A gif depicting using the SMACT code. The first lines of code show how SMACT can be used to access properties of Iron (Fe) by create an Fe Element object and then accessing the oxidation states, pauling electronegativity. The next line after these shows the use of the smact_filter function for the Fe-Cu-O chemical system followed by the lists of possible compositions. ](smact_simple.gif)
+
+## Getting started
 
-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 used.
-Extended examples are available in [our examples folder](https://github.com/WMD-group/SMACT/tree/master/examples).
+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://smact.readthedocs.io/en/latest/examples.html) and [tutorials](https://smact.readthedocs.io/en/latest/tutorials.html) folders.
+
+## Code features
 
-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. 
+- 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: 
-  - A use case is shown in [this publication](https://pubs.rsc.org/en/content/articlehtml/2018/sc/c7sc03961a), in which 160,000 chemical compositions are screened based on optical band gap calculated using the [solid-state energy scale](https://www.sciencedirect.com/science/article/pii/S0022459615300888).
+- 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:
+
+  - An application is shown in [this publication](https://pubs.rsc.org/en/content/articlehtml/2018/sc/c7sc03961a), in which 160,000 chemical compositions are screened based on optical band gap calculated using the [solid-state energy scale](https://www.sciencedirect.com/science/article/pii/S0022459615300888).
   - The [oxidation_states module](https://smact.readthedocs.io/en/latest/smact.oxidation_states.html) can be used to filter out compositions containing metals in unlikely oxidation states according to [a data-driven model](https://pubs.rsc.org/en/content/articlelanding/2018/fd/c8fd00032h#!divAbstract).
 
-- 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 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: 
+- 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).
   - The [lattice module](https://smact.readthedocs.io/en/latest/smact.lattice.html) and [distorter module](https://smact.readthedocs.io/en/latest/smact.distorter.html) rely on the [Atomic Simulation Environment](https://wiki.fysik.dtu.dk/ase/) and can be used to generate unique atomic substitutions on a given crystal structure.
-  - 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 [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.
 
-List of modules
--------
-* **smact** library containing:
-  * **\_\_init\_\_.py** Contains the core `Element` and `Species` classes.
-  *  **data_loader.py** Handles the loading of external data used to initialise the core `smact.Element` and `smact.Species` classes.
-  *  **screening.py** Used for generating and applying filters to compositional search spaces.
-  *  **properties.py** A collection of tools for estimating useful properties based on composition.
-  * **lattice.py** Given the sites, multiplicities and possible oxidation states
+## List of modules
+
+- **smact** library containing:
+  - **\_\_init\_\_.py** Contains the core `Element` and `Species` classes.
+  - **data_loader.py** Handles the loading of external data used to initialise the core `smact.Element` and `smact.Species` classes.
+  - **screening.py** Used for generating and applying filters to compositional search spaces.
+  - **properties.py** A collection of tools for estimating useful properties based on composition.
+  - **lattice.py** Given the sites, multiplicities and possible oxidation states
     at those sites, this reads from the database and generates all possible
     stoichiometries.
-  * **builder.py** Builds some common lattice structures, given the chemical
+  - **builder.py** Builds some common lattice structures, given the chemical
     composition.
-  * **lattice_parameters.py** Estimation of lattice parameters for various lattice types using covalent/ionic radii.
-  * **distorter.py** A collection of functions for enumerating and then
+  - **lattice_parameters.py** Estimation of lattice parameters for various lattice types using covalent/ionic radii.
+  - **distorter.py** A collection of functions for enumerating and then
     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.
+  - **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
 
-Requirements
-------------
-The main language is Python 3 and has been tested using Python 3.9+.
+The main language is Python 3 and has been tested using Python 3.10+.
 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 [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.
+
+## Installation
 
-Installation
-------------
 The latest stable release can be installed via pip which will automatically set up other Python packages as required:
 
-    pip install smact  
+    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
-```
+    conda install -c conda-forge smact
 
 Alternatively, the very latest version can be installed using:
 
     pip install git+https://github.com/WMD-group/SMACT.git
 
 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.
+repository (<https://github.com/wmd-group/smact>); this will be preferred if using experimental code branches.
 
 To clone the project from GitHub and make a local installation:
 
@@ -112,19 +115,18 @@ To clone the project from GitHub and make a local 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.
 
-
-License and attribution
------------------------
+## License and attribution
 
 Python code and original data tables are licensed under the MIT License.
 
-Development notes
------------------
+## 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 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 anthony.onwuli16@imperial.ac.uk 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 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).
 
 ### 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.
@@ -133,27 +135,23 @@ We are always looking for ways to make SMACT better and more useful to the wider
 - 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. 
-Run the tests using `python -m pytest -v`.
-(The final `-v` is optional and adds more detail to the output.)
 
-We also use integrated testing on GitHub via [GitHub Actions](hhttps://github.com/features/actions).
+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.)
 
-References
-----------
+## References
 
 [H. Park et al.,
-"Mapping inorganic crystal chemical space" *Faraday Discuss.* (2024)](https://pubs.rsc.org/en/content/articlelanding/2024/fd/d4fd00063c)
+"Mapping inorganic crystal chemical space" _Faraday Discuss._ (2024)](https://pubs.rsc.org/en/content/articlelanding/2024/fd/d4fd00063c)
 
 [D. W. Davies et al.,
-"SMACT: Semiconducting Materials by Analogy and Chemical Theory" *JOSS* **4**, 1361 (2019)](https://joss.theoj.org/papers/7efd2f2ad60d25bdccee3fbd3fc11448)
+"SMACT: Semiconducting Materials by Analogy and Chemical Theory" _JOSS_ **4**, 1361 (2019)](https://joss.theoj.org/papers/7efd2f2ad60d25bdccee3fbd3fc11448)
 
 [D. W. Davies et al.,
-"Materials discovery by chemical analogy: role of oxidation states in structure prediction" *Faraday Discuss.* **211**, 553 (2018)](https://pubs.rsc.org/en/Content/ArticleLanding/2018/FD/C8FD00032H)
+"Materials discovery by chemical analogy: role of oxidation states in structure prediction" _Faraday Discuss._ **211**, 553 (2018)](https://pubs.rsc.org/en/Content/ArticleLanding/2018/FD/C8FD00032H)
 
 [D. W. Davies et al.,
-"Computational screening of all stoichiometric inorganic materials" *Chem* **1**, 617 (2016)](http://www.cell.com/chem/abstract/S2451-9294(16)30155-3)
+"Computational screening of all stoichiometric inorganic materials" _Chem_ **1**, 617 (2016)](<http://www.cell.com/chem/abstract/S2451-9294(16)30155-3>)
 
-[B. R. Pamplin, "A systematic method of deriving new semiconducting
-compounds by structural analogy", *J. Phys. Chem. Solids*
-**25**, 675 (1964)](http://www.sciencedirect.com/science/article/pii/0022369764901763)
+[B. R. Pamplin, "A systematic method of deriving new semiconducting compounds by structural analogy", _J. Phys. Chem. Solids_
+**25**, 675 (1964)](http://www.sciencedirect.com/science/article/pii/0022369764901763)