JOSEcon deployment

_toc.yml

@@ -16,17 +16,8 @@
 # Learn more at https://jupyterbook.org/customize/toc.html
 
 format: jb-book
-root: README
+root: content/paper/0_paper
 parts:
-  - caption: Content
-    chapters:
-      - file: content/paper/1_intro
-      - file: content/paper/2_method
-      - file: content/paper/3_multdim
-      - file: content/paper/4_multinterp
-      - file: content/paper/5_conditions
-      - file: content/paper/6_conclusion
-      - file: content/paper/7_appendix
   - caption: Code
     chapters:
       - file: code/examples/example_ConsPensionModel_baseline

content/paper/0_paper.md

@@ -0,0 +1,20 @@
+:::{include} 1_intro.md
+:::
+
+:::{include} 2_method.md
+:::
+
+:::{include} 3_multdim.md
+:::
+
+:::{include} 4_multinterp.md
+:::
+
+:::{include} 5_conditions.md
+:::
+
+:::{include} 6_conclusion.md
+:::
+
+:::{include} 7_appendix.md
+:::

content/paper/1_intro.md

@@ -1,32 +1,7 @@
----
-# title: Introduction # a string (max 500 chars) page & project
-# description: # a string (max 500 chars) page & project
-short_title: Intro # a string (max 40 chars) page & project
-# name:  # a string (max 500 chars) page & project
-# tags:  # a list of strings page only
-# thumbnail: # a link to a local or remote image page only
-# subtitle: # a string (max 500 chars) page only
-# date: # a valid date formatted string page can override project
-# authors:  # a list of author objects page can override project
-# doi:  # a valid DOI, either URL or id page can override project
-# arxiv: # a valid arXiv reference, either URL or id page can override project
-# open_access: # boolean (true/false) page can override project
-# license: # a license object or a string page can override project
-# github: # a valid GitHub URL or owner/reponame page can override project
-# binder: # any valid URL page can override project
-# subject: # a string (max 40 chars) page can override project
-# venue: # a venue object page can override project
-# biblio: # a biblio object with various fields page can override project
-numbering:
-    enumerator: "1.%s"
----
-
 +++ {"part": "abstract"}
 
 Heterogeneous agent models with multiple decisions are often solved using inefficient grid search methods that require many evaluations and are slow. This paper provides a novel method for solving such models using an extension of the Endogenous Grid Method (EGM) that uses Gaussian Process Regression (GPR) to interpolate functions on unstructured grids. First, I propose an intuitive and strategic procedure for decomposing a problem into subproblems which allows the use of efficient solution methods. Second, using an exogenous grid of post-decision states and solving for an endogenous grid of pre-decision states that obey a first-order condition greatly speeds up the solution process. Third, since the resulting endogenous grid can often be non-rectangular at best and unstructured at worst, GPR provides an efficient and accurate method for interpolating the value, marginal value, and decision functions. Applied sequentially to each decision within the problem, the method is able to solve heterogeneous agent models with multiple decisions in a fraction of the time and with less computational resources than are required by standard methods currently used. Software to reproduce these methods is available under the [`Econ-ARK/HARK`](https://econ-ark.org/) project for the `python` programming language.
 
-+++
-
 +++ {"part": "acknowledgements"}
 
 I would like to thank Chris Carroll, Matthew White, and Simon Scheidegger for their helpful comments and suggestions. The remaining errors are my own. All figures and other numerical results were produced using the [`Econ-ARK/HARK`](https://econ-ark.org/) toolkit {cite:p}`Carroll2018`. Additional libraries used in the production of this paper include but are not limited to: [`scipy`](https://www.scipy.org/) {cite:p}`Virtanen2020`, [`numpy`](https://www.numpy.org/) {cite:p}`Harris2020`, [`numba`](https://numba.pydata.org/) {cite:p}`Lam2015`, [`cupy`](https://cupy.dev/) {cite:p}`Okuta2017`, [`scikit-learn`](https://scikit-learn.org/) {cite:p}`Pedregosa2011`, [`pytorch`](https://pytorch.org/) {cite:p}`Paszke2019`, and [`gpytorch`](https://gpytorch.ai/) {cite:p}`Gardner2018`

content/paper/2_method.md

@@ -1,25 +1,3 @@
----
-# title: The Sequential Endogenous Grid Method # a string (max 500 chars) page & project
-# description: # a string (max 500 chars) page & project
-short_title: Method # a string (max 40 chars) page & project
-# name:  # a string (max 500 chars) page & project
-# tags:  # a list of strings page only
-# thumbnail: # a link to a local or remote image page only
-# subtitle: # a string (max 500 chars) page only
-# date: # a valid date formatted string page can override project
-# authors:  # a list of author objects page can override project
-# doi:  # a valid DOI, either URL or id page can override project
-# arxiv: # a valid arXiv reference, either URL or id page can override project
-# open_access: # boolean (true/false) page can override project
-# license: # a license object or a string page can override project
-# github: # a valid GitHub URL or owner/reponame page can override project
-# binder: # any valid URL page can override project
-# subject: # a string (max 40 chars) page can override project
-# venue: # a venue object page can override project
-# biblio: # a biblio object with various fields page can override project
-numbering:
-    enumerator: "2.%s"
----
 
 (method)=
 

content/paper/3_multdim.md

@@ -1,27 +1,5 @@
----
-# title: The Sequential Endogenous Grid Method # a string (max 500 chars) page & project
-# description: # a string (max 500 chars) page & project
-short_title: MultDim # a string (max 40 chars) page & project
-# name:  # a string (max 500 chars) page & project
-# tags:  # a list of strings page only
-# thumbnail: # a link to a local or remote image page only
-# subtitle: # a string (max 500 chars) page only
-# date: # a valid date formatted string page can override project
-# authors:  # a list of author objects page can override project
-# doi:  # a valid DOI, either URL or id page can override project
-# arxiv: # a valid arXiv reference, either URL or id page can override project
-# open_access: # boolean (true/false) page can override project
-# license: # a license object or a string page can override project
-# github: # a valid GitHub URL or owner/reponame page can override project
-# binder: # any valid URL page can override project
-# subject: # a string (max 40 chars) page can override project
-# venue: # a venue object page can override project
-# biblio: # a biblio object with various fields page can override project
-numbering:
-    enumerator: "3.%s"
----
-
 (multdim)=
+
 # The EGM$^n$ in Higher Dimensions
 
 The problem in [Section %s](#method) demonstrates the simplicity of solving problems sequentially. However, as constructed, the problem has only one state variable and one post-decision state variable per stage. Can EGM$^n$ be used to solve higher dimensional problems? In short, yes, but it requires additional thought on interpolation.
@@ -31,21 +9,21 @@ The problem in [Section %s](#method) demonstrates the simplicity of solving prob
 For a demonstration, we now turn to the problem of a worker saving up for retirement. This worker must consume, save, and deposit resources into a tax-advantaged account that can not be liquidated until retirement. In the recursive problem, the worker begins a new period with a liquid account of market resources $\mRat_{t}$ and an illiquid account of retirement savings $\nRat_{t}$. The worker maximizes their utility by choosing consumption $\cRat_{t}$ and pension deposit $\dRat_{t}$. The pension deposit is set aside on a retirement account that is exposed to a risky return, while their post-consumption liquid assets accrue risk-free interest every period. The worker additionally receives an income that faces a permanent ($\PGro_{t+1}$) and a transitory ($\tShkEmp_{t+1}$) shock every period. At the age of 65, the worker is retired and their assets are liquidated, at which point the state reduces to one liquid account of market resources. The worker's recursive problem is:
 
 \begin{equation}
-    \begin{split}
-        \vFunc_{t}(\mRat_{t}, \nRat_{t}) & = \max_{\cRat_{t}, \dRat_{t}} \util(\cRat_{t}) + \DiscFac \Ex_{t}
-        \left[ \PGro_{t+1}^{1-\CRRA} \vFunc_{t+1}(\mRat_{t+1}, \nRat_{t+1}) \right] \\
-        & \text{s.t.} \quad \cRat_{t} \ge 0, \quad \dRat_{t} \ge 0 \\
-        \aRat_{t} & = \mRat_{t} - \cRat_{t} - \dRat_{t} \\
-        \bRat_{t} & = \nRat_{t} + \dRat_{t} + g(\dRat_{t}) \\
-        \mRat_{t+1} & = \aRat_{t} \Rfree / \PGro_{t+1} + \tShkEmp_{t+1} \\
-        \nRat_{t+1} & = \bRat_{t} \Risky_{t+1} / / \PGro_{t+1}
-    \end{split}
+\begin{split}
+\vFunc*{t}(\mRat*{t}, \nRat*{t}) & = \max*{\cRat*{t}, \dRat*{t}} \util(\cRat*{t}) + \DiscFac \Ex*{t}
+\left[ \PGro_{t+1}^{1-\CRRA} \vFunc_{t+1}(\mRat_{t+1}, \nRat_{t+1}) \right] \\
+& \text{s.t.} \quad \cRat*{t} \ge 0, \quad \dRat*{t} \ge 0 \\
+\aRat*{t} & = \mRat*{t} - \cRat*{t} - \dRat*{t} \\
+\bRat*{t} & = \nRat*{t} + \dRat*{t} + g(\dRat*{t}) \\
+\mRat*{t+1} & = \aRat*{t} \Rfree / \PGro*{t+1} + \tShkEmp*{t+1} \\
+\nRat*{t+1} & = \bRat*{t} \Risky*{t+1} / / \PGro*{t+1}
+\end{split}
 \end{equation}
 
 where
 
 \begin{equation}
-    \gFunc(\dRat) = \xFer \log(1+\dRat).
+\gFunc(\dRat) = \xFer \log(1+\dRat).
 \end{equation}
 
 This problem can subsequently be broken down into 3 stages: a pension deposit stage, a consumption stage, and an income shock stage.
@@ -55,34 +33,34 @@ This problem can subsequently be broken down into 3 stages: a pension deposit st
 In the deposit stage, the worker begins with market resources and a retirement savings account. The worker must maximize their value of liquid wealth $\lRat_{t}$ and retirement balance $\bRat_{t}$ by choosing a pension deposit $\dRat_{t}$, which must be positive. The retirement balance $\bRat$ is the cash value of their retirement account plus their pension deposit and an additional amount $g(\dRat_{t})$ that provides an incentive to save for retirement. As we'll see, this additional term will allow us to use the Endogenous Grid Method to solve this subproblem.
 
 \begin{equation}
-    \begin{split}
-        \vFunc_{t}(\mRat_{t}, \nRat_{t}) & = \max_{\dRat_{t}} \vOpt_{t}(\lRat_{t}, \bRat_{t}) \\
-        & \text{s.t.} \quad \dRat_{t} \ge 0 \\
-        \lRat_{t} & = \mRat_{t} - \dRat_{t} \\
-        \bRat_{t} & = \nRat_{t} + \dRat_{t} + g(\dRat_{t})
-    \end{split}
+\begin{split}
+\vFunc*{t}(\mRat*{t}, \nRat*{t}) & = \max*{\dRat*{t}} \vOpt*{t}(\lRat*{t}, \bRat*{t}) \\
+& \text{s.t.} \quad \dRat*{t} \ge 0 \\
+\lRat*{t} & = \mRat*{t} - \dRat*{t} \\
+\bRat*{t} & = \nRat*{t} + \dRat*{t} + g(\dRat*{t})
+\end{split}
 \end{equation}
 
 After making their pension decision, the worker begins their consumption stage with liquid wealth $\lRat_{t}$ and retirement balance $\bRat_{t}$. From their liquid wealth, the worker must choose a level of consumption to maximize utility and continuation value $\wFunc_{t}$. After consumption, the worker is left with post-decision states that represent liquid assets $\aRat_{t}$ and retirement balance $\bRat_{t}$, which passes through this problem unaffected because it can't be liquidated until retirement.
 
 \begin{equation}
-    \begin{split}
-        \vOpt_{t}(\lRat_{t}, \bRat_{t}) & = \max_{\cRat_{t}} \util(\cRat_{t}) + \DiscFac \wFunc_{t}(\aRat_{t}, \bRat_{t})  \\
-        & \text{s.t.} \quad \cRat_{t} \ge 0 \\
-        \aRat_{t} & = \lRat_{t} - \cRat_{t}
-    \end{split}
+\begin{split}
+\vOpt*{t}(\lRat*{t}, \bRat*{t}) & = \max*{\cRat*{t}} \util(\cRat*{t}) + \DiscFac \wFunc*{t}(\aRat*{t}, \bRat*{t}) \\
+& \text{s.t.} \quad \cRat*{t} \ge 0 \\
+\aRat*{t} & = \lRat*{t} - \cRat\_{t}
+\end{split}
 \end{equation}
 
 Finally, the post-decision value function $\wFunc_{t}$ represents the value of both liquid and illiquid account balances before the realization of uncertainty regarding the risky return and income shocks. Since we are dealing with a normalized problem, this stage handles the normalization of state variables and value functions into the next period.
 
 \begin{equation}
-    \begin{split}
-        \wFunc_{t}(\aRat_{t}, \bRat_{t}) & = \Ex_{t}
-        \left[ \PGro_{t+1}^{1-\CRRA} \vFunc_{t+1}(\mRat_{t+1}, \mRat_{t+1}) \right] \\
-        & \text{s.t.} \quad \aRat_{t} \ge 0, \quad \bRat_{t} \ge 0 \\
-        \mRat_{t+1} & = \aRat_{t} \Rfree / \PGro_{t+1} + \tShkEmp_{t+1} \\
-        \nRat_{t+1} & = \bRat_{t} \Risky_{t+1} / \PGro_{t+1}
-    \end{split}
+\begin{split}
+\wFunc*{t}(\aRat*{t}, \bRat*{t}) & = \Ex*{t}
+\left[ \PGro_{t+1}^{1-\CRRA} \vFunc_{t+1}(\mRat_{t+1}, \mRat_{t+1}) \right] \\
+& \text{s.t.} \quad \aRat*{t} \ge 0, \quad \bRat*{t} \ge 0 \\
+\mRat*{t+1} & = \aRat*{t} \Rfree / \PGro*{t+1} + \tShkEmp*{t+1} \\
+\nRat*{t+1} & = \bRat*{t} \Risky*{t+1} / \PGro*{t+1}
+\end{split}
 \end{equation}
 
 The advantage of conceptualizing this subproblem as a separate stage is that we can construct a function $\wFunc_{t}$ and use it in the prior optimization problems without having to worry about stochastic optimization and taking expectations repeatedly.
@@ -98,66 +76,66 @@ In the deposit stage, both the state variables and post-decision variables are d
 First, we can rewrite the pension deposit problem more compactly:
 
 \begin{equation}
-    \vFunc_{t}(\mRat_{t}, \nRat_{t}) = \max_{\dRat_{t}}
-    \vOpt_{t}(\mRat_{t} - \dRat_{t}, \nRat_{t} + \dRat_{t} + \gFunc(\dRat_{t}))
+\vFunc*{t}(\mRat*{t}, \nRat*{t}) = \max*{\dRat*{t}}
+\vOpt*{t}(\mRat*{t} - \dRat*{t}, \nRat*{t} + \dRat*{t} + \gFunc(\dRat\_{t}))
 \end{equation}
 
 The first-order condition is
 
 \begin{equation}
-    \vOpt_{t}^{\lRat}(\lRat_{t}, \bRat_{t})(-1) +
-    \vOpt_{t}^{\bRat}(\lRat_{t}, \bRat_{t})(1+\gFunc'(\dRat_{t})) = 0.
+\vOpt*{t}^{\lRat}(\lRat*{t}, \bRat*{t})(-1) +
+\vOpt*{t}^{\bRat}(\lRat*{t}, \bRat*{t})(1+\gFunc'(\dRat\_{t})) = 0.
 \end{equation}
 
 Rearranging this equation gives
 
 \begin{equation}
-    \gFunc'(\dRat_{t}) = \frac{\vOpt_{t}^{\lRat}(\lRat_{t},
-        \bRat_{t})}{\vOpt_{t}^{\bRat}(\lRat_{t}, \bRat_{t})} - 1
+\gFunc'(\dRat*{t}) = \frac{\vOpt*{t}^{\lRat}(\lRat*{t},
+\bRat*{t})}{\vOpt*{t}^{\bRat}(\lRat*{t}, \bRat\_{t})} - 1
 \end{equation}
 
 where
 
 \begin{equation}
-    \gFunc'(\dRat) =
-    \frac{\xFer}{1+\dRat} \qquad \gFunc'^{-1}(y) = \xFer/y - 1
+\gFunc'(\dRat) =
+\frac{\xFer}{1+\dRat} \qquad \gFunc'^{-1}(y) = \xFer/y - 1
 \end{equation}
 
 Given that $\gFunc'(\dRat)$ exists and is invertible, we can find
 
 \begin{equation}
-    \dEndFunc_{t}(\lRat_{t}, \bRat_{t}) = \gFunc'^{-1}\left(
-    \frac{\vOpt_{t}^{\lRat}(\lRat_{t},
-        \bRat_{t})}{\vOpt_{t}^{\bRat}(\lRat_{t},
-        \bRat_{t})} - 1 \right)
+\dEndFunc*{t}(\lRat*{t}, \bRat*{t}) = \gFunc'^{-1}\left(
+\frac{\vOpt*{t}^{\lRat}(\lRat*{t},
+\bRat*{t})}{\vOpt*{t}^{\bRat}(\lRat*{t},
+\bRat\_{t})} - 1 \right)
 \end{equation}
 
 Using this, we can back out $\nRat_{t}$ as
 
 \begin{equation}
-    \nEndFunc_{t}(\lRat_{t}, \bRat_{t}) = \bRat_{t} -
-    \dEndFunc_{t}(\lRat_{t}, \bRat_{t}) - \gFunc(\dEndFunc_{t}(\lRat_{t},
-        \bRat_{t}))
+\nEndFunc*{t}(\lRat*{t}, \bRat*{t}) = \bRat*{t} -
+\dEndFunc*{t}(\lRat*{t}, \bRat*{t}) - \gFunc(\dEndFunc*{t}(\lRat*{t},
+\bRat*{t}))
 \end{equation}
 
 and $\mRat_{t}$ as
 
 \begin{equation}
-    \mEndFunc_{t}(\lRat_{t}, \bRat_{t}) = \lRat_{t} +
-    \dEndFunc_{t}(\lRat_{t}, \bRat_{t})
+\mEndFunc*{t}(\lRat*{t}, \bRat*{t}) = \lRat*{t} +
+\dEndFunc*{t}(\lRat*{t}, \bRat\_{t})
 \end{equation}
 
 In sum, given an exogenous grid $(\lRat_{t}, \bRat_{t})$ we obtain the triple $\left(\mEndFunc_{t}(\lRat_{t}, \bRat_{t}), \nEndFunc_{t}(\lRat_{t}, \bRat_{t}), \dEndFunc_{t}(\lRat_{t}, \bRat_{t})\right)$, which we can use to create an interpolator for the decision rule $\dRat_{t}$.
 
 To close the solution method, the envelope conditions are
 
 \begin{equation}
-    \begin{split}
-        \vFunc_{t}^{\mRat}(\mRat_{t}, \nRat_{t}) & =
-        \vOpt_{t}^{\lRat}(\lRat_{t}, \bRat_{t}) \\
-        \vFunc_{t}^{\nRat}(\mRat_{t}, \nRat_{t}) & =
-        \vOpt_{t}^{\bRat}(\lRat_{t}, \bRat_{t})
-    \end{split}
+\begin{split}
+\vFunc*{t}^{\mRat}(\mRat*{t}, \nRat*{t}) & =
+\vOpt*{t}^{\lRat}(\lRat*{t}, \bRat*{t}) \\
+\vFunc*{t}^{\nRat}(\mRat*{t}, \nRat*{t}) & =
+\vOpt*{t}^{\bRat}(\lRat*{t}, \bRat*{t})
+\end{split}
 \end{equation}
 
 ## Unstructured Grid Interpolation
@@ -169,7 +147,7 @@ To close the solution method, the envelope conditions are
 A regular, rectilinear exogenous grid of pension balances after deposit $\bRat_{t}$ and liquid assets after consumption $\lRat_{t}$.
 ```
 
-As in [Section %s](#method), the resulting endogenous grid is not rectilinear, and in this more complex problem it is not even a regular grid. We can see in  [Figure %s](#fig:exog) that starting from a regular and rectilinear exogenous grid of liquid assets post-consumption $\lRat_{t}$ and pension balances post-deposit $\bRat_{t}$, we obtain [Figure %s](#fig:endog) which shows an irregular and unstructured endogenous grid of market resources $\mRat_{t}$ and pension balances pre-deposit $\nRat_{t}$.
+As in [Section %s](#method), the resulting endogenous grid is not rectilinear, and in this more complex problem it is not even a regular grid. We can see in [Figure %s](#fig:exog) that starting from a regular and rectilinear exogenous grid of liquid assets post-consumption $\lRat_{t}$ and pension balances post-deposit $\bRat_{t}$, we obtain [Figure %s](#fig:endog) which shows an irregular and unstructured endogenous grid of market resources $\mRat_{t}$ and pension balances pre-deposit $\nRat_{t}$.
 
 ```{figure} ../figures/PensionEndogenousGrid.*
 :name: fig:endog

content/paper/4_multinterp.md

@@ -1,25 +1,3 @@
----
-# title: The Sequential Endogenous Grid Method # a string (max 500 chars) page & project
-# description: # a string (max 500 chars) page & project
-short_title: MultInterp # a string (max 40 chars) page & project
-# name:  # a string (max 500 chars) page & project
-# tags:  # a list of strings page only
-# thumbnail: # a link to a local or remote image page only
-# subtitle: # a string (max 500 chars) page only
-# date: # a valid date formatted string page can override project
-# authors:  # a list of author objects page can override project
-# doi:  # a valid DOI, either URL or id page can override project
-# arxiv: # a valid arXiv reference, either URL or id page can override project
-# open_access: # boolean (true/false) page can override project
-# license: # a license object or a string page can override project
-# github: # a valid GitHub URL or owner/reponame page can override project
-# binder: # any valid URL page can override project
-# subject: # a string (max 40 chars) page can override project
-# venue: # a venue object page can override project
-# biblio: # a biblio object with various fields page can override project
-numbering:
-    enumerator: "4.%s"
----
 
 (multinterp)=
 # Multivariate Interpolation on Unstructured Grids