LSTNet on ECL

End-to-end pipeline: download the UCI Electricity Load Diagrams (ECL) dataset, preprocess it, run EDA, train LSTNet, and benchmark it against a plain LSTM baseline at four forecast horizons (3 / 6 / 12 / 24 hours).

See design.md for the full design writeup.

Setup

python -m venv .venv
.venv\Scripts\activate      # Windows
pip install -r requirements.txt

GPU (CUDA 12.1) build — install torch separately first:

pip install torch --index-url https://download.pytorch.org/whl/cu121
pip install -r requirements.txt

Usage

python download_data.py          # fetch data/raw/electricity.txt (321 clients, hourly)
python main.py                   # preprocess + train LSTNet & LSTM baseline for all horizons + eval
python main.py --skip-preprocess # reuse data_processed/ from a previous run
python main.py --eval-only       # only run eval.py against existing checkpoints
jupyter notebook eda.ipynb       # exploratory data analysis

Results (RSE / CORR / MAE per horizon, per model) are printed and saved to results.csv.

Configuration

All pipeline settings (architecture, optimization, horizons, paths, Optuna search settings) live in config.yaml. Every entrypoint accepts --config to point at a different file:

python main.py --config config.yaml

Hyperparameter search (Optuna)

tune.py runs an Optuna study over LSTNet's architecture and optimization hyperparameters for one horizon at a time (val L1 loss, with pruning). It needs data_processed/ for that horizon already built (python main.py --skip-preprocess --eval-only won't do it — run python -c "import preprocess; preprocess.run()" or a full python main.py first).

python tune.py                          # searches config.yaml's optuna.search_horizon
python tune.py --horizon 12 --n-trials 50
python tune.py --write-best              # persist best params into config.yaml
python main.py --skip-preprocess         # retrain using the tuned overrides

--write-best adds a best_hparams: {<horizon>: {...}} section to config.yaml; train.py picks up any entry there and overrides the defaults for that horizon's LSTNet run (the LSTM baseline is not tuned — it exists purely as a fixed reference point).

Layout

config.yaml            all pipeline settings (see config.py)
data/raw/               LD2011_2014-derived electricity.txt (gitignored)
data_processed/         preprocess.py output: X/y .npy files + scaler.pkl (gitignored)
model/lstnet.py         LSTNet: CNN + GRU + Skip-GRU + AR
model/lstm_baseline.py  two-layer LSTM baseline
train.py                training loop for both models
tune.py                 Optuna hyperparameter search (LSTNet only)
eval.py                 RSE / CORR / MAE evaluation
checkpoints/            best model weights per (model, horizon) (gitignored)