qcopt 0.1.0__tar.gz

qcopt-0.1.0/.github/workflows/ci.yaml

@@ -0,0 +1,23 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: uv sync --all-groups --all-extras
+      - run: uv run ruff check .
+      - run: uv run ruff format --check .
+      - run: uv run mypy
+      - run: uv run pytest

qcopt-0.1.0/.github/workflows/publish-to-pypi.yaml

@@ -0,0 +1,53 @@
+name: Release
+
+# The file name must stay publish-to-pypi.yaml: PyPI's trusted publisher for this
+# project is registered against it.
+# Pushing a version tag (e.g. 0.16.0) on main publishes to PyPI and creates the
+# GitHub release. Publishing waits for approval on the protected `pypi` environment.
+on:
+  push:
+    tags: ["*"]
+
+jobs:
+  publish:
+    name: Build and publish to PyPI
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/qcopt/
+    permissions:
+      contents: read
+      id-token: write # trusted publishing
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v7
+      - name: Tag must match the package version
+        run: |
+          version="$(sed -n 's/^version *= *"\(.*\)"/\1/p' pyproject.toml | head -n1)"
+          if [ "$version" != "$GITHUB_REF_NAME" ]; then
+            echo "::error::Tag $GITHUB_REF_NAME does not match pyproject version $version."
+            exit 1
+          fi
+      - name: Build
+        run: uv build
+      - uses: pypa/gh-action-pypi-publish@release/v1
+
+  github-release:
+    name: Create GitHub release
+    needs: publish
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v7
+      - name: Extract release notes from CHANGELOG.md
+        run: |
+          awk -v v="$GITHUB_REF_NAME" '
+            $0 ~ "^## \\[" v "\\]" {f=1; next}
+            f && /^## \[/ {exit}
+            f {print}
+          ' CHANGELOG.md > RELEASE_NOTES.md
+      - name: Create release
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: gh release create "$GITHUB_REF_NAME" --title "$GITHUB_REF_NAME" --notes-file RELEASE_NOTES.md --verify-tag

qcopt-0.1.0/.gitignore

@@ -0,0 +1,175 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/#use-with-ide
+.pdm.toml
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+# Ignore all .xyz files
+*.xyz
+
+# Allow .xyz files in tests/data and its subdirectories
+!tests/data/**/*.xyz
+
+# rdkit artifacts
+nul
+run.out
+
+# Convention for testing scripts
+fake*.py
+# benchmark run logs
+benchmarks/*.out

qcopt-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,62 @@
+# Every hook runs the project's own locked tools through `uv run`, so local hooks,
+# CI, and your editor use identical versions. Install once with
+# `uv run pre-commit install`; see CONTRIBUTING.md.
+default_install_hook_types: [pre-commit]
+default_stages: [pre-commit]
+repos:
+  - repo: local
+    hooks:
+      - id: check-yaml
+        name: check yaml
+        entry: uv run check-yaml
+        language: system
+        types: [yaml]
+        exclude: ^mkdocs\.yml$
+      - id: check-toml
+        name: check toml
+        entry: uv run check-toml
+        language: system
+        types: [toml]
+      - id: check-merge-conflict
+        name: check for merge conflicts
+        entry: uv run check-merge-conflict
+        language: system
+        types: [text]
+      - id: check-added-large-files
+        name: check for added large files
+        entry: uv run check-added-large-files --maxkb=250
+        language: system
+        exclude: ^(tests/data/|docs/)
+      - id: detect-secrets
+        name: detect secrets
+        entry: uv run detect-secrets-hook
+        language: system
+        types: [text]
+        exclude: (\.lock|\.ipynb)$|^tests/data/
+      - id: uv-lock
+        name: uv.lock is up to date
+        entry: uv lock --check
+        language: system
+        files: ^(pyproject\.toml|uv\.lock)$
+        pass_filenames: false
+      - id: ruff-check
+        name: ruff check
+        entry: uv run ruff check --fix --exit-non-zero-on-fix
+        language: system
+        types_or: [python, pyi]
+      - id: ruff-format
+        name: ruff format
+        entry: uv run ruff format
+        language: system
+        types_or: [python, pyi]
+      - id: typos
+        name: typos
+        entry: uv run typos --force-exclude
+        language: system
+        types: [text]
+      - id: mypy
+        name: mypy
+        entry: uv run mypy
+        language: system
+        types_or: [python, pyi]
+        pass_filenames: false

qcopt-0.1.0/.python-version

@@ -0,0 +1 @@
+3.12

qcopt-0.1.0/AGENTS.md

@@ -0,0 +1,37 @@
+# AGENTS.md
+
+Instructions for AI coding agents (and a quick reference for people) working in `qcopt`.
+
+## This package
+
+`qcopt` optimizes structures: minima, transition states, and IRCs. It is AFH's own optimizer, meant to replace Sella, geomeTRIC, and ASE's optimizers in our stack. Inputs are qcdata `ProgramInput`s with `program="qcopt"` and gradient (and optionally Hessian) subprograms; outputs are qcdata `ProgramOutput`s holding `OptimizationData` or `PathData`.
+
+- **Algorithms are generators** (`qcopt/algorithms.py`): they yield the geometries where they need gradients or Hessians and receive the answers. `qcopt.driver.drive` runs many of them in lockstep and hands each round's requests to an evaluator in one call. Never call a program from inside an algorithm.
+- **Evaluators** (`qcopt/evaluators.py`) compute requests: axtb in-process (our own codes come first: no subprocess, wavefunction reuse, threads), qccompute for every other program, or a Python function.
+- **Atomic units everywhere** (bohr, Hartree); qcref constants as `from qcref import constants as c` and `c.NAME`, never copied into module variables.
+- **Fail loudly**: unknown keywords are errors (pydantic models in `qcopt/keywords.py`). A run that fails or does not converge returns `success=False` with its frames kept.
+- **Our own implementation.** Sella (LGPL-3.0), geomeTRIC (BSD-3 with a non-AI clause), OptKing (BSD-3) and pysisyphus may be read as guides; implement from the papers and cite them in docstrings. Never copy their code.
+
+## The qc* suite
+
+Dependencies point one way: qcref -> qcdata -> {qcinf, qccodec} -> qccompute -> qcopt. qccompute is optional (only the `ComputeEvaluator` needs it).
+
+## Commands
+
+```sh
+uv sync --all-groups                  # install
+uv pip install <axtb wheel>           # axtb is not on PyPI yet; its tests skip without it
+uv run pytest                         # tests
+uv run ruff check --fix . && uv run ruff format .
+uv run mypy
+```
+
+Benchmarks against Sella and geomeTRIC live in `benchmarks/` with their own venv (see `benchmarks/README.md`). Benchmark data and results stay outside the repo.
+
+## Code conventions
+
+- Type annotations on all functions; Google-style docstrings with units.
+- Performance matters: with axtb a gradient can take under a millisecond, so the optimizer's own time per step is part of the result. Profile before optimizing; keep per-step work vectorized NumPy.
+- New behavior has tests; bug fixes have a test that failed before the fix.
+- User-visible changes go under `## [unreleased]` in CHANGELOG.md.
+- Do not commit, push, tag, or release unless asked to.

qcopt-0.1.0/CHANGELOG.md

@@ -0,0 +1,43 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project uses
+[Semantic Versioning](https://semver.org/).
+
+## [unreleased]
+
+## [0.1.0] - 2026-11-06
+
+### Added
+
+- First version: minimizations (RS-RFO), transition-state searches (RS-P-RFO with
+  TS-BFGS updates) and IRCs (local quadratic approximation, both branches together) in
+  Cartesian coordinates, as `ProgramInput(program="qcopt")` -> `ProgramOutput` with
+  `OptimizationData` or `PathData`.
+- Lockstep runs of many calculations with one evaluator call per round (`qcopt.run(list)`).
+- Evaluators: axtb in-process, qccompute (any program with a codec), Python functions;
+  finite-difference Hessians from gradients computed together.
+- Lindh model Hessian; BFGS, SR1, PSB, Bofill and TS-BFGS updates; harmonic frequency
+  check of the final structure.
+- Internal coordinates, the default: TRIC (per-fragment translation and rotation, with
+  analytic rotation derivatives) and delocalized internals; rebuilt when they degrade,
+  Cartesians when they cannot describe the structure.
+- Constraints on distances, angles and dihedrals; saddle escape for minimizations
+  (`escape_saddles`).
+- A qccodec codec, so `qccompute.compute(ProgramInput(program="qcopt", ...))` works.
+- IRCs by Gonzalez-Schlegel steps on the quadratic model (default, step 0.3) or the
+  local quadratic approximation; overshoots retried at half the step; an exact Hessian
+  decides when a small-gradient branch shows negative curvature; `minimize_ends`.
+- Internal-coordinate values and B matrices are cached per geometry, so a TRIC step
+  computes each once (8.0 -> 4.6 ms per step on a 16-atom minimization).
+- Hessians from another method than the gradients (`hessian=` a different program or
+  model, such as GFN2-xTB Hessians for g-xTB): every Hessian request also gets the
+  gradient program's energy and gradient (reused when just computed), and frames keep
+  only the gradient program's results. On 100 Reaction-QM transition states at g-xTB,
+  GFN2 starting Hessians halved the total time.
+- The starting-Hessian keyword is `initial_hessian`; `hessian=` in `minimize`,
+  `find_ts` and `irc` names the Hessian program only, and other values are errors
+  (a string was ignored).
+
+[unreleased]: https://github.com/atomsforhumanity/qcopt/compare/0.1.0...HEAD
+[0.1.0]: https://github.com/atomsforhumanity/qcopt/releases/tag/0.1.0

qcopt-0.1.0/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

qcopt-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Colton Hicks
+
+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:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

qcopt-0.1.0/PKG-INFO

@@ -0,0 +1,122 @@
+Metadata-Version: 2.5
+Name: qcopt
+Version: 0.1.0
+Summary: Geometry optimization, transition-state searches, and IRCs that return qcdata results.
+Project-URL: Homepage, https://github.com/atomsforhumanity/qcopt
+Project-URL: Source, https://github.com/atomsforhumanity/qcopt
+Project-URL: Changelog, https://github.com/atomsforhumanity/qcopt/blob/main/CHANGELOG.md
+Project-URL: Bug Tracker, https://github.com/atomsforhumanity/qcopt/issues
+Author-email: Colton Hicks <github@coltonhicks.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Natural Language :: English
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: Chemistry
+Requires-Python: >=3.11
+Requires-Dist: numpy>=1.24.0
+Requires-Dist: pydantic>=2.0
+Requires-Dist: qcdata>=0.23.1
+Requires-Dist: qcref>=0.5.1
+Provides-Extra: qccompute
+Requires-Dist: qccodec>=0.21.0; extra == 'qccompute'
+Requires-Dist: qccompute>=0.22.0; extra == 'qccompute'
+Description-Content-Type: text/markdown
+
+# qcopt
+
+Minimizations, transition-state searches, and IRCs for the qc* stack. Inputs and outputs
+are [qcdata](https://github.com/atomsforhumanity/qcdata) objects; gradients and Hessians
+come from [axtb](https://github.com/atomsforhumanity/axtb) in-process or from any program
+qccompute runs.
+
+```python
+import qcopt
+from qcdata import Structure
+
+# accuracy 0.01: at axtb's default SCF accuracy, g-xTB gradients carry ~1e-5 Eh/bohr
+# of noise, the size of qcopt's convergence threshold (12% more time per gradient).
+gxtb = {"program": "axtb", "model": {"method": "gxtb-v2.0.1"}, "keywords": {"accuracy": 0.01}}
+guess = Structure.open("ts_guess.xyz")
+
+ts = qcopt.find_ts(guess, gxtb, hessian=True, frequencies=True)  # ProgramOutput
+ts.results.extras["n_imaginary"]                                   # 1
+path = qcopt.irc(ts.results.final_structure, gxtb, hessian=True)   # PathData
+```
+
+`hessian` names the program computing Hessians: `True` for the gradient program, or another
+one, often a cheaper method. Frames keep the gradient program's energies and gradients:
+
+```python
+gfn2 = {"program": "axtb", "model": {"method": "gfn2"}, "keywords": {"accuracy": 0.01}}
+ts = qcopt.find_ts(guess, gxtb, hessian=gfn2)   # g-xTB saddle from a GFN2 starting Hessian
+```
+
+Keyword arguments are qcopt's keywords (`qcopt.keywords`), such as `maxiter`,
+`initial_hessian` (`"model"`, `"exact"`, ...) or `hessian_every`.
+
+Or as a qcdata input, alone or many at once (they advance together, and each round's
+gradients from all of them are computed in one call):
+
+```python
+from qcdata import ProgramInput, ProgramSpec
+
+inp = ProgramInput(
+    program="qcopt",
+    calctype="transition_state",
+    structure=guess,
+    keywords={"maxiter": 300},
+    subprograms=[
+        ProgramSpec(program="axtb", calctype="gradient", model={"method": "gxtb-v2.0.1"},
+                    keywords={"accuracy": 0.01}),
+        ProgramSpec(program="axtb", calctype="hessian", model={"method": "gxtb-v2.0.1"},
+                    keywords={"accuracy": 0.01}),
+    ],
+)
+out = qcopt.run(inp)            # or qcopt.run([inp1, inp2, ...])
+```
+
+## What it does
+
+| Calculation | Method |
+|---|---|
+| `optimization` | RS-RFO in TRIC coordinates (Wang and Song, 2016: each molecule's internal coordinates plus its translation and rotation), or delocalized internals, or Cartesians; Lindh model Hessian or the program's exact one; BFGS updates (Bofill while the Hessian is indefinite); optional frequency check that steps off saddle points |
+| `transition_state` | RS-P-RFO climbing the lowest mode (or one following a guide direction); exact (or a cheaper method's) or finite-difference starting Hessian; TS-BFGS updates; recomputed when the negative mode is lost |
+| `irc` | Mass-weighted steepest descent by Gonzalez-Schlegel steps (or the local quadratic approximation), both branches together, frames in the input's frame; overshoots retried at half the step; optionally both ends minimized together (`minimize_ends`) |
+
+Distances, angles and dihedrals can be held at target values (`constraints`), atoms
+frozen (`frozen_atoms`). Every frame is a qcdata `Frame` with the energy and gradient
+computed there.
+
+With qccompute installed, qcopt is also a program it runs:
+
+```python
+from qccompute import compute
+out = compute(inp)   # the ProgramInput above
+```
+
+## Benchmarks
+
+`benchmarks/` compares qcopt with Sella, geomeTRIC and OptKing on the same axtb
+gradients; results are summarized in AFH's findings.
+
+## Install
+
+```sh
+pip install qcopt               # or: pip install "qcopt[qccompute]" for any program qccompute runs
+```
+
+axtb (in-process g-xTB and GFN2-xTB with analytic Hessians) is installed from its
+[repository](https://github.com/atomsforhumanity/axtb) until it is on PyPI.
+
+## Status
+
+0.1: the API may still change between minor versions.
+
+## License
+
+MIT.

qcopt-0.1.0/README.md

@@ -0,0 +1,93 @@
+# qcopt
+
+Minimizations, transition-state searches, and IRCs for the qc* stack. Inputs and outputs
+are [qcdata](https://github.com/atomsforhumanity/qcdata) objects; gradients and Hessians
+come from [axtb](https://github.com/atomsforhumanity/axtb) in-process or from any program
+qccompute runs.
+
+```python
+import qcopt
+from qcdata import Structure
+
+# accuracy 0.01: at axtb's default SCF accuracy, g-xTB gradients carry ~1e-5 Eh/bohr
+# of noise, the size of qcopt's convergence threshold (12% more time per gradient).
+gxtb = {"program": "axtb", "model": {"method": "gxtb-v2.0.1"}, "keywords": {"accuracy": 0.01}}
+guess = Structure.open("ts_guess.xyz")
+
+ts = qcopt.find_ts(guess, gxtb, hessian=True, frequencies=True)  # ProgramOutput
+ts.results.extras["n_imaginary"]                                   # 1
+path = qcopt.irc(ts.results.final_structure, gxtb, hessian=True)   # PathData
+```
+
+`hessian` names the program computing Hessians: `True` for the gradient program, or another
+one, often a cheaper method. Frames keep the gradient program's energies and gradients:
+
+```python
+gfn2 = {"program": "axtb", "model": {"method": "gfn2"}, "keywords": {"accuracy": 0.01}}
+ts = qcopt.find_ts(guess, gxtb, hessian=gfn2)   # g-xTB saddle from a GFN2 starting Hessian
+```
+
+Keyword arguments are qcopt's keywords (`qcopt.keywords`), such as `maxiter`,
+`initial_hessian` (`"model"`, `"exact"`, ...) or `hessian_every`.
+
+Or as a qcdata input, alone or many at once (they advance together, and each round's
+gradients from all of them are computed in one call):
+
+```python
+from qcdata import ProgramInput, ProgramSpec
+
+inp = ProgramInput(
+    program="qcopt",
+    calctype="transition_state",
+    structure=guess,
+    keywords={"maxiter": 300},
+    subprograms=[
+        ProgramSpec(program="axtb", calctype="gradient", model={"method": "gxtb-v2.0.1"},
+                    keywords={"accuracy": 0.01}),
+        ProgramSpec(program="axtb", calctype="hessian", model={"method": "gxtb-v2.0.1"},
+                    keywords={"accuracy": 0.01}),
+    ],
+)
+out = qcopt.run(inp)            # or qcopt.run([inp1, inp2, ...])
+```
+
+## What it does
+
+| Calculation | Method |
+|---|---|
+| `optimization` | RS-RFO in TRIC coordinates (Wang and Song, 2016: each molecule's internal coordinates plus its translation and rotation), or delocalized internals, or Cartesians; Lindh model Hessian or the program's exact one; BFGS updates (Bofill while the Hessian is indefinite); optional frequency check that steps off saddle points |
+| `transition_state` | RS-P-RFO climbing the lowest mode (or one following a guide direction); exact (or a cheaper method's) or finite-difference starting Hessian; TS-BFGS updates; recomputed when the negative mode is lost |
+| `irc` | Mass-weighted steepest descent by Gonzalez-Schlegel steps (or the local quadratic approximation), both branches together, frames in the input's frame; overshoots retried at half the step; optionally both ends minimized together (`minimize_ends`) |
+
+Distances, angles and dihedrals can be held at target values (`constraints`), atoms
+frozen (`frozen_atoms`). Every frame is a qcdata `Frame` with the energy and gradient
+computed there.
+
+With qccompute installed, qcopt is also a program it runs:
+
+```python
+from qccompute import compute
+out = compute(inp)   # the ProgramInput above
+```
+
+## Benchmarks
+
+`benchmarks/` compares qcopt with Sella, geomeTRIC and OptKing on the same axtb
+gradients; results are summarized in AFH's findings.
+
+## Install
+
+```sh
+pip install qcopt               # or: pip install "qcopt[qccompute]" for any program qccompute runs
+```
+
+axtb (in-process g-xTB and GFN2-xTB with analytic Hessians) is installed from its
+[repository](https://github.com/atomsforhumanity/axtb) until it is on PyPI.
+
+## Status
+
+0.1: the API may still change between minor versions.
+
+## License
+
+MIT.

qcopt-0.1.0/benchmarks/README.md

@@ -0,0 +1,30 @@
+# Benchmarks
+
+Scripts that compare qcopt with Sella and geomeTRIC on the same gradients (axtb,
+in-process, one thread per run). They need their own environment:
+
+```sh
+cd benchmarks
+uv venv -p 3.12 .venv
+VIRTUAL_ENV=.venv uv pip install -e .. <axtb wheel> sella==2.6.0 ase==3.29.0 geometric==1.1.1 networkx
+VIRTUAL_ENV=.venv uv pip install "optking @ git+https://github.com/psi-rking/optking.git@0.5.0"
+```
+
+axtb runs at SCF accuracy 0.01 (`--accuracy`, passed explicitly): at axtb's default (1.0) g-xTB
+gradients carry ~1e-5 Eh/bohr of noise, the size of the 0.001 eV/A convergence threshold. Rounds
+before 2026-11-06 evening ran at the default.
+
+Pin BLAS to one thread before numpy loads (the scripts do), or small eigendecompositions run
+~100x slower next to axtb's threads. Freeze a copy of these scripts and of the code under test
+for each round: every job imports them when it starts.
+
+- `ts_bench.py OPTIMIZER XYZ OUT.json`: one optimization, counted and checked with a fresh
+  analytic Hessian (frequencies, energy, final gradient).
+- `run_set.py OUTDIR --xyz-glob ...`: many, in parallel processes (`--task ts|min|irc`,
+  `--extra OPT=JSON`, `--tag OPT=NAME`, `--pairs` for IRC connectivity checks).
+- `summarize.py RESULTS`: minima and transition states; `irc_summary.py RESULTS`: IRCs, with the
+  cost of minimizing their ends.
+- OptKing runs through its own driver (`optking.optimize.optimize`) with a computer that calls
+  axtb: its step-by-step helper breaks when it rebuilds its coordinates.
+
+Data (Reaction-QM structures, Jan's F0001 tables) and results live outside the repo.