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)
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_inputint- default=1278. Input-channel count.
num_outputint- default=2. Output-channel count.
num_branchint- default=45. Branched input-feature count.
num_synapse_per_branchint- default=100. Contact slots per branch.
input_to_synapse_routingstr | None- default='neuronio_routing'.
model_dimint- default=64. Temporal hidden-feature width.
num_layersint- default=2. Number of temporal layers.
block_repeatsint- default=1.
state_dimint- default=16. Temporal state width.
conv_kernelint- default=4.
expansionint- default=2.
block_typestr- default='mamba1'.
head_dimint- default=64. Configured head width of the backbone.
num_groupsint- default=1.
chunk_sizeint- default=256. Chunk length for the supported Mamba or streaming execution path.
block_normbool- default=True.
final_normbool- default=True.
dropoutfloat- default=0.0.
residual_scale_initfloat- default=0.1. Initial learned multiplier on the residual update.
mamba_update_normalizationstr- default='none'. Normalize residual updates when the supported fixed_rms mode is selected.
separate_headsbool- default=False.
soma_filterbool- default=False.
soma_filter_taufloat- default=25.0.
soma_filter_kernelint- default=129.
learn_soma_filter_decaybool- default=True.
soma_multiplicative_gatebool- default=False.
soma_multiplicative_scale_initfloat- default=0.1.
soma_peak_correctionbool- default=False.
soma_peak_correction_scale_initfloat- default=0.1.
soma_highpass_correctionbool- default=False.
soma_highpass_correction_scale_initfloat- default=0.1.
spike_voltage_coupling_scalefloat- default=0.0.
spike_voltage_coupling_detachbool- default=False. Keep the forward spike-voltage coupling but stop spike-loss gradients from reaching the voltage path through it.
morphology_idslist[str] | None- default=None. Ordered morphology identity vocabulary.
morphology_embedding_scalefloat | None- default=None.
population_adapter_morphology_idstr | None- default=None.
synapse_gain_scalefloat | None- default=None.
morphology_synapse_gain_scalefloat | None- default=None.
share_morphology_synapse_gainbool- default=False.
morphology_synapse_gain_rankint- default=0.
morphology_synapse_feature_dimint- default=0.
morphology_synapse_feature_hiddenint- default=0.
morphology_synapse_feature_scalefloat | None- default=None.
morphology_synapse_feature_storage_dtypestr- default='float32'.
local_tcn_scalefloat | None- default=None.
local_tcn_modestr- default='dilated'.
local_tcn_positionstr- default='parallel'.
share_local_tcn_pointwisebool- default=False.
local_tcn_pointwise_adapter_rankint- default=0.
local_tcn_pointwise_rankint- default=0.
local_tcn_output_rankint- default=0.
mamba_projection_rankint- default=0.
branch_gainbool- default=False.
branch_nonlinearitystr- default='none'.
branch_nonlinearity_scale_initfloat- default=0.1.
branch_subunitsint- default=0.
branch_subunit_routingstr- default='contiguous'.
branch_subunit_scalefloat- default=1.0.
branch_bilinear_rankint- default=0.
branch_bilinear_scalefloat | None- default=None.
branch_trace_tauslist[float] | None- default=None.
branch_trace_kernelint- default=65.
hidden_trace_tauslist[float] | None- default=None.
hidden_trace_kernelint- default=129.
temporal_refine_kernelint- default=0.
integrative_mixerbool- default=False.
integrative_mixer_short_kernelint- default=9.
integrative_mixer_long_kernelint- default=65.
integrative_mixer_positionstr- default='pre'.
integrative_mixer_long_path_biasfloat- default=0.5.
Attributes
Constructor fields are retained as read-only attributes.
default_axomamba_config
axosim.axomamba.default_axomamba_config(**overrides: Any) -> AxoMambaConfig
Build the default AxoSim Mamba recipe and apply keyword overrides.
Parameters
overridesAny- variadic. Keyword fields that replace values in the selected architecture recipe.
Returns
configAxoMambaConfig- Architecture recipe with the supplied keyword overrides applied.
structured_compact_axomamba_config
axosim.axomamba.structured_compact_axomamba_config(**overrides: Any) -> AxoMambaConfig
Build the structured compact recipe and apply keyword overrides.
Parameters
overridesAny- variadic. Keyword fields that replace values in the selected architecture recipe.
Returns
configAxoMambaConfig- Architecture recipe with the supplied keyword overrides applied.
regression_axomamba_config
axosim.axomamba.regression_axomamba_config(**overrides: Any) -> AxoMambaConfig
Build the voltage-focused recipe and apply keyword overrides.
Parameters
overridesAny- variadic. Keyword fields that replace values in the selected architecture recipe.
Returns
configAxoMambaConfig- Architecture recipe with the supplied keyword overrides applied.
population_axomamba_config
axosim.axomamba.population_axomamba_config(**overrides: Any) -> AxoMambaConfig
Build the population-domain recipe and apply keyword overrides.
Parameters
overridesAny- variadic. Keyword fields that replace values in the selected architecture recipe.
Returns
configAxoMambaConfig- Architecture recipe with the supplied keyword overrides applied.
spike_axomamba_config
axosim.axomamba.spike_axomamba_config(**overrides: Any) -> AxoMambaConfig
Build the spike-focused recipe and apply keyword overrides.
Parameters
overridesAny- variadic. Keyword fields that replace values in the selected architecture recipe.
Returns
configAxoMambaConfig- Architecture recipe with the supplied keyword overrides applied.
load_axomamba_config
axosim.axomamba.load_axomamba_config(path: str | Path | None=None, **overrides: Any) -> AxoMambaConfig
Read a JSON architecture configuration and apply keyword overrides; without a path, use the default AxoSim Mamba recipe.
Parameters
pathstr | Path | None- default=None. Filesystem location to read or write; see the operation's persistence contract.
overridesAny- variadic. Keyword fields that replace values in the selected architecture recipe.
Returns
configAxoMambaConfig- 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
Convert a configuration object or mapping to AxoMambaConfig; None selects the default recipe.
Parameters
configAxoMambaConfig | BranchOfficialMambaConfig | Mapping[str, Any] | None- required. Model configuration; use the defaults and constraints documented for its configuration class.
Returns
configAxoMambaConfig- 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)
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
configAxoMambaConfig | BranchOfficialMambaConfig | Mapping[str, Any] | None- default=None. Model configuration; use the defaults and constraints documented for its configuration class.
mamba_classestuple[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)
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
configAxoMambaConfig | 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
Construct a newly initialized AxoMamba, using the fused backend unless the PyTorch fallback is requested.
Parameters
configAxoMambaConfig | BranchOfficialMambaConfig | Mapping[str, Any] | None- default=None. Model configuration; use the defaults and constraints documented for its configuration class.
use_pytorch_fallbackbool- keyword-only, default=False. Construct the CPU/test-compatible backend. Its checkpoint format differs from the fused backend.
Returns
modelAxoMamba- 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)
Architecture and optional branch, morphology, temporal-correction, and readout settings for the fused Mamba model.
Parameters
num_inputint- default=1278. Input-channel count.
num_outputint- default=2. Output-channel count.
num_branchint- default=45. Branched input-feature count.
num_synapse_per_branchint- default=100. Contact slots per branch.
input_to_synapse_routingstr | None- default='neuronio_routing'.
model_dimint- default=64. Temporal hidden-feature width.
num_layersint- default=2. Number of temporal layers.
block_repeatsint- default=1.
state_dimint- default=16. Temporal state width.
conv_kernelint- default=4.
expansionint- default=2.
block_typestr- default='mamba1'.
head_dimint- default=64. Configured head width of the backbone.
num_groupsint- default=1.
chunk_sizeint- default=256. Chunk length for the supported Mamba or streaming execution path.
block_normbool- default=True.
final_normbool- default=True.
dropoutfloat- default=0.0.
residual_scale_initfloat- default=0.1. Initial learned multiplier on the residual update.
mamba_update_normalizationstr- default='none'. Normalize residual updates when the supported fixed_rms mode is selected.
separate_headsbool- default=False.
soma_filterbool- default=False.
soma_filter_taufloat- default=25.0.
soma_filter_kernelint- default=129.
learn_soma_filter_decaybool- default=True.
soma_multiplicative_gatebool- default=False.
soma_multiplicative_scale_initfloat- default=0.1.
soma_peak_correctionbool- default=False.
soma_peak_correction_scale_initfloat- default=0.1.
soma_highpass_correctionbool- default=False.
soma_highpass_correction_scale_initfloat- default=0.1.
spike_voltage_coupling_scalefloat- default=0.0.
spike_voltage_coupling_detachbool- default=False. Keep the forward spike-voltage coupling but stop spike-loss gradients from reaching the voltage path through it.
morphology_idslist[str] | None- default=None. Ordered morphology identity vocabulary.
morphology_embedding_scalefloat | None- default=None.
population_adapter_morphology_idstr | None- default=None.
synapse_gain_scalefloat | None- default=None.
morphology_synapse_gain_scalefloat | None- default=None.
share_morphology_synapse_gainbool- default=False.
morphology_synapse_gain_rankint- default=0.
morphology_synapse_feature_dimint- default=0.
morphology_synapse_feature_hiddenint- default=0.
morphology_synapse_feature_scalefloat | None- default=None.
morphology_synapse_feature_storage_dtypestr- default='float32'.
local_tcn_scalefloat | None- default=None.
local_tcn_modestr- default='dilated'.
local_tcn_positionstr- default='parallel'.
share_local_tcn_pointwisebool- default=False.
local_tcn_pointwise_adapter_rankint- default=0.
local_tcn_pointwise_rankint- default=0.
local_tcn_output_rankint- default=0.
mamba_projection_rankint- default=0.
branch_gainbool- default=False.
branch_nonlinearitystr- default='none'.
branch_nonlinearity_scale_initfloat- default=0.1.
branch_subunitsint- default=0.
branch_subunit_routingstr- default='contiguous'.
branch_subunit_scalefloat- default=1.0.
branch_bilinear_rankint- default=0.
branch_bilinear_scalefloat | None- default=None.
branch_trace_tauslist[float] | None- default=None.
branch_trace_kernelint- default=65.
hidden_trace_tauslist[float] | None- default=None.
hidden_trace_kernelint- default=129.
temporal_refine_kernelint- default=0.
integrative_mixerbool- default=False.
integrative_mixer_short_kernelint- default=9.
integrative_mixer_long_kernelint- default=65.
integrative_mixer_positionstr- default='pre'.
integrative_mixer_long_path_biasfloat- 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)
Mutable recurrent state for exact one-timestep AxoMamba inference.
Parameters
mamba_stateslist[tuple[torch.Tensor, torch.Tensor]]- required.
local_tcn_historieslist[torch.Tensor]- required.
morphology_feature_gainstorch.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)
Branch-routed wrapper around the official mamba-ssm Mamba module.
Bases: nn.Module.
Parameters
configBranchOfficialMambaConfig- required. Model configuration; use the defaults and constraints documented for its configuration class.
mamba_classestuple[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()BranchOfficialMamba.allocate_streaming_state()BranchOfficialMamba.streaming_step()BranchOfficialMamba.streaming_step_events()
BranchOfficialMamba.forward
axosim.mamba_official.BranchOfficialMamba.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), 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
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.
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
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_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
stateBranchMambaStreamingState- 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
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
xtorch.Tensor- required. Input tensor for the full-sequence or streaming operation.
stateBranchMambaStreamingState- 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.
Returns
predictiontorch.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
Advance one timestep from padded sparse channel/value event rows.
Parameters
event_indicestorch.Tensor- required.
event_valuestorch.Tensor- required. Signed floating-point event amplitudes, one per paired address.
stateBranchMambaStreamingState- 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
BranchPyTorchMamba
axosim.mamba_official.BranchPyTorchMamba(config: BranchOfficialMambaConfig)
Branch-routed Mamba wrapper using the differentiable PyTorch fallback block.
Bases: BranchOfficialMamba.
Parameters
configBranchOfficialMambaConfig- required. Model configuration; use the defaults and constraints documented for its configuration class.