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]
Fit the supplied model with spike and soma losses; optionally validate after each epoch and save the best voltage result.
Parameters
modelBranchELM- required. Model to execute, optimize, count, or serialize for this operation.
datasetShardedNeuronIODataset- required. Trace dataset supporting the batching contract used by this operation.
epochsint- keyword-only, default=1. Number of passes over the declared epoch sampling budget.
batch_sizeint- keyword-only, default=8. Examples processed per batch.
learning_ratefloat- keyword-only, default=0.0005. Optimizer step size.
burn_inint- keyword-only, default=0. Initial timesteps excluded from training losses.
devicestr- keyword-only, default='cpu'. Execution or allocation device.
seedint- keyword-only, default=0. Random seed for the declared operation.
validation_datasetShardedNeuronIODataset | None- keyword-only, default=None. Development data for choosing trained states and calibration.
validation_batch_sizeint | None- keyword-only, default=None. Validation batch size; None uses the training batch size.
best_checkpoint_pathstr | Path | None- keyword-only, default=None. Destination for the state with the lowest validation soma RMSE.
validation_soma_unitsstr- keyword-only, default='millivolts'. Soma coordinate convention for validation RMSE.
validation_metric_ignore_startint- keyword-only, default=0. Initial native timesteps excluded from validation metrics.
validation_metric_mask_modestr- keyword-only, default='ignore-start'. Temporal masking policy used for validation metrics.
validation_metric_stitch_burn_inint- keyword-only, default=150. Overlap exclusion for stitched validation traces.
validation_soma_affine_calibrationbool- keyword-only, default=False. Apply target-statistic affine calibration to validation soma predictions.
max_train_batchesint | None- keyword-only, default=None. Optional cap on batches in each training epoch.
lr_schedulestr- keyword-only, default='constant'. Learning-rate schedule selection.
lr_schedule_stepsint | None- keyword-only, default=None. Number of optimizer steps used to parameterize the schedule.
optimizer_namestr- keyword-only, default='adam'. Optimizer selection supported by this training path.
weight_decayfloat- keyword-only, default=0.0. Optimizer regularization coefficient.
l1_lambdafloat- keyword-only, default=0.0. Coefficient of the L1 penalty on model parameters.
spike_loss_weightfloat- keyword-only, default=0.5. Multiplier applied to the spike training loss.
soma_loss_weightfloat- keyword-only, default=0.5. Multiplier applied to the soma training loss.
sparse_soma_loss_weightfloat- keyword-only, default=0.0. Coefficient of auxiliary soma MSE over teacher-defined high-importance timesteps.
sparse_soma_high_voltage_quantilefloat- keyword-only, default=0.9. Teacher-voltage quantile used to select high-voltage timesteps.
sparse_soma_high_dvdt_quantilefloat- keyword-only, default=0.9. Absolute teacher-voltage difference quantile used to select rapidly changing timesteps.
sparse_soma_input_event_quantilefloat- keyword-only, default=0.95. Positive input-activity quantile used to select event-adjacent timesteps.
sparse_soma_spike_windowint- keyword-only, default=5. Symmetric native-timestep radius around reference spikes in the auxiliary mask.
sparse_soma_post_event_windowint- keyword-only, default=5. Causal native-timestep window after selected input events.
sera_soma_loss_weightfloat- keyword-only, default=0.0. Coefficient of the relevance-weighted auxiliary soma loss.
sera_soma_min_weightfloat- keyword-only, default=0.05. Minimum timestep weight in the relevance-weighted soma loss.
sera_soma_relevance_powerfloat- keyword-only, default=1.0. Exponent applied to the teacher-derived relevance weights.
soma_slope_loss_weightfloat- keyword-only, default=0.0. Coefficient of squared error in adjacent-timestep soma differences.
grad_clip_normfloat- keyword-only, default=0.0. Maximum gradient norm when clipping is enabled.
update_log_intervalint- keyword-only, default=0. Optimizer-step interval between update-log records; zero disables logging.
update_log_pathstr | Path | None- keyword-only, default=None. Destination for per-update JSON log records.
prefetch_batchesint- keyword-only, default=0. Number of dataset batches prepared ahead of consumption.
pin_memorybool- keyword-only, default=False. Stage CPU arrays in pinned memory before a CUDA transfer.
non_blockingbool- keyword-only, default=True. Request asynchronous tensor transfers where supported.
Returns
metricsdict[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]
Train the supplied model, save its final weights and configuration, and write training metrics as JSON.
Parameters
modelBranchELM- required. Model to execute, optimize, count, or serialize for this operation.
datasetShardedNeuronIODataset- required. Trace dataset supporting the batching contract used by this operation.
checkpoint_pathstr | Path- keyword-only, required. Trusted model-weight file to reconstruct or evaluate.
metrics_pathstr | Path- keyword-only, required. Destination for training metrics JSON.
epochsint- keyword-only, default=1. Number of passes over the declared epoch sampling budget.
batch_sizeint- keyword-only, default=8. Examples processed per batch.
learning_ratefloat- keyword-only, default=0.0005. Optimizer step size.
burn_inint- keyword-only, default=0. Initial timesteps excluded from training losses.
devicestr- keyword-only, default='cpu'. Execution or allocation device.
seedint- keyword-only, default=0. Random seed for the declared operation.
validation_datasetShardedNeuronIODataset | None- keyword-only, default=None. Development data for choosing trained states and calibration.
validation_batch_sizeint | None- keyword-only, default=None. Validation batch size; None uses the training batch size.
best_checkpoint_pathstr | Path | None- keyword-only, default=None. Destination for the state with the lowest validation soma RMSE.
validation_soma_unitsstr- keyword-only, default='millivolts'. Soma coordinate convention for validation RMSE.
validation_metric_ignore_startint- keyword-only, default=0. Initial native timesteps excluded from validation metrics.
validation_metric_mask_modestr- keyword-only, default='ignore-start'. Temporal masking policy used for validation metrics.
validation_metric_stitch_burn_inint- keyword-only, default=150. Overlap exclusion for stitched validation traces.
validation_soma_affine_calibrationbool- keyword-only, default=False. Apply target-statistic affine calibration to validation soma predictions.
max_train_batchesint | None- keyword-only, default=None. Optional cap on batches in each training epoch.
lr_schedulestr- keyword-only, default='constant'. Learning-rate schedule selection.
lr_schedule_stepsint | None- keyword-only, default=None. Number of optimizer steps used to parameterize the schedule.
optimizer_namestr- keyword-only, default='adam'. Optimizer selection supported by this training path.
weight_decayfloat- keyword-only, default=0.0. Optimizer regularization coefficient.
l1_lambdafloat- keyword-only, default=0.0. Coefficient of the L1 penalty on model parameters.
spike_loss_weightfloat- keyword-only, default=0.5. Multiplier applied to the spike training loss.
soma_loss_weightfloat- keyword-only, default=0.5. Multiplier applied to the soma training loss.
sparse_soma_loss_weightfloat- keyword-only, default=0.0. Coefficient of auxiliary soma MSE over teacher-defined high-importance timesteps.
sparse_soma_high_voltage_quantilefloat- keyword-only, default=0.9. Teacher-voltage quantile used to select high-voltage timesteps.
sparse_soma_high_dvdt_quantilefloat- keyword-only, default=0.9. Absolute teacher-voltage difference quantile used to select rapidly changing timesteps.
sparse_soma_input_event_quantilefloat- keyword-only, default=0.95. Positive input-activity quantile used to select event-adjacent timesteps.
sparse_soma_spike_windowint- keyword-only, default=5. Symmetric native-timestep radius around reference spikes in the auxiliary mask.
sparse_soma_post_event_windowint- keyword-only, default=5. Causal native-timestep window after selected input events.
sera_soma_loss_weightfloat- keyword-only, default=0.0. Coefficient of the relevance-weighted auxiliary soma loss.
sera_soma_min_weightfloat- keyword-only, default=0.05. Minimum timestep weight in the relevance-weighted soma loss.
sera_soma_relevance_powerfloat- keyword-only, default=1.0. Exponent applied to the teacher-derived relevance weights.
soma_slope_loss_weightfloat- keyword-only, default=0.0. Coefficient of squared error in adjacent-timestep soma differences.
grad_clip_normfloat- keyword-only, default=0.0. Maximum gradient norm when clipping is enabled.
update_log_intervalint- keyword-only, default=0. Optimizer-step interval between update-log records; zero disables logging.
update_log_pathstr | Path | None- keyword-only, default=None. Destination for per-update JSON log records.
prefetch_batchesint- keyword-only, default=0. Number of dataset batches prepared ahead of consumption.
pin_memorybool- keyword-only, default=False. Stage CPU arrays in pinned memory before a CUDA transfer.
non_blockingbool- keyword-only, default=True. Request asynchronous tensor transfers where supported.
Returns
metricsdict[str, Any]- The training metrics returned by train_dataset; the requested checkpoint and metrics JSON are also written.