Reorganize and rename optimal savings lectures

jstac · claude · jstac · commit 083a4f377a09 · 2025-11-24T12:52:47.000+09:00
This commit restructures the cake eating lecture series into a more coherent "Introduction to Optimal Savings" section with clearer naming and terminology. Changes: - Created new "Introduction to Optimal Savings" section in table of contents - Renamed all 6 lectures with "os" prefix for consistency: * cake_eating.md → os.md (Optimal Savings I: Cake Eating) * cake_eating_numerical.md → os_numerical.md (Optimal Savings II: Numerical Cake Eating) * cake_eating_stochastic.md → os_stochastic.md (Optimal Savings III: Stochastic Returns) * cake_eating_time_iter.md → os_time_iter.md (Optimal Savings IV: Time Iteration) * cake_eating_egm.md → os_egm.md (Optimal Savings V: The Endogenous Grid Method) * cake_eating_egm_jax.md → os_egm_jax.md (Optimal Savings VI: EGM with JAX) - Updated all lecture titles to use "Optimal Savings I-VI" naming convention - Replaced "cake eating" terminology with "optimal savings" throughout all lectures - Updated terminology in os_stochastic.md: "cake" → "wealth/harvest" to better reflect stochastic growth - Updated all cross-references across the codebase to use new filenames - Made cross-references robust to future title changes by using {doc}`filename` format 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
diff --git a/lectures/_toc.yml b/lectures/_toc.yml
@@ -72,15 +72,18 @@ parts:
   - file: jv
   - file: odu
   - file: mccall_q
+- caption: Introduction to Optimal Savings
+  numbered: true
+  chapters:
+  - file: os
+  - file: os_numerical
+  - file: os_stochastic
+  - file: os_time_iter
+  - file: os_egm
+  - file: os_egm_jax
 - caption: Household Problems
   numbered: true
   chapters:
-  - file: cake_eating
-  - file: cake_eating_numerical
-  - file: cake_eating_stochastic
-  - file: cake_eating_time_iter
-  - file: cake_eating_egm
-  - file: cake_eating_egm_jax
   - file: ifp
   - file: ifp_advanced
 - caption: LQ Control
diff --git a/lectures/ifp.md b/lectures/ifp.md
@@ -45,14 +45,14 @@ It is an essential sub-problem for many representative macroeconomic models
 * {cite}`Huggett1993`
 * etc.
 
-It is related to the decision problem in the {doc}`cake eating model <cake_eating_stochastic>` but differs in significant ways.
+It is related to the decision problem in {doc}`os_stochastic` but differs in significant ways.
 
 For example, 
 
 1. The choice problem for the agent includes an additive income term that leads to an occasionally binding constraint.
 2. Shocks affecting the budget constraint are correlated, forcing us to track an extra state variable.
 
-To solve the model we will use the endogenous grid method, which we found to be {doc}`fast and accurate <cake_eating_egm_jax>` in our investigation of cake eating.
+To solve the model we will use the endogenous grid method, which we found to be fast and accurate in {doc}`os_egm_jax`.
 
 We'll need the following imports:
 
@@ -256,7 +256,7 @@ We solve for the optimal consumption policy using time iteration and the
 endogenous grid method.
 
 Readers unfamiliar with the endogenous grid method should review the discussion
-in {doc}`cake_eating_egm`.
+in {doc}`os_egm`.
 
 ### Solution Method
 
diff --git a/lectures/ifp_advanced.md b/lectures/ifp_advanced.md
@@ -251,7 +251,7 @@ convergence (as measured by the distance $\rho$).
 ### Using an Endogenous Grid
 
 In the study of that model we found that it was possible to further
-accelerate time iteration via the {doc}`endogenous grid method <cake_eating_egm>`.
+accelerate time iteration via the {doc}`endogenous grid method <os_egm>`.
 
 We will use the same method here.
 
diff --git a/lectures/lqcontrol.md b/lectures/lqcontrol.md
@@ -57,7 +57,7 @@ In reading what follows, it will be useful to have some familiarity with
 
 * matrix manipulations
 * vectors of random variables
-* dynamic programming and the Bellman equation (see for example {doc}`this lecture <intro:short_path>` and {doc}`this lecture <cake_eating_stochastic>`)
+* dynamic programming and the Bellman equation (see for example {doc}`this lecture <intro:short_path>` and {doc}`os_stochastic`)
 
 For additional reading on LQ control, see, for example,
 
diff --git a/lectures/os.md b/lectures/os.md
@@ -9,7 +9,7 @@ kernelspec:
   name: python3
 ---
 
-# Cake Eating I: Introduction to Optimal Saving
+# Optimal Savings I: Cake Eating
 
 ```{contents} Contents
 :depth: 2
diff --git a/lectures/os_egm.md b/lectures/os_egm.md
@@ -17,7 +17,7 @@ kernelspec:
 </div>
 ```
 
-# {index}`Cake Eating V: The Endogenous Grid Method <single: Cake Eating V: The Endogenous Grid Method>`
+# {index}`Optimal Savings V: The Endogenous Grid Method <single: Optimal Savings V: The Endogenous Grid Method>`
 
 ```{contents} Contents
 :depth: 2
@@ -26,10 +26,10 @@ kernelspec:
 
 ## Overview
 
-Previously, we solved the stochastic cake eating problem using
+Previously, we solved the optimal savings problem using
 
-1. {doc}`value function iteration <cake_eating_stochastic>`
-1. {doc}`Euler equation based time iteration <cake_eating_time_iter>`
+1. {doc}`value function iteration <os_stochastic>`
+1. {doc}`Euler equation based time iteration <os_time_iter>`
 
 We found time iteration to be significantly more accurate and efficient.
 
@@ -42,7 +42,7 @@ The original reference is {cite}`Carroll2006`.
 For now we will focus on a clean and simple implementation of EGM that stays
 close to the underlying mathematics.
 
-Then, in {doc}`the next lecture <cake_eating_egm_jax>`, we will construct a fully vectorized and parallelized version of EGM based on JAX.
+Then, in {doc}`os_egm_jax`, we will construct a fully vectorized and parallelized version of EGM based on JAX.
 
 Let's start with some standard imports:
 
@@ -58,7 +58,7 @@ First we remind ourselves of the theory and then we turn to numerical methods.
 
 ### Theory
 
-We work with the model set out in {doc}`cake_eating_time_iter`, following the same terminology and notation.
+We work with the model set out in {doc}`os_time_iter`, following the same terminology and notation.
 
 The Euler equation is
 
@@ -84,15 +84,15 @@ u'(c)
 
 ### Exogenous Grid
 
-As discussed in {doc}`cake_eating_time_iter`, to implement the method on a
+As discussed in {doc}`os_time_iter`, to implement the method on a
 computer, we need numerical approximation.
 
 In particular, we represent a policy function by a set of values on a finite grid.
 
 The function itself is reconstructed from this representation when necessary,
 using interpolation or some other method.
 
-Our {doc}`previous strategy <cake_eating_time_iter>` for obtaining a finite representation of an updated consumption policy was to
+Our previous strategy in {doc}`os_time_iter` for obtaining a finite representation of an updated consumption policy was to
 
 * fix a grid of income points $\{x_i\}$
 * calculate the consumption value $c_i$ corresponding to each $x_i$ using
@@ -146,7 +146,7 @@ The name EGM comes from the fact that the grid $\{x_i\}$ is determined **endogen
 
 ## Implementation
 
-As in {doc}`cake_eating_time_iter`, we will start with a simple setting where
+As in {doc}`os_time_iter`, we will start with a simple setting where
 
 * $u(c) = \ln c$,
 * the function $f$ has a Cobb-Douglas specification, and
@@ -172,7 +172,7 @@ def σ_star(x, α, β):
     return (1 - α * β) * x
 ```
 
-We reuse the `Model` structure from {doc}`cake_eating_time_iter`.
+We reuse the `Model` structure from {doc}`os_time_iter`.
 
 ```{code-cell} python3
 from typing import NamedTuple, Callable
@@ -205,7 +205,7 @@ def create_model(u: Callable,
                  f_prime: Callable = None,
                  u_prime_inv: Callable = None) -> Model:
     """
-    Creates an instance of the cake eating model.
+    Creates an instance of the optimal savings model.
     """
     # Set up exogenous savings grid
     s_grid = np.linspace(1e-4, grid_max, grid_size)
@@ -257,7 +257,7 @@ Note the lack of any root-finding algorithm.
 ```{note}
 The routine is still not particularly fast because we are using pure Python loops.
 
-But in the next lecture ({doc}`cake_eating_egm_jax`) we will use a fully vectorized and efficient solution.
+But in the next lecture ({doc}`os_egm_jax`) we will use a fully vectorized and efficient solution.
 ```
 
 ### Testing
@@ -347,7 +347,7 @@ EGM is faster than time iteration because it avoids numerical root-finding.
 
 Instead, we invert the marginal utility function directly, which is much more efficient.
 
-In the {doc}`next lecture <cake_eating_egm_jax>`, we will use a fully vectorized
+In {doc}`os_egm_jax`, we will use a fully vectorized
 and efficient version of EGM that is also parallelized using JAX.
 
 This provides an extremely fast way to solve the optimal consumption problem we
diff --git a/lectures/os_egm_jax.md b/lectures/os_egm_jax.md
@@ -17,7 +17,7 @@ kernelspec:
 </div>
 ```
 
-# {index}`Cake Eating VI: EGM with JAX <single: Cake Eating VI: EGM with JAX>`
+# {index}`Optimal Savings VI: EGM with JAX <single: Optimal Savings VI: EGM with JAX>`
 
 ```{contents} Contents
 :depth: 2
@@ -28,7 +28,7 @@ kernelspec:
 
 In this lecture, we'll implement the endogenous grid method (EGM) using JAX.
 
-This lecture builds on {doc}`cake_eating_egm`, which introduced EGM using NumPy.
+This lecture builds on {doc}`os_egm`, which introduced EGM using NumPy.
 
 By converting to JAX, we can leverage fast linear algebra, hardware accelerators, and JIT compilation for improved performance.
 
@@ -46,11 +46,11 @@ from typing import NamedTuple
 
 ## Implementation
 
-For details on the savings problem and the endogenous grid method (EGM), please see {doc}`cake_eating_egm`.
+For details on the savings problem and the endogenous grid method (EGM), please see {doc}`os_egm`.
 
 Here we focus on the JAX implementation of EGM.
 
-We use the same setting as in {doc}`cake_eating_egm`:
+We use the same setting as in {doc}`os_egm`:
 
 * $u(c) = \ln c$,
 * production is Cobb-Douglas, and
@@ -99,7 +99,7 @@ def create_model(β: float = 0.96,
                  seed: int = 1234,
                  α: float = 0.4) -> Model:
     """
-    Creates an instance of the cake eating model.
+    Creates an instance of the optimal savings model.
     """
     # Set up exogenous savings grid
     s_grid = jnp.linspace(1e-4, grid_max, grid_size)
@@ -250,7 +250,7 @@ This speed comes from:
 ```{exercise}
 :label: cake_egm_jax_ex1
 
-Solve the stochastic cake eating problem with CRRA utility
+Solve the optimal savings problem with CRRA utility
 
 $$
     u(c) = \frac{c^{1 - \gamma} - 1}{1 - \gamma}
diff --git a/lectures/os_numerical.md b/lectures/os_numerical.md
@@ -9,15 +9,15 @@ kernelspec:
   name: python3
 ---
 
-# Cake Eating II: Numerical Methods
+# Optimal Savings II: Numerical Cake Eating
 
 ```{contents} Contents
 :depth: 2
 ```
 
 ## Overview
 
-In this lecture we continue the study of {doc}`the cake eating problem <cake_eating>`.
+In this lecture we continue the study of the problem described in {doc}`os`.
 
 The aim of this lecture is to solve the problem using numerical
 methods.
@@ -54,7 +54,7 @@ from typing import NamedTuple
 
 ## Reviewing the Model
 
-You might like to {doc}`review the details <cake_eating>` before we start.
+You might like to review the details in {doc}`os` before we start.
 
 Recall in particular that the Bellman equation is
 
@@ -402,7 +402,7 @@ These ideas will be explored over the next few lectures.
 
 Let's try computing the optimal policy.
 
-In the {doc}`first lecture on cake eating <cake_eating>`, the optimal
+In {doc}`os`, the optimal
 consumption policy was shown to be
 
 $$
@@ -477,7 +477,7 @@ However, both changes will lead to a longer compute time.
 Another possibility is to use an alternative algorithm, which offers the
 possibility of faster compute time and, at the same time, more accuracy.
 
-We explore this {doc}`soon <cake_eating_time_iter>`.
+We explore this in {doc}`os_time_iter`.
 
 
 ## Exercises
diff --git a/lectures/os_stochastic.md b/lectures/os_stochastic.md
@@ -18,39 +18,25 @@ kernelspec:
 </div>
 ```
 
-# {index}`Cake Eating III: Stochastic Dynamics <single: Cake Eating III: Stochastic Dynamics>`
+# {index}`Optimal Savings III: Stochastic Returns <single: Optimal Savings III: Stochastic Returns>`
 
 ```{contents} Contents
 :depth: 2
 ```
 
 ## Overview
 
-In this lecture, we continue our study of the cake eating problem, building on
-{doc}`Cake Eating I <cake_eating>` and {doc}`Cake Eating II <cake_eating_numerical>`.
+In this lecture, we continue our study of optimal savings problems, building on
+{doc}`os` and {doc}`os_numerical`.
 
-The key difference from the previous lectures is that the cake size now evolves
+The key difference from the previous lectures is that wealth now evolves
 stochastically.
 
-We can think of this cake as a harvest that regrows if we save some seeds.
+We can think of wealth as a harvest that regrows if we save some seeds.
 
 Specifically, if we save and invest part of today's harvest $x_t$, it grows into next
 period's harvest $x_{t+1}$ according to a stochastic production process.
 
-```{note}
-The term "cake eating" is not such a good fit now that we have a stochastic and
-potentially growing state.
-
-Nonetheless, we'll continue to refer to cake eating to maintain flow from the
-previous lectures.
-
-Soon we'll move to more ambitious optimal savings/consumption problems and adopt
-new terminology.
-
-This lecture serves as a bridge between cake eating and the more ambitious
-problems.
-```
-
 The extensions in this lecture introduce several new elements:
 
 * nonlinear returns to saving, through a production function, and
@@ -87,7 +73,7 @@ from typing import NamedTuple, Callable
 
 ## The Model
 
-```{index} single: Stochastic Cake Eating; Model
+```{index} single: Optimal Savings; Model
 ```
 
 Here we described the new model and the optimization problem.
@@ -167,7 +153,7 @@ In the present context
 
 ### The Policy Function Approach
 
-```{index} single: Stochastic Cake Eating; Policy Function Approach
+```{index} single: Optimal Savings; Policy Function Approach
 ```
 
 One way to think about solving this problem is to look for the best **policy function**.
@@ -459,7 +445,7 @@ flexibility.
 (In subsequent lectures we will focus on efficiency and speed.)
 
 We will use fitted value function iteration, which was
-already described in {doc}`cake eating <cake_eating_numerical>`.
+already described in {doc}`os_numerical`.
 
 
 ### Scalar Maximization
@@ -520,7 +506,7 @@ def create_model(u: Callable,
                  shock_size: int = 250,
                  seed: int = 1234) -> Model:
     """
-    Creates an instance of the cake eating model.
+    Creates an instance of the optimal savings model.
     """
     # Set up grid
     grid = np.linspace(1e-4, grid_max, grid_size)
@@ -778,7 +764,7 @@ The figure shows that we are pretty much on the money.
 
 ### The Policy Function
 
-```{index} single: Stochastic Cake Eating; Policy Function
+```{index} single: Optimal Savings; Policy Function
 ```
 
 The policy `v_greedy` computed above corresponds to an approximate optimal policy.
@@ -816,7 +802,7 @@ u(c) = \frac{c^{1 - \gamma}} {1 - \gamma}
 $$
 
 Maintaining the other defaults, including the Cobb-Douglas production
-function,  solve the stochastic cake eating model with this
+function,  solve the optimal savings model with this
 utility specification.
 
 Setting $\gamma = 1.5$, compute and plot an estimate of the optimal policy.
diff --git a/lectures/os_time_iter.md b/lectures/os_time_iter.md
diff --git a/lectures/wald_friedman_2.md b/lectures/wald_friedman_2.md
