daftar 0.2.0__tar.gz → 0.3.0__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 (39) hide show
  1. {daftar-0.2.0 → daftar-0.3.0}/CHANGELOG.md +48 -0
  2. {daftar-0.2.0/src/daftar.egg-info → daftar-0.3.0}/PKG-INFO +6 -2
  3. {daftar-0.2.0 → daftar-0.3.0}/README.md +2 -1
  4. {daftar-0.2.0 → daftar-0.3.0}/examples/adapter_usage.py +38 -1
  5. {daftar-0.2.0 → daftar-0.3.0}/pyproject.toml +3 -2
  6. daftar-0.3.0/src/daftar/__version__.py +1 -0
  7. {daftar-0.2.0 → daftar-0.3.0}/src/daftar/adapters/__init__.py +5 -3
  8. daftar-0.3.0/src/daftar/adapters/brian2_adapter.py +442 -0
  9. {daftar-0.2.0 → daftar-0.3.0}/src/daftar/capture.py +13 -1
  10. {daftar-0.2.0 → daftar-0.3.0/src/daftar.egg-info}/PKG-INFO +6 -2
  11. {daftar-0.2.0 → daftar-0.3.0}/src/daftar.egg-info/SOURCES.txt +1 -0
  12. {daftar-0.2.0 → daftar-0.3.0}/src/daftar.egg-info/requires.txt +4 -0
  13. {daftar-0.2.0 → daftar-0.3.0}/tests/test_adapters_live.py +133 -0
  14. {daftar-0.2.0 → daftar-0.3.0}/tests/test_core.py +1 -1
  15. daftar-0.2.0/src/daftar/__version__.py +0 -1
  16. {daftar-0.2.0 → daftar-0.3.0}/LICENSE +0 -0
  17. {daftar-0.2.0 → daftar-0.3.0}/MANIFEST.in +0 -0
  18. {daftar-0.2.0 → daftar-0.3.0}/PUBLISHING.md +0 -0
  19. {daftar-0.2.0 → daftar-0.3.0}/ROADMAP.md +0 -0
  20. {daftar-0.2.0 → daftar-0.3.0}/TROUBLESHOOTING.md +0 -0
  21. {daftar-0.2.0 → daftar-0.3.0}/examples/daftar_in_notebooks.ipynb +0 -0
  22. {daftar-0.2.0 → daftar-0.3.0}/examples/demo_end_to_end.py +0 -0
  23. {daftar-0.2.0 → daftar-0.3.0}/setup.cfg +0 -0
  24. {daftar-0.2.0 → daftar-0.3.0}/src/daftar/__init__.py +0 -0
  25. {daftar-0.2.0 → daftar-0.3.0}/src/daftar/adapters/base.py +0 -0
  26. {daftar-0.2.0 → daftar-0.3.0}/src/daftar/adapters/cpm_adapter.py +0 -0
  27. {daftar-0.2.0 → daftar-0.3.0}/src/daftar/adapters/jaxley_adapter.py +0 -0
  28. {daftar-0.2.0 → daftar-0.3.0}/src/daftar/adapters/meltingpot_adapter.py +0 -0
  29. {daftar-0.2.0 → daftar-0.3.0}/src/daftar/cli.py +0 -0
  30. {daftar-0.2.0 → daftar-0.3.0}/src/daftar/diff.py +0 -0
  31. {daftar-0.2.0 → daftar-0.3.0}/src/daftar/manifest.py +0 -0
  32. {daftar-0.2.0 → daftar-0.3.0}/src/daftar/notebook.py +0 -0
  33. {daftar-0.2.0 → daftar-0.3.0}/src/daftar/run.py +0 -0
  34. {daftar-0.2.0 → daftar-0.3.0}/src/daftar/store.py +0 -0
  35. {daftar-0.2.0 → daftar-0.3.0}/src/daftar/sweep.py +0 -0
  36. {daftar-0.2.0 → daftar-0.3.0}/src/daftar.egg-info/dependency_links.txt +0 -0
  37. {daftar-0.2.0 → daftar-0.3.0}/src/daftar.egg-info/entry_points.txt +0 -0
  38. {daftar-0.2.0 → daftar-0.3.0}/src/daftar.egg-info/top_level.txt +0 -0
  39. {daftar-0.2.0 → daftar-0.3.0}/tests/test_notebook.py +0 -0
@@ -1,5 +1,53 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.3.0 — Brian2
4
+
5
+ Brian2 hides more of what determines the answer than any other framework daftar
6
+ supports, which makes it the best argument yet for domain adapters.
7
+
8
+ **The integration method is chosen for you and then forgotten.** Brian2's
9
+ default is not a method but a candidate list, `('exact', 'euler', 'heun')`,
10
+ tried in order until one accepts the equations. Which one wins depends on the
11
+ equations, so a model that integrated `exact` silently falls back to `euler`
12
+ after an edit that makes the system non-linear — changing every result.
13
+
14
+ Brian2 stores the winner nowhere. `state_updater.method_choice` still holds the
15
+ list you never chose from, and the decision appears only in a log line. The
16
+ adapter records both:
17
+
18
+ ```
19
+ param.group.G.method_choice ('exact', 'euler', 'heun') what was permitted
20
+ param.group.G.method_resolved exact what actually ran
21
+ ```
22
+
23
+ Resolution is done by reproducing Brian2's own selection rather than by reading
24
+ its log. That matters: `apply_stateupdater` is cached, so the log line is
25
+ emitted only the first time a set of equations is seen in a process. An earlier
26
+ draft read the log and recorded the method on run 1 and nothing on run 2 —
27
+ making the field appear and disappear between runs, and show up as a spurious
28
+ cause in every diff.
29
+
30
+ **`codegen.target` defaults to `auto`**, which resolves to Cython where a
31
+ compiler exists and NumPy where one does not. The same script takes different
32
+ code paths on a laptop and on a cluster, and neither the script nor the
33
+ preference records which happened. `brian2.codegen_resolved` does.
34
+
35
+ **Fixed: `track(seed=...)` did not seed Brian2.** `brian2.seed()` delegates to
36
+ the current device; seeding numpy does not reach it. Without this,
37
+ `connect(p=0.05)` draws a different synaptic graph on every run, so two
38
+ otherwise identical runs differ with nothing in the manifest to explain it.
39
+ Core seeding now calls it and records `seed.brian2`.
40
+
41
+ Also recorded: the network schedule (reordering thresholds, synapses and resets
42
+ changes results without touching model code), equation hashes with differential
43
+ and parameter variable names, threshold/reset/refractory, per-group `dt`,
44
+ realised synapse counts and delay ranges, `core.default_float_dtype`, and
45
+ monitor output as comparable scalars rather than traces.
46
+
47
+ Four live tests against a real Brian2 network. Two identical runs now diff to
48
+ `identical` including the synapse count, which is the check that proves the
49
+ seeding fix.
50
+
3
51
  ## 0.2.0 — notebooks
4
52
 
5
53
  Notebooks are where provenance dies, and until now daftar was no better there
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: daftar
3
- Version: 0.2.0
3
+ Version: 0.3.0
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
@@ -21,6 +21,8 @@ Provides-Extra: cpm
21
21
  Requires-Dist: cpm-toolbox; extra == "cpm"
22
22
  Provides-Extra: meltingpot
23
23
  Requires-Dist: dm-meltingpot; extra == "meltingpot"
24
+ Provides-Extra: brian2
25
+ Requires-Dist: brian2; extra == "brian2"
24
26
  Provides-Extra: dev
25
27
  Requires-Dist: pytest>=7; extra == "dev"
26
28
  Requires-Dist: numpy; extra == "dev"
@@ -31,6 +33,7 @@ Provides-Extra: all
31
33
  Requires-Dist: jaxley; extra == "all"
32
34
  Requires-Dist: cpm-toolbox; extra == "all"
33
35
  Requires-Dist: dm-meltingpot; extra == "all"
36
+ Requires-Dist: brian2; extra == "all"
34
37
  Dynamic: license-file
35
38
 
36
39
  # daftar
@@ -126,7 +129,7 @@ Three consequences of taking that seriously:
126
129
  |---|---|
127
130
  | `code.*` | git commit, branch, dirty flag, **hash of uncommitted changes**, entrypoint, argv |
128
131
  | `param.*` | everything you chose, including defaults you never passed |
129
- | `seed.*` | seeds **applied** to `random`, numpy, torch; the JAX root key |
132
+ | `seed.*` | seeds **applied** to `random`, numpy, torch, **Brian2's device RNG**; the JAX root key |
130
133
  | `input.*` | sha256 and size of every declared input file or directory |
131
134
  | `env.*` | interpreter, OS, versions of packages the run imported, **and where each was installed from** |
132
135
  | `result.*` | scalar outcomes worth comparing |
@@ -310,6 +313,7 @@ knowing something a generic tracker cannot infer.
310
313
  |---|---|
311
314
  | `jaxley` | morphology (compartments, branches, channels, synapses), `jx.integrate` defaults you never passed, `jax_enable_x64`, backend |
312
315
  | `cpm` | parameter **bounds and priors**, estimator and its scipy method/tolerance, per-participant convergence counts, cohort hash |
316
+ | `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 |
313
317
  | `meltingpot` | resolved substrate ConfigDict hash, roles, episode-length cap, pinned bot checkpoints, per-player returns and Gini |
314
318
 
315
319
  All three are verified against live installs by `tests/test_adapters_live.py`,
@@ -91,7 +91,7 @@ Three consequences of taking that seriously:
91
91
  |---|---|
92
92
  | `code.*` | git commit, branch, dirty flag, **hash of uncommitted changes**, entrypoint, argv |
93
93
  | `param.*` | everything you chose, including defaults you never passed |
94
- | `seed.*` | seeds **applied** to `random`, numpy, torch; the JAX root key |
94
+ | `seed.*` | seeds **applied** to `random`, numpy, torch, **Brian2's device RNG**; the JAX root key |
95
95
  | `input.*` | sha256 and size of every declared input file or directory |
96
96
  | `env.*` | interpreter, OS, versions of packages the run imported, **and where each was installed from** |
97
97
  | `result.*` | scalar outcomes worth comparing |
@@ -275,6 +275,7 @@ knowing something a generic tracker cannot infer.
275
275
  |---|---|
276
276
  | `jaxley` | morphology (compartments, branches, channels, synapses), `jx.integrate` defaults you never passed, `jax_enable_x64`, backend |
277
277
  | `cpm` | parameter **bounds and priors**, estimator and its scipy method/tolerance, per-participant convergence counts, cohort hash |
278
+ | `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 |
278
279
  | `meltingpot` | resolved substrate ConfigDict hash, roles, episode-length cap, pinned bot checkpoints, per-player returns and Gini |
279
280
 
280
281
  All three are verified against live installs by `tests/test_adapters_live.py`,
@@ -63,6 +63,42 @@ with daftar.track("bandit-fit", seed=7) as run:
63
63
  # and nothing in the output tells you which you have.
64
64
  '''
65
65
 
66
+ # ---------------------------------------------------------------- Brian2 ---
67
+ BRIAN2 = '''
68
+ from brian2 import *
69
+ import daftar
70
+ from daftar.adapters import brian2 as b2a
71
+
72
+ eqs = """dv/dt = (I-v)/tau : 1
73
+ I : 1
74
+ tau : second"""
75
+ G = NeuronGroup(100, eqs, threshold="v>1", reset="v=0", name="G")
76
+ G.I = "1.5 + 0.5*rand()"; G.tau = 10*ms
77
+ S = Synapses(G, G, on_pre="v_post += 0.05", name="S"); S.connect(p=0.05)
78
+ net = Network(G, S, SpikeMonitor(G, name="spikes"))
79
+
80
+ with daftar.track("balanced-net", seed=42) as run:
81
+ b2a.run_network(net, 1*second, run)
82
+
83
+ # Recorded automatically:
84
+ # group.G.method_choice = (exact, euler, heun) <- what was permitted
85
+ # group.G.method_resolved = exact <- what actually ran
86
+ # brian2.codegen_resolved = cython (auto) <- auto means machine-dependent
87
+ # brian2.prefs.core.default_float_dtype = float64
88
+ # network.schedule = [start, groups, thresholds, synapses, resets, end]
89
+ # synapses.S.n_synapses = 496 <- p=0.05 is drawn, not declared
90
+ # result.monitor.spikes.num_spikes
91
+ #
92
+ # method_resolved is the one to watch. Brian2's default is a candidate list, not
93
+ # a method: a model that integrated `exact` silently falls back to `euler` after
94
+ # an edit that makes the equations non-linear. Brian2 stores the winner nowhere
95
+ # -- it only mentions it in a log line, once per process.
96
+ #
97
+ # Note also that daftar.track(seed=...) now calls brian2.seed(). Seeding numpy
98
+ # does not reach Brian2's device RNG, so without it `connect(p=0.05)` draws a
99
+ # different graph every run.
100
+ '''
101
+
66
102
  # ------------------------------------------------------------ MeltingPot ---
67
103
  MELTINGPOT = '''
68
104
  import daftar
@@ -120,7 +156,8 @@ def main():
120
156
 
121
157
  print("\nReference usage:")
122
158
  for title, snippet in (
123
- ("Jaxley", JAXLEY), ("cpm", CPM), ("MeltingPot", MELTINGPOT),
159
+ ("Jaxley", JAXLEY), ("cpm", CPM), ("Brian2", BRIAN2),
160
+ ("MeltingPot", MELTINGPOT),
124
161
  ):
125
162
  print(f"\n{'-' * 70}\n{title}\n{'-' * 70}{snippet}")
126
163
  print(f"\n{'-' * 70}\nConcordia -- why it is not here yet\n{'-' * 70}{CONCORDIA_NOTE}")
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
4
4
 
5
5
  [project]
6
6
  name = "daftar"
7
- version = "0.2.0"
7
+ version = "0.3.0"
8
8
  description = "Record what produced each computational result: environment, code, parameters, seeds, inputs."
9
9
  readme = "README.md"
10
10
  requires-python = ">=3.10"
@@ -29,9 +29,10 @@ Issues = "https://github.com/aslansd/daftar/issues"
29
29
  jaxley = ["jaxley"]
30
30
  cpm = ["cpm-toolbox"]
31
31
  meltingpot = ["dm-meltingpot"]
32
+ brian2 = ["brian2"]
32
33
  dev = ["pytest>=7", "numpy", "ipython"]
33
34
  notebook = ["ipython"]
34
- all = ["jaxley", "cpm-toolbox", "dm-meltingpot"]
35
+ all = ["jaxley", "cpm-toolbox", "dm-meltingpot", "brian2"]
35
36
 
36
37
  [project.scripts]
37
38
  daftar = "daftar.cli:main"
@@ -0,0 +1 @@
1
+ __version__ = "0.3.0"
@@ -7,17 +7,19 @@ at module load.
7
7
 
8
8
  from __future__ import annotations
9
9
 
10
- from . import cpm_adapter, jaxley_adapter, meltingpot_adapter
10
+ from . import brian2_adapter, cpm_adapter, jaxley_adapter, meltingpot_adapter
11
11
  from .base import Adapter, AdapterRegistry, record_optional, safe
12
12
 
13
13
  registry = AdapterRegistry()
14
14
  registry.register("jaxley", jaxley_adapter)
15
15
  registry.register("cpm", cpm_adapter)
16
16
  registry.register("meltingpot", meltingpot_adapter)
17
+ registry.register("brian2", brian2_adapter)
17
18
 
18
19
  jaxley = jaxley_adapter
19
20
  cpm = cpm_adapter
20
21
  meltingpot = meltingpot_adapter
22
+ brian2 = brian2_adapter
21
23
 
22
24
 
23
25
  def available() -> list[str]:
@@ -31,7 +33,7 @@ def get(name: str):
31
33
 
32
34
  __all__ = [
33
35
  "registry", "available", "get",
34
- "jaxley", "cpm", "meltingpot",
35
- "jaxley_adapter", "cpm_adapter", "meltingpot_adapter",
36
+ "jaxley", "cpm", "meltingpot", "brian2",
37
+ "jaxley_adapter", "cpm_adapter", "meltingpot_adapter", "brian2_adapter",
36
38
  "Adapter", "AdapterRegistry", "safe", "record_optional",
37
39
  ]
@@ -0,0 +1,442 @@
1
+ """Brian2 adapter.
2
+
3
+ Brian2 is the strongest case in this package for a domain adapter, because more
4
+ of what determines the answer is invisible than in any other framework here.
5
+
6
+ **The integration method is usually chosen for you and then forgotten.** The
7
+ default is not a method but a list of candidates, ``('exact', 'euler', 'heun')``,
8
+ tried in order until one fits the equations. Which one won depends on the
9
+ equations, so a model that integrated exactly can silently fall back to Euler
10
+ after an edit that makes the system non-linear. Brian2 reports the choice *only*
11
+ as a log line -- ``group_name.state_updater.method_choice`` still holds the list
12
+ you never chose from. This adapter captures the log during ``run()`` and records
13
+ the method that actually ran, per group. Nothing else records it.
14
+
15
+ **The code-generation target changes numerics.** ``prefs.codegen.target``
16
+ defaults to ``auto``, which resolves to Cython where a compiler exists and NumPy
17
+ where one does not. The same script on a laptop and on a cluster can therefore
18
+ take different code paths, and neither the script nor the resolved value appears
19
+ anywhere afterwards.
20
+
21
+ **Brian2 has its own RNG.** ``brian2.seed()`` delegates to the current device;
22
+ seeding ``numpy`` does not seed it. daftar's core seeding now calls it, and the
23
+ manifest records that it did.
24
+
25
+ **The schedule is an experiment parameter.** ``net.schedule`` orders
26
+ thresholds, synapses and resets within a timestep. Reordering it changes results
27
+ without changing a line of model code.
28
+ """
29
+
30
+ from __future__ import annotations
31
+
32
+ import hashlib
33
+ import logging
34
+ import re
35
+ from typing import Any
36
+
37
+ from ..run import Run
38
+ from .base import safe
39
+
40
+ name = "brian2"
41
+
42
+ #: ``No numerical integration method specified for group 'G', using method
43
+ #: 'exact' (took 0.02s).`` -- and the shorter ``Group G: using numerical
44
+ #: integration method exact``. Both are matched; the first is authoritative.
45
+ _METHOD_PATTERNS = (
46
+ re.compile(r"for group '(?P<group>[^']+)', using method '(?P<method>[^']+)'"),
47
+ re.compile(r"Group (?P<group>\S+): using numerical integration method "
48
+ r"(?P<method>\S+)"),
49
+ )
50
+
51
+
52
+ def is_available() -> bool:
53
+ try:
54
+ import brian2 # noqa: F401
55
+ return True
56
+ except Exception:
57
+ return False
58
+
59
+
60
+ def _sha(text: str) -> str:
61
+ return hashlib.sha256(text.encode("utf-8", "replace")).hexdigest()[:16]
62
+
63
+
64
+ # --------------------------------------------------------------------------
65
+ # capturing the resolved integration method
66
+ # --------------------------------------------------------------------------
67
+
68
+ class _MethodCapture(logging.Handler):
69
+ """Collects ``group -> resolved method`` from Brian2's own log output.
70
+
71
+ Reading a log is not elegant, but it is the only route: Brian2 resolves the
72
+ method during ``before_run`` and does not store the winner on any object.
73
+ The handler is attached for the duration of the run and removed afterwards,
74
+ and it never raises -- a logging handler that throws would take the
75
+ simulation down with it.
76
+ """
77
+
78
+ def __init__(self) -> None:
79
+ super().__init__()
80
+ self.methods: dict[str, str] = {}
81
+
82
+ def emit(self, record: logging.LogRecord) -> None:
83
+ try:
84
+ message = record.getMessage()
85
+ except Exception:
86
+ return
87
+ for pattern in _METHOD_PATTERNS:
88
+ m = pattern.search(message)
89
+ if m:
90
+ self.methods.setdefault(m.group("group"), m.group("method"))
91
+ return
92
+
93
+
94
+ class capture_methods:
95
+ """Attach :class:`_MethodCapture` to Brian2's logger for a block.
96
+
97
+ No longer used by :func:`run_network` -- :func:`resolve_method` reproduces
98
+ the selection directly, which is immune to Brian2's caching of
99
+ ``apply_stateupdater``. Kept as a public escape hatch for anyone who wants
100
+ the method as Brian2 itself reported it, and for cross-checking that our
101
+ resolution agrees with Brian's.
102
+ """
103
+
104
+ def __init__(self) -> None:
105
+ self.handler = _MethodCapture()
106
+ self._logger = logging.getLogger("brian2")
107
+ self._previous_level: int | None = None
108
+
109
+ def __enter__(self) -> _MethodCapture:
110
+ self._previous_level = self._logger.level
111
+ # Brian2 emits the method choice at DEBUG. Lower the level only if it
112
+ # would otherwise suppress the message, and restore it on exit.
113
+ if self._logger.level > logging.DEBUG or self._logger.level == logging.NOTSET:
114
+ self._logger.setLevel(logging.DEBUG)
115
+ self._logger.addHandler(self.handler)
116
+ return self.handler
117
+
118
+ def __exit__(self, *exc) -> bool:
119
+ self._logger.removeHandler(self.handler)
120
+ if self._previous_level is not None:
121
+ self._logger.setLevel(self._previous_level)
122
+ return False
123
+
124
+
125
+ # --------------------------------------------------------------------------
126
+ # preferences, device, clock
127
+ # --------------------------------------------------------------------------
128
+
129
+ #: Preferences that change results and are almost never written down.
130
+ _TRACKED_PREFS = (
131
+ "codegen.target",
132
+ "codegen.loop_invariant_optimisations",
133
+ "codegen.string_expression_target",
134
+ "core.default_float_dtype",
135
+ "core.network.default_schedule",
136
+ "legacy.refractory_timing",
137
+ )
138
+
139
+
140
+ def describe_environment(run: Run, prefix: str = "brian2") -> None:
141
+ """Record the Brian2 preferences and device that shape every result."""
142
+ import brian2
143
+
144
+ run.log_param(f"{prefix}.version", safe(lambda: brian2.__version__, "unknown"))
145
+
146
+ prefs = safe(lambda: brian2.prefs)
147
+ if prefs is not None:
148
+ for key in _TRACKED_PREFS:
149
+ value = safe(lambda k=key: prefs[k])
150
+ if value is None:
151
+ continue
152
+ # core.default_float_dtype is a numpy type object; its repr is a
153
+ # class path, so reduce it to the name that actually matters.
154
+ run.log_param(f"{prefix}.prefs.{key}",
155
+ getattr(value, "__name__", None) or value)
156
+
157
+ device = safe(lambda: brian2.get_device())
158
+ if device is not None:
159
+ run.log_param(f"{prefix}.device", type(device).__name__)
160
+
161
+ # `codegen.target = auto` resolves to cython where a compiler exists and
162
+ # numpy where it does not, so the *resolved* value is the one that matters.
163
+ run.log_param(f"{prefix}.codegen_resolved", safe(_resolved_target, "unknown"))
164
+
165
+ clock = safe(lambda: brian2.defaultclock)
166
+ if clock is not None:
167
+ run.log_param(f"{prefix}.defaultclock_dt", _quantity(clock.dt))
168
+
169
+
170
+ def resolve_method(group: Any) -> str | None:
171
+ """Which integration method Brian2 will actually use for ``group``.
172
+
173
+ Brian2's default is not a method but a candidate list,
174
+ ``('exact', 'euler', 'heun')``, tried in order until one accepts the
175
+ equations. The winner is stored nowhere: ``state_updater.method_choice``
176
+ still holds the list.
177
+
178
+ Brian2 does log the choice, but ``apply_stateupdater`` is cached, so the
179
+ line is emitted only the first time a given set of equations is seen in a
180
+ process. Reading the log therefore records the method on run 1 and nothing
181
+ on run 2 -- which makes the field *appear* and *disappear* between runs and
182
+ shows up as a spurious cause in every diff. Reproducing the selection
183
+ directly is deterministic and immune to the cache.
184
+ """
185
+ from brian2.stateupdaters.base import (
186
+ StateUpdateMethod, UnsupportedEquationsException,
187
+ )
188
+
189
+ updater = safe(lambda: group.state_updater)
190
+ if updater is None:
191
+ return None
192
+ choice = safe(lambda: updater.method_choice)
193
+ if choice is None:
194
+ return None
195
+ if isinstance(choice, str):
196
+ return choice
197
+ if callable(choice):
198
+ return getattr(choice, "__name__", None) or type(choice).__name__
199
+
200
+ equations = safe(lambda: group.equations)
201
+ variables = safe(lambda: group.variables)
202
+ if equations is None or variables is None:
203
+ return None
204
+
205
+ for candidate in choice:
206
+ updater_impl = safe(lambda c=candidate: StateUpdateMethod.stateupdaters[c])
207
+ if updater_impl is None:
208
+ continue
209
+ try:
210
+ updater_impl(equations, variables)
211
+ return str(candidate)
212
+ except UnsupportedEquationsException:
213
+ continue
214
+ except Exception:
215
+ # An unrelated failure tells us nothing about suitability; keep
216
+ # looking rather than reporting a method that may not be the one.
217
+ continue
218
+ return None
219
+
220
+
221
+ def _resolved_target() -> str:
222
+ """What ``codegen.target = 'auto'`` actually became.
223
+
224
+ ``auto`` resolves to Cython where a working compiler exists and NumPy where
225
+ one does not, so the same script takes different code paths on a laptop and
226
+ on a cluster. Neither the script nor the preference records which happened.
227
+ """
228
+ import brian2
229
+
230
+ target = safe(lambda: brian2.prefs["codegen.target"], "unknown")
231
+ if target != "auto":
232
+ return str(target)
233
+ try:
234
+ from brian2.codegen.runtime.cython_rt.cython_rt import CythonCodeObject
235
+ if CythonCodeObject.is_available():
236
+ return "cython (auto)"
237
+ except Exception:
238
+ pass
239
+ return "numpy (auto)"
240
+
241
+
242
+ def _quantity(value: Any) -> str:
243
+ """Render a Brian2 Quantity in a stable, unit-bearing form.
244
+
245
+ ``str(100*usecond)`` gives ``'100. us'``. Keeping the unit is the point:
246
+ a manifest recording ``dt = 0.0001`` loses the fact that it is seconds, and
247
+ a bare float invites the reader to guess.
248
+ """
249
+ return safe(lambda: str(value), "<unavailable>")
250
+
251
+
252
+ # --------------------------------------------------------------------------
253
+ # groups
254
+ # --------------------------------------------------------------------------
255
+
256
+ def describe_group(group: Any, run: Run, prefix: str | None = None) -> None:
257
+ """Record a NeuronGroup: size, equations, threshold, method choice, clock."""
258
+ gname = safe(lambda: group.name, "group")
259
+ prefix = prefix or f"group.{gname}"
260
+
261
+ run.log_param(f"{prefix}.type", type(group).__name__)
262
+ run.log_param(f"{prefix}.N", safe(lambda: int(group.N), "unknown"))
263
+
264
+ # The equations *are* the model. Hash them so an edit is visible, and record
265
+ # the variable names so a diff says which part changed.
266
+ eqs = safe(lambda: str(group.equations))
267
+ if eqs:
268
+ run.log_param(f"{prefix}.equations_sha256", _sha(eqs))
269
+ run.log_param(f"{prefix}.diff_eq_names",
270
+ safe(lambda: sorted(group.equations.diff_eq_names), []))
271
+ run.log_param(f"{prefix}.parameter_names",
272
+ safe(lambda: sorted(group.equations.parameter_names), []))
273
+
274
+ for attr, key in (("_threshold", "threshold"), ("_reset", "reset"),
275
+ ("_refractory", "refractory")):
276
+ value = safe(lambda a=attr: getattr(group, a))
277
+ if value not in (None, False):
278
+ run.log_param(f"{prefix}.{key}", _quantity(value))
279
+
280
+ updater = safe(lambda: group.state_updater)
281
+ if updater is not None:
282
+ # method_choice is the candidate *list*; method_resolved is the winner.
283
+ # Both are recorded: the list shows what was permitted, the winner shows
284
+ # what ran. A model that integrated exactly and silently fell back to
285
+ # euler after an edit shows up as a change in the second field only.
286
+ run.log_param(f"{prefix}.method_choice",
287
+ _quantity(safe(lambda: updater.method_choice)))
288
+ run.log_param(f"{prefix}.method_resolved",
289
+ safe(lambda: resolve_method(group), "unknown") or "unknown")
290
+ options = safe(lambda: updater.method_options)
291
+ if options:
292
+ run.log_param(f"{prefix}.method_options", options)
293
+
294
+ clock = safe(lambda: group.clock)
295
+ if clock is not None:
296
+ run.log_param(f"{prefix}.dt", _quantity(clock.dt))
297
+
298
+ events = safe(lambda: dict(group.events), {})
299
+ if events:
300
+ run.log_param(f"{prefix}.events", sorted(events.keys()))
301
+
302
+
303
+ def describe_synapses(syn: Any, run: Run, prefix: str | None = None) -> None:
304
+ """Record a Synapses object: connectivity, delays, equations.
305
+
306
+ The number of realised synapses matters and is not knowable from the script:
307
+ ``connect(p=0.02)`` draws a different graph on every unseeded run, which is
308
+ one of the commonest sources of "why is my network different today".
309
+ """
310
+ sname = safe(lambda: syn.name, "synapses")
311
+ prefix = prefix or f"synapses.{sname}"
312
+
313
+ run.log_param(f"{prefix}.type", type(syn).__name__)
314
+ run.log_param(f"{prefix}.n_synapses", safe(lambda: int(len(syn)), "unknown"))
315
+ run.log_param(f"{prefix}.source", safe(lambda: syn.source.name, "unknown"))
316
+ run.log_param(f"{prefix}.target", safe(lambda: syn.target.name, "unknown"))
317
+
318
+ eqs = safe(lambda: str(syn.equations))
319
+ if eqs:
320
+ run.log_param(f"{prefix}.equations_sha256", _sha(eqs))
321
+
322
+ for attr, key in (("_on_pre", "on_pre"), ("_on_post", "on_post")):
323
+ value = safe(lambda a=attr: getattr(syn, a))
324
+ if value:
325
+ run.log_param(f"{prefix}.{key}_sha256", _sha(str(value)))
326
+
327
+ delay = safe(lambda: syn.delay)
328
+ if delay is not None:
329
+ run.log_param(f"{prefix}.delay_summary", _delay_summary(delay))
330
+
331
+
332
+ def _delay_summary(delay: Any) -> str:
333
+ """min/max of a delay array, or the scalar. Recording every delay is noise."""
334
+ def _summary():
335
+ import numpy as np
336
+ arr = np.asarray(delay[:])
337
+ if arr.size == 0:
338
+ return "none"
339
+ if arr.size == 1 or arr.min() == arr.max():
340
+ return f"{float(arr.flat[0]):.6g} s (uniform)"
341
+ return f"{float(arr.min()):.6g}..{float(arr.max()):.6g} s"
342
+ return safe(_summary, "<unavailable>")
343
+
344
+
345
+ def describe_network(net: Any, run: Run, prefix: str = "network") -> None:
346
+ """Record the network: which objects, and the within-timestep schedule."""
347
+ objects = safe(lambda: sorted(o.name for o in net.objects), [])
348
+ run.log_param(f"{prefix}.objects", objects)
349
+ run.log_param(f"{prefix}.n_objects", len(objects))
350
+
351
+ # Reordering the schedule changes results without changing model code.
352
+ run.log_param(f"{prefix}.schedule", safe(lambda: list(net.schedule), []))
353
+ run.log_param(f"{prefix}.t_start", _quantity(safe(lambda: net.t)))
354
+
355
+ for obj in safe(lambda: list(net.objects), []):
356
+ cls = type(obj).__name__
357
+ if cls in ("NeuronGroup", "PoissonGroup", "SpikeGeneratorGroup"):
358
+ describe_group(obj, run)
359
+ elif cls == "Synapses":
360
+ describe_synapses(obj, run)
361
+
362
+
363
+ # --------------------------------------------------------------------------
364
+ # monitors -> results
365
+ # --------------------------------------------------------------------------
366
+
367
+ def describe_monitors(net: Any, run: Run, prefix: str = "monitor") -> None:
368
+ """Summarise monitor output as comparable scalars.
369
+
370
+ Deliberately summaries, not traces. A recorded voltage array would make
371
+ every diff unreadable; spike counts and rates are what you actually compare
372
+ between two runs.
373
+ """
374
+ for obj in safe(lambda: list(net.objects), []):
375
+ cls = type(obj).__name__
376
+ oname = safe(lambda o=obj: o.name, "monitor")
377
+
378
+ if cls == "SpikeMonitor":
379
+ run.log_result(f"{prefix}.{oname}.num_spikes",
380
+ safe(lambda o=obj: int(o.num_spikes), "unknown"))
381
+ run.log_result(f"{prefix}.{oname}.n_active_neurons",
382
+ safe(lambda o=obj: int(len(set(o.i[:]))), "unknown"))
383
+
384
+ elif cls == "PopulationRateMonitor":
385
+ def _mean_rate(o=obj):
386
+ import numpy as np
387
+ return round(float(np.asarray(o.rate[:]).mean()), 6)
388
+ run.log_result(f"{prefix}.{oname}.mean_rate_hz",
389
+ safe(_mean_rate, "unknown"))
390
+
391
+ elif cls == "StateMonitor":
392
+ variables = safe(lambda o=obj: list(o.record_variables), [])
393
+ run.log_param(f"{prefix}.{oname}.variables", sorted(variables))
394
+ for var in variables:
395
+ def _stats(o=obj, v=var):
396
+ import numpy as np
397
+ arr = np.asarray(getattr(o, v)[:])
398
+ return {
399
+ "mean": round(float(arr.mean()), 8),
400
+ "min": round(float(arr.min()), 8),
401
+ "max": round(float(arr.max()), 8),
402
+ "n_nonfinite": int((~np.isfinite(arr)).sum()),
403
+ }
404
+ for stat, value in (safe(_stats, {}) or {}).items():
405
+ run.log_result(f"{prefix}.{oname}.{var}.{stat}", value)
406
+
407
+
408
+ # --------------------------------------------------------------------------
409
+ # the wrapper people actually call
410
+ # --------------------------------------------------------------------------
411
+
412
+ def run_network(net: Any, duration: Any, run: Run, **kwargs: Any):
413
+ """``net.run(duration)`` with everything provenance-relevant recorded.
414
+
415
+ ::
416
+
417
+ with daftar.track("balanced-network", seed=42) as run:
418
+ brian2_adapter.run_network(net, 1*second, run)
419
+
420
+ The resolved integration method is captured from Brian2's log during the
421
+ run, because it exists nowhere else afterwards.
422
+ """
423
+ describe_environment(run)
424
+ describe_network(net, run)
425
+ run.log_param("brian2.run_duration", _quantity(duration))
426
+
427
+ result = net.run(duration, **kwargs)
428
+
429
+ describe_monitors(net, run)
430
+ run.log_result("brian2.t_end", _quantity(safe(lambda: net.t)))
431
+ return result
432
+
433
+
434
+ def describe(obj: Any, run: Run, prefix: str | None = None) -> None:
435
+ """Dispatch on whatever Brian2 object is handed in."""
436
+ cls = type(obj).__name__
437
+ if cls == "Network":
438
+ describe_network(obj, run)
439
+ elif cls == "Synapses":
440
+ describe_synapses(obj, run, prefix)
441
+ else:
442
+ describe_group(obj, run, prefix)
@@ -27,7 +27,7 @@ from typing import Any
27
27
  # guarantees the usual suspects appear even if imported lazily later.
28
28
  _ALWAYS_RECORD = (
29
29
  "numpy", "scipy", "pandas", "jax", "jaxlib", "jaxley", "torch",
30
- "equinox", "brian2", "neuron", "cpm-toolbox", "cpm", "dm-meltingpot",
30
+ "equinox", "brian2", "neuron", "cpm-toolbox", "cpm", "cython", "sympy", "dm-meltingpot",
31
31
  "dmlab2d", "gdm-concordia", "matplotlib", "scikit-learn",
32
32
  )
33
33
 
@@ -292,6 +292,18 @@ def apply_seeds(seed: int) -> dict[str, Any]:
292
292
  if jax is not None:
293
293
  applied["jax_root_key"] = f"jax.random.PRNGKey({seed})"
294
294
 
295
+ # Brian2 keeps its own RNG on the current device. Seeding numpy does not
296
+ # reach it, so a Brian2 network seeded only through numpy still draws a
297
+ # different random connectivity on every run -- exactly the failure this
298
+ # function exists to prevent.
299
+ brian2 = sys.modules.get("brian2")
300
+ if brian2 is not None:
301
+ try:
302
+ brian2.seed(seed)
303
+ applied["brian2"] = True
304
+ except Exception: # pragma: no cover - defensive
305
+ applied["brian2"] = False
306
+
295
307
  return applied
296
308
 
297
309
 
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: daftar
3
- Version: 0.2.0
3
+ Version: 0.3.0
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
@@ -21,6 +21,8 @@ Provides-Extra: cpm
21
21
  Requires-Dist: cpm-toolbox; extra == "cpm"
22
22
  Provides-Extra: meltingpot
23
23
  Requires-Dist: dm-meltingpot; extra == "meltingpot"
24
+ Provides-Extra: brian2
25
+ Requires-Dist: brian2; extra == "brian2"
24
26
  Provides-Extra: dev
25
27
  Requires-Dist: pytest>=7; extra == "dev"
26
28
  Requires-Dist: numpy; extra == "dev"
@@ -31,6 +33,7 @@ Provides-Extra: all
31
33
  Requires-Dist: jaxley; extra == "all"
32
34
  Requires-Dist: cpm-toolbox; extra == "all"
33
35
  Requires-Dist: dm-meltingpot; extra == "all"
36
+ Requires-Dist: brian2; extra == "all"
34
37
  Dynamic: license-file
35
38
 
36
39
  # daftar
@@ -126,7 +129,7 @@ Three consequences of taking that seriously:
126
129
  |---|---|
127
130
  | `code.*` | git commit, branch, dirty flag, **hash of uncommitted changes**, entrypoint, argv |
128
131
  | `param.*` | everything you chose, including defaults you never passed |
129
- | `seed.*` | seeds **applied** to `random`, numpy, torch; the JAX root key |
132
+ | `seed.*` | seeds **applied** to `random`, numpy, torch, **Brian2's device RNG**; the JAX root key |
130
133
  | `input.*` | sha256 and size of every declared input file or directory |
131
134
  | `env.*` | interpreter, OS, versions of packages the run imported, **and where each was installed from** |
132
135
  | `result.*` | scalar outcomes worth comparing |
@@ -310,6 +313,7 @@ knowing something a generic tracker cannot infer.
310
313
  |---|---|
311
314
  | `jaxley` | morphology (compartments, branches, channels, synapses), `jx.integrate` defaults you never passed, `jax_enable_x64`, backend |
312
315
  | `cpm` | parameter **bounds and priors**, estimator and its scipy method/tolerance, per-participant convergence counts, cohort hash |
316
+ | `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 |
313
317
  | `meltingpot` | resolved substrate ConfigDict hash, roles, episode-length cap, pinned bot checkpoints, per-player returns and Gini |
314
318
 
315
319
  All three are verified against live installs by `tests/test_adapters_live.py`,
@@ -27,6 +27,7 @@ src/daftar.egg-info/requires.txt
27
27
  src/daftar.egg-info/top_level.txt
28
28
  src/daftar/adapters/__init__.py
29
29
  src/daftar/adapters/base.py
30
+ src/daftar/adapters/brian2_adapter.py
30
31
  src/daftar/adapters/cpm_adapter.py
31
32
  src/daftar/adapters/jaxley_adapter.py
32
33
  src/daftar/adapters/meltingpot_adapter.py
@@ -3,6 +3,10 @@
3
3
  jaxley
4
4
  cpm-toolbox
5
5
  dm-meltingpot
6
+ brian2
7
+
8
+ [brian2]
9
+ brian2
6
10
 
7
11
  [cpm]
8
12
  cpm-toolbox
@@ -352,3 +352,136 @@ def test_at_least_report_what_is_installed():
352
352
  ok, why = _jaxley_is_usable()
353
353
  if daftar.adapters.get("jaxley").is_available() and not ok:
354
354
  print(f"\nNOTE: {why}")
355
+
356
+
357
+ # ==========================================================================
358
+ # Brian2
359
+ # ==========================================================================
360
+
361
+ def _brian2_network(name_suffix=""):
362
+ """A small spiking network: neurons, random synapses, two monitors."""
363
+ from brian2 import (
364
+ Network, NeuronGroup, PopulationRateMonitor, SpikeMonitor, Synapses,
365
+ ms, prefs, start_scope,
366
+ )
367
+
368
+ prefs.codegen.target = "numpy" # no compiler needed in CI
369
+ start_scope()
370
+ eqs = """dv/dt = (I-v)/tau : 1
371
+ I : 1
372
+ tau : second"""
373
+ G = NeuronGroup(50, eqs, threshold="v>1", reset="v=0", name="G")
374
+ G.I = "1.5 + 0.5*rand()"
375
+ G.tau = 10 * ms
376
+ S = Synapses(G, G, on_pre="v_post += 0.05", name="S")
377
+ S.connect(p=0.05)
378
+ return Network(G, S, SpikeMonitor(G, name="spikes"),
379
+ PopulationRateMonitor(G, name="rate"))
380
+
381
+
382
+ @_require("brian2")
383
+ def test_brian2_records_the_resolved_integration_method(store):
384
+ from brian2 import ms
385
+
386
+ from daftar.adapters import brian2 as b2a
387
+
388
+ with daftar.track("net", seed=42, store=store) as run:
389
+ b2a.run_network(_brian2_network(), 50 * ms, run)
390
+ rid = run.run_id
391
+
392
+ m = store.load(rid)
393
+
394
+ # The default is a candidate *list*; the winner is stored nowhere in Brian2.
395
+ assert m.get("param.group.G.method_choice").startswith("(")
396
+ assert m.get("param.group.G.method_resolved") == "exact"
397
+
398
+ # codegen.target = auto resolves differently per machine; record the winner.
399
+ assert m.get("param.brian2.codegen_resolved")
400
+ assert m.get("param.brian2.prefs.core.default_float_dtype") == "float64"
401
+ assert m.get("param.brian2.device") == "RuntimeDevice"
402
+
403
+ # The schedule orders thresholds/synapses/resets within a timestep.
404
+ assert "thresholds" in m.get("param.network.schedule")
405
+
406
+ # Connectivity is drawn, not declared: p=0.05 gives a different graph
407
+ # every unseeded run.
408
+ assert int(m.get("param.synapses.S.n_synapses")) > 0
409
+ assert m.get("param.group.G.N") == "50"
410
+ assert m.get("param.group.G.equations_sha256")
411
+
412
+ assert int(m.get("result.monitor.spikes.num_spikes")) > 0
413
+ assert m.get("result.monitor.rate.mean_rate_hz")
414
+
415
+
416
+ @_require("brian2")
417
+ def test_brian2_seed_is_applied_so_connectivity_reproduces(store):
418
+ """brian2.seed() is a device call; seeding numpy does not reach it.
419
+
420
+ Without it, `connect(p=0.05)` draws a different graph on every run and two
421
+ otherwise identical runs would differ with nothing to explain it.
422
+ """
423
+ from brian2 import ms
424
+
425
+ from daftar.adapters import brian2 as b2a
426
+
427
+ ids = []
428
+ for _ in range(2):
429
+ with daftar.track("net", seed=42, store=store) as run:
430
+ b2a.run_network(_brian2_network(), 50 * ms, run)
431
+ ids.append(run.run_id)
432
+
433
+ a, b = store.load(ids[0]), store.load(ids[1])
434
+ assert a.get("seed.brian2") == "true"
435
+ assert a.get("param.synapses.S.n_synapses") == b.get("param.synapses.S.n_synapses")
436
+
437
+ d = daftar.diff_manifests(a, b)
438
+ assert not d.causes, [c.key for c in d.causes]
439
+ assert not d.effects, [c.key for c in d.effects]
440
+
441
+
442
+ @_require("brian2")
443
+ def test_brian2_method_resolution_survives_brian_caching(store):
444
+ """The resolved method must not vanish on the second run in a process.
445
+
446
+ Brian2 logs its choice, but `apply_stateupdater` is cached, so the log line
447
+ appears only the first time a set of equations is seen. Reading the log gave
448
+ the method on run 1 and nothing on run 2, which showed up as a spurious
449
+ cause in every diff. Resolution is now done directly.
450
+ """
451
+ from brian2 import ms
452
+
453
+ from daftar.adapters import brian2 as b2a
454
+
455
+ resolved = []
456
+ for _ in range(2):
457
+ with daftar.track("net", seed=1, store=store) as run:
458
+ b2a.run_network(_brian2_network(), 20 * ms, run)
459
+ rid = run.run_id
460
+ resolved.append(store.load(rid).get("param.group.G.method_resolved"))
461
+
462
+ assert resolved[0] == resolved[1] == "exact"
463
+ assert "unknown" not in resolved
464
+
465
+
466
+ @_require("brian2")
467
+ def test_brian2_dt_change_is_a_cause_not_a_mystery(store):
468
+ from brian2 import defaultclock, ms
469
+
470
+ from daftar.adapters import brian2 as b2a
471
+
472
+ with daftar.track("net", seed=42, store=store) as run:
473
+ b2a.run_network(_brian2_network(), 50 * ms, run)
474
+ a = run.run_id
475
+
476
+ defaultclock.dt = 0.05 * ms
477
+ try:
478
+ with daftar.track("net", seed=42, store=store) as run:
479
+ b2a.run_network(_brian2_network(), 50 * ms, run)
480
+ b = run.run_id
481
+ finally:
482
+ defaultclock.dt = 0.1 * ms
483
+
484
+ d = daftar.diff_manifests(store.load(a), store.load(b))
485
+ causes = [c.key for c in d.causes]
486
+ assert "param.brian2.defaultclock_dt" in causes
487
+ assert d.effects, "changing dt should move the spike count"
@@ -430,7 +430,7 @@ def test_manifests_are_valid_json_on_disk(store):
430
430
 
431
431
  def test_adapters_import_without_their_frameworks():
432
432
  from daftar import adapters
433
- assert set(adapters.registry.all()) == {"jaxley", "cpm", "meltingpot"}
433
+ assert set(adapters.registry.all()) == {"jaxley", "cpm", "meltingpot", "brian2"}
434
434
  for name in adapters.registry.all():
435
435
  assert isinstance(adapters.get(name).is_available(), bool)
436
436
 
@@ -1 +0,0 @@
1
- __version__ = "0.2.0"
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes