feat: unify parameter learning across channels, ions, synapses, and networks

[TLDSZ]

Description

This PR extends parameter learning from a small set of schema-backed channels to constructor-declared Channel, Ion, and Synapse parameters. It also adds trainable connection weights, voltage detection thresholds, and Network-wide parameter aggregation.

The implementation reuses the existing parameter sources, grouping, shared roots, and materialization pipeline. The accompanying documentation distinguishes implemented contracts from proposals and historical experiment records.

Constructor-based Channel parameter discovery

Commit: 5b390b6

• Discover candidate parameters from explicit constructor signatures, including declared inherited and forwarded parameters.
• Remove the need for a separate handwritten trainable-parameter dictionary.
• Preserve parameter units, spatial selection, grouping, shared roots, and direct/scale/callable parameter sources.
• Keep derived channel quantities responsive to their current parameter dependencies, including temperature-dependent kinetics.
• Add regression coverage for parameter discovery, defaults, runtime updates, gradients, and repeated compiled execution.
• Add channel_learning.ipynb with focused parameter-fitting examples.

Ion parameter learning and differentiable initialization

Commit: dfca5a3

• Extend the same binding mechanism to Ion constructor parameters and explicitly named initialization parameters.
• Keep trainable initial conditions distinct from dynamic concentration states. Reset evaluates the current parameter roots so initialization remains part of the differentiated model.
• Refresh dependent Nernst, concentration, and shell-geometry quantities at their appropriate lifecycle stages.
• Preserve shared Channel/Ion roots and parameter dependency behavior across runtime materialization and reset.
• Add Ion integration tests and a five-example learning notebook.

Synapse, Connection, and Network parameter learning

Commit: 5f90f69

• Derive Synapse parameter metadata from explicit constructor signatures and migrate ExpSyn and Exp2Syn to this contract.
• Support trainable synaptic parameters, physical Connection weights, and voltage detector thresholds.
• Keep Synapse and Connection bindings on their owning target Cell. Aggregate Cell roots through Network.trainables, deduplicating shared objects without
  copying optimizer state.
• Add Network.prepare_run() for initialization and static routing setup outside tracing, and Network.update() for differentiable single-step execution
  inside BrainState compiled loops.
• Read current connection weights during event delivery so optimizer updates remain visible to cached execution.
• Preserve hard threshold-crossing events in the forward pass while using surrogate derivatives for upstream voltage and threshold gradients.
• Add an exact bilinear JVP for sparse delivery, supporting batched event and weight tangents used by full-state RTRL.
• Add autapse, cross-Cell, and bidirectional-population experiments with gradient, reset, delay-queue, shared-root, and joint-fitting tests.

Design structure, progress tracking, and contributor guidance

Commit: 99eb4d8

• Organize Design by module with local TODOs and separate current, proposals, and references content.
• Separate public API contracts from runtime architecture and preserve historical plans and verification records under docs/specs/.
• Define dedicated writing rules for Current, Proposal, Reference, and progress documents.
• Update global task markers and link completed capabilities to their implementation and verification records.
• Refocus Developer documentation on contribution workflows and link module-specific contracts to Design.
• Update repository navigation, visualization documentation, source references, and example links.
• Record proposals for single/multi-compartment unification, explicit-solver boundary inputs, random contexts, and plasticity.

Saved notebook results

Commit: 20c2bc1

• Refresh the saved Channel/Ion notebook environment metadata.
• Update seven Ion notebook output cells while preserving all code and Markdown cell sources.
• Keep the older JAX 0.8.0 measurements identified as historical results; the refreshed Ion output reports JAX 0.10.1.

How Has This Been Tested

Runtime and training regression tests

The functional snapshot was tested on CPU in two environments:

• Python 3.11.4 / JAX 0.8.0: 1523 passed, 2 skipped. Coverage includes Channel, Ion, compute, trainable, Cell, Network, Synapse, base classes, and new
  training example tests.
• Python 3.11.15 / JAX 0.10.1: 175 passed, 2 skipped, with 25 additional subtests passed. Coverage includes Network, Synapse, Network roots, point parameter targets, and new training example tests.

The new experiments check:

• Voltage and spike-loss gradients through autapses and cross-Cell feedback.
• Bidirectional populations with independently trainable parameters and contact weights.
• Agreement between BPTT and full-state RTRL on the same surrogate computation.
• Shared-root gradient accumulation and sensitivity propagation through delayed event queues.
• Repeated compiled execution after reset and root updates.
• Single-parameter fitting and joint optimization of both populations.

All six code cells in synapse_learning.ipynb executed successfully on JAX 0.8.0.

Documentation and static validation

• Checked 967 documentation links and 207 anchors.
• Validated the global TODO structure across 14 modules and 94 tasks.
• Executed the selected Cell, Synapse, and trainable API examples.
• Built Sphinx HTML; the build retained the same 18 existing warnings.
• Passed Ruff checks, applicable pre-commit hooks, and git diff --check.
• Validated the staged notebooks with nbformat and confirmed that the refreshed Channel/Ion notebooks contain no error outputs or changed cell sources.

Detailed acceptance results are recorded in docs/design/optim/current/results/synapse-network-learning.md.

Types of changes

• Breaking change (fix or feature that would cause existing functionality to change)

Checklist

• Code follows the code style of this project.
• Changes follow the CONTRIBUTING guidelines.
• Update necessary documentation accordingly.
• Lint and tests pass locally with the changes.
• Check issues and pull requests first. You don't want to duplicate effort.

Other information

Compatibility considerations:

• Custom Synapse implementations must replace nonempty parameters dictionaries with explicit constructor parameters. Dynamic states continue to use states declarations.
• Rising threshold detection uses last < threshold <= next; reaching the threshold produces an event, while remaining at equality does not repeat it.
  Falling detection uses the reversed comparisons.
• Parameter bindings must be declared before initialization. Connection delay remains static.
• Parameter transforms should maintain constraints such as positive time constants and tau1 < tau2 throughout optimization.

The JAX 0.10.1 result covers the focused suite listed above. Existing combined Ion-suite dtype/cache issues remain documented in the verification record.

This PR is based on reduction and covers five commits, 340f632..20c2bc1.

[sourcery-ai]

Sorry, we are unable to review this pull request

The GitHub API does not allow us to fetch diffs exceeding 20000 lines