Version 1.1

.github/PULL_REQUEST_TEMPLATE/pull_request_template.md

@@ -0,0 +1,14 @@
+# Description
+
+> _Briefly describe the purpose and content of this merge request._
+> _E.g. "Add structure generation constraints", or "Fix bug in energy parsing"._
+
+# Checklist
+
+Mark with `x` when complete, or `~` if not applicable.
+
+- [ ] [I have read and followed the **RAFFLE's contribution guidelines.**](https://github.com/ExeQuantCode/RAFFLE/blob/main/CONTRIBUTING.md)
+- [ ] **Code is commented** appropriately, and API docstrings follow NumPy or FORD style.
+- [ ] **Read*the*Docs** documentation is added/updated (if applicable).
+- [ ] **Unit tests** are added/updated (if applicable).
+- [ ] **Linked issue** is resolved with a `closes #XXXX` reference (if applicable).

.gitignore

@@ -45,6 +45,7 @@ IBZKPT
 KPOINTS
 PCDAT
 REPORT
+[0-9][0-9][0-9][0-9]_*.json
 vasprun.xml
 DVASP_MACE_comparison/
 pca_model*.pkl
@@ -53,4 +54,9 @@ pca_model*.pkl
 *.tgz
 .ipynb_checkpoints
 *.model
-*.vasp
+*.vasp
+*.pkl
+meta.json
+context.json
+options.json
+procedure.py

.pre-commit-config.yaml

@@ -5,7 +5,7 @@ repos:
     -   id: trailing-whitespace
     -   id: end-of-file-fixer
 -   repo: https://github.com/nedtaylor/fortran-format-hooks
-    rev: e757850a2edabf0c06326ea18acc8125d12054ec
+    rev: 749c61fce3a5f29f6d5d3b236ed9b693c6b2bf4e
     hooks:
     -   id: check-fortran-indentation
-        args: [--line-length=80, --ignore-directories 'src/wrapper']
+        args: [--line-length=80, --ignore-directories=src/wrapper]

CITATION.cff

@@ -7,8 +7,9 @@ title: >-
   minima
 message: >-
   If you use this software, please cite it using the
-  metadata from this file and the following paper:
+  metadata from this file and the following papers:
   https://link.aps.org/doi/10.1103/PhysRevLett.132.066201
+  https://arxiv.org/abs/2504.02528
 type: software
 authors:
   - given-names: Ned Thaddeus

CMakeLists.txt

@@ -74,6 +74,7 @@ set(LIB_DIR ${FORTRAN_SRC_DIR}/lib)
 set(LIB_FILES
 	mod_io_utils.F90
 	mod_constants.f90
+    mod_cache.f90
 	mod_misc.f90
     mod_tools_infile.f90
 	mod_misc_maths.f90

CONTRIBUTING.md

@@ -92,7 +92,7 @@ When submitting your contributions, please ensure the following:
 - Reference any related issues or pull requests, if applicable.
 - Write unit tests for your contributions
 - Ensure all existing tests pass before submitting your changes.
-- Update the documentation to reflect your changes, if necessary (i.e. through FORD style commenting).
+- Update the documentation to reflect your changes, if necessary (i.e. through FORD style commenting for Fortran and NumPy docstrings style for Python).
 - Provide examples and usage instructions, if applicable.
 
 Follow the [Code Style](#code-style) when contributing code to this project to ensure compatibility and a uniform format to the project.
@@ -101,7 +101,7 @@ Follow the [Code Style](#code-style) when contributing code to this project to e
 ### Code Style
 - Follow the existing code style and conventions.
 - Use meaningful variable and function names.
-- Write clear and concise comments. For the Fortran library, use comments compatible with the [FORD Fortran Documenter](https://forddocs.readthedocs.io/en/stable/). For the Python wrapper, use comments compatible with [pandoc](https://pandoc.org).
+- Write clear and concise comments. For the Fortran library, use comments compatible with the [FORD Fortran Documenter](https://forddocs.readthedocs.io/en/stable/). For the Python wrapper, use comments compatible with [pandoc](https://pandoc.org), following the [NumPy style guide](https://numpydoc.readthedocs.io/en/latest/format.html).
 
 
 

README.md

@@ -4,11 +4,12 @@
 
 [![GPLv3 workflow](https://img.shields.io/badge/License-GPLv3-yellow.svg)](https://www.gnu.org/licenses/gpl-3.0.en.html "View GPLv3 license")
 [![Latest Release](https://img.shields.io/github/v/release/ExeQuantCode/RAFFLE?sort=semver)](https://github.com/ExeQuantCode/RAFFLE/releases "View on GitHub")
-[![Paper](https://img.shields.io/badge/Paper-Phys_Rev_B-blue.svg)](https://link.aps.org/doi/10.1103/PhysRevLett.132.066201)
+[![Methods Paper](https://img.shields.io/badge/Paper-Phys_Rev_B-blue.svg)](https://link.aps.org/doi/10.1103/PhysRevLett.132.066201)
+[![Code Paper](https://img.shields.io/badge/Paper-arXiv-red.svg)](https://doi.org/10.48550/arXiv.2504.02528)
 [![Documentation Status](https://readthedocs.org/projects/raffle-fortran/badge/?version=latest)](https://raffle-fortran.readthedocs.io/en/latest/?badge=latest "RAFFLE ReadTheDocs")
-[![FPM](https://img.shields.io/badge/fpm-0.10.1-purple)](https://github.com/fortran-lang/fpm "View Fortran Package Manager")
+[![FPM](https://img.shields.io/badge/fpm-0.11.0-purple)](https://github.com/fortran-lang/fpm "View Fortran Package Manager")
 [![CMAKE](https://img.shields.io/badge/cmake-3.27.7-red)](https://github.com/Kitware/CMake/releases/tag/v3.27.7 "View cmake")
-[![GCC compatibility](https://img.shields.io/badge/gcc-14.1.0-green)](https://gcc.gnu.org/gcc-14/ "View GCC")
+[![GCC compatibility](https://img.shields.io/badge/gcc-14.2.0-green)](https://gcc.gnu.org/gcc-14/ "View GCC")
 [![Coverage](https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/nedtaylor/48f14ebb5636b54d3813e4b4494903eb/raw/raffle_coverage_main.json)](https://ExeQuantCode.github.io/RAFFLE/ "View coverage report")
 
 
@@ -17,7 +18,7 @@
 by Ned Thaddeus Taylor, Joe Pitfield, and Steven Paul Hepplestone
 
 RAFFLE (pseudoRandom Approach For Finding Local Energetic minima) is a package for structural prediction applied to material interfaces.
-RAFFLE can interface with the [Atomic Simulation Environment (ASE)](https://gitlab.com/ase/ase).
+RAFFLE interfaces with the [Atomic Simulation Environment (ASE)](https://gitlab.com/ase/ase).
 
 RAFFLE is both a Fortran and a Python library, with the option of a Fortran executable.
 The code heavily relies on features of Fortran 2018 and above, so there is no backwards compatibility with Fortran95.
@@ -26,7 +27,7 @@ The code heavily relies on features of Fortran 2018 and above, so there is no ba
 
 Tutorials and documentation are provided on the [docs](http://raffle-fortran.readthedocs.io/) website.
 The methodology is detailed in the [Phys Rev B paper](https://link.aps.org/doi/10.1103/PhysRevLett.132.066201).
-The software package will be submitted for publication soon.
+The paper detailing the software package is currently avaialble on [arXiv](https://doi.org/10.48550/arXiv.2504.02528) with plans for peer-reviewed publication.
 
 Refer to the [API Documentation section](#api-documentation) later in this document to see how to access the API-specific documentation.
 
@@ -47,7 +48,7 @@ Python-specific installation:
 - meson
 - make or ninja
 - CMake
-- ASE (optional)
+- ASE
 
 The library bas been developed and tested using the following Fortran compilers:
 - gfortran -- gcc 11.4.0
@@ -65,12 +66,6 @@ For the Python library, the easiest method of installation is to install it dire
 pip install raffle
 ```
 
-or
-
-```
-pip install 'raffle[ase]'
-```
-
 Once this is done, RAFFLE is ready to be used.
 
 Alternatively, to download development versions or, if, for some reason, the pip method does not work, then RAFFLE can be installed from the source.
@@ -194,7 +189,7 @@ Contributing
 
 Please note that this project adheres to the [Contributing Guide](CONTRIBUTING.md).
 If you want to contribute to this project, please first read through the guide.
-If you have any questions, bug reports, or feature requests, please either discuss then in [issues](https://github.com/nedtaylor/athena/issues).
+If you have any questions, bug reports, or feature requests, please either discuss then in [issues](https://github.com/ExeQuantCode/raffle/issues).
 
 
 License
@@ -225,4 +220,16 @@ If you use this code, please cite our papers:
   doi = {10.1103/PhysRevLett.132.066201},
   url = {https://link.aps.org/doi/10.1103/PhysRevLett.132.066201}
 }
+
+@article{Taylor2025RAFFLEActiveLearning,
+  title = {RAFFLE: Active learning accelerated interface structure prediction},
+  author = {Taylor,  Ned Thaddeus and Pitfield,  Joe and Davies,  Francis Huw and Hepplestone,  Steven Paul},
+  year = {2025},
+  eprint={2504.02528},
+  archivePrefix={arXiv},
+  primaryClass={cond-mat.mtrl-sci},
+  doi = {10.48550/ARXIV.2504.02528},
+  url = {https://arxiv.org/abs/2504.02528},
+  publisher = {arXiv},
+}
 ```

docs/RAFFLE.bib

@@ -0,0 +1,26 @@
+@article{Pitfield2024PredictingPhaseStability,
+  title = {Predicting Phase Stability at Interfaces},
+  author = {Pitfield, J. and Taylor, N. T. and Hepplestone, S. P.},
+  journal = {Phys. Rev. Lett.},
+  volume = {132},
+  issue = {6},
+  pages = {066201},
+  numpages = {8},
+  year = {2024},
+  month = {Feb},
+  publisher = {American Physical Society},
+  doi = {10.1103/PhysRevLett.132.066201},
+  url = {https://link.aps.org/doi/10.1103/PhysRevLett.132.066201}
+}
+
+@article{Taylor2025RAFFLEActiveLearning,
+  title = {RAFFLE: Active learning accelerated interface structure prediction},
+  author = {Taylor,  Ned Thaddeus and Pitfield,  Joe and Davies,  Francis Huw and Hepplestone,  Steven Paul},
+  year = {2025},
+  eprint={2504.02528},
+  archivePrefix={arXiv},
+  primaryClass={cond-mat.mtrl-sci},
+  doi = {10.48550/ARXIV.2504.02528},
+  url = {https://arxiv.org/abs/2504.02528},
+  publisher = {arXiv},
+}

docs/source/conf.py

@@ -21,6 +21,13 @@
 # -- General configuration
 master_doc = 'index'
 
+# Identify the branch of the documentation
+on_rtd = os.environ.get('READTHEDOCS') == 'True'
+if on_rtd:
+    git_branch = os.environ.get("READTHEDOCS_GIT_IDENTIFIER", "main")
+else:
+    git_branch = "main"  # or get from git directly with subprocess
+
 extensions = [
     'sphinx.ext.duration',
     'sphinx.ext.doctest',
@@ -31,8 +38,13 @@
     'sphinx.ext.napoleon',
     'sphinx.ext.viewcode',
     'sphinx_rtd_theme',
+    'sphinx.ext.extlinks',
 ]
 
+extlinks = {
+    'git': ('https://github.com/ExeQuantCode/RAFFLE/blob/' + git_branch + '/%s', 'git: %s')
+}
+
 intersphinx_mapping = {
     'python': ('https://docs.python.org/3/', None),
     'sphinx': ('https://www.sphinx-doc.org/en/master/', None),

docs/source/faq.rst

@@ -0,0 +1,123 @@
+.. _faq:
+
+==========================
+Frequently Asked Questions
+==========================
+
+
+Issues with installation
+========================
+
+We have found that there are some issues with the installation of RAFFLE on some systems.
+These often relate to the Fortran and C compilers.
+
+Pip pointing to incorrect Fortran and C compilers
+-------------------------------------------------
+
+If you are using pip to install RAFFLE, you may encounter an issue where pip points to the wrong Fortran and C compilers (this can happen with both local installation and installation from PyPI).
+This can happen if you have multiple versions of gfortran and gcc installed on your system, or if you have installed them using a package manager such as Homebrew.
+To fix this, you can set the environment variables ``CC`` and ``FC`` to point to the correct compilers before running pip.
+To do this, run the following commands:
+
+.. code-block:: bash
+
+    export CC=$(which gfortran)
+    export FC=$(which gfortran)
+    export CXX=$(which g++)
+
+This will set the environment variables to point to the correct compilers (the ones you currently have in your path).
+
+However, we have found this to not always work either.
+So, another option is to run the following line to install RAFFLE:
+
+.. code-block:: bash
+
+    CC=<PATH_TO_C_COMPILER> FC=<PATH_TO_FORTRAN_COMPILER> CXX=<PATH_TO_CXX_COMPILER> pip install --upgrade raffle
+
+Installing on MacOS (Homebrew)
+------------------------------
+
+RAFFLE is developed on Linux and MacOS, and should work on both.
+However, there are likely some additional steps required to install RAFFLE on MacOS.
+This is because **it is not recommended to rely on the Mac system Python, or Fortran and C compilers**.
+
+The recommended way to install Python, gfortran and gcc on MacOS is to use `Homebrew <https://brew.sh>`_.
+First, install Homebrew by following the guide on their website.
+
+Once Homebrew is installed, you can install the required dependencies by running:
+
+.. code-block:: bash
+
+    brew install python
+    brew install gcc
+    brew install gfortran
+    export CC=$(brew --prefix gfortran)
+    export FC=$(brew --prefix gcc)
+
+Confirm a successful Python installation by running:
+
+.. code-block:: bash
+
+    python --version
+    whereis python
+
+This should show the correct Python version (3.11 or later) and path.
+
+Next, if you are using ``pip``, then the following command is found to result in the least issues:
+
+.. code-block:: bash
+
+    python -m pip install --upgrade .
+
+This ensures that the correct Python version is being called, and that the correct version of ``pip`` is being used.
+
+
+Issues with running RAFFLE
+==========================
+
+Sometimes, RAFFLE installs correctly, but you may encounter issues when running it.
+This is often due to missing dependencies or incorrect environment variables.
+
+Missing Fortran libraries
+--------------------------
+
+Sometimes, installation works fine, but you may encounter an error when running RAFFLE that looks like this:
+
+.. code-block:: text
+
+    ImportError: libgfortran.so.5: cannot open shared object file: No such file or directory
+
+To fix this, you need to install the correct version of the gfortran library.
+If you are using a conda environment, you can do this by running the following command:
+
+.. code-block:: bash
+
+    conda install -c conda-forge libgfortran-ng libgfortran5
+
+
+General
+=======
+
+.. _cite:
+
+How to cite RAFFLE?
+--------------------
+
+If you use RAFFLE in your research, please cite the following papers:
+
+
+    | Joe Pitfield, Ned Thaddeus Taylor, Steven Paul Hepplestone,
+    | Predicting Phase Stability at Interfaces,
+    | Phys. Rev. Lett. 132, 066201, 2024.
+    | doi: 10.1103/PhysRevLett.132.066201
+
+and
+
+    | Ned Thaddeus Taylor, Joe Pitfield, Steven Paul Hepplestone,
+    | RAFFLE: Active learning accelerated interface structure prediction,
+    | arXiv, 2504.02528v1, 2025.
+    | doi: 10.48550/arXiv.2504.02528
+
+BibTex (:git:`bibliography <docs/RAFFLE.bib>`):
+
+.. literalinclude:: ../RAFFLE.bib