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.
- qcstore-0.1.0a1/.github/ISSUE_TEMPLATE/bug_report.md +27 -0
- qcstore-0.1.0a1/.github/ISSUE_TEMPLATE/feature_request.md +20 -0
- qcstore-0.1.0a1/.github/dependabot.yml +17 -0
- qcstore-0.1.0a1/.github/workflows/ci.yaml +54 -0
- qcstore-0.1.0a1/.github/workflows/docs.yaml +48 -0
- qcstore-0.1.0a1/.github/workflows/publish-to-pypi.yaml +56 -0
- qcstore-0.1.0a1/.gitignore +14 -0
- qcstore-0.1.0a1/.pre-commit-config.yaml +62 -0
- qcstore-0.1.0a1/.python-version +1 -0
- qcstore-0.1.0a1/AGENTS.md +46 -0
- qcstore-0.1.0a1/CHANGELOG.md +23 -0
- qcstore-0.1.0a1/CONTRIBUTING.md +81 -0
- qcstore-0.1.0a1/LICENSE +21 -0
- qcstore-0.1.0a1/PKG-INFO +160 -0
- qcstore-0.1.0a1/README.md +111 -0
- qcstore-0.1.0a1/docs/CNAME +1 -0
- qcstore-0.1.0a1/docs/api/backends.md +5 -0
- qcstore-0.1.0a1/docs/api/sqlite.md +8 -0
- qcstore-0.1.0a1/docs/api/store.md +9 -0
- qcstore-0.1.0a1/docs/api/verify.md +9 -0
- qcstore-0.1.0a1/docs/design.md +215 -0
- qcstore-0.1.0a1/docs/index.md +1 -0
- qcstore-0.1.0a1/mkdocs.yml +75 -0
- qcstore-0.1.0a1/pyproject.toml +97 -0
- qcstore-0.1.0a1/src/qcstore/__init__.py +27 -0
- qcstore-0.1.0a1/src/qcstore/__main__.py +44 -0
- qcstore-0.1.0a1/src/qcstore/backend.py +143 -0
- qcstore-0.1.0a1/src/qcstore/index.py +370 -0
- qcstore-0.1.0a1/src/qcstore/py.typed +0 -0
- qcstore-0.1.0a1/src/qcstore/store.py +973 -0
- qcstore-0.1.0a1/src/qcstore/verify.py +93 -0
- qcstore-0.1.0a1/tests/__init__.py +0 -0
- qcstore-0.1.0a1/tests/outputs.py +157 -0
- qcstore-0.1.0a1/tests/test_backend.py +126 -0
- qcstore-0.1.0a1/tests/test_concurrency.py +200 -0
- qcstore-0.1.0a1/tests/test_index.py +250 -0
- qcstore-0.1.0a1/tests/test_store.py +385 -0
- qcstore-0.1.0a1/tests/test_verify.py +105 -0
- qcstore-0.1.0a1/tests/writers.py +90 -0
- 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,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.
|
qcstore-0.1.0a1/LICENSE
ADDED
|
@@ -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.
|
qcstore-0.1.0a1/PKG-INFO
ADDED
|
@@ -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.
|