portfolio_optimization.components package

This subpackage contains components used by the PortfolioOptimizer.

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

Bases: object

Decoder class for decoding samples and samplesets.

__init__(portfolio_data, k)[source]

Init for the Decoder Class.

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.

decode_sample(sample)[source]

Decodes a sample to the oustanding_future array.

Parameters:

sample (Mapping[int, int]) – Sample as returned by D-Wave.

Return type:

ndarray[Any, dtype[float64]]

Returns:

Array containing all outstanding future values.

decode_sampleset(sampleset)[source]

Efficiently decodes a sampleset create a matrix of oustanding_future values.

Each row in the matrix corresponds to a different sample in the sampleset.

Parameters:

sampleset (SampleSet) – SampleSet as returned by D-Wave.

Return type:

ndarray[Any, dtype[float64]]

Returns:

Matrix containing all outstanding future values.

class portfolio_optimization.components.PortfolioData(portfolio_dataframe, columns_rename=None)[source]

Bases: object

The PortfolioData stores the data used for portfolio optimization.

__contains__(other)[source]

Check if other is part of the dataset.

Return type:

bool

__init__(portfolio_dataframe, columns_rename=None)[source]

Creates a PortfolioData object from a pandas DataFrame.

The portfolio data is expected to contain at least the following columns names:

  • "assets": The name of the asset.

  • "outstanding_now_now": Current outstanding amount per asset.

  • "min_outstanding_future": Lower bound outstanding amount in the future per asset.

  • "max_outstanding_future": Upper bound outstanding amount in the future per asset.

  • "income_now": Current income per asset, corresponds to return multiplied by the current outstanding amount.

  • "regcap_now": Current regulatory capital per asset.

Different column names in the dataset can be used but need to be provided as a renaming dictionary to the columns_rename argument.

Parameters:
  • portfolio_dataframe (DataFrame) – Pandas DataFrame containing the portfolio data.

  • column_rename – to rename columns provided as dict with new column names as keys and to replace column name as value. Example {"outstanding_2021": "outstanding_now"}.

Raises:

ValueError if required columns are not present in dataset.

__len__()[source]

Length of the dataset.

Return type:

int

__repr__()[source]

Representation for debugging.

Return type:

str

__str__()[source]

String representation of the PortfolioData object.

Return type:

str

classmethod from_file(filename, columns_rename=None)[source]

Reads portfolio data object into PortfolioData.

The portfolio data is expected to contain at least the following columns names:

  • "assets": The name of the asset.

  • "outstanding_now_now": Current outstanding amount per asset.

  • "min_outstanding_future": Lower bound outstanding amount in the future per asset.

  • "max_outstanding_future": Upper bound outstanding amount in the future per asset.

  • "income_now": Current income per asset, corresponds to return multiplied by the current outstanding amount.

  • "regcap_now": Current regulatory capital per asset.

Different column names in the dataset can be used but need to be provided as a renaming dictionary to the columns_rename argument.

Parameters:
  • filename (str | Path) – path to portfolio data. If instead benchmark_dataset is provided, a default benchmark dataset containing 52 assets will be used.

  • column_rename – to rename columns provided as dict with new column names as keys and to replace column name as value. Example {"outstanding_2021": "outstanding_now"}.

Raises:

ValueError if required columns are not present in dataset.

Return type:

TypeVar(PortfolioDataT, bound= PortfolioData)

get_capital()[source]

Gets the capital data from the dataset.

Return type:

ndarray[Any, dtype[float64]]

Returns:

The regcap_now column from the dataset as a numpy array.

get_column(column_name)[source]

Gets the specified column from the dataset.

Parameters:

column_name (str) – Name of the column to get.

Return type:

ndarray[Any, dtype[float64]]

Returns:

The regcap_now columns from the dataset as a numpy array.

get_income()[source]

Gets the income data from the dataset.

Return type:

ndarray[Any, dtype[float64]]

Returns:

The income_now column from the dataset as a numpy array.

get_l_bound()[source]

Gets the l_bound data from the dataset.

Return type:

ndarray[Any, dtype[float64]]

Returns:

The min_outstanding_future column from the dataset as a numpy array.

get_outstanding_now()[source]

Gets the outstanding_now data from the dataset.

Return type:

ndarray[Any, dtype[float64]]

Returns:

The outstanding_now column from the dataset as a numpy array.

get_returns()[source]

Gets the returns data from the dataset.

Return type:

ndarray[Any, dtype[float64]]

Returns:

Returns is defined as income / outstanding_now

get_u_bound()[source]

Gets the u_bound data from the dataset.

Return type:

ndarray[Any, dtype[float64]]

Returns:

The max_outstanding_future column from the dataset as a numpy array.

print_portfolio_info()[source]

Prints information about portfolio data to terminal.

Return type:

None

class portfolio_optimization.components.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.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

class portfolio_optimization.components.Results(portfolio_data, provided_emission_constraints=None, provided_growth_target=None)[source]

Bases: object

Results container

__init__(portfolio_data, provided_emission_constraints=None, provided_growth_target=None)[source]

Init of Results container.

Parameters:
  • portfolio_data (PortfolioData) – the portfolio data

  • provided_emission_constraints (Optional[list[tuple[str, str, float, str]]]) – list of all the emission constraints that are provided. Each list element contains the emission_now, emission_future and reduction_percentage_target input.

  • provided_growth_target (Optional[float]) – target outstanding amount growth factor if the growth factor constraint is set, otherwise None.

__len__()[source]

Return the number of samples stored in the Results object.

Return type:

int

add_result(outstanding_future_samples)[source]

Adds a new outstanding_future data point to results container.

Parameters:

outstanding_future_samples (ndarray[Any, dtype[float64]]) – outstanding amounts in the future for each sample of the dataset.

Return type:

None

drop_duplicates()[source]

Drops duplicates in results DataFrame

Return type:

None

head(n=5)[source]

Returns first n rows of self.results_df DataFrame

Parameters:
  • selected_columns – By default all columns

  • n (int) – number of results to return

Return type:

DataFrame

slice_results(tolerance=0.0)[source]

Helper function that slices the results in two groups, those results that satisfy all constraints and those that violate at least one of the growth factor or emission constraints.

Parameters:

tolerance (float) – tolerance on how strict the constraints need to be satisfied (in percentage point). Example: if the desired target growth rate is 1.2, if the tolerance is set to 0.05 (5%). Solutions that increase outstanding amount by a factor of 1.15 are considered to satisfy the constraints given the tolerance.

Return type:

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

Returns:

Relative difference (diversification, roc) coordinates for solutions that satisfy all constraints, and for those that do not satisfy all constraints.

Raises:

ValueError – when there are no emission or growth factor constraints set.

portfolio_optimization.components.pareto_front(xvals, yvals, min_points=50, upper_right_quadrant=True)[source]

Calculates the pareto front with at least min_points data points by repeatedly creating a convex hull around data points.

Parameters:
  • xvals (ArrayLike) – x-values of data points

  • yvals (ArrayLike) – y-values of data points

  • min_points (int) – minimum number of points to be selected

  • upper_right_quadrant (bool) – If True, only show the upper right quadrant of the pareto front.

Return type:

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

Returns:

x, y values of the points that are on the pareto front

portfolio_optimization.components.plot_front(diversification_values, roc_values, color=None, label=None, c=None, vmin=None, vmax=None, alpha=None, cmap=None, ax=None)[source]

Plots a pareto front of the given data-points in a Diversification-ROC plot.

Parameters:
  • diversification_values (ArrayLike) – 1-D ArrayLike containing the x values of the plot.

  • roc_values (ArrayLike) – 1-D ArrayLike containing the y values of the plot.

  • color (Optional[str]) – Optional color to use for the points. For an overview of allowed colors see the Matplotlib Documentation. If None is given, a default color will be assigned by matplotlib. Default is None.

  • label (Optional[str]) – Label to use in the legend. If None is given, no label will be used. Default is None.

  • c (Union[_SupportsArray[dtype[Any]], _NestedSequence[_SupportsArray[dtype[Any]]], bool, int, float, complex, str, bytes, _NestedSequence[Union[bool, int, float, complex, str, bytes]], Sequence[Union[tuple[float, float, float], str, tuple[float, float, float, float], tuple[Union[tuple[float, float, float], str], float], tuple[tuple[float, float, float, float], float]]], tuple[float, float, float], tuple[float, float, float, float], tuple[Union[tuple[float, float, float], str], float], tuple[tuple[float, float, float, float], float], None]) – The marker colors as used by matplotlib.

  • vmin (Optional[float]) – min value of data range that colormap covers as used by matplotlib.

  • vmax (Optional[float]) – max value of data range that colormap covers as used by matplotlib.

  • alpha (Optional[float]) – The alpha blending value as used by matplotlib.

  • cmap (UnionType[str, Colormap, None]) – The Colormap instance or registered colormap name as used by matplotlib.

  • ax (Optional[Axes]) – Axes to plot on. If None, a new figure with one Axes will be created.

Return type:

PatchCollection

Returns:

The matplotlib PathCollection object created by scatter.

portfolio_optimization.components.plot_points(diversification_values, roc_values, color=None, label=None, c=None, vmin=None, vmax=None, alpha=None, cmap=None, ax=None)[source]

Plots the given data-points in a Diversification-ROC plot.

Parameters:
  • diversification_values (ArrayLike) – 1-D ArrayLike containing the x values of the plot.

  • roc_values (ArrayLike) – 1-D ArrayLike containing the y values of the plot.

  • color (Optional[str]) – Optional color to use for the points. For an overview of allowed colors see the Matplotlib Documentation. If None is given, a default color will be assigned by matplotlib. Default is None.

  • label (Optional[str]) – Label to use in the legend. If None is given, no label will be used. Default is None.

  • c (Union[_SupportsArray[dtype[Any]], _NestedSequence[_SupportsArray[dtype[Any]]], bool, int, float, complex, str, bytes, _NestedSequence[Union[bool, int, float, complex, str, bytes]], Sequence[Union[tuple[float, float, float], str, tuple[float, float, float, float], tuple[Union[tuple[float, float, float], str], float], tuple[tuple[float, float, float, float], float]]], tuple[float, float, float], tuple[float, float, float, float], tuple[Union[tuple[float, float, float], str], float], tuple[tuple[float, float, float, float], float], None]) – The marker colors as used by matplotlib.

  • vmin (Optional[float]) – min value of data range that colormap covers as used by matplotlib.

  • vmax (Optional[float]) – max value of data range that colormap covers as used by matplotlib.

  • alpha (Optional[float]) – The alpha blending value as used by matplotlib.

  • cmap (UnionType[str, Colormap, None]) – The Colormap instance or registered colormap name as used by matplotlib.

  • ax (Optional[Axes]) – Axes to plot on. If None, a new figure with one Axes will be created.

Return type:

PatchCollection | Any

Returns:

The matplotlib PathCollection object created by scatter.

Subpackages