API reference

Mamba models and configuration

Signatures, parameters, return contracts, and source for mamba models and configuration.

Overview

AxoMamba is the public Mamba implementation and inherits BranchOfficialMamba. AxoMambaConfig inherits all BranchOfficialMambaConfig fields. The default_axomamba_config factory supplies the promoted recipe, which differs from the dataclass’s raw field defaults. AxoPyTorchMamba is a test-oriented fallback with a different checkpoint format.

Source revision: caef7be03abd. Public export index.

AxoMambaConfig

axosim.axomamba.AxoMambaConfig(num_input: int = 1278, num_output: int = 2, num_branch: int = 45, num_synapse_per_branch: int = 100, input_to_synapse_routing: str | None = 'neuronio_routing', model_dim: int = 64, num_layers: int = 2, block_repeats: int = 1, state_dim: int = 16, conv_kernel: int = 4, expansion: int = 2, block_type: str = 'mamba1', head_dim: int = 64, num_groups: int = 1, chunk_size: int = 256, block_norm: bool = True, final_norm: bool = True, dropout: float = 0.0, residual_scale_init: float = 0.1, mamba_update_normalization: str = 'none', separate_heads: bool = False, soma_filter: bool = False, soma_filter_tau: float = 25.0, soma_filter_kernel: int = 129, learn_soma_filter_decay: bool = True, soma_multiplicative_gate: bool = False, soma_multiplicative_scale_init: float = 0.1, soma_peak_correction: bool = False, soma_peak_correction_scale_init: float = 0.1, soma_highpass_correction: bool = False, soma_highpass_correction_scale_init: float = 0.1, spike_voltage_coupling_scale: float = 0.0, spike_voltage_coupling_detach: bool = False, morphology_ids: list[str] | None = None, morphology_embedding_scale: float | None = None, population_adapter_morphology_id: str | None = None, synapse_gain_scale: float | None = None, morphology_synapse_gain_scale: float | None = None, share_morphology_synapse_gain: bool = False, morphology_synapse_gain_rank: int = 0, morphology_synapse_feature_dim: int = 0, morphology_synapse_feature_hidden: int = 0, morphology_synapse_feature_scale: float | None = None, morphology_synapse_feature_storage_dtype: str = 'float32', local_tcn_scale: float | None = None, local_tcn_mode: str = 'dilated', local_tcn_position: str = 'parallel', share_local_tcn_pointwise: bool = False, local_tcn_pointwise_adapter_rank: int = 0, local_tcn_pointwise_rank: int = 0, local_tcn_output_rank: int = 0, mamba_projection_rank: int = 0, branch_gain: bool = False, branch_nonlinearity: str = 'none', branch_nonlinearity_scale_init: float = 0.1, branch_subunits: int = 0, branch_subunit_routing: str = 'contiguous', branch_subunit_scale: float = 1.0, branch_bilinear_rank: int = 0, branch_bilinear_scale: float | None = None, branch_trace_taus: list[float] | None = None, branch_trace_kernel: int = 65, hidden_trace_taus: list[float] | None = None, hidden_trace_kernel: int = 129, temporal_refine_kernel: int = 0, integrative_mixer: bool = False, integrative_mixer_short_kernel: int = 9, integrative_mixer_long_kernel: int = 65, integrative_mixer_position: str = 'pre', integrative_mixer_long_path_bias: float = 0.5)

Source

Named config for the current best compact AxoSim Mamba surrogate.

Bases: BranchOfficialMambaConfig.

Inherits all fields and raw defaults from BranchOfficialMambaConfig. default_axomamba_config applies the AxoSim recipe over those raw defaults.

Parameters

num_input int
default=1278. Input-channel count.
num_output int
default=2. Output-channel count.
num_branch int
default=45. Branched input-feature count.
num_synapse_per_branch int
default=100. Contact slots per branch.
input_to_synapse_routing str | None
default='neuronio_routing'.
model_dim int
default=64. Temporal hidden-feature width.
num_layers int
default=2. Number of temporal layers.
block_repeats int
default=1.
state_dim int
default=16. Temporal state width.
conv_kernel int
default=4.
expansion int
default=2.
block_type str
default='mamba1'.
head_dim int
default=64. Configured head width of the backbone.
num_groups int
default=1.
chunk_size int
default=256. Chunk length for the supported Mamba or streaming execution path.
block_norm bool
default=True.
final_norm bool
default=True.
dropout float
default=0.0.
residual_scale_init float
default=0.1. Initial learned multiplier on the residual update.
mamba_update_normalization str
default='none'. Normalize residual updates when the supported fixed_rms mode is selected.
separate_heads bool
default=False.
soma_filter bool
default=False.
soma_filter_tau float
default=25.0.
soma_filter_kernel int
default=129.
learn_soma_filter_decay bool
default=True.
soma_multiplicative_gate bool
default=False.
soma_multiplicative_scale_init float
default=0.1.
soma_peak_correction bool
default=False.
soma_peak_correction_scale_init float
default=0.1.
soma_highpass_correction bool
default=False.
soma_highpass_correction_scale_init float
default=0.1.
spike_voltage_coupling_scale float
default=0.0.
spike_voltage_coupling_detach bool
default=False. Keep the forward spike-voltage coupling but stop spike-loss gradients from reaching the voltage path through it.
morphology_ids list[str] | None
default=None. Ordered morphology identity vocabulary.
morphology_embedding_scale float | None
default=None.
population_adapter_morphology_id str | None
default=None.
synapse_gain_scale float | None
default=None.
morphology_synapse_gain_scale float | None
default=None.
share_morphology_synapse_gain bool
default=False.
morphology_synapse_gain_rank int
default=0.
morphology_synapse_feature_dim int
default=0.
morphology_synapse_feature_hidden int
default=0.
morphology_synapse_feature_scale float | None
default=None.
morphology_synapse_feature_storage_dtype str
default='float32'.
local_tcn_scale float | None
default=None.
local_tcn_mode str
default='dilated'.
local_tcn_position str
default='parallel'.
share_local_tcn_pointwise bool
default=False.
local_tcn_pointwise_adapter_rank int
default=0.
local_tcn_pointwise_rank int
default=0.
local_tcn_output_rank int
default=0.
mamba_projection_rank int
default=0.
branch_gain bool
default=False.
branch_nonlinearity str
default='none'.
branch_nonlinearity_scale_init float
default=0.1.
branch_subunits int
default=0.
branch_subunit_routing str
default='contiguous'.
branch_subunit_scale float
default=1.0.
branch_bilinear_rank int
default=0.
branch_bilinear_scale float | None
default=None.
branch_trace_taus list[float] | None
default=None.
branch_trace_kernel int
default=65.
hidden_trace_taus list[float] | None
default=None.
hidden_trace_kernel int
default=129.
temporal_refine_kernel int
default=0.
integrative_mixer bool
default=False.
integrative_mixer_short_kernel int
default=9.
integrative_mixer_long_kernel int
default=65.
integrative_mixer_position str
default='pre'.
integrative_mixer_long_path_bias float
default=0.5.

Attributes

Constructor fields are retained as read-only attributes.

default_axomamba_config

axosim.axomamba.default_axomamba_config(**overrides: Any) -> AxoMambaConfig

Source

Build the default AxoSim Mamba recipe and apply keyword overrides.

Parameters

overrides Any
variadic. Keyword fields that replace values in the selected architecture recipe.

Returns

config AxoMambaConfig
Architecture recipe with the supplied keyword overrides applied.

structured_compact_axomamba_config

axosim.axomamba.structured_compact_axomamba_config(**overrides: Any) -> AxoMambaConfig

Source

Build the structured compact recipe and apply keyword overrides.

Parameters

overrides Any
variadic. Keyword fields that replace values in the selected architecture recipe.

Returns

config AxoMambaConfig
Architecture recipe with the supplied keyword overrides applied.

regression_axomamba_config

axosim.axomamba.regression_axomamba_config(**overrides: Any) -> AxoMambaConfig

Source

Build the voltage-focused recipe and apply keyword overrides.

Parameters

overrides Any
variadic. Keyword fields that replace values in the selected architecture recipe.

Returns

config AxoMambaConfig
Architecture recipe with the supplied keyword overrides applied.

population_axomamba_config

axosim.axomamba.population_axomamba_config(**overrides: Any) -> AxoMambaConfig

Source

Build the population-domain recipe and apply keyword overrides.

Parameters

overrides Any
variadic. Keyword fields that replace values in the selected architecture recipe.

Returns

config AxoMambaConfig
Architecture recipe with the supplied keyword overrides applied.

spike_axomamba_config

axosim.axomamba.spike_axomamba_config(**overrides: Any) -> AxoMambaConfig

Source

Build the spike-focused recipe and apply keyword overrides.

Parameters

overrides Any
variadic. Keyword fields that replace values in the selected architecture recipe.

Returns

config AxoMambaConfig
Architecture recipe with the supplied keyword overrides applied.

load_axomamba_config

axosim.axomamba.load_axomamba_config(path: str | Path | None=None, **overrides: Any) -> AxoMambaConfig

Source

Read a JSON architecture configuration and apply keyword overrides; without a path, use the default AxoSim Mamba recipe.

Parameters

path str | Path | None
default=None. Filesystem location to read or write; see the operation's persistence contract.
overrides Any
variadic. Keyword fields that replace values in the selected architecture recipe.

Returns

config AxoMambaConfig
Configuration loaded from JSON with the requested overrides, or the default recipe when path is None.

coerce_axomamba_config

axosim.axomamba.coerce_axomamba_config(config: AxoMambaConfig | BranchOfficialMambaConfig | Mapping[str, Any] | None) -> AxoMambaConfig

Source

Convert a configuration object or mapping to AxoMambaConfig; None selects the default recipe.

Parameters

config AxoMambaConfig | BranchOfficialMambaConfig | Mapping[str, Any] | None
required. Model configuration; use the defaults and constraints documented for its configuration class.

Returns

config AxoMambaConfig
Converted configuration; an existing AxoMambaConfig is returned unchanged.

AxoMamba

axosim.axomamba.AxoMamba(config: AxoMambaConfig | BranchOfficialMambaConfig | Mapping[str, Any] | None=None, *, mamba_classes: tuple[type, type | None] | None=None)

Source

Reusable named AxoSim Mamba surrogate built on the official Mamba backend.

Bases: BranchOfficialMamba.

Full-sequence and streaming methods are inherited from BranchOfficialMamba below. Preserve the recorded fused/fallback backend when loading weights.

Parameters

config AxoMambaConfig | BranchOfficialMambaConfig | Mapping[str, Any] | None
default=None. Model configuration; use the defaults and constraints documented for its configuration class.
mamba_classes tuple[type, type | None] | None
keyword-only, default=None. Optional backend class pair used when constructing the Mamba implementation.

AxoPyTorchMamba

axosim.axomamba.AxoPyTorchMamba(config: AxoMambaConfig | BranchOfficialMambaConfig | Mapping[str, Any] | None=None)

Source

AxoMamba with the dependency-free PyTorch Mamba block, for tests/smokes.

Bases: AxoMamba.

Full-sequence and streaming methods are inherited from BranchOfficialMamba below. Preserve the recorded fused/fallback backend when loading weights.

Parameters

config AxoMambaConfig | BranchOfficialMambaConfig | Mapping[str, Any] | None
default=None. Model configuration; use the defaults and constraints documented for its configuration class.

create_axomamba

axosim.axomamba.create_axomamba(config: AxoMambaConfig | BranchOfficialMambaConfig | Mapping[str, Any] | None=None, *, use_pytorch_fallback: bool=False) -> AxoMamba

Source

Construct a newly initialized AxoMamba, using the fused backend unless the PyTorch fallback is requested.

Parameters

config AxoMambaConfig | BranchOfficialMambaConfig | Mapping[str, Any] | None
default=None. Model configuration; use the defaults and constraints documented for its configuration class.
use_pytorch_fallback bool
keyword-only, default=False. Construct the CPU/test-compatible backend. Its checkpoint format differs from the fused backend.

Returns

model AxoMamba
Newly initialized AxoMamba or AxoPyTorchMamba, according to use_pytorch_fallback.

BranchOfficialMambaConfig

axosim.mamba_official.BranchOfficialMambaConfig(num_input: int = 1278, num_output: int = 2, num_branch: int = 45, num_synapse_per_branch: int = 100, input_to_synapse_routing: str | None = 'neuronio_routing', model_dim: int = 64, num_layers: int = 2, block_repeats: int = 1, state_dim: int = 16, conv_kernel: int = 4, expansion: int = 2, block_type: str = 'mamba1', head_dim: int = 64, num_groups: int = 1, chunk_size: int = 256, block_norm: bool = True, final_norm: bool = True, dropout: float = 0.0, residual_scale_init: float = 0.1, mamba_update_normalization: str = 'none', separate_heads: bool = False, soma_filter: bool = False, soma_filter_tau: float = 25.0, soma_filter_kernel: int = 129, learn_soma_filter_decay: bool = True, soma_multiplicative_gate: bool = False, soma_multiplicative_scale_init: float = 0.1, soma_peak_correction: bool = False, soma_peak_correction_scale_init: float = 0.1, soma_highpass_correction: bool = False, soma_highpass_correction_scale_init: float = 0.1, spike_voltage_coupling_scale: float = 0.0, spike_voltage_coupling_detach: bool = False, morphology_ids: list[str] | None = None, morphology_embedding_scale: float | None = None, population_adapter_morphology_id: str | None = None, synapse_gain_scale: float | None = None, morphology_synapse_gain_scale: float | None = None, share_morphology_synapse_gain: bool = False, morphology_synapse_gain_rank: int = 0, morphology_synapse_feature_dim: int = 0, morphology_synapse_feature_hidden: int = 0, morphology_synapse_feature_scale: float | None = None, morphology_synapse_feature_storage_dtype: str = 'float32', local_tcn_scale: float | None = None, local_tcn_mode: str = 'dilated', local_tcn_position: str = 'parallel', share_local_tcn_pointwise: bool = False, local_tcn_pointwise_adapter_rank: int = 0, local_tcn_pointwise_rank: int = 0, local_tcn_output_rank: int = 0, mamba_projection_rank: int = 0, branch_gain: bool = False, branch_nonlinearity: str = 'none', branch_nonlinearity_scale_init: float = 0.1, branch_subunits: int = 0, branch_subunit_routing: str = 'contiguous', branch_subunit_scale: float = 1.0, branch_bilinear_rank: int = 0, branch_bilinear_scale: float | None = None, branch_trace_taus: list[float] | None = None, branch_trace_kernel: int = 65, hidden_trace_taus: list[float] | None = None, hidden_trace_kernel: int = 129, temporal_refine_kernel: int = 0, integrative_mixer: bool = False, integrative_mixer_short_kernel: int = 9, integrative_mixer_long_kernel: int = 65, integrative_mixer_position: str = 'pre', integrative_mixer_long_path_bias: float = 0.5)

Source

Architecture and optional branch, morphology, temporal-correction, and readout settings for the fused Mamba model.

Parameters

num_input int
default=1278. Input-channel count.
num_output int
default=2. Output-channel count.
num_branch int
default=45. Branched input-feature count.
num_synapse_per_branch int
default=100. Contact slots per branch.
input_to_synapse_routing str | None
default='neuronio_routing'.
model_dim int
default=64. Temporal hidden-feature width.
num_layers int
default=2. Number of temporal layers.
block_repeats int
default=1.
state_dim int
default=16. Temporal state width.
conv_kernel int
default=4.
expansion int
default=2.
block_type str
default='mamba1'.
head_dim int
default=64. Configured head width of the backbone.
num_groups int
default=1.
chunk_size int
default=256. Chunk length for the supported Mamba or streaming execution path.
block_norm bool
default=True.
final_norm bool
default=True.
dropout float
default=0.0.
residual_scale_init float
default=0.1. Initial learned multiplier on the residual update.
mamba_update_normalization str
default='none'. Normalize residual updates when the supported fixed_rms mode is selected.
separate_heads bool
default=False.
soma_filter bool
default=False.
soma_filter_tau float
default=25.0.
soma_filter_kernel int
default=129.
learn_soma_filter_decay bool
default=True.
soma_multiplicative_gate bool
default=False.
soma_multiplicative_scale_init float
default=0.1.
soma_peak_correction bool
default=False.
soma_peak_correction_scale_init float
default=0.1.
soma_highpass_correction bool
default=False.
soma_highpass_correction_scale_init float
default=0.1.
spike_voltage_coupling_scale float
default=0.0.
spike_voltage_coupling_detach bool
default=False. Keep the forward spike-voltage coupling but stop spike-loss gradients from reaching the voltage path through it.
morphology_ids list[str] | None
default=None. Ordered morphology identity vocabulary.
morphology_embedding_scale float | None
default=None.
population_adapter_morphology_id str | None
default=None.
synapse_gain_scale float | None
default=None.
morphology_synapse_gain_scale float | None
default=None.
share_morphology_synapse_gain bool
default=False.
morphology_synapse_gain_rank int
default=0.
morphology_synapse_feature_dim int
default=0.
morphology_synapse_feature_hidden int
default=0.
morphology_synapse_feature_scale float | None
default=None.
morphology_synapse_feature_storage_dtype str
default='float32'.
local_tcn_scale float | None
default=None.
local_tcn_mode str
default='dilated'.
local_tcn_position str
default='parallel'.
share_local_tcn_pointwise bool
default=False.
local_tcn_pointwise_adapter_rank int
default=0.
local_tcn_pointwise_rank int
default=0.
local_tcn_output_rank int
default=0.
mamba_projection_rank int
default=0.
branch_gain bool
default=False.
branch_nonlinearity str
default='none'.
branch_nonlinearity_scale_init float
default=0.1.
branch_subunits int
default=0.
branch_subunit_routing str
default='contiguous'.
branch_subunit_scale float
default=1.0.
branch_bilinear_rank int
default=0.
branch_bilinear_scale float | None
default=None.
branch_trace_taus list[float] | None
default=None.
branch_trace_kernel int
default=65.
hidden_trace_taus list[float] | None
default=None.
hidden_trace_kernel int
default=129.
temporal_refine_kernel int
default=0.
integrative_mixer bool
default=False.
integrative_mixer_short_kernel int
default=9.
integrative_mixer_long_kernel int
default=65.
integrative_mixer_position str
default='pre'.
integrative_mixer_long_path_bias float
default=0.5.

Attributes

Constructor fields are retained as read-only attributes.

BranchMambaStreamingState

axosim.mamba_official.BranchMambaStreamingState(mamba_states: list[tuple[torch.Tensor, torch.Tensor]], local_tcn_histories: list[torch.Tensor], morphology_feature_gains: torch.Tensor | None = None)

Source

Mutable recurrent state for exact one-timestep AxoMamba inference.

Parameters

mamba_states list[tuple[torch.Tensor, torch.Tensor]]
required.
local_tcn_histories list[torch.Tensor]
required.
morphology_feature_gains torch.Tensor | None
default=None.

Attributes

Constructor fields are retained as attributes.

BranchOfficialMamba

axosim.mamba_official.BranchOfficialMamba(config: BranchOfficialMambaConfig, *, mamba_classes: tuple[type[nn.Module], type[nn.Module] | None] | None=None)

Source

Branch-routed wrapper around the official mamba-ssm Mamba module.

Bases: nn.Module.

Parameters

config BranchOfficialMambaConfig
required. Model configuration; use the defaults and constraints documented for its configuration class.
mamba_classes tuple[type[nn.Module], type[nn.Module] | None] | None
keyword-only, default=None. Optional backend class pair used when constructing the Mamba implementation.

Methods

BranchOfficialMamba.forward

axosim.mamba_official.BranchOfficialMamba.forward(x: torch.Tensor, *, morphology_indices: torch.Tensor | None=None) -> torch.Tensor

Source

Predict native spike and soma outputs for the supplied sequence.

x is (B,T,num_input), and optional morphology_indices is integer (B,). Morphology-conditioned synaptic gains require valid morphology indices. Returns (B,T,num_output) in the checkpoint’s spike-logit and soma-target coordinates.

Parameters

x torch.Tensor
required. Input tensor for the full-sequence or streaming operation.
morphology_indices torch.Tensor | None
keyword-only, default=None. Integer class assignments into the model's ordered morphology vocabulary; one per batch item or persistent neuron.

Returns

prediction torch.Tensor
Spike-logit and soma-target channels in the tensor shape specified above.

BranchOfficialMamba.allocate_streaming_state

axosim.mamba_official.BranchOfficialMamba.allocate_streaming_state(batch_size: int, *, device: torch.device | str | None=None, dtype: torch.dtype | None=None) -> BranchMambaStreamingState

Source

Allocate state that advances a population without replaying history.

Allocates a persistent streaming-state record for the requested batch_size, device, and dtype. Allocate a fresh state for independent traces or changed batch membership.

Parameters

batch_size int
required. Examples processed per batch.
device torch.device | str | None
keyword-only, default=None. Execution or allocation device.
dtype torch.dtype | None
keyword-only, default=None. Floating-point execution or allocation dtype.

Returns

state BranchMambaStreamingState
Fresh recurrent buffers and local-filter histories for the selected batch, device, and dtype.

BranchOfficialMamba.streaming_step

axosim.mamba_official.BranchOfficialMamba.streaming_step(x: torch.Tensor, state: BranchMambaStreamingState, *, morphology_indices: torch.Tensor | None=None, chunk_size: int | None=None) -> torch.Tensor

Source

Advance one timestep and return (batch, 1, output) predictions.

Advances the supplied mutable streaming state by one native input step. The guide supplies x as (B,num_input), with one morphology index per item when configured. Returns (B,1,num_output).

Parameters

x torch.Tensor
required. Input tensor for the full-sequence or streaming operation.
state BranchMambaStreamingState
required. Temporal state returned by the matching initial-state or allocation method.
morphology_indices torch.Tensor | None
keyword-only, default=None. Integer class assignments into the model's ordered morphology vocabulary; one per batch item or persistent neuron.
chunk_size int | None
keyword-only, default=None. Chunk length for the supported Mamba or streaming execution path.

Returns

prediction torch.Tensor
One native output step (batch,1,num_output); the supplied state is updated in place.

BranchOfficialMamba.streaming_step_events

axosim.mamba_official.BranchOfficialMamba.streaming_step_events(event_indices: torch.Tensor, event_values: torch.Tensor, state: BranchMambaStreamingState, *, 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

Source

Advance one timestep from padded sparse channel/value event rows.

Parameters

event_indices torch.Tensor
required.
event_values torch.Tensor
required. Signed floating-point event amplitudes, one per paired address.
state BranchMambaStreamingState
required. Temporal state returned by the matching initial-state or allocation method.
morphology_indices torch.Tensor | None
keyword-only, default=None. Integer class assignments into the model's ordered morphology vocabulary; one per batch item or persistent neuron.
chunk_size int | None
keyword-only, default=None. Chunk length for the supported Mamba or streaming execution path.
output_buffer torch.Tensor | None
keyword-only, default=None. Optional preallocated output tensor for the operation.
retain_base_soma_prediction bool
keyword-only, default=True. Keep the base soma readout available for inspection.

Returns

torch.Tensor

BranchPyTorchMamba

axosim.mamba_official.BranchPyTorchMamba(config: BranchOfficialMambaConfig)

Source

Branch-routed Mamba wrapper using the differentiable PyTorch fallback block.

Bases: BranchOfficialMamba.

Parameters

config BranchOfficialMambaConfig
required. Model configuration; use the defaults and constraints documented for its configuration class.

Search guides, examples, and API signatures.