From 29285259719a595a736abdbfd6f708985d6bd8bc Mon Sep 17 00:00:00 2001 From: Jonah Marks Date: Sun, 5 Apr 2026 13:26:09 +0200 Subject: [PATCH 1/4] add initial changelog.md and contributing.md --- CHANGELOG.md | 32 +++++++++++++++++ CONTRIBUTING.md | 93 +++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 10 ++++-- 3 files changed, 133 insertions(+), 2 deletions(-) create mode 100644 CHANGELOG.md create mode 100644 CONTRIBUTING.md diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..d2daf84 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,32 @@ +# Changelog + +All notable changes to this project will be documented in this file. + +The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), +and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). + +## [Unreleased] + +## [1.0.1] - 2025 + +### Fixed +- Minor bug fixes and stability improvements + +## [1.0.0] - 2025 + +### Added +- Initial public release of ML-FSM +- Internal coordinates interpolation for the Freezing String Method +- Support for ML-based potentials via ASE calculator interface +- Support for AIMNet2, MACEOFF23, FAIR UMA, TensorNet, xTB, and QChem backends +- Google Colab example notebook for Diels-Alder reaction with AIMNet2 +- Comprehensive example script (`examples/fsm_example.py`) covering most FSM functionality +- Custom ASE calculator wrapper templates for NNPs without native ASE interfaces +- Full test suite with pytest +- Type annotations and mypy support +- Sphinx documentation hosted on Read the Docs +- Pixi-based development environment + +[Unreleased]: https://github.com/thegomeslab/ML-FSM/compare/v1.0.1...HEAD +[1.0.1]: https://github.com/thegomeslab/ML-FSM/compare/v1.0.0...v1.0.1 +[1.0.0]: https://github.com/thegomeslab/ML-FSM/releases/tag/v1.0.0 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..1a5a6c1 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,93 @@ +# Contributing to ML-FSM + +Thank you for your interest in contributing to ML-FSM! This document outlines the process for contributing and how to set up your development environment. + +## Before You Open a Pull Request + +**Please open an issue or reach out before starting significant work.** + +If you have a bug report, feature request, or want to propose a change, start by [opening an issue](https://github.com/thegomeslab/ML-FSM/issues) on GitHub. For questions or to discuss a contribution before diving in, you can also contact the maintainer directly: + +**Joe Gomes** — joe-gomes@uiowa.edu + +This helps avoid duplicated effort and ensures your contribution aligns with the project's direction before you invest time in it. + +## Development Setup + +ML-FSM uses [Pixi](https://pixi.sh) to manage the development environment. Pixi handles dependencies, virtual environments, and task running — no manual conda/pip setup needed. + +### 1. Install Pixi + +```bash +curl -fsSL https://pixi.sh/install.sh | bash +``` + +Or see the [Pixi installation docs](https://pixi.sh/latest/#installation) for other options. + +### 2. Clone the repository + +```bash +git clone https://github.com/thegomeslab/ML-FSM.git +cd ML-FSM +``` + +### 3. Set up the dev environment + +```bash +pixi install -e dev +``` + +This creates an isolated environment with all development dependencies (pytest, ruff, mypy, sphinx, pre-commit, etc.) — no additional steps required. + +### 4. Install pre-commit hooks + +```bash +pixi run -e dev pre-commit install +``` + +This registers the hooks so they run automatically on every commit. + +## Available Commands + +All development tasks are run via `pixi run` from the repository root. Make sure to use the `dev` environment (`-e dev`) or set it as your active environment. + +| Command | Description | +|---|---| +| `pixi run fmt` | Format code with ruff | +| `pixi run lint` | Lint and auto-fix code with ruff | +| `pixi run types` | Run static type checking with mypy | +| `pixi run test` | Run the test suite with pytest | +| `pixi run coverage` | Run tests with coverage report (generates `coverage.xml`) | +| `pixi run docs` | Build the Sphinx documentation locally | +| `pixi run all` | Run fmt, lint, types, test, and docs in sequence | + +For example: + +```bash +pixi run test # run tests +pixi run fmt && pixi run lint # format then lint +pixi run all # run everything +``` + +## Pre-commit Checks + +The pre-commit hooks run ruff format, ruff check, mypy, and pytest on every commit and push. Before opening a pull request, run the full pre-commit suite manually to make sure everything passes: + +```bash +pixi run -e dev pre-commit run --all-files +``` + +Pull requests that fail any of these checks will not be merged. + +## Contribution Workflow + +1. [Open an issue](https://github.com/thegomeslab/ML-FSM/issues) or contact Joe to discuss your proposed change. +2. Fork the repository and create a feature branch from `main`. +3. Make your changes, adding tests for any new behavior. +4. Run `pixi run all` to confirm everything passes. +5. Run `pre-commit run --all-files` as a final check. +6. Open a pull request against `main`, referencing the relevant issue. + +## Code Style + +This project uses [ruff](https://github.com/astral-sh/ruff) for formatting and linting, and [mypy](https://mypy-lang.org/) for static type checking. Docstrings follow the NumPy convention. The pre-commit hooks enforce these automatically — just run `pixi run fmt` and `pixi run lint` before committing. diff --git a/README.md b/README.md index 09a58b8..4baec89 100644 --- a/README.md +++ b/README.md @@ -7,8 +7,8 @@ [![GitHub Workflow Status](https://img.shields.io/github/actions/workflow/status/thegomeslab/ML-FSM/test.yml?branch=main&logo=github-actions)](https://github.com/jonmarks12/ML-FSM/actions/) [![Documentation Status](https://readthedocs.org/projects/ml-fsm/badge/?version=latest)](https://ml-fsm.readthedocs.io/en/latest/?badge=latest) [![codecov](https://codecov.io/gh/thegomeslab/ML-FSM/branch/main/graph/badge.svg)](https://codecov.io/gh/thegomeslab/ML-FSM) - - +[![Contributing](https://img.shields.io/badge/contributions-welcome-brightgreen)](./CONTRIBUTING.md) +[![Changelog](https://img.shields.io/badge/changelog-available-blue)](./CHANGELOG.md) [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/thegomeslab/ML-FSM/blob/dev/examples/FSM_Colab_AIMNet2.ipynb) @@ -66,6 +66,12 @@ For projects using the FSM with ML-based potentials please cite: >Marks, J., & Gomes, J. (2025). Efficient Transition State Searches by Freezing String Method with Graph Neural Network Potentials. http://arxiv.org/abs/2501.06159 +## Contributing + +Contributions are welcome! Please read the [Contributing Guide](./CONTRIBUTING.md) before opening a pull request. We ask that you open an issue or reach out to the maintainer first to discuss proposed changes. + +See the [Changelog](./CHANGELOG.md) for a history of notable changes. + ## License This project is licensed under the MIT License. See the [LICENSE](./LICENSE) file for details. From df629dbbd4e032adcaf28bed4424bec7cdc98aed Mon Sep 17 00:00:00 2001 From: Jonah Marks <56830107+jonmarks12@users.noreply.github.com> Date: Sun, 5 Apr 2026 13:47:17 +0200 Subject: [PATCH 2/4] Update CONTRIBUTING.md with maintainer information Added section for project maintainers and reorganized contributing guidelines. --- CONTRIBUTING.md | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 1a5a6c1..a89a439 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -2,14 +2,20 @@ Thank you for your interest in contributing to ML-FSM! This document outlines the process for contributing and how to set up your development environment. -## Before You Open a Pull Request +## Project Maintainers -**Please open an issue or reach out before starting significant work.** +ML-FSM is primarily developed and maintained at the [Gomes Lab](https://github.com/thegomeslab) at the University of Iowa. The package was co-created by Jonah Marks (now at AstraZeneca), who remains a maintainer, with additional contributions from Jonathon Vandezande. -If you have a bug report, feature request, or want to propose a change, start by [opening an issue](https://github.com/thegomeslab/ML-FSM/issues) on GitHub. For questions or to discuss a contribution before diving in, you can also contact the maintainer directly: +For questions, bug reports, or to discuss potential contributions, please contact: **Joe Gomes** — joe-gomes@uiowa.edu +## Before You Open a Pull Request + +**Please open an issue or reach out before starting significant work.** + +If you have a bug report, feature request, or want to propose a change, start by [opening an issue](https://github.com/thegomeslab/ML-FSM/issues) on GitHub. For questions or to discuss a contribution before diving in, you can also contact Joe directly at the address above. + This helps avoid duplicated effort and ensures your contribution aligns with the project's direction before you invest time in it. ## Development Setup From b3d1dc95610fc33cab9039dae519e0438ee254f6 Mon Sep 17 00:00:00 2001 From: Jonah Marks <56830107+jonmarks12@users.noreply.github.com> Date: Sun, 5 Apr 2026 16:08:31 +0200 Subject: [PATCH 3/4] Update Changelog.md --- CHANGELOG.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index d2daf84..6b62c39 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,8 +7,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] -## [1.0.1] - 2025 - +## [1.0.1] - 2026 +### Added +- Fixed atoms functionality +- Ability to directly input stepsize ### Fixed - Minor bug fixes and stability improvements From 956669cddfdb77eaf453b8b41a8dfd3d109055d0 Mon Sep 17 00:00:00 2001 From: Jonah Marks <56830107+jonmarks12@users.noreply.github.com> Date: Sun, 5 Apr 2026 16:13:06 +0200 Subject: [PATCH 4/4] Update CHANGELOG for version 1.0.1 changes --- CHANGELOG.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 6b62c39..5f0cee2 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -11,6 +11,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Added - Fixed atoms functionality - Ability to directly input stepsize +### Changed +- Moved ML-FSM repo from @jonmarks12 to @thegomeslab +- Large documentation update, changed theme to furo, updated docstrings, added examples, various other improvements ### Fixed - Minor bug fixes and stability improvements