neitpm/hybridtrinet-oil-forecasting

HybridTriNet: Multi-Horizon Oil Price Forecasting

This repository hosts official checkpoints, architecture definitions, and isolated preprocessing metadata for HybridTriNet, a tri-branch deep neural network designed for multi-horizon oil and refined product price forecasting.

Disclaimer: The checkpoints and model architecture are released strictly for research, benchmark evaluation, and educational reproducibility purposes. Raw dataset redistribution is not included.

---

1. Architecture Overview

HybridTriNet fuses three complementary representation learning branches via a Dynamic Gated Fusion network:

1. KAN Branch (Kolmogorov-Arnold Network): Captures complex non-linear feature interactions using learnable Radial Basis Function expansions ($M=8$, depth=2).
2. GRU Branch: Models sequential temporal dependencies and autoregressive momentum (hidden dimension=128).
3. Patch Transformer Branch: Captures long-range multi-scale attention patterns across segmented temporal patches (patch length=16, stride=8, $d_{model}=64$, 4 heads, 2 encoder layers).

Predictions are generated simultaneously across multiple forecasting horizons ($H \in {1, 5, 10, 15, 20, 30, 60}$ steps) with input lookback window $K = 64$ trading steps.

---

2. Input/Output Inference Contract

To ensure valid forecasting without schema mismatch, inputs must conform strictly to the following contract:

• Lookback Window ($K$): Exactly 64 consecutive trading steps.
• Input Dimension ($D_{in} = 15$): The input tensor consists of 15 authentic market, calendar, and risk features (synthetic temporal indices such as index counters are deliberately omitted to avoid temporal trend shortcut learning):
  1. BRT DTD (Brent Dated Benchmark)
  2. BRT KH (Brent Futures/Forward)
  3. WTI (West Texas Intermediate Benchmark)
  4. NgayTrongTuan (Day of week: 0–6)
  5. ThangTrongNam (Month of year: 1–12)
  6. QuyTrongNam (Quarter: 1–4)
  7. Nam (Year)
  8. NgayLe (Public holiday indicator: 0 or 1)
  9. SuKienDacBiet (Special geopolitical/economic event indicator)
  10. USD_Index (US Dollar Index)
  11. GPRD (Geopolitical Risk Daily Index)
  12. MG95 (Mogas 95 Refined Gasoline Price)
  13. MG92 (Mogas 92 Refined Gasoline Price)
  14. DO 0.001% (Diesel Oil 0.001% Price)
  15. DO 0.05% (Diesel Oil 0.05% Price)
• Target Columns ($D_{out} = 4$):
  • MG95 (Index 11)
  • MG92 (Index 12)
  • DO 0.001% (Index 13)
  • DO 0.05% (Index 14)
• Lagged Target Semantics: Target columns are provided strictly as historical lagged inputs within the 64-step lookback window; future target values are never used as input.
• Output Scale: Predictions are output in the original target units defined by the dataset metadata following automated inverse standardization (out_real = out_norm * y_sd + y_mu).

---

3. Holdout Evaluation Benchmark

Models were trained and evaluated chronologically on out-of-sample holdout test windows (Test Period: 2023-09-11 to 2026-05-25).

Benchmark Evaluation Note: The reported metrics reflect out-of-sample holdout performance during benchmark training on chronological slices (Test Period: 2023-09-11 to 2026-05-25). The cleaned 15-feature retraining removes the synthetic temporal index and preserves competitive holdout performance across all seven forecast horizons without systematic degradation. Software verification scripts (verify_bundle.py) test model bundle integrity, determinism, and software pipeline correctness, and are separate from future empirical forecasting accuracy evaluations.

Model	Horizon ($H$)	MAE	MAPE (%)	RMSE	Windows Evaluated
HybridTriNet	1-step	8.12	6.76%	19.15	699
HybridTriNet	5-step	9.58	8.40%	18.09	695
HybridTriNet	10-step	9.26	7.82%	20.19	690
HybridTriNet	15-step	10.27	8.85%	21.48	685
HybridTriNet	20-step	9.86	8.46%	21.11	680
HybridTriNet	30-step	10.58	9.23%	22.22	670
HybridTriNet	60-step	10.89	9.95%	21.49	640

Complete metric tables and comparison baselines are available in metrics/holdout_metrics.csv and metrics/training_history.json. Checkpoints and metrics from legacy runs containing synthetic temporal indices are archived separately as experimental artifacts.

---

4. Repository Structure

hybridtrinet-oil-forecasting/
├── README.md
├── LICENSE
├── checksums.sha256
├── inference/
│   ├── model_architecture.py     # Standalone PyTorch architecture
│   ├── run_inference.py          # Runnable inference pipeline with denormalization
│   └── verify_bundle.py          # Deep verification suite (integrity, determinism, shapes)
├── models/
│   ├── h1/                       # Horizon 1 model + metadata
│   ├── h5/                       # Horizon 5 model + metadata
│   ├── h10/                      # Horizon 10 model + metadata
│   ├── h15/                      # Horizon 15 model + metadata
│   ├── h20/                      # Horizon 20 model + metadata
│   ├── h30/                      # Horizon 30 model + metadata
│   └── h60/                      # Horizon 60 model + metadata
└── metrics/
    ├── holdout_metrics.csv       # Multi-horizon evaluation benchmark
    └── training_history.json     # Epoch-level training logs

Each horizon folder (models/h<H>/) is strictly self-contained and binds:

• model.pt: Checkpoint weights.
• model_config.json: Model hyperparameters ($K, H, D_{in}, D_{out}$, layers, attention heads).
• feature_cols.json: Input feature ordering and target indices.
• x_mu.npy, x_sd.npy: Input standardization parameters.
• y_mu.npy, y_sd.npy: Target inverse standardization parameters.

---

5. Quickstart & Inference

import numpy as np
from inference.run_inference import load_forecasting_pipeline, forecast

# 1. Load pipeline for 60-step horizon
bundle = load_forecasting_pipeline("models/h60", device="cpu")

# 2. Input shape: (Batch, K=64, D_in=15) in raw feature scale
sample_raw_input = np.random.normal(loc=bundle["x_mu"], scale=bundle["x_sd"], size=(1, 64, 15))

# 3. Run inference (standardization -> forward pass -> inverse standardization)
forecast_real = forecast(bundle, sample_raw_input)
print("Forecast shape (B, H=60, D_out=4):", forecast_real.shape)
print("Products:", bundle["target_cols"])

Or run directly via command line:

python inference/run_inference.py --model_dir models/h60

To run deep integrity and determinism verification:

python inference/verify_bundle.py --bundle_dir .