vtl.nn.models

Sequential[T] composes layers and a loss around an autograd context. Its builder methods cover inputs, dense/convolutional layers, pooling, activations, normalization, embeddings, recurrent and attention layers, and loss selection. The architecture is an ordered list: each builder adds a layer whose output feeds the next layer. The context is supplied when constructing the model.

gru(input_size, hidden_size) adds a single-layer CPU GRU. It uses a zero initial hidden state and expects [sequence, batch, features] input. Its output keeps the sequence and batch dimensions and replaces the feature dimension with hidden_size.

import vtl.autograd
import vtl.nn.models

ctx := autograd.ctx[f32]()
mut model := models.sequential_from_ctx[f32](ctx)
model.input([4])
model.linear(8)
model.relu()
model.linear(2)
model.mse_loss()

Use forward for inference and the model's loss/backpropagation methods for training; consult sequential.v for exact method signatures.

save(path) writes model weights. save_checkpoint(path, epoch, loss) also stores epoch/loss metadata; load_weights(path) loads into an already-built compatible model and Sequential.load_checkpoint[T](path) reads checkpoint metadata. For resumable Adam training, build the optimizer with the model's parameters and use save_training_checkpoint(path, epoch, loss, optimizer); restore into a compatible model and a built Adam optimizer with load_training_checkpoint(path, mut optimizer). This stores Adam's scalar configuration and first/second moments alongside model weights and metadata. For SGD with momentum, use save_sgd_training_checkpoint and load_sgd_training_checkpoint; these store the scalar configuration, momentum buffers, and first-step initialization state. For AdamW, use save_adamw_training_checkpoint and load_adamw_training_checkpoint to store its scalar configuration and first/second moments. For RMSProp, use save_rmsprop_training_checkpoint and load_rmsprop_training_checkpoint; these store its scalar configuration and squared-gradient buffers. For AdaGrad, use save_adagrad_training_checkpoint and load_adagrad_training_checkpoint; these store its scalar configuration and accumulated squared gradients. For NAdam and RAdam, use the corresponding save_nadam_training_checkpoint / load_nadam_training_checkpoint and save_radam_training_checkpoint / load_radam_training_checkpoint methods; these persist the step schedule, scalar configuration, and both moments. The custom optimizer types, device remapping, and cross-version migration are not supported by this API yet. The JSON format has version 1.0, ordered layer definitions, per-layer weight maps, optimizer metadata, and checkpoint metadata; tensor weights are base64 encoded. Loading rejects a version mismatch.

import vtl.nn.models
import vtl.nn.optimizers

mut model := models.sequential[f64]()
model.input([2])
model.linear(1)
mut optimizer := optimizers.adam_optimizer[f64](learning_rate: 0.001)
optimizer.build_params(model.info.layers)
model.save_training_checkpoint('training.json', 12, 0.25, optimizer)!

mut resumed := models.sequential[f64]()
resumed.input([2])
resumed.linear(1)
mut resumed_optimizer := optimizers.adam_optimizer[f64](learning_rate: 0.001)
resumed_optimizer.build_params(resumed.info.layers)
epoch, loss := resumed.load_training_checkpoint('training.json', mut resumed_optimizer)!

Start with the neural-network tutorial.

fn sequential[T]() &Sequential[T]

sequential creates a new sequential network with a new context.

fn sequential_from_ctx[T](ctx &autograd.Context[T]) &Sequential[T]

sequential_from_ctx creates a new sequential network with the given context.

fn sequential_from_ctx_with_layers[T](ctx &autograd.Context[T], given_layers []types.Layer[T]) &Sequential[T]

sequential_from_ctx_with_layers creates a new sequential network with the given context and the given layers.

fn sequential_info[T](ctx &autograd.Context[T], layers_ []types.Layer[T]) &SequentialInfo[T]

sequential_info creates a new neural network container with an empty list of layers.

fn sequential_with_layers[T](given_layers []types.Layer[T]) &Sequential[T]

sequential_with_layers creates a new sequential network with a new context and the given layers.

fn validate_model_compatibility[T](saved_path string, model_layers []types.Layer[T]) !bool

validate_model_compatibility checks if a saved model is compatible with the given layers. Returns an error with details if incompatible.

fn Sequential.load_checkpoint[T](path string) !(int, f64)

load_checkpoint restores a Sequential model's weights and training metadata from a JSON file. Returns the epoch and loss from the checkpoint.

Note: The model must already be constructed with the same architecture. This method loads weights into an existing model.

fn (mut ls SequentialInfo[T]) input(shape []int)

input adds a new input layer to the network with the given shape.

fn (mut ls SequentialInfo[T]) linear(output_size int)

linear adds a new linear layer to the network with the given output size

fn (mut ls SequentialInfo[T]) maxpool2d(kernel []int, padding []int, stride []int)

maxpool2d adds a new maxpool2d layer to the network with the given kernel size and stride.

fn (mut ls SequentialInfo[T]) mse_loss()

mse_loss sets the loss function to the mean squared error loss.

fn (mut ls SequentialInfo[T]) sigmoid_cross_entropy_loss()

sigmoid_cross_entropy_loss sets the loss function to the sigmoid cross entropy loss.

fn (mut ls SequentialInfo[T]) softmax_cross_entropy_loss()

softmax_cross_entropy_loss sets the loss function to the softmax cross entropy loss.

fn (mut ls SequentialInfo[T]) flatten()

flatten adds a new flatten layer to the network.

fn (mut ls SequentialInfo[T]) relu()

relu adds a new relu layer to the network.

fn (mut ls SequentialInfo[T]) leaky_relu()

leaky_relu adds a new leaky_relu layer to the network.

fn (mut ls SequentialInfo[T]) elu()

elu adds a new elu layer to the network.

fn (mut ls SequentialInfo[T]) sigmoid()

sigmoid adds a new sigmoid layer to the network.

fn (mut ls SequentialInfo[T]) tanh()

tanh adds a new tanh layer to the network.

fn (mut ls SequentialInfo[T]) softmax()

softmax adds a new softmax layer to the network.

fn (mut ls SequentialInfo[T]) gelu()

gelu adds a new GELU layer to the network.

fn (mut ls SequentialInfo[T]) swish()

swish adds a new Swish layer to the network.

fn (mut ls SequentialInfo[T]) mish()

mish adds a new Mish layer to the network.

fn (mut ls SequentialInfo[T]) softplus()

softplus adds a Softplus layer to the network.

fn (mut ls SequentialInfo[T]) selu()

selu adds a SELU layer to the network.

fn (mut ls SequentialInfo[T]) hardswish()

hardswish adds a HardSwish layer to the network.

fn (mut ls SequentialInfo[T]) conv2d(in_channels int, out_channels int, kernel_size []int, config layers.Conv2DConfig)

conv2d adds a new Conv2D layer to the network.

fn (mut ls SequentialInfo[T]) batchnorm1d(num_features int, config layers.BatchNorm1DConfig)

batchnorm1d adds a new BatchNorm1D layer to the network.

fn (mut ls SequentialInfo[T]) batchnorm2d(num_features int, config layers.BatchNorm2DConfig)

batchnorm2d adds a new BatchNorm2D layer to the network.

fn (mut ls SequentialInfo[T]) batchnorm3d(num_features int, config layers.BatchNorm3DConfig)

batchnorm3d adds a new BatchNorm3D layer to the network.

fn (mut ls SequentialInfo[T]) dropout(prob f64)

dropout adds a dropout layer using the preceding layer's output shape.

fn (mut ls SequentialInfo[T]) avgpool2d(kernel []int, padding []int, stride []int)

avgpool2d adds a new AveragePool2D layer to the network.

fn (mut ls SequentialInfo[T]) global_avgpool2d()

global_avgpool2d adds a new GlobalAveragePool2D layer to the network.

fn (mut ls SequentialInfo[T]) layer_norm(normalized_shape []int, config layers.LayerNormConfig)

layer_norm adds a new LayerNorm layer to the network.

fn (mut ls SequentialInfo[T]) group_norm(num_groups int, config layers.GroupNormConfig)

group_norm adds a channel-first GroupNorm layer to the network.

fn (mut ls SequentialInfo[T]) rms_norm(normalized_shape []int, config layers.RMSNormConfig)

rms_norm adds a trailing-dimension RMSNorm layer to the network.

fn (mut ls SequentialInfo[T]) embedding(vocab_size int, embedding_dim int)

embedding adds a new Embedding layer to the network.

fn (mut ls SequentialInfo[T]) lstm(input_size int, hidden_size int, num_layers int)

lstm adds a new LSTM layer to the network.

fn (mut ls SequentialInfo[T]) gru(input_size int, hidden_size int)

gru adds a single-layer, unidirectional GRU with a zero initial state.

fn (mut ls SequentialInfo[T]) conv1d(out_channels int, kernel_size int, config layers.Conv1DConfig)

conv1d adds a Conv1D layer using the previous layer's [channels, length] shape.

fn (mut ls SequentialInfo[T]) multihead_attention(embed_dim int, num_heads int)

multihead_attention adds a new MultiHeadAttention layer to the network.

fn (mut ls SequentialInfo[T]) positional_encoding(embed_dim int, max_len int)

positional_encoding adds a new PositionalEncoding layer to the network.

fn (mut ls SequentialInfo[T]) cross_entropy_loss()

cross_entropy_loss sets the loss function to cross entropy loss.

fn (mut ls SequentialInfo[T]) bce_loss()

bce_loss sets the loss function to binary cross entropy loss.

fn (mut ls SequentialInfo[T]) huber_loss()

huber_loss sets the loss function to Huber loss.

fn (mut ls SequentialInfo[T]) l1_loss()

l1_loss sets mean absolute error as the loss function.

fn (mut ls SequentialInfo[T]) hinge_loss()

hinge_loss sets binary hinge loss as the loss function.

fn (mut ls SequentialInfo[T]) focal_loss()

focal_loss sets binary focal loss with its default configuration.

fn (mut ls SequentialInfo[T]) nll_loss()

nll_loss sets the loss function to negative log likelihood loss.

fn (mut ls SequentialInfo[T]) kl_div_loss()

kl_div_loss sets the loss function to KL divergence loss.

fn (mut nn Sequential[T]) input(shape []int)

input adds a new input layer to the network with the given shape.

fn (mut nn Sequential[T]) linear(output_size int)

linear adds a new linear layer to the network with the given output size

fn (mut nn Sequential[T]) maxpool2d(kernel []int, padding []int, stride []int)

maxpool2d adds a new maxpool2d layer to the network with the given kernel size and stride.

fn (mut nn Sequential[T]) mse_loss()

mse_loss sets the loss function to the mean squared error loss.

fn (mut nn Sequential[T]) sigmoid_cross_entropy_loss()

sigmoid_cross_entropy_loss sets the loss function to the sigmoid cross entropy loss.

fn (mut nn Sequential[T]) softmax_cross_entropy_loss()

softmax_cross_entropy_loss sets the loss function to the softmax cross entropy loss.

fn (mut nn Sequential[T]) flatten()

flatten adds a new flatten layer to the network.

fn (mut nn Sequential[T]) relu()

relu adds a new relu layer to the network.

fn (mut nn Sequential[T]) leaky_relu()

leaky_relu adds a new leaky_relu layer to the network.

fn (mut nn Sequential[T]) elu()

elu adds a new elu layer to the network.

fn (mut nn Sequential[T]) sigmoid()

sigmoid adds a new sigmoid layer to the network.

fn (mut nn Sequential[T]) tanh()

tanh adds a new tanh layer to the network.

fn (mut nn Sequential[T]) softmax()

softmax adds a new softmax layer to the network.

fn (mut nn Sequential[T]) gelu()

gelu adds a new GELU layer to the network.

fn (mut nn Sequential[T]) swish()

swish adds a new Swish layer to the network.

fn (mut nn Sequential[T]) mish()

mish adds a new Mish layer to the network.

fn (mut nn Sequential[T]) softplus()

softplus adds a Softplus activation layer to the network.

fn (mut nn Sequential[T]) selu()

selu adds a SELU activation layer to the network.

fn (mut nn Sequential[T]) hardswish()

hardswish adds a HardSwish activation layer to the network.

fn (mut nn Sequential[T]) conv2d(in_channels int, out_channels int, kernel_size []int, config layers.Conv2DConfig)

conv2d adds a new Conv2D layer to the network.

fn (mut nn Sequential[T]) batchnorm1d(num_features int, config layers.BatchNorm1DConfig)

batchnorm1d adds a new BatchNorm1D layer to the network.

fn (mut nn Sequential[T]) batchnorm2d(num_features int, config layers.BatchNorm2DConfig)

batchnorm2d adds a new BatchNorm2D layer to the network.

fn (mut nn Sequential[T]) batchnorm3d(num_features int, config layers.BatchNorm3DConfig)

batchnorm3d adds a new BatchNorm3D layer to the network.

fn (mut nn Sequential[T]) dropout(prob f64)

dropout adds a dropout layer with the given probability.

fn (mut nn Sequential[T]) avgpool2d(kernel []int, padding []int, stride []int)

avgpool2d adds a new AveragePool2D layer to the network.

fn (mut nn Sequential[T]) global_avgpool2d()

global_avgpool2d adds a new GlobalAveragePool2D layer to the network.

fn (mut nn Sequential[T]) layer_norm(normalized_shape []int, config layers.LayerNormConfig)

layer_norm adds a new LayerNorm layer to the network.

fn (mut nn Sequential[T]) group_norm(num_groups int, config layers.GroupNormConfig)

group_norm adds a channel-first GroupNorm layer to the network.

fn (mut nn Sequential[T]) rms_norm(normalized_shape []int, config layers.RMSNormConfig)

rms_norm adds a trailing-dimension RMSNorm layer to the network.

fn (mut nn Sequential[T]) embedding(vocab_size int, embedding_dim int)

embedding adds a new Embedding layer to the network.

fn (mut nn Sequential[T]) lstm(input_size int, hidden_size int, num_layers int)

lstm adds a new LSTM layer to the network.

fn (mut nn Sequential[T]) gru(input_size int, hidden_size int)

gru adds a new single-layer GRU to the network.

fn (mut nn Sequential[T]) conv1d(out_channels int, kernel_size int, config layers.Conv1DConfig)

conv1d adds a one-dimensional convolution over channel-first sequence input.

fn (mut nn Sequential[T]) multihead_attention(embed_dim int, num_heads int)

multihead_attention adds a new MultiHeadAttention layer to the network.

fn (mut nn Sequential[T]) positional_encoding(embed_dim int, max_len int)

positional_encoding adds a new PositionalEncoding layer to the network.

fn (mut nn Sequential[T]) cross_entropy_loss()

cross_entropy_loss sets the loss function to cross entropy loss.

fn (mut nn Sequential[T]) bce_loss()

bce_loss sets the loss function to binary cross entropy loss.

fn (mut nn Sequential[T]) huber_loss()

huber_loss sets the loss function to Huber loss.

fn (mut nn Sequential[T]) l1_loss()

l1_loss sets mean absolute error as the loss function.

fn (mut nn Sequential[T]) hinge_loss()

hinge_loss sets binary hinge loss as the loss function.

fn (mut nn Sequential[T]) focal_loss()

focal_loss sets binary focal loss with its default configuration.

fn (mut nn Sequential[T]) nll_loss()

nll_loss sets the loss function to negative log likelihood loss.

fn (mut nn Sequential[T]) kl_div_loss()

kl_div_loss sets the loss function to KL divergence loss.

fn (mut nn Sequential[T]) forward(train &autograd.Variable[T]) !&autograd.Variable[T]

forward exposes this operation as part of the public API.

fn (mut nn Sequential[T]) train()

train enables training behavior for mode-aware layers such as dropout and batch normalization.

fn (mut nn Sequential[T]) eval()

eval enables evaluation behavior for mode-aware layers such as dropout and batch normalization.

fn (mut nn Sequential[T]) loss(output &autograd.Variable[T], target &vtl.Tensor[T]) !&autograd.Variable[T]

loss exposes this operation as part of the public API.

fn (nn &Sequential[T]) save(path string) !

save saves a Sequential model's weights to a JSON file. Does NOT save optimizer state - use save_checkpoint for full state.

fn (nn &Sequential[T]) save_checkpoint(path string, epoch int, loss f64) !

save_checkpoint saves a Sequential model's weights and training metadata to a JSON file.

fn (nn &Sequential[T]) save_training_checkpoint(path string, epoch int, loss f64,
	optimizer &optimizers.AdamOptimizer[T]) !

save_training_checkpoint stores model weights and Adam state for training resume.

fn (nn &Sequential[T]) save_sgd_training_checkpoint(path string, epoch int, loss f64,
	optimizer &optimizers.SgdOptimizer[T]) !

save_sgd_training_checkpoint stores model weights and SGD momentum state for an exact training resume.

fn (nn &Sequential[T]) save_rmsprop_training_checkpoint(path string, epoch int, loss f64,
	optimizer &optimizers.RMSPropOptimizer[T]) !

save_rmsprop_training_checkpoint stores model weights and RMSProp state for an exact training resume.

fn (nn &Sequential[T]) save_adagrad_training_checkpoint(path string, epoch int, loss f64,
	optimizer &optimizers.AdaGradOptimizer[T]) !

save_adagrad_training_checkpoint stores model weights and AdaGrad state for an exact training resume.

fn (nn &Sequential[T]) save_nadam_training_checkpoint(path string, epoch int, loss f64,
	optimizer &optimizers.NAdamOptimizer[T]) !

save_nadam_training_checkpoint stores model weights and complete NAdam state.

fn (nn &Sequential[T]) save_radam_training_checkpoint(path string, epoch int, loss f64,
	optimizer &optimizers.RAdamOptimizer[T]) !

save_radam_training_checkpoint stores model weights and complete RAdam state.

fn (nn &Sequential[T]) save_adamw_training_checkpoint(path string, epoch int, loss f64,
	optimizer &optimizers.AdamWOptimizer[T]) !

save_adamw_training_checkpoint stores model weights and AdamW state for a resumable training checkpoint.

fn (mut nn Sequential[T]) load_training_checkpoint(path string,
	mut optimizer &optimizers.AdamOptimizer[T]) !(int, f64)

load_training_checkpoint restores model weights, training metadata, and Adam state. Build the optimizer with the destination model's parameters before calling this method.

fn (mut nn Sequential[T]) load_sgd_training_checkpoint(path string,
	mut optimizer &optimizers.SgdOptimizer[T]) !(int, f64)

load_sgd_training_checkpoint restores model weights, metadata, and SGD momentum state into an optimizer already built from the destination model.

fn (mut nn Sequential[T]) load_rmsprop_training_checkpoint(path string,
	mut optimizer &optimizers.RMSPropOptimizer[T]) !(int, f64)

load_rmsprop_training_checkpoint restores model weights, metadata, and RMSProp state into an optimizer already built from the destination model.

fn (mut nn Sequential[T]) load_adagrad_training_checkpoint(path string,
	mut optimizer &optimizers.AdaGradOptimizer[T]) !(int, f64)

load_adagrad_training_checkpoint restores model weights, metadata, and AdaGrad state into an optimizer already built from the destination model.

fn (mut nn Sequential[T]) load_nadam_training_checkpoint(path string,
	mut optimizer &optimizers.NAdamOptimizer[T]) !(int, f64)

load_nadam_training_checkpoint restores model weights, metadata, and NAdam state.

fn (mut nn Sequential[T]) load_radam_training_checkpoint(path string,
	mut optimizer &optimizers.RAdamOptimizer[T]) !(int, f64)

load_radam_training_checkpoint restores model weights, metadata, and RAdam state.

fn (mut nn Sequential[T]) load_adamw_training_checkpoint(path string,
	mut optimizer &optimizers.AdamWOptimizer[T]) !(int, f64)

load_adamw_training_checkpoint restores model weights, metadata, and AdamW state into an optimizer built from the destination model.

fn (nn &Sequential[T]) load_weights(path string) !

load_weights restores weights into an existing model. The model's layers must already be constructed in the same order as when saved.

struct ModelMetadata {
pub:
	epoch    int
	loss     f64
	saved_at string
	version  string = model_version
}

ModelMetadata stores training metadata for checkpoints.

struct Sequential[T] {
pub mut:
	info     &SequentialInfo[T] = unsafe { nil }
	training bool               = true
}

Sequential defines a public data structure for this module.

struct SequentialInfo[T] {
	ctx &autograd.Context[T] = unsafe { nil }
pub mut:
	layers        []types.Layer[T]
	layer_types   []string
	layer_configs []map[string]int
	loss          types.Loss[T]
}

SequentialInfo defines a public data structure for this module.

struct SerializationError {
	msg string
}

SerializationError represents errors during model save/load operations.

fn (e &SerializationError) msg() string

msg exposes this operation as part of the public API.