Skip to content

Commit 9c81cc8

Browse files
IvanChernyshovIvanChernyshov
committed
v0.1.4 - First public release
First public `atomref` release: a lightweight, pure-Python package for curated, provenance-aware atomic reference data. - Includes element metadata and named datasets for covalent, van der Waals, and atomic-radius values. - Provides typed policies with overrides, fallbacks, custom sets, and transfer-based completion. - Added provisional X–H bond-length support via `xh_bond_length`, `csd_legacy_xh_cno`, and `XHPolicy`. - Transfer models now support datasets, custom sets, and policies as sources. - Added safeguards for nested correlations, transfer-depth tracking, and robust cycle detection. - Documentation, changelog, and roadmap were cleaned up and synchronized across the repo.
2 parents 9d869c5 + 53ae9f7 commit 9c81cc8

80 files changed

Lines changed: 8060 additions & 0 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.flake8‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
[flake8]
2+
max-line-length = 88
3+
extend-ignore = E203

‎.gitattributes‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
# Enforce Linux-style line endings for all text files
2+
* text=auto eol=lf

‎.github/workflows/ci.yml‎

Lines changed: 92 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,92 @@
1+
name: CI
2+
3+
on:
4+
push:
5+
pull_request:
6+
7+
jobs:
8+
lint:
9+
runs-on: ubuntu-latest
10+
steps:
11+
- uses: actions/checkout@v4
12+
- uses: actions/setup-python@v5
13+
with:
14+
python-version: "3.12"
15+
- name: Install lint dependencies
16+
run: |
17+
python -m pip install --upgrade pip
18+
python -m pip install .[dev]
19+
- name: Lint
20+
run: flake8 src tests tools
21+
- name: Validate packaged registry
22+
run: python tools/check_registry.py
23+
- name: Validate notebooks
24+
run: python tools/check_notebooks.py
25+
- name: Check notebook exports
26+
run: python tools/export_notebooks.py --check
27+
- name: Check README sync
28+
run: python tools/gen_readme.py --check
29+
30+
docs-check:
31+
runs-on: ubuntu-latest
32+
steps:
33+
- uses: actions/checkout@v4
34+
- uses: actions/setup-python@v5
35+
with:
36+
python-version: "3.12"
37+
- name: Install docs extras
38+
run: |
39+
python -m pip install --upgrade pip
40+
python -m pip install .[docs]
41+
- name: Export notebooks and README
42+
run: |
43+
python tools/export_notebooks.py --check
44+
python tools/gen_readme.py --check
45+
- name: Build docs
46+
run: mkdocs build --strict
47+
48+
test:
49+
runs-on: ubuntu-latest
50+
strategy:
51+
matrix:
52+
python-version: ["3.10", "3.11", "3.12", "3.13"]
53+
steps:
54+
- uses: actions/checkout@v4
55+
- uses: actions/setup-python@v5
56+
with:
57+
python-version: ${{ matrix.python-version }}
58+
- name: Install
59+
run: |
60+
python -m pip install --upgrade pip
61+
python -m pip install .[test]
62+
- name: Test
63+
run: pytest
64+
65+
build-dist:
66+
runs-on: ubuntu-latest
67+
steps:
68+
- uses: actions/checkout@v4
69+
- uses: actions/setup-python@v5
70+
with:
71+
python-version: "3.12"
72+
- name: Install build dependencies
73+
run: |
74+
python -m pip install --upgrade pip
75+
python -m pip install build twine
76+
- name: Build distributions
77+
run: python -m build
78+
- name: Validate metadata
79+
run: python -m twine check dist/*
80+
- name: Check packaged files
81+
run: python tools/check_dist.py dist
82+
- name: Install built wheel and smoke-test it
83+
run: |
84+
python -m pip install --force-reinstall --no-deps dist/*.whl
85+
python - <<'PY'
86+
import atomref as ar
87+
88+
assert ar.get_covalent_radius('C') == 0.76
89+
assert ar.get_vdw_radius('C') == 1.77
90+
assert 'atomic_radius' in ar.list_quantities()
91+
assert 'rahm2016' in ar.list_dataset_ids('atomic_radius', usage_role='support')
92+
PY

‎.github/workflows/docs.yml‎

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
name: Docs
2+
3+
on:
4+
push:
5+
branches: [main, master]
6+
workflow_dispatch:
7+
8+
concurrency:
9+
group: pages
10+
cancel-in-progress: true
11+
12+
jobs:
13+
build-docs:
14+
runs-on: ubuntu-latest
15+
permissions:
16+
contents: read
17+
steps:
18+
- uses: actions/checkout@v4
19+
- name: Configure GitHub Pages
20+
uses: actions/configure-pages@v5
21+
- uses: actions/setup-python@v5
22+
with:
23+
python-version: "3.12"
24+
- name: Install docs extras
25+
run: |
26+
python -m pip install --upgrade pip
27+
python -m pip install .[docs]
28+
- name: Check generated files
29+
run: |
30+
python tools/export_notebooks.py --check
31+
python tools/gen_readme.py --check
32+
- name: Build docs
33+
run: mkdocs build --strict
34+
- name: Upload GitHub Pages artifact
35+
uses: actions/upload-pages-artifact@v4
36+
with:
37+
path: site
38+
39+
deploy-docs:
40+
runs-on: ubuntu-latest
41+
needs: build-docs
42+
permissions:
43+
pages: write
44+
id-token: write
45+
environment:
46+
name: github-pages
47+
url: ${{ steps.deployment.outputs.page_url }}
48+
steps:
49+
- name: Deploy to GitHub Pages
50+
id: deployment
51+
uses: actions/deploy-pages@v4

‎CHANGELOG.md‎

Lines changed: 127 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,127 @@
1+
# Changelog
2+
3+
## 0.1.4 - 2026-03-15
4+
5+
### Added
6+
7+
- `LookupResult.transfer_depth`, which records how many transfer steps were
8+
involved in the returned numeric value.
9+
- Explicit nested-policy safeguards for `LinearTransfer` via:
10+
- `fit_sources`
11+
- `fit_max_depth`
12+
- `prediction_sources`
13+
- `prediction_max_depth`
14+
- Regression tests covering generic-policy cycles, wrapper-policy cycles,
15+
conservative nested-fit defaults, and explicit opt-in for deeper nested
16+
linear workflows.
17+
18+
### Changed
19+
20+
- Nested policy-backed linear transfers are now guarded in two phases:
21+
conservative defaults are used for fit training, while one additional nested
22+
completion step remains allowed at prediction time.
23+
- Linear-transfer fitting now distinguishes direct predictor values from nested
24+
policy-derived predictor values.
25+
- Cycle detection now tracks both generic policies and wrapper policies using a
26+
context-local activation stack, so recursion through freshly materialized
27+
wrapper policies is detected reliably and safely.
28+
- Radii and X–H convenience helpers now resolve through wrapper-aware cycle
29+
tracking rather than materializing a fresh generic policy for each public
30+
lookup call.
31+
32+
### Documentation
33+
34+
- Expanded the transfer and policy docs to explain nested-policy safeguards,
35+
`transfer_depth`, and cycle detection.
36+
- Added guidance on when chained correlations are scientifically reasonable and
37+
how to opt in deliberately when broader fit training is desired.
38+
39+
## 0.1.3 - 2026-03-15
40+
41+
### Added
42+
43+
- Support for using generic policies and wrapper policies as transfer sources in
44+
`SubstitutionTransfer` and `LinearTransfer`.
45+
- Public `atomref.xh` module docs and examples for policy-backed predictor
46+
workflows.
47+
48+
### Changed
49+
50+
- `LinearTransfer` now treats predictors as **sources** rather than only raw
51+
datasets, while still keeping the current runtime to one predictor at a time.
52+
- Generic policy resolution now supports blocked element keys, which is used by
53+
the X–H helper to prevent invalid `H` parent-element lookups.
54+
- Transfer results now preserve nested-policy provenance through
55+
`resolved_from` and explanatory notes when a policy source is involved.
56+
57+
## 0.1.2 - 2026-03-15
58+
59+
### Added
60+
61+
- New `xh_bond_length` quantity family.
62+
- Packaged provisional X–H dataset `csd_legacy_xh_cno` with ConQuest/CSD
63+
hydrogen-normalisation targets for `C`, `N`, and `O`.
64+
- New `atomref.xh` convenience layer with `XHPolicy`, `DEFAULT_XH_POLICY`, set
65+
listing helpers, and X–H lookup helpers.
66+
67+
### Documentation
68+
69+
- Added X–H dataset and API pages.
70+
- Documented the provisional scope of X–H support in `0.1.x` and the planned
71+
broader follow-up in `0.2.x`.
72+
73+
## 0.1.1 - 2026-03-15
74+
75+
### Added
76+
77+
- Public generic lookup helpers `lookup_value(...)` and `get_value(...)`.
78+
- Tests for alias normalization, immutable metadata, non-finite-value rejection,
79+
collision detection, and explicit placeholder notes.
80+
81+
### Changed
82+
83+
- Registry metadata returned by `get_dataset_info(...)` is now frozen so callers
84+
cannot mutate the cached registry state.
85+
- Dataset-alias resolution now normalizes Unicode and dash variants more
86+
robustly.
87+
- Custom-set construction and policy configuration now reject normalized-key
88+
collisions and non-finite numeric values.
89+
- Radii-specific wrappers now reject negative override and fallback values.
90+
- Base and substitution lookups now emit explicit placeholder notes when the
91+
returned numeric value is a dataset placeholder.
92+
- `LinearTransfer` now validates empty-predictor and invalid-`min_points`
93+
configurations eagerly.
94+
- The docs now explain the distinction between quantity, domain, dataset, and
95+
policy, and clarify that the current runtime supports only the `element`
96+
domain.
97+
98+
## 0.1.0 - 2026-03-15
99+
100+
First public release.
101+
102+
### Added
103+
104+
- Packaged element metadata and curated radii tables.
105+
- Quantity-aware registry metadata that separates operational lookup quantity
106+
from scientific classification and dataset usage role.
107+
- Provenance-aware radii policies with deterministic resolution order.
108+
- Substitution and linear-transfer support for restoring missing values from
109+
curated support datasets.
110+
- Public helpers for inspecting quantities, dataset metadata, and packaged
111+
built-in sets.
112+
- Runnable notebooks together with generated Markdown notebook pages in the
113+
documentation.
114+
- Validation and maintenance tools for registry checks, notebook export, README
115+
generation, and distribution-artifact inspection.
116+
117+
### Documentation
118+
119+
- Expanded dataset guides with citations and selection-oriented descriptions.
120+
- Added module-level API pages and notebook walkthroughs.
121+
- Added developer-facing curation and tooling notes.
122+
123+
### Packaging
124+
125+
- Built and validated wheel and source-distribution artifacts.
126+
- Added CI coverage for linting, tests, docs builds, notebook sync, and
127+
distribution checks.

0 commit comments

Comments
 (0)