Installation & Setup#

Source Files

pyproject.toml

Quick Install#

# Core (tree models + lets-plot + great-tables)
pip install twiga

# + Matplotlib, Plotly, SciencePlots
pip install "twiga[plots]"

# + Neural networks (PyTorch Lightning)
pip install "twiga[nn]"

# Everything
pip install "twiga[all]"

Batteries included — XGBoost, LightGBM, CatBoost, NGBoost, lets-plot and Great Tables ship with the base install.

Extra	What it adds
`plots`	Matplotlib, Plotly, SciencePlots (publication-quality & interactive charts)
`nn`	PyTorch, Lightning, TorchMetrics, TensorBoard
`explain`	SHAP feature attribution
`mlops`	MLflow, FastAPI, Evidently, Prefect
`all`	Everything above

GPU (CUDA) Support for Neural Networks#

The default twiga[nn] install pulls the CPU-only PyTorch wheel from PyPI. To use a GPU, point your installer at the PyTorch CUDA index instead:

# pip
pip install "twiga[nn]" --extra-index-url https://download.pytorch.org/whl/cu124

# uv  (--index-strategy required so uv falls back to PyPI for non-torch packages)
uv pip install "twiga[nn]" \
  --extra-index-url https://download.pytorch.org/whl/cu124 \
  --index-strategy unsafe-best-match

Replace cu124 with the suffix that matches your driver — run nvidia-smi to check:

CUDA version	Suffix
11.8	`cu118`
12.1	`cu121`
12.4	`cu124`
12.6	`cu126`

Verify the GPU build:

import torch
print(torch.cuda.is_available())    # True
print(torch.cuda.get_device_name()) # e.g. NVIDIA A100

Development Setup#

Prerequisites#

Python 3.12 (required: >=3.12,<3.13)
uv — fast Python package manager
Git with pre-commit hook support

Installation#

# Clone the repository
git clone https://github.com/sambaiga/twiga-forecast.git
cd twiga-forecast

# Install all development dependencies (including dev tools and all extras)
uv sync --all-extras --dev

GPU Support in Dev Environment#

The default uv sync --all-extras installs the CPU-only PyTorch wheel. To replace it with a CUDA build:

# 1. Sync everything first (installs CPU torch into .venv)
uv sync --all-extras --dev

# 2. Force-reinstall torch from the CUDA index
#    --index-strategy unsafe-best-match lets uv fall back to PyPI for packages
#    like torchmetrics and numpy whose CUDA-index builds are outdated.
uv pip install --reinstall torch \
  --index-url https://download.pytorch.org/whl/cu124 \
  --index-strategy unsafe-best-match

Note

uv sync will revert torch to the CPU wheel from uv.lock. Re-run step 2 after any uv sync.

Core Dependencies#

The base install (pip install twiga) includes:

Package	Version	Purpose
`pydantic`	>=2.10.6	Configuration validation
`numpy`	>=2.0.0	Numerical computation
`pandas`	>=2.2.3	Data manipulation
`scikit-learn`	>=1.8.0	Base transformers and utilities
`optuna`	>=4.7.0	Hyperparameter optimization
`statsmodels`	>=0.14.0	Statistical modeling
`astral`	>=3.2	Sunrise/sunset calculations
`rich`	>=13.0.0	Terminal formatting
`tqdm`	>=4.66.4	Progress bars
`xgboost`	>=3.1.3	Gradient boosted trees
`lightgbm`	>=4.6.0	Gradient boosted trees
`catboost`	>=1.2.8	Gradient boosted trees
`ngboost`	>=0.5.9	Probabilistic boosting
`lets-plot`	>=4.9.0	Primary interactive plots
`great-tables`	>=0.21.0	Result tables

System Requirements#

Python: 3.12 or 3.13 (required — >=3.12)
OS: Linux, macOS, Windows
GPU: Optional — for neural network models and tree model GPU modes

Verification#

import twiga
from twiga.forecaster.core import TwigaForecaster
from twiga.core.config import DataPipelineConfig, ForecasterConfig

print("Twiga installed successfully!")

To verify GPU availability for neural models:

import torch
print(f"CUDA available: {torch.cuda.is_available()}")
print(f"Device: {torch.cuda.get_device_name(0) if torch.cuda.is_available() else 'CPU'}")

Next: Key Concepts | Quick Start Guide