Malatium

Volatility portfolio backtesting and optimization in dollar vega, built on Polars and CVXPY. Sibling of atium with vega in place of capital.

Malatium is data-agnostic. It takes frames in through providers and never reads a store: the reference-return panel it prices a book off, the risk model tables and the scores or alphas all come from the caller (in the Atium stack, from ml-data-pipelines through ml-data-access).

Installation

pip install malatium

Units

Every position is a number of units of a reference instrument per name (in the Atium stack, one delta-hedged ATM straddle rolled on a fixed rule). A unit is marked by its dollar vega, the dollars of P&L per one-point move in implied vol. The return of a unit is its daily P&L divided by its dollar vega at inception, pnl_per_vega. Strategy weights are fractions of a gross vega budget; the backtester turns a weight into units by multiplying by the budget and dividing by the unit's dollar vega at today's close.

Quick start

import datetime as dt

from malatium.backtester import Backtester
from malatium.optimizer import MVO, GrossCap, MaxUtility, NetVegaNeutral, TurnoverPenalty
from malatium.providers import PanelProvider, TradingCalendar
from malatium.results import BacktestResults
from malatium.risk_model import FactorRiskModelConstructor
from malatium.strategy import OptimizationStrategy, QuantileSpreadStrategy

# Frames in the schemas of `malatium.schemas`, loaded however you like.
calendar = TradingCalendar(sessions)
reference = PanelProvider(reference_returns_df)

# A rank book: long the cheapest decile of scores, short the richest.
rank_book = QuantileSpreadStrategy(
    PanelProvider(scores_df), universe=PanelProvider(universe_df), quantile=0.1
)

# A mean-variance book: alphas against a factor risk model.
risk_model = FactorRiskModelConstructor(
    PanelProvider(factor_loadings_df),
    PanelProvider(factor_covariances_df),
    PanelProvider(idio_vol_df),
)
optimizer = MVO(
    objectives=[MaxUtility(risk_aversion=0.2), TurnoverPenalty(cost=0.1)],
    constraints=[NetVegaNeutral(0.025), GrossCap(1.0)],
)
mvo_book = OptimizationStrategy(PanelProvider(alphas_df), risk_model, optimizer)

records_df = Backtester().run(
    calendar,
    reference,
    mvo_book,
    start=dt.date(2018, 7, 2),
    end=dt.date(2025, 6, 30),
    gross_vega=20_000.0,
    rebalance_frequency="weekly",
)
results = BacktestResults(records_df)
results.summary()
results.factor_regression(factor_returns_df)
BacktestResults.decile_table(scores_df, reference_returns_df, horizon_days=60)

What is here

Reference returns

ReferenceReturnsSchema is the contract between the data and the engine. Per (date, symbol):

Between rebalances the backtester holds a constant number of units, so its P&L is units × entry_vega × pnl_per_vega and its cost |units| × entry_vega × cost_per_vega; a rebalance trades |Δunits| × half-spread. Costs are charged at cost_fraction of those amounts, zero by default.

A strategy never sees the close it trades at. On a rebalance session the backtester asks for weights as of the previous session and executes them at today's close, and the decile table's forward window starts after that executable close. The lag is structural and has no switch: a score built from the same quotes as the marks would otherwise collect bid-ask bounce that no trader can.

Development

uv sync --all-extras
uv run pytest
uv run ruff check . && uv run ruff format .