malatium 0.1.0__tar.gz

malatium-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,33 @@
+# Publishes to PyPI on a version tag (v0.1.0) through trusted publishing.
+# One-time setup on pypi.org: add a trusted publisher for this repository
+# with workflow `publish.yml` and environment `pypi`. No token is stored here.
+name: publish
+
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - run: uv build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

malatium-0.1.0/.github/workflows/test.yml

@@ -0,0 +1,16 @@
+name: test
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - run: uv sync --all-extras
+      - run: uv run ruff check .
+      - run: uv run pytest -q

malatium-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+__pycache__/
+*.py[cod]
+.venv/
+.env
+*.egg-info/
+dist/
+build/
+.pytest_cache/
+.ruff_cache/
+.DS_Store

malatium-0.1.0/PKG-INFO

@@ -0,0 +1,113 @@
+Metadata-Version: 2.5
+Name: malatium
+Version: 0.1.0
+Summary: Volatility portfolio backtesting and optimization in dollar vega, built on Polars and CVXPY.
+Project-URL: Repository, https://github.com/Atium-Research/malatium
+Requires-Python: >=3.13
+Requires-Dist: cvxpy>=1.6
+Requires-Dist: dataframely>=2.7
+Requires-Dist: numpy>=2.0
+Requires-Dist: polars>=1.30
+Provides-Extra: plot
+Requires-Dist: matplotlib>=3.9; extra == 'plot'
+Description-Content-Type: text/markdown
+
+# Malatium
+
+Volatility portfolio backtesting and optimization in dollar vega, built on [Polars](https://pola.rs/) and [CVXPY](https://www.cvxpy.org/). Sibling of [atium](https://github.com/Atium-Research/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
+
+```bash
+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
+
+```python
+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
+
+| module | holds |
+| --- | --- |
+| `schemas.py`, `types.py` | dataframely schemas for every frame in and out |
+| `data.py` | provider protocols: `get(date_)` for scores, alphas, universe, reference returns, risk model tables |
+| `providers.py` | `TradingCalendar`, `PanelProvider` over frames in memory |
+| `strategy.py` | `Strategy`, `QuantileSpreadStrategy`, `OptimizationStrategy` |
+| `optimizer/` | `MVO`; objectives `MaxUtility`, `TurnoverPenalty`; constraints `NetVegaNeutral`, `FactorNeutral`, `PerNameCap`, `GrossShortCap`, `GrossCap` |
+| `risk_model/` | `RiskModel`, `FactorRiskModel` (Sigma = B F B' + D²), `FactorRiskModelConstructor` |
+| `backtester.py` | the daily loop over the reference-return panel |
+| `results.py` | `BacktestResults`: summary, factor regression, decile table, plots (`pip install 'malatium[plot]'`) |
+
+## Reference returns
+
+`ReferenceReturnsSchema` is the contract between the data and the engine. Per `(date, symbol)`:
+
+| column | meaning |
+| --- | --- |
+| `pnl_per_vega` | the unit's P&L today per dollar of its inception vega |
+| `cost_per_vega` | rolling and hedging cost today, same scale |
+| `exit_cost_per_vega` | half-spread to close the unit today, same scale |
+| `dollar_vega` | the unit's dollar vega at today's close |
+| `entry_vega` | inception dollar vega of the unit held into today |
+| `event` | `open`, `roll`, `forced_close` or empty |
+
+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.
+
+## Development
+
+```bash
+uv sync --all-extras
+uv run pytest
+uv run ruff check . && uv run ruff format .
+```

malatium-0.1.0/README.md

@@ -0,0 +1,99 @@
+# Malatium
+
+Volatility portfolio backtesting and optimization in dollar vega, built on [Polars](https://pola.rs/) and [CVXPY](https://www.cvxpy.org/). Sibling of [atium](https://github.com/Atium-Research/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
+
+```bash
+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
+
+```python
+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
+
+| module | holds |
+| --- | --- |
+| `schemas.py`, `types.py` | dataframely schemas for every frame in and out |
+| `data.py` | provider protocols: `get(date_)` for scores, alphas, universe, reference returns, risk model tables |
+| `providers.py` | `TradingCalendar`, `PanelProvider` over frames in memory |
+| `strategy.py` | `Strategy`, `QuantileSpreadStrategy`, `OptimizationStrategy` |
+| `optimizer/` | `MVO`; objectives `MaxUtility`, `TurnoverPenalty`; constraints `NetVegaNeutral`, `FactorNeutral`, `PerNameCap`, `GrossShortCap`, `GrossCap` |
+| `risk_model/` | `RiskModel`, `FactorRiskModel` (Sigma = B F B' + D²), `FactorRiskModelConstructor` |
+| `backtester.py` | the daily loop over the reference-return panel |
+| `results.py` | `BacktestResults`: summary, factor regression, decile table, plots (`pip install 'malatium[plot]'`) |
+
+## Reference returns
+
+`ReferenceReturnsSchema` is the contract between the data and the engine. Per `(date, symbol)`:
+
+| column | meaning |
+| --- | --- |
+| `pnl_per_vega` | the unit's P&L today per dollar of its inception vega |
+| `cost_per_vega` | rolling and hedging cost today, same scale |
+| `exit_cost_per_vega` | half-spread to close the unit today, same scale |
+| `dollar_vega` | the unit's dollar vega at today's close |
+| `entry_vega` | inception dollar vega of the unit held into today |
+| `event` | `open`, `roll`, `forced_close` or empty |
+
+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.
+
+## Development
+
+```bash
+uv sync --all-extras
+uv run pytest
+uv run ruff check . && uv run ruff format .
+```

malatium-0.1.0/pyproject.toml

@@ -0,0 +1,41 @@
+[project]
+name = "malatium"
+version = "0.1.0"
+description = "Volatility portfolio backtesting and optimization in dollar vega, built on Polars and CVXPY."
+readme = "README.md"
+requires-python = ">=3.13"
+dependencies = [
+    "cvxpy>=1.6",
+    "dataframely>=2.7",
+    "numpy>=2.0",
+    "polars>=1.30",
+]
+
+[project.optional-dependencies]
+plot = ["matplotlib>=3.9"]
+
+[project.urls]
+Repository = "https://github.com/Atium-Research/malatium"
+
+[dependency-groups]
+dev = [
+    "pytest>=8",
+    "ruff>=0.6",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/malatium"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py313"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B"]

malatium-0.1.0/src/malatium/backtester.py

@@ -0,0 +1,165 @@
+"""Daily loop over a book of reference units, priced off the reference-return panel.
+
+The book holds `units` of the reference instrument per name. Each session:
+
+1. Mark the units held into today. P&L is `units × entry_vega × pnl_per_vega`,
+   the holding cost (rolls, hedging) `|units| × entry_vega × cost_per_vega`.
+   A held name with no row today is closed with no P&L and no cost.
+2. On a rebalance session, the strategy's weights times the gross vega
+   budget are the target dollar vega per name; units are the target divided
+   by the unit's dollar vega at today's close. Names the strategy does not
+   weight go to zero. Trading `|Δunits|` pays the half-spread of the unit.
+3. Record one row per name held at any point today.
+
+Costs are charged at `cost_fraction` of the panel's half-spread and holding
+cost; `exit_cost` is always recorded and never charged.
+"""
+
+import datetime as dt
+from typing import Literal
+
+import polars as pl
+
+from malatium.data import CalendarProvider, ReferenceReturnsProvider
+from malatium.schemas import PositionResultsSchema, ReferenceReturnsSchema
+from malatium.strategy import Strategy
+from malatium.types import PositionResults, ReferenceReturns, Weights
+
+HOLDINGS_SCHEMA = {"symbol": pl.String, "units": pl.Float64}
+
+
+def is_rebalance_date(
+    date_: dt.date,
+    previous: dt.date | None,
+    frequency: Literal["daily", "weekly", "monthly"],
+) -> bool:
+    if previous is None or frequency == "daily":
+        return True
+    if frequency == "weekly":
+        return date_.isocalendar()[:2] != previous.isocalendar()[:2]
+    if frequency == "monthly":
+        return (date_.year, date_.month) != (previous.year, previous.month)
+    raise ValueError(f"unknown rebalance frequency {frequency!r}")
+
+
+class Backtester:
+    def run(
+        self,
+        calendar_provider: CalendarProvider,
+        reference_returns_provider: ReferenceReturnsProvider,
+        strategy: Strategy,
+        start: dt.date,
+        end: dt.date,
+        gross_vega: float,
+        rebalance_frequency: Literal["daily", "weekly", "monthly"] = "weekly",
+        cost_fraction: float = 0.0,
+    ) -> PositionResults:
+        """Run `strategy` from `start` to `end` and return one row per (date, symbol) held.
+
+        Args:
+            calendar_provider: Trading sessions.
+            reference_returns_provider: The reference unit's marks per date.
+            strategy: Produces budget-fraction weights on rebalance dates.
+            start: First session, inclusive.
+            end: Last session, inclusive.
+            gross_vega: The budget in dollars per vol point that weights are fractions of.
+            rebalance_frequency: When `generate_weights` is called.
+            cost_fraction: Share of the panel's half-spread and holding cost to charge.
+        """
+        holdings_df = pl.DataFrame(schema=HOLDINGS_SCHEMA)
+        previous: dt.date | None = None
+        days: list[pl.DataFrame] = []
+        for date_ in calendar_provider.get(start, end):
+            today_df = ReferenceReturnsSchema.validate(
+                reference_returns_provider.get(date_), cast=True
+            )
+            weights_df = None
+            if is_rebalance_date(date_, previous, rebalance_frequency):
+                weights_df = strategy.generate_weights(date_)
+            day_df = step(date_, holdings_df, today_df, weights_df, gross_vega, cost_fraction)
+            holdings_df = day_df.filter(pl.col("units") != 0).select("symbol", "units")
+            days.append(day_df)
+            previous = date_
+        if not days:
+            return PositionResultsSchema.create_empty()
+        return PositionResultsSchema.validate(pl.concat(days), cast=True)
+
+
+def step(
+    date_: dt.date,
+    holdings_df: pl.DataFrame,
+    today_df: ReferenceReturns,
+    weights_df: Weights | None,
+    gross_vega: float,
+    cost_fraction: float,
+) -> pl.DataFrame:
+    """One session: mark, optionally rebalance, record."""
+    present = pl.col("dollar_vega").is_not_null()
+    inception_vega = (
+        pl.when(pl.col("event").is_in(["open", "roll"]))
+        .then(pl.col("dollar_vega"))
+        .otherwise(pl.col("entry_vega"))
+        .fill_null(0.0)
+    )
+    frame = (
+        holdings_df.join(today_df.drop("date"), on="symbol", how="full", coalesce=True)
+        .with_columns(pl.col("units").fill_null(0.0))
+        .with_columns(
+            (pl.col("units") * pl.col("entry_vega") * pl.col("pnl_per_vega"))
+            .fill_null(0.0)
+            .alias("pnl"),
+            (pl.col("units").abs() * pl.col("entry_vega") * pl.col("cost_per_vega") * cost_fraction)
+            .fill_null(0.0)
+            .alias("cost"),
+            (pl.col("exit_cost_per_vega").fill_null(0.0) * inception_vega).alias("half_spread"),
+            pl.when(present).then(pl.col("units")).otherwise(0.0).alias("marked_units"),
+            pl.when((pl.col("units") != 0) & ~present)
+            .then(pl.lit("forced_close"))
+            .otherwise(pl.col("event").fill_null(""))
+            .alias("event"),
+        )
+    )
+    if weights_df is None:
+        frame = frame.with_columns(pl.col("marked_units").alias("new_units"))
+    else:
+        targets_df = weights_df.select(
+            "symbol", (pl.col("weight") * gross_vega).alias("target_vega")
+        )
+        sizable = present & (pl.col("dollar_vega") > 0)
+        frame = (
+            frame.join(targets_df, on="symbol", how="left")
+            .with_columns(
+                pl.when(sizable)
+                .then(pl.col("target_vega").fill_null(0.0) / pl.col("dollar_vega"))
+                .otherwise(pl.col("marked_units"))
+                .alias("new_units")
+            )
+            .with_columns((pl.col("new_units") - pl.col("marked_units")).alias("traded"))
+            .with_columns(
+                (
+                    pl.col("cost") + pl.col("traded").abs() * pl.col("half_spread") * cost_fraction
+                ).alias("cost"),
+                pl.when((pl.col("marked_units") == 0) & (pl.col("new_units") != 0))
+                .then(pl.lit("open"))
+                .when((pl.col("marked_units") != 0) & (pl.col("new_units") == 0))
+                .then(pl.lit("close"))
+                .when((pl.col("traded") != 0) & (pl.col("event") == ""))
+                .then(pl.lit("trade"))
+                .otherwise(pl.col("event"))
+                .alias("event"),
+            )
+        )
+    return (
+        frame.filter((pl.col("units") != 0) | (pl.col("new_units") != 0))
+        .select(
+            pl.lit(date_).alias("date"),
+            "symbol",
+            pl.col("new_units").alias("units"),
+            (pl.col("new_units") * pl.col("dollar_vega").fill_null(0.0)).alias("dollar_vega"),
+            "pnl",
+            "cost",
+            (pl.col("new_units").abs() * pl.col("half_spread")).alias("exit_cost"),
+            "event",
+        )
+        .sort("symbol")
+    )

malatium-0.1.0/src/malatium/data.py

@@ -0,0 +1,62 @@
+"""Provider protocols: anything that answers `get(date_)` with that day's frame."""
+
+import datetime as dt
+from typing import Protocol
+
+from malatium.types import (
+    Alphas,
+    FactorCovariances,
+    FactorLoadings,
+    IdioVol,
+    ReferenceReturns,
+    Scores,
+    Universe,
+)
+
+
+class CalendarProvider(Protocol):
+    """Trading sessions in an inclusive window."""
+
+    def get(self, start: dt.date, end: dt.date) -> list[dt.date]: ...
+
+
+class UniverseProvider(Protocol):
+    """Names in the universe on a date, with columns [date, symbol]."""
+
+    def get(self, date_: dt.date) -> Universe: ...
+
+
+class ScoresProvider(Protocol):
+    """Cross-sectional scores with columns [date, symbol, score]."""
+
+    def get(self, date_: dt.date) -> Scores: ...
+
+
+class AlphaProvider(Protocol):
+    """Expected P&L per dollar of vega with columns [date, symbol, alpha]."""
+
+    def get(self, date_: dt.date) -> Alphas: ...
+
+
+class ReferenceReturnsProvider(Protocol):
+    """The reference unit's marks for a date; see `ReferenceReturnsSchema`."""
+
+    def get(self, date_: dt.date) -> ReferenceReturns: ...
+
+
+class FactorLoadingsProvider(Protocol):
+    """Factor exposures with columns [date, symbol, factor, loading]."""
+
+    def get(self, date_: dt.date) -> FactorLoadings: ...
+
+
+class FactorCovariancesProvider(Protocol):
+    """Factor covariance with columns [date, factor_1, factor_2, covariance]."""
+
+    def get(self, date_: dt.date) -> FactorCovariances: ...
+
+
+class IdioVolProvider(Protocol):
+    """Idiosyncratic vol per dollar of vega with columns [date, symbol, idio_vol]."""
+
+    def get(self, date_: dt.date) -> IdioVol: ...

malatium-0.1.0/src/malatium/optimizer/__init__.py

@@ -0,0 +1,24 @@
+from malatium.optimizer.base import Objective, OptimizationError, OptimizerConstraint
+from malatium.optimizer.constraints import (
+    FactorNeutral,
+    GrossCap,
+    GrossShortCap,
+    NetVegaNeutral,
+    PerNameCap,
+)
+from malatium.optimizer.mvo import MVO
+from malatium.optimizer.objectives import MaxUtility, TurnoverPenalty
+
+__all__ = [
+    "MVO",
+    "FactorNeutral",
+    "GrossCap",
+    "GrossShortCap",
+    "MaxUtility",
+    "NetVegaNeutral",
+    "Objective",
+    "OptimizationError",
+    "OptimizerConstraint",
+    "PerNameCap",
+    "TurnoverPenalty",
+]

malatium-0.1.0/src/malatium/optimizer/base.py

@@ -0,0 +1,34 @@
+"""Objective and constraint interfaces.
+
+`MVO` builds `cp.Problem(Maximize(sum of objective terms), constraints)` and
+passes every term the same keyword arguments:
+
+    alphas       (n,)   expected daily P&L per dollar of vega
+    covariance   (n, n) daily covariance of P&L per dollar of vega
+    loadings     (n, k) factor loadings
+    factors      list[str]
+    previous     (n,)   the weights held before this rebalance
+    symbols      list[str]
+
+`weights` is the (n,) CVXPY variable: each name's fraction of the gross vega
+budget, long vega positive.
+"""
+
+from abc import ABC, abstractmethod
+
+import cvxpy as cp
+
+
+class Objective(ABC):
+    @abstractmethod
+    def build(self, weights: cp.Variable, **kwargs) -> cp.Expression:
+        """An expression to maximise; a penalty returns a negative expression."""
+
+
+class OptimizerConstraint(ABC):
+    @abstractmethod
+    def build(self, weights: cp.Variable, **kwargs) -> cp.Constraint | list[cp.Constraint]: ...
+
+
+class OptimizationError(RuntimeError):
+    """The solver did not return an optimal point."""

malatium-0.1.0/src/malatium/optimizer/constraints.py

@@ -0,0 +1,67 @@
+"""Hard constraints on the weight vector. Every cap is a fraction of the gross vega budget."""
+
+import cvxpy as cp
+import numpy as np
+
+from malatium.optimizer.base import OptimizerConstraint
+
+
+class NetVegaNeutral(OptimizerConstraint):
+    """|sum(w)| <= tolerance."""
+
+    def __init__(self, tolerance: float = 0.0):
+        self.tolerance = tolerance
+
+    def build(self, weights: cp.Variable, **kwargs) -> list[cp.Constraint]:
+        return [cp.sum(weights) <= self.tolerance, cp.sum(weights) >= -self.tolerance]
+
+
+class FactorNeutral(OptimizerConstraint):
+    """|B' w| <= epsilon per factor; every factor unless `factors` names a subset."""
+
+    def __init__(self, epsilon: float = 0.0, factors: tuple[str, ...] | None = None):
+        self.epsilon = epsilon
+        self.factors = factors
+
+    def build(self, weights: cp.Variable, **kwargs) -> list[cp.Constraint]:
+        loadings: np.ndarray = kwargs["loadings"]
+        names: list[str] = kwargs["factors"]
+        columns = [
+            index
+            for index, name in enumerate(names)
+            if self.factors is None or name in self.factors
+        ]
+        if not columns:
+            return []
+        exposure = loadings[:, columns].T @ weights
+        return [exposure <= self.epsilon, exposure >= -self.epsilon]
+
+
+class PerNameCap(OptimizerConstraint):
+    """|w_i| <= cap."""
+
+    def __init__(self, cap: float):
+        self.cap = cap
+
+    def build(self, weights: cp.Variable, **kwargs) -> cp.Constraint:
+        return cp.abs(weights) <= self.cap
+
+
+class GrossShortCap(OptimizerConstraint):
+    """sum(max(-w_i, 0)) <= cap."""
+
+    def __init__(self, cap: float):
+        self.cap = cap
+
+    def build(self, weights: cp.Variable, **kwargs) -> cp.Constraint:
+        return cp.sum(cp.pos(-weights)) <= self.cap
+
+
+class GrossCap(OptimizerConstraint):
+    """sum(|w_i|) <= cap; 1.0 is the whole budget."""
+
+    def __init__(self, cap: float = 1.0):
+        self.cap = cap
+
+    def build(self, weights: cp.Variable, **kwargs) -> cp.Constraint:
+        return cp.norm1(weights) <= self.cap