qcstore 0.1.0a1__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (40) hide show
  1. qcstore-0.1.0a1/.github/ISSUE_TEMPLATE/bug_report.md +27 -0
  2. qcstore-0.1.0a1/.github/ISSUE_TEMPLATE/feature_request.md +20 -0
  3. qcstore-0.1.0a1/.github/dependabot.yml +17 -0
  4. qcstore-0.1.0a1/.github/workflows/ci.yaml +54 -0
  5. qcstore-0.1.0a1/.github/workflows/docs.yaml +48 -0
  6. qcstore-0.1.0a1/.github/workflows/publish-to-pypi.yaml +56 -0
  7. qcstore-0.1.0a1/.gitignore +14 -0
  8. qcstore-0.1.0a1/.pre-commit-config.yaml +62 -0
  9. qcstore-0.1.0a1/.python-version +1 -0
  10. qcstore-0.1.0a1/AGENTS.md +46 -0
  11. qcstore-0.1.0a1/CHANGELOG.md +23 -0
  12. qcstore-0.1.0a1/CONTRIBUTING.md +81 -0
  13. qcstore-0.1.0a1/LICENSE +21 -0
  14. qcstore-0.1.0a1/PKG-INFO +160 -0
  15. qcstore-0.1.0a1/README.md +111 -0
  16. qcstore-0.1.0a1/docs/CNAME +1 -0
  17. qcstore-0.1.0a1/docs/api/backends.md +5 -0
  18. qcstore-0.1.0a1/docs/api/sqlite.md +8 -0
  19. qcstore-0.1.0a1/docs/api/store.md +9 -0
  20. qcstore-0.1.0a1/docs/api/verify.md +9 -0
  21. qcstore-0.1.0a1/docs/design.md +215 -0
  22. qcstore-0.1.0a1/docs/index.md +1 -0
  23. qcstore-0.1.0a1/mkdocs.yml +75 -0
  24. qcstore-0.1.0a1/pyproject.toml +97 -0
  25. qcstore-0.1.0a1/src/qcstore/__init__.py +27 -0
  26. qcstore-0.1.0a1/src/qcstore/__main__.py +44 -0
  27. qcstore-0.1.0a1/src/qcstore/backend.py +143 -0
  28. qcstore-0.1.0a1/src/qcstore/index.py +370 -0
  29. qcstore-0.1.0a1/src/qcstore/py.typed +0 -0
  30. qcstore-0.1.0a1/src/qcstore/store.py +973 -0
  31. qcstore-0.1.0a1/src/qcstore/verify.py +93 -0
  32. qcstore-0.1.0a1/tests/__init__.py +0 -0
  33. qcstore-0.1.0a1/tests/outputs.py +157 -0
  34. qcstore-0.1.0a1/tests/test_backend.py +126 -0
  35. qcstore-0.1.0a1/tests/test_concurrency.py +200 -0
  36. qcstore-0.1.0a1/tests/test_index.py +250 -0
  37. qcstore-0.1.0a1/tests/test_store.py +385 -0
  38. qcstore-0.1.0a1/tests/test_verify.py +105 -0
  39. qcstore-0.1.0a1/tests/writers.py +90 -0
  40. qcstore-0.1.0a1/uv.lock +1752 -0
@@ -0,0 +1,27 @@
1
+ ---
2
+ name: Bug report
3
+ about: Create a report to help us improve
4
+ title: "[BUG] - "
5
+ labels: bug
6
+ assignees: ''
7
+
8
+ ---
9
+
10
+ **Describe the bug**
11
+ A clear and concise description of what the bug is.
12
+
13
+ **To Reproduce**
14
+ Steps to reproduce the behavior. Please provide all necessary data and a runnable Python script that reproduces your error:
15
+ 1. Go to '...'
16
+ 2. Click on '....'
17
+ 3. Scroll down to '....'
18
+ 4. See error
19
+
20
+ **Expected behavior**
21
+ A clear and concise description of what you expected to happen.
22
+
23
+ **Screenshots**
24
+ If applicable, add screenshots to help explain your problem.
25
+
26
+ **Additional context**
27
+ Add any other context about the problem here.
@@ -0,0 +1,20 @@
1
+ ---
2
+ name: Feature request
3
+ about: Suggest an idea for this project
4
+ title: "[FEATURE] - "
5
+ labels: enhancement
6
+ assignees: ''
7
+
8
+ ---
9
+
10
+ **Is your feature request related to a problem? Please describe.**
11
+ A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
12
+
13
+ **Describe the solution you'd like**
14
+ A clear and concise description of what you want to happen.
15
+
16
+ **Describe alternatives you've considered**
17
+ A clear and concise description of any alternative solutions or features you've considered.
18
+
19
+ **Additional context**
20
+ Add any other context or screenshots about the feature request here.
@@ -0,0 +1,17 @@
1
+ version: 2
2
+ updates:
3
+ - package-ecosystem: github-actions
4
+ directory: /
5
+ schedule:
6
+ interval: monthly
7
+ groups:
8
+ actions:
9
+ patterns: ["*"]
10
+ # Keeps uv.lock current so CI tests the dependency versions users install.
11
+ - package-ecosystem: uv
12
+ directory: /
13
+ schedule:
14
+ interval: monthly
15
+ groups:
16
+ dependencies:
17
+ patterns: ["*"]
@@ -0,0 +1,54 @@
1
+ name: CI
2
+
3
+ on:
4
+ push:
5
+ branches: [main, next]
6
+ pull_request:
7
+ workflow_dispatch:
8
+
9
+ concurrency:
10
+ group: ${{ github.workflow }}-${{ github.ref }}
11
+ cancel-in-progress: true
12
+
13
+ permissions:
14
+ contents: read
15
+
16
+ jobs:
17
+ checks:
18
+ name: Lint, format, types, secrets
19
+ runs-on: ubuntu-latest
20
+ steps:
21
+ - uses: actions/checkout@v7
22
+ - uses: astral-sh/setup-uv@v7
23
+ with:
24
+ enable-cache: true
25
+ - name: Install
26
+ run: uv sync --locked --all-extras --all-groups
27
+ - name: No local or git sources for qc* packages
28
+ run: |
29
+ if awk '/^\[tool\.uv\.sources\]/{f=1;next} /^\[/{f=0} f' pyproject.toml | grep -E '^qc[a-z]+ *= *\{.*(path|git) *='; then
30
+ echo "::error::Remove path/git [tool.uv.sources] entries for qc* packages before merging."
31
+ exit 1
32
+ fi
33
+ - name: Pre-commit hooks
34
+ run: uv run pre-commit run --all-files --show-diff-on-failure
35
+
36
+ tests:
37
+ name: Tests (Python ${{ matrix.python-version }})
38
+ runs-on: ubuntu-latest
39
+ strategy:
40
+ fail-fast: false
41
+ matrix:
42
+ python-version: ["3.11", "3.15"]
43
+ steps:
44
+ - uses: actions/checkout@v7
45
+ - uses: astral-sh/setup-uv@v7
46
+ with:
47
+ enable-cache: true
48
+ python-version: ${{ matrix.python-version }}
49
+ # Optional extras are installed and type-checked by the checks job; some
50
+ # (e.g. xtb-python) have no wheels for the newest Python.
51
+ - name: Install
52
+ run: uv sync --locked --all-groups
53
+ - name: Run tests
54
+ run: uv run pytest --cov --cov-report=term-missing
@@ -0,0 +1,48 @@
1
+ name: Docs
2
+
3
+ # Publishes https://qcstore.docs.afh.org from the gh-pages branch.
4
+ # A final release tag (0.1.0, not a pre-release such as 0.1.0a1) or a manual run
5
+ # builds and deploys the site; pull requests that touch the docs only build it.
6
+ on:
7
+ push:
8
+ # Filter patterns, not regular expressions: + repeats the preceding character
9
+ # class, . is literal, and the pattern must match the whole tag.
10
+ tags: ["[0-9]+.[0-9]+.[0-9]+"]
11
+ workflow_dispatch:
12
+ pull_request:
13
+ paths:
14
+ - "docs/**"
15
+ - "src/**"
16
+ - "mkdocs.yml"
17
+ - "pyproject.toml"
18
+ - "uv.lock"
19
+ - ".github/workflows/docs.yaml"
20
+
21
+ permissions:
22
+ contents: read
23
+
24
+ jobs:
25
+ docs:
26
+ name: Build and publish docs
27
+ runs-on: ubuntu-latest
28
+ # Deploys must not overlap; pull request builds can be superseded.
29
+ concurrency:
30
+ group: docs-${{ github.event_name == 'pull_request' && github.ref || 'deploy' }}
31
+ cancel-in-progress: ${{ github.event_name == 'pull_request' }}
32
+ permissions:
33
+ contents: write # push to gh-pages
34
+ steps:
35
+ - uses: actions/checkout@v7
36
+ - uses: astral-sh/setup-uv@v7
37
+ with:
38
+ enable-cache: true
39
+ - name: Install
40
+ run: uv sync --locked --group docs
41
+ - name: Build
42
+ run: uv run mkdocs build --strict
43
+ - name: Publish to gh-pages
44
+ if: github.event_name != 'pull_request'
45
+ run: |
46
+ git config user.name "github-actions[bot]"
47
+ git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
48
+ uv run mkdocs gh-deploy --force --message "Deploy {sha} with MkDocs {version}"
@@ -0,0 +1,56 @@
1
+ name: Release
2
+
3
+ # The file name must stay publish-to-pypi.yaml: PyPI's trusted publisher for this
4
+ # project is registered against it.
5
+ # Pushing a version tag (e.g. 0.1.0a1) publishes to PyPI and creates the
6
+ # GitHub release. Publishing waits for approval on the protected `pypi` environment.
7
+ on:
8
+ push:
9
+ tags: ["*"]
10
+
11
+ jobs:
12
+ publish:
13
+ name: Build and publish to PyPI
14
+ runs-on: ubuntu-latest
15
+ environment:
16
+ name: pypi
17
+ url: https://pypi.org/project/qcstore/
18
+ permissions:
19
+ contents: read
20
+ id-token: write # trusted publishing
21
+ steps:
22
+ - uses: actions/checkout@v7
23
+ - uses: astral-sh/setup-uv@v7
24
+ - name: Tag must match the package version
25
+ run: |
26
+ version="$(sed -n 's/^version *= *"\(.*\)"/\1/p' pyproject.toml | head -n1)"
27
+ if [ "$version" != "$GITHUB_REF_NAME" ]; then
28
+ echo "::error::Tag $GITHUB_REF_NAME does not match pyproject version $version."
29
+ exit 1
30
+ fi
31
+ - name: Build
32
+ run: uv build
33
+ - uses: pypa/gh-action-pypi-publish@release/v1
34
+
35
+ github-release:
36
+ name: Create GitHub release
37
+ needs: publish
38
+ runs-on: ubuntu-latest
39
+ permissions:
40
+ contents: write
41
+ steps:
42
+ - uses: actions/checkout@v7
43
+ - name: Extract release notes from CHANGELOG.md
44
+ run: |
45
+ awk -v v="$GITHUB_REF_NAME" '
46
+ $0 ~ "^## \\[" v "\\]" {f=1; next}
47
+ f && /^## \[/ {exit}
48
+ f {print}
49
+ ' CHANGELOG.md > RELEASE_NOTES.md
50
+ - name: Create release
51
+ env:
52
+ GH_TOKEN: ${{ github.token }}
53
+ run: |
54
+ prerelease=""
55
+ case "$GITHUB_REF_NAME" in *a*|*b*|*rc*) prerelease="--prerelease" ;; esac
56
+ gh release create "$GITHUB_REF_NAME" --title "$GITHUB_REF_NAME" --notes-file RELEASE_NOTES.md --verify-tag $prerelease
@@ -0,0 +1,14 @@
1
+ __pycache__/
2
+ *.py[cod]
3
+ build/
4
+ dist/
5
+ *.egg-info/
6
+ .venv/
7
+ .coverage
8
+ .coverage.*
9
+ htmlcov/
10
+ coverage.xml
11
+ .pytest_cache/
12
+ .mypy_cache/
13
+ .ruff_cache/
14
+ /site
@@ -0,0 +1,62 @@
1
+ # Every hook runs the project's own locked tools through `uv run`, so local hooks,
2
+ # CI, and your editor use identical versions. Install once with
3
+ # `uv run pre-commit install`; see CONTRIBUTING.md.
4
+ default_install_hook_types: [pre-commit]
5
+ default_stages: [pre-commit]
6
+ repos:
7
+ - repo: local
8
+ hooks:
9
+ - id: check-yaml
10
+ name: check yaml
11
+ entry: uv run check-yaml
12
+ language: system
13
+ types: [yaml]
14
+ exclude: ^mkdocs\.yml$
15
+ - id: check-toml
16
+ name: check toml
17
+ entry: uv run check-toml
18
+ language: system
19
+ types: [toml]
20
+ - id: check-merge-conflict
21
+ name: check for merge conflicts
22
+ entry: uv run check-merge-conflict
23
+ language: system
24
+ types: [text]
25
+ - id: check-added-large-files
26
+ name: check for added large files
27
+ entry: uv run check-added-large-files --maxkb=250
28
+ language: system
29
+ exclude: ^(uv\.lock|tests/data/|docs/)
30
+ - id: detect-secrets
31
+ name: detect secrets
32
+ entry: uv run detect-secrets-hook
33
+ language: system
34
+ types: [text]
35
+ exclude: (\.lock|\.ipynb)$|^tests/data/
36
+ - id: uv-lock
37
+ name: uv.lock is up to date
38
+ entry: uv lock --check
39
+ language: system
40
+ files: ^(pyproject\.toml|uv\.lock)$
41
+ pass_filenames: false
42
+ - id: ruff-check
43
+ name: ruff check
44
+ entry: uv run ruff check --fix --exit-non-zero-on-fix
45
+ language: system
46
+ types_or: [python, pyi]
47
+ - id: ruff-format
48
+ name: ruff format
49
+ entry: uv run ruff format
50
+ language: system
51
+ types_or: [python, pyi]
52
+ - id: typos
53
+ name: typos
54
+ entry: uv run typos --force-exclude
55
+ language: system
56
+ types: [text]
57
+ - id: mypy
58
+ name: mypy
59
+ entry: uv run mypy
60
+ language: system
61
+ types_or: [python, pyi]
62
+ pass_filenames: false
@@ -0,0 +1 @@
1
+ 3.11
@@ -0,0 +1,46 @@
1
+ # AGENTS.md
2
+
3
+ Instructions for AI coding agents (and a quick reference for people) working in `qcstore`. CONTRIBUTING.md explains the same workflow in more detail.
4
+
5
+ ## This package
6
+
7
+ `qcstore` keeps every run of every quantum chemistry calculation as plain JSON records, filed under qcdata's calculation key, with the numerics identities of the programs that produced each run. `docs/design.md` describes the layout and the concurrency rules; read it before changing how anything is written.
8
+
9
+ - It depends on `qcdata` and the standard library only. Do not add runtime dependencies.
10
+ - Correctness under concurrent writers and crashes comes before features. Every file is written once, atomically, through the `Backend`; `current.json` is the only file ever replaced; nothing in a run is ever deleted. A change to the write order or the files needs a test with real processes (`tests/test_concurrency.py`).
11
+ - The records are read by people and agents with `cat` and `jq`: keep them plain, uncompressed, and self-describing. A change to `record.json` bumps `FORMAT`.
12
+ - The index is a cache of the store: its rows always come from the store, never from journal lines.
13
+
14
+ ## The qc* suite
15
+
16
+ Dependencies point one way: qcref -> qcdata -> {qcinf, qcstore, qccodec} -> qccompute. Never import a package that sits later in that order.
17
+
18
+ ## Commands
19
+
20
+ ```sh
21
+ uv sync --all-groups # install everything
22
+ uv run pre-commit install # once per clone: run the checks on every commit
23
+ uv run pytest # tests
24
+ uv run ruff check --fix . && uv run ruff format .
25
+ uv run mypy
26
+ uv run pre-commit run --all-files # exactly what CI checks
27
+ uv run mkdocs build --strict # the docs
28
+ ```
29
+
30
+ Use `uv add` / `uv remove` for dependencies; never edit `uv.lock` by hand.
31
+
32
+ ## Code conventions
33
+
34
+ - Use type annotations for all function and method parameters (except `self` and `cls`) and return values, including `-> None`. mypy enforces this for library code.
35
+ - Prefer precise types; avoid `Any` unless genuinely necessary (JSON documents are `Any`).
36
+ - Write Google-style docstrings for all public modules, classes, functions, and methods (ruff enforces this). Start with a one-line summary ending in a period; add Args, Returns, Raises sections where applicable; state units of any number.
37
+ - Use `X | None`, not `Optional[X]`. Target Python 3.11.
38
+ - Keep changes focused. Do not reformat or refactor unrelated code.
39
+
40
+ ## Before you finish
41
+
42
+ - `uv run pre-commit run --all-files` and `uv run pytest` pass.
43
+ - New behavior has tests; bug fixes have a test that failed before the fix.
44
+ - User-visible changes are listed under `## [unreleased]` in CHANGELOG.md.
45
+ - `pyproject.toml` has no `[tool.uv.sources]` path or git entries for qc* packages (CI rejects them).
46
+ - Do not commit, push, tag, or release unless asked to.
@@ -0,0 +1,23 @@
1
+ # Changelog
2
+
3
+ All notable changes to this project will be documented in this file.
4
+
5
+ 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).
6
+
7
+ ## [unreleased]
8
+
9
+ ## [0.1.0a1] - 2026-11-17
10
+
11
+ The first alpha of qcstore: a general store for quantum chemistry results, depending on qcdata only.
12
+
13
+ ### Added
14
+
15
+ - `Store(uri)`: every run of every calculation, filed under `qcdata.calculation_key(inp)` (the input alone) as plain JSON records, on a local disk or NFS, with many writers at once and no locks. Each run records the numerics identities of the programs that produced it.
16
+ - `Store.put(output, identities, tags=(), meta=None)` adds a run and returns its id; it refuses warm-started session frames (`record.warm_start` true).
17
+ - `Store.get(key, identities=None, blobs=True)`: the preferred run (the latest success not withdrawn, else the latest run not withdrawn), among the runs made with, or carried to, exactly those identities, or among all runs.
18
+ - `Store.runs(key)`: every run with its identities, carries, withdrawal, meta, and the environment it ran in (host, CPU model, devices, libc).
19
+ - `Store.blob`, `withdraw`, `tag`, `untag`, `iter` and `copy_to`.
20
+ - `Store.carry(runs, identities, evidence)`: declares any selection of runs valid for other identities, with the evidence stored once (`carries/<sha256>.json`) and an empty marker on each run.
21
+ - `Store.index()`: an optional SQLite index fed by per-writer journals, with `update`, `rebuild`, `query` and `sql`; columns for identities, carries, tags, meta, the environment and each run's whole input.
22
+ - `python -m qcstore verify URI [--repair]`: keys recomputed, records complete, blob and carry digests, pointers consistent.
23
+ - `Backend`, the interface a store's files go through, and `LocalBackend` for local disks and NFS.
@@ -0,0 +1,81 @@
1
+ # Contributing to qcstore
2
+
3
+ Thanks for helping! This guide covers setup, the pre-commit workflow, tests, pull requests, and releases. Code conventions (typing, docstrings, units) are in [AGENTS.md](./AGENTS.md), which applies to people and AI agents alike.
4
+
5
+ ## Development setup
6
+
7
+ You need [uv](https://docs.astral.sh/uv/). Then:
8
+
9
+ ```sh
10
+ git clone https://github.com/atomsforhumanity/qcstore.git
11
+ cd qcstore
12
+ uv sync --all-groups # creates .venv with the package and all dev tools
13
+ uv run pre-commit install # run the checks automatically on every commit
14
+ ```
15
+
16
+ ## Pre-commit workflow
17
+
18
+ Every `git commit` runs these checks on the files you staged. All of them use the tool versions locked in `uv.lock`, so they behave the same on your machine and in CI.
19
+
20
+ | Check | What it does |
21
+ |---|---|
22
+ | `ruff check` | Lints (pyflakes, pycodestyle, import order, bugbear, pyupgrade, Google docstrings) and fixes what it can |
23
+ | `ruff format` | Formats Python code |
24
+ | `mypy` | Type-checks the package; library functions must be fully annotated |
25
+ | `typos` | Spell-checks code and docs |
26
+ | `detect-secrets` | Blocks commits that contain credentials or tokens |
27
+ | `uv lock --check` | Fails if `uv.lock` is out of date with `pyproject.toml` |
28
+ | file checks | Valid YAML and TOML, no merge-conflict markers, no files over 250 KB outside `tests/data/` and `docs/` |
29
+
30
+ If a hook fixes files (ruff often does), the commit stops so you can review the changes. Stage them and commit again:
31
+
32
+ ```sh
33
+ git add -u && git commit
34
+ ```
35
+
36
+ Run every check on the whole repository, exactly as CI does:
37
+
38
+ ```sh
39
+ uv run pre-commit run --all-files
40
+ ```
41
+
42
+ You can run the tools directly too: `uv run ruff check --fix .`, `uv run ruff format .`, `uv run mypy`. Please don't skip hooks with `--no-verify`; CI runs the same checks and will fail.
43
+
44
+ ## Running tests
45
+
46
+ ```sh
47
+ uv run pytest # all tests
48
+ uv run pytest --cov --cov-report=term-missing # with coverage
49
+ ```
50
+
51
+ ## Pull requests
52
+
53
+ 1. Branch from `next`.
54
+ 2. Make your change with tests. Bug fixes should include a test that fails without the fix.
55
+ 3. Add a line under `## [unreleased]` in [CHANGELOG.md](./CHANGELOG.md) for anything users would notice.
56
+ 4. Open a pull request. CI runs the pre-commit checks and the test suite on the oldest and newest supported Python versions.
57
+
58
+ Never commit `[tool.uv.sources]` entries that point qc* packages at local paths or git branches; CI rejects them. When a change needs an unreleased version of another qc* package, release that package first.
59
+
60
+ ## Releases (maintainers)
61
+
62
+ Alphas (`0.1.0a1`, ...) are tagged from `next`; final releases from `main`.
63
+
64
+ 1. Set the version in `pyproject.toml`, date the changelog section, run `uv lock`, and
65
+ commit "Release X.Y.Z" through a pull request.
66
+ 2. Tag the release commit and push the tag: `git tag X.Y.Z && git push origin X.Y.Z`.
67
+ 3. The tag starts the Release workflow. Approve the waiting deployment to the `pypi` environment in the Actions tab; the workflow then publishes to PyPI and creates the GitHub release from the changelog section. The workflow refuses a tag that doesn't match the version in `pyproject.toml`.
68
+ 4. A final release tag also starts the Docs workflow, which builds the site and publishes it to
69
+ [qcstore.docs.afh.org](https://qcstore.docs.afh.org). Run it
70
+ by hand from the Actions tab ("Run workflow") to republish without a release.
71
+
72
+ ## Documentation
73
+
74
+ The site is built with MkDocs from `docs/` and the package's docstrings:
75
+
76
+ ```sh
77
+ uv run mkdocs serve # live preview at http://127.0.0.1:8000
78
+ uv run mkdocs build --strict
79
+ ```
80
+
81
+ Pull requests that touch the docs or source build the site in CI.
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Atoms for Humanity
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,160 @@
1
+ Metadata-Version: 2.5
2
+ Name: qcstore
3
+ Version: 0.1.0a1
4
+ Summary: A store for quantum chemistry results: plain JSON records, safe under concurrent writers.
5
+ Project-URL: Homepage, https://github.com/atomsforhumanity/qcstore
6
+ Project-URL: Documentation, https://qcstore.docs.afh.org
7
+ Project-URL: Source, https://github.com/atomsforhumanity/qcstore
8
+ Project-URL: Changelog, https://github.com/atomsforhumanity/qcstore/blob/main/CHANGELOG.md
9
+ Project-URL: Bug Tracker, https://github.com/atomsforhumanity/qcstore/issues
10
+ Author-email: Colton Hicks <github@coltonhicks.com>
11
+ License: MIT License
12
+
13
+ Copyright (c) 2026 Atoms for Humanity
14
+
15
+ Permission is hereby granted, free of charge, to any person obtaining a copy
16
+ of this software and associated documentation files (the "Software"), to deal
17
+ in the Software without restriction, including without limitation the rights
18
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
19
+ copies of the Software, and to permit persons to whom the Software is
20
+ furnished to do so, subject to the following conditions:
21
+
22
+ The above copyright notice and this permission notice shall be included in all
23
+ copies or substantial portions of the Software.
24
+
25
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
26
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
27
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
28
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
29
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
30
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
31
+ SOFTWARE.
32
+ License-File: LICENSE
33
+ Keywords: cache,data-store,provenance,quantum-chemistry
34
+ Classifier: Development Status :: 3 - Alpha
35
+ Classifier: Intended Audience :: Developers
36
+ Classifier: Intended Audience :: Science/Research
37
+ Classifier: License :: OSI Approved :: MIT License
38
+ Classifier: Natural Language :: English
39
+ Classifier: Programming Language :: Python :: 3.11
40
+ Classifier: Programming Language :: Python :: 3.12
41
+ Classifier: Programming Language :: Python :: 3.13
42
+ Classifier: Programming Language :: Python :: 3.14
43
+ Classifier: Programming Language :: Python :: 3.15
44
+ Classifier: Topic :: Scientific/Engineering
45
+ Classifier: Topic :: Software Development :: Libraries
46
+ Requires-Python: >=3.11
47
+ Requires-Dist: qcdata>=0.24.0a2
48
+ Description-Content-Type: text/markdown
49
+
50
+ # qcstore
51
+
52
+ A store for quantum chemistry results. Every run of every calculation is kept as plain
53
+ JSON you can read with `cat` and `jq`, filed under the calculation's key, and nothing is
54
+ ever overwritten or deleted. Many processes can write to one store at once, on a local
55
+ disk or NFS, without locks, and a writer killed mid-write leaves nothing a reader trusts.
56
+
57
+ qcstore depends only on [qcdata](https://github.com/atomsforhumanity/qcdata) and the
58
+ Python standard library.
59
+
60
+ ## Install
61
+
62
+ ```sh
63
+ pip install qcstore
64
+ ```
65
+
66
+ ## Five minutes
67
+
68
+ A store files each calculation under its key, `qcdata.calculation_key(inp)`: the input
69
+ alone. Each run also records the *numerics identity* of every program that produced it
70
+ (`{"xtb": "6.7.1"}`), so results of different code stay apart while the key stays the
71
+ same across releases.
72
+
73
+ ```python
74
+ from qcdata import ProgramInput, ProgramOutput, SinglePointData, Structure
75
+ from qcstore import Store
76
+
77
+ water = Structure(
78
+ symbols=["O", "H", "H"],
79
+ geometry=[[0.0, 0.0, 0.0], [0.0, 1.43, 1.11], [0.0, -1.43, 1.11]], # bohr
80
+ )
81
+ inp = ProgramInput(
82
+ program="xtb", calctype="energy", structure=water, model={"method": "gfn2"}
83
+ )
84
+ output = ProgramOutput(
85
+ input_data=inp,
86
+ success=True,
87
+ logs="normal termination of xtb\n",
88
+ results=SinglePointData(
89
+ provenance={"program": "xtb", "program_version": "6.7.1"}, energy=-5.07
90
+ ),
91
+ )
92
+
93
+ store = Store("./store")
94
+ run = store.put(output, {"xtb": "6.7.1"}, tags=["demo"], meta={"by": "readme"})
95
+
96
+ key = store.key(inp)
97
+ store.get(key) # the latest success, whatever produced it
98
+ store.get(key, {"xtb": "6.7.1"}) # only a run of xtb 6.7.1
99
+ store.get(key, {"xtb": "6.8.0"}) # None: never run with 6.8.0
100
+ store.blob(key, "logs") # b"normal termination of xtb\n"
101
+ ```
102
+
103
+ A new release that gives the same results need not rerun anything: carry the runs to the
104
+ new identities, with the evidence. The evidence is stored once, however many runs it
105
+ covers, and asserts that each run's whole output is what the new code would produce.
106
+
107
+ ```python
108
+ store.carry([(key, run)], {"xtb": "6.8.0"}, {"benchmark": "S22", "max_abs_diff": 0.0})
109
+ store.get(key, {"xtb": "6.8.0"}) # the 6.7.1 run, valid for 6.8.0 too
110
+ ```
111
+
112
+ A wrong result is withdrawn, not deleted:
113
+
114
+ ```python
115
+ store.withdraw(key, run, "wrong geometry")
116
+ store.get(key) # None: no other run
117
+ for r in store.runs(key):
118
+ print(r.id, r.success, r.identities, r.withdrawn.reason)
119
+ ```
120
+
121
+ Questions across calculations go to an optional SQLite index, kept up to date from the
122
+ store's journals:
123
+
124
+ ```python
125
+ index = store.index()
126
+ index.query(tag="demo", program="xtb")
127
+ index.query(identities={"xtb": "6.8.0"}) # every run valid under xtb 6.8.0
128
+ index.sql(
129
+ "SELECT formula, COUNT(DISTINCT key) AS calculations FROM runs GROUP BY formula"
130
+ )
131
+ ```
132
+
133
+ With [qccompute](https://github.com/atomsforhumanity/qccompute), a store caches
134
+ calculations: `qccompute.compute(inp, store=store)` returns a stored result when one
135
+ from the same code exists, and stores what it runs.
136
+
137
+ ## On disk
138
+
139
+ ```text
140
+ store/
141
+ records/3f/k1:3f9a.../ one directory per calculation
142
+ current.json the preferred run, overall and per identity set
143
+ tags/demo an empty file per tag
144
+ 20261117T101500.123456Z-7c1e9a0b/ one directory per run, never changed
145
+ record.json identities, meta, and the output
146
+ blobs/output.logs logs, files and large arrays, named by JSON path
147
+ carries/9c1f... an empty marker per carry of this run
148
+ withdrawn.json who withdrew it, when, and why
149
+ carries/9c1f....json a carry: "also valid for xtb 6.8.0", the evidence
150
+ journals/<writer>/<batch>.jsonl what each writer changed, for the index
151
+ index.sqlite the optional index, rebuildable at any time
152
+ ```
153
+
154
+ `python -m qcstore verify ./store` checks every record: keys, blob digests, pointers.
155
+
156
+ ## Documentation
157
+
158
+ [qcstore.docs.afh.org](https://qcstore.docs.afh.org): the API, and the
159
+ [design](https://qcstore.docs.afh.org/design/): the layout, how writers agree without
160
+ locks, and what a crash can and cannot leave behind.