daftar 0.3.2__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.
Files changed (44) hide show
  1. {daftar-0.3.2 → daftar-0.3.3}/CHANGELOG.md +28 -0
  2. daftar-0.3.3/INSTALL.md +158 -0
  3. {daftar-0.3.2 → daftar-0.3.3}/MANIFEST.in +4 -2
  4. {daftar-0.3.2/src/daftar.egg-info → daftar-0.3.3}/PKG-INFO +87 -103
  5. daftar-0.3.3/PUBLISHING.md +122 -0
  6. {daftar-0.3.2 → daftar-0.3.3}/README.md +86 -102
  7. daftar-0.3.3/ROADMAP.md +168 -0
  8. daftar-0.3.3/TESTING.md +142 -0
  9. daftar-0.3.3/TROUBLESHOOTING.md +234 -0
  10. {daftar-0.3.2 → daftar-0.3.3}/pyproject.toml +1 -1
  11. daftar-0.3.3/src/daftar/__version__.py +1 -0
  12. {daftar-0.3.2 → daftar-0.3.3}/src/daftar/adapters/brian2_adapter.py +4 -73
  13. {daftar-0.3.2 → daftar-0.3.3/src/daftar.egg-info}/PKG-INFO +87 -103
  14. {daftar-0.3.2 → daftar-0.3.3}/src/daftar.egg-info/SOURCES.txt +2 -0
  15. daftar-0.3.2/PUBLISHING.md +0 -134
  16. daftar-0.3.2/ROADMAP.md +0 -207
  17. daftar-0.3.2/TROUBLESHOOTING.md +0 -415
  18. daftar-0.3.2/src/daftar/__version__.py +0 -1
  19. {daftar-0.3.2 → daftar-0.3.3}/LICENSE +0 -0
  20. {daftar-0.3.2 → daftar-0.3.3}/examples/adapter_usage.py +0 -0
  21. {daftar-0.3.2 → daftar-0.3.3}/examples/daftar_in_notebooks.ipynb +0 -0
  22. {daftar-0.3.2 → daftar-0.3.3}/examples/demo_end_to_end.py +0 -0
  23. {daftar-0.3.2 → daftar-0.3.3}/setup.cfg +0 -0
  24. {daftar-0.3.2 → daftar-0.3.3}/src/daftar/__init__.py +0 -0
  25. {daftar-0.3.2 → daftar-0.3.3}/src/daftar/adapters/__init__.py +0 -0
  26. {daftar-0.3.2 → daftar-0.3.3}/src/daftar/adapters/base.py +0 -0
  27. {daftar-0.3.2 → daftar-0.3.3}/src/daftar/adapters/cpm_adapter.py +0 -0
  28. {daftar-0.3.2 → daftar-0.3.3}/src/daftar/adapters/jaxley_adapter.py +0 -0
  29. {daftar-0.3.2 → daftar-0.3.3}/src/daftar/adapters/meltingpot_adapter.py +0 -0
  30. {daftar-0.3.2 → daftar-0.3.3}/src/daftar/capture.py +0 -0
  31. {daftar-0.3.2 → daftar-0.3.3}/src/daftar/cli.py +0 -0
  32. {daftar-0.3.2 → daftar-0.3.3}/src/daftar/diff.py +0 -0
  33. {daftar-0.3.2 → daftar-0.3.3}/src/daftar/manifest.py +0 -0
  34. {daftar-0.3.2 → daftar-0.3.3}/src/daftar/notebook.py +0 -0
  35. {daftar-0.3.2 → daftar-0.3.3}/src/daftar/run.py +0 -0
  36. {daftar-0.3.2 → daftar-0.3.3}/src/daftar/store.py +0 -0
  37. {daftar-0.3.2 → daftar-0.3.3}/src/daftar/sweep.py +0 -0
  38. {daftar-0.3.2 → daftar-0.3.3}/src/daftar.egg-info/dependency_links.txt +0 -0
  39. {daftar-0.3.2 → daftar-0.3.3}/src/daftar.egg-info/entry_points.txt +0 -0
  40. {daftar-0.3.2 → daftar-0.3.3}/src/daftar.egg-info/requires.txt +0 -0
  41. {daftar-0.3.2 → daftar-0.3.3}/src/daftar.egg-info/top_level.txt +0 -0
  42. {daftar-0.3.2 → daftar-0.3.3}/tests/test_adapters_live.py +0 -0
  43. {daftar-0.3.2 → daftar-0.3.3}/tests/test_core.py +0 -0
  44. {daftar-0.3.2 → daftar-0.3.3}/tests/test_notebook.py +0 -0
@@ -1,5 +1,33 @@
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
+
3
31
  ## 0.3.2
4
32
 
5
33
  **cpm live tests now skip with an explanation instead of failing** when cpm and
@@ -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.2
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, or a
51
- 200-episode multi-agent sweep. Those runs have no epochs, no loss curves, and no
52
- checkpoints. They have parameter grids, solver tolerances, random seeds, and
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
- this number different from Tuesday's?* — and provenance arrives as a free side
111
- effect of a tool they already wanted. Reproducibility is the by-product, not
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 of packages the run imported, **and where each was installed from** |
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
- Two of these are less obvious than they look.
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, then records what it set. If you
145
- pass no seed, one is generated, applied, and recorded — an accidental seed that
146
- is written down is reproducible; a deliberate one that isn't, is not.
147
-
148
- **A version string is not an identity.** jaxley 0.13.0 on PyPI is broken with
149
- current JAX; jaxley `main` fixes it and still calls itself 0.13.0. Recording only
150
- `env.jaxley = 0.13.0` would call those two environments identical when one works
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
- ## The four commands
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 # which adapters work here, and why not
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. `daftar` reports it as a finding rather than a glitch.
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**, estimator and its scipy method/tolerance, per-participant convergence counts, cohort hash |
317
- | `brian2` | **the integration method Brian2 actually chose** (its default is a candidate list, and the winner is stored nowhere), resolved `codegen.target`, network schedule, equation hashes, realised synapse counts |
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 jaxley as jxa
321
+ from daftar.adapters import brian2 as b2a
325
322
 
326
- with daftar.track("hh-cell", seed=0) as run:
327
- v = jxa.integrate(cell, run, t_max=10.0, delta_t=0.025)
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
- works with none of them installed. Every probe is best-effort: a provenance tool
332
- that crashes a four-hour simulation because a framework renamed an attribute has
333
- done far more harm than the missing field was worth.
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
- See `examples/adapter_usage.py` for the full pattern for each.
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.