LSTM Seasonal Regression / Forecasting

This is the runnable supervised sequence example: an LSTM trains on a real-valued forecasting task and works with the same CPU/CUDA runtime flags as the other model commands.

The default data path uses the UCI Individual Household Electric Power Consumption dataset: minute-level power readings from one household over almost four years. The preparation script turns that into hourly one-step forecasting windows:

past 24 hours -> next 24 shifted-by-one-hour targets

Prepare the real data once:

python3 scripts/datasets/download_example_data.py --household-power --household-power-windows 512

Recommended runs:

• use --steps 1 to check that the runtime, data loader, and CUDA path agree on shapes;
• use --steps 200 --windows 96 for a short training run with before/after forecast reports;
• change --report-offset to evaluate a different part of the power curve;
• lower --lr if the reported forecast error increases.

lake -R -K cuda=true exe torchlean lstm_regression --device cuda --steps 1 --windows 1
lake -R -K cuda=true exe torchlean lstm_regression --device cuda --steps 200 --windows 96

Dataset citation: Hebrail and Berard, "Individual Household Electric Power Consumption", UCI Machine Learning Repository, DOI 10.24432/C58K54, CC BY 4.0.

def NN.Examples.Models.Supervised.LstmRegression.exeName : String

Runner subcommand: lake exe torchlean lstm_regression ....

def NN.Examples.Models.Supervised.LstmRegression.defaultLogPath : System.FilePath

Default JSON path for the before/after loss.

Pass --log PATH to write somewhere else, or --log disabled when you only want terminal output.

def NN.Examples.Models.Supervised.LstmRegression.sequenceLength : ℕ

Prepared household-power windows contain one day of hourly samples.

def NN.Examples.Models.Supervised.LstmRegression.featureCount : ℕ

One scalar feature. Increase this when the prepared sequence data gains more features.

def NN.Examples.Models.Supervised.LstmRegression.hiddenWidth : ℕ

Hidden width for the recurrent state used by this runnable example.

def NN.Examples.Models.Supervised.LstmRegression.outputWidth : ℕ

One scalar power-consumption prediction at each timestep.

@[reducible, inline]

abbrev NN.Examples.Models.Supervised.LstmRegression.modelConfig : TorchLean.nn.models.Recurrent.Config

Shared recurrent-model configuration.

The model constructor, input shape, and output shape all read from this value. The single output feature is the next power-consumption prediction at each time step.

@[reducible, inline]

abbrev NN.Examples.Models.Supervised.LstmRegression.input : Spec.Shape

Input shape: one scalar observation at each timestep.

@[reducible, inline]

abbrev NN.Examples.Models.Supervised.LstmRegression.output : Spec.Shape

Target/prediction shape: one next-step scalar at each timestep.

def NN.Examples.Models.Supervised.LstmRegression.model : TorchLean.nn.Builder (TorchLean.nn.Sequential input output)

The actual forecaster.

nn.models.lstm modelConfig expands to:

nn.lstm sequenceLength featureCount hiddenWidth followed by a time-distributed nn.linear hiddenWidth outputWidth.

So every timestep emits a scalar forecast. We are not using only the final hidden state here; the loss checks the whole output sequence.

def NN.Examples.Models.Supervised.LstmRegression.dataTags (xPath yPath : System.FilePath) : Array String

Data source tags for terminal logs and JSON metadata.

def NN.Examples.Models.Supervised.LstmRegression.availableWindows (xPath : System.FilePath) : IO ℕ

Validate the prepared input file and return its available window count.

def NN.Examples.Models.Supervised.LstmRegression.loadReportSamples (xPath yPath : System.FilePath) (windows : ℕ) : IO (Array (TorchLean.Sample.Supervised Float input output))

Load the Float version once for reporting probes and short training.

def NN.Examples.Models.Supervised.LstmRegression.readSeriesAt (t : TorchLean.Tensor Float output) (row : Fin sequenceLength) : Float

Read t[row,0] from a forecast tensor.

def NN.Examples.Models.Supervised.LstmRegression.targetSummary (sample : TorchLean.Sample.Supervised Float input output) : String

Render the first few target values for one forecast window.

def NN.Examples.Models.Supervised.LstmRegression.probeOfSample (sample : TorchLean.Sample.Supervised Float input output) (index : ℕ) : TorchLean.Trainer.Probe input

Public trainer probe for a deterministic forecast window.

def NN.Examples.Models.Supervised.LstmRegression.trainForecast (runtime : TorchLean.Runtime.Config) (flags : RealData.HouseholdPowerModelTrainFlags) : IO (TorchLean.Trainer.Result input output)

def NN.Examples.Models.Supervised.LstmRegression.main (args : List String) : IO UInt32

Executable entrypoint for CPU/CUDA Float training.