neuromap.trainer

neuromap.trainer

Reusable training loop for Neuromap SNN networks.

The :class:Trainer encapsulates gradient clipping, LR scheduling with warmup, early stopping, and best-checkpoint tracking in a single high-level API.

Example::

from neuromap import Network, Trainer, chips

net = Network(chips.NEUROSOC_V1, use_decoder=False)
trainer = Trainer(net, lr=1e-3, epochs=20)
history = trainer.fit(train_loader, val_loader)

TrainHistory dataclass

Container for per-epoch training metrics.

Each element in :attr:epochs is a dictionary with at least epoch, train_loss, and learning_rate keys. When validation is used, val_loss is also present.

append(row)

Append a single epoch's metrics.

to_list()

Return the epochs list (shallow copy).

Trainer

High-level training driver for :class:~neuromap.network.Network.

Parameters:

Name	Type	Description	Default
network	Any	A :class:~neuromap.network.Network instance.	required
lr	float	Initial learning rate.	0.0003
epochs	int	Maximum number of training epochs.	40
device	str	Torch device string (e.g. "cpu", "cuda").	'cpu'
optimizer	str	Optimizer class name: "adam" or "sgd".	'adam'
weight_decay	float	L2 regularisation weight.	1e-06
scheduler	str	LR scheduler type: "plateau", "cosine", or "none".	'plateau'
scheduler_factor	float	Factor by which LR is reduced (plateau).	0.5
scheduler_patience	int	Epochs of no improvement before LR reduction.	2
min_lr	float	Minimum learning rate for the scheduler.	1e-06
lr_warmup_epochs	int	Epochs for linear LR warmup from 0 to lr.	3
early_stop_patience	int	Stop after this many epochs without val-loss improvement.	8
early_stop_min_delta	float	Minimum decrease to count as improvement.	0.0001
grad_clip_norm	float	Max gradient norm for clipping (<=0 disables).	1.0
loss_fn	Callable[..., Tensor] | None	Optional custom loss (preds, targets) -> scalar. Defaults to MSE.	None
use_sequence_forward	bool	If True, use model.forward_sequence for frame-level loss instead of rate-coded model.forward.	False

fit(train_loader, val_loader=None, *, verbose=True)

Train the network and return a :class:TrainHistory.

Each element in train_loader / val_loader must yield either a (x, y) tuple of tensors, or an object with .x and .y attributes.

Parameters:

Name	Type	Description	Default
train_loader	DataLoader	Training data loader.	required
val_loader	DataLoader | None	Optional validation data loader.	None
verbose	bool	Print epoch-level progress to stdout.	True

Returns:

Name	Type	Description
A	TrainHistory	class:TrainHistory with per-epoch metrics.

evaluate(dataloader)

Evaluate the network and return a metric dictionary.

Parameters:

Name	Type	Description	Default
dataloader	DataLoader	Data loader to evaluate on.	required

Returns:

Type	Description
dict[str, float]	Dictionary with at least a "loss" key.