Supplied-history scan | AxoSim documentation

Overview

Process one or more complete native input histories through a provided Mamba1 model. All neuron rows share its weights; the function partitions neurons when requested while preserving each complete time sequence. The supplied-history guide provides runnable single-neuron, population and gradient checks. For continuing streams, use the model’s streaming API; for delayed network feedback, use connected population rollout.

This reference describes axosim.history_scan. Repository access is currently required to inspect the source. Export index.

scan_histories

axosim.scan_histories(
    model: BranchOfficialMamba,
    inputs: torch.Tensor,
    *,
    morphology_indices: torch.Tensor | None = None,
    neuron_batch_size: int | None = None,
    require_parallel: bool = True,
) -> HistoryScanResult

Source

Evaluate complete histories with fresh temporal state, retaining autograd and the caller’s training/evaluation mode. The default requires the official fused CUDA Mamba1 full-sequence path. An explicitly permitted portable model reports sequential execution; this option never replaces a checkpoint’s architecture or weights.

Parameters

model BranchOfficialMamba: required. Provided AxoMamba or Branch-routed Mamba1 model, including the portable AxoPyTorchMamba reference. Official execution requires the actual mamba_ssm Mamba1 blocks and enabled fused kernels. GRU, Lite, Mamba2 and unrelated custom block implementations are unsupported. The function neither moves the model nor changes its mode or weights.
inputs torch.Tensor: required. Floating tensor (N, T, C) with positive N and T and C == model.num_input. One neuron uses N=1. Supply the checkpoint's native channel order, input convention and sampling cadence on the model's device. No dtype or device conversion occurs. Official kernels accept float16, bfloat16 or float32 inputs; use a dtype compatible with the model's weights.
morphology_indices torch.Tensor | None: default=None. Integer tensor (N,) indexing model.config.morphology_ids, with each value in [0, len(morphology_ids)). Required when the model declares that vocabulary; omit it for an unconditioned model. Indices are sliced with their matching neuron rows. The underlying model places the indices on its execution device.
neuron_batch_size int | None: default=None. Positive integer maximum rows per forward call; None processes all rows together. Only N is partitioned, with the complete T sequence retained in each partition. Output order remains the input order. This limits intermediate per-forward memory, not the size of the complete returned predictions or retained autograd graph.
require_parallel bool: default=True. Require the enabled official CUDA fused temporal scan. Set False to accept the sequential portable PyTorch Mamba1 model; official checkpoints still require their CUDA backend. Inspect result.backend for the actual path.

Returns

HistoryScanResult: prediction is a tensor (N, T, model.num_output) in the provided model's output coordinates, with its derivative graph retained when gradient tracking is enabled. backend describes the path that executed. No streaming state, recurrent events or new graph topology are returned.

Execution and sequence boundaries

Each call invokes full-sequence model forward from its initial state. Separate calls on time chunks do not continue one another. The function does not generate future network inputs from emitted spikes: those inputs must already be present in the supplied histories. It also does not impose eval() or disable gradients; use model.eval() and torch.inference_mode() for inference. Training-mode stochastic layers retain their usual behavior, so comparisons across different neuron batch sizes should use evaluation mode when testing numerical parity. Batch partitioning can also change floating-point results; strict CUDA FP32 comparisons require consistent TF32 settings and appropriate numerical tolerances, not bitwise equality. The function does not change those settings.

Raises

Exception	Condition and source message
`TypeError`	Unsupported model: `scan_histories requires an AxoSim or Branch-routed Mamba model`
`TypeError`	Non-tensor input: `inputs must be a torch.Tensor`
`TypeError`	Non-boolean parallel flag: `require_parallel must be a bool`
`ValueError`	Wrong rank: `inputs must have shape (neurons, time, input_channels)`; empty neuron/time dimension: `inputs must have non-empty neuron and time dimensions`
`ValueError`	Wrong width: `inputs must have num_input={model.num_input} channels`; non-floating input: `inputs must have a floating-point dtype`
`ValueError`	Invalid batch size: `neuron_batch_size must be a positive integer or None`
`ValueError`	Device mismatch: `inputs and model parameters must be on the same device`
`ValueError`	Missing conditioning: `morphology_indices are required for a morphology-conditioned model`; unnecessary conditioning: `morphology_indices were provided to an unconditioned model`
`ValueError`	Invalid morphology tensor: `morphology_indices must have shape (neurons,)`, `morphology_indices must have an integer dtype`, or `morphology_indices must be in range [0, {len(ids)})`
`RuntimeError`	Unsupported Mamba variant: `scan_histories currently supports only the Mamba1 history backend`
`RuntimeError`	Sequential path rejected: `require_parallel=True rejects the sequential PyTorch Mamba reference; use an official CUDA Mamba model or explicitly set require_parallel=False`
`RuntimeError`	Official dependency missing: `The official Mamba1 fused CUDA backend is unavailable`; unsupported blocks: `The model does not contain the supported official Mamba1 blocks`
`RuntimeError`	Official model on CPU: `Official Mamba1 history scan requires CUDA inputs and model; require_parallel=False does not replace checkpoint backends`
`ValueError`	Unsupported official input precision: `Official Mamba1 scan requires float16, bfloat16 or float32 inputs`
`RuntimeError`	Fast path disabled: `Official Mamba1 history scan requires use_fast_path=True in every block`
`RuntimeError`	Kernels unavailable: `Official Mamba1 fused selective-scan or causal-convolution kernels are unavailable`

Errors raised by the model or dependencies during forward are propagated. See installation for the official CUDA dependencies.

HistoryScanBackend

axosim.HistoryScanBackend(name: str, parallel: bool, reason: str)

Source

Frozen execution metadata returned with a scan. This describes the provided model’s validated execution path, rather than a requested backend preference.

Attributes

name: str: official-mamba1-fused for official Mamba1's enabled fused CUDA path, or pytorch-sequential-reference for the explicitly permitted portable implementation.
parallel: bool: True for the fused temporal scan; false for the portable recurrence evaluated sequentially in time. Neuron batching alone does not make this value true.
reason: str: Source explanation of the selected path: Official Mamba1 full-sequence mamba_inner_fn with fused CUDA selective scan and causal convolution. or Portable PyTorch Mamba evaluates the state recurrence sequentially in time.

All constructor fields are required. The dataclass’s attributes cannot be reassigned.

HistoryScanResult

axosim.HistoryScanResult(prediction: torch.Tensor, backend: HistoryScanBackend)

Source

Predictions and validated execution metadata for complete supplied histories.

Attributes

prediction: torch.Tensor: Model predictions (N, T, model.num_output), ordered like the input neuron rows. Standard two-output models return spike logits and soma-target coordinates. The function does not threshold spikes, convert soma units, detach derivatives or clone the tensor into an immutable snapshot.
backend: HistoryScanBackend: Actual fused or sequential execution path, including its explanatory reason.

Both constructor fields are required. The dataclass’s attributes cannot be reassigned; its prediction tensor retains normal PyTorch mutability and autograd semantics. It contains no continuation state.