abaquant.financial_math.portfolio¶

Import path: abaquant.financial_math.portfolio

Domain: Time-value, actuarial, fixed-income, corporate-finance, and portfolio mathematics.

Purpose¶

Pure portfolio return, covariance, and allocation mathematics.

When to use it¶

Use these functions for deterministic calculations where explicit cash-flow, rate, compounding, sign, and annualization conventions matter.

Public objects¶

function: simple_returns_from_prices — Compute simple returns independently for each price series.
function: log_returns_from_prices — Compute logarithmic returns independently for each price series.
function: annualized_mean_returns_from_returns — Annualize arithmetic mean returns from periodic observations.
function: annualized_covariance_from_returns — Annualize the sample covariance matrix of periodic returns.
function: equal_weight — Construct or evaluate an equally weighted fully invested portfolio.
function: portfolio_variance — Compute portfolio variance from a weight vector and covariance matrix.
function: minimum_variance_weights — Solve the constrained global minimum-variance allocation problem.
function: maximum_sharpe_weights — Solve the constrained maximum-Sharpe portfolio allocation problem.
function: historical_mean_returns — Estimate annualized arithmetic expected returns from historical prices.
function: sample_covariance — Estimate an annualized covariance matrix from historical prices.
function: log_return_volatility — Estimate annualized volatility from historical log returns.
function: portfolio_return — Compute the weighted expected return of a portfolio.
function: portfolio_volatility — Compute portfolio volatility from a weight vector and covariance matrix.
function: portfolio_sharpe — Compute the annualized excess-return-to-volatility ratio.
function: equal_weight_portfolio — Compute the result defined by ‘’equal_weight_portfolio’’ under this module’s documented convention.
function: max_sharpe_portfolio — Compute the result defined by ‘’max_sharpe_portfolio’’ under this module’s documented convention.
function: min_variance_portfolio — Compute the result defined by ‘’min_variance_portfolio’’ under this module’s documented convention.
function: risk_parity_objective — Compute the result defined by ‘’risk_parity_objective’’ under this module’s documented convention.
function: risk_parity_portfolio — Compute the result defined by ‘’risk_parity_portfolio’’ under this module’s documented convention.
function: mvsk_neg_utility — Compute the result defined by ‘’mvsk_neg_utility’’ under this module’s documented convention.
function: mvsk_portfolio — Compute the result defined by ‘’mvsk_portfolio’’ under this module’s documented convention.
function: monte_carlo_portfolio_cloud — Compute the result defined by ‘’monte_carlo_portfolio_cloud’’ under this module’s documented convention.
function: evaluate_custom_portfolio — Compute the result defined by ‘’evaluate_custom_portfolio’’ under this module’s documented convention.
function: evaluate_custom_portfolio_from_prices — Compute the result defined by ‘’evaluate_custom_portfolio_from_prices’’ under this module’s documented convention.
function: optimize_portfolio_strategies — Compute the result defined by ‘’optimize_portfolio_strategies’’ under this module’s documented convention.

Detailed reference¶

Pure portfolio return, covariance, and allocation mathematics.

Purpose¶

The module transforms price panels into returns, annualizes moments, evaluates portfolios, and solves selected static allocation problems.

Conventions¶

Returns are simple or log returns as stated. The default annualization factor is 252 observations per year. Weight vectors are ordered consistently with the input expected-return vector or covariance matrix.

Scope and limitations¶

Optimisation outputs are in-sample mathematical solutions; they do not include transaction costs, taxes, rebalancing, or investment advice.

References

[ 1 ] Markowitz, H. (1952), “Portfolio Selection”. [ 2 ] Sharpe, W. F. (1966), “Mutual Fund Performance”.

abaquant.financial_math.portfolio.annualized_covariance_from_returns(returns, periods=TRADING_DAYS)¶

Annualize the sample covariance matrix of periodic returns.

Parameters:

returns (pd.DataFrame) – Periodic simple return observations; rows are observation dates and columns are assets when two-dimensional.
periods (int, default=TRADING_DAYS) – Number of discrete compounding or payment periods.

Returns:

Tabular result with schema defined by the module-level convention.

Return type:

pd.DataFrame

Notes

This is an analytical in-sample calculation. It does not by itself model transaction costs, execution effects, taxes, or future return uncertainty.

abaquant.financial_math.portfolio.annualized_mean_returns_from_returns(returns, periods=TRADING_DAYS)¶

Annualize arithmetic mean returns from periodic observations.

Parameters:

returns (pd.DataFrame) – Periodic simple return observations; rows are observation dates and columns are assets when two-dimensional.
periods (int, default=TRADING_DAYS) – Number of discrete compounding or payment periods.

Returns:

One-dimensional labeled result aligned to the documented input order.

Return type:

pd.Series

Notes

This is an analytical in-sample calculation. It does not by itself model transaction costs, execution effects, taxes, or future return uncertainty.

abaquant.financial_math.portfolio.equal_weight(n_assets)¶

Construct or evaluate an equally weighted fully invested portfolio.

Parameters:: n_assets (int) – Number of assets in the allocation problem.
Returns:: Numeric array ordered consistently with the supplied strikes, time grid, assets, or state labels.
Return type:: numpy.ndarray

abaquant.financial_math.portfolio.equal_weight_portfolio(asset_names, expected_returns, covariance, risk_free_rate)¶

Compute the result defined by equal_weight_portfolio under this module’s documented convention.

Parameters:

asset_names (list[str]) – Asset labels ordered consistently with expected returns and covariance.
expected_returns (np.ndarray) – Expected-return vector ordered consistently with portfolio weights and covariance.
covariance (np.ndarray) – Square covariance matrix ordered consistently with the weight vector.
risk_free_rate (float) – Annual risk-free rate in decimal units.

Returns:

Positional outputs produced by the equal weight portfolio calculation.

Return type:

tuple[float, float, float, dict[str, float]]

Notes

This is an analytical in-sample calculation. It does not by itself model transaction costs, execution effects, taxes, or future return uncertainty.

abaquant.financial_math.portfolio.evaluate_custom_portfolio(prices, weights_by_asset, expected_return_fn, covariance_fn)¶

Compute the result defined by evaluate_custom_portfolio under this module’s documented convention.

Parameters:

prices (pd.DataFrame) – Price observations with dates on the index and assets on columns where applicable.
weights_by_asset (dict[str, float]) – Mapping from asset label to portfolio weight.
expected_return_fn (Callable[[pd.DataFrame], pd.Series]) – Callable that estimates expected returns from a price panel.
covariance_fn (Callable[[pd.DataFrame], pd.DataFrame]) – Callable that estimates a covariance matrix from a price panel.

Returns:

Positional outputs produced by the evaluate custom portfolio calculation.

Return type:

tuple[float, float, np.ndarray, list[str]]

Notes

This is an analytical in-sample calculation. It does not by itself model transaction costs, execution effects, taxes, or future return uncertainty.

abaquant.financial_math.portfolio.evaluate_custom_portfolio_from_prices(prices, weights_by_asset)¶

Compute the result defined by evaluate_custom_portfolio_from_prices under this module’s documented convention.

Parameters:

prices (pd.DataFrame) – Price observations with dates on the index and assets on columns where applicable.
weights_by_asset (dict[str, float]) – Mapping from asset label to portfolio weight.

Returns:

Positional outputs produced by the evaluate custom portfolio from prices calculation.

Return type:

tuple[float, float, np.ndarray, list[str]]

Notes

This is an analytical in-sample calculation. It does not by itself model transaction costs, execution effects, taxes, or future return uncertainty.

abaquant.financial_math.portfolio.historical_mean_returns(prices, periods=TRADING_DAYS)¶

Estimate annualized arithmetic expected returns from historical prices.

Parameters:

prices (pd.DataFrame) – Price observations with dates on the index and assets on columns where applicable.
periods (int, default=TRADING_DAYS) – Number of discrete compounding or payment periods.

Returns:

One-dimensional labeled result aligned to the documented input order.

Return type:

pd.Series

Notes

This is an analytical in-sample calculation. It does not by itself model transaction costs, execution effects, taxes, or future return uncertainty.

abaquant.financial_math.portfolio.log_return_volatility(prices, periods=TRADING_DAYS)¶

Estimate annualized volatility from historical log returns.

Parameters:

prices (pd.Series) – Price observations with dates on the index and assets on columns where applicable.
periods (int, default=TRADING_DAYS) – Number of discrete compounding or payment periods.

Returns:

Computed log return volatility as a dimensionless decimal quantity.

Return type:

float

abaquant.financial_math.portfolio.log_returns_from_prices(prices)¶

Compute logarithmic returns independently for each price series.

Parameters:: prices (pd.DataFrame) – Price observations with dates on the index and assets on columns where applicable.
Returns:: Tabular result with schema defined by the module-level convention.
Return type:: pd.DataFrame

Notes

This is an analytical in-sample calculation. It does not by itself model transaction costs, execution effects, taxes, or future return uncertainty.

abaquant.financial_math.portfolio.max_sharpe_portfolio(asset_names, expected_returns, covariance, risk_free_rate)¶

Compute the result defined by max_sharpe_portfolio under this module’s documented convention.

Parameters:

asset_names (list[str]) – Asset labels ordered consistently with expected returns and covariance.
expected_returns (np.ndarray) – Expected-return vector ordered consistently with portfolio weights and covariance.
covariance (np.ndarray) – Square covariance matrix ordered consistently with the weight vector.
risk_free_rate (float) – Annual risk-free rate in decimal units.

Returns:

Positional outputs produced by the max sharpe portfolio calculation.

Return type:

tuple[float, float, float, dict[str, float]]

Notes

This is an analytical in-sample calculation. It does not by itself model transaction costs, execution effects, taxes, or future return uncertainty.

abaquant.financial_math.portfolio.maximum_sharpe_weights(mean_returns, covariance_matrix, risk_free_rate, bounds=(0.0, 1.0))¶

Solve the constrained maximum-Sharpe portfolio allocation problem.

Parameters:

mean_returns (np.ndarray) – Expected-return vector ordered consistently with the covariance matrix.
covariance_matrix (np.ndarray) – Square covariance matrix ordered consistently with the asset order.
risk_free_rate (float) – Annual risk-free rate in decimal units.
bounds (tuple[float, float], default=(0.0, 1.0)) – Allocation bounds in the format accepted by the underlying optimizer.

Returns:

Numeric array ordered consistently with the supplied strikes, time grid, assets, or state labels.

Return type:

numpy.ndarray

Notes

This is an analytical in-sample calculation. It does not by itself model transaction costs, execution effects, taxes, or future return uncertainty.

abaquant.financial_math.portfolio.min_variance_portfolio(asset_names, expected_returns, covariance, risk_free_rate)¶

Compute the result defined by min_variance_portfolio under this module’s documented convention.

Parameters:

asset_names (list[str]) – Asset labels ordered consistently with expected returns and covariance.
expected_returns (np.ndarray) – Expected-return vector ordered consistently with portfolio weights and covariance.
covariance (np.ndarray) – Square covariance matrix ordered consistently with the weight vector.
risk_free_rate (float) – Annual risk-free rate in decimal units.

Returns:

Positional outputs produced by the min variance portfolio calculation.

Return type:

tuple[float, float, float, dict[str, float]]

Notes

This is an analytical in-sample calculation. It does not by itself model transaction costs, execution effects, taxes, or future return uncertainty.

abaquant.financial_math.portfolio.minimum_variance_weights(covariance_matrix, bounds=(0.0, 1.0))¶

Solve the constrained global minimum-variance allocation problem.

Parameters:

covariance_matrix (np.ndarray) – Square covariance matrix ordered consistently with the asset order.
bounds (tuple[float, float], default=(0.0, 1.0)) – Allocation bounds in the format accepted by the underlying optimizer.

Returns:

Numeric array ordered consistently with the supplied strikes, time grid, assets, or state labels.

Return type:

numpy.ndarray

Notes

This is an analytical in-sample calculation. It does not by itself model transaction costs, execution effects, taxes, or future return uncertainty.

abaquant.financial_math.portfolio.monte_carlo_portfolio_cloud(expected_returns, covariance, risk_free_rate, n_simulations=2500, seed=None)¶

Compute the result defined by monte_carlo_portfolio_cloud under this module’s documented convention.

Parameters:

expected_returns (np.ndarray) – Expected-return vector ordered consistently with portfolio weights and covariance.
covariance (np.ndarray) – Square covariance matrix ordered consistently with the weight vector.
risk_free_rate (float) – Annual risk-free rate in decimal units.
n_simulations (int, default=2500) – Number of simulated portfolio allocations.
seed (int | None, default=None) – Optional pseudo-random seed for reproducible simulation.

Returns:

Positional outputs produced by the monte carlo portfolio cloud calculation.

Return type:

tuple[np.ndarray, np.ndarray, np.ndarray, np.ndarray]

Notes

This is an analytical in-sample calculation. It does not by itself model transaction costs, execution effects, taxes, or future return uncertainty.

abaquant.financial_math.portfolio.mvsk_neg_utility(weights, daily_returns, lambda2=1.0, lambda3=0.5, lambda4=0.5)¶

Compute the result defined by mvsk_neg_utility under this module’s documented convention.

Parameters:

weights (np.ndarray) – Portfolio weights, either a mapping keyed by asset or an ordered numeric vector as documented by the callable.
daily_returns (np.ndarray) – Daily simple-return matrix used by higher-moment portfolio objectives.
lambda2 (float, default=1.0) – Second-moment penalty coefficient in the MVSK utility.
lambda3 (float, default=0.5) – Third-moment reward or penalty coefficient in the MVSK utility.
lambda4 (float, default=0.5) – Fourth-moment penalty coefficient in the MVSK utility.

Returns:

Computed mvsk neg utility as a scalar in the units implied by the input values.

Return type:

float

abaquant.financial_math.portfolio.mvsk_portfolio(asset_names, expected_returns, covariance, daily_returns, risk_free_rate)¶

Compute the result defined by mvsk_portfolio under this module’s documented convention.

Parameters:

asset_names (list[str]) – Asset labels ordered consistently with expected returns and covariance.
expected_returns (np.ndarray) – Expected-return vector ordered consistently with portfolio weights and covariance.
covariance (np.ndarray) – Square covariance matrix ordered consistently with the weight vector.
daily_returns (np.ndarray) – Daily simple-return matrix used by higher-moment portfolio objectives.
risk_free_rate (float) – Annual risk-free rate in decimal units.

Returns:

Positional outputs produced by the mvsk portfolio calculation.

Return type:

tuple[float, float, float, dict[str, float]]

Notes

This is an analytical in-sample calculation. It does not by itself model transaction costs, execution effects, taxes, or future return uncertainty.

abaquant.financial_math.portfolio.optimize_portfolio_strategies(prices, risk_free_rate=0.05, n_simulations=2500, seed=None)¶

Compute the result defined by optimize_portfolio_strategies under this module’s documented convention.

Parameters:

prices (pd.DataFrame) – Price observations with dates on the index and assets on columns where applicable.
risk_free_rate (float, default=0.05) – Annual risk-free rate in decimal units.
n_simulations (int, default=2500) – Number of simulated portfolio allocations.
seed (int | None, default=None) – Optional pseudo-random seed for reproducible simulation.

Returns:

Positional outputs produced by the optimize portfolio strategies calculation.

Return type:

tuple[pd.Series, pd.DataFrame, dict[str, tuple[float, float, float, dict[str, float]]], tuple[np.ndarray, np.ndarray, np.ndarray]]

Notes

This is an analytical in-sample calculation. It does not by itself model transaction costs, execution effects, taxes, or future return uncertainty.

abaquant.financial_math.portfolio.portfolio_return(weights, expected_returns)¶

Compute the weighted expected return of a portfolio.

Parameters:

weights (np.ndarray) – Portfolio weights, either a mapping keyed by asset or an ordered numeric vector as documented by the callable.
expected_returns (np.ndarray) – Expected-return vector ordered consistently with portfolio weights and covariance.

Returns:

Computed portfolio return as a dimensionless decimal quantity.

Return type:

float

Notes

This is an analytical in-sample calculation. It does not by itself model transaction costs, execution effects, taxes, or future return uncertainty.

abaquant.financial_math.portfolio.portfolio_sharpe(return_, volatility, risk_free_rate=0.0)¶

Compute the annualized excess-return-to-volatility ratio.

Parameters:

return (float) – Expected portfolio return in decimal annual units.
volatility (float) – Volatility input: a positive annualized decimal number, "realized", or "market" as documented by the applied interface.
risk_free_rate (float, default=0.0) – Annual risk-free rate in decimal units.
return_ (float)

Returns:

Computed portfolio sharpe as a scalar in the units implied by the input values.

Return type:

float

Notes

This is an analytical in-sample calculation. It does not by itself model transaction costs, execution effects, taxes, or future return uncertainty.

abaquant.financial_math.portfolio.portfolio_variance(weights, covariance)¶

Compute portfolio variance from a weight vector and covariance matrix.

Parameters:

weights (np.ndarray) – Portfolio weights, either a mapping keyed by asset or an ordered numeric vector as documented by the callable.
covariance (np.ndarray) – Square covariance matrix ordered consistently with the weight vector.

Returns:

Computed portfolio variance as a scalar in the units implied by the input values.

Return type:

float

Notes

This is an analytical in-sample calculation. It does not by itself model transaction costs, execution effects, taxes, or future return uncertainty.

abaquant.financial_math.portfolio.portfolio_volatility(weights, covariance)¶

Compute portfolio volatility from a weight vector and covariance matrix.

Parameters:

weights (np.ndarray) – Portfolio weights, either a mapping keyed by asset or an ordered numeric vector as documented by the callable.
covariance (np.ndarray) – Square covariance matrix ordered consistently with the weight vector.

Returns:

Computed portfolio volatility as a dimensionless decimal quantity.

Return type:

float

Notes

This is an analytical in-sample calculation. It does not by itself model transaction costs, execution effects, taxes, or future return uncertainty.

abaquant.financial_math.portfolio.risk_parity_objective(weights, covariance)¶

Compute the result defined by risk_parity_objective under this module’s documented convention.

Parameters:

weights (np.ndarray) – Portfolio weights, either a mapping keyed by asset or an ordered numeric vector as documented by the callable.
covariance (np.ndarray) – Square covariance matrix ordered consistently with the weight vector.

Returns:

Computed risk parity objective as a scalar in the units implied by the input values.

Return type:

float

Notes

This is an analytical in-sample calculation. It does not by itself model transaction costs, execution effects, taxes, or future return uncertainty.

abaquant.financial_math.portfolio.risk_parity_portfolio(asset_names, expected_returns, covariance, risk_free_rate)¶

Compute the result defined by risk_parity_portfolio under this module’s documented convention.

Parameters:

asset_names (list[str]) – Asset labels ordered consistently with expected returns and covariance.
expected_returns (np.ndarray) – Expected-return vector ordered consistently with portfolio weights and covariance.
covariance (np.ndarray) – Square covariance matrix ordered consistently with the weight vector.
risk_free_rate (float) – Annual risk-free rate in decimal units.

Returns:

Positional outputs produced by the risk parity portfolio calculation.

Return type:

tuple[float, float, float, dict[str, float]]

Notes

This is an analytical in-sample calculation. It does not by itself model transaction costs, execution effects, taxes, or future return uncertainty.

abaquant.financial_math.portfolio.sample_covariance(prices, periods=TRADING_DAYS)¶

Estimate an annualized covariance matrix from historical prices.

Parameters:

prices (pd.DataFrame) – Price observations with dates on the index and assets on columns where applicable.
periods (int, default=TRADING_DAYS) – Number of discrete compounding or payment periods.

Returns:

Tabular result with schema defined by the module-level convention.

Return type:

pd.DataFrame

Notes

This is an analytical in-sample calculation. It does not by itself model transaction costs, execution effects, taxes, or future return uncertainty.

abaquant.financial_math.portfolio.simple_returns_from_prices(prices)¶

Compute simple returns independently for each price series.

Parameters:: prices (pd.DataFrame) – Price observations with dates on the index and assets on columns where applicable.
Returns:: Tabular result with schema defined by the module-level convention.
Return type:: pd.DataFrame

Notes

This is an analytical in-sample calculation. It does not by itself model transaction costs, execution effects, taxes, or future return uncertainty.