Training and Evaluation#

Generate labeled time-varying AR data, train DeepLagField, and evaluate coefficients, predictions, and order selection. All order labels are AR orders rather than zero-based category indices.

Synthetic Datasets#

class neuralfieldmanifold.training.TVARDataset(signals: ndarray, coefficients: ndarray, orders: ndarray, family_indices: ndarray, family_names: tuple[str, ...], seeds: ndarray, noise_std: ndarray)[source]#

Synthetic signals, coefficient paths, AR orders, and generation labels.

Signals have shape (sample, time), coefficients have shape (sample, time, coefficient_width), and per-sample labels have shape (sample,). Coefficients beyond the AR order are zero-padded.

save(path)[source]#

Save numeric arrays and Unicode labels; no pickled Python objects.

neuralfieldmanifold.training.make_tvar_dataset(*, n_per_family=10, n_samples=600, families=None, orders=(2, 3, 4, 5, 6), coefficient_width=None, noise_range=(0.2, 0.5), seed=123, target_power=0.5, power_window_samples=40, workers=1, max_retries=10000)[source]#

Generate synthetic data balanced by coefficient family and AR order.

A fixed seed is assigned to each generation task, keeping the dataset reproducible for a fixed seed across worker counts.

neuralfieldmanifold.training.split_dataset(dataset, *, train_fraction=0.8, seed=42)[source]#

Split a TVAR dataset into training and validation sets, stratified by AR order.

Requires scikit-learn, available in the tutorials extra.

Loss Functions#

class neuralfieldmanifold.training.LossWeights(reconstruction: float = 1.0, order_classification: float = 10.0, energy: float = 0.1, smoothness: float = 0.05, order_penalty: float = 0.0)[source]#

Nonnegative weights for the five components returned by compute_losses.

neuralfieldmanifold.training.compute_losses(output, signal, *, orders, true_order=None, weights=None, target_power=0.5, energy_window_samples=40)[source]#

Compute loss components and their weighted sum.

Reconstruction is prediction MSE after the maximum-order lag context. Order classification is cross-entropy against the supplied AR orders. Energy penalizes rolling mean-square prediction power relative to target_power, after skipping the first energy_window_samples samples. Smoothness penalizes squared successive differences of coefficients, summed over lags and averaged over batch and time. The optional order penalty is the expected index of the candidate order.

Parameters:

  • output (DynamicsOutput) – Model coefficients, order logits, and signal prediction.

  • signal (torch.Tensor, shape (batch, time)) – Target sequences.

  • orders (sequence of int) – Candidate AR orders corresponding to the logit columns.

  • true_order (torch.Tensor, shape (batch,), or None) – AR order for each sequence. Required when order classification has nonzero weight.

  • weights (LossWeights or None) – Nonnegative loss weights. None uses LossWeights defaults.

  • target_power (float) – Target mean-square prediction amplitude.

  • energy_window_samples (int) – Rolling window length for the energy term.

Returns:

Scalar reconstruction, order_classification, energy, smoothness, order_penalty, and total losses.

Return type:

dict of str to torch.Tensor

Training#

class neuralfieldmanifold.training.TrainingConfig(epochs: int = 100, learning_rate: float = 0.001, weights: ~neuralfieldmanifold.training.losses.LossWeights = <factory>, target_power: float = 0.5, energy_window_samples: int = 40, temperature: float = 1.0, stochastic_validation: bool = False, gradient_clip: float = 1.0)[source]#

Epoch count, Adam learning rate, loss weights, and regularization settings.

Energy settings control the target prediction power and rolling window. Temperature controls Gumbel order sampling. Validation uses argmax unless stochastic_validation is True. Gradient clipping bounds the parameter gradient norm before each optimizer step.

neuralfieldmanifold.training.train(model, train_loader, *, validation_loader=None, config=None, device='cpu', callback=None)[source]#

Train DeepLagField and return per-epoch losses and order accuracy.

Parameters:

  • model (DeepLagField) – Model to train.

  • train_loader (iterable) – Batches of (signal, order), with signals shaped (batch, time) and one AR order per signal.

  • validation_loader (iterable or None) – Optional validation batches with the same structure.

  • config (TrainingConfig or None) – Optimization and loss settings. None uses TrainingConfig defaults.

  • device (str or torch.device) – Device used for model parameters and batches.

  • callback (callable or None) – Called with the metrics dictionary at the end of each epoch.

Returns:

Epoch records containing train and optional validation losses, order accuracy, and within-one-order accuracy.

Return type:

list of dict

Notes

Uses Adam, gradient clipping, and ReduceLROnPlateau. Loss records are averages of batch losses. Validation uses deterministic order selection unless config.stochastic_validation is True.

Evaluation#

neuralfieldmanifold.training.evaluate(model, signals, *, true_coefficients=None, true_orders=None, batch_size=32, device='cpu', sample_order=False)[source]#

Evaluate DeepLagField predictions and optional ground-truth targets.

Prediction MSE excludes the leading maximum-order lag context. Coefficient MSE includes all time positions and lag coefficients. When true_orders are supplied, returns exact and within-one order accuracy, mean absolute order error, and mean relative order error.

Inputs have shape (batch, sequence_length). Returned predictions, coefficients, and selected orders are NumPy arrays. Order selection is deterministic unless sample_order=True.