Connected population lifecycle | AxoSim documentation

Overview

create_population constructs an actually connected Lite inference simulator from an explicitly supplied model and graph. Persistent state, thresholded recurrent events, native time and delayed deliveries belong to this object. Read the connected population guide for the complete lifecycle. AxoSimPopulation remains the separate supplied-history autograd interface. Reference and fused-neuron backends support the same explicit or deterministic procedural graphs; the historical specialized quantized large-population runtime has a different topology and timing contract.

Source revision: 856207f6de56. Public export index.

InputEvents

axosim.connected_population.InputEvents(neurons: Sequence[int] | torch.Tensor, channels: Sequence[int] | torch.Tensor, values: Sequence[float] | torch.Tensor)

Source

Sparse external inputs in the model’s declared input encoding.

Owns equally sized one-dimensional CPU arrays; duplicate neuron/channel events add. Neuron/channel bounds and input signs are checked before a native step changes runtime state. Channel-encoded inputs must be nonnegative. Signed amplitudes must agree with channel_roles when declared. External values receive no second source-role sign.

Parameters

neurons Sequence[int] | torch.Tensor: required. Integer (events,) destination neuron IDs for one native input sample.
channels Sequence[int] | torch.Tensor: required. Integer (events,) Lite input-channel IDs, paired with neurons.
values Sequence[float] | torch.Tensor: required. Finite (events,) native amplitudes in the declared input convention; no additional source sign is applied.

Attributes

Constructor fields are retained as read-only attributes.

ExplicitConnectome

axosim.connected_population.ExplicitConnectome(sources: Sequence[int] | torch.Tensor, targets: Sequence[int] | torch.Tensor, channels: Sequence[int] | torch.Tensor, delays: Sequence[int] | torch.Tensor, source_roles: Sequence[int] | torch.Tensor, efficacies: Sequence[float] | torch.Tensor)

Source

An exact directed multigraph with one efficacy per retained edge.

The six owned CPU arrays have equal length E. Parallel edges and ragged degrees are retained. Integer source/target bounds [0,n), channel bounds [0,input_dim), consistent source roles (+1/-1), and P4 delays >=4 ms are checked at population construction. Efficacies are independently stored nonnegative float32 magnitudes, including zero for a disabled edge. Edge ID is its original row index.

Parameters

sources Sequence[int] | torch.Tensor: required. Integer (E,) source neuron IDs; outgoing edges of one neuron must share a role.
targets Sequence[int] | torch.Tensor: required. Integer (E,) destination neuron IDs; ragged degrees and parallel edges are preserved.
channels Sequence[int] | torch.Tensor: required. Integer (E,) destination Lite input-channel IDs.
delays Sequence[int] | torch.Tensor: required. Integer (E,) native delivery delays in milliseconds; Lite requires each >=4.
source_roles Sequence[int] | torch.Tensor: required. Integer (E,) source roles, +1 excitatory or -1 inhibitory.
efficacies Sequence[float] | torch.Tensor: required. Finite nonnegative (E,) independent edge magnitudes; zero disables deliveries without deleting the edge.

Attributes

Constructor fields are retained as read-only attributes.

Read-only attributes

ExplicitConnectome.edge_count: int: Number of retained edges, including parallel edges. Source

ProceduralConnectome

axosim.connected_population.ProceduralConnectome(n: int, out_degree: int, input_dim: int, neuron_roles: Sequence[int] | torch.Tensor, channel_roles: Sequence[int] | torch.Tensor, delay_ms: int = 4, seed: int = 0, efficacy: float = 1.0)

Source

Implicit deterministic fan-out graph with an exact efficacy per edge.

Retains nout_degree edges with edge ID sourceout_degree+contact. Target ID is (source+seed+contact*104729)%n; channel cycles through declared channels matching the source role. Self and parallel edges are allowed. Any positive n is supported; source and channel roles must have shapes (n,) and (input_dim,), and each source role requires a matching channel. Topology is computed only for active sources, but exact mutable efficacies still require O(E) storage. This is a deterministic graph, not an empirical connectome or the old tiled unique-channel topology.

Parameters

n int: required. Positive population size; no power-of-two constraint.
out_degree int: required. Positive retained outgoing edge count per source; total E=n*out_degree.
input_dim int: required. Destination input-channel count, matching the supplied Lite model.
neuron_roles Sequence[int] | torch.Tensor: required. Integer (n,) +1/-1 role for each source neuron.
channel_roles Sequence[int] | torch.Tensor: required. Integer (input_dim,) +1/-1 role for each destination input channel.
delay_ms int: default=4. Common native delivery delay in milliseconds; Lite population construction requires >=4.
seed int: default=0. Nonnegative integer <2**31 added to the deterministic target formula; not a random generator state.
efficacy float: default=1.0. Initial nonnegative float32 magnitude copied into all E independently mutable edges.

Attributes

Constructor fields are retained as read-only attributes.

Read-only attributes

ProceduralConnectome.edge_count: int: Exact retained edge count; implicit topology does not discard edges. Source

Methods

ProceduralConnectome.materialize()

ProceduralConnectome.materialize

axosim.connected_population.ProceduralConnectome.materialize() -> ExplicitConnectome

Source

Return an equivalent owned explicit graph, allocating all E edges.

Allocates O(E) CPU edge-index arrays for the equivalent exact explicit multigraph. It preserves every procedural edge ID, role, destination channel, delay and initial efficacy; use for small topology inspection or parity checks.

Returns

graph ExplicitConnectome: Equivalent exact CPU multigraph with all E edge identities and initial efficacies.

PopulationFrame

axosim.connected_population.PopulationFrame(time_ms: int, valid: bool, signals: dict[str, torch.Tensor], neuron_ids: dict[str, torch.Tensor])

Source

Owned selected tensors at one native timestamp.

Signals and matching row identities are selected before copying and stay on the simulation device. Returned frames own ordinary tensors, so later steps and caller edits do not change runtime buffers. valid=False identifies the first four causal-padding samples; spikes are always false there. Before any step, observe has time_ms=-1. The runtime time_ms attribute instead names the next sample to process.

Parameters

time_ms int: required. Processed native sample timestamp; -1 before the first step.
valid bool: required. False for the first four causal-padding samples; true from timestamp 4 ms onward.
signals dict[str, torch.Tensor]: required. Mapping of subscribed signal names to owned selected device tensors.
neuron_ids dict[str, torch.Tensor]: required. Mapping of each signal name to its integer row identities in the same order.

Attributes

Constructor fields are retained as read-only attributes.

ConnectedPopulation

axosim.connected_population.ConnectedPopulation(*, model: AdaptiveSupportP4Surrogate, n: int, connectome: ExplicitConnectome | ProceduralConnectome, morphology_indices: Sequence[int] | torch.Tensor, input_encoding: Literal['signed', 'channel'], channel_roles: Sequence[int] | torch.Tensor | None=None, stream_inputs: StreamInput | None=None, stream_outputs: Mapping[str, Sequence[int] | torch.Tensor | Literal['all']] | None=None, backend: Literal['reference', 'fused']='reference', spike_threshold: float | Sequence[float] | torch.Tensor=0.0, sample_every_ms: int=1, soma_transform: tuple[float, float] | None=None, runtime_coefficients: torch.Tensor | None=None)

Source

A state-owning, closed-loop inference simulator for a supplied Lite model.

Use create_population with the same keyword arguments. The reference backend executes the supplied Lite model on CPU or CUDA. The fused backend requires an explicitly CUDA FP16 Lite model and Triton; it fuses the neuron recurrence/decoder, not the old specialized million-neuron router. Edge efficacies and feature queue accumulation remain float32. stream_outputs=None selects all-neuron spikes; {} selects no signals. sample_every_ms applies to run; step always returns its native frame.

Parameters

model AdaptiveSupportP4Surrogate: keyword-only, required. Explicit trained AxoSimLite model, copied with its weights/configuration. The factory never chooses or initializes weights for you.
n int: keyword-only, required. Positive persistent neuron count.
connectome ExplicitConnectome | ProceduralConnectome: keyword-only, required. ExplicitConnectome or ProceduralConnectome, copied and validated without altering topology/delays.
morphology_indices Sequence[int] | torch.Tensor: keyword-only, required. Integer (n,) assignments into model.config.morphology_ids, one per persistent neuron.
input_encoding Literal['signed', 'channel']: keyword-only, required. Required training-compatible convention: 'signed' applies recurrent E/I sign; 'channel' uses positive counts and inhibitory channel identity/features.
channel_roles Sequence[int] | torch.Tensor | None: keyword-only, default=None. Optional integer (input_dim,) +1/-1 vector for explicit-graph and external-sign validation; the procedural schema carries its own vector.
stream_inputs StreamInput | None: keyword-only, default=None. Deterministic callback(time_ms) or owned timestamp mapping returning InputEvents, dense (n,input_dim) tensors, or None. Arbitrary iterators are rejected.
stream_outputs Mapping[str, Sequence[int] | torch.Tensor | Literal['all']] | None: keyword-only, default=None. Signal-name to neuron-ID-selection mapping; 'all' selects all rows. None defaults to all-neuron spikes; {} selects no signals.
backend Literal['reference', 'fused']: keyword-only, default='reference'. 'reference' executes the actual Lite PyTorch step; 'fused' requires CUDA FP16 plus Triton and fuses neuron recurrence/decoding only.
spike_threshold float | Sequence[float] | torch.Tensor: keyword-only, default=0.0. Finite scalar or (n,) native spike-logit threshold; calibrate on development data. Warmup never emits spikes.
sample_every_ms int: keyword-only, default=1. Positive integer output-sampling cadence for run, aligned to absolute timestamps 0, k, 2k, ...; step always exports its native sample.
soma_transform tuple[float, float] | None: keyword-only, default=None. Optional (positive scale_mv,offset_mv) affine transform: soma_mv=soma_target*scale_mv+offset_mv. Required to request soma_mv.
runtime_coefficients torch.Tensor | None: keyword-only, default=None. Optional finite (n,model.cache_width) packed coefficients. Otherwise compile the model's morphology behavior rows, or use zeros when adaptation is disabled.

Attributes

n int: Persistent population size.
time_ms int: Next native sample timestamp; the latest observed frame has time_ms-1.
backend str: Explicit reference or fused-neuron backend.
device torch.device: Device inherited from the explicitly supplied Lite model.
dtype torch.dtype: Neuron-execution dtype; edge efficacies and the feature queue remain float32.
input_encoding str: Declared signed or channel input convention.
sample_every_ms int: Absolute-timestamp observation cadence used by run.

Read-only attributes

ConnectedPopulation.connectome: ExplicitConnectome | ProceduralConnectome: Owned graph-schema copy; editing it cannot change validated runtime topology. Source
ConnectedPopulation.morphology_indices: torch.Tensor: Integer class assignments into the model's ordered morphology vocabulary; one per batch item or persistent neuron. Source
ConnectedPopulation.efficacies: torch.Tensor: Positive floating-point contact multipliers, shaped by the retained topology. Source
ConnectedPopulation.thresholds: torch.Tensor: Owned ``(n,)`` snapshot of native spike-logit thresholds. Source

Methods

ConnectedPopulation.set_efficacies()
ConnectedPopulation.set_thresholds()
ConnectedPopulation.step()
ConnectedPopulation.run()
ConnectedPopulation.observe()
ConnectedPopulation.state_dict()
ConnectedPopulation.load_state_dict()
ConnectedPopulation.reset()

ConnectedPopulation.set_efficacies

axosim.connected_population.ConnectedPopulation.set_efficacies(edge_ids: Sequence[int] | torch.Tensor, values: Sequence[float] | torch.Tensor) -> None

Source

Set selected nonnegative edge magnitudes; queued deliveries are unchanged.

edge_ids is a unique integer selection into E retained edges; values is an equally sized finite nonnegative array. Values are stored as float32 even for FP16 neuron execution. An emitted event uses its emission-time efficacy; already scheduled deliveries do not change.

Parameters

edge_ids Sequence[int] | torch.Tensor: required. Unique valid integer retained-edge IDs.
values Sequence[float] | torch.Tensor: required. Equally sized finite nonnegative edge magnitudes, stored as float32.

Returns

result None: No return value.

ConnectedPopulation.set_thresholds

axosim.connected_population.ConnectedPopulation.set_thresholds(values: float | Sequence[float] | torch.Tensor) -> None

Source

Replace scalar or per-neuron spike-logit thresholds for future samples.

values is a finite scalar or (n,) vector in spike-logit coordinates. Changes future native threshold decisions; warmup remains spike-free at any finite threshold.

Parameters

values float | Sequence[float] | torch.Tensor: required. Finite scalar or (n,) threshold vector in native spike-logit coordinates.

Returns

result None: No return value.

ConnectedPopulation.step

axosim.connected_population.ConnectedPopulation.step(inputs: InputEvents | torch.Tensor | None=None) -> PopulationFrame

Source

Advance one native millisecond and return an owned subscribed frame.

Advances one native 1-ms sample. Optional sparse InputEvents or dense inputs (n,input_dim) add to the configured native-time stream. The returned frame contains only subscribed signals. At timestamps 3,7,11,… hidden_state is updated from the completed patch; spike/soma values are the current sample from the preceding forecast. State is held between these boundaries.

Parameters

inputs InputEvents | torch.Tensor | None: default=None. Optional InputEvents or dense (n,input_dim) native sample, added to the configured stream at the current timestamp.

Returns

frame PopulationFrame: Owned subscribed signals and row identities at the native sample just processed; population.time_ms now names the next sample.

ConnectedPopulation.run

axosim.connected_population.ConnectedPopulation.run(duration_ms: int) -> Iterator[PopulationFrame]

Source

Yield sampled frames while continuing state for exactly duration_ms steps.

Consuming the iterator advances exactly duration_ms native steps unless iteration is stopped early. Observations are copied/yielded only at absolute timestamps divisible by sample_every_ms; intervening steps still execute. The consumer controls progress, with no background/unbounded output queue. Coarse samples do not aggregate skipped spikes: use sample_every_ms=1 for the complete event history. duration_ms=0 does not advance.

Parameters

duration_ms int: required. Nonnegative integer number of native 1-ms steps to execute when consumed.

Returns

frames Iterator[PopulationFrame]: Owned frames at requested absolute sample timestamps; consuming the iterator executes all intervening native steps.

ConnectedPopulation.observe

axosim.connected_population.ConnectedPopulation.observe(*, neurons: Sequence[int] | torch.Tensor | None=None, signals: Sequence[str] | None=None) -> PopulationFrame

Source

Copy selected current signals without advancing state or time.

Copies selected signals without advancing time. Without arguments, uses the output subscriptions. With signals, neurons selects a shared row order (all neurons when omitted). Known signals: spikes (L,) bool; spike_logit (L,) native logit; soma_target (L,) native coordinate; soma_mv (L,) validated affine millivolts; hidden_state (L,state_dim) learned state; input_features (L,route_feature_dim) current routed input. soma_mv requires soma_transform=(positive scale_mv,offset_mv).

Parameters

neurons Sequence[int] | torch.Tensor | None: keyword-only, default=None. Selected neuron IDs in desired row order; omit for all neurons when signals is supplied.
signals Sequence[str] | None: keyword-only, default=None. Known signal names; omit to use output subscriptions. Supplying neurons requires an explicit signals selection.

Returns

frame PopulationFrame: Owned selected current signals and neuron IDs without any time/state advance.

ConnectedPopulation.state_dict

axosim.connected_population.ConnectedPopulation.state_dict() -> dict[str, object]

Source

Return owned device tensors sufficient for queue/phase/state replay.

Returns owned runtime tensors: learned state, partial patch, forecasts, delayed queue, current routed features/outputs/spikes, thresholds, direct coefficients and exact efficacies, plus version, clock, validity and model/topology fingerprint. Save with torch.save; read with torch.load(…,weights_only=True). Recreate the same model/topology/encoding/backend; weights and topology are not embedded. A native-time input callback must reproduce the same value on replay; arbitrary callback/random state is not saved.

Returns

state dict[str, object]: Owned runtime tensors, native clock/validity, schema version and model/topology identity fingerprint; weights and external callback state are not embedded.

ConnectedPopulation.load_state_dict

axosim.connected_population.ConnectedPopulation.load_state_dict(state: Mapping[str, object]) -> None

Source

Restore a compatible owned snapshot; reject mismatch before mutation.

Checks identity, time/validity, complete tensor schema, shapes, dtypes, finite values and nonnegative efficacies before any runtime mutation. Compatible tensor values are transferred to the execution device. The external stream remains the configured callback or owned timestamp mapping.

Parameters

state Mapping[str, object]: required. Owned compatible runtime snapshot returned by state_dict or read with weights_only=True.

Returns

result None: No return value.

ConnectedPopulation.reset

axosim.connected_population.ConnectedPopulation.reset() -> None

Source

Restore construction-time clock, state, empty queue, thresholds and efficacies.

Restores construction-time state, zero clock, empty delayed queue, initial forecasts/patch, original thresholds, runtime coefficients and exact edge efficacies. External callbacks must likewise return their original timestamp-dependent inputs.

Returns

result None: No return value.

create_population

axosim.connected_population.create_population(*, model: AdaptiveSupportP4Surrogate, n: int, connectome: ExplicitConnectome | ProceduralConnectome, morphology_indices: Sequence[int] | torch.Tensor, input_encoding: Literal['signed', 'channel'], channel_roles: Sequence[int] | torch.Tensor | None=None, stream_inputs: StreamInput | None=None, stream_outputs: Mapping[str, Sequence[int] | torch.Tensor | Literal['all']] | None=None, backend: Literal['reference', 'fused']='reference', spike_threshold: float | Sequence[float] | torch.Tensor=0.0, sample_every_ms: int=1, soma_transform: tuple[float, float] | None=None, runtime_coefficients: torch.Tensor | None=None) -> ConnectedPopulation

Source

Create an actually connected Lite inference simulation from supplied weights.

The model is mandatory and must be AxoSimLite (AdaptiveSupportP4Surrogate). Morphology indices have shape (n,) and address the model’s declared vocabulary. One native step is 1 ms, and recurrent delays must be integer >=4 ms; graph delays are never adjusted. ‘signed’ applies the source role to recurrent event amplitude; ‘channel’ uses nonnegative counts with inhibition encoded by channel identity/features. External amplitudes are already in that convention. Every outgoing edge of a source must declare the same role, and channel_roles validates destination-channel compatibility when supplied. Model weights, graph topology, morphology assignments and initial banks are copied rather than borrowed. The connected threshold/event loop is inference-only.

Parameters

model AdaptiveSupportP4Surrogate: keyword-only, required. Explicit trained AxoSimLite model, copied with its weights/configuration. The factory never chooses or initializes weights for you.
n int: keyword-only, required. Positive persistent neuron count.
connectome ExplicitConnectome | ProceduralConnectome: keyword-only, required. ExplicitConnectome or ProceduralConnectome, copied and validated without altering topology/delays.
morphology_indices Sequence[int] | torch.Tensor: keyword-only, required. Integer (n,) assignments into model.config.morphology_ids, one per persistent neuron.
input_encoding Literal['signed', 'channel']: keyword-only, required. Required training-compatible convention: 'signed' applies recurrent E/I sign; 'channel' uses positive counts and inhibitory channel identity/features.
channel_roles Sequence[int] | torch.Tensor | None: keyword-only, default=None. Optional integer (input_dim,) +1/-1 vector for explicit-graph and external-sign validation; the procedural schema carries its own vector.
stream_inputs StreamInput | None: keyword-only, default=None. Deterministic callback(time_ms) or owned timestamp mapping returning InputEvents, dense (n,input_dim) tensors, or None. Arbitrary iterators are rejected.
stream_outputs Mapping[str, Sequence[int] | torch.Tensor | Literal['all']] | None: keyword-only, default=None. Signal-name to neuron-ID-selection mapping; 'all' selects all rows. None defaults to all-neuron spikes; {} selects no signals.
backend Literal['reference', 'fused']: keyword-only, default='reference'. 'reference' executes the actual Lite PyTorch step; 'fused' requires CUDA FP16 plus Triton and fuses neuron recurrence/decoding only.
spike_threshold float | Sequence[float] | torch.Tensor: keyword-only, default=0.0. Finite scalar or (n,) native spike-logit threshold; calibrate on development data. Warmup never emits spikes.
sample_every_ms int: keyword-only, default=1. Positive integer output-sampling cadence for run, aligned to absolute timestamps 0, k, 2k, ...; step always exports its native sample.
soma_transform tuple[float, float] | None: keyword-only, default=None. Optional (positive scale_mv,offset_mv) affine transform: soma_mv=soma_target*scale_mv+offset_mv. Required to request soma_mv.
runtime_coefficients torch.Tensor | None: keyword-only, default=None. Optional finite (n,model.cache_width) packed coefficients. Otherwise compile the model's morphology behavior rows, or use zeros when adaptation is disabled.

Returns

population ConnectedPopulation: State-owning Lite inference simulator with closed-loop delayed recurrence, exact edge efficacies and selected timestamped observations.