Version 1.0 release

.github/workflows/cmake.yml

@@ -37,6 +37,7 @@ jobs:
         python-version: [ "3.11", "3.12", "3.13" ]
         toolchain:
         - {fortran-compiler: gcc, fc-version: 13}
+        - {fortran-compiler: gcc, fc-version: 14}
         # - {fortran-compiler: intel, fc-version: '2024.1'}
         # - {fortran-compiler: intel-classic,fc- version: '2021.10'}
         # exclude:

.github/workflows/coverage.yml

@@ -101,13 +101,19 @@ jobs:
       - name: upload artifact
         uses: actions/upload-pages-artifact@v3
         with: 
-          path: './build/coverage/'
+          path: './build/coverage/'        
 
-      # Deploy to GitHub Pages: uniform pattern for all branches
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: run-code-coverage
+    if: ${{ github.ref == 'refs/heads/main' }}
+    steps:
       - name: deploy to Github Pages (main branch)
-        if: ${{ github.ref == 'refs/heads/main' }}
-        uses: actions/deploy-pages@v2
         id: deployment
+        uses: actions/deploy-pages@v4
 
       # - name: deploy to Github Pages (development branch)
       #   if: ${{ github.ref != 'refs/heads/main' }}

.github/workflows/formatting.yml

@@ -51,12 +51,10 @@ jobs:
 
       - name: Comment on PR if script failed
         if: github.event_name == 'pull_request' && steps.run_format_checker.outcome != 'success'
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         run: |
-          github.rest.issues.createComment({
-            issue_number: context.issue.number,
-            owner: context.repo.owner,
-            repo: context.repo.repo,
-            body: '⚠️ The format checker failed.
-              Please check the formatting of your code by running tools/check_indentation.py locally.'
-          })
+          gh pr comment ${{ github.event.pull_request.number }} --body "⚠️ The format checker failed.
+          Please check the formatting of your code by running tools/check_indentation.py locally."
+
 

.github/workflows/fpm.yml

@@ -36,6 +36,7 @@ jobs:
         os: [ubuntu-latest, macos-latest]
         toolchain:
         - {compiler: gcc, version: 13}
+        - {fortran-compiler: gcc, fc-version: 14}
         # - {compiler: intel, version: '2024.1'}
         # - {compiler: intel-classic, version: '2021.10'}
         # exclude:

.github/workflows/publish-to-test-pypi.yml

@@ -12,6 +12,37 @@ on:
   workflow_dispatch:
 
 jobs:
+  check-version-matches:
+    name: Check if version numbers match the GitHub tag
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Extract version from fpm.toml
+        id: fpm_version
+        run: echo "RAFFLE_FPM_VERSION=$(grep -oP '(?<=version = ")[^"]+' fpm.toml)" >> "$GITHUB_ENV"
+
+      - name: Extract version from mod_io_utils.F90
+        id: fortran_version
+        run: echo "RAFFLE_FORTRAN_VERSION=$(grep -oP '(?<=raffle__version__ = ")[^"]+' src/fortran/lib/mod_io_utils.F90)" >> "$GITHUB_ENV"
+
+      - name: Extract GitHub tag version
+        id: github_tag
+        run: echo "TAG_VERSION=${GITHUB_REF#refs/tags/v}" >> "$GITHUB_ENV"
+
+      - name: Verify version consistency
+        run: |
+          if [[ "$FPM_VERSION" != "$TAG_VERSION" ]]; then
+            echo "❌ Version mismatch: fpm.toml ($FPM_VERSION) does not match GitHub tag ($TAG_VERSION)"
+            exit 1
+          fi
+          if [[ "$FORTRAN_VERSION" != "$TAG_VERSION" ]]; then
+            echo "❌ Version mismatch: mod_io_utils.F90 ($FORTRAN_VERSION) does not match GitHub tag ($TAG_VERSION)"
+            exit 1
+          fi
+          echo "✅ Version numbers match!"
+
   build_wheel:
     name: Build wheel distribution 📦
     runs-on: ${{ matrix.platform[0] }}
@@ -24,6 +55,8 @@ jobs:
         python-version: [ "3.12" ] # cibuildwheel automatically runs on all versions of Python
         toolchain:
         - {fortran-compiler: gcc, fc-version: 13}
+    needs:
+      - check-version-matches
 
     steps:
     - name: checkout repo
@@ -127,6 +160,14 @@ jobs:
       id-token: write  # IMPORTANT: mandatory for sigstore
 
     steps:
+    - name: Check if GitHub release already exists
+      env:
+        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      run: |
+        if gh release view '${{ github.ref_name }}' --repo '${{ github.repository }}' > /dev/null 2>&1; then
+          echo "Release already exists for tag '${{ github.ref_name }}'. Skipping release creation."
+          exit 0
+        fi
     - name: Download all the dists
       uses: actions/download-artifact@v4
       with:

.gitignore

@@ -48,4 +48,9 @@ REPORT
 vasprun.xml
 DVASP_MACE_comparison/
 pca_model*.pkl
-.benchmarks/
+.benchmarks/
+.local-pre-commit-config.yaml
+*.tgz
+.ipynb_checkpoints
+*.model
+*.vasp

.pre-commit-config.yaml

@@ -0,0 +1,11 @@
+repos:
+-   repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0  # Use the ref you want to point at
+    hooks:
+    -   id: trailing-whitespace
+    -   id: end-of-file-fixer
+-   repo: https://github.com/nedtaylor/fortran-format-hooks
+    rev: 5400a80b67ac12f16dd70d1200d6c5a06dbf8855
+    hooks:
+    -   id: check-fortran-indentation
+        args: [--line-length=80, --ignore-directories 'src/wrapper']

CITATION.cff

@@ -31,6 +31,6 @@ keywords:
   - structure prediction
   - random structure search
 license: GPL-3.0
-commit: 4cdf115d5d43d6f97037f6cb15c036dc9615eacb
-version: 0.5.0
-date-released: '2024-12-18'
+commit: 1a4e7aacf07b4d9623d846df30aa7ac3a5e98e81
+version: 1.0.0
+date-released: '2025-03-03'

CONTRIBUTING.md

@@ -0,0 +1,117 @@
+# Contributing Guidelines
+
+Thank you for considering contributing to the RAFFLE project! We appreciate your time and effort. To ensure a smooth collaboration, please follow the guidelines provided below.
+
+Please first discuss potential changes you wish to make to the project via issue (preferably), or email.
+
+> And if you like the project, but just don't have time to contribute, that's fine. There are other easy ways to support the project and show your appreciation, which we would also be very happy about:
+> - Star the project
+> - Mention it on social media platforms
+> - Refer this project in your project's readme
+> - Mention the project at local meetups and tell your friends/colleagues
+
+<!-- omit in toc -->
+
+## Table of Contents
+- [Code of Conduct](#code-of-conduct)
+- [I Have a Question](#i-have-a-question)
+- [I Want to Contribute](#i-want-to-contribute)
+- [Reporting Bugs](#reporting-bugs)
+- [Suggesting Enhancements](#suggesting-enhancements)
+- [Code Style](#code-style)
+- [Testing](#testing)
+- [Documentation](#documentation)
+- [Contact](#contact)
+- [License](#license)
+
+
+## Code of Conduct
+
+This project and everyone participating in it is governed by the
+[RAFFLE Code of Conduct](CODE_OF_CONDUCT.md).
+By participating, you are expected to uphold this code.
+Please report unacceptable behavior to the RAFFLE developers: [Ned Taylor](mailto:n.t.taylor@exeter.ac.uk?subject=RAFFLE%20-%behaviour) or [Steve Hepplestone](mailto:s.p.hepplestone@exeter.ac.uk?subject=RAFFLE%20-%behaviour).
+
+## I Have a Question
+
+> If you want to ask a question, we assume that you have read the available [Documentation](README.md).
+
+Before you ask a question, it is best to search for existing [Issues](https://github.com/ExeQuantCode/RAFFLE/issues) that might help you.
+In case you have found a suitable issue and still need clarification, you can write your question in this issue. It is also advisable to search the internet for answers first.
+
+If you then still feel the need to ask a question and need clarification, we recommend the following:
+
+- Open an [Issue](https://github.com/ExeQuantCode/RAFFLE/issues/new).
+- Provide as much context as you can about what you're running into.
+- Provide project and platform versions (python, fortran, pip), depending on what seems relevant.
+
+We will then take care of the issue as soon as possible.
+
+## I Want To Contribute
+
+> ### Legal Notice <!-- omit in toc -->
+> When contributing to this project, you must agree that you have authored 100% of the content, that you have the necessary rights to the content and that the content you contribute may be provided under the project license.
+
+### Reporting Bugs
+If you encounter any issues or have suggestions for improvement, please open an [Issue](https://github.com/ExeQuantCode/RAFFLE/issues/new) on the repository's issue tracker.
+
+When reporting, please provide as much context as possible and describe the reproduction steps that someone else can follow to recreate the issue on their own.
+This usually includes your code.
+For good bug reports you should isolate the problem and create a reduced test case.
+
+
+
+### Suggesting Enhancements
+
+This section guides you through submitting an enhancement suggestion for RAFFLE, **including completely new features and minor improvements to existing functionality**.
+Following these guidelines will help maintainers and the community to understand your suggestion and find related suggestions.
+
+<!-- omit in toc -->
+#### Before Submitting an Enhancement
+
+- Make sure that you are using the latest version.
+- Read the compilable documentation carefully and find out if the functionality is already covered.
+- Perform a [search](https://github.com/ExeQuantCode/RAFFLE/issues) to see if the enhancement has already been suggested. If it has, add a comment to the existing issue instead of opening a new one.
+- Find out whether your idea fits with the scope and aims of the project. It's up to you to make a strong case to convince the project's developers of the merits of this feature. Keep in mind that we want features that will be useful to the majority of our users and not just a small subset. If you're just targeting a minority of users, consider writing an add-on/plugin library.
+
+
+### Contributing Code
+
+This guide provides the recommended route to contributing to RAFFLE:
+
+1. Fork the repository.
+2. Clone the forked repository to your local machine.
+3. Create a new branch for your changes.
+4. Make your changes and commit them.
+5. Push the changes to your forked repository.
+6. Open a pull request to the main repository.
+
+When submitting your contributions, please ensure the following:
+- Provide a clear and descriptive title for your pull request.
+- Include a detailed description of the changes made.
+- 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).
+- 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.
+
+
+### 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).
+
+
+
+## Contact
+If you have any questions or need further assistance, feel free to contact [Ned Taylor](mailto:n.t.taylor@exeter.ac.uk?subject=RAFFLE%20-%query) or [Steve Hepplestone](mailto:s.p.hepplestone@exeter.ac.uk?subject=RAFFLE%20-%query).
+
+## License
+This project is licensed under the [GPL-3.0 License](LICENSE).
+
+<!-- omit in toc -->
+## Attribution
+This guide is based on the **contributing-gen** and has been copied from the [graphstruc](https://github.com/nedtaylor/graphstruc) repository, with permission from the creator (Ned Taylor).
+[Make your own](https://github.com/bttger/contributing-gen)!

README.md

@@ -28,6 +28,9 @@ Tutorials and documentation are provided on the [docs](http://raffle-fortran.rea
 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.
 
+Refer to the [API Documentation section](#api-documentation) later in this document to see how to access the API-specific documentation.
+
+
 
 ## Requirements
 
@@ -47,21 +50,38 @@ Python-specific installation:
 - ASE (optional)
 
 The library bas been developed and tested using the following Fortran compilers:
+- gfortran -- gcc 11.4.0
 - gfortran -- gcc 13.2.0
 - gfortran -- gcc 14.1.0
+- gfortran -- gcc 14.2.0
 
 The library is known to not currently work with the intel Fortran compilers.
 
 ## Installation
 
-To install RAFFLE, the source must be obtained from the git repository. Use the following commands to get started:
+For the Python library, the easiest method of installation is to install it directly from pip:
+
+```
+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.
+To do so, the source must be obtained from the git repository.
+Use the following commands to get started:
 ```
  git clone https://github.com/ExeQuantCode/raffle.git
  cd raffle
 ```
 
-
-Depending on what language will be used in, installation will fary from this point.
+Depending on what language will be used in, installation will vary from this point.
 
 ### Python
 
@@ -150,36 +170,31 @@ Now follow the instructions for the [Python](#python) build methods.
 
 After the library has been installed, a set of example programs can be found in the `example` directory (note, the `test` directory is for unit tests to ensure each procedure in the library produces expected outputs after compilation, they are not really needed to be looked at by potential users).
 
-The `example/executable` example uses a shell script to run the Fortran installed application.
+The `example/fortran_exe` example uses a shell script to run the Fortran installed application.
 It uses a user-editable input file `param.in` in the same directory to change values of the RAFFLE generator and provided database.
 
-The `example/wrapper` directory contains a set of `run_*.py` files that show how RAFFLE can be called using Python to implement it into existing random structure search workflows.
+The `example/python_pkg` directory contains a set of subdirectories `MATERIAL_learn` that show how RAFFLE can be called using Python to implement it into existing structure search workflows.
 These examples are the recommended ones to run.
-To successfully run them, follow the above installation instructions for Python, then go to the `example/wrapper` directory and run one of the scripts.
-
-
-<!-- 
-Next, after the code is compiled, the way to run it is as follows:
-```
-<PATH TO RAFFLE DIRECTORY>/bin/raffle -f <PARAMETER_FILE>
-```
-
-An example parameter file is provided in the repository. This is `param.in`. filename_host is the host structure filename, found in the execution directory. stoichiometry is the number of each element to be added to the structure. elements is a list of the names of chemical elements. It must be the same size as stoichiometry and its size must match the value provided in the num_species tag (this'll be tidied up later).
-
-The code will search for a directory called "database/" and read any enclosing directories for POSCARs and OUTCARs (will be moving to vasprun.xml once the code works). The structure is obtained from the POSCAR, the energy is obtained from the OUTCAR. These structures are used to seed the gvectors (distribution functions). NOTE TO JOE: Ned has added a cutoff function to the 2-body exactly as found in the original Behler and Parrinello paper.
+To successfully run them, follow the above installation instructions for Python, then go to the `example/python_pkg` directory and run one of the scripts.
 
-For testing purposes, the code will output the 2-, 3-, and 4-body gvectors to files 2body.txt, 3body.txt, and 4body.txt, respectively, for plotting purposes. For the most part, they look all right right now. Lots more testing needs to be done to ensure they are stable.
 
-The code will then output any generated structures to increment1/strucXXX/POSCAR. Note, if you rerun, the code will likely break as it won't want to write over existing files.
+API documentation
+-----------------
 
-It seems that the void finder works. I don't think that scan or pseudo-random walk work at all (and neither should they as they look for the old directory space to calculated distribution function contributions, instead of using the new gvectors).
--->
+API documentation can be generated using FORD (Fortran Documenter).
+To do so, follow the installation guide on the [FORD website](https://forddocs.readthedocs.io/en/stable/) to ensure FORD is installed.
+Once FORD is installed, run the following command in the root directory of the git repository:
 
+```
+  ford ford.md
+```
 
 Contributing
 ------------
 
-If you have any questions, bug reports, or feature requests, please post then in [issues](https://github.com/ExeQuantCode/RAFFLE/issues).
+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).
 
 
 License