Kolmo API

Overview

kolmo-stats is a Python package for analysts, traders, and risk teams. It works with lists, dictionaries, NumPy arrays, pandas Series, and DataFrames.

Install

python -m pip install kolmo-stats

Intent: install the core package. JAX and CVXPY are optional extras for workflows shown below.

Import a few functions

from kolmo import curve_shape, crack_spread, historical_var
from kolmo import scenario_pnl, npv

Intent: keep imports explicit. The package is designed for readable scripts and notebooks.

Core API

Read a forward curve

from kolmo import curve_shape, calendar_spread

brent = {"M1": 84.5, "M2": 83.2, "M6": 80.5}

shape = curve_shape(brent)
spread = calendar_spread(brent, "M1", "M6")

Intent: turn a small contract dictionary into curve structure and near-minus-far spread.

Check a crack spread

from kolmo import crack_spread

margin = crack_spread(
    crude=80,
    gasoline=103,
    distillate=110,
    ratio="3-2-1",
)

Intent: convert crude and product prices into a comparable refining margin.

Value a project

from kolmo import npv

cashflows = [80, 120, 140, 130, 110]
value = npv(cashflows, discount_rate=0.12, initial_investment=400)

Intent: use the same plain-function style for economics as for market analytics.

JAX example

Use JAX when the array work is the heavy part. Generate or transform many scenarios with JAX, then pass ordinary values into Kolmo for the market statistic.

python -m pip install jax

Intent: add JAX only when you need fast array simulation or batching.

import jax
import jax.numpy as jnp
from kolmo import historical_var

key = jax.random.PRNGKey(7)
returns = jax.random.normal(key, shape=(20_000,)) * 0.025
pnl = (84.5 * jnp.exp(returns) - 84.5) * 100_000

var_95 = historical_var(pnl.tolist(), confidence=0.95)

Intent: let JAX create the simulated P&L distribution; let Kolmo compute the risk number.

CVXPY example

Use CVXPY when you need variables, objectives, and constraints. After solving, use Kolmo to score the resulting book under a scenario.

python -m pip install cvxpy

Intent: add CVXPY only for optimization workflows.

import cvxpy as cp
import numpy as np
from kolmo import scenario_pnl

exposure = np.array([1_000_000.0, -400_000.0])
max_trade = np.array([750_000.0, 500_000.0])
hedge = cp.Variable(2)

problem = cp.Problem(
    cp.Minimize(cp.sum_squares(exposure + hedge)),
    [cp.abs(hedge) <= max_trade],
)
problem.solve()

net = exposure + hedge.value
pnl = scenario_pnl({"brent": float(net[0])}, {"brent": -0.05})

Intent: choose a constrained hedge first, then evaluate scenario impact with Kolmo.

Reference

The public API is grouped by job.

• mean
• weighted_mean
• rolling_zscore
• seasonal_zscore
• rolling_correlation
• lead_lag_correlation
• curve_shape
• calendar_spread
• butterfly_spread
• roll_yield
• curve_slope
• crack_spread
• spark_spread
• lng_arbitrage
• historical_var
• expected_shortfall
• scenario_pnl
• hedge_ratio
• npv
• breakeven_price