Recordings

_allocate_records!(P, C, S, dt::Float32, duration::Float32)

Pre-allocate dense recording buffers and the flat :fire COO event list for every monitored component. Idempotent across chunked sim! calls: a key already allocated at the same dt is skipped; on dt mismatch the buffer is reallocated.

_ensure_fire_capacity!(rec, meta, need)

Make room for need more spikes in the :fire COO buffers (called once per step, before the writes). If the countdown meta[:allocated][:fire] is short, the buffers grow to max(2 * capacity, written + need, 1) slots, keeping the written prefix, with one warning per recording.

_fire_mask!(meta, ind, N, owner = nothing)

Membership mask (length N) of the recorded subset ind, and whether ind is strictly increasing. Cached in meta until ind is another vector or N changes; rebuilt at every sim!/train! call (in-place edits of ind within a manual loop are not seen). Throws ArgumentError if an index is outside 1:N.

add_endtime!(model::NamedTuple)

For every monitored key of every component of model that has no end time, set records[:end_time][key] to the current model time. Used for records loaded from older files.

add_starttime!(model::NamedTuple)

For every monitored key of every component of model that has no start time, set records[:start_time][key] = 0. Used for records loaded from older files.

clear_monitor!(obj)

Remove all monitoring from obj by deleting every entry in obj.records. Unlike clear_records!, which empties data but preserves the monitoring schema, this function removes the schema too — monitor! must be called again before the next sim.

clear_records!(objs::AbstractArray)

Call clear_records! on each element of objs.

clear_records!(obj, sym::Symbol)

Delete the recorded data of the key sym of obj only, keeping it monitored.

clear_records!(obj)

Delete the recorded data of obj (a component, or a model/NamedTuple/collection of components, recursing into groups) but keep the monitoring set-up: the next sim! records the same variables again, with new start and end times.

get_dt(T::Time)

Get the time step size.

Arguments

• T::Time: The Time object.

Returns

• Float32: The time step size.

get_interval(T::Time)

Time points dt:dt:get_time(T) (ms) of the steps simulated so far, in the precision of the clock.

get_measure_interval(p, sym::Symbol, steps::Int)
get_measure_interval(p, sym::Symbol, step::AbstractFloat)

Time range from p.records[:start_time][sym] to p.records[:end_time][sym], with steps points or with step step (ms).

get_step(T::Time)

Get the current simulation step counter (integer number of dt steps elapsed).

Arguments

• T::Time: The Time object.

Returns

• Float32: The step counter T.tt[1], cast to Float32.

get_time(T::Time)
get_time(model::NamedTuple)

Current simulation time in ms (T.t[1], or model.time.t[1] for a model built with compose), in the precision of the clock.

getrecord(p, sym)

Return the raw storage p.records[sym] (for dense records the full pre-allocated buffer, including unwritten slots; prefer getvariable). Throws ArgumentError if sym is not recorded.

getvariable(obj, key::Symbol, id = nothing)

Raw recorded samples of key, without interpolation, with time as the last dimension (neurons x samples for a vector field). For dense records this is a view on the buffer restricted to the samples written so far; id selects an index (or indices) along the first dimension. Legacy records are concatenated into a new array.

interpolated_record(p, sym, τ = 20ms)

Return (y, r): the recording sym of p as an Interpolations object y with time as the last axis, and the range r of time points (ms) assigned to the samples. It is evaluated with call syntax, y(i, t) (indices or ranges), at any t within r (linear interpolation; singleton dimensions are not interpolated). Indexing with square brackets and a non-integer time does not work.

Samples are taken at the steps whose global step counter is a multiple of the sampling period (including t = 0 for a fresh model). r spans from the time of the first sample to the time of the last one (records[:start_time][sym] to records[:end_time][sym]) with as many points as samples, so it is the exact sample-time axis, also when monitoring starts after t = 0 or the simulated time is not a multiple of the sampling period.

For sym == :fire it returns firing_rate(p, τ = τ).

monitor!(obj, keys; sr = 1000Hz, variables = :none, monitor_time = nothing, monitor_rate = nothing, verbose = false)
monitor!(objs::Union{Array,NamedTuple}, keys; sr = 200Hz, kwargs...)
monitor!(obj, keys, variables::Symbol; kwargs...)

Register variables of a population, connection or stimulus for recording during the next sim!/train! calls. keys is a Symbol, a (Symbol, indices) tuple, or a vector of them. Buffers are allocated just before the time loop starts (_allocate_records!), not here.

Arguments

• obj: an AbstractPopulation, AbstractConnection or AbstractStimulus. For a vector or a NamedTuple (e.g. model.pop) the call is repeated on each element, and the default sampling rate is then 200Hz instead of 1000Hz.
• keys: field names of obj (e.g. :v, :w, :W, :ρ, :fire). A tuple (sym, indices) records only the listed elements of a vector field.
• sr = 1000Hz: sampling rate. The sampling period is max(1, round(1 / (sr * dt))) steps, so sr larger than 1/dt records every step. Ignored for :fire.
• variables = :none: name of a nested field holding the variables, e.g. :STPVars or :LTPVars of a SpikingSynapse, or :synvars. The key sym is then read from obj.<variables>.<sym> and stored as Symbol(variables, "_", sym), e.g. :STPVars_u. The positional form monitor!(obj, keys, :STPVars) is equivalent. Variables of a plasticity rule are recorded at their value at the sampling time, read through plasticity_value (lazily decayed traces are not stored at that value; reading the field directly returns the stored value). Recording never changes the state. A lazily stored variable without a plasticity_value method is an ArgumentError.
• monitor_time: capacity hint in ms used to size the buffers (default: the duration of the sim! call, at least 1 s). Recording beyond the capacity is still correct: the buffer is doubled with a one-time warning.
• monitor_rate: expected maximum firing rate, with units (e.g. 50Hz), used to size the :fire buffers (default 20Hz). A plain number (any value above 1kHz) is an ArgumentError.
• verbose = false: warn about keys already monitored or not found.

Storage

• :fire is stored as a list of (time, neuron) events; read it with spiketimes(obj), firing_rate, or record(obj, :fire; interval).
• Float32 scalars, Vector{Float32} (also with indices), and Matrix{Float32} / Array{Float32,3} without indices are stored in a dense array with time as the last dimension; read with getvariable (raw samples) or record (interpolated in time).
• Other field types (e.g. matrices with indices, vectors of vectors) are stored as a vector of snapshots.
• A first sample is taken at t = 0 when the model time is 0.

Already-monitored keys and missing fields are skipped silently (with a warning if verbose = true).

With (:fire, indices) only the spikes of the listed neurons are recorded (with their original neuron indices, so spiketimes still returns one entry per neuron of the population). An index outside 1:N throws an ArgumentError at the first step of the next sim!/train!.

Example

using SpikingNeuralNetworks
SNN.@load_units
E = SNN.IF(N = 100)
stim = SNN.Stimulus(SNN.PoissonFixed(rate = 2kHz), E, :ge)
SNN.monitor!(E, [:v, :fire]; sr = 2kHz)
SNN.monitor!(E, [(:w, [1, 2, 3])])
model = SNN.compose(; E, stim)
SNN.sim!(; model, duration = 200ms)
v = SNN.getvariable(E, :v)          # 100 x 401 samples
st = SNN.spiketimes(E)

record!(obj, T::Time)

Record all monitored variables of obj at the current time T. Dispatches to the dense or legacy path per meta[:mode][key]. Called every dt inside the sim loop.

record(p, sym::Symbol; range = false, interval = nothing, interpolate = true, variables = nothing, kwargs...)
record(p, sym::Symbol, interval::AbstractRange; kwargs...)
record(pops, sym::Symbol; interval, interpolate = true, kwargs...)

Read a recording of a population, connection or stimulus p.

• sym == :fire: firing rates computed by firing_rate(p, interval; interpolate, kwargs...); interval (an AbstractRange, ms) is required.
• sym == :spiketimes or :spikes: returns spiketimes(p) (ignores range).
• any other sym: with interpolate = true (default) an interpolation object over time, as returned by interpolated_record, resampled on interval if given; with interpolate = false the raw samples getvariable(p, sym) (and r = interval).
• variables: name of the variable group used in monitor! (e.g. :STPVars); the key read is Symbol(variables, "_", sym). Equivalent to passing :STPVars_u directly.
• range = true returns (v, r) instead of v.

The method on a collection pops stacks the interpolated recordings of all elements sampled on interval (required); elements that do not record sym contribute no rows.

Example

using SpikingNeuralNetworks
SNN.@load_units
E = SNN.IF(N = 50)
stim = SNN.Stimulus(SNN.PoissonFixed(rate = 2kHz), E, :ge)
SNN.monitor!(E, [:v, :fire])
model = SNN.compose(; E, stim)
SNN.sim!(; model, duration = 500ms)
v = SNN.record(E, :v)                   # interpolated: v(1, 100.5ms)
v, r = SNN.record(E, :v, range = true)  # r: time axis in ms
v_raw = SNN.record(E, :v, interpolate = false)
fr, r = SNN.record(E, :fire; interval = 0:10ms:500ms, range = true)
st = SNN.record(E, :spikes)

record_fire!(fire, fire_rec, T, indices)

Legacy fire recorder. Appends the current timestep's spike set to the jagged :time / :neurons vectors in fire_rec. Used when meta[:mode][:fire] == :legacy. The dense path uses record_fire_dense! instead, which writes into pre-allocated COO buffers without allocating.

record_fire_dense!(obj, fire, records, meta, T, indices)

Append the spikes of this step of obj (time Float32(get_time(T)), neuron id) to the COO buffers records[:fire][:times_buf], [:neurons_buf], in ascending neuron order (from _fire_step_list). With indices[:fire] only the listed neurons are recorded; an unsorted or repeated index list is visited in its own order.

record_sym!(my_record, obj, key, T, indices, sr)

Legacy variable recorder. Appends a snapshot of my_record to obj.records[key] at the rate set by sr. Gated by record_step. Used when meta[:mode][key] == :legacy. The dense path uses record_sym_dense! instead.

reset_time!(T::Time)
reset_time!(model::NamedTuple)

Set the time to 0 and the step counter to 0 (for a model, its model.time). Recordings are not cleared; use clear_records! for that.

update_time!(T::Time, dt)
update_time!(T::Time, myT::Time)

Advance the clock by one step: T.t[1] += dt and the step counter T.tt[1] += 1. Called at the beginning of every sim!/train! step, before the stimuli. The second method copies time and step counter from myT into T.