q-timesfm 0.1.0

Tools for testing quantum and classical adapter heads in time-series forecasting experiments

Q-TimesFM

Q-TimesFM is a small research package for testing hybrid quantum-classical adapter heads on top of frozen time-series forecasting backbones.

The current code focuses on practical experiments: loading a CSV, building sliding windows, training a lightweight adapter head, and comparing it with a matched classical bottleneck. It is not a replacement for TimesFM, and it does not make any claim of quantum advantage.

Status

This is an alpha research prototype. APIs may change while the experiments are being tightened up.

Installation

After the package is published:

pip install q-timesfm

For local development:

pip install -e ".[dev,lightning,yaml]"

The lightning extra installs PennyLane Lightning support. GPU execution still depends on a compatible NVIDIA driver, CUDA, and cuQuantum stack.

Draw the Quantum Circuit

q-timesfm-draw-circuit \
  --n-qubits 6 \
  --quantum-depth 2 \
  --output circuit.png

Use --pennylane-device lightning.qubit when PennyLane Lightning is available.

Train on a CSV File

Single-series example:

q-timesfm-train \
  --data-source generic_csv \
  --csv-path your.csv \
  --target-col value \
  --time-col date \
  --context 32 \
  --horizon 8 \
  --head-type classical_bottleneck \
  --epochs 1 \
  --batch-size 8 \
  --backend torch

Grouped time series are supported with --group-col. Windows are built within each group and never cross group boundaries:

q-timesfm-train \
  --data-source generic_csv \
  --csv-path your.csv \
  --target-col value \
  --time-col date \
  --group-col series_id \
  --context 32 \
  --horizon 8 \
  --head-type quantum \
  --backend pennylane \
  --pennylane-device lightning.qubit

CSV Format

Minimum single-series format:

date,value
2020-01-01,1.0
2020-01-02,1.2

Grouped format:

series_id,date,value
A,2020-01-01,1.0
A,2020-01-02,1.2
B,2020-01-01,5.0

TimesFM Checkpoints

Pretrained TimesFM checkpoints are not bundled with this package. If you use the TimesFM adapter wrapper, point the code to a local checkpoint and make sure the upstream TimesFM package or source tree is available in your environment.

Python API

from q_timesfm import make_generic_dataset, train_adapter

X, y, meta, info = make_generic_dataset(
    "your.csv",
    target_col="value",
    time_col="date",
    context=32,
    horizon=8,
)

result = train_adapter(
    data_source="generic_csv",
    csv_path="your.csv",
    target_col="value",
    time_col="date",
    head_type="classical_bottleneck",
    context=32,
    horizon=8,
    epochs=1,
    backend="torch",
)

Notes

• The package is intended for controlled experiments, not production forecasts.
• Quantum results should be compared against matched classical baselines.
• Report negative results; they are useful for this line of work.
• Do not interpret early runs as evidence of quantum advantage.