ExeQuantCode · nedtaylor · Dec 18, 2024 · Oct 31, 2024 · Oct 31, 2024 · Oct 31, 2024
diff --git a/.github/ISSUE_TEMPLATE/bug_report.yaml b/.github/ISSUE_TEMPLATE/bug_report.yaml
@@ -0,0 +1,64 @@
+name: Bug Report
+description: Something is not working
+title: "[BUG]"
+labels: [bug]
+body:
+  - type: textarea
+    id: description
+    attributes:
+      label: Description
+      placeholder: |
+        A clear and concise description of what the bug is and what the expected behaviour is.
+    validations:
+      required: true
+  - type: textarea
+    id: reproduction
+    attributes:
+      label: Reproduction steps
+      description: "How do you trigger this bug? If possible, please provide a minimal reproducible example."
+      placeholder: |
+        Does the library compile? Is there an issue with a unit test or example? Or is the bug encountered when calling the library? If possible, provide a step-by-step guide:
+        1.
+        2.
+        3.
+    validations:
+      required: true
+  - type: input
+    id: version
+    attributes:
+      label: Version number
+      description: "What was the latest version (or branch) of RAFFLE is the bug reproducible in?"
+      placeholder: 1.0.0
+    validations:
+      required: true
+  - type: input
+    id: compiler
+    attributes:
+      label: Fortran compiler
+      description: "What Fortran compiler (and version) was used?"
+      placeholder: gfortran version 14.0
+    validations:
+      required: true
+  - type: input
+    id: platform
+    attributes:
+      label: Platform and Architecture
+      description: "What architecture and operating system was the bug encountered on?"
+      placeholder: macOS/ARM 10.14
+    validations:
+      required: true
+  - type: checkboxes
+    id: build
+    attributes:
+      label: Build method
+      description: "What build methods was this issue encountered with?"
+      options:
+        - label: fpm
+        - label: cmake
+  - type: textarea
+    id: additional
+    attributes:
+      label: Additional information
+      placeholder: Any further relevant context, i.e. screenshots, links to other issues, version number of build method.
+    validations:
+      required: false
diff --git a/.github/ISSUE_TEMPLATE/feature_request.yaml b/.github/ISSUE_TEMPLATE/feature_request.yaml
@@ -0,0 +1,29 @@
+name: Feature Proposal
+description: Suggest new functionality for RAFFLE
+title: "[PROPOSAL]"
+labels: [enhancement]
+body:
+  - type: textarea
+    id: reasoning
+    attributes:
+      label: Reasoning
+      placeholder: |
+        Provide clear reasoning why the proposed functionality should be added to the RAFFLE library.
+    validations:
+      required: true
+  - type: textarea
+    id: prior_art
+    attributes:
+      label: Prior Art
+      placeholder: |
+        Provide examples of where this has been implemented for machine learning before to help justify its presence in this library.
+    validations:
+      required: false
+  - type: textarea
+    id: additional
+    attributes:
+      label: Additional information
+      placeholder: |
+        Add any other context or screenshots about the feature request here.
+    validations:
+      required: false
diff --git a/.gitignore b/.gitignore
@@ -15,7 +15,7 @@ iteration*
 doc/html
 docs/html
 settings.json
-example/example_files/database*
+example/**/database*.xyz
 **/POSCAR*
 iteration/
 *.traj
@@ -31,4 +31,6 @@ fort.*
 *.agr
 *.pdf
 *.eps
-*.pyc
+*.pyc
+*.xyz
+.coverage
diff --git a/.readthedocs.yaml b/.readthedocs.yaml
@@ -17,7 +17,7 @@ build:
 
 # Build documentation in the "docs/" directory with Sphinx
 sphinx:
-  configuration: docs/conf.py
+  configuration: docs/source/conf.py
 
 # Optionally build your docs in additional formats such as PDF and ePub
 # formats:
@@ -27,6 +27,6 @@ sphinx:
 # Optional but recommended, declare the Python requirements required
 # to build your documentation
 # See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
-# python:
-#    install:
-#    - requirements: docs/requirements.txt
+python:
+   install:
+   - requirements: docs/requirements.txt
diff --git a/CITATION.cff b/CITATION.cff
@@ -0,0 +1,36 @@
+# This CITATION.cff file was generated with cffinit.
+# Visit https://bit.ly/cffinit to generate yours today!
+
+cff-version: 1.2.0
+title: >-
+  RAFFLE: pseudoRandom Approach For Finding Local Energy
+  minima
+message: >-
+  If you use this software, please cite it using the
+  metadata from this file and the following paper:
+  https://link.aps.org/doi/10.1103/PhysRevLett.132.066201
+type: software
+authors:
+  - given-names: Ned Thaddeus
+    family-names: Taylor
+    orcid: 'https://orcid.org/0000-0002-9134-9712'
+    affiliation: University of Exeter
+  - given-names: Joe
+    family-names: Pitfield
+    orcid: 'https://orcid.org/0000-0002-9758-5230'
+    affiliation: Aarhus Universitet
+  - given-names: Steven Paul
+    family-names: Hepplestone
+    orcid: 'https://orcid.org/0000-0002-2528-1270'
+    affiliation: University of Exeter
+repository-code: 'https://github.com/ExeQuantCode/RAFFLE'
+keywords:
+  - materials science
+  - interfaces
+  - material interfaces
+  - structure prediction
+  - random structure search
+license: GPL-3.0
+commit: 4cdf115d5d43d6f97037f6cb15c036dc9615eacb
+version: 0.5.0
+date-released: '2024-12-18'
diff --git a/CMakeLists.txt b/CMakeLists.txt
@@ -72,6 +72,7 @@ set(LIB_FILES
 	mod_io_utils.F90
 	mod_constants.f90
 	mod_misc.f90
+    mod_tools_infile.f90
 	mod_misc_maths.f90
 	mod_misc_linalg.f90
 	mod_dist_calcs.f90

diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md
@@ -0,0 +1,70 @@
+# Code of Conduct - RAFFLE
+
+## Our Pledge
+
+In the interest of fostering an open and welcoming environment, we as
+contributors and maintainers pledge to make participation in our project and
+our community a harassment-free experience for everyone, regardless of age, body
+size, disability, ethnicity, sex characteristics, gender identity and expression,
+level of experience, education, socio-economic status, nationality, personal
+appearance, race, religion, or sexual identity and orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologising to those affected by our mistakes,
+and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the
+overall community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualised language or imagery, and sexual attention or
+advances
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email
+address, without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+professional setting
+
+## Our Responsibilities
+
+Project maintainers are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any instances of unacceptable behavior.
+
+Project maintainers have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, or to ban
+temporarily or permanently any contributor for other behaviors that they deem
+inappropriate, threatening, offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official e-mail address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at .
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant](https://contributor-covenant.org/), version
+[1.4](https://www.contributor-covenant.org/version/1/4/code-of-conduct/code_of_conduct.md) and
+[2.0](https://www.contributor-covenant.org/version/2/0/code_of_conduct/code_of_conduct.md),
+and was generated by [contributing-gen](https://github.com/bttger/contributing-gen).
diff --git a/README.md b/README.md
@@ -1,25 +1,34 @@
 <p align="center">
-<img src="docs/RAFFLE_logo_no_background.png" width="250"/>
+<img src="docs/source/RAFFLE_logo_no_background.png" width="250"/>
 </p>
 
-[![MIT 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/nedtaylor/RAFFLE?sort=semver)](https://github.com/nedtaylor/RAFFLE/releases "View on GitHub")
+[![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)
+[![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")
 [![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")
-[![Coverage](https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/nedtaylor/48f14ebb5636b54d3813e4b4494903eb/raw/raffle_coverage_main.json)](https://nedtaylor.github.io/RAFFLE/ "View coverage report")
+[![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")
 
 
 # RAFFLE
 
 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 (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 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.
 
+## Documentation
+
+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.
+
+
 ## Requirements
 
 - Fortran compiler supporting Fortran 2018 standard or later
@@ -47,7 +56,7 @@ The library is known to not currently work with the intel Fortran compilers.
 
 To install RAFFLE, the source must be obtained from the git repository. Use the following commands to get started:
 ```
- git clone https://github.com/nedtaylor/raffle.git
+ git clone https://github.com/ExeQuantCode/raffle.git
  cd raffle
 ```
 
@@ -167,6 +176,22 @@ It seems that the void finder works. I don't think that scan or pseudo-random wa
 -->
 
 
+Contributing
+------------
+
+If you have any questions, bug reports, or feature requests, please post then in [issues](https://github.com/ExeQuantCode/RAFFLE/issues).
+
+
+License
+-------
+This work is licensed under a [GPL v3 license]([https://opensource.org/license/mit/](https://www.gnu.org/licenses/gpl-3.0.en.html)).
+
+Code Coverage
+-------------
+
+Automated reporting on unit test code coverage in the README is achieved through utilising the [cmake-modules](https://github.com/rpavlik/cmake-modules) and [dynamic-badges-action](https://github.com/Schneegans/dynamic-badges-action?tab=readme-ov-file) projects.
+
+
 ## References
 
 If you use this code, please cite our papers:

diff --git a/docs/Makefile b/docs/Makefile
@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= python -m sphinx
+SOURCEDIR     = source
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
diff --git a/docs/make.bat b/docs/make.bat
@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=source
+set BUILDDIR=build
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.https://www.sphinx-doc.org/
+	exit /b 1
+)
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd
diff --git a/docs/requirements.txt b/docs/requirements.txt
@@ -0,0 +1,2 @@
+sphinx==7.1.2
+sphinx-rtd-theme==1.3.0rc1
diff --git a/docs/RAFFLE_logo.pdf → docs/source/RAFFLE_logo.pdf b/docs/RAFFLE_logo.pdf → docs/source/RAFFLE_logo.pdf
diff --git a/docs/RAFFLE_logo_no_background.png → docs/source/RAFFLE_logo_no_background.png b/docs/RAFFLE_logo_no_background.png → docs/source/RAFFLE_logo_no_background.png