Coverage for HARK / Labeled / agents.py: 100%

1""" 

2Agent types for labeled consumption-saving models. 

3 

4These classes combine the labeled solvers with HARK's agent framework, 

5providing complete agent types that can be instantiated and solved. 

6""" 

7 

8from __future__ import annotations 

9 

10from HARK.ConsumptionSaving.ConsIndShockModel import IndShockConsumerType 

11from HARK.ConsumptionSaving.ConsPortfolioModel import PortfolioConsumerType 

12from HARK.ConsumptionSaving.ConsRiskyAssetModel import RiskyAssetConsumerType 

13from HARK.core import make_one_period_oo_solver 

14 

15from .config import ( 

16 IND_SHOCK_CONFIG, 

17 PERF_FORESIGHT_CONFIG, 

18 PORTFOLIO_CONFIG, 

19 RISKY_ASSET_CONFIG, 

20) 

21from .solvers import ( 

22 ConsIndShockLabeledSolver, 

23 ConsPerfForesightLabeledSolver, 

24 ConsPortfolioLabeledSolver, 

25 ConsRiskyAssetLabeledSolver, 

26) 

27 

28__all__ = [ 

29 "PerfForesightLabeledType", 

30 "IndShockLabeledType", 

31 "RiskyAssetLabeledType", 

32 "PortfolioLabeledType", 

33] 

34 

35 

36class PerfForesightLabeledType(IndShockConsumerType): 

37 """ 

38 A labeled perfect foresight consumer type. 

39 

40 This agent has no uncertainty about income or interest rates. 

41 The only state variable is normalized market resources (m). 

42 

43 Uses labeled xarray data structures for solutions, enabling 

44 clear variable naming and easier manipulation of results. 

45 """ 

46 

47 default_ = { 

48 "params": PERF_FORESIGHT_CONFIG.build_params(), 

49 "solver": make_one_period_oo_solver(ConsPerfForesightLabeledSolver), 

50 "model": "ConsPerfForesight.yaml", 

51 } 

52 

53 def post_solve(self) -> None: 

54 """Skip post-solve processing (no stable points to calculate).""" 

55 pass 

56 

57 

58class IndShockLabeledType(PerfForesightLabeledType): 

59 """ 

60 A labeled consumer type with idiosyncratic income shocks. 

61 

62 This agent faces permanent and transitory shocks to income. 

63 Inherits from PerfForesightLabeledType and adds income uncertainty. 

64 

65 Uses labeled xarray data structures for solutions. 

66 """ 

67 

68 default_ = { 

69 "params": IND_SHOCK_CONFIG.build_params(), 

70 "solver": make_one_period_oo_solver(ConsIndShockLabeledSolver), 

71 "model": "ConsIndShock.yaml", 

72 } 

73 

74 

75class RiskyAssetLabeledType(IndShockLabeledType, RiskyAssetConsumerType): 

76 """ 

77 A labeled consumer type with risky asset investment. 

78 

79 This agent can only save in a risky asset that pays a stochastic return. 

80 There is no risk-free savings option. 

81 

82 Uses labeled xarray data structures for solutions. 

83 """ 

84 

85 default_ = { 

86 "params": RISKY_ASSET_CONFIG.build_params(), 

87 "solver": make_one_period_oo_solver(ConsRiskyAssetLabeledSolver), 

88 "model": "ConsRiskyAsset.yaml", 

89 } 

90 

91 

92class PortfolioLabeledType(PortfolioConsumerType): 

93 """ 

94 A labeled consumer type with optimal portfolio choice. 

95 

96 This agent can save in both a risk-free asset and a risky asset, 

97 choosing the optimal allocation between them each period. 

98 

99 Uses labeled xarray data structures for solutions. 

100 

101 Note 

102 ---- 

103 Unlike other labeled types, this class inherits directly from 

104 `PortfolioConsumerType` rather than from `IndShockLabeledType`. 

105 This is because `PortfolioConsumerType` provides essential portfolio- 

106 specific functionality (share grids, portfolio optimization methods) 

107 that would be difficult to replicate. The labeled solver handles 

108 the xarray integration while the parent class handles agent lifecycle. 

109 """ 

110 

111 default_ = { 

112 "params": PORTFOLIO_CONFIG.build_params(), 

113 "solver": make_one_period_oo_solver(ConsPortfolioLabeledSolver), 

114 "model": "ConsPortfolio.yaml", 

115 } 

116 

117 def post_solve(self) -> None: 

118 """Skip post-solve processing.""" 

119 pass