Release v2.0.0: trial-based timing architecture

.flake8

@@ -8,12 +8,15 @@ ignore =
 	D101,
 	D102,
 	D107,
+	E501,
 	E741,
 	F821,
 	W503
 per-file-ignores =
     # - docstrings rules that should not be applied to tests
 	tests/*: D100, D101, D102, D103
+    # - repository imports intentionally follow sys.path setup in this script
+    validation/manuscript_support/generate_tutorial3_case10_v2_package.py: E402
 # for compatibility with black
 # https://black.readthedocs.io/en/stable/guides/using_black_with_other_tools.html#flake8
 extend-ignore = E203

.github/workflows/tests.yml

@@ -39,3 +39,48 @@ jobs:
             with:
                 flags: ${{ matrix.os }}_${{ matrix.py }}
             if: success()
+
+    notebooks:
+        name: Execute notebooks
+        runs-on: ubuntu-latest
+        steps:
+        -   name: Checkout
+            uses: actions/checkout@v5
+        -   name: Setup python
+            uses: actions/setup-python@v6
+            with:
+                python-version: '3.12'
+        -   name: Install tox
+            run: python -m pip install --upgrade tox
+        -   name: Execute tutorial notebooks
+            run: tox run -e test_notebooks
+
+    docs:
+        name: Build docs
+        runs-on: ubuntu-latest
+        steps:
+        -   name: Checkout
+            uses: actions/checkout@v5
+        -   name: Setup python
+            uses: actions/setup-python@v6
+            with:
+                python-version: '3.12'
+        -   name: Install tox
+            run: python -m pip install --upgrade tox
+        -   name: Build documentation
+            run: tox run -e docs
+
+    validation:
+        name: Aggregate validation
+        runs-on: ubuntu-latest
+        steps:
+        -   name: Checkout
+            uses: actions/checkout@v5
+        -   name: Setup python
+            uses: actions/setup-python@v6
+            with:
+                python-version: '3.12'
+        -   name: Install validation dependencies
+            run: python -m pip install ".[doc,test]"
+        -   name: Run aggregate validation
+            run: python -m validation.run_all_validation_workflows

.gitignore

@@ -4,6 +4,24 @@ examples/output
 neurodesign/_version.py
 
 .vscode
+.agents/
+.claude/
+.suplex/
+AGENTS.md
+CLAUDE.md
+SUPLEX.md
+.venv/
+.pytest_cache/
+build/
+output/
+manuscript/
+validation/_artifacts/
+validation/**/*.pyc
+validation/**/__pycache__/
+neurodesign/__pycache__/
+tests/**/__pycache__/
+docs/_build/
+dist/
 
 # Byte-compiled / optimized / DLL files
 __pycache__/
@@ -94,3 +112,5 @@ ENV/
 
 # Rope project settings
 .ropeproject
+
+.tmp_precommit/

CHANGES.md

@@ -19,6 +19,82 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Security
 -->
 
+## [2.0.0] - 2026-07-18
+
+### Breaking changes
+
+- Replaced the inherited event-only timing surface with a trial-aware version-2 architecture based on conceptual trials and modeled events.
+- Replaced ambiguous ITI handling with separate `trial_start_interval`, `post_event_interval`, `event_transition_interval`, `inter_trial_interval`, `rest_every_n_trials`, and `rest_interval`.
+- Replaced event-level probability-template truncation with complete-template conceptual-trial sampling driven by `trial_templates`, `trial_template_probabilities`, and `n_conceptual_trials`.
+- Replaced direct manual `Design(order=..., ITI=...)` construction with `Experiment.create_design(...)` and `Experiment.create_manual_design(...)`.
+- Standardized the public optimization workflow around `optimise()` followed by `selected_design(0)`.
+
+### Added
+
+- Flat one-event shorthand through `order`.
+- Fixed complete conceptual-trial templates through `trial_templates` plus `trials`.
+- Probabilistic complete-template sampling through `trial_templates`, `trial_template_probabilities`, and `n_conceptual_trials`.
+- Shared timing-rule parsing for `event_durations`, `trial_start_interval`, `post_event_interval`, `event_transition_interval`, `inter_trial_interval`, and `rest_interval`.
+- Selector wrappers for trial-type, event-category, and event-transition timing rules.
+- Requested, normalized, and realized timing state exports.
+- Trial-aware schedule metadata on `Design`, including trial IDs, template IDs, trial types, and realized schedule arrays.
+- Public `selected_design(rank)` retrieval after optimization.
+- Canonical migration guide in `MIGRATION_2.0.md`.
+
+### Fixed
+
+- `Xnonconv` occupancy now reflects modeled event durations only rather than absorbing surrounding intervals.
+- Trial-start, post-event, within-trial transition, between-trial, and rest timing roles now remain structurally distinct.
+- Rest intervals now remain boundary intervals instead of being treated like synthetic task events.
+- `Ff` and `Fc` now use flattened realized event counts rather than conceptual-trial counts.
+- Case 10 now uses one canonical version-2 configuration shared across tutorials, validation, and manuscript-support generation.
+
+### Validation and reproducibility
+
+- Switched schedule sampling and optimization RNG handling to NumPy `SeedSequence` and `Generator`.
+- Added deterministic canonical Case 10 validation, manuscript-support generation, and cross-process determinism checks.
+- Added release-audit coverage for `selected_design()` guardrails, bounded distribution semantics, and version-2 public workflows.
+- Regenerated and validated the maintained tutorial notebooks from a single canonical notebook generator.
+
+### Migration requirements
+
+- Version 2.0 is intentionally source-breaking for scripts written against the version-1 timing API.
+- User-facing docs now route version migration through `MIGRATION_2.0.md`.
+- Tutorials and examples now teach the selected-design workflow, trial-aware timing terms, and event-count versus conceptual-trial-count distinctions.
+
+### Removed arguments
+
+- Removed `stimuli_durations`.
+- Removed `conditional_ITI`.
+- Removed `order_keys`, `order_probabilities`, and `order_length`.
+- Removed `all_stim_durations`.
+- Removed `t_pre` and `t_post`.
+- Removed `ITImodel`, `ITImin`, `ITImean`, and `ITImax`.
+- Removed active user-facing reliance on `.bestdesign` and internal design-pool indexing.
+
+### Export and report changes
+
+- Reports now align with the selected-design workflow.
+- `Design.export_payload()` now preserves reconstructable schedule arrays, schedule rows, counts, and metric components.
+- `Experiment.export_specification()` now preserves requested public timing specifications and trial-template configuration.
+
+### Trial-aware optimization changes
+
+- Flat mode remains event-order based.
+- Fixed conceptual-trial mode preserves the declared trial sequence.
+- Probabilistic template mode mutates and crosses at conceptual-trial boundaries instead of truncating event-level template fragments.
+
+### RNG changes
+
+- Removed dependence on global NumPy reseeding and Python `random`.
+- RNG derivation is now stable across sampling, crossover, mutation, and immigration.
+
+### Convergence changes
+
+- `convergence=k` now documents and exposes patience-based early stopping after `k` completed generations without strict improvement in the generation-best objective score.
+- `convergence=0` and `convergence=None` disable early stopping.
+- Public optimization state now exposes `generations_completed`, `stop_reason`, and `optima` for user-facing reporting.
+
 ## [1.0.2] - 2026-03-25
 
 ### Added

CITATION.cff

@@ -0,0 +1,29 @@
+cff-version: 1.2.0
+message: "If you use this software, please cite it using the metadata below."
+title: "neurodesign-plus"
+type: software
+authors:
+  - family-names: "Umap"
+    given-names: "Atharv Amar"
+  - family-names: "Charpentier"
+    given-names: "Caroline Juliette "
+  - family-names: "Guigon"
+    given-names: "Valentin"
+version: "2.0.0"
+repository-code: "https://github.com/SLDlab/neurodesign-plus"
+url: "https://github.com/SLDlab/neurodesign-plus"
+license: "MIT"
+preferred-citation:
+  type: software
+  title: "neurodesign-plus"
+  authors:
+    - family-names: "Umap"
+      given-names: "Atharv Amar"
+    - family-names: "Charpentier"
+      given-names: "Caroline Juliette"
+    - family-names: "Guigon"
+      given-names: "Valentin"
+  version: "2.0.0"
+  repository-code: "https://github.com/SLDlab/neurodesign-plus"
+  url: "https://github.com/SLDlab/neurodesign-plus"
+  license: "MIT"

Dockerfile

@@ -1,23 +1,13 @@
-FROM continuumio/miniconda
-MAINTAINER Joke Durnez <joke.durnez@gmail.com>
+FROM python:3.12-slim
 
-ENV LANG=C.UTF-8 LC_ALL=C.UTF-8
+ENV PYTHONDONTWRITEBYTECODE=1
+ENV PYTHONUNBUFFERED=1
+ENV MPLBACKEND=Agg
 
-RUN conda install numpy && \
-    conda install scipy && \
-    conda install pandas && \
-    conda install matplotlib
+WORKDIR /app
 
-RUN pip install neurodesign > 0.2.02
-RUN pip install sklearn
-RUN pip install pdfrw
-RUN pip install reportlab
-RUN pip install progressbar
-RUN pip install seaborn
+COPY . /app
 
-ENV LD_LIBRARY_PATH=/opt/conda/lib:$LD_LIBRARY_PATH
+RUN pip install --no-cache-dir .
 
-# Clear apt cache to reduce image size
-RUN apt-get update && \
-    apt-get install -y libgl1-mesa-glx && \
-    apt-get clean && rm -rf /var/lib/apt/lists/* /tmp/* /var/tmp/*
+CMD ["python", "-c", "from neurodesign import Experiment, Design, Optimisation; print('neurodesign-plus container ready')"]