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
--outputstr · required- Destination: output.
--samplesint · default=8- Destination: samples.
--shardsint · default=1- Destination: shards.
--time-stepsint · default=32- Native sequence horizon.
--input-dimint · default=64- Native input-channel count.
--seedint · default=0- Random seed for the declared operation.
axosim convert-neuronio
convert raw NeuronIO pickle files to deterministic shards
Parameters
--inputstr · required- Destination: input.
--outputstr · required- Destination: output.
--shard-sizeint · default=128- Maximum sample count in each converted shard.
--window-sizeint · default=None- Native timesteps per extracted window.
--window-strideint · default=None- Native timestep distance between successive window starts.
--ignore-startint · default=0- Initial native timesteps excluded by the declared path.
axosim repack-shards
repack shards as sliceable .npy arrays
Parameters
--inputstr · required- Destination: input.
--outputstr · required- Destination: output.
--input-dtypestr · default='int8'- Stored NumPy dtype of the converted input arrays. Choices: ['int8', 'float32'].
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
--presetstr · default=None- Choices: ['fulltrace-paper-metric', 'legacy-baseline-smoke'].
--datastr · required- Destination: data.
--outputstr · required- Destination: output.
--input-dimint · default=1278- Native input-channel count.
--memory-unitsint · default=30- Width of the recurrent memory state.
--branchesint · default=32- Number of routed branch features in the adapter.
--model-kindstr · 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-configstr · default='configs/branch_elm_30_official.json'- Destination: model_config.
--batch-sizeint · default=8- Examples processed per batch.
--seedint · default=0- Random seed for the declared operation.
--devicestr · default='cpu'- Execution or allocation device.
--checkpointstr · default=None- Upstream baseline checkpoint file.
--window-sizeint · default=None- Native timesteps per extracted window.
--window-strideint · default=None- Native timestep distance between successive window starts.
--ignore-startint · default=0- Initial native timesteps excluded by the declared path.
--cache-shardsint · default=1- Maximum cached shards; zero disables the cache.
--soma-unitsstr · default='millivolts'- Coordinate convention used when computing the local soma metric. Choices: ['millivolts', 'normalized'].
--metric-ignore-startint · default=0- Destination: metric_ignore_start.
--metric-mask-modestr · default='ignore-start'- Compatibility option hidden from default help. Choices: ['ignore-start', 'official-overlap'].
--metric-stitch-burn-inint · default=150- Compatibility option hidden from default help.
--soma-affine-calibrationflag · default=False- Rescale predictions to the evaluation targets' mean and standard deviation; declare this calibration when comparing metrics. Sets soma_affine_calibration=True.
--pin-memoryflag · default=False- Stage CPU arrays in pinned memory before a CUDA transfer. Sets pin_memory=True.
--blocking-transferflag · default=True- Request asynchronous tensor transfers where supported. Sets non_blocking=False.
--registrystr · default=None- append a one-line JSONL record; defaults to <output-dir>/experiment-registry.jsonl
--no-registryflag · default=None- Sets registry='off'.
axosim diagnose
write biology-oriented surrogate fidelity diagnostics
Parameters
--presetstr · default=None- Choices: ['fulltrace-paper-metric', 'legacy-baseline-smoke'].
--datastr · required- Destination: data.
--output-dirstr · required- Directory receiving converted shards and their manifest.
--input-dimint · default=1278- Native input-channel count.
--memory-unitsint · default=30- Width of the recurrent memory state.
--branchesint · default=32- Number of routed branch features in the adapter.
--model-kindstr · default='baseline'- Checkpoint architecture/backend discriminator. Choices: ['baseline', 'official', 'axomamba', 'mamba-official', 'mamba-pytorch', 'branch-mamba-pytorch', 'branch-trace-rnn'].
--model-configstr · default='configs/branch_elm_30_official.json'- Destination: model_config.
--batch-sizeint · default=8- Examples processed per batch.
--seedint · default=0- Random seed for the declared operation.
--devicestr · default='cpu'- Execution or allocation device.
--checkpointstr · default=None- Upstream baseline checkpoint file.
--window-sizeint · default=None- Native timesteps per extracted window.
--window-strideint · default=None- Native timestep distance between successive window starts.
--ignore-startint · default=0- Initial native timesteps excluded by the declared path.
--cache-shardsint · default=1- Maximum cached shards; zero disables the cache.
--metric-ignore-startint · default=0- Destination: metric_ignore_start.
--metric-mask-modestr · default='ignore-start'- Compatibility option hidden from default help. Choices: ['ignore-start', 'official-overlap'].
--metric-stitch-burn-inint · default=150- Compatibility option hidden from default help.
--soma-affine-calibrationflag · default=False- Rescale predictions to the evaluation targets' mean and standard deviation; declare this calibration when comparing metrics. Sets soma_affine_calibration=True.
--max-samplesint · default=None- Destination: max_samples.
--pin-memoryflag · default=False- Stage CPU arrays in pinned memory before a CUDA transfer. Sets pin_memory=True.
--blocking-transferflag · default=True- Request asynchronous tensor transfers where supported. Sets non_blocking=False.
axosim train
train a model with the current experiment workflow
Parameters
--presetstr · default=None- Choices: ['axomamba-probe', 'legacy-baseline-smoke', 'mamba-official-probe', 'mamba2-official-probe', 'official-fulltrace-reference', 'paper-random-fulltrace'].
--datastr · required- Destination: data.
--checkpointstr · required- Upstream baseline checkpoint file.
--metricsstr · required- Metrics dictionary to serialize.
--input-dimint · default=1278- Native input-channel count.
--memory-unitsint · default=30- Width of the recurrent memory state.
--branchesint · default=32- Number of routed branch features in the adapter.
--model-kindstr · 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-configstr · default='configs/branch_elm_30_official.json'- Destination: model_config.
--epochsint · default=1- Number of passes over the declared epoch sampling budget.
--batch-sizeint · default=8- Examples processed per batch.
--learning-ratefloat · default=0.0005- Optimizer step size.
--burn-inint · default=0- Initial timesteps excluded from training losses.
--seedint · default=0- Random seed for the declared operation.
--devicestr · default='cpu'- Execution or allocation device.
--window-sizeint · default=None- Native timesteps per extracted window.
--window-strideint · default=None- Native timestep distance between successive window starts.
--ignore-startint · default=0- Initial native timesteps excluded by the declared path.
--window-samplingstr · default='random-full-trace'- Choices: ['deterministic', 'random-full-trace', 'official-full-trace'].
--epoch-samplesint · default=None- Destination: epoch_samples.
--shard-reuse-batchesint · default=1- Number of consecutive batches sampled before advancing to another shard.
--file-load-fractionfloat · default=0.3- Fraction of each shard made available to the sampling path.
--full-trace-lengthint · default=None- Destination: full_trace_length.
--sample-window-readsflag · default=False- read random/official windows by sample instead of caching full compressed shards Sets sample_window_reads=True.
--shuffle-modestr · default='shard'- Choose sample-level or shard-level reordering. Choices: ['sample', 'shard', 'none'].
--cache-shardsint · default=1- Maximum cached shards; zero disables the cache.
--val-datastr · default=None- Destination: val_data.
--val-batch-sizeint · default=None- Destination: val_batch_size.
--val-cache-shardsint · default=1- Destination: val_cache_shards.
--val-window-sizeint · default=None- Destination: val_window_size.
--val-window-strideint · default=None- Destination: val_window_stride.
--val-ignore-startint · default=0- Destination: val_ignore_start.
--val-soma-unitsstr · default='millivolts'- Choices: ['millivolts', 'normalized'].
--val-metric-ignore-startint · default=500- Destination: val_metric_ignore_start.
--val-metric-mask-modestr · default='ignore-start'- Compatibility option hidden from default help. Choices: ['ignore-start', 'official-overlap'].
--val-metric-stitch-burn-inint · default=150- Compatibility option hidden from default help.
--val-soma-affine-calibrationflag · default=True- Sets val_soma_affine_calibration=True.
--no-val-soma-affine-calibrationflag · default=True- Sets val_soma_affine_calibration=False.
--best-checkpointstr · default=None- Destination: best_checkpoint.
--max-train-batchesint · default=None- Optional cap on batches in each training epoch.
--lr-schedulestr · default='constant'- Learning-rate schedule selection. Choices: ['constant', 'cosine'].
--lr-schedule-stepsint · default=None- Number of optimizer steps used to parameterize the schedule.
--optimizerstr · default='adam'- Optimizer attached to the selected parameters. Choices: ['adam', 'adamw'].
--weight-decayfloat · default=0.0- Optimizer regularization coefficient.
--l1-lambdafloat · default=0.0- Coefficient of the L1 penalty on model parameters.
--spike-loss-weightfloat · default=0.5- Multiplier applied to the spike training loss.
--soma-loss-weightfloat · default=0.5- Multiplier applied to the soma training loss.
--sparse-soma-loss-weightfloat · default=0.0- Coefficient of auxiliary soma MSE over teacher-defined high-importance timesteps.
--sparse-soma-high-voltage-quantilefloat · default=0.9- Teacher-voltage quantile used to select high-voltage timesteps.
--sparse-soma-high-dvdt-quantilefloat · default=0.9- Absolute teacher-voltage difference quantile used to select rapidly changing timesteps.
--sparse-soma-input-event-quantilefloat · default=0.95- Positive input-activity quantile used to select event-adjacent timesteps.
--sparse-soma-spike-windowint · default=5- Symmetric native-timestep radius around reference spikes in the auxiliary mask.
--sparse-soma-post-event-windowint · default=5- Causal native-timestep window after selected input events.
--sera-soma-loss-weightfloat · default=0.0- Coefficient of the relevance-weighted auxiliary soma loss.
--sera-soma-min-weightfloat · default=0.05- Minimum timestep weight in the relevance-weighted soma loss.
--sera-soma-relevance-powerfloat · default=1.0- Exponent applied to the teacher-derived relevance weights.
--soma-slope-loss-weightfloat · default=0.0- Coefficient of squared error in adjacent-timestep soma differences.
--grad-clip-normfloat · default=0.0- Maximum gradient norm when clipping is enabled.
--train-update-log-intervalint · default=0- Destination: train_update_log_interval.
--train-update-logstr · default=None- Destination: train_update_log.
--prefetch-batchesint · default=0- Number of dataset batches prepared ahead of consumption.
--pin-memoryflag · default=False- Stage CPU arrays in pinned memory before a CUDA transfer. Sets pin_memory=True.
--blocking-transferflag · default=True- Request asynchronous tensor transfers where supported. Sets non_blocking=False.
--registrystr · default=None- append a one-line JSONL record; defaults to <metrics-dir>/experiment-registry.jsonl
--no-registryflag · default=None- Sets registry='off'.
axosim benchmark
time model forward passes on random input
Parameters
--input-dimint · default=1278- Native input-channel count.
--memory-unitsint · default=30- Width of the recurrent memory state.
--branchesint · default=32- Number of routed branch features in the adapter.
--model-kindstr · 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-configstr · default='configs/branch_elm_30_official.json'- Destination: model_config.
--batch-sizeint · default=1- Examples processed per batch.
--time-stepsint · default=500- Native sequence horizon.
--runsint · default=10- Measured repetitions after the declared warmup.
--devicestr · default='cpu'- Execution or allocation device.
--compileflag · default=False- Enable the benchmark's compilation path. Sets compile_model=True.
--outputstr · default=None- Destination: output.
axosim inference-benchmark
benchmark deployment-oriented inference throughput across batch and sequence scales
Parameters
--input-dimint · default=1278- Native input-channel count.
--memory-unitsint · default=30- Width of the recurrent memory state.
--branchesint · default=32- Number of routed branch features in the adapter.
--model-kindstr · default='baseline'- Checkpoint architecture/backend discriminator. Choices: ['baseline', 'official', 'axomamba', 'mamba-official', 'mamba-pytorch', 'branch-mamba-pytorch', 'branch-trace-rnn'].
--model-configstr · default='configs/branch_elm_30_official.json'- Destination: model_config.
--checkpointstr · default=None- Upstream baseline checkpoint file.
--batch-sizesstr · default='1,8,32,128'- Batch sizes included in the benchmark matrix.
--time-stepsstr · default='500,1000,6000'- Native sequence horizon.
--runsint · default=20- Measured repetitions after the declared warmup.
--warmup-runsint · default=5- Unmeasured iterations before the timing repetitions.
--precisionstr · default='float32'- Floating-point execution precision. Choices: ['float32', 'float16', 'bfloat16'].
--devicestr · default='cpu'- Execution or allocation device.
--compileflag · default=False- Enable the benchmark's compilation path. Sets compile_model=True.
--accuracy-metricsstr · default=None- Destination: accuracy_metrics.
--outputstr · required- Destination: output.