Silver Fund Quant

A quantitative finance library for the BYU Silver Fund quant team. Provides tools for data loading, portfolio optimization, backtesting, performance analysis, and signal research — all built on Polars DataFrames.

Installation

pip install sf-quant

Environment Configuration

sf-quant requires two environment variables to locate data: ROOT and DATABASE.

Option 1: .env file or environment variables

Create a .env file in your project root (automatically loaded via python-dotenv):

ROOT=/path/to/root
DATABASE=your_database

Or export them in your shell:

export ROOT=/path/to/root
export DATABASE=your_database

Option 2: Programmatic configuration

Set values at runtime using sfd.env():

import sf_quant.data as sfd

sfd.env(root="/path/to/root", database="your_database")

This will override any values set via environment variables.

Quick Start

A complete workflow: load asset data, build a momentum alpha signal, construct a covariance matrix, and optimize a portfolio.

import sf_quant.data as sfd
import sf_quant.optimizer as sfo
import datetime as dt
import polars as pl

# 1. Load asset data
df = (
    sfd.load_assets(
        start=dt.date(2024, 1, 1),
        end=dt.date(2024, 12, 31),
        columns=["date", "barrid", "price", "return", "specific_risk", "predicted_beta"],
        in_universe=True,
    )
    .with_columns(pl.col("return", "specific_risk").truediv(100))
    .sort("barrid", "date")
)

# 2. Build a momentum alpha signal
df_clean = (
    df
    .with_columns(
        pl.col("return").log1p().rolling_sum(window_size=230).shift(22).over("barrid").alias("momentum"),
    )
    .with_columns(
        pl.col("momentum").sub(pl.col("momentum").mean()).truediv(pl.col("momentum").std()).over("date").alias("score")
    )
    .with_columns(
        pl.lit(0.05).mul(pl.col("score")).mul(pl.col("specific_risk")).alias("alpha")
    )
    .drop_nulls()
    .sort("barrid")
)

# 3. Construct the covariance matrix
date_ = df_clean["date"].last()
barrids = df_clean["barrid"].to_list()

covariance_matrix = (
    sfd.construct_covariance_matrix(date_=date_, barrids=barrids)
    .drop("barrid").to_numpy()
)

# 4. Optimize the portfolio
weights = sfo.mve_optimizer(
    ids=barrids,
    alphas=df_clean["alpha"].to_list(),
    betas=df_clean["predicted_beta"].to_list(),
    covariance_matrix=covariance_matrix,
    constraints=[sfo.ZeroBeta()],
    gamma=100,
)

Modules

sf_quant.data

Load financial data as Polars DataFrames. Use get_*_columns() to inspect available columns for any dataset.

sf_quant.optimizer

Mean-variance efficient (MVE) portfolio optimizer built on CVXPY.

import sf_quant.optimizer as sfo

weights = sfo.mve_optimizer(
    ids=barrids,
    alphas=alphas,
    covariance_matrix=covariance_matrix,
    constraints=[sfo.FullInvestment(), sfo.LongOnly()],
    gamma=2,
)

Available constraints:

The exported Constraint protocol defines the interface for custom constraints. Total-space constraints use h + b when the dynamic optimizer receives benchmark weights b; without a benchmark they act on h directly. ZeroInvestment and ZeroBeta always act on the optimization variable. GrossLeverage rejects booleans, nonnumeric values, nonpositive limits, NaN, and infinities. A gross limit of 1.6 permits up to 130% long and 30% short only when net investment is also 1.

The dynamic optimizer maximizes expected alpha under a factor-model risk cap:

weights = sfo.dynamic_mve_optimizer(
    ids=barrids,
    alphas=alphas,
    factor_exposures=factor_exposures,
    factor_covariance=factor_covariance,
    specific_risk=specific_variance,
    constraints=[sfo.ZeroInvestment(), sfo.LongOnly(), sfo.ZeroBeta()],
    target_active_risk=0.05,
    betas=betas,
    benchmark_weights=benchmark_weights,
    active_weights=True,
)

Supply specific variance, not standard deviation, to specific_risk, in units consistent with the factor covariance and annualized risk cap. The output includes weight, model-predicted active_risk, and gamma implied by the risk constraint's dual variable. active_weights=False requires benchmark weights and returns total weights instead of active weights.

Only the supplied constraints impose a mandate. An empty list leaves the dynamic risk cap alone; it does not enforce investment, beta neutrality, or long-only holdings, and the cap need not bind. The standard optimizer's empty list instead retains its quadratic risk penalty controlled by gamma. For standalone long-short research, omit benchmark weights (or pass zeros) so total-space limits apply directly to the optimized weights. Beta neutrality is selected with ZeroBeta(); there is no separate boolean beta flag.

sf_quant.backtester

Run walk-forward backtests that optimize at each rebalance date.

import sf_quant.backtester as sfb
import sf_quant.optimizer as sfo

# Sequential (single core)
portfolio = sfb.backtest_sequential(data=df, constraints=constraints, gamma=2)

# Parallel (multi-core via Ray)
portfolio = sfb.backtest_parallel(data=df, constraints=constraints, gamma=2, n_cpus=4)

# Dynamic risk cap; mandates come from the constraint objects
portfolio = sfb.dynamic_backtest_parallel(
    data=df,
    constraints=[sfo.ZeroInvestment(), sfo.LongOnly(), sfo.ZeroBeta()],
    target_active_risk=0.05,
    active_weights=True,
    n_cpus=4,
)

sf_quant.performance

Compute and visualize portfolio performance metrics.

sf_quant.research

Tools for signal analysis and factor research.

Documentation Development

To run a local server of the sphinx documentation run

uv run sphinx-autobuild docs docs/_build/html

Release Process

1. Create PR
2. Merge PR(s)
3. Increment version in pyproject.toml
4. git tag v*..
5. git push origin main --tags
6. Create a release and publish release notes (github)
7. uv build
8. uv publish