Merge branch 'PhasesResearchLab:main' into main

.github/workflows/benchmarks.yaml

@@ -15,10 +15,10 @@ jobs:
       fail-fast: false
     runs-on: ubuntu-22.04
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
 
       - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v4
+        uses: actions/setup-python@v5
         with:
           python-version: ${{ matrix.python-version }}
           cache: 'pip'

.github/workflows/coreTests_LinuxUbuntu.yaml

@@ -15,10 +15,10 @@ jobs:
       fail-fast: false
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
 
       - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v4
+        uses: actions/setup-python@v5
         with:
           python-version: ${{ matrix.python-version }}
           cache: 'pip'

.github/workflows/coreTests_MacIntel.yaml

@@ -15,10 +15,10 @@ jobs:
       fail-fast: false
     runs-on: macos-12
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
 
       - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v4
+        uses: actions/setup-python@v5
         with:
           python-version: ${{ matrix.python-version }}
           cache: 'pip'

.github/workflows/coreTests_MacM1.yaml

@@ -15,10 +15,10 @@ jobs:
       fail-fast: false
     runs-on: macos-14
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
 
       - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v4
+        uses: actions/setup-python@v5
         with:
           python-version: ${{ matrix.python-version }}
           cache: 'pip'

.github/workflows/coreTests_Windows.yaml

@@ -15,10 +15,10 @@ jobs:
       fail-fast: false
     runs-on: windows-latest
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
 
       - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v4
+        uses: actions/setup-python@v5
         with:
           python-version: ${{ matrix.python-version }}
           cache: 'pip'

.github/workflows/fullTest.yaml

@@ -15,10 +15,10 @@ jobs:
     strategy:
       fail-fast: false
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
 
       - name: Set up Python 3.9
-        uses: actions/setup-python@v4
+        uses: actions/setup-python@v5
         with:
           python-version: '3.9'
           cache: 'pip'
@@ -52,10 +52,10 @@ jobs:
     needs: testPython309
     runs-on: macos-12
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
 
       - name: Set up Python 3.10
-        uses: actions/setup-python@v4
+        uses: actions/setup-python@v5
         with:
           python-version: '3.10'
           cache: 'pip'
@@ -86,10 +86,10 @@ jobs:
     needs: testPython310
     runs-on: macos-12
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
 
       - name: Set up Python 3.11
-        uses: actions/setup-python@v4
+        uses: actions/setup-python@v5
         with:
           python-version: '3.11'
           cache: 'pip'

.github/workflows/publishPyPI.yaml

@@ -4,15 +4,16 @@ on:
   push:
     tags:
       - '**'
+  workflow_dispatch:
 
 jobs:
   deploy:
-    runs-on: macos-14
+    runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v4
 
     - name: Set up Python
-      uses: actions/setup-python@v4
+      uses: actions/setup-python@v5
       with:
         python-version: '3.10'
         cache: 'pip'

.github/workflows/weeklyTesting.yaml

@@ -14,10 +14,10 @@ jobs:
       fail-fast: false
     runs-on: ${{ matrix.platform }}
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
 
       - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v4
+        uses: actions/setup-python@v5
         with:
           python-version: ${{ matrix.python-version }}
           cache: 'pip'
@@ -35,12 +35,12 @@ jobs:
           
   testFullPython310:
     needs: coreTests
-    runs-on: ubuntu-22.04
+    runs-on: macos-12
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
 
       - name: Set up Python 3.10
-        uses: actions/setup-python@v4
+        uses: actions/setup-python@v5
         with:
           python-version: '3.10'
           cache: 'pip'

.gitignore

@@ -8,4 +8,8 @@ docs/jupyter_execute
 pysipfenn.egg-info
 
 # ONNX Models
-*.onnx
+*.onnx
+
+# Test and temporary files
+**/*_TestResult.csv
+**/TestResult_*.csv

README.md

@@ -38,19 +38,18 @@ Research Lab webpage under https://phaseslab.com/sipfenn.
 
 ### Major News:
 
-- **(v0.13.0)** Model exports are now effortless the new `pysipfenn.core.modelExporters` module, which also allows
-users to reduce models to FP16 precision or simplify model structure. It supports ONNX, PyTorch, and CoreML formats. The
-latter allows use of highly efficient Neural Engine on all modern Apple devices. Note that to use these features, you
-need to install additional dependencies with `pip install pysipfenn[dev]`.
-- **(v0.12.2)** The license has been changed to LGPLv3 to allow for integration with proprietary software developed
-by CALPHAD community, while supporting the development of new pySIPFENN features for all users. Many thanks to our colleagues from 
-[GTT-Technologies](https://gtt-technologies.de) and other participants of [50th CALPHAD 2023 conference in Boston](https://calphad.org/calphad-2023) for fruitful discussions.
-- **(v0.12.0)** Official Python 3.11 support.
+- **(v0.15.0)** A new descriptor (feature vector) calculator [**`descriptorDefinitions.KS2022_randomSolutions`**](https://github.com/PhasesResearchLab/pySIPFENN/blob/main/pysipfenn/descriptorDefinitions/KS2022_randomSolutions.py) has been implemented. It is used for structure informed featurization of compositions randomly occupying a lattice, spiritually similar to SQS generation, but also taking into account (1) chemical differences between elements and (2) structural effects. A full description will be given in the upcoming manuscript.
+
+- **(v0.14.0)** Users can now take advantage of a **Prototype Library** to obtain common structures from any `Calculator` instance `c` with a simple `c.prototypeLibrary['BCC']['structure']`. It can be easily [updated](https://pysipfenn.readthedocs.io/en/latest/source/pysipfenn.core.html#pysipfenn.Calculator.parsePrototypeLibrary) or [appended](https://pysipfenn.readthedocs.io/en/latest/source/pysipfenn.core.html#pysipfenn.Calculator.appendPrototypeLibrary) with high-level API or by manually modifyig its YAML [here](https://github.com/PhasesResearchLab/pySIPFENN/blob/main/pysipfenn/misc/prototypeLibrary.yaml).
+
+- **(v0.13.0)** Model exports (and more!) to PyTorch, CoreML, and ONNX are now effortless thanks to [**`core.modelExporters`**](https://github.com/PhasesResearchLab/pySIPFENN/blob/main/pysipfenn/core/modelExporters.py) module. Please note you need to install pySIPFENN with `dev` option (e.g., `pip install "pysipfenn[dev]"`) to use it. See [docs here](https://pysipfenn.readthedocs.io/en/stable/source/pysipfenn.core.html#module-pysipfenn.core.modelExporters).
+
+- **(v0.12.2)** Swith to LGPLv3 allowing for integration with proprietary software developed by CALPHAD community, while supporting the development of new pySIPFENN features for all. Many thanks to our colleagues from 
+[GTT-Technologies](https://gtt-technologies.de) and other participants of [CALPHAD 2023](https://calphad.org/calphad-2023) for fruitful discussions.
+
 - **(March 2023 Workshop)** We would like to thank all of our amazing attendees for making our workshop, co-organized with the
 [Materials Genome Foundation](https://materialsgenomefoundation.org), such a success! Over 100 of you simultaneously followed
-all exercises and, at the peak, we loaded over 1,200GB of models into the HPC's RAM. At this point, we would also like to 
-acknowledge the generous support from [IBM](https://www.ibm.com) who funded the workshop. Please stay tuned for next workshops
-planned online and in-person at conferences. They will be announced both here and at the [Materials Genome Foundation](https://materialsgenomefoundation.org) website.
+all exercises and, at the peak, we loaded over 1,200GB of models into the HPC's RAM. 
 
 ### Applications
 
@@ -90,29 +89,35 @@ https://doi.org/10.1038/s41598-021-03578-0
 
 ## Installation
 
-Installing pySIPFENN is simple and easy by utilizing **PyPI** package repository, **conda-forge**, or by cloning from **GitHub** directly.
+Installing pySIPFENN is simple and easy by utilizing **PyPI** package repository, **conda-forge**  package repository, or by cloning from **GitHub** directly.
 While not required, it is recommended to first set up a virtual environment using venv or Conda. This ensures that (a) one of the required 
-versions of Python (3.9+) is used and (b) there are no dependency conflicts. If you have Conda installed on your system (see instructions 
-at https://docs.conda.io/en/latest/miniconda.html), you can create a new environment with a simple:
+versions of Python (3.9+) is used and (b) there are no dependency conflicts. If you have Conda installed on your system (see [`miniconda` install instructions](https://docs.conda.io/en/latest/miniconda.html)), you can create a new environment with a simple:
 
     conda create -n pysipfenn python=3.10 jupyter numpy 
     conda activate pysipfenn
 
+If you are managing a large set of dependencies in your project, you may consider using `mamba` in place of `conda`. It is a less mature, but much faster drop-in replacement compatible with existing environments. See [`micromamba` install instructions](https://mamba.readthedocs.io/en/latest/installation/micromamba-installation.html).
+
 ### Standard
 
 If your main goal is to run pySIPFENN models, provided by us or any other vendor, you need only a subset of the capabilities of our code, so
 you can follow with the following install. Simply install pySIPFENN:
 
-- from **PyPI** with:
+- from **PyPI** with `pip`:
     ```shell
     pip install pysipfenn
     ```
 
-- from **conda-forge** with:
+- from **conda-forge** with `conda`:
     ```shell
     conda install -c conda-forge pysipfenn
     ```
 
+- from **conda-forge** with `micromamba`:
+    ```shell
+    micromamba install -c conda-forge pysipfenn
+    ```
+
 - **from source**, by cloning. To get a stable version, you can specify a version tag after the URL with
 `--branch <tag_name> --single-branch`, or omit it to get the development version (which may have bugs!):
     ```shell

docs/conf.py

@@ -27,6 +27,7 @@
               'sphinx_autodoc_typehints',
               'myst_nb',
               'sphinx_github_changelog',
+              'sphinx_rtd_size'
               ]
 
 # Jupyter Notebook configuration
@@ -51,6 +52,8 @@
 
 html_theme = "sphinx_rtd_theme"
 html_static_path = ['_static']
+sphinx_rtd_size_width = "70%"
+
 
 html_context = {
     "display_github": True,

docs/contributing.md

@@ -0,0 +1,39 @@
+# Contributing
+
+## What to Contribute
+
+If you wish to contribute to the development of pySIPFENN you are more than welcome to do so by forking the repository and creating a pull request. As of Spring
+2024, we are actively developing the code and we should get back to you within a few days. We are also open to collaborations and partnerships, so if you have
+an idea for a new feature or a new model, please do not hesitate to contact us through the GitHub issues or by `email <mailto:[email protected]>`__.
+
+In particular, we are seeking contributions in the following areas:
+
+- **New Models**: We are always looking for new models to add to the repository. We have several (yet) unpublished ones for several different properties, so there is a good chance it will work for your case as well. We are happy to provide basic support for training, including using the default model for **transfer learning on small datasets**.
+
+- **New Featurizers / Descriptor Sets**: We are always looking for new ways to featurize atomic configurations. 
+    - We are **particularly interested** in including more domain-specific knowledge for different niches of materials science. Our KS2022 does a good job for most materials, but we look to expand it. 
+    - We are **not looking for** featurizers that (a) cannot embed a structure into the feature space (e.g., most of the graph representations, which became popular in the last two years) or (b) do not encode physics into the feature space (e.g., raw atomic coordinates or 3D voxel representations).
+    - Note: Autoencoders which utilize graph or 3D voxel representations to encode latent space position to predict property/properties fall into the first category and **are very welcome**.
+
+- **Quality of Life Improvements**: We are always looking for ways to make the software easier to use and more efficient for users. If you have an idea for a new data parsing method, or a new way to visualize the results, we would love to hear about it.
+
+## Rules for Contributing
+
+We are currently very flexible with the rules for contributing, despite being quite opinionated :) 
+
+Some general guidelines are:
+- The ``core`` module is the only one that should be used by our typical end user. All **top-level APIs should be defined in the ``pysipfenn.py``** through the ``Calculator`` class. APIs operating _on_ the ``Calculator`` class, to export or retrain models, should be defined outside it, but within ``pysipfenn.core`` module.
+
+- All **featurizers / descriptor calculators _must_ be self-contained in a single submodule** (file or directory) of ``pysipfenn.descriptorDefinitions`` (i.e., not spread around the codebase) and depend only on standard Python library and current pySIPFENN dependencies, including ``numpy``, ``torch``, ``pymatgen``, ``onnx``, ``tqdm``. If you need to add a new dependency, please discuss it with us first.
+
+- All models **_must_ be ONNX models**, which can be obtained from almost any machine learning framework. We are happy to help with this process.
+
+- All new classes, attributes, and methods **_must_ be type-annotated**. We are happy to help with this process.
+
+- All new classes, attributes, and methods **_must_ have a well-styled docstring**. We are happy to help with this process.
+
+- All functions, classes, and methods **_should_ have explicit inputs**, rather than passing a dictionary of parameters (*kwargs). This does require a bit more typing, but it makes the code much easier to use for the end user, who can see in the IDE exactly what parameters are available and what they do.
+
+- All functions, classes, and methods **_should_ explain _why_ they are doing something, not just _what_** they are doing. This is critical for end-users who did not write the code and are trying to understand it. In particular, the default values of parameters should be explained in the docstring.
+
+- All new features _must_ be tested with the ``pytest`` framework. **Coverage _should_ be 100%** for new code or close to it for good reasons. We are happy to help with this process.

docs/docs_requirements.txt

@@ -1,5 +1,6 @@
 sphinx-github-changelog>=1.2.1
 sphinx-autodoc-typehints
+sphinx-rtd-size
 sphinx-rtd-theme>=1.3.0
 myst-nb>=0.17.2
 sphinx>5.0.0