Coverage for src / cvx / risk / linalg / cholesky.py: 100%

1"""Cholesky decomposition utilities for covariance matrices. 

2 

3This module provides a function to compute the upper triangular Cholesky 

4decomposition of a positive definite covariance matrix. 

5 

6Example: 

7 Compute the Cholesky decomposition of a covariance matrix: 

8 

9 >>> import numpy as np 

10 >>> from cvx.risk.linalg import cholesky 

11 >>> # Create a positive definite matrix 

12 >>> cov = np.array([[4.0, 2.0], [2.0, 5.0]]) 

13 >>> # Compute upper triangular Cholesky factor 

14 >>> R = cholesky(cov) 

15 >>> # Verify: R.T @ R = cov 

16 >>> np.allclose(R.T @ R, cov) 

17 True 

18 

19""" 

20 

21# Copyright 2023 Stanford University Convex Optimization Group 

22# 

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

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

25# You may obtain a copy of the License at 

26# 

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

28# 

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

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

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

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

33# limitations under the License. 

34from __future__ import annotations 

35 

36import numpy as np 

37from numpy.linalg import cholesky as _cholesky 

38 

39 

40def cholesky(cov: np.ndarray) -> np.ndarray: 

41 """Compute the upper triangular part of the Cholesky decomposition. 

42 

43 This function computes the Cholesky decomposition of a positive definite matrix 

44 and returns the upper triangular matrix R such that R^T @ R = cov. 

45 

46 The Cholesky decomposition is useful in portfolio optimization because it 

47 provides an efficient way to compute portfolio risk as ||R @ w||_2, where 

48 w is the portfolio weights vector. 

49 

50 Args: 

51 cov: A positive definite covariance matrix of shape (n, n). 

52 

53 Returns: 

54 The upper triangular Cholesky factor R of shape (n, n). 

55 

56 Example: 

57 Basic usage with a simple covariance matrix: 

58 

59 >>> import numpy as np 

60 >>> from cvx.risk.linalg import cholesky 

61 >>> # Identity matrix 

62 >>> cov = np.eye(3) 

63 >>> R = cholesky(cov) 

64 >>> np.allclose(R, np.eye(3)) 

65 True 

66 

67 With a more complex covariance matrix: 

68 

69 >>> cov = np.array([[1.0, 0.5, 0.0], 

70 ... [0.5, 1.0, 0.5], 

71 ... [0.0, 0.5, 1.0]]) 

72 >>> R = cholesky(cov) 

73 >>> np.allclose(R.T @ R, cov) 

74 True 

75 

76 Note: 

77 This function returns the upper triangular factor (R), whereas 

78 numpy.linalg.cholesky returns the lower triangular factor (L). 

79 The relationship is: L @ L^T = cov and R^T @ R = cov, where R = L^T. 

80 

81 """ 

82 return _cholesky(cov).transpose()