sf_quant.optimizer.mve_optimizer#

sf_quant.optimizer.mve_optimizer(ids: list[str], alphas: ndarray, factor_exposures: ndarray, factor_covariance: ndarray, specific_risk: ndarray, constraints: list[Constraint], gamma: float = 2, betas: ndarray | None = None) → DataFrame#

Mean-variance optimizer using a factor risk model decomposition.

Solves a mean-variance optimization problem where portfolio variance is computed using a factor model with Fama-French style factor decomposition:

\[\Sigma = B F B^T + \text{diag}(D)\]

Parameters#

idslist[str]

Asset identifiers (e.g., ticker symbols or BARRAs).

alphasnp.ndarray

Expected returns for each asset, shape (n_assets,).

factor_exposuresnp.ndarray

B matrix of shape (n_assets, n_factors), containing asset factor exposures.

factor_covariancenp.ndarray

F matrix of shape (n_factors, n_factors), factor covariance matrix.

specific_risknp.ndarray

D vector of shape (n_assets,), idiosyncratic (specific) variance per asset.

constraintslist[Constraint]

List of constraint objects implementing the Constraint protocol (e.g., FullInvestment(), LongOnly()).

gammafloat, optional

Risk aversion parameter. Higher values penalize variance more strongly. Default is 2.

betasnp.ndarray, optional

Predicted betas or other asset-level values required by certain constraints such as UnitBeta or ZeroBeta.

Returns#

pl.DataFrame

Polars DataFrame with columns:

  • barrid : str, asset identifier.

  • weight : float, optimized portfolio weight.

Examples#

>>> import sf_quant.optimizer as sfo
>>> import numpy as np
>>> ids = ['AAPL', 'IBM']
>>> alphas = np.array([1.1, 1.2])
>>> factor_exposures = np.array([[0.8, 0.5], [1.2, 0.3]])
>>> factor_covariance = np.array([[0.5, 0.1], [0.1, 0.2]])
>>> specific_risk = np.array([0.1, 0.15])
>>> constraints = [sfo.FullInvestment()]
>>> weights = sfo.mve_optimizer(
...     ids=ids,
...     alphas=alphas,
...     factor_exposures=factor_exposures,
...     factor_covariance=factor_covariance,
...     specific_risk=specific_risk,
...     constraints=constraints
... )
>>> weights
shape: (2, 2)
┌────────┬────────┐
│ barrid ┆ weight │
│ ---    ┆ ---    │
│ str    ┆ f64    │
╞════════╪════════╡
│ AAPL   ┆ 0.45   │
│ IBM    ┆ 0.55   │
└────────┴────────┘
On this page