Big breaking API redesign

.github/PULL_REQUEST_TEMPLATE.md

@@ -11,4 +11,4 @@ Before a pull request can be merged, the following items must be checked:
 * [ ] Run [ruff](https://beta.ruff.rs/docs/rules/#pydocstyle-d) on your code.
 * [ ] Tests have been added for any new functionality or bug fixes.
 
-We highly recommended installing the pre-commit hooks running in CI locally to speedup the development process. Simply run `pip install pre-commit && pre-commit install` to install the hooks which will check your code before each commit.
+We highly recommended installing the `prek` hooks running in CI locally to speedup the development process. Simply run `pip install prek && prek install` to install the hooks which will check your code before each commit.

.github/release.yml

@@ -1,6 +1,6 @@
 changelog:
   exclude:
-    authors: [github-actions, pre-commit-ci]
+    authors: [github-actions]
   categories:
     - title: 💥 Breaking Changes
       labels: [breaking]
@@ -33,4 +33,4 @@ changelog:
     - title: 🧹 Linting
       labels: [linting]
     - title: 🤷‍♂️ Other Changes
-      labels: ["*"]
+      labels: ['*']

.github/workflows/docs.yml

@@ -24,7 +24,7 @@ jobs:
 
       - uses: actions/setup-python@v5
         with:
-          python-version: "3.11"
+          python-version: '3.12'
 
       - name: Set up uv
         uses: astral-sh/setup-uv@v6

.github/workflows/lint.yml

@@ -6,26 +6,12 @@ on:
   pull_request:
     branches: [main]
 
-permissions:
-  contents: read
-
-concurrency:
-  group: ${{ github.workflow }}-pr-${{ github.event.pull_request.number }}
-  cancel-in-progress: true
-
 jobs:
-  lint:
+  prek:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
-
-      - name: Set up Python
-        uses: actions/setup-python@v5
-        with:
-          python-version: "3.12"
-
-      - name: Install dependencies
-        run: pip install pre-commit
+      - name: Check out repo
+        uses: actions/checkout@v5
 
-      - name: Run pre-commit
-        run: pre-commit run --all-files --show-diff-on-failure
+      - name: Run prek
+        uses: j178/prek-action@v1

.github/workflows/test.yml

@@ -18,8 +18,8 @@ jobs:
       matrix:
         os: [ubuntu-latest, macos-14]
         version:
-          - { python: "3.11", resolution: highest }
-          - { python: "3.12", resolution: lowest-direct }
+          - { python: '3.12', resolution: highest }
+          - { python: '3.13', resolution: lowest-direct }
     runs-on: ${{ matrix.os }}
 
     steps:
@@ -64,32 +64,24 @@ jobs:
       matrix:
         os: [ubuntu-latest, macos-14]
         version:
-          - { python: "3.11", resolution: highest }
-          - { python: "3.12", resolution: lowest-direct }
+          - { python: '3.12', resolution: highest }
+          - { python: '3.13', resolution: lowest-direct }
         model:
-          - { name: fairchem, test_path: "tests/models/test_fairchem.py" }
-          - { name: graphpes, test_path: "tests/models/test_graphpes.py" }
-          - { name: mace, test_path: "tests/models/test_mace.py" }
-          - { name: mace, test_path: "tests/test_elastic.py" }
-          - { name: mace, test_path: "tests/test_optimizers_vs_ase.py" }
-          - { name: mattersim, test_path: "tests/models/test_mattersim.py" }
-          - { name: metatomic, test_path: "tests/models/test_metatomic.py" }
-          - { name: orb, test_path: "tests/models/test_orb.py" }
-          - { name: sevenn, test_path: "tests/models/test_sevennet.py" }
+          - { name: fairchem, test_path: tests/models/test_fairchem.py }
+          - { name: graphpes, test_path: tests/models/test_graphpes.py }
+          - { name: mace, test_path: tests/models/test_mace.py }
+          - { name: mace, test_path: tests/test_elastic.py }
+          - { name: mace, test_path: tests/test_optimizers_vs_ase.py }
+          - { name: mattersim, test_path: tests/models/test_mattersim.py }
+          - { name: metatomic, test_path: tests/models/test_metatomic.py }
+          - { name: orb, test_path: tests/models/test_orb.py }
+          - { name: sevenn, test_path: tests/models/test_sevennet.py }
     runs-on: ${{ matrix.os }}
 
     steps:
       - name: Check out repo
         uses: actions/checkout@v4
 
-      - name: Check out fairchem repository
-        if: ${{ matrix.model.name == 'fairchem' }}
-        uses: actions/checkout@v4
-        with:
-          repository: FAIR-Chem/fairchem
-          path: fairchem-repo
-          ref: fairchem_core-1.10.0
-
       - name: Set up Python
         uses: actions/setup-python@v5
         with:
@@ -98,33 +90,21 @@ jobs:
       - name: Set up uv
         uses: astral-sh/setup-uv@v6
 
-      - name: Install fairchem repository and dependencies
+      - name: Login to @janosh's HuggingFace account to access fairchem models
         if: ${{ matrix.model.name == 'fairchem' }}
         env:
           HF_TOKEN: ${{ secrets.HUGGING_FACE_TOKEN }}
         run: |
           uv pip install huggingface_hub --system
           if [ -n "$HF_TOKEN" ]; then
-            huggingface-cli login --token "$HF_TOKEN"
+            hf auth login --token "$HF_TOKEN"
           else
             echo "HF_TOKEN is not set. Skipping login."
           fi
-          if [ -f fairchem-repo/packages/requirements.txt ]; then
-            uv pip install -r fairchem-repo/packages/requirements.txt --system
-          fi
-          if [ -f fairchem-repo/packages/requirements-optional.txt ]; then
-            uv pip install -r fairchem-repo/packages/requirements-optional.txt --system
-          fi
-          uv pip install -e fairchem-repo/packages/fairchem-core[dev] --system
-          uv pip install -e .[test] --resolution=${{ matrix.version.resolution }} --system
-
-      - name: Install torch_sim with model dependencies
-        if: ${{ matrix.model.name != 'fairchem' }}
-        run: |
-          uv pip install -e .[test,${{ matrix.model.name }}] --resolution=${{ matrix.version.resolution }} --system
 
       - name: Run ${{ matrix.model.test_path }} tests
         run: |
+          uv pip install -e .[test,${{ matrix.model.name }}] --resolution=${{ matrix.version.resolution }} --system
           pytest --cov=torch_sim --cov-report=xml ${{ matrix.model.test_path }}
 
       - name: Upload coverage to Codecov
@@ -162,7 +142,7 @@ jobs:
       - name: Set up Python
         uses: actions/setup-python@v5
         with:
-          python-version: 3.11
+          python-version: '3.12'
 
       - name: Set up uv
         uses: astral-sh/setup-uv@v6

.pre-commit-config.yaml

@@ -9,7 +9,7 @@ repos:
   - repo: https://github.com/astral-sh/ruff-pre-commit
     rev: v0.11.13
     hooks:
-      - id: ruff
+      - id: ruff-check
         args: [--fix]
       - id: ruff-format
 
@@ -39,4 +39,4 @@ repos:
         # MD033: no inline HTML
         # MD041: first line in a file should be a top-level heading
         # MD034: bare URL used
-        args: [--disable, MD013, MD033, MD041, MD034, "--"]
+        args: [--disable, MD013, MD033, MD041, MD034, '--']

CHANGELOG.md

@@ -6,89 +6,89 @@
 
 ### 💥 Breaking Changes
 
-* Remove higher level model imports by @CompRhys in https://github.com/TorchSim/torch-sim/pull/179
+* Remove higher level model imports by @CompRhys in #179
 
 ### 🛠 Enhancements
 
-* Add per atom energies and stresses for batched LJ by @abhijeetgangan in https://github.com/TorchSim/torch-sim/pull/144
-* throw error if autobatcher type is wrong by @orionarcher in https://github.com/TorchSim/torch-sim/pull/167
+* Add per atom energies and stresses for batched LJ by @abhijeetgangan in #144
+* throw error if autobatcher type is wrong by @orionarcher in #167
 
 ### 🐛 Bug Fixes
 
-* Fix column->row cell vector mismatch in integrators by @CompRhys in https://github.com/TorchSim/torch-sim/pull/175
-* Mattersim fix tensors on wrong device (CPU->GPU) by @orionarcher in https://github.com/TorchSim/torch-sim/pull/154
-* fix `npt_langevin` by @jla-gardner in https://github.com/TorchSim/torch-sim/pull/153
-* Make sure to move data to CPU before calling vesin by @Luthaf in https://github.com/TorchSim/torch-sim/pull/156
-* Fix virial calculations in `optimizers` and `integrators` by @janosh in https://github.com/TorchSim/torch-sim/pull/163
-* Pad memory estimation by @orionarcher in https://github.com/TorchSim/torch-sim/pull/160
-* Refactor sevennet model by @YutackPark in https://github.com/TorchSim/torch-sim/pull/172
-* `io` optional dependencies in `pyproject.toml` by @curtischong in https://github.com/TorchSim/torch-sim/pull/185
+* Fix column->row cell vector mismatch in integrators by @CompRhys in #175
+* Mattersim fix tensors on wrong device (CPU->GPU) by @orionarcher in #154
+* fix `npt_langevin` by @jla-gardner in #153
+* Make sure to move data to CPU before calling vesin by @Luthaf in #156
+* Fix virial calculations in `optimizers` and `integrators` by @janosh in #163
+* Pad memory estimation by @orionarcher in #160
+* Refactor sevennet model by @YutackPark in #172
+* `io` optional dependencies in `pyproject.toml` by @curtischong in #185
 
 ### 📖 Documentation
 
-* (tiny) add graph-pes to README by @jla-gardner in https://github.com/TorchSim/torch-sim/pull/149
-* Better module fig by @janosh in https://github.com/TorchSim/torch-sim/pull/168
+* (tiny) add graph-pes to README by @jla-gardner in #149
+* Better module fig by @janosh in #168
 
 ### 🚀 Performance
 
-* More efficient Orb `state_to_atoms_graph` calculation by @AdeeshKolluru in https://github.com/TorchSim/torch-sim/pull/165
+* More efficient Orb `state_to_atoms_graph` calculation by @AdeeshKolluru in #165
 
 ### 🚧 CI
 
-* Refactor `test_math.py` and `test_transforms.py` by @janosh in https://github.com/TorchSim/torch-sim/pull/151
+* Refactor `test_math.py` and `test_transforms.py` by @janosh in #151
 
 ### 🏥 Package Health
 
-* Try out hatchling for build vs setuptools by @CompRhys in https://github.com/TorchSim/torch-sim/pull/177
+* Try out hatchling for build vs setuptools by @CompRhys in #177
 
 ### 🏷️ Type Hints
 
-* Add `torch_sim/typing.py` by @janosh in https://github.com/TorchSim/torch-sim/pull/157
+* Add `torch-sim/typing.py` by @janosh in #157
 
 ### 📦 Dependencies
 
-* Bump `mace-torch` to v0.3.12 by @janosh in https://github.com/TorchSim/torch-sim/pull/170
-* Update metatrain dependency by @Luthaf in https://github.com/TorchSim/torch-sim/pull/186
+* Bump `mace-torch` to v0.3.12 by @janosh in #170
+* Update metatrain dependency by @Luthaf in #186
 
 ## New Contributors
 
-* @Luthaf made their first contribution in https://github.com/TorchSim/torch-sim/pull/156
-* @YutackPark made their first contribution in https://github.com/TorchSim/torch-sim/pull/172
-* @curtischong made their first contribution in https://github.com/TorchSim/torch-sim/pull/185
+* @Luthaf made their first contribution in #156
+* @YutackPark made their first contribution in #172
+* @curtischong made their first contribution in #185
 
-**Full Changelog**: https://github.com/TorchSim/torch-sim/compare/v0.2.0...v0.2.1
+**Full Changelog**: https://github.com/torchsim/torch-sim/compare/v0.2.0...v0.2.1
 
 ## v0.2.0
 
 ### Bug Fixes 🐛
 
-* Fix integrate reporting kwarg to arg error, https://github.com/TorchSim/torch-sim/issues/113 (raised by @hn-yu)
-* Allow runners to take large initial batches, https://github.com/TorchSim/torch-sim/issues/128 (raised by @YutackPark)
-* Add Fairchem model support for PBC, https://github.com/TorchSim/torch-sim/issues/111 (raised by @ryanliu30)
+* Fix integrate reporting kwarg to arg error, #113 (raised by @hn-yu)
+* Allow runners to take large initial batches, #128 (raised by @YutackPark)
+* Add Fairchem model support for PBC, #111 (raised by @ryanliu30)
 
 ### Enhancements 🛠
 
-* **breaking** Rename `HotSwappingAutobatcher` to `InFlightAutobatcher` and `ChunkingAutoBatcher` to `BinningAutoBatcher`, https://github.com/TorchSim/torch-sim/pull/143 @orionarcher
-* Support for Orbv3, https://github.com/TorchSim/torch-sim/pull/140, @AdeeshKolluru
-* Support metatensor models, https://github.com/TorchSim/torch-sim/pull/141, @frostedoyter @Luthaf
-* Support for graph-pes models, https://github.com/TorchSim/torch-sim/pull/118 @jla-gardner
-* Support MatterSim and fix ASE cell convention issues, https://github.com/TorchSim/torch-sim/pull/112 @CompRhys
-* Implement positions only FIRE optimization, https://github.com/TorchSim/torch-sim/pull/139 @abhijeetgangan
-* Allow different temperatures in batches, https://github.com/TorchSim/torch-sim/pull/123 @orionarcher
-* FairChem model updates: PBC handling, test on OMat24 e-trained model, https://github.com/TorchSim/torch-sim/pull/126 @AdeeshKolluru
-* FairChem model from_data_list support, https://github.com/TorchSim/torch-sim/pull/138 @ryanliu30
-* New correlation function module, https://github.com/TorchSim/torch-sim/pull/115 @stefanbringuier
+* **breaking** Rename `HotSwappingAutobatcher` to `InFlightAutobatcher` and `ChunkingAutoBatcher` to `BinningAutoBatcher`, #143 @orionarcher
+* Support for Orbv3, #140, @AdeeshKolluru
+* Support metatensor models, #141, @frostedoyter @Luthaf
+* Support for graph-pes models, #118 @jla-gardner
+* Support MatterSim and fix ASE cell convention issues, #112 @CompRhys
+* Implement positions only FIRE optimization, #139 @abhijeetgangan
+* Allow different temperatures in batches, #123 @orionarcher
+* FairChem model updates: PBC handling, test on OMat24 e-trained model, #126 @AdeeshKolluru
+* FairChem model from_data_list support, #138 @ryanliu30
+* New correlation function module, #115 @stefanbringuier
 
 ### Documentation 📖
 
-* Improved model documentation, https://github.com/TorchSim/torch-sim/pull/121 @orionarcher
-* Plot of TorchSim module graph in docs, https://github.com/TorchSim/torch-sim/pull/132 @janosh
+* Improved model documentation, #121 @orionarcher
+* Plot of TorchSim module graph in docs, #132 @janosh
 
 ### House-Keeping 🧹
 
-* Only install HF for fairchem tests, https://github.com/TorchSim/torch-sim/pull/134 @CompRhys
-* Don't download MBD in CI, https://github.com/TorchSim/torch-sim/pull/135 @orionarcher
-* Tighten graph-pes test bounds, https://github.com/TorchSim/torch-sim/pull/143 @orionarcher
+* Only install HF for fairchem tests, #134 @CompRhys
+* Don't download MBD in CI, #135 @orionarcher
+* Tighten graph-pes test bounds, #143 @orionarcher
 
 ## v0.1.0
 

CONTRIBUTING.md

@@ -2,14 +2,6 @@
 
 TorchSim is an experimental library and we would appreciate any feedback from the community.
 
-## Contributor License Agreement (CLA)
-
-Before contributing, you'll need to sign our Contributor License Agreement (CLA). This is a one-time requirement that covers all Radical AI open source projects. The CLA allows you to maintain ownership of your contributions while granting Radical AI the necessary rights to use them.
-
-[Radical AI CLA](https://www.radical-ai.com/oss)
-
-Our CLA-bot will automatically verify your signature on pull requests. For questions about the CLA, contact [email protected].
-
 ## Code Reviews
 
 All submissions require review by project maintainers before merging:

LICENSE

@@ -1,5 +1,5 @@
 The MIT License (MIT)
-Copyright 2025 Radical AI
+Copyright 2025 Project TorchSim
 
 Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
 

README.md

@@ -1,9 +1,9 @@
 # TorchSim
 
-[![CI](https://github.com/TorchSim/torch-sim/actions/workflows/test.yml/badge.svg)](https://github.com/TorchSim/torch-sim/actions/workflows/test.yml)
-[![codecov](https://codecov.io/gh/radical-ai/torch-sim/branch/main/graph/badge.svg)](https://codecov.io/gh/radical-ai/torch-sim)
-[![This project supports Python 3.11+](https://img.shields.io/badge/Python-3.11+-blue.svg?logo=python&logoColor=white)](https://python.org/downloads)
-[![PyPI](https://img.shields.io/pypi/v/torch_sim_atomistic?logo=pypi&logoColor=white)](https://pypi.org/project/torch_sim_atomistic)
+[![CI](https://github.com/torchsim/torch-sim/actions/workflows/test.yml/badge.svg)](https://github.com/torchsim/torch-sim/actions/workflows/test.yml)
+[![codecov](https://codecov.io/gh/torchsim/torch-sim/branch/main/graph/badge.svg)](https://codecov.io/gh/torchsim/torch-sim)
+[![This project supports Python 3.12+](https://img.shields.io/badge/Python-3.12+-blue.svg?logo=python&logoColor=white)](https://python.org/downloads)
+[![PyPI](https://img.shields.io/pypi/v/torch-sim-atomistic?logo=pypi&logoColor=white)](https://pypi.org/project/torch-sim-atomistic)
 [![Zenodo](https://img.shields.io/badge/Zenodo-15127004-blue?logo=Zenodo&logoColor=white)][zenodo]
 
 [zenodo]: https://zenodo.org/records/15127004
@@ -81,27 +81,14 @@ To then relax those structures with FIRE is just a few more lines.
 relaxed_state = ts.optimize(
     system=final_state,
     model=mace_model,
-    optimizer=ts.frechet_cell_fire,
+    optimizer=ts.OptimFlavor.fire,
+    cell_filter=ts.CellFilter.frechet,
     autobatcher=True,
 )
 
 print(relaxed_state.energy)
 ```
 
-## Speedup
-
-TorchSim achieves up to 100x speedup compared to ASE with popular MLIPs.
-
-<img src="/docs/_static/speedup_plot.svg" alt="Speedup comparison" width="100%">
-
-This figure compares the time per atom of ASE and `torch_sim`. Time per atom is defined
-as the number of atoms / total time. While ASE can only run a single system of `n_atoms`
-(on the $x$ axis), `torch_sim` can run as many systems as will fit in memory. On an H100 80 GB card,
-the max atoms that could fit in memory was ~8,000 for [EGIP](https://github.com/FAIR-Chem/fairchem),
-~10,000 for [MACE-MPA-0](https://github.com/ACEsuit/mace), ~22,000 for [Mattersim V1 1M](https://github.com/microsoft/mattersim),
-~2,500 for [SevenNet](https://github.com/MDIL-SNU/SevenNet), and ~9000 for [PET-MAD](https://github.com/lab-cosmo/pet-mad).
-This metric describes model performance by capturing speed and memory usage simultaneously.
-
 ## Installation
 
 ### PyPI Installation
@@ -113,7 +100,7 @@ pip install torch-sim-atomistic
 ### Installing from source
 
 ```sh
-git clone https://github.com/TorchSim/torch-sim
+git clone https://github.com/torchsim/torch-sim
 cd torch-sim
 pip install .
 ```
@@ -126,11 +113,11 @@ To understand how TorchSim works, start with the [comprehensive tutorials](https
 
 TorchSim's package structure is summarized in the [API reference](https://torchsim.github.io/torch-sim/reference/index.html) documentation and drawn as a treemap below.
 
-![TorchSim package treemap](https://github.com/user-attachments/assets/1ccb3a15-233d-4bc0-b11c-35a676a2bcf3)
+![TorchSim package treemap](https://github.com/user-attachments/assets/56f894ad-b995-4108-a6de-a48714276d89)
 
 ## License
 
-TorchSim is released under an [MIT license](LICENSE).
+TorchSim is released under an [MIT license](license).
 
 ## Citation