API reference

AxoSim CLI

Complete options and defaults for axosim.

Usage

axosim --help

Every command and subcommand accepts -h or --help. The option reference below includes exact parser defaults, choices, required arguments, and compatibility options hidden from ordinary help.

A subcommand is required. Named presets replace their declared defaults, while explicitly supplied flags take precedence. Boolean defaults refer to the destination value: for example, --blocking-transfer sets non_blocking=False.

axosim make-demo-data

write deterministic demo NPZ shards

Parameters

--output str · required
Destination: output.
--samples int · default=8
Destination: samples.
--shards int · default=1
Destination: shards.
--time-steps int · default=32
Native sequence horizon.
--input-dim int · default=64
Native input-channel count.
--seed int · default=0
Random seed for the declared operation.

Parser source

axosim convert-neuronio

convert raw NeuronIO pickle files to deterministic shards

Parameters

--input str · required
Destination: input.
--output str · required
Destination: output.
--shard-size int · default=128
Maximum sample count in each converted shard.
--window-size int · default=None
Native timesteps per extracted window.
--window-stride int · default=None
Native timestep distance between successive window starts.
--ignore-start int · default=0
Initial native timesteps excluded by the declared path.

Parser source

axosim repack-shards

repack shards as sliceable .npy arrays

Parameters

--input str · required
Destination: input.
--output str · required
Destination: output.
--input-dtype str · default='int8'
Stored NumPy dtype of the converted input arrays. Choices: ['int8', 'float32'].

Parser source

axosim list-presets

list named train/evaluate presets

No additional arguments are required; this command prints the named recipes as JSON.

axosim evaluate

evaluate a model with the corrected full-trace metric path

Parameters

--preset str · default=None
Choices: ['fulltrace-paper-metric', 'legacy-baseline-smoke'].
--data str · required
Destination: data.
--output str · required
Destination: output.
--input-dim int · default=1278
Native input-channel count.
--memory-units int · default=30
Width of the recurrent memory state.
--branches int · default=32
Number of routed branch features in the adapter.
--model-kind str · default='baseline'
use 'official' for the paper-style model, 'axomamba' for the promoted Mamba surrogate, 'mamba-official' for the generic official mamba-ssm backend, or 'branch-trace-rnn' for the RNN comparison path; 'baseline' is legacy/debug Choices: ['baseline', 'official', 'axomamba', 'mamba-official', 'mamba-pytorch', 'branch-mamba-pytorch', 'branch-trace-rnn'].
--model-config str · default='configs/branch_elm_30_official.json'
Destination: model_config.
--batch-size int · default=8
Examples processed per batch.
--seed int · default=0
Random seed for the declared operation.
--device str · default='cpu'
Execution or allocation device.
--checkpoint str · default=None
Upstream baseline checkpoint file.
--window-size int · default=None
Native timesteps per extracted window.
--window-stride int · default=None
Native timestep distance between successive window starts.
--ignore-start int · default=0
Initial native timesteps excluded by the declared path.
--cache-shards int · default=1
Maximum cached shards; zero disables the cache.
--soma-units str · default='millivolts'
Coordinate convention used when computing the local soma metric. Choices: ['millivolts', 'normalized'].
--metric-ignore-start int · default=0
Destination: metric_ignore_start.
--metric-mask-mode str · default='ignore-start'
Compatibility option hidden from default help. Choices: ['ignore-start', 'official-overlap'].
--metric-stitch-burn-in int · default=150
Compatibility option hidden from default help.
--soma-affine-calibration flag · default=False
Rescale predictions to the evaluation targets' mean and standard deviation; declare this calibration when comparing metrics. Sets soma_affine_calibration=True.
--pin-memory flag · default=False
Stage CPU arrays in pinned memory before a CUDA transfer. Sets pin_memory=True.
--blocking-transfer flag · default=True
Request asynchronous tensor transfers where supported. Sets non_blocking=False.
--registry str · default=None
append a one-line JSONL record; defaults to <output-dir>/experiment-registry.jsonl
--no-registry flag · default=None
Sets registry='off'.

Parser source

axosim diagnose

write biology-oriented surrogate fidelity diagnostics

Parameters

--preset str · default=None
Choices: ['fulltrace-paper-metric', 'legacy-baseline-smoke'].
--data str · required
Destination: data.
--output-dir str · required
Directory receiving converted shards and their manifest.
--input-dim int · default=1278
Native input-channel count.
--memory-units int · default=30
Width of the recurrent memory state.
--branches int · default=32
Number of routed branch features in the adapter.
--model-kind str · default='baseline'
Checkpoint architecture/backend discriminator. Choices: ['baseline', 'official', 'axomamba', 'mamba-official', 'mamba-pytorch', 'branch-mamba-pytorch', 'branch-trace-rnn'].
--model-config str · default='configs/branch_elm_30_official.json'
Destination: model_config.
--batch-size int · default=8
Examples processed per batch.
--seed int · default=0
Random seed for the declared operation.
--device str · default='cpu'
Execution or allocation device.
--checkpoint str · default=None
Upstream baseline checkpoint file.
--window-size int · default=None
Native timesteps per extracted window.
--window-stride int · default=None
Native timestep distance between successive window starts.
--ignore-start int · default=0
Initial native timesteps excluded by the declared path.
--cache-shards int · default=1
Maximum cached shards; zero disables the cache.
--metric-ignore-start int · default=0
Destination: metric_ignore_start.
--metric-mask-mode str · default='ignore-start'
Compatibility option hidden from default help. Choices: ['ignore-start', 'official-overlap'].
--metric-stitch-burn-in int · default=150
Compatibility option hidden from default help.
--soma-affine-calibration flag · default=False
Rescale predictions to the evaluation targets' mean and standard deviation; declare this calibration when comparing metrics. Sets soma_affine_calibration=True.
--max-samples int · default=None
Destination: max_samples.
--pin-memory flag · default=False
Stage CPU arrays in pinned memory before a CUDA transfer. Sets pin_memory=True.
--blocking-transfer flag · default=True
Request asynchronous tensor transfers where supported. Sets non_blocking=False.

Parser source

axosim train

train a model with the current experiment workflow

Parameters

--preset str · default=None
Choices: ['axomamba-probe', 'legacy-baseline-smoke', 'mamba-official-probe', 'mamba2-official-probe', 'official-fulltrace-reference', 'paper-random-fulltrace'].
--data str · required
Destination: data.
--checkpoint str · required
Upstream baseline checkpoint file.
--metrics str · required
Metrics dictionary to serialize.
--input-dim int · default=1278
Native input-channel count.
--memory-units int · default=30
Width of the recurrent memory state.
--branches int · default=32
Number of routed branch features in the adapter.
--model-kind str · default='baseline'
use 'official' for the paper-style model, 'axomamba' for the promoted Mamba surrogate, 'mamba-official' for the generic official mamba-ssm backend, or 'branch-trace-rnn' for the RNN comparison path; 'baseline' is legacy/debug Choices: ['baseline', 'official', 'axomamba', 'mamba-official', 'mamba-pytorch', 'branch-mamba-pytorch', 'branch-trace-rnn'].
--model-config str · default='configs/branch_elm_30_official.json'
Destination: model_config.
--epochs int · default=1
Number of passes over the declared epoch sampling budget.
--batch-size int · default=8
Examples processed per batch.
--learning-rate float · default=0.0005
Optimizer step size.
--burn-in int · default=0
Initial timesteps excluded from training losses.
--seed int · default=0
Random seed for the declared operation.
--device str · default='cpu'
Execution or allocation device.
--window-size int · default=None
Native timesteps per extracted window.
--window-stride int · default=None
Native timestep distance between successive window starts.
--ignore-start int · default=0
Initial native timesteps excluded by the declared path.
--window-sampling str · default='random-full-trace'
Choices: ['deterministic', 'random-full-trace', 'official-full-trace'].
--epoch-samples int · default=None
Destination: epoch_samples.
--shard-reuse-batches int · default=1
Number of consecutive batches sampled before advancing to another shard.
--file-load-fraction float · default=0.3
Fraction of each shard made available to the sampling path.
--full-trace-length int · default=None
Destination: full_trace_length.
--sample-window-reads flag · default=False
read random/official windows by sample instead of caching full compressed shards Sets sample_window_reads=True.
--shuffle-mode str · default='shard'
Choose sample-level or shard-level reordering. Choices: ['sample', 'shard', 'none'].
--cache-shards int · default=1
Maximum cached shards; zero disables the cache.
--val-data str · default=None
Destination: val_data.
--val-batch-size int · default=None
Destination: val_batch_size.
--val-cache-shards int · default=1
Destination: val_cache_shards.
--val-window-size int · default=None
Destination: val_window_size.
--val-window-stride int · default=None
Destination: val_window_stride.
--val-ignore-start int · default=0
Destination: val_ignore_start.
--val-soma-units str · default='millivolts'
Choices: ['millivolts', 'normalized'].
--val-metric-ignore-start int · default=500
Destination: val_metric_ignore_start.
--val-metric-mask-mode str · default='ignore-start'
Compatibility option hidden from default help. Choices: ['ignore-start', 'official-overlap'].
--val-metric-stitch-burn-in int · default=150
Compatibility option hidden from default help.
--val-soma-affine-calibration flag · default=True
Sets val_soma_affine_calibration=True.
--no-val-soma-affine-calibration flag · default=True
Sets val_soma_affine_calibration=False.
--best-checkpoint str · default=None
Destination: best_checkpoint.
--max-train-batches int · default=None
Optional cap on batches in each training epoch.
--lr-schedule str · default='constant'
Learning-rate schedule selection. Choices: ['constant', 'cosine'].
--lr-schedule-steps int · default=None
Number of optimizer steps used to parameterize the schedule.
--optimizer str · default='adam'
Optimizer attached to the selected parameters. Choices: ['adam', 'adamw'].
--weight-decay float · default=0.0
Optimizer regularization coefficient.
--l1-lambda float · default=0.0
Coefficient of the L1 penalty on model parameters.
--spike-loss-weight float · default=0.5
Multiplier applied to the spike training loss.
--soma-loss-weight float · default=0.5
Multiplier applied to the soma training loss.
--sparse-soma-loss-weight float · default=0.0
Coefficient of auxiliary soma MSE over teacher-defined high-importance timesteps.
--sparse-soma-high-voltage-quantile float · default=0.9
Teacher-voltage quantile used to select high-voltage timesteps.
--sparse-soma-high-dvdt-quantile float · default=0.9
Absolute teacher-voltage difference quantile used to select rapidly changing timesteps.
--sparse-soma-input-event-quantile float · default=0.95
Positive input-activity quantile used to select event-adjacent timesteps.
--sparse-soma-spike-window int · default=5
Symmetric native-timestep radius around reference spikes in the auxiliary mask.
--sparse-soma-post-event-window int · default=5
Causal native-timestep window after selected input events.
--sera-soma-loss-weight float · default=0.0
Coefficient of the relevance-weighted auxiliary soma loss.
--sera-soma-min-weight float · default=0.05
Minimum timestep weight in the relevance-weighted soma loss.
--sera-soma-relevance-power float · default=1.0
Exponent applied to the teacher-derived relevance weights.
--soma-slope-loss-weight float · default=0.0
Coefficient of squared error in adjacent-timestep soma differences.
--grad-clip-norm float · default=0.0
Maximum gradient norm when clipping is enabled.
--train-update-log-interval int · default=0
Destination: train_update_log_interval.
--train-update-log str · default=None
Destination: train_update_log.
--prefetch-batches int · default=0
Number of dataset batches prepared ahead of consumption.
--pin-memory flag · default=False
Stage CPU arrays in pinned memory before a CUDA transfer. Sets pin_memory=True.
--blocking-transfer flag · default=True
Request asynchronous tensor transfers where supported. Sets non_blocking=False.
--registry str · default=None
append a one-line JSONL record; defaults to <metrics-dir>/experiment-registry.jsonl
--no-registry flag · default=None
Sets registry='off'.

Parser source

axosim benchmark

time model forward passes on random input

Parameters

--input-dim int · default=1278
Native input-channel count.
--memory-units int · default=30
Width of the recurrent memory state.
--branches int · default=32
Number of routed branch features in the adapter.
--model-kind str · default='baseline'
use 'official' for the paper-style model, 'mamba-official' for the official mamba-ssm backend, or 'branch-trace-rnn' for the RNN comparison path; 'baseline' is legacy/debug Choices: ['baseline', 'official', 'axomamba', 'mamba-official', 'mamba-pytorch', 'branch-mamba-pytorch', 'branch-trace-rnn'].
--model-config str · default='configs/branch_elm_30_official.json'
Destination: model_config.
--batch-size int · default=1
Examples processed per batch.
--time-steps int · default=500
Native sequence horizon.
--runs int · default=10
Measured repetitions after the declared warmup.
--device str · default='cpu'
Execution or allocation device.
--compile flag · default=False
Enable the benchmark's compilation path. Sets compile_model=True.
--output str · default=None
Destination: output.

Parser source

axosim inference-benchmark

benchmark deployment-oriented inference throughput across batch and sequence scales

Parameters

--input-dim int · default=1278
Native input-channel count.
--memory-units int · default=30
Width of the recurrent memory state.
--branches int · default=32
Number of routed branch features in the adapter.
--model-kind str · default='baseline'
Checkpoint architecture/backend discriminator. Choices: ['baseline', 'official', 'axomamba', 'mamba-official', 'mamba-pytorch', 'branch-mamba-pytorch', 'branch-trace-rnn'].
--model-config str · default='configs/branch_elm_30_official.json'
Destination: model_config.
--checkpoint str · default=None
Upstream baseline checkpoint file.
--batch-sizes str · default='1,8,32,128'
Batch sizes included in the benchmark matrix.
--time-steps str · default='500,1000,6000'
Native sequence horizon.
--runs int · default=20
Measured repetitions after the declared warmup.
--warmup-runs int · default=5
Unmeasured iterations before the timing repetitions.
--precision str · default='float32'
Floating-point execution precision. Choices: ['float32', 'float16', 'bfloat16'].
--device str · default='cpu'
Execution or allocation device.
--compile flag · default=False
Enable the benchmark's compilation path. Sets compile_model=True.
--accuracy-metrics str · default=None
Destination: accuracy_metrics.
--output str · required
Destination: output.

Parser source

Search guides, examples, and API signatures.