ExecutionResult

Import result types from snnlab.sim.execution. ExecutionSpec configures a run; these objects carry its results.

from snnlab.sim.execution import ExecutionResult, NumpyExecutionResult

FieldsCopy Anchor Link

The result class uses empty mappings/None for absent data. Attributes are populated by the operation; do not assume every handler returns all state. For example, graph training returns final-update outputs/diagnostics and checkpoints but does not populate its result’s runtime_state field.

Epoch metricsCopy Anchor Link

In dataset iteration mode (epochs > 0), train evaluates the complete training split at initialization and after each completed epoch. Supplying validation also evaluates the held-out split at those points. Results are returned as result.metrics["epochs"]:

Each evaluation uses fixed weights and minibatches bounded by batch_size. The final smaller batch is weighted by its actual sample count. Training samples are not shuffled during evaluation. result.metrics["updates"] retains the separate per-update losses measured before each optimizer step.

Resuming at an epoch boundary evaluates that starting boundary and subsequent completed epochs. Resuming partway through an epoch reports only subsequent completed epochs. An updates limit that stops partway through an epoch adds no partial-epoch measurement. The returned history covers this invocation; previous history is not stored in the checkpoint. Full-batch update mode without positive epochs returns an empty epoch history.

Epoch evaluations do not replace the final update’s returned outputs or diagnostics, and do not affect checkpoint selection, which continues to use update loss. Validation does not perform early stopping or select checkpoints. Epoch evaluation adds forward passes over the splits; training itself remains inside one train call.

numpyCopy Anchor Link

data = result.numpy(batch=0)
spikes = data.outputs["spikes"]
voltages = data.diagnostics["e_voltage"]
time_ms = data.time_ms

ExecutionResult.numpy(*, batch: int | None = None) returns NumpyExecutionResult for plotting or analysis:

The method detaches tensors, transfers them to CPU, and copies their NumPy arrays. Changing the arrays cannot modify the original tensors, and the original result retains its computation graphs. Conversion uses PyTorch’s NumPy-supported dtypes.

Without batch, all batch items and tensor axes are preserved. Passing a non-negative integer selects that item and removes its batch axis. Selection uses the compiled signal shape: (time, batch, cells) becomes (time, cells), while (batch, classes) becomes (classes,). Signals without a batch axis are unchanged. Booleans and non-integer indices raise TypeError; negative or out-of-range indices raise IndexError. Selection requires metadata supplied by the graph executor, and is unavailable on a build-only or manually constructed result without that metadata.

time_ms comes from the effective execution timestep and step count, including timestep/duration overrides. It starts at zero for a fresh run; a resumed runtime trajectory starts at its absolute continuation step. Time-reduced outputs such as class scores do not have a time axis, even though data.time_ms still describes the run. Training converts its final-update outputs and diagnostics, with time referring to that update’s input presentation.

Import ExecutionResult and NumpyExecutionResult from snnlab.sim.execution if needed for type annotations.

Shapes and gradientsCopy Anchor Link

Shapes follow the declared graph signal, rather than one universal result layout. A population trace typically has (time, batch, cells) axes; time-reduced class scores have (batch, classes) axes. Keys in outputs are names from net.output; keys in diagnostics are names from net.expose.

Declared outputs always return, and direct graph forward outputs retain autograd. Diagnostics and continuation state are detached; diagnostics=False returns an empty diagnostic mapping. The built-in training result carries the last optimizer update’s outputs, not an aggregate of all training presentations. Use metrics for epoch curves.

For a differentiable PyTorch loss use result.outputs tensors directly. Use .numpy() only for plotting or analysis. It converts outputs and diagnostics, not parameters, optimizer state or metrics.

Constructor defaultsCopy Anchor Link

class ExecutionResult:
    executor: ExecutorName
    outputs: dict[str, torch.Tensor] = field(default_factory=dict)
    diagnostics: dict[str, torch.Tensor] = field(default_factory=dict)
    parameters: dict[str, torch.Tensor] = field(default_factory=dict)
    gradients: dict[str, torch.Tensor] = field(default_factory=dict)
    optimizer_state: dict[str, Any] = field(default_factory=dict)
    training_checkpoint: TrainingCheckpoint | None = None
    selected_checkpoint: TrainingCheckpoint | None = None
    final_state: dict[str, torch.Tensor] = field(default_factory=dict)
    runtime_state: GraphRuntimeState | None = None
    metrics: dict[str, Any] = field(default_factory=dict)
    model: nn.Module | None = None

class NumpyExecutionResult:
    outputs: dict[str, np.ndarray]
    diagnostics: dict[str, np.ndarray]
    time_ms: np.ndarray | None