Coverage for src / cvx / markowitz / models / expected_returns.py: 100%

1# Copyright 2023 Stanford University Convex Optimization Group 

2# 

3# Licensed under the Apache License, Version 2.0 (the "License"); 

4# you may not use this file except in compliance with the License. 

5# You may obtain a copy of the License at 

6# 

7# http://www.apache.org/licenses/LICENSE-2.0 

8# 

9# Unless required by applicable law or agreed to in writing, software 

10# distributed under the License is distributed on an "AS IS" BASIS, 

11# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 

12# See the License for the specific language governing permissions and 

13# limitations under the License. 

14"""Model for expected returns.""" 

15 

16from __future__ import annotations 

17 

18from dataclasses import dataclass 

19 

20import cvxpy as cp 

21import numpy as np 

22 

23from cvx.markowitz.cvxerror import CvxError 

24from cvx.markowitz.model import Model 

25from cvx.markowitz.names import DataNames as D 

26from cvx.markowitz.types import Expressions, Matrix, Parameter, Variables # noqa: F401 

27from cvx.markowitz.utils.fill import fill_vector 

28 

29 

30@dataclass(frozen=True) 

31class ExpectedReturns(Model): 

32 """Model for expected returns.""" 

33 

34 def __post_init__(self) -> None: 

35 """Initialize expected-return parameters and uncertainty bounds.""" 

36 self.data[D.MU] = cp.Parameter( 

37 shape=self.assets, 

38 name=D.MU, 

39 value=np.zeros(self.assets), 

40 ) 

41 

42 # Robust return estimate 

43 self.parameter["mu_uncertainty"] = cp.Parameter( 

44 shape=self.assets, 

45 name="mu_uncertainty", 

46 value=np.zeros(self.assets), 

47 nonneg=True, 

48 ) 

49 

50 def estimate(self, variables: Variables) -> cp.Expression: 

51 """Return robust expected return w^T mu - mu_uncertainty^T |w|. 

52 

53 Args: 

54 variables: Optimization variables containing D.WEIGHTS. 

55 

56 Returns: 

57 A CVXPY expression for the robust expected return. 

58 """ 

59 return self.data[D.MU] @ variables[D.WEIGHTS] - self.parameter["mu_uncertainty"] @ cp.abs(variables[D.WEIGHTS]) 

60 

61 def update(self, **kwargs: Matrix) -> None: 

62 """Update expected returns and their uncertainty bounds. 

63 

64 Expected keyword arguments: 

65 D.MU: Vector of expected returns. 

66 mu_uncertainty: Nonnegative vector with element-wise uncertainty. 

67 """ 

68 exp_returns = kwargs[D.MU] 

69 self.data[D.MU].value = fill_vector(num=self.assets, x=exp_returns) 

70 

71 # Robust return estimate 

72 uncertainty = kwargs["mu_uncertainty"] 

73 if not uncertainty.shape[0] == exp_returns.shape[0]: 

74 raise CvxError("Mismatch in length for mu and mu_uncertainty") 

75 

76 self.parameter["mu_uncertainty"].value = fill_vector(num=self.assets, x=uncertainty)