DPointNet contributor reference#

This page is for contributors and authors of custom execution loops, not a first-run configuration recipe. Current user guidance lives in DPointNet, DPointNet defaults and configuration migration and DPointNet performance and GPU setup.

GLIF3Cell gradient-control API#

The constructor retains old positional argument slots for compatibility. Its parameter documentation marks deprecated aliases and their replacements; the migration table also covers JSON configurations.

class bmtk.simulator.dpointnet.cell_models.glif3_cell.GLIF3Cell
Parameters:

  • spike_surrogate – Preferred selector: "gaussian" (default) or "triangular".

  • spike_surrogate_width – Preferred Gaussian width (default 0.28).

  • spike_surrogate_gain – Preferred surrogate gain (default 0.05).

  • recurrent_spike_gradient_scale – Preferred recurrent gradient retention (default 1.0).

  • voltage_state_gradient_scale – Preferred voltage gradient retention in [0, 1] (default 1.0).

  • gauss_std – Deprecated compatibility alias for spike_surrogate_width.

  • dampening_factor – Deprecated compatibility alias for spike_surrogate_gain.

  • recurrent_dampening_factor – Deprecated compatibility alias for recurrent_spike_gradient_scale.

  • voltage_gradient_dampening – Deprecated removed fraction; convert to voltage_state_gradient_scale = 1 - clip(value, 0, 1).

  • pseudo_gauss – Deprecated Boolean selector; True maps to "gaussian", False to "triangular".

Explicit aliases emit FutureWarning; omitted aliases do not warn. Existing values and positional slots remain supported, with no scheduled removal version. Supplying both names for one control raises ValueError.

Terminology#

  • Canonical weights: trainable variables in SONATA edge-row order.

  • CSR: compressed sparse row, an internal connectivity layout grouped by source neuron rather than original edge order.

  • Compute shadow: a refreshed, possibly lower-precision copy of a master weight used by the forward computation.

  • Weight carrier: a differentiable loop input whose backward value accumulates weight derivatives; an FP32 carrier does not imply FP32 spike or current derivatives.

  • VJP: vector-Jacobian product, the backward propagation of a supplied output derivative through an operation.

Canonical weights and gradients#

Preserve SONATA neuron and edge-row identity. Trainable FP32 masters, optimizer slots, constraints, checkpoints, regularizers and exports remain canonical; source-CSR shadows are internal compute representations. Restore CSR dynamics gradients exactly once at their enclosing training boundary before composing canonical regularizer gradients or applying an optimizer. Match distributed masters and replica components by exact identity, never names.

Refresh recurrent and all trainable named-input ordinary/CSR shadows after updates, explicit assignment, restore or local plasticity. Frozen masters must not leave stale nonzero compute shadows. Preserve Dale’s law, configured bounds and duplicate-edge ordering; do not prune silent-neuron spike adjoints. Preserve Poisson counts, invocation-local replay/RNG state, external delay history and NEST end-of-step timestamps.

Automatic direct-CSR gradients require a training-engine or FP32-temporal restoration boundary. Bare cells and inference-only RNNs retain canonical gradients. Type-indexed state dispatch checks current coefficient identity; static dispatch is an explicit assumption that those coefficients cannot change.

Custom runners and FP32 temporal gradients#

The supported FP32 temporal route uses TemporalAdjointRunner or ExplicitStateRNN with selective forward state. The reverse pass uses FP32 state/projection derivatives and can record the original compute-precision currents to preserve the primal trajectory. recompute is approximate when atomic projections are nondeterministic.

Do not wrap this runner in a second segmented gradient runner or restore CSR order twice. A private tf.while_loop with FP32 weight carriers is not automatically this route: inspect every state/current/spike derivative dtype. fused_recurrent_weight_carry(vjp_only=True) requires FP32 operands; ordinary direct-loop use supplies compute-dtype primal currents. External custom runners must wire their input and recurrent carrier surfaces. Explicit packed/small-batch FP16 backward requests are incompatible with the FP32 temporal route.

Online loss channels#

Register state-dependent loss channels before model construction. Retain FP32 online accumulators under mixed precision and preserve the chosen physical-state policy. For VoltageRateFloor, preserve pre-reset voltage semantics and refractory gating without changing spikes or reset/ASC derivatives.

Rate-history updates happen only after accepted optimizer updates, never during validation, replay or a rejected loss-scaled step. Pool rates across the actual combined batch; series and accumulated updates have different commit boundaries. Serialize history and reconstruct the same channel configuration before restore. The initial gate is inactive until measured rates are committed or explicitly initialized, not an assumed all-silent population.

Connectivity preprocessing#

build_csr_connectivity deduplicates compact (post, synapse_type) pairs with uint64 keys when ranges fit. The original tuple path handles unrepresentable ranges/strides. Stable packed (source, target, synapse_type) sorting preserves the original lexicographic permutation, including duplicates. lex_sort_order_np similarly packs nonnegative integer pairs; signed, floating, empty or overflowing cases retain the original lexsort.

Use unsigned integer arithmetic, never float64 keys or approximate ordering. Compare packed-key paths with independent tuple/lexsort references and test overflow, signed, floating and empty cases. These optimizations require no user configuration or persistent cache and do not change model/RNG initialization.

Compatibility implementation#

Below compute capability 7.0, scalar half accumulation uses TensorFlow’s compare-and-swap helper and duplicate-target warp grouping uses shuffle/ballot matching. Preserve grouping and live silent-neuron derivatives. Pre-Volta LGN filtering uses bounded extract-patches/matrix multiplication, retaining padding, normalization and multichannel temporal filtering. Do not generalize that input-specific route into a blanket convolution fallback.

Alpha-basis fitting uses shared time constants and unconstrained per-class least squares. Its objective is the unweighted mean waveform error; acceptance uses the maximum per-class relative RMS error. Preserve distinct kinetic-class identity, supplied coefficients and metadata. Automatic tolerance relaxation, amplitude renormalization, nonnegative coefficient constraints and neuron-frequency weighting would change the fitting method.

Validation and attribution#

Test independent values and VJPs, canonical ordering, live coefficients, distributed identity, replay, state/delay/RNG carry and strict model/optimizer restore. Keras3 success does not replace actual Keras2 symbolic-state testing. Rebuild both architecture-covered operators after CUDA/signature/ABI edits. Do not relax tolerances, precision, clipping or scientific constraints to pass.

Variable-batch tiles, scaled-half projection and sparse weight accumulation adapt Javier Galvan’s JavierGalvan9/V1_GLIF_model implementation; retain the source attribution and exact revision comments in the corresponding code.

Alpha fitting and drifting-grating input placement also draw on JavierGalvan9/V1_GLIF_model at 2c52ec10c1eee409ddf900f8a5b8460cf9c46d24. The alpha fitting reference is synaptic_data/alpha_basis_calculation.ipynb. Preserve attribution while distinguishing generalized network-fitting bounds and DPointNet’s seeded broadcast trial assignment from that reference implementation.