API reference
GRU temporal models
Signatures, parameters, return contracts, and source for gru temporal models.
Overview
AxoTemporalModel wraps the common backbone with a selected temporal core. Named public GRU profiles use this class. Full-sequence forward calls reset temporal state; streaming calls use an explicitly allocated persistent state. Low-level temporal cores and behavior adapters are included below for direct construction.
Source revision: caef7be03abd. Public export index.
AxoTemporalStreamingState
axosim.temporal_core.AxoTemporalStreamingState(core_state: torch.Tensor | tuple[torch.Tensor, torch.Tensor], local_tcn_histories: list[torch.Tensor], morphology_feature_gains: torch.Tensor | None, patch_sum: torch.Tensor | None = None, patch_correction: torch.Tensor | None = None, patch_position: int = 0)
Mutable online state for a replacement temporal core.
Parameters
core_statetorch.Tensor | tuple[torch.Tensor, torch.Tensor]- required.
local_tcn_historieslist[torch.Tensor]- required.
morphology_feature_gainstorch.Tensor | None- required.
patch_sumtorch.Tensor | None- default=None.
patch_correctiontorch.Tensor | None- default=None.
patch_positionint- default=0.
Attributes
Constructor fields are retained as attributes.
AxoTemporalCoreConfig
axosim.temporal_core.AxoTemporalCoreConfig(kind: TemporalCoreKind, gru_hidden_units: int | None = None, branch_memory_units: int = 30, branch_hidden_units: int = 64, branch_synapse_decay: float = 0.85, branch_memory_decay: float = 0.9, residual_scale_init: float = 0.1, keep_local_tcn: bool = False, gru_layers: int = 1, dropout: float = 0.0, patch_size: int = 1, behavior_adapter_morphology_id: str | None = None, behavior_adapter_rank: int = 0, behavior_adapter_branch_token_offset: bool = False)
Configuration for a temporal core behind the shared AxoMamba encoder.
Parameters
kindTemporalCoreKind- required.
gru_hidden_unitsint | None- default=None.
branch_memory_unitsint- default=30.
branch_hidden_unitsint- default=64.
branch_synapse_decayfloat- default=0.85.
branch_memory_decayfloat- default=0.9.
residual_scale_initfloat- default=0.1. Initial learned multiplier on the residual update.
keep_local_tcnbool- default=False.
gru_layersint- default=1. Residual GRU layers; more than one builds a StackedResidualGRUTemporalCore, which does not support streaming inference.
dropoutfloat- default=0.0. Training dropout on the GRU residual correction, in [0, 1).
patch_sizeint- default=1. Native timesteps represented by one block.
behavior_adapter_morphology_idstr | None- default=None.
behavior_adapter_rankint- default=0.
behavior_adapter_branch_token_offsetbool- default=False.
Attributes
Constructor fields are retained as read-only attributes.
NeuronBehaviorAdapter
axosim.temporal_core.NeuronBehaviorAdapter(*, branches: int, width: int, outputs: int, morphology_index: int, rank: int=0, branch_token_offset: bool=False)
Neuron-specific response parameters around shared GRU dynamics.
Bases: nn.Module.
Parameters
branchesint- keyword-only, required. Number of routed branch features in the adapter.
widthint- keyword-only, required. Feature width of the behavior adapter or population recurrence.
outputsint- keyword-only, required. Number of readout channels.
morphology_indexint- keyword-only, required. Index of the morphology row to select.
rankint- keyword-only, default=0. Low-rank adapter factor width.
branch_token_offsetbool- keyword-only, default=False. Include adaptation offsets for encoded branch tokens.
Read-only attributes
StackedResidualGRUTemporalCore
axosim.temporal_core.StackedResidualGRUTemporalCore(layers: list[nn.Module])
Several residual GRU layers applied in sequence (full-sequence use).
Bases: nn.Module.
Parameters
layerslist[nn.Module]- required. Residual GRU layers applied in sequence; adapter deltas apply to the first layer only.
Methods
StackedResidualGRUTemporalCore.forward
axosim.temporal_core.StackedResidualGRUTemporalCore.forward(hidden: torch.Tensor, **kwargs) -> torch.Tensor
Predict native spike and soma outputs for the supplied sequence.
Parameters
hiddentorch.Tensor- required. Hidden recurrent state for the selected temporal core.
kwargsunannotated- variadic. Keyword arguments passed to the first layer only.
Returns
torch.Tensor
ResidualGRUTemporalCore
axosim.temporal_core.ResidualGRUTemporalCore(width: int, *, hidden_units: int | None=None, residual_scale_init: float, dropout: float=0.0)
Vendor-fused GRU with the same residual contract as AxoMamba blocks.
Bases: nn.Module.
Parameters
widthint- required. Feature width of the behavior adapter or population recurrence.
hidden_unitsint | None- keyword-only, default=None. Width of the hidden feature layer.
residual_scale_initfloat- keyword-only, required. Initial learned multiplier on the residual update.
dropoutfloat- keyword-only, default=0.0. Training dropout on the residual correction, in [0, 1).
Read-only attributes
ResidualGRUTemporalCore.recurrent_state_elements: int- Source
Methods
ResidualGRUTemporalCore.forward
axosim.temporal_core.ResidualGRUTemporalCore.forward(hidden: torch.Tensor, *, weight_ih_delta: torch.Tensor | None=None, weight_hh_delta: torch.Tensor | None=None, adapter_mask: torch.Tensor | None=None) -> torch.Tensor
Predict native spike and soma outputs for the supplied sequence.
Parameters
hiddentorch.Tensor- required. Hidden recurrent state for the selected temporal core.
weight_ih_deltatorch.Tensor | None- keyword-only, default=None. Optional correction to GRU input-to-hidden weights.
weight_hh_deltatorch.Tensor | None- keyword-only, default=None. Optional correction to GRU hidden-to-hidden weights.
adapter_masktorch.Tensor | None- keyword-only, default=None. Mask selecting members that receive the adapter correction.
Returns
torch.Tensor
ResidualGRUTemporalCore.temporal_correction
axosim.temporal_core.ResidualGRUTemporalCore.temporal_correction(hidden: torch.Tensor, *, weight_ih_delta: torch.Tensor | None=None, weight_hh_delta: torch.Tensor | None=None, adapter_mask: torch.Tensor | None=None) -> torch.Tensor
Compute the temporal correction for encoded features.
Parameters
hiddentorch.Tensor- required. Hidden recurrent state for the selected temporal core.
weight_ih_deltatorch.Tensor | None- keyword-only, default=None. Optional correction to GRU input-to-hidden weights.
weight_hh_deltatorch.Tensor | None- keyword-only, default=None. Optional correction to GRU hidden-to-hidden weights.
adapter_masktorch.Tensor | None- keyword-only, default=None. Mask selecting members that receive the adapter correction.
Returns
torch.Tensor
BranchELMTemporalCore
axosim.temporal_core.BranchELMTemporalCore(width: int, *, memory_units: int, hidden_units: int, synapse_decay: float, memory_decay: float, residual_scale_init: float)
Leaky branch/memory recurrence behind the shared biological encoder.
Bases: nn.Module.
Parameters
widthint- required. Feature width of the behavior adapter or population recurrence.
memory_unitsint- keyword-only, required. Width of the recurrent memory state.
hidden_unitsint- keyword-only, required. Width of the hidden feature layer.
synapse_decayfloat- keyword-only, required. Decay coefficient of the synaptic trace.
memory_decayfloat- keyword-only, required. Decay coefficient of recurrent memory.
residual_scale_initfloat- keyword-only, required. Initial learned multiplier on the residual update.
Read-only attributes
BranchELMTemporalCore.recurrent_state_elements: int- Source
Methods
BranchELMTemporalCore.forward
axosim.temporal_core.BranchELMTemporalCore.forward(hidden: torch.Tensor) -> torch.Tensor
Predict native spike and soma outputs for the supplied sequence.
Parameters
hiddentorch.Tensor- required. Hidden recurrent state for the selected temporal core.
Returns
torch.Tensor
BranchELMTemporalCore.temporal_correction
axosim.temporal_core.BranchELMTemporalCore.temporal_correction(hidden: torch.Tensor) -> torch.Tensor
Compute the temporal correction for encoded features.
Parameters
hiddentorch.Tensor- required. Hidden recurrent state for the selected temporal core.
Returns
torch.Tensor
CausalPatchedTemporalCore
axosim.temporal_core.CausalPatchedTemporalCore(core: nn.Module, *, width: int, patch_size: int)
Run a temporal core on causal patch means and delay its correction.
Bases: nn.Module.
Parameters
corenn.Module- required. Temporal core instance used by the wrapper.
widthint- keyword-only, required. Feature width of the behavior adapter or population recurrence.
patch_sizeint- keyword-only, required. Native timesteps represented by one block.
Read-only attributes
CausalPatchedTemporalCore.recurrent_state_elements: int- Source
Methods
CausalPatchedTemporalCore.forward
axosim.temporal_core.CausalPatchedTemporalCore.forward(hidden: torch.Tensor, **temporal_kwargs) -> torch.Tensor
Predict native spike and soma outputs for the supplied sequence.
Parameters
hiddentorch.Tensor- required. Hidden recurrent state for the selected temporal core.
temporal_kwargsunannotated- variadic. Keyword options forwarded to temporal-core construction.
Returns
torch.Tensor
AxoTemporalModel
axosim.temporal_core.AxoTemporalModel(source: BranchOfficialMamba, temporal_config: AxoTemporalCoreConfig)
Shared AxoMamba encoder/heads with an interchangeable temporal core.
Bases: nn.Module.
Parameters
sourceBranchOfficialMamba- required.
temporal_configAxoTemporalCoreConfig- required. Temporal-core selection and its recurrence/adaptation settings.
Read-only attributes
AxoTemporalModel.config- Configuration retained by the model or its shared backbone. Source
AxoTemporalModel.num_input: int- Native input-channel count. Source
AxoTemporalModel.num_output: int- Readout-channel count. Source
AxoTemporalModel.num_branch: int- Branched input-feature count. Source
AxoTemporalModel.base_soma_prediction: torch.Tensor | None- Most recently retained base soma prediction, when available. Source
Methods
AxoTemporalModel.forward()AxoTemporalModel.allocate_streaming_state()AxoTemporalModel.streaming_step()AxoTemporalModel.streaming_step_events()AxoTemporalModel.recurrent_state_bytes()AxoTemporalModel.component_manifest()
AxoTemporalModel.forward
axosim.temporal_core.AxoTemporalModel.forward(x: torch.Tensor, *, morphology_indices: torch.Tensor | None=None) -> torch.Tensor
Predict native spike and soma outputs for the supplied sequence.
x is (B,T,num_input), with integer morphology_indices (B,) when morphology conditioning or behavior adaptation is configured. Returns (B,T,num_output). Each sequence forward initializes the core state.
Parameters
xtorch.Tensor- required. Input tensor for the full-sequence or streaming operation.
morphology_indicestorch.Tensor | None- keyword-only, default=None. Integer class assignments into the model's ordered morphology vocabulary; one per batch item or persistent neuron.
Returns
predictiontorch.Tensor- Spike-logit and soma-target channels in the tensor shape specified above.
AxoTemporalModel.allocate_streaming_state
axosim.temporal_core.AxoTemporalModel.allocate_streaming_state(batch_size: int, *, device: torch.device | str | None=None, dtype: torch.dtype | None=None) -> AxoTemporalStreamingState
Allocate exact online state without retaining native-rate history.
Allocates an AxoTemporalStreamingState for batch_size on the requested device and dtype; the state contains temporal-core values and causal local-filter histories.
Parameters
batch_sizeint- required. Examples processed per batch.
devicetorch.device | str | None- keyword-only, default=None. Execution or allocation device.
dtypetorch.dtype | None- keyword-only, default=None. Floating-point execution or allocation dtype.
Returns
stateAxoTemporalStreamingState- Fresh temporal-core buffers and local-filter histories for the selected batch, device, and dtype.
AxoTemporalModel.streaming_step
axosim.temporal_core.AxoTemporalModel.streaming_step(x: torch.Tensor, state: AxoTemporalStreamingState, *, morphology_indices: torch.Tensor | None=None) -> torch.Tensor
Advance one dense native-rate timestep.
Advances one native input step using persistent state. The guide supplies x as (B,num_input) and morphology_indices as (B,) when required. Returns (B,1,num_output).
Parameters
xtorch.Tensor- required. Input tensor for the full-sequence or streaming operation.
stateAxoTemporalStreamingState- required. Temporal state returned by the matching initial-state or allocation method.
morphology_indicestorch.Tensor | None- keyword-only, default=None. Integer class assignments into the model's ordered morphology vocabulary; one per batch item or persistent neuron.
Returns
predictiontorch.Tensor- One native output step (batch,1,num_output); the supplied state is updated in place.
AxoTemporalModel.streaming_step_events
axosim.temporal_core.AxoTemporalModel.streaming_step_events(event_indices: torch.Tensor, event_values: torch.Tensor, state: AxoTemporalStreamingState, *, morphology_indices: torch.Tensor | None=None, chunk_size: int | None=None, output_buffer: torch.Tensor | None=None, retain_base_soma_prediction: bool=True) -> torch.Tensor
Advance one timestep from padded sparse channel/value rows.
Parameters
event_indicestorch.Tensor- required.
event_valuestorch.Tensor- required. Signed floating-point event amplitudes, one per paired address.
stateAxoTemporalStreamingState- required. Temporal state returned by the matching initial-state or allocation method.
morphology_indicestorch.Tensor | None- keyword-only, default=None. Integer class assignments into the model's ordered morphology vocabulary; one per batch item or persistent neuron.
chunk_sizeint | None- keyword-only, default=None. Chunk length for the supported Mamba or streaming execution path.
output_buffertorch.Tensor | None- keyword-only, default=None. Optional preallocated output tensor for the operation.
retain_base_soma_predictionbool- keyword-only, default=True. Keep the base soma readout available for inspection.
Returns
torch.Tensor
AxoTemporalModel.recurrent_state_bytes
axosim.temporal_core.AxoTemporalModel.recurrent_state_bytes(*, dtype: torch.dtype) -> int
Report the declared recurrent-state storage in bytes.
Parameters
dtypetorch.dtype- keyword-only, required. Floating-point execution or allocation dtype.
Returns
int
AxoTemporalModel.component_manifest
axosim.temporal_core.AxoTemporalModel.component_manifest() -> dict[str, object]
Describe the model’s temporal and readout components.
Returns
dict[str, object]
create_temporal_model
axosim.temporal_core.create_temporal_model(source: BranchOfficialMamba, temporal_config: AxoTemporalCoreConfig) -> BranchOfficialMamba | AxoTemporalModel
Compose a selected AxoMamba front end with one temporal core.
Parameters
sourceBranchOfficialMamba- required.
temporal_configAxoTemporalCoreConfig- required. Temporal-core selection and its recurrence/adaptation settings.
Returns
BranchOfficialMamba \| AxoTemporalModel
migrate_legacy_gru_state_dict
axosim.temporal_core.migrate_legacy_gru_state_dict(state_dict: dict[str, torch.Tensor]) -> dict[str, torch.Tensor]
Map the internal I108 GRU wrapper into the unified checkpoint schema.
Parameters
state_dictdict[str, torch.Tensor]- required. Stored parameter and buffer mapping to load.
Returns
dict[str, torch.Tensor]