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 exe -K cuda=true torchlean lstm_regression --cuda --steps 1 --windows 1
lake exe -K cuda=true torchlean lstm_regression --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.defaultLogJson : 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.defaultDataDir : System.FilePath

Default root for downloaded real datasets. Override with --data-dir.

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

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

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

Short prefix used by the runnable recurrent example.

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

One scalar feature. If you add calendar/weather features, increase this and update scalarRow.

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

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

def NN.Examples.Models.Supervised.LstmRegression.cfg : TorchLean.nn.models.SeqRnnHeadConfig

Shared recurrent-model configuration.

The model constructor, input shape, and output shape all read from seqLen, inputSize, and hiddenSize. If a shape error appears, start here.

@[reducible, inline]

abbrev NN.Examples.Models.Supervised.LstmRegression.σ : Shape

Input shape: one scalar observation at each of seqLen timesteps.

@[reducible, inline]

abbrev NN.Examples.Models.Supervised.LstmRegression.τ : Shape

Target/prediction shape: one next-step scalar at each of seqLen timesteps.

@[reducible, inline]

abbrev NN.Examples.Models.Supervised.LstmRegression.rawσ : Shape

Raw input shape stored by the prepared household-power .npy files.

@[reducible, inline]

abbrev NN.Examples.Models.Supervised.LstmRegression.rawτ : Shape

Raw target shape stored by the prepared household-power .npy files.

def NN.Examples.Models.Supervised.LstmRegression.mkModel : TorchLean.nn.M (TorchLean.nn.Sequential σ τ)

The actual forecaster.

nn.models.lstmWithLinearHead cfg expands to:

nn.LSTM seqLen inputSize hiddenSize followed by a time-distributed nn.Linear hiddenSize inputSize.

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 (Except String ℕ)

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

def NN.Examples.Models.Supervised.LstmRegression.loadReportSamples (xPath yPath : System.FilePath) (windows : ℕ) : IO (Except String (Array (TorchLean.SupervisedSample Float rawσ rawτ)))

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

def NN.Examples.Models.Supervised.LstmRegression.takePrefix (t : TorchLean.Tensor.T Float rawσ) : TorchLean.Tensor.T Float σ

Keep the first seqLen rows of a prepared rawSeqLen × 1 tensor.

def NN.Examples.Models.Supervised.LstmRegression.prefixSample (sample : TorchLean.SupervisedSample Float rawσ rawτ) : TorchLean.SupervisedSample Float σ τ

Convert one real 24-hour prepared window into the tiny recurrent training sample.

def NN.Examples.Models.Supervised.LstmRegression.readSeriesAt (t : TorchLean.Tensor.T Float τ) (i : ℕ) : Float

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

The row is clamped so the reporting loop remains valid if seqLen is changed without also updating the number of displayed rows.

def NN.Examples.Models.Supervised.LstmRegression.targetSummary (sample : TorchLean.SupervisedSample Float σ τ) : String

Render the first few target values for one forecast window.

def NN.Examples.Models.Supervised.LstmRegression.probeOfSample (sample : TorchLean.SupervisedSample Float σ τ) (idx : ℕ) : TorchLean.Trainer.Probe σ

Public trainer probe for a deterministic forecast window.

def NN.Examples.Models.Supervised.LstmRegression.trainForecast (opts : TorchLean.Options) (train : RealData.HouseholdPowerModelTrainFlags) : IO (TorchLean.Trainer.TrainResult σ τ)

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

Executable entrypoint for CPU/CUDA Float training.