daftar 0.3.1__tar.gz → 0.3.3__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.
- {daftar-0.3.1 → daftar-0.3.3}/CHANGELOG.md +47 -0
- daftar-0.3.3/INSTALL.md +158 -0
- {daftar-0.3.1 → daftar-0.3.3}/MANIFEST.in +4 -2
- {daftar-0.3.1/src/daftar.egg-info → daftar-0.3.3}/PKG-INFO +87 -103
- daftar-0.3.3/PUBLISHING.md +122 -0
- {daftar-0.3.1 → daftar-0.3.3}/README.md +86 -102
- daftar-0.3.3/ROADMAP.md +168 -0
- daftar-0.3.3/TESTING.md +142 -0
- daftar-0.3.3/TROUBLESHOOTING.md +234 -0
- {daftar-0.3.1 → daftar-0.3.3}/pyproject.toml +1 -1
- daftar-0.3.3/src/daftar/__version__.py +1 -0
- {daftar-0.3.1 → daftar-0.3.3}/src/daftar/adapters/brian2_adapter.py +4 -73
- {daftar-0.3.1 → daftar-0.3.3/src/daftar.egg-info}/PKG-INFO +87 -103
- {daftar-0.3.1 → daftar-0.3.3}/src/daftar.egg-info/SOURCES.txt +2 -0
- {daftar-0.3.1 → daftar-0.3.3}/tests/test_adapters_live.py +71 -4
- daftar-0.3.1/PUBLISHING.md +0 -134
- daftar-0.3.1/ROADMAP.md +0 -207
- daftar-0.3.1/TROUBLESHOOTING.md +0 -347
- daftar-0.3.1/src/daftar/__version__.py +0 -1
- {daftar-0.3.1 → daftar-0.3.3}/LICENSE +0 -0
- {daftar-0.3.1 → daftar-0.3.3}/examples/adapter_usage.py +0 -0
- {daftar-0.3.1 → daftar-0.3.3}/examples/daftar_in_notebooks.ipynb +0 -0
- {daftar-0.3.1 → daftar-0.3.3}/examples/demo_end_to_end.py +0 -0
- {daftar-0.3.1 → daftar-0.3.3}/setup.cfg +0 -0
- {daftar-0.3.1 → daftar-0.3.3}/src/daftar/__init__.py +0 -0
- {daftar-0.3.1 → daftar-0.3.3}/src/daftar/adapters/__init__.py +0 -0
- {daftar-0.3.1 → daftar-0.3.3}/src/daftar/adapters/base.py +0 -0
- {daftar-0.3.1 → daftar-0.3.3}/src/daftar/adapters/cpm_adapter.py +0 -0
- {daftar-0.3.1 → daftar-0.3.3}/src/daftar/adapters/jaxley_adapter.py +0 -0
- {daftar-0.3.1 → daftar-0.3.3}/src/daftar/adapters/meltingpot_adapter.py +0 -0
- {daftar-0.3.1 → daftar-0.3.3}/src/daftar/capture.py +0 -0
- {daftar-0.3.1 → daftar-0.3.3}/src/daftar/cli.py +0 -0
- {daftar-0.3.1 → daftar-0.3.3}/src/daftar/diff.py +0 -0
- {daftar-0.3.1 → daftar-0.3.3}/src/daftar/manifest.py +0 -0
- {daftar-0.3.1 → daftar-0.3.3}/src/daftar/notebook.py +0 -0
- {daftar-0.3.1 → daftar-0.3.3}/src/daftar/run.py +0 -0
- {daftar-0.3.1 → daftar-0.3.3}/src/daftar/store.py +0 -0
- {daftar-0.3.1 → daftar-0.3.3}/src/daftar/sweep.py +0 -0
- {daftar-0.3.1 → daftar-0.3.3}/src/daftar.egg-info/dependency_links.txt +0 -0
- {daftar-0.3.1 → daftar-0.3.3}/src/daftar.egg-info/entry_points.txt +0 -0
- {daftar-0.3.1 → daftar-0.3.3}/src/daftar.egg-info/requires.txt +0 -0
- {daftar-0.3.1 → daftar-0.3.3}/src/daftar.egg-info/top_level.txt +0 -0
- {daftar-0.3.1 → daftar-0.3.3}/tests/test_core.py +0 -0
- {daftar-0.3.1 → daftar-0.3.3}/tests/test_notebook.py +0 -0
|
@@ -1,5 +1,52 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## 0.3.3 — documentation and cleanup
|
|
4
|
+
|
|
5
|
+
No behaviour changes. The four adapters, notebook support and the CLI are all
|
|
6
|
+
verified working; this release makes the documentation match.
|
|
7
|
+
|
|
8
|
+
**Documentation restructured** around the four things a user actually needs to
|
|
9
|
+
do, each in its own file rather than scattered across a README:
|
|
10
|
+
|
|
11
|
+
* `INSTALL.md` — installing daftar, and the per-adapter environment
|
|
12
|
+
requirements. Including the honest part: **the four target frameworks cannot
|
|
13
|
+
currently share one interpreter**, and the two-environment split that works.
|
|
14
|
+
* `TESTING.md` — the three test suites, what each covers, and how to read a
|
|
15
|
+
skip. Skips have three distinct meanings and only one of them is ordinary.
|
|
16
|
+
* `PUBLISHING.md` — the release sequence, trimmed to the steps that matter.
|
|
17
|
+
* `TROUBLESHOOTING.md` — reorganised around what is currently open versus
|
|
18
|
+
already fixed upstream.
|
|
19
|
+
* `ROADMAP.md` — updated for the shipped state.
|
|
20
|
+
|
|
21
|
+
**Removed `diagnose_jaxley.py`.** jaxley 0.14.0 fixed the `jnp.clip(a_max=...)`
|
|
22
|
+
incompatibility, so the script has nothing left to diagnose. `daftar doctor`
|
|
23
|
+
covers the general case.
|
|
24
|
+
|
|
25
|
+
**Removed the unused Brian2 log-capture path.** `capture_methods` and
|
|
26
|
+
`_MethodCapture` were superseded by `resolve_method`, which reproduces Brian2's
|
|
27
|
+
integration-method selection directly and is immune to its caching. Nothing
|
|
28
|
+
called them and no test covered them; unused code that reads private framework
|
|
29
|
+
internals is a maintenance liability, not an escape hatch.
|
|
30
|
+
|
|
31
|
+
## 0.3.2
|
|
32
|
+
|
|
33
|
+
**cpm live tests now skip with an explanation instead of failing** when cpm and
|
|
34
|
+
SciPy disagree. cpm 0.25.6 passes `disp=` to `fmin_l_bfgs_b`, which SciPy
|
|
35
|
+
removed in 1.18.0, so cpm imports cleanly and raises the moment you fit
|
|
36
|
+
anything.
|
|
37
|
+
|
|
38
|
+
This is the third framework/dependency clash across four adapters — jaxley
|
|
39
|
+
against JAX, brian2 against NumPy, cpm against SciPy — so the preflight logic is
|
|
40
|
+
now a single `_require_working(name, probe)` helper rather than one bespoke
|
|
41
|
+
function per adapter. The rule it encodes: skip for a clash we recognise and can
|
|
42
|
+
explain, fail loudly for anything we do not, because an unrecognised error might
|
|
43
|
+
be our bug and a silent skip would hide it.
|
|
44
|
+
|
|
45
|
+
**Runtime checks are reported separately from import checks.** `daftar doctor`
|
|
46
|
+
answers "does it import", which is fast and usually enough. It is not the same
|
|
47
|
+
question as "does it work": cpm reports `ok` under SciPy 1.18 and then fails on
|
|
48
|
+
the first fit. The adapter status test now prints both.
|
|
49
|
+
|
|
3
50
|
## 0.3.1
|
|
4
51
|
|
|
5
52
|
**A framework that is installed but broken is no longer reported as absent.**
|
daftar-0.3.3/INSTALL.md
ADDED
|
@@ -0,0 +1,158 @@
|
|
|
1
|
+
# Installing daftar
|
|
2
|
+
|
|
3
|
+
## Just the tool
|
|
4
|
+
|
|
5
|
+
```bash
|
|
6
|
+
pip install daftar
|
|
7
|
+
```
|
|
8
|
+
|
|
9
|
+
That is everything. daftar has **zero runtime dependencies** and works on Python
|
|
10
|
+
3.10 or newer. It needs no account, no server, and makes no network call.
|
|
11
|
+
|
|
12
|
+
Verify:
|
|
13
|
+
|
|
14
|
+
```bash
|
|
15
|
+
python -c "import daftar; print(daftar.__version__)"
|
|
16
|
+
daftar doctor
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
---
|
|
20
|
+
|
|
21
|
+
## With the framework adapters
|
|
22
|
+
|
|
23
|
+
Here the honest answer is more complicated than a single command, and it is
|
|
24
|
+
worth understanding why before you start.
|
|
25
|
+
|
|
26
|
+
**The four target frameworks cannot currently share one environment.** Each pins
|
|
27
|
+
its dependencies loosely, and their dependencies remove APIs on schedules the
|
|
28
|
+
frameworks do not track. As of this writing:
|
|
29
|
+
|
|
30
|
+
| Framework | Constraint | Consequence |
|
|
31
|
+
|---|---|---|
|
|
32
|
+
| brian2 ≥ 2.10 | requires **Python ≥ 3.12** | earlier brian2 releases call `ndarray.ptp`, removed in NumPy 2.0 |
|
|
33
|
+
| cpm-toolbox 0.25.6 | needs **scipy < 1.18** | passes `disp=` to `fmin_l_bfgs_b`, removed in SciPy 1.18.0 |
|
|
34
|
+
| dm-meltingpot | needs **dmlab2d**, narrow wheel coverage | weakest on macOS arm64; often needs Python 3.11 or a source build |
|
|
35
|
+
| jaxley ≥ 0.14 | fine on current JAX | 0.13.0 was broken; upgrade rather than pin |
|
|
36
|
+
|
|
37
|
+
This is not anyone's fault and it is not unusual. It is the normal condition of
|
|
38
|
+
a scientific Python environment, and it is a large part of why daftar records
|
|
39
|
+
`env.*` at all.
|
|
40
|
+
|
|
41
|
+
**Do not try to force all four into one environment.** Use two, and let the test
|
|
42
|
+
suite skip whatever is absent in each — both suites go green.
|
|
43
|
+
|
|
44
|
+
### Environment A — brian2, jaxley, cpm (Python 3.12)
|
|
45
|
+
|
|
46
|
+
```bash
|
|
47
|
+
conda create --name daftar312 python=3.12
|
|
48
|
+
conda activate daftar312
|
|
49
|
+
|
|
50
|
+
pip install daftar
|
|
51
|
+
pip install brian2 jaxley cpm-toolbox
|
|
52
|
+
pip install "scipy<1.18" # required by cpm-toolbox 0.25.6
|
|
53
|
+
pip install pytest ipython # for the test suite and notebook support
|
|
54
|
+
|
|
55
|
+
daftar doctor
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
Expect:
|
|
59
|
+
|
|
60
|
+
```
|
|
61
|
+
daftar 0.3.3
|
|
62
|
+
python 3.12.14 on Darwin arm64
|
|
63
|
+
|
|
64
|
+
brian2 ok
|
|
65
|
+
cpm ok
|
|
66
|
+
jaxley ok
|
|
67
|
+
meltingpot - not installed
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
### Environment B — meltingpot (Python 3.11)
|
|
71
|
+
|
|
72
|
+
```bash
|
|
73
|
+
conda create --name daftar311 python=3.11
|
|
74
|
+
conda activate daftar311
|
|
75
|
+
|
|
76
|
+
pip install daftar pytest
|
|
77
|
+
pip install dm-meltingpot # or install from a local clone, see below
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
If the wheel will not install on your platform, clone MeltingPot and install it
|
|
81
|
+
editable:
|
|
82
|
+
|
|
83
|
+
```bash
|
|
84
|
+
git clone https://github.com/google-deepmind/meltingpot.git
|
|
85
|
+
cd meltingpot && pip install -e .
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
Note the consequence: every manifest will then record
|
|
89
|
+
|
|
90
|
+
```
|
|
91
|
+
env.dm_meltingpot.source editable:file:///path/to/meltingpot
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
and `daftar replay` will warn that nobody else can fetch that path. That warning
|
|
95
|
+
is correct. If you are producing manifests for other people to act on, install a
|
|
96
|
+
release build rather than a working copy.
|
|
97
|
+
|
|
98
|
+
### All extras at once
|
|
99
|
+
|
|
100
|
+
The extras exist for convenience, but read the constraints above before using
|
|
101
|
+
`[all]`:
|
|
102
|
+
|
|
103
|
+
```bash
|
|
104
|
+
pip install "daftar[jaxley]"
|
|
105
|
+
pip install "daftar[cpm]"
|
|
106
|
+
pip install "daftar[brian2]"
|
|
107
|
+
pip install "daftar[meltingpot]"
|
|
108
|
+
pip install "daftar[all]" # will not resolve cleanly on one interpreter
|
|
109
|
+
pip install "daftar[dev]" # pytest, numpy, ipython
|
|
110
|
+
```
|
|
111
|
+
|
|
112
|
+
---
|
|
113
|
+
|
|
114
|
+
## For development
|
|
115
|
+
|
|
116
|
+
```bash
|
|
117
|
+
git clone https://github.com/aslansd/daftar.git
|
|
118
|
+
cd daftar
|
|
119
|
+
pip install -e ".[dev]"
|
|
120
|
+
pytest -q
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
See [TESTING.md](TESTING.md) for what the different suites cover and what a
|
|
124
|
+
skip means.
|
|
125
|
+
|
|
126
|
+
---
|
|
127
|
+
|
|
128
|
+
## Notebooks and Colab
|
|
129
|
+
|
|
130
|
+
Nothing extra is needed — `daftar.track()` detects IPython by itself. IPython is
|
|
131
|
+
never imported when running as a script, so there is no cost to non-notebook
|
|
132
|
+
users.
|
|
133
|
+
|
|
134
|
+
For the `%%daftar` cell magic:
|
|
135
|
+
|
|
136
|
+
```python
|
|
137
|
+
!pip install daftar
|
|
138
|
+
%load_ext daftar
|
|
139
|
+
```
|
|
140
|
+
|
|
141
|
+
On Colab this is the whole setup. See `examples/daftar_in_notebooks.ipynb`.
|
|
142
|
+
|
|
143
|
+
---
|
|
144
|
+
|
|
145
|
+
## Checking an installation
|
|
146
|
+
|
|
147
|
+
```bash
|
|
148
|
+
daftar doctor
|
|
149
|
+
```
|
|
150
|
+
|
|
151
|
+
Reports the interpreter, the daftar version, and every adapter as `ok`,
|
|
152
|
+
`not installed`, or **`BROKEN`** with the exception that caused it. Exits 1 if
|
|
153
|
+
anything is broken, so it is usable in CI.
|
|
154
|
+
|
|
155
|
+
**`ok` means the framework imports.** That is not the same as it working — cpm
|
|
156
|
+
under SciPy 1.18 imports cleanly and fails on the first fit. The live adapter
|
|
157
|
+
tests run a real workload and will tell you. See
|
|
158
|
+
[TROUBLESHOOTING.md](TROUBLESHOOTING.md) if something is `BROKEN`.
|
|
@@ -1,9 +1,11 @@
|
|
|
1
1
|
include LICENSE
|
|
2
2
|
include README.md
|
|
3
|
+
include INSTALL.md
|
|
4
|
+
include TESTING.md
|
|
3
5
|
include PUBLISHING.md
|
|
4
|
-
include CHANGELOG.md
|
|
5
|
-
include ROADMAP.md
|
|
6
6
|
include TROUBLESHOOTING.md
|
|
7
|
+
include ROADMAP.md
|
|
8
|
+
include CHANGELOG.md
|
|
7
9
|
recursive-include examples *.py
|
|
8
10
|
recursive-include examples *.ipynb
|
|
9
11
|
recursive-include tests *.py
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: daftar
|
|
3
|
-
Version: 0.3.
|
|
3
|
+
Version: 0.3.3
|
|
4
4
|
Summary: Record what produced each computational result: environment, code, parameters, seeds, inputs.
|
|
5
5
|
Author: Aslan Satary Dizaji
|
|
6
6
|
License-Expression: Apache-2.0
|
|
@@ -47,10 +47,10 @@ past run can be rebuilt.
|
|
|
47
47
|
|
|
48
48
|
Experiment trackers solved this for deep learning, where an experiment is
|
|
49
49
|
`model.fit()`. They do not help when the experiment is a Hodgkin–Huxley
|
|
50
|
-
simulation of 302 neurons, a hierarchical fit across 60 participants,
|
|
51
|
-
200-episode multi-agent sweep. Those runs have no epochs, no loss
|
|
52
|
-
checkpoints. They have parameter grids, solver tolerances, random
|
|
53
|
-
derived quantities.
|
|
50
|
+
simulation of 302 neurons, a hierarchical fit across 60 participants, a spiking
|
|
51
|
+
network, or a 200-episode multi-agent sweep. Those runs have no epochs, no loss
|
|
52
|
+
curves, and no checkpoints. They have parameter grids, solver tolerances, random
|
|
53
|
+
seeds, and derived quantities.
|
|
54
54
|
|
|
55
55
|
**No dependencies. Runs offline. No account, no server, no network call.**
|
|
56
56
|
|
|
@@ -58,6 +58,13 @@ derived quantities.
|
|
|
58
58
|
pip install daftar
|
|
59
59
|
```
|
|
60
60
|
|
|
61
|
+
Python 3.10+. Apache 2.0.
|
|
62
|
+
|
|
63
|
+
[PyPI](https://pypi.org/project/daftar/) · [INSTALL](INSTALL.md) ·
|
|
64
|
+
[TESTING](TESTING.md) · [PUBLISHING](PUBLISHING.md) ·
|
|
65
|
+
[TROUBLESHOOTING](TROUBLESHOOTING.md) · [ROADMAP](ROADMAP.md) ·
|
|
66
|
+
[CHANGELOG](CHANGELOG.md)
|
|
67
|
+
|
|
61
68
|
---
|
|
62
69
|
|
|
63
70
|
## The thirty-second version
|
|
@@ -106,10 +113,9 @@ platform to save and re-run a computational experiment.
|
|
|
106
113
|
Every one of those tools asked scientists to change how they work today in
|
|
107
114
|
exchange for a benefit arriving in three years. That trade never closes.
|
|
108
115
|
|
|
109
|
-
`daftar` inverts it. `diff` answers a question people ask weekly — *why is
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
the pitch.
|
|
116
|
+
`daftar` inverts it. `diff` answers a question people ask weekly — *why is this
|
|
117
|
+
number different from Tuesday's?* — and provenance arrives as a free side effect
|
|
118
|
+
of a tool they already wanted. Reproducibility is the by-product, not the pitch.
|
|
113
119
|
|
|
114
120
|
Three consequences of taking that seriously:
|
|
115
121
|
|
|
@@ -127,38 +133,31 @@ Three consequences of taking that seriously:
|
|
|
127
133
|
|
|
128
134
|
| Namespace | Contents |
|
|
129
135
|
|---|---|
|
|
130
|
-
| `code.*` | git commit, branch, dirty flag, **hash of uncommitted changes**, entrypoint, argv |
|
|
136
|
+
| `code.*` | git commit, branch, dirty flag, **hash of uncommitted changes**, entrypoint, argv; in notebooks, the **cell hash and session history hash** |
|
|
131
137
|
| `param.*` | everything you chose, including defaults you never passed |
|
|
132
138
|
| `seed.*` | seeds **applied** to `random`, numpy, torch, **Brian2's device RNG**; the JAX root key |
|
|
133
139
|
| `input.*` | sha256 and size of every declared input file or directory |
|
|
134
|
-
| `env.*` | interpreter, OS, versions
|
|
140
|
+
| `env.*` | interpreter, OS, package versions, **and where each package was installed from** |
|
|
135
141
|
| `result.*` | scalar outcomes worth comparing |
|
|
136
142
|
| `output.*` | sha256 of produced files |
|
|
137
143
|
| `cost.*` | wall clock, host, cpu count |
|
|
138
144
|
|
|
139
|
-
|
|
145
|
+
Three of these are less obvious than they look.
|
|
140
146
|
|
|
141
147
|
**Seeds are applied, not merely recorded.** A tool that only writes down the
|
|
142
148
|
seed is close to useless: if the code seeded itself from the clock, recording
|
|
143
149
|
that fact tells you the run is irreproducible but does nothing to fix it.
|
|
144
|
-
`track(seed=...)` sets every RNG it can reach
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
**A version string is not an identity.** jaxley 0.13.0 on PyPI
|
|
149
|
-
current JAX; jaxley `main`
|
|
150
|
-
`env.jaxley = 0.13.0` would call those two environments identical when one
|
|
151
|
-
and one does not. daftar reads PEP 610 `direct_url.json` and adds
|
|
152
|
-
`env.<pkg>.source` for anything not installed from an index
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
env.jaxley 0.13.0
|
|
156
|
-
env.jaxley.source git+https://github.com/jaxleyverse/jaxley.git#2638cca2665e
|
|
157
|
-
```
|
|
158
|
-
|
|
159
|
-
Index installs record nothing, which is the right default: absence means "from
|
|
160
|
-
PyPI". `daftar replay` then emits a `pip install` line that actually works,
|
|
161
|
-
pinning index packages by version and VCS packages by URL and commit.
|
|
150
|
+
`track(seed=...)` sets every RNG it can reach — including Brian2's device RNG,
|
|
151
|
+
which numpy seeding does not touch — then records what it set. If you pass no
|
|
152
|
+
seed, one is generated, applied, and recorded.
|
|
153
|
+
|
|
154
|
+
**A version string is not an identity.** jaxley 0.13.0 on PyPI was broken with
|
|
155
|
+
current JAX; jaxley `main` fixed it and still called itself 0.13.0. Recording
|
|
156
|
+
only `env.jaxley = 0.13.0` would call those two environments identical when one
|
|
157
|
+
works and one does not. daftar reads PEP 610 `direct_url.json` and adds
|
|
158
|
+
`env.<pkg>.source` for anything not installed from an index. `daftar replay`
|
|
159
|
+
then emits a `pip install` line that actually works, pinning index packages by
|
|
160
|
+
version and VCS packages by URL and commit.
|
|
162
161
|
|
|
163
162
|
**Dirty working trees get their diff hashed.** "Dirty" alone tells you there
|
|
164
163
|
were uncommitted edits but not whether they were the *same* edits. Hashing the
|
|
@@ -167,7 +166,7 @@ case during a debugging session.
|
|
|
167
166
|
|
|
168
167
|
---
|
|
169
168
|
|
|
170
|
-
##
|
|
169
|
+
## Commands
|
|
171
170
|
|
|
172
171
|
```bash
|
|
173
172
|
daftar list # what has been run
|
|
@@ -176,11 +175,12 @@ daftar diff r-4f21ab r-88c07e # what changed, and whether it mattered
|
|
|
176
175
|
daftar vary -l my-sweep # which fields differ across many runs
|
|
177
176
|
daftar replay r-4f21ab # what it would take to reproduce this
|
|
178
177
|
daftar export r-4f21ab -o run.zip
|
|
179
|
-
daftar doctor
|
|
178
|
+
daftar doctor # which adapters work here, and why not
|
|
180
179
|
```
|
|
181
180
|
|
|
182
181
|
`diff` exits 0 if the second run reproduces the first and 1 otherwise, so it
|
|
183
|
-
works in CI as a regression check on your own results.
|
|
182
|
+
works in CI as a regression check on your own results. `doctor` exits 1 if any
|
|
183
|
+
adapter's framework is installed but broken.
|
|
184
184
|
|
|
185
185
|
### Verdicts
|
|
186
186
|
|
|
@@ -199,7 +199,7 @@ combination implies:
|
|
|
199
199
|
|
|
200
200
|
That fourth verdict is the valuable one. An unseeded RNG buried three libraries
|
|
201
201
|
deep can survive for years because nobody ever compares two runs precisely
|
|
202
|
-
enough to notice.
|
|
202
|
+
enough to notice. daftar reports it as a finding rather than a glitch.
|
|
203
203
|
|
|
204
204
|
---
|
|
205
205
|
|
|
@@ -220,46 +220,6 @@ point 3 of 40 keeps the first two results.
|
|
|
220
220
|
|
|
221
221
|
---
|
|
222
222
|
|
|
223
|
-
## Replay
|
|
224
|
-
|
|
225
|
-
`daftar replay` prints a plan, and deliberately does **not** execute
|
|
226
|
-
anything. Re-running arbitrary recorded code would mean this package executes
|
|
227
|
-
whatever a manifest tells it to, and it still could not restore your CUDA
|
|
228
|
-
driver. What it does honestly is state the target state, check the current state
|
|
229
|
-
against it, and list every discrepancy:
|
|
230
|
-
|
|
231
|
-
```
|
|
232
|
-
Replay plan for r-4f21ab
|
|
233
|
-
|
|
234
|
-
entrypoint sim/celegans_hh.py::run_network
|
|
235
|
-
commit 9c1d0ae
|
|
236
|
-
seed 42
|
|
237
|
-
|
|
238
|
-
BLOCKERS -- this run cannot be reproduced as recorded:
|
|
239
|
-
- input file changed since the run: data/connectome.csv
|
|
240
|
-
(was a7f39b21, now 3e0c77af)
|
|
241
|
-
|
|
242
|
-
To reproduce:
|
|
243
|
-
git checkout 9c1d0ae
|
|
244
|
-
pip install numpy==2.4.6 "jaxley @ git+https://github.com/jaxleyverse/jaxley.git@2638cca"
|
|
245
|
-
```
|
|
246
|
-
|
|
247
|
-
Packages installed from a local path or in editable mode are listed as comments
|
|
248
|
-
rather than requirements, and raise a warning: nobody else can fetch
|
|
249
|
-
`file:///Users/you/Downloads/thing`, and a version pin would not reproduce it.
|
|
250
|
-
|
|
251
|
-
---
|
|
252
|
-
|
|
253
|
-
## Export
|
|
254
|
-
|
|
255
|
-
`daftar export` writes a zip containing `README.md`, `manifest.json`,
|
|
256
|
-
`fields.tsv`, and the referenced input and output files. The README is generated
|
|
257
|
-
in plain English at the archive root, so a successor learns what they are
|
|
258
|
-
looking at without installing anything. A bundle that needs our tool to be
|
|
259
|
-
understood defeats its own purpose.
|
|
260
|
-
|
|
261
|
-
---
|
|
262
|
-
|
|
263
223
|
## Notebooks and Colab
|
|
264
224
|
|
|
265
225
|
Notebooks are the hardest case: the git commit means little when cells ran in an
|
|
@@ -305,6 +265,46 @@ See `examples/daftar_in_notebooks.ipynb`, which runs on Colab.
|
|
|
305
265
|
|
|
306
266
|
---
|
|
307
267
|
|
|
268
|
+
## Replay
|
|
269
|
+
|
|
270
|
+
`daftar replay` prints a plan, and deliberately does **not** execute anything.
|
|
271
|
+
Re-running arbitrary recorded code would mean this package executes whatever a
|
|
272
|
+
manifest tells it to, and it still could not restore your CUDA driver. What it
|
|
273
|
+
does honestly is state the target state, check the current state against it, and
|
|
274
|
+
list every discrepancy:
|
|
275
|
+
|
|
276
|
+
```
|
|
277
|
+
Replay plan for r-4f21ab
|
|
278
|
+
|
|
279
|
+
entrypoint sim/celegans_hh.py::run_network
|
|
280
|
+
commit 9c1d0ae
|
|
281
|
+
seed 42
|
|
282
|
+
|
|
283
|
+
BLOCKERS -- this run cannot be reproduced as recorded:
|
|
284
|
+
- input file changed since the run: data/connectome.csv
|
|
285
|
+
(was a7f39b21, now 3e0c77af)
|
|
286
|
+
|
|
287
|
+
To reproduce:
|
|
288
|
+
git checkout 9c1d0ae
|
|
289
|
+
pip install numpy==2.4.6 "jaxley @ git+https://github.com/jaxleyverse/jaxley.git@2638cca"
|
|
290
|
+
```
|
|
291
|
+
|
|
292
|
+
Packages installed from a local path or in editable mode are listed as comments
|
|
293
|
+
rather than requirements, and raise a warning: nobody else can fetch
|
|
294
|
+
`file:///Users/you/Downloads/thing`, and a version pin would not reproduce it.
|
|
295
|
+
|
|
296
|
+
---
|
|
297
|
+
|
|
298
|
+
## Export
|
|
299
|
+
|
|
300
|
+
`daftar export` writes a zip containing `README.md`, `manifest.json`,
|
|
301
|
+
`fields.tsv`, and the referenced input and output files — plus `cell.py` for
|
|
302
|
+
notebook runs. The README is generated in plain English at the archive root, so
|
|
303
|
+
a successor learns what they are looking at without installing anything. A
|
|
304
|
+
bundle that needs our tool to be understood defeats its own purpose.
|
|
305
|
+
|
|
306
|
+
---
|
|
307
|
+
|
|
308
308
|
## Framework adapters
|
|
309
309
|
|
|
310
310
|
The core tracks any Python function. An adapter earns its existence only by
|
|
@@ -313,26 +313,26 @@ knowing something a generic tracker cannot infer.
|
|
|
313
313
|
| Adapter | Records what you'd otherwise lose |
|
|
314
314
|
|---|---|
|
|
315
315
|
| `jaxley` | morphology (compartments, branches, channels, synapses), `jx.integrate` defaults you never passed, `jax_enable_x64`, backend |
|
|
316
|
-
| `cpm` | parameter **bounds and priors
|
|
317
|
-
| `brian2` | **the integration method Brian2 actually chose**
|
|
316
|
+
| `cpm` | parameter **bounds and priors** (resolved to the scipy distribution and its arguments), estimator and its scipy settings, restart counts and the initial guesses themselves, per-participant convergence, cohort hash |
|
|
317
|
+
| `brian2` | **the integration method Brian2 actually chose** — its default is a candidate list and the winner is stored nowhere — plus resolved `codegen.target`, network schedule, equation hashes, realised synapse counts |
|
|
318
318
|
| `meltingpot` | resolved substrate ConfigDict hash, roles, episode-length cap, pinned bot checkpoints, per-player returns and Gini |
|
|
319
319
|
|
|
320
|
-
All three are verified against live installs by `tests/test_adapters_live.py`,
|
|
321
|
-
which runs real workloads and skips cleanly when a framework is absent.
|
|
322
|
-
|
|
323
320
|
```python
|
|
324
|
-
from daftar.adapters import
|
|
321
|
+
from daftar.adapters import brian2 as b2a
|
|
325
322
|
|
|
326
|
-
with daftar.track("
|
|
327
|
-
|
|
323
|
+
with daftar.track("balanced-net", seed=42) as run:
|
|
324
|
+
b2a.run_network(net, 1*second, run)
|
|
328
325
|
```
|
|
329
326
|
|
|
330
|
-
Adapters never import their framework at module load, so `import daftar`
|
|
331
|
-
|
|
332
|
-
|
|
333
|
-
|
|
327
|
+
Adapters never import their framework at module load, so `import daftar` works
|
|
328
|
+
with none of them installed. Every probe is best-effort: a provenance tool that
|
|
329
|
+
crashes a four-hour simulation because a framework renamed an attribute has done
|
|
330
|
+
far more harm than the missing field was worth.
|
|
334
331
|
|
|
335
|
-
|
|
332
|
+
All four are verified against live installs by `tests/test_adapters_live.py`.
|
|
333
|
+
See `examples/adapter_usage.py` for the pattern for each, and
|
|
334
|
+
[INSTALL.md](INSTALL.md) for which environment each needs — they do not all fit
|
|
335
|
+
in one.
|
|
336
336
|
|
|
337
337
|
### Why not Concordia
|
|
338
338
|
|
|
@@ -360,22 +360,6 @@ python examples/demo_end_to_end.py
|
|
|
360
360
|
No frameworks needed. Walks through a clean reproduction, a deliberate parameter
|
|
361
361
|
change, a genuine nondeterminism catch, a sweep, a replay plan, and an export.
|
|
362
362
|
|
|
363
|
-
## Development
|
|
364
|
-
|
|
365
|
-
```bash
|
|
366
|
-
pip install -e ".[dev]"
|
|
367
|
-
pytest -q # core suite, no frameworks needed
|
|
368
|
-
|
|
369
|
-
pip install -e ".[all]" # jaxley, cpm-toolbox, dm-meltingpot
|
|
370
|
-
pytest tests/test_adapters_live.py -v # adapters against real frameworks
|
|
371
|
-
```
|
|
372
|
-
|
|
373
|
-
Adapters fail *silently by design* -- `safe()` turns a renamed attribute into
|
|
374
|
-
`<unavailable>` rather than crashing a four-hour simulation -- so adapter rot
|
|
375
|
-
looks fine until someone reads a manifest. Re-run the live suite after every
|
|
376
|
-
upgrade of a target framework, not only at release. See `TROUBLESHOOTING.md`
|
|
377
|
-
if a framework will not install.
|
|
378
|
-
|
|
379
363
|
## Licence
|
|
380
364
|
|
|
381
365
|
Apache 2.0.
|
|
@@ -0,0 +1,122 @@
|
|
|
1
|
+
# Publishing daftar
|
|
2
|
+
|
|
3
|
+
## The release, start to finish
|
|
4
|
+
|
|
5
|
+
```bash
|
|
6
|
+
conda activate daftar312 # or whichever env has build tooling
|
|
7
|
+
pip install build twine
|
|
8
|
+
```
|
|
9
|
+
|
|
10
|
+
**1. Bump the version in two places.** They must match or the build is
|
|
11
|
+
confusing later:
|
|
12
|
+
|
|
13
|
+
```bash
|
|
14
|
+
# src/daftar/__version__.py
|
|
15
|
+
__version__ = "0.3.4"
|
|
16
|
+
# pyproject.toml
|
|
17
|
+
version = "0.3.4"
|
|
18
|
+
```
|
|
19
|
+
|
|
20
|
+
**2. Write the changelog entry first, not last.** If you cannot describe the
|
|
21
|
+
change in a paragraph that says why it matters, the change is probably not
|
|
22
|
+
finished.
|
|
23
|
+
|
|
24
|
+
**3. Verify.**
|
|
25
|
+
|
|
26
|
+
```bash
|
|
27
|
+
pytest -q # 64 passed, 6 skipped minimum
|
|
28
|
+
pytest tests/test_adapters_live.py -v # in each environment
|
|
29
|
+
python examples/demo_end_to_end.py
|
|
30
|
+
daftar doctor
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
**4. Build and check.**
|
|
34
|
+
|
|
35
|
+
```bash
|
|
36
|
+
rm -rf dist build src/*.egg-info
|
|
37
|
+
python -m build
|
|
38
|
+
python -m twine check dist/*
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
**5. Test the artifact, not the source tree.** This catches packaging mistakes
|
|
42
|
+
the test suite cannot see — a module missing from the wheel, a data file not in
|
|
43
|
+
`MANIFEST.in`:
|
|
44
|
+
|
|
45
|
+
```bash
|
|
46
|
+
python -m venv /tmp/check
|
|
47
|
+
/tmp/check/bin/pip install dist/daftar-*.whl
|
|
48
|
+
/tmp/check/bin/python -c "import daftar; print(daftar.__version__)"
|
|
49
|
+
/tmp/check/bin/daftar doctor
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
**6. Upload.**
|
|
53
|
+
|
|
54
|
+
```bash
|
|
55
|
+
python -m twine upload dist/*
|
|
56
|
+
git tag v0.3.4 && git push --tags
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
**7. Confirm.** pip caches the index page and PyPI's CDN takes a minute or two,
|
|
60
|
+
so an immediate `pip install -U daftar` will often show the old version:
|
|
61
|
+
|
|
62
|
+
```bash
|
|
63
|
+
pip install --no-cache-dir -U daftar
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
---
|
|
67
|
+
|
|
68
|
+
## Things that have cost time before
|
|
69
|
+
|
|
70
|
+
**A version number can never be reused**, not even after deleting the release.
|
|
71
|
+
If 0.3.4 turns out wrong, ship 0.3.5. Do not delete and retry — 0.1.0 is
|
|
72
|
+
permanently burned this way.
|
|
73
|
+
|
|
74
|
+
**`pip install --no-cache-dir`** when verifying. Without it you will see the
|
|
75
|
+
previous version and conclude the upload failed.
|
|
76
|
+
|
|
77
|
+
**Use an API token, not a password.** PyPI account settings → API tokens. Scope
|
|
78
|
+
it to the project after the first upload. Twine 7 prompts for the token
|
|
79
|
+
directly, so you do not type `__token__` as a username.
|
|
80
|
+
|
|
81
|
+
To avoid re-pasting, put it in `~/.pypirc` (mode 600):
|
|
82
|
+
|
|
83
|
+
```ini
|
|
84
|
+
[distutils]
|
|
85
|
+
index-servers = pypi
|
|
86
|
+
|
|
87
|
+
[pypi]
|
|
88
|
+
username = __token__
|
|
89
|
+
password = pypi-AgEIcHlwaS5vcmc...
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
**TestPyPI is a separate service** with separate accounts and separate tokens. A
|
|
93
|
+
PyPI token there returns a bare `403 Forbidden`. It is rarely worth the detour:
|
|
94
|
+
`twine check` plus the clean-venv install in step 5 covers what a rehearsal
|
|
95
|
+
would tell you.
|
|
96
|
+
|
|
97
|
+
---
|
|
98
|
+
|
|
99
|
+
## On the licence
|
|
100
|
+
|
|
101
|
+
`LICENSE` contains the full Apache-2.0 text and `pyproject.toml` declares
|
|
102
|
+
`license = "Apache-2.0"` as an SPDX expression. This is not bookkeeping. The
|
|
103
|
+
strategy rests on publishing freely available source code, which has generally
|
|
104
|
+
been treated as "information and informational materials". A public repository
|
|
105
|
+
with a permissive licence and a licence file present is a different legal object
|
|
106
|
+
from a private or licence-gated artifact. Keep it that way.
|
|
107
|
+
|
|
108
|
+
---
|
|
109
|
+
|
|
110
|
+
## Before announcing a release publicly
|
|
111
|
+
|
|
112
|
+
- [ ] `pytest -q` green
|
|
113
|
+
- [ ] live adapter suite green in both environments
|
|
114
|
+
- [ ] `python examples/demo_end_to_end.py` runs on a fresh clone
|
|
115
|
+
- [ ] wheel installed into a clean venv and imported
|
|
116
|
+
- [ ] README renders correctly on the live PyPI page
|
|
117
|
+
- [ ] **daftar used on your own work, unmodified, for a month**
|
|
118
|
+
- [ ] `git tag && git push --tags`
|
|
119
|
+
|
|
120
|
+
The second-to-last item is the one that matters and the only one still open. It
|
|
121
|
+
is the real test of whether the API is unobtrusive enough that you keep using it
|
|
122
|
+
when nobody is watching. Do it before the announcement, not after.
|