portfolio_optimization.components.qubos package

This subpackage contains QUBO related classes and methods.

The QuboCompiler can create a variety of QUBO formulation by combining different objectives and constraints with their corresponding penalty or preference parameters.

The QuboFactory class provides a convenient interface for constructing intermediate QUBO matrices for different objectives and constraints.

class portfolio_optimization.components.qubos.QuboCompiler(portfolio_data, k)[source]

Bases: object

QuboCompiler - A compiler class for creating QUBO instances.

This class provides a convenient interface for combining different QUBO formulations without needing to worry about the qubo size.

Methods:

  • add_minimize_hhi: Adds the to minimize HHI QUBO to the compile list.

  • add_maximize_roc: Adds a ROC and optionally a stabilizing QUBO to the compile list.

  • add_emission_constraint: Adds an emission constraint QUBO to the compile list.

  • add_growth_factor_constraint: Adds the growth factor constraint QUBO to the compile list.

__init__(portfolio_data, k)[source]

Init of the QuboCompiler class.

The QuboCompiler can create a variety of QUBO formulation by combining different objectives and constraints with penalty or preference parameters.

Parameters:
  • portfolio_data (PortfolioData) – A PortfolioData object containing the portfolio to optimize.

  • k (int) – The number of bits that are used to represent the outstanding amount for each asset. A fixed point representation is used to represent \(2^k\) different equidistant values in the range \([LB_i, UB_i]\) for asset i.

add_emission_constraint(emission_now, emission_future=None, reduction_percentage_target=0.7)[source]

Adds the emission constraint to the compile list.

The constraint is given by

\[\frac{\sum_{i=1}^Nf_i \cdot x_i}{\sum_{i=1}^N x_i} = g_e \frac{\sum_{i=1}^Ne_i \cdot y_i}{\sum_{i=1}^N y_i},\]

where:

  • \(x_i\) is the future outstanding amount for asset \(i\),

  • \(y_i\) is the current outstanding amount for asset \(i\),

  • \(e_i\) is the current emission intensity for asset \(i\),

  • \(f_i\) is the expected emission intensity at the future for asset \(i\),

  • \(g_e\) is the target value for the relative emission reduction.

For the QUBO formulation, see the docs of calc_emission_constraint().

Parameters:
  • emission_now (str) – Name of the column in the portfolio dataset corresponding to the variables at current time.

  • emission_future (Optional[str]) – Name of the column in the portfolio dataset corresponding to the variables at future time. If no value is provided, it is assumed that the value is constant over time, i.e., the variable emission_now will be used.

  • reduction_percentage_target (float) – target value for reduction percentage amount.

Return type:

TypeVar(QuboCompilerT, bound= QuboCompiler)

Returns:

Self.

add_growth_factor_constraint(growth_target)[source]

Adds the capital growth factor constraint to the compile list.

The constraint is given by

\[\frac{\sum_{i=1}^N x_i}{\sum_{i=1}^N y_i} = g_c,\]

where

  • \(N\) is the total number of assets,

  • \(x_i\) is the future outstanding amount for asset \(i\),

  • \(y_i\) is the current outstanding amount for asset \(i\),

  • \(g_c\) is the target value for the total growth factor.

For the QUBO formulation, see the docs of calc_growth_factor_constraint().

Parameters:

growth_target (float) – target value for growth factor total outstanding amount.

Return type:

TypeVar(QuboCompilerT, bound= QuboCompiler)

Returns:

Self.

add_maximize_roc(formulation, ancilla_variables=0)[source]

Adds the maximize ROC objective and based on the chosen formulation a stabilize c constraint.

Parameters:
  • formulation (int) – Integer representing which formulation to pick. If formulation is 1, then one QUBO term will be added. If formulation is 2, then 2 QUBO terms will be added as well, but the argument ancilla_variables must be provided.

  • ancilla_variables (int) – Number of ancilla variables to use for formulation 2.

Return type:

TypeVar(QuboCompilerT, bound= QuboCompiler)

Returns:

Self.

add_minimize_hhi()[source]

Adds the minimize HHI objective to the compile list.

The HHI objective is given by

\[HHI(x) = \sum_{i=1}^N\left(\frac{x_i}{\sum_{j=1}^N x_j}\right)^2,\]

where

  • \(N\) is the total number of assets,

  • \(x_i\) is the future outstanding amount for asset \(i\).

For the QUBO formulation, see the docs of calc_minimize_hhi().

Return type:

TypeVar(QuboCompilerT, bound= QuboCompiler)

Returns:

Self.

compile()[source]

Compiles all QUBOs in the compile list.

Return type:

TypeVar(QuboCompilerT, bound= QuboCompiler)

Returns:

Self.

make_qubo(*lambdas)[source]

Makes a QUBO of the entire problem with the given lambdas.

Parameters:

lambdas (float) – Scaling parameters for each QUBO in the formulation.

Return type:

tuple[ndarray[Any, dtype[float64]], float]

Returns:

Tuple containing the QUBO matrix and offset.

class portfolio_optimization.components.qubos.QuboFactory(portfolio_data, k)[source]

Bases: object

QuboFactory - A factory class for creating QUBO instances.

This class provides a convenient interface for constructing intermediate QUBO matrices for different objectives and constraints.

Methods:

  • calc_minimize_hhi: Calculates the to minimize HHI QUBO

  • calc_maximize_roc1: Calculates the to maximize return on capital QUBO variant 1

  • calc_maximize_roc2: Calculates the to maximize return on capital QUBO variant 2

  • calc_emission_constraint: Calculates the emission constraint QUBO

  • calc_growth_factor_constraint: Calculates the growth factor constraint QUBO

  • calc_stabilize_c: Calculates the constraint QUBO that stabilizes growth factor.

__init__(portfolio_data, k)[source]

Init of the QuboFactory.

Parameters:
  • portfolio_data (PortfolioData) – A PortfolioData object containing the portfolio to optimize.

  • k (int) – The number of bits that are used to represent the outstanding amount for each asset. A fixed point representation is used to represent \(2^k\) different equidistant values in the range \([LB_i, UB_i]\) for asset i.

calc_emission_constraint(emission_now, emission_future=None, reduction_percentage_target=0.7)[source]

Calculates the emission constraint QUBO for arbitrary target reduction target

The QUBO formulation is given by

\[ \begin{align}\begin{aligned}QUBO(x) &= \left( \sum_{i=1}^N f_i x_i - g_e E \sum_{i=1}^N x_i \right)^2,\\x_i & = LB_i+\frac{UB_i-LB_i}{2^k-1}\sum_{j=0}^{k-1}2^j\cdot x_{i,j},\\E &= \frac{\sum_{i=1}^N e_i \cdot y_i}{\sum_{i=1}^N y_i},\end{aligned}\end{align} \]

where:

  • \(LB_i\) is the lower bound for asset \(i\),

  • \(UB_i\) is the upper bound for asset \(i\),

  • \(k\) is the number of bits,

  • \(e_i\) is the current emission intensity for asset \(i\),

  • \(f_i\) is the expected emission intensity at the future for asset \(i\),

  • \(y_i\) is the current outstanding amount for asset \(i\),

  • \(g_e\) is the target value for the relative emission reduction,

  • and \(x_{i,j}\) are the \(k\) binary variables for asset \(i\) with \(j<k\).

Parameters:
  • emission_now (str) – Name of the column in the portfolio dataset corresponding to the variables at current time.

  • emission_future (Optional[str]) – Name of the column in the portfolio dataset corresponding to the variables at future time. If no value is provided, it is assumed that the value is constant over time, i.e., the variable emission_now will be used.

  • reduction_percentage_target (float) – Target value for reduction percentage amount.

Raises:

KeyError – if the provided column names are not in the portfolio_data.

Return type:

tuple[ndarray[Any, dtype[float64]], float]

Returns:

qubo matrix and its offset

calc_growth_factor_constraint(growth_target)[source]

Calculates the growth factor constraint QUBO

The QUBO formulation is given by

\[QUBO(x) = \left( \frac{\sum_{i=1}^N LB_i + \frac{UB_i-LB_i}{2^k-1}\sum_{j=0}^{k-1} 2^j\cdot x_{i,j}}{\sum_{i=1}^N y_i} - g_c \right)^2\]

where:

  • \(LB_i\) is the lower bound for asset \(i\),

  • \(UB_i\) is the upper bound for asset \(i\),

  • \(k\) is the number of bits,

  • \(g_c\) is the target value for the total growth factor,

  • \(y_i\) is the current outstanding amount for asset \(i\),

  • and \(x_{i,j}\) are the \(k\) binary variables for asset \(i\) with \(j<k\).

Parameters:

growth_target (float) – target value for growth factor total outstanding amount.

Return type:

tuple[ndarray[Any, dtype[float64]], float]

Returns:

qubo matrix and its offset

calc_maximize_roc1()[source]

Calculates the to maximize ROC QUBO for variant 1.

The QUBO formulation is given by

\[QUBO(x) = -\sum_{i=1}^N\frac{r_i}{c_i\cdot y_i} \left(LB_i + \frac{UB_i-LB_i}{2^k-1}\sum_{j=0}^{k-1}2^j\cdot x_{i,j}\right),\]

where

  • \(LB_i\) is the lower bound for asset \(i\),

  • \(UB_i\) is the upper bound for asset \(i\),

  • \(k\) is the number of bits,

  • \(y_i\) is the current outstanding amount for asset \(i\),

  • \(r_i\) is the current return for asset \(i\),

  • \(c_i\) is the regulatory capital for asset \(i\),

  • and \(x_{i,j}\) are the \(k\) binary variables for asset \(i\) with \(j<k\).

Return type:

tuple[ndarray[Any, dtype[float64]], float]

Returns:

qubo matrix and its offset

calc_maximize_roc2()[source]

Calculates the to maximize ROC QUBO for variant 2.

The QUBO formulation is given by

\[ \begin{align}\begin{aligned}QUBO(x,g) &= - G_{inv}(g) \cdot \sum_{i=1}^N\frac{r_i}{y_i} \left(LB_i + \frac{UB_i-LB_i}{2^k-1}\sum_{j=0}^{k-1}2^j\cdot x_{i,j}\right),\\G_{inv}(g) &= 1 + \sum_{j=0}^{k-1} 2^{-j-1}(2^{-j-1} - 1)\cdot g_{j},\end{aligned}\end{align} \]

where

  • \(LB_i\) is the lower bound for asset \(i\),

  • \(UB_i\) is the upper bound for asset \(i\),

  • \(k\) is the number of bits,

  • \(a\) is the number of ancilla variables,

  • \(y_i\) is the current outstanding amount for asset \(i\),

  • \(r_i\) is the return for asset \(i\),

  • \(c_i\) is the regulatory capital for asset \(i\),

  • \(x_{i,j}\) are the \(k\) binary variables for asset \(i\) with \(j<k\).

  • \(g_{j}\) are the \(a\) binary ancilla variables with \(j<a\).

Return type:

tuple[ndarray[Any, dtype[float64]], float]

Returns:

qubo matrix and its offset

calc_minimize_hhi()[source]

Calculates the to minimize HHI QUBO.

The QUBO formulation is given by

\[QUBO(x) = \sum_{i=1}^N\left(LB_i + \frac{UB_i-LB_i}{2^k-1}\sum_{j=0}^{k-1}2^j\cdot x_{i,j}\right)^2,\]

where:

  • \(LB_i\) is the lower bound for asset \(i\),

  • \(UB_i\) is the upper bound for asset \(i\),

  • \(k\) is the number of bits,

  • and \(x_{i,j}\) are the \(k\) binary variables for asset \(i\) with \(j<k\).

Return type:

tuple[ndarray[Any, dtype[float64]], float]

Returns:

qubo matrix and its offset

calc_stabilize_c()[source]

Calculates the QUBO that stabilizes the growth factor in the second ROC formulation.

The QUBO formulation is given by

\[ \begin{align}\begin{aligned}QUBO(x,g) &= \left( \sum_{i=1}^N\frac{c_i}{y_i} \left(LB_i + \frac{UB_i-LB_i}{2^k-1}\sum_{j=0}^{k-1}2^j\cdot x_{i,j}\right) - G_C(g)\sum_{i=1}^N c_i \right)^2,\\G_C &= 1 + \sum_{j=0}^{k-1} 2^{-j - 1} \cdot g_j,\end{aligned}\end{align} \]

where

  • \(LB_i\) is the lower bound for asset \(i\),

  • \(UB_i\) is the upper bound for asset \(i\),

  • \(k\) is the number of bits,

  • \(a\) is the number of ancilla variables,

  • \(y_i\) is the current outstanding amount for asset \(i\),

  • \(c_i\) is the regulatory capital for asset \(i\),

  • \(x_{i,j}\) are the \(k\) binary variables for asset \(i\) with \(j<k\),

  • \(g_j\) are the \(a\) ancillary binary variables with \(j<a\).

Return type:

tuple[ndarray[Any, dtype[float64]], float]

Returns:

qubo matrix and its offset