Phi-Mamba: Adaptive Delay and Retrieval-Augmented State Space Models for Edge Time-Series Forecasting

Release version: v1.0 — This tag corresponds to the reference metrics and tables bundled under paper/tables/source/ and the minimal sample figures in artifacts/paper/.

---

Overview

Phi-Mamba is a research codebase for edge-oriented multivariate time-series forecasting. It implements a Phi-Mamba forecaster (adaptive delay, retrieval-augmented memory, gated fusion, Mamba-style backbone) alongside LSTM, Transformer, and Mamba baselines. The Python package name is phimamba (import path); the method and paper use the hyphenated name Phi-Mamba.

Naming: Use Phi-Mamba in prose and citations; use phimamba / PhiMamba in code and class names.

---

Key contributions

• Adaptive delay modeling — learnable temporal filtering before the sequence backbone.
• Retrieval-augmented temporal memory — attention-style readout over a bounded memory of past patterns.
• Efficient edge deployment — configs and scripts for latency/memory benchmarks on CPU-oriented setups.

---

Results summary (reference snapshot, v1.0)

Numbers below come from the bundled tables in paper/tables/source/final_results.csv (regenerate anytime with scripts/generate_paper_figures.py).

Model	Test MSE	Avg latency (ms)
Transformer (best MSE here)	0.703	15.0
Mamba	0.805	128.8
LSTM	0.823	27.4
Phi-Mamba (Final)	1.186	146.3

• Phi-Mamba (Final) vs Mamba: MSE 1.186 vs 0.805 on this snapshot (+47.4% relative MSE vs. Mamba; lower is better).
• Latency: Phi-Mamba (Final) 146.3 ms vs Mamba 128.8 ms (+13.6% slower in this run).

Your own training may differ; see Reproducing results below.

---

Installation

python3 -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -r requirements.txt

Install PyTorch for your platform from pytorch.org if you need a specific CUDA or MPS build.

---

Quick start

From the repository root, with PYTHONPATH set by running scripts (they prepend src/ automatically).

1. Data (ETT)

Place ETTh1 (or your dataset) where the dataset config expects it. Default config: configs/dataset/ett.yaml (paths under data/raw/).

python3 scripts/download_data.py
# or copy ETTh1.csv to data/raw/ett/ per configs/dataset/ett.yaml

2. Train a baseline (example: Mamba)

python3 scripts/train.py \
  --dataset-config configs/dataset/ett.yaml \
  --model-config configs/model/mamba.yaml \
  --training-config configs/training/default.yaml \
  --device cpu

3. Train Phi-Mamba final variant only (G / gated + safe residual)

python3 scripts/train_g_safe_gated.py \
  --dataset-config configs/dataset/ett.yaml \
  --experiment-config configs/experiment/production_ablation.yaml \
  --device cpu

4. Ablation suite

python3 scripts/run_ablation.py \
  --dataset-config configs/dataset/ett.yaml \
  --experiment-config configs/experiment/ablation_phi_mamba.yaml \
  --device cpu

Train checkpoints only (no CSV/plots):

python3 scripts/run_ablation.py --train-checkpoints-only --device cpu

5. Robustness

python3 scripts/run_robustness.py \
  --dataset-config configs/dataset/ett.yaml \
  --experiment-config configs/experiment/robustness_phi_mamba.yaml \
  --lstm --transformer \
  --device cpu

6. Edge benchmark (CPU-oriented latency)

python3 scripts/run_edge_benchmark.py \
  --dataset-config configs/dataset/ett.yaml \
  --experiment-config configs/experiment/edge_benchmark.yaml

7. Paper tables and figures

python3 scripts/generate_paper_figures.py

Outputs: paper/tables/ (CSV + LaTeX + summary text), paper/figures/ (all plots), and a minimal copy under artifacts/paper/ for the public repo sample.

---

Project structure

Path	Role
src/phimamba/	Library: data, models, training, evaluation, experiments
configs/	YAML: datasets, models, training, experiments
scripts/	CLI entrypoints
tests/	Pytest tests
paper/	Draft materials: draft.md, paper.tex, tables/, figures/
paper/tables/source/	Bundled reference CSVs for v1.0 figures
artifacts/	Local outputs (checkpoints, plots); mostly gitignored

---

Reproducing results

1. Dataset: Use the same split and preprocessing as configs/dataset/ett.yaml (ETTh1, window length / horizon as specified).
2. Configs: Training hyperparameters live under configs/training/ and configs/experiment/*.yaml. Production-style ablation: configs/experiment/production_ablation.yaml.
3. Order of operations (typical):
   • Download or place raw data.
   • Run scripts/train.py (or variants) to populate artifacts/checkpoints/.
   • Run scripts/run_final_summary.py, scripts/run_ablation.py, scripts/run_robustness.py, scripts/run_edge_benchmark.py as needed (many modes expect existing checkpoints — see each script’s --help).
4. Expected outputs: Metrics CSVs under artifacts/results/, plots under artifacts/plots/, checkpoints under artifacts/checkpoints/.
5. Paper bundle: Run python3 scripts/generate_paper_figures.py to refresh paper/tables/ and paper/figures/ from paper/tables/source/ (or from artifacts/results/ if source files are missing).

Delay-aware stress benchmarks (optional)

Evaluates LSTM, Transformer, Mamba, and Phi-Mamba (G) on ETT with strong regime shift, synthetic variable delay on test inputs, and a short forex-like synthetic fine-tune (see each script’s --help). Requires trained weights under artifacts/checkpoints/ (same layout as scripts/run_robustness.py).

python3 scripts/run_strong_regime_shift.py --device cpu
python3 scripts/run_synthetic_delay.py --device cpu
python3 scripts/run_forex_like.py --device cpu
python3 scripts/generate_paper_figures.py   # copies delay plots + delay_benchmark_summary.csv

---

Paper and citation

• Draft: paper/draft.md (Markdown) and paper/paper.tex (LaTeX stub).
• Citation: See CITATION.cff (GitHub reads this for the “Cite this repository” widget). Replace the placeholder DOI and repository URL when the paper and archive record are public.
• Paper PDF / venue: To appear — link will be added here: https://doi.org/10.0000/PLACEHOLDER

---

Tests

pip install pytest
pytest

pyproject.toml sets pythonpath = ["src"] so imports resolve without a manual PYTHONPATH.

---

License

MIT — see LICENSE.