API reference

Training functions

Signatures, parameters, return contracts, and source for training functions.

Overview

The trainer fits native spike and soma targets with configurable losses, optimization, windowing, and validation. Model checkpoints store weights and metadata; preserve optimizer, scheduler, random, and data-order states separately when continuing an optimization trajectory.

Source revision: caef7be03abd. Public export index.

train_dataset

axosim.train.train_dataset(model: BranchELM, dataset: ShardedNeuronIODataset, *, epochs: int=1, batch_size: int=8, learning_rate: float=0.0005, burn_in: int=0, device: str='cpu', seed: int=0, validation_dataset: ShardedNeuronIODataset | None=None, validation_batch_size: int | None=None, best_checkpoint_path: str | Path | None=None, validation_soma_units: str='millivolts', validation_metric_ignore_start: int=0, validation_metric_mask_mode: str='ignore-start', validation_metric_stitch_burn_in: int=150, validation_soma_affine_calibration: bool=False, max_train_batches: int | None=None, lr_schedule: str='constant', lr_schedule_steps: int | None=None, optimizer_name: str='adam', weight_decay: float=0.0, l1_lambda: float=0.0, spike_loss_weight: float=0.5, soma_loss_weight: float=0.5, sparse_soma_loss_weight: float=0.0, sparse_soma_high_voltage_quantile: float=0.9, sparse_soma_high_dvdt_quantile: float=0.9, sparse_soma_input_event_quantile: float=0.95, sparse_soma_spike_window: int=5, sparse_soma_post_event_window: int=5, sera_soma_loss_weight: float=0.0, sera_soma_min_weight: float=0.05, sera_soma_relevance_power: float=1.0, soma_slope_loss_weight: float=0.0, grad_clip_norm: float=0.0, update_log_interval: int=0, update_log_path: str | Path | None=None, prefetch_batches: int=0, pin_memory: bool=False, non_blocking: bool=True) -> dict[str, Any]

Source

Fit the supplied model with spike and soma losses; optionally validate after each epoch and save the best voltage result.

Parameters

model BranchELM
required. Model to execute, optimize, count, or serialize for this operation.
dataset ShardedNeuronIODataset
required. Trace dataset supporting the batching contract used by this operation.
epochs int
keyword-only, default=1. Number of passes over the declared epoch sampling budget.
batch_size int
keyword-only, default=8. Examples processed per batch.
learning_rate float
keyword-only, default=0.0005. Optimizer step size.
burn_in int
keyword-only, default=0. Initial timesteps excluded from training losses.
device str
keyword-only, default='cpu'. Execution or allocation device.
seed int
keyword-only, default=0. Random seed for the declared operation.
validation_dataset ShardedNeuronIODataset | None
keyword-only, default=None. Development data for choosing trained states and calibration.
validation_batch_size int | None
keyword-only, default=None. Validation batch size; None uses the training batch size.
best_checkpoint_path str | Path | None
keyword-only, default=None. Destination for the state with the lowest validation soma RMSE.
validation_soma_units str
keyword-only, default='millivolts'. Soma coordinate convention for validation RMSE.
validation_metric_ignore_start int
keyword-only, default=0. Initial native timesteps excluded from validation metrics.
validation_metric_mask_mode str
keyword-only, default='ignore-start'. Temporal masking policy used for validation metrics.
validation_metric_stitch_burn_in int
keyword-only, default=150. Overlap exclusion for stitched validation traces.
validation_soma_affine_calibration bool
keyword-only, default=False. Apply target-statistic affine calibration to validation soma predictions.
max_train_batches int | None
keyword-only, default=None. Optional cap on batches in each training epoch.
lr_schedule str
keyword-only, default='constant'. Learning-rate schedule selection.
lr_schedule_steps int | None
keyword-only, default=None. Number of optimizer steps used to parameterize the schedule.
optimizer_name str
keyword-only, default='adam'. Optimizer selection supported by this training path.
weight_decay float
keyword-only, default=0.0. Optimizer regularization coefficient.
l1_lambda float
keyword-only, default=0.0. Coefficient of the L1 penalty on model parameters.
spike_loss_weight float
keyword-only, default=0.5. Multiplier applied to the spike training loss.
soma_loss_weight float
keyword-only, default=0.5. Multiplier applied to the soma training loss.
sparse_soma_loss_weight float
keyword-only, default=0.0. Coefficient of auxiliary soma MSE over teacher-defined high-importance timesteps.
sparse_soma_high_voltage_quantile float
keyword-only, default=0.9. Teacher-voltage quantile used to select high-voltage timesteps.
sparse_soma_high_dvdt_quantile float
keyword-only, default=0.9. Absolute teacher-voltage difference quantile used to select rapidly changing timesteps.
sparse_soma_input_event_quantile float
keyword-only, default=0.95. Positive input-activity quantile used to select event-adjacent timesteps.
sparse_soma_spike_window int
keyword-only, default=5. Symmetric native-timestep radius around reference spikes in the auxiliary mask.
sparse_soma_post_event_window int
keyword-only, default=5. Causal native-timestep window after selected input events.
sera_soma_loss_weight float
keyword-only, default=0.0. Coefficient of the relevance-weighted auxiliary soma loss.
sera_soma_min_weight float
keyword-only, default=0.05. Minimum timestep weight in the relevance-weighted soma loss.
sera_soma_relevance_power float
keyword-only, default=1.0. Exponent applied to the teacher-derived relevance weights.
soma_slope_loss_weight float
keyword-only, default=0.0. Coefficient of squared error in adjacent-timestep soma differences.
grad_clip_norm float
keyword-only, default=0.0. Maximum gradient norm when clipping is enabled.
update_log_interval int
keyword-only, default=0. Optimizer-step interval between update-log records; zero disables logging.
update_log_path str | Path | None
keyword-only, default=None. Destination for per-update JSON log records.
prefetch_batches int
keyword-only, default=0. Number of dataset batches prepared ahead of consumption.
pin_memory bool
keyword-only, default=False. Stage CPU arrays in pinned memory before a CUDA transfer.
non_blocking bool
keyword-only, default=True. Request asynchronous tensor transfers where supported.

Returns

metrics dict[str, Any]
Epoch history, final training loss and timing, optimizer/loss settings, and optional validation and best-state metrics. The supplied model retains its final trained weights.

train_and_save

axosim.train.train_and_save(model: BranchELM, dataset: ShardedNeuronIODataset, *, checkpoint_path: str | Path, metrics_path: str | Path, epochs: int=1, batch_size: int=8, learning_rate: float=0.0005, burn_in: int=0, device: str='cpu', seed: int=0, validation_dataset: ShardedNeuronIODataset | None=None, validation_batch_size: int | None=None, best_checkpoint_path: str | Path | None=None, validation_soma_units: str='millivolts', validation_metric_ignore_start: int=0, validation_metric_mask_mode: str='ignore-start', validation_metric_stitch_burn_in: int=150, validation_soma_affine_calibration: bool=False, max_train_batches: int | None=None, lr_schedule: str='constant', lr_schedule_steps: int | None=None, optimizer_name: str='adam', weight_decay: float=0.0, l1_lambda: float=0.0, spike_loss_weight: float=0.5, soma_loss_weight: float=0.5, sparse_soma_loss_weight: float=0.0, sparse_soma_high_voltage_quantile: float=0.9, sparse_soma_high_dvdt_quantile: float=0.9, sparse_soma_input_event_quantile: float=0.95, sparse_soma_spike_window: int=5, sparse_soma_post_event_window: int=5, sera_soma_loss_weight: float=0.0, sera_soma_min_weight: float=0.05, sera_soma_relevance_power: float=1.0, soma_slope_loss_weight: float=0.0, grad_clip_norm: float=0.0, update_log_interval: int=0, update_log_path: str | Path | None=None, prefetch_batches: int=0, pin_memory: bool=False, non_blocking: bool=True) -> dict[str, Any]

Source

Train the supplied model, save its final weights and configuration, and write training metrics as JSON.

Parameters

model BranchELM
required. Model to execute, optimize, count, or serialize for this operation.
dataset ShardedNeuronIODataset
required. Trace dataset supporting the batching contract used by this operation.
checkpoint_path str | Path
keyword-only, required. Trusted model-weight file to reconstruct or evaluate.
metrics_path str | Path
keyword-only, required. Destination for training metrics JSON.
epochs int
keyword-only, default=1. Number of passes over the declared epoch sampling budget.
batch_size int
keyword-only, default=8. Examples processed per batch.
learning_rate float
keyword-only, default=0.0005. Optimizer step size.
burn_in int
keyword-only, default=0. Initial timesteps excluded from training losses.
device str
keyword-only, default='cpu'. Execution or allocation device.
seed int
keyword-only, default=0. Random seed for the declared operation.
validation_dataset ShardedNeuronIODataset | None
keyword-only, default=None. Development data for choosing trained states and calibration.
validation_batch_size int | None
keyword-only, default=None. Validation batch size; None uses the training batch size.
best_checkpoint_path str | Path | None
keyword-only, default=None. Destination for the state with the lowest validation soma RMSE.
validation_soma_units str
keyword-only, default='millivolts'. Soma coordinate convention for validation RMSE.
validation_metric_ignore_start int
keyword-only, default=0. Initial native timesteps excluded from validation metrics.
validation_metric_mask_mode str
keyword-only, default='ignore-start'. Temporal masking policy used for validation metrics.
validation_metric_stitch_burn_in int
keyword-only, default=150. Overlap exclusion for stitched validation traces.
validation_soma_affine_calibration bool
keyword-only, default=False. Apply target-statistic affine calibration to validation soma predictions.
max_train_batches int | None
keyword-only, default=None. Optional cap on batches in each training epoch.
lr_schedule str
keyword-only, default='constant'. Learning-rate schedule selection.
lr_schedule_steps int | None
keyword-only, default=None. Number of optimizer steps used to parameterize the schedule.
optimizer_name str
keyword-only, default='adam'. Optimizer selection supported by this training path.
weight_decay float
keyword-only, default=0.0. Optimizer regularization coefficient.
l1_lambda float
keyword-only, default=0.0. Coefficient of the L1 penalty on model parameters.
spike_loss_weight float
keyword-only, default=0.5. Multiplier applied to the spike training loss.
soma_loss_weight float
keyword-only, default=0.5. Multiplier applied to the soma training loss.
sparse_soma_loss_weight float
keyword-only, default=0.0. Coefficient of auxiliary soma MSE over teacher-defined high-importance timesteps.
sparse_soma_high_voltage_quantile float
keyword-only, default=0.9. Teacher-voltage quantile used to select high-voltage timesteps.
sparse_soma_high_dvdt_quantile float
keyword-only, default=0.9. Absolute teacher-voltage difference quantile used to select rapidly changing timesteps.
sparse_soma_input_event_quantile float
keyword-only, default=0.95. Positive input-activity quantile used to select event-adjacent timesteps.
sparse_soma_spike_window int
keyword-only, default=5. Symmetric native-timestep radius around reference spikes in the auxiliary mask.
sparse_soma_post_event_window int
keyword-only, default=5. Causal native-timestep window after selected input events.
sera_soma_loss_weight float
keyword-only, default=0.0. Coefficient of the relevance-weighted auxiliary soma loss.
sera_soma_min_weight float
keyword-only, default=0.05. Minimum timestep weight in the relevance-weighted soma loss.
sera_soma_relevance_power float
keyword-only, default=1.0. Exponent applied to the teacher-derived relevance weights.
soma_slope_loss_weight float
keyword-only, default=0.0. Coefficient of squared error in adjacent-timestep soma differences.
grad_clip_norm float
keyword-only, default=0.0. Maximum gradient norm when clipping is enabled.
update_log_interval int
keyword-only, default=0. Optimizer-step interval between update-log records; zero disables logging.
update_log_path str | Path | None
keyword-only, default=None. Destination for per-update JSON log records.
prefetch_batches int
keyword-only, default=0. Number of dataset batches prepared ahead of consumption.
pin_memory bool
keyword-only, default=False. Stage CPU arrays in pinned memory before a CUDA transfer.
non_blocking bool
keyword-only, default=True. Request asynchronous tensor transfers where supported.

Returns

metrics dict[str, Any]
The training metrics returned by train_dataset; the requested checkpoint and metrics JSON are also written.

Search guides, examples, and API signatures.