riskit 1.0.0

A library providing implementations of various risk metrics for risk-aware trajectory planning.

RisKit: Risk Metrics for Risk-Aware Planning

RisKit provides implementations of common risk metrics used in risk-aware trajectory planning, intended for researchers who need reliable risk quantification under uncertainty.

The library provides the following metrics:

• Expected Value,
• Mean-Variance,
• Value at Risk (VaR),
• Conditional Value at Risk (CVaR), and
• Entropic Risk metrics,

with built-in support for both NumPy and JAX backends (can easily be extended to other backends, e.g. PyTorch). The API is type-safe, but offers automatic backend inference based on the type annotations of the cost function (uncertain variable transform).

RisKit is being actively developed. Some features may be missing and some of the API might change. You can help by reporting issues or contributing fixes and features.

Installation

Python 3.13+ is required.

pip install riskit

Quick Start

import numpy as np
from numtypes import array, Dim2
from riskit import (
    risk, distribution,
    NumPyInputAndState, NumPyUncertaintySamples, NumPyCosts,
)

# A cost function takes typed trajectories and uncertainty samples,
# and returns a costs array of shape (T, M, N). You're free to use
# any type you want though, as long as it supports the necessary operations.
def distance_cost(
    *,
    trajectories: NumPyInputAndState,
    uncertainties: NumPyUncertaintySamples[Dim2],
) -> NumPyCosts:
    x = trajectories.x          # (T, D_x, M)
    xi = uncertainties           # (V, D, N)
    T, _, M = x.shape
    _, _, N = xi.shape
    return np.tile((x[:, 0, :, None] - xi[0, 0, None, :]) ** 2, (1, 1, 1)).reshape(T, M, N)

# The factory infers the NumPy backend from the cost function's return type.
metric = risk.cvar_of(distance_cost, alpha=0.1)

# Create an uncertainty distribution.
uncertainties = distribution.numpy.gaussian(
    mean=array([[0.0]], shape=(1, 1)),
    covariance=array([[[1.0]]], shape=(1, 1, 1)),
    seed=42,
)

# Compute risk over trajectories and uncertainty samples.
results = metric.compute(trajectories=..., uncertainties=uncertainties)

If the cost function in your case works with JAX and returns a JAX array, you can just use the appropriate type annotation and the JAX backend will be automatically inferred.

Risk Metrics

Metric	Factory	Description
Expected Value	risk.expected_value_of(f)	Mean cost across samples
Mean-Variance	risk.mean_variance_of(f, gamma=...)	Mean + γ · Variance tradeoff
Value at Risk	risk.var_of(f, alpha=...)	α-quantile of the cost distribution
Conditional VaR	risk.cvar_of(f, alpha=...)	Expected cost in the worst α-fraction
Entropic Risk	risk.entropic_risk_of(f, theta=...)	Exponential utility-based risk measure

Features

• Multiple risk metrics with a consistent, protocol-based API
• NumPy and JAX backends with automatic inference from type annotations
• Monte Carlo sampling with built-in distributions, or custom sampling strategies

Documentation

To build the Typst-based documentation, install the custom Typst packages locally:

typi --project-directory=documents

typi is available after you've set up the project environment with uv sync.

Contributing

See CONTRIBUTING.md.

License

MIT, see LICENSE.