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
) – APortfolioData
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.- __init__(portfolio_dataframe, columns_rename=None)[source]
Creates a
PortfolioData
object from a pandasDataFrame
.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
) – PandasDataFrame
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. –
- 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 insteadbenchmark_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
- 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
) – APortfolioData
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 variableemission_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 is1
, then one QUBO term will be added. If formulation is2
, 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 formulation2
.
- 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.
- 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
) – APortfolioData
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 variableemission_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 dataprovided_emission_constraints (
Optional
[list
[tuple
[str
,str
,float
,str
]]]) – list of all the emission constraints that are provided. Each list element contains theemission_now
,emission_future
andreduction_percentage_target
input.provided_growth_target (
Optional
[float
]) – target outstanding amount growth factor if the growth factor constraint is set, otherwise None.
- 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
- 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 pointsyvals (
ArrayLike
) – y-values of data pointsmin_points (
int
) – minimum number of points to be selectedupper_right_quadrant (
bool
) – IfTrue
, 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-DArrayLike
containing the x values of the plot.roc_values (
ArrayLike
) – 1-DArrayLike
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. IfNone
is given, a default color will be assigned bymatplotlib
. Default isNone
.label (
Optional
[str
]) – Label to use in the legend. IfNone
is given, no label will be used. Default isNone
.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 bymatplotlib
.vmin (
Optional
[float
]) – min value of data range that colormap covers as used bymatplotlib
.vmax (
Optional
[float
]) – max value of data range that colormap covers as used bymatplotlib
.alpha (
Optional
[float
]) – The alpha blending value as used bymatplotlib
.cmap (
UnionType
[str
,Colormap
,None
]) – The Colormap instance or registered colormap name as used bymatplotlib
.ax (
Optional
[Axes
]) –Axes
to plot on. IfNone
, a new figure with oneAxes
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-DArrayLike
containing the x values of the plot.roc_values (
ArrayLike
) – 1-DArrayLike
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. IfNone
is given, a default color will be assigned bymatplotlib
. Default isNone
.label (
Optional
[str
]) – Label to use in the legend. IfNone
is given, no label will be used. Default isNone
.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 bymatplotlib
.vmin (
Optional
[float
]) – min value of data range that colormap covers as used bymatplotlib
.vmax (
Optional
[float
]) – max value of data range that colormap covers as used bymatplotlib
.alpha (
Optional
[float
]) – The alpha blending value as used bymatplotlib
.cmap (
UnionType
[str
,Colormap
,None
]) – The Colormap instance or registered colormap name as used bymatplotlib
.ax (
Optional
[Axes
]) –Axes
to plot on. IfNone
, a new figure with oneAxes
will be created.
- Return type:
PatchCollection
|Any
- Returns:
The
matplotlib
PathCollection object created by scatter.
Subpackages
- portfolio_optimization.components.io module
PortfolioData
PortfolioData.__contains__()
PortfolioData.__init__()
PortfolioData.__len__()
PortfolioData.__repr__()
PortfolioData.__str__()
PortfolioData.from_file()
PortfolioData.get_capital()
PortfolioData.get_column()
PortfolioData.get_income()
PortfolioData.get_l_bound()
PortfolioData.get_outstanding_now()
PortfolioData.get_returns()
PortfolioData.get_u_bound()
PortfolioData.print_portfolio_info()
- portfolio_optimization.components.postprocess module
- portfolio_optimization.components.results module
- portfolio_optimization.components.visualization module