% !TeX spellcheck = en_GB

\documentclass[12pt,titlepage,letterpaper]{econtex}
\usepackage{econtexSetup}\usepackage{econtexShortcuts}
\usepackage{graphicx}
\usepackage{hyperref}
\newcommand{\E}{\mathbb{E}}
%\newcommand{\pd}[2]{\frac{\partial#1}{\partial#2}}

\begin{document}
\section{ConsIndShockModel.py}

Defines consumption-saving models whose agents have CRRA utility over a unitary consumption good, geometric discounting, and who face idiosyncratic shocks to income.

\subsection{Perfect Foresight}

Consider an agent with CRRA utility over consumption, who discounts future utility at a constant rate per period and has no bequest motive.  His problem can be written as:
\begin{eqnarray*}
V_t(M_t) &=& \max_{C_t} \utilFunc(C_t) + \beta \PLives_{t+1} \E [V_{t+1}(M_{t+1}) ], \\
A_t &=& M_t - C_t, \\
M_{t+1} &=& \Rfree A_t + Y_{t+1}, \\
Y_{t+1} &=& \Gamma_{t+1} Y_t, \\
\utilFunc(C) &=& \frac{C^{1-\CRRA}}{1-\CRRA}.
\end{eqnarray*}
The model can be normalized by current income (which is also permanent income in this model) by defining lower case variables as their upper case version divided by $Y_t$:
\begin{eqnarray*}
\vFunc_t(m_t) &=& \max_{c_t} \utilFunc(c_t) + \beta \PLives_{t+1} \E [\vFunc_{t+1}(m_{t+1}) ], \\
a_t &=& m_t - c_t, \\
m_{t+1} &=& (\Rfree/\Gamma_{t+1}) a_t + 1, \\
\utilFunc(c) &=& \frac{c^{1-\CRRA}}{1-\CRRA}.
\end{eqnarray*}
An individual agent's model is thus characterized by values of $\CRRA$, $\beta$, and $\Rfree$ along with sequences $\{\Gamma_t\}_{t=1}^T$ and $\{\PLives_t\}_{t=1}^T$, with $T = \infty$ possible.

The one period problem for this model is solved by the function \texttt{solveConsPerfForesight}, which creates an instance of the class \texttt{ConsPerfForesightSolver}.  The class \texttt{PerfForesightConsumerType} extends \texttt{AgentType} to represent agents in this model. The concordance between model variables and their code equivalents is as follows.

\begin{table}[h!]
\centering
\begin{tabular}{c c c}
Var & Description & Code \\
\hline
$\CRRA$ & Coefficient of relative risk aversion & \texttt{CRRA} \\
$\beta$ & Intertemporal discount factor & \texttt{DiscFac} \\
$\Rfree$ & Risk free interest factor & \texttt{Rfree} \\
$\PLives$ & Survival probability & \texttt{LivPrb} \\
$\Gamma$ & Permanent income growth factor & \texttt{PermGroFac} \\
(none) & Number of agents of this type & \texttt{Nagents}
\end{tabular}
\end{table}

These are the only six parameters that an instance of \texttt{PerfForesightConsumerType} must have in order to create an instance and its \texttt{solve} method.\footnote{The attribute \texttt{Nagents} is not needed to \texttt{solve} this type, but is instead used during simulation.  However, this attribute is used by the constructor method for this class (to set the attributes \texttt{a\_init} and \texttt{p\_init}), so it must be passed when a new instance is created.}  Note that \texttt{LivPrb} and \texttt{PermGroFac} are assumed to be time-varying, so they should be input as a list.  Each element of the \texttt{solution} attribute will be an instance of \texttt{ConsumerSolution} with the following attributes:

\begin{table}[h!]
\centering
\begin{tabular}{c c c}
Var & Description & Code \\
\hline
$\cFunc(\cdot)$ & Noramlized consumption function & \texttt{cFunc} \\
$\vFunc(\cdot)$ & Normalized value function & \texttt{vFunc} \\
$\vFunc'(\cdot)$ & Normalized marginal value function & \texttt{vPfunc} \\
$\underline{m}$ & Mininum normalized market resources & \texttt{mNrmMin} \\
$h$ & Normalized human wealth & \texttt{hNrm} \\
$\overline{\kappa}$ & Maximum marginal propensity to consume & \texttt{MPCmax} \\
$\underline{\kappa}$ & Minimum marginal propensity to consume & \texttt{MPCmin} \\
\end{tabular}
\end{table}
In the perfect foresight model, the consumption function is linear, so the maximum and minimum MPC are equal.  Each of the functions takes normalized market resources $m$ as an argument, and they only defined on the domain $m \geq \underline{m} = -h$.

\subsection{Permanent and Transitory Idiosyncratic Shocks}

Consider an agent with CRRA utility over consumption, who discounts future utility at a constant rate per period and has no bequest motive.  He foresees that he will experience shocks to his income that are fully transitory or fully permanent.  Using the normalization above, his problem can be written as:

\begin{eqnarray*}
\vFunc_t(m_t) &=& \max_{c_t} \utilFunc(c_t) + \beta \PLives_{t+1} \E [\vFunc_{t+1}(m_{t+1}) ], \\
a_t &=& m_t - c_t, \\
a_t &\geq& \underline{a}, \\
m_{t+1} &=& \Rfree/(\Gamma_{t+1} \psi_{t+1}) a_t + \theta_{t+1}, \\
\theta_t \sim F_{\theta t}, &\qquad& \psi_t \sim F_{\psi t}, \hspace{0.25cm} \E[F_{\psi t}] = 1, \\
\utilFunc(c) &=& \frac{c^{1-\CRRA}}{1-\CRRA}.
\end{eqnarray*}
That is, this agent is identical to the perfect foresight agent except that his income is subject to permanent ($\psi$) and transitory ($\theta$) shocks to income, and he might have an artificial borrowing constraint $\underline{a}$.

The one period problem for this model is solved by the function \texttt{solveConsIndShock}, which creates an instance of the class \texttt{ConsIndShockSolver}.  The class \texttt{IndShockConsumerType} extends \texttt{PerfForesightConsumerType} to represent agents in this model.  To construct an instance of this class, several additional parameters must be passed to the constructor.  Note that most of these parameters are \textit{indirect} inputs to the consumer's model: they are used to construct direct inputs to the one period problem.  The concordance between the model and code is as follows:

\begin{table}[h!]
\centering
\begin{tabular}{c c c}
Var & Description & Code \\
\hline
(none) & Minimum of ``assets above minimum'' grid & \texttt{aXtraMin} \\
(none) & Maximum of ``assets above minimum'' grid & \texttt{aXtraMax} \\
(none) & Number of points in ``assets above minimum'' grid & \texttt{aXtraCount} \\
(none) & Additional values for the ``assets above minimum'' grid & \texttt{aXtraExtra} \\
(none) & Degree of exponential nesting for assets grid & \texttt{exp\_nest} \\
$N_{\theta}$ & Number of discrete values in transitory shock distribution & \texttt{TranShkCount} \\
$N_{\psi}$ & Number of discrete values in permanent shock distribution & \texttt{PermShkCount} \\
$\sigma_\theta$ & Standard deviation of log transitory shocks & \texttt{TranShkStd} \\
$\sigma_\psi$ & Standard deviation of log permanent shocks & \texttt{PermShkStd} \\
$\mho$ & Unemployment probability in working period & \texttt{UnempPrb} \\
$\mho_{ret}$ & ``Unemployment'' probability in retirement period & \texttt{UnempPrbRet} \\
$\underline{\theta}$ & Transitory income when unemployed in working period & \texttt{IncUnemp} \\
$\underline{\theta}_{ret}$ & Transitory income when ``unemployed'' in retired period & \texttt{IncUnempRet} \\
$\tau$ & Marginal income tax rate & \texttt{tax\_rate} \\
$T_{ret}$ & Period of retirement; number of working periods & \texttt{T\_retire} \\
$\underline{a}$ & Artificial borrowing constraint & \texttt{BoroCnstArt} \\
(none) & Indicator for whether \texttt{cFunc} should use cubic splines & \texttt{CubicBool} \\
(none) & Indicator for whether \texttt{vFunc} should be computed & \texttt{vFuncBool} \\
$T$ & Total number of (non-terminal) periods in sequence & \texttt{T\_total} \\
(none) & Number of agents of this type & \texttt{Nagents}
\end{tabular}
\end{table}

The first five attributes in the table above are used to construct the ``assets above minimum'' grid \texttt{aXtraGrid}, an input for \texttt{solveConsIndShock}.\footnote{In the current configuration, the grid is multi-exponentially spaced given minimum, maximum, number of gridpoints, and degree of exponential nesting (with additional values to force into the grid with \texttt{aXtraExtra}).  It is simple to replace this grid with another by changing the function \texttt{makeAssetsGrid}.}  The next ten attributes specify an assumed form for the income distribution $(F_{\psi t}, F_{\theta t})$. Both permanent and transitory shocks are lognormally distributed, and with a point mass in the transitory distribution representing unemployment.  Further, the sequence of periods is broken into two parts, ``working'' and ``retired'' to allow for a different income process in retirement.\footnote{Permanent and transitory shocks are turned off during retirement, other than the possibility of ``unemployment'', representing (say) a temporary failure of the retirement benefit system.} The attributes \texttt{PermShkStd} and \texttt{TranShkStd} are thus lists of the (log) standard deviation of shocks period-by-period.

Like the assets grid, the specification of the income process can be changed with little difficulty.  No matter what form is used, the relevant direct input to \texttt{solveConsIndShock} is \texttt{IncomeDstn}, a finite discrete approximation to the true income process.  This attribute is specified as a list with three elements: an array of probabilities (that sum to 1), an array of permanent income shocks, and an array of transitory income shocks.

The artificial borrowing constraint imposes a restriction on assets at the end of the period; it can be set to \texttt{None} to turn off the constraint (i.e.\ only the ``natural'' borrowing constraint will be used). The attributes \texttt{CubicBool} and \texttt{vFuncBool} should be set to \texttt{True} or \texttt{False}, as their name implies.  The solver can construct a linear or cubic spline interpolation of the consumption function; cubic interpolation is slower but more accurate at any number of gridpoints.  The value function is not strictly necessary to compute during solution and carries a computational burden, so it can be turned off with \texttt{vFuncBool=False}.  The number of agents of this type \texttt{Nagents} is irrelevant during solution and is only used during simulation (when \textit{ex-post} heterogeneity emerges within the \textit{ex-ante} homogeneous type).

The \texttt{solve} method of \texttt{IndShockConsumerType} will populate the \texttt{solution} attribute with a list containing instances of \texttt{ConsumerSolution}.  Each of these instances has all the elements listed above in the perfect foresight section plus the attribute \texttt{vPPfunc} (representing $\vFunc''(m)$) if \texttt{CubicBool=True}.\footnote{\texttt{vFunc} will be a placeholder function of the class \texttt{NullFunc} if \texttt{vFuncBool=False}.}  The problem is solved using the method of endogenous gridpoints, which is explained for this model in section 5.8 of \href{http://www.econ2.jhu.edu/people/ccarroll/SolvingMicroDSOPs/}{this set of lecture notes}.

\subsection{Different Interest Rate on Borrowing vs Saving}

Consider an agent identical to the ``idiosyncratic shocks'' model above, except that his interest factor differs depending on whether he borrows or saves on net.  His problem is the same as the one above, with a simple addition:
\begin{equation*}
\Rfree = \begin{cases}
\Rfree_{boro} & \text{if  } a_t < 0 \\
\Rfree_{save} & \text{if  } a_t > 0
\end{cases}, \qquad \Rfree_{boro} \geq \Rfree_{save}.
\end{equation*}

The one period problem for this model is solved by \texttt{solveConsKinkedR}, which creates an instance of \texttt{ConsKinkedRsolver}.  The class \texttt{KinkedRconsumerType} extends \texttt{IndShockConsumerType} to represent agents in this model.  The attributes required to specify an instance of \texttt{KinkedRconsumerType} are the same as \texttt{IndShockConsumerType} except that \texttt{Rfree} \textit{should not} be included, instead replaced by values of \texttt{Rboro} and \texttt{Rsave}.  The ``kinked R'' solver is not yet compatible with cubic spline interpolation for \texttt{cFunc}; if the \texttt{solve} method is run with \texttt{CubicBool=True}, it will throw an exception.\footnote{This is an item that is ripe for development by an outside contributor.}

The \texttt{solve} method of \texttt{KinkedRconsumerType} populates the \texttt{solution} attribute with a list of \texttt{ConsumerSolution} instances, in the same format as the idiosyncratic shocks model.  The problem is solved using the method of endogenous gridpoints with \textit{two} copies of $a_t = 0$ in the grid of end-of-period states-- one for $\Rfree_{boro}$ and the other for $\Rfree_{save}$.  This generates the ``kinked'' portion of the resulting consumption function, where the consumer is unwilling to borrow and insufficiently motivated to save, so he consumes at $c_t = m_t$.

\section{ConsPrefShockModel.py}

Defines consumption-saving models whose agents have CRRA utility over a unitary consumption good, geometric discounting, who face idiosyncratic shocks to income and to their utility or preferences.

\subsection{Multiplicative Shocks to Utility}

Consider an agent with a very similar problem to that of the ``idiosyncratic shocks'' model in the preceding section, except that he receives an iid multiplicative shock to his utility at the beginning of each period, before making the consumption decision.  This model can be written in Bellman form as:

\begin{eqnarray*}
\vFunc_t(m_t,\eta_t) &=& \max_{c_t} \eta \cdot \utilFunc(c_t) + \beta \PLives_{t+1} \E [\vFunc_{t+1}(m_{t+1},\eta_{t+1}) ], \\
a_t &=& m_t - c_t, \\
a_t &\geq& \underline{a}, \\
m_{t+1} &=& \Rfree/(\Gamma_{t+1} \psi_{t+1}) a_t + \theta_{t+1}, \\
\theta_t \sim F_{\theta t}, &\qquad& \psi_t \sim F_{\psi t}, \hspace{0.25cm} \E[F_{\psi t}] = 1, \\
\utilFunc(c) &=& \frac{c^{1-\CRRA}}{1-\CRRA}, \qquad \eta_t \sim F_{\eta t}.
\end{eqnarray*}

The one period problem for this model is solved by the function \texttt{solveConsPrefShock}, which creates an instance of \texttt{ConsPrefShockSolver}.  The class \texttt{PrefShockConsumerType} is used to represent agents in this model.  The attributes required to construct an instance of this class are the same as for \texttt{IndShockConsumerType} above, but with three additions:
\begin{table}[h!]
\centering
\begin{tabular}{c c c}
Var & Description & Code \\
\hline
$N_\eta$ & Number of discrete points in ``body'' of preference shock distribution & \texttt{PrefShkCount} \\
$N_\eta^{tail}$ & Number of discrete points in ``tails'' of preference shock distribution & \texttt{PrefShk\_tail\_N} \\
$\sigma_\eta$ & Log standard deviation of multiplicative utility shocks & \texttt{PrefShkStd}
\end{tabular}
\end{table}

These attributes are indirect inputs to the problem, used during instantiation to construct the \texttt{PrefShkDstn}, an input to \texttt{solveConsPrefShock}.  The tails of the preference shock distribution matter a great deal for the accuracy of the solution and are underrepresented by the default equiprobable discrete approximation (unless a very large number of points are used).  To fix this issue, the attribute \texttt{PrefShk\_tail\_N} specifies the number of points in each ``augmented tail'' section of the preference shock discrete approximation.\footnote{See documentation for \texttt{HARKutilities.approxLognormal} for more details.}  The standard deviation of preference shocks might vary by period, so \texttt{PrefShkStd} should be input as a list.  The ``preference shock'' solver is not yet compatible with cubic spline interpolation for the consumption function and will throw an exception if \texttt{CubicBool=True}.

The \texttt{solve} method of \texttt{PrefShockConsumerType} populates the \texttt{solution} attribute with a list of \texttt{ConsumerSolution} instaces.  These single-period-solution objects have the same attributes as the ``idiosyncratic shocks'' models above, but the attribute \texttt{cFunc} is defined over the space of $(m_t,\eta_t)$ rather than just $m_t$.  The value function \texttt{vFunc} and marginal value \texttt{vPfunc}, however, are defined \textit{only} over $m_t$, as they represent expected (marginal) value \textit{just before} the preference shock $\eta_t$ is realized:\footnote{Particularly in the case of \texttt{vPfunc}, this is the object of interest for solving the preceding period.}
\begin{eqnarray*}
\overline{\vFunc}_t(m_t) &=& \int_0^\infty \vFunc(m_t,\eta)dF_{\eta t}(\eta), \\
\overline{\vFunc}_t'(m_t) &=& \int_0^\infty \vFunc'(m_t,\eta)dF_{\eta t}(\eta).
\end{eqnarray*}

\subsection{Utility Shocks and Different Interest Rates}

Consider an agent with idiosyncratic shocks to permanent and transitory income and multiplicative shocks to utility \textit{and} faces a different interest rate on borrowing vs saving.  This agent's model is identical to that of the ``preference shock'' consumer in section 2.1, with the addition of the interest rate rule from the ``kinked R'' consumer in section 1.3.

The one period problem of this combination model is solved by the function \texttt{solveConsKinkyPref}, which creates an instance of \texttt{ConsKinkyPrefSolver}.  The class \texttt{KinkyPrefConsumerType} represents agents in this model.  As you will see in \texttt{ConsPrefShockModel.py}, there is \textit{very} little new code required to program this model: the solver and consumer classes each inherit from both \texttt{KinkedR} and \texttt{PrefShock} and only need a trivial constructor function to rectify the differences between the two.  This is a good demonstration of the benefit of HARK's object-oriented approach to solution methods: it is sometimes trivial to combine two models to make a new one.

The attributes required to properly construct an instance of \texttt{KinkyPrefConsumerType} are the same as for \texttt{PrefShockConsumerType} except that (like the ``kinked R'' parent model) \texttt{Rfree} should not be replaced with \texttt{Rboro} and \texttt{Rsave}.  Like both of its parents, \texttt{KinkyPref} is not yet compatible with cubic spline interpolation of the consumption function.

\newpage

\section{ConsMarkovModel.py}

Defines consumption-saving models with a discrete state that evolves according to an exogenous Markov process.

\subsection{Markov States and Idiosyncratic Shocks}

Consider an agent with CRRA utility over consumption who geometrically discounts future utility flows and expects to experience transitory and permanent shocks to his income.  Moreover, in any given period he finds himself in exactly one of several discrete states; this state evolves from period to period according to a Markov process.  The individual's income distribution, permanent income growth rate, and interest factor might vary across states.  This agent's problem can be written in Bellman form as:
\begin{eqnarray*}
\vFunc_t(m_t,s_t) &=& \max_{c_t} \utilFunc(c_t) + \beta \PLives_{t+1} \E [\vFunc_{t+1}(m_{t+1},s_{t+1}) ], \\
a_t &=& m_t - c_t, \\
a_t &\geq& \underline{a}, \\
m_{t+1} &=& \frac{\Rfree(s_{t+1})}{\Gamma_{t+1}(s_{t+1})\psi_{t+1}} \cdot a_t + \theta_{t+1}, \\
\theta_t \sim F_{\theta t}(s_{t}), &\qquad& \psi_t \sim F_{\psi t}(s_{t}), \hspace{0.25cm} \E[F_{\psi t}(s_{t})] = 1, \\
\text{Prob}[s_{t+1}=j | s_t=i] &=& \Delta_{ij}, \\
\utilFunc(c) &=& \frac{c^{1-\CRRA}}{1-\CRRA}.
\end{eqnarray*}
The Markov matrix is $\Delta$, giving transition probabilities from current state $i$ to future state $j$.  This model is the same as the ``idiosyncratic shocks'' model of section 2.1 but for the presence of the Markov state $s_t$, so that the interest factor $\Rfree$, income distribution $(F_{\psi t},F_{\theta t})$, and permanent income growth factor $\Gamma_{t+1}$ are all functions of the Markov state, having a value for each state.

The function \texttt{solveConsMarkov} solves the one period problem of this model, creating an instance of \texttt{ConsMarkovSolver}.  The class \texttt{MarkovConsumerType} is used to represent agents in this model, extending \texttt{IndShockConsumerType}.  The attributes required to specify an instance of this class are the same as for \texttt{IndShockConsumerType} but for one addition:

\begin{table}[h!]
\centering
\begin{tabular}{c c c}
Var & Description & Code \\
\hline
$\Delta$ & Discrete state transition probability matrix & \texttt{MrkvArray}
\end{tabular}
\end{table}

The attribute \texttt{MrkvArray} is a \texttt{numpy.array} of size $(N_s,N_s)$ corresponding to the number of discrete states.\footnote{As is, \texttt{MrkvArray} is an element of \texttt{time\_inv}, so the same transition probabilities are used for each period.  However, it can be moved to \texttt{time\_vary} and specified as a list of \texttt{array}s instead.}  The attributes \texttt{Rfree}, \texttt{PermGroFac}, and \texttt{IncomeDstn} should be specified as lists\footnote{\texttt{PermGroFac} and \texttt{Rfree} can be arrays or lists.} with $N_s$ elements for each period.  Note that \texttt{MarkovConsumerType} currently has no method to automatically construct a valid \texttt{IncomeDstn}; as seen in the examples in \texttt{ConsMarkovModel.py}, the \texttt{IncomeDstn} is manually constructed in each case.\footnote{Writing a method to supersede  \texttt{IndShockConsumerType.updateIncomeProcess} for the ``Markov model'' would be a welcome contribution.}  All other attributes are specified the same as in the ``idiosyncratic shocks'' model.

When the \texttt{solve} method of a \texttt{MarkovConsumerType} is invoked, the \texttt{solution} attribute is populated with a list of \texttt{ConsumerSolution} objects, which each have the same attributes as the ``idiosyncratic shocks'' model.  However, each attribute is now a list (or array) whose elements are \textit{state-conditional} values of that object.  For example, in a model with four discrete states, each the \texttt{cFunc} attribute of each element of \texttt{solution} is a length-4 list whose elements are state-conditional consumption functions (e.g. \texttt{cFunc[2]} is the consumption function when $s_t=2$).  The ``Markov model'' is compatible with cubic spline interpolation for the consumption functions, so \texttt{CubicBool=True} will not generate an exception.  The problem is solved using the method of endogenous gridpoints, which is moderately more complicated than in the basic ``idiosyncratic shocks'' model.

\section{ConsAggShockModel.py}

Defines consumption-saving models with idiosyncratic and aggregate shocks to income.

\subsection{Idiosyncratic and Aggregate Shocks to Income}

Consider an agent with CRRA preferences over consumption who discounts future utility flows and expects to experience permanent and transitory shocks to his income.  He also believes that the market to which he supplies (a fixed amount of) labor will experience \textit{aggregate} permanent and transitory shocks to the effective productivity of labor.  The wage rate in the market is the marginal product of labor in the aggregate production function, and the interest factor is one plus the (net) marginal product of capital; assume that the ratio of aggregate capital-to-labor is a sufficient statistic for these marginal products.  Further, the agent believes that the capital-to-labor ratio evolves as a function of its current value.  This model can be written in Bellman form as:

\begin{eqnarray*}
\vFunc_t(m_t,k_t) &=& \max_{c_t} \utilFunc(c_t) + \beta \PLives_{t+1} \E [\vFunc_{t+1}(m_{t+1},k_{t+1}) ], \\
a_t &=& m_t - c_t, \\
a_t &\geq& 0, \\
m_{t+1} &=& \frac{\Rfree_{t+1}}{\Gamma_{t+1}\psi_{t+1} \Psi_{t+1}} \cdot a_t + W_{t+1} \theta_{t+1}, \\
\Rfree_{t+1} = \textbf{R}(k_{t+1}/\Theta_{t+1}), & & W_{t+1} = \textbf{W}(k_{t+1}/\Theta_{t+1}), \\
k_{t+1} &=& \textbf{k}(k_t), \\
\theta_t \sim F_{\theta t}, &\qquad& \psi_t \sim F_{\psi t}, \hspace{0.25cm} \E[F_{\psi t}] = 1, \\
\Theta_t \sim F_{\Theta}, &\qquad& \Psi_t \sim F_{\Psi}, \hspace{0.25cm} \E[F_{\Psi}] = \E[F_{\Theta}] = 1, \\
\utilFunc(c) &=& \frac{c^{1-\CRRA}}{1-\CRRA}.
\end{eqnarray*}

The objects $\textbf{R}(\cdot)$ and $\textbf{W}(\cdot)$, are functions of the (effective) capital-to-labor ratio that yield the (net) interest factor and wage rate respectively.  As noted above, these are determined by the aggregate production function and the degree of capital depreciation.  The $\texttt{k}(\cdot)$ function represents the agent's beliefs about the evolution of the capital-to-labor ratio $k_t$.  As with idiosyncratic shocks, there is an aggregate shock process $(F_{\Theta},F_{\Psi})$.

The one period problem of this model is solved by the function \texttt{solveConsAggShock}, the default value of \texttt{solveOnePeriod} for \texttt{AggShockConsumerType}.  The attributes required to specify an instance of this class are listed in the concordance below.

\begin{table}[h!]
\centering
\begin{tabular}{c c c}
Var & Description & Code \\
\hline
$\CRRA$ & Coefficient of relative risk aversion & \texttt{CRRA} \\
$\beta$ & Intertemporal discount factor & \texttt{DiscFac} \\
$\PLives$ & Survival probability & \texttt{LivPrb} \\
$\Gamma$ & Permanent income growth factor & \texttt{PermGroFac} \\
(none) & Minimum of ``assets above minimum'' grid & \texttt{aXtraMin} \\
(none) & Maximum of ``assets above minimum'' grid & \texttt{aXtraMax} \\
(none) & Number of points in ``assets above minimum'' grid & \texttt{aXtraCount} \\
(none) & Additional values for the ``assets above minimum'' grid & \texttt{aXtraExtra} \\
(none) & Degree of exponential nesting for assets grid & \texttt{exp\_nest} \\
$\{\hat{k}\}$ & Array of scaling factors for capital ratio (around SS) & \texttt{kGridBase} \\
$N_{\theta}$ & Number of discrete values in transitory shock distribution & \texttt{TranShkCount} \\
$N_{\psi}$ & Number of discrete values in permanent shock distribution & \texttt{PermShkCount} \\
$\sigma_\theta$ & Standard deviation of log transitory shocks & \texttt{TranShkStd} \\
$\sigma_\psi$ & Standard deviation of log permanent shocks & \texttt{PermShkStd} \\
$\mho$ & Unemployment probability in working period & \texttt{UnempPrb} \\
$\mho_{ret}$ & ``Unemployment'' probability in retirement period & \texttt{UnempPrbRet} \\
$\underline{\theta}$ & Transitory income when unemployed in working period & \texttt{IncUnemp} \\
$\underline{\theta}_{ret}$ & Transitory income when ``unemployed'' in retired period & \texttt{IncUnempRet} \\
$\tau$ & Marginal income tax rate & \texttt{tax\_rate} \\
$T_{ret}$ & Period of retirement; number of working periods & \texttt{T\_retire} \\
$T$ & Total number of (non-terminal) periods in sequence & \texttt{T\_total} \\
(none) & Number of agents of this type & \texttt{Nagents}
\end{tabular}
\end{table}

This list is very similar to the one for \texttt{IndShockConsumerType}, but several attributes have been removed: \texttt{Rfree} is endogenous here, while \texttt{CubicBool}, \texttt{vFuncBool}, and \texttt{BoroCnstArt} are not yet supported in the ``aggregate shocks'' model.  The only new attribute is \texttt{kGridBase}, an array of scaling factors for the (perfect foresight equivalent) steady state capital ratio; it is used to construct \texttt{kGrid}, a direct input for \texttt{solveConsAggShock}.

A new \texttt{AggShockConsumerType} with these attributes is not yet ready to solve its micro model, as it lacks several features.  After creating a valid \texttt{CobbDouglasEconomy} instance (see section 4.2), the agent type must get ``macro'' level objects from this by invoking its \texttt{getEconomyData} method with the \texttt{CobbDouglasEconomy} as the input.  This gives the agent type its interest, wage, and next-capital-ratio functions as the attributes \texttt{Rfunc}, \texttt{Wfunc}, and \texttt{kNextFunc}, its capital ratio grid \texttt{kGrid}, and reformats the \texttt{IncomeDstn} attribute as a discrete joint distribution across all four types of shocks.\footnote{As of the beta release, this method is only compatible with one period infinite horizon micro models, but this can be fixed with minimal difficulty.}

After obtaining ``macro''-level inputs to its model, an \texttt{AggShockConsumerType}'s \texttt{solve} method will populate the \texttt{solution} attribute with a list of \texttt{ConsumerSolution} instances.  Unlike the models with only idiosyncratic shocks, the one-period-solution objects have only two attributes, \texttt{cFunc} and \texttt{vPfunc}; both of these functions are defined over the space of $(m_t,k_t)$.  The model is solved using the method of endogenous gridpoints, following Kiichi Tokuoka's Mathematica code for the \href{http://www.econ2.jhu.edu/people/ccarroll/papers/cstwMPC/}{``cstwMPC'' project}.

\subsection{Cobb-Douglas Economy}

A model with ``aggregate shocks'' only makes sense if there is some market-level object that experiences these shocks.  The \texttt{CobbDouglasEconomy} class extends \texttt{Market} to represent an economy with a Cobb-Douglas production function over aggregate capital and aggregate labor\footnote{As the microeconomic model in section 4.1 assumes a fixed per capita labor supply, aggregate labor for this class is assumed constant and disappears into the background.  The HARK team welcomes contributions that extend both the micro and macro models to account for endogenous labor supply.} and permanent and transitory shocks to labor productivity.  The basic model for the Cobb-Douglas economy is:

\begin{eqnarray*}
Y &=& K^\alpha L^{1-\alpha}, \qquad k \equiv K/L,\\
W = \pd{Y}{L} &=& (1-\alpha) K^{\alpha} L^{-\alpha} = (1-\alpha) k^\alpha, \\
\rfree = \pd{Y}{K} &=& \alpha K^{\alpha-1} L^{1-\alpha} = \alpha k^{\alpha-1}, \\
\Rfree &=& 1 + \rfree - \delta.
\end{eqnarray*}

A new instance of \texttt{CobbDouglasEconomy} must have attributes listed in the table below.  The constructor for the class uses these attributes to calculate the perfect foresight steady state of the capital-to-labor ratio\footnote{If the economy were populated with perfect foresight agents with preferences given by $\beta^{PF}$ and $\CRRA^{PF}$, the steady state level of capital is where $k_{t+1} = k_t$ (when aggregate shocks are turned off as well).}, wage rate, and interest rate; the interest and wage functions; a discretization of the aggregate shock process, and an initial guess of the next-capital-ratio function.  Following Krusell and Smith (1998), we assume that the log of next period's capital ratio is a linear function of the log of this period's capital ratio.

\begin{table}[h!]
\centering
\begin{tabular}{c c c}
Var & Description & Code \\
\hline
$\alpha$ & Capital's share of output & \texttt{CapShare} \\
$\delta$ & Capital depreciation rate & \texttt{DeprFac} \\
$\sigma_\Psi$ & Standard deviation of log permanent aggregate shocks & \texttt{PermShkAggStd} \\
$\sigma_\Theta$ & Standard deviation of log transitory aggregate shocks & \texttt{TranShkAggStd} \\
$N_\Psi$ & Number of discrete values in permanent agg shock distribution & \texttt{PermShkAggCount} \\
$N_\Theta$ & Number of discrete values in transitory agg shock distribution & \texttt{TranShkAggCount} \\
$\CRRA^{PF}$ & Perfect foresight coefficient of relative risk aversion & \texttt{CRRAPF} \\
$\beta^{PF}$ & Perfect foresight intertemporal discount factor & \texttt{DiscFacPF} \\
\end{tabular}
\end{table}

After a well-formed \texttt{CobbDouglasEconomy} has been created, its \texttt{agents} attribute can be populated with one or more instances of \texttt{AggShockConsumerType} (who have taken ``macro'' level information from the \texttt{CobbDouglasEconomy}).  A history of aggregate shocks can be created by invoking the \texttt{makeAggShkHist} method.  If each element of \texttt{AggShockConsumerType} has run its \texttt{makeIncShkHist} method to create a history of idiosyncratic income shocks (for many agents in each type), then the \texttt{CobbDouglasEconomy} can invoke its \texttt{solve} method.  This will search for a general equilibrium of the model, defined as a ``dynamic rule'' for the capital ratio $\textbf{k}(k_t)$ that is \textit{consistent}: when agents believe this $\textbf{k}(k_t)$ in their microeconomic problem, and the model is simulated for many periods, the resulting history of the capital ratio is consistent with that same dynamic rule.

In the \texttt{Market} framework, the \texttt{millRule} for \texttt{CobbDouglasEconomy} gathers each agent's end-of-period normalized assets $a_t$ and permanent income $p_t$.  It aggregates wealth across all consumers into total capital, which it transforms into the capital-to-labor ratio.  It then uses the next aggregate shock values to calculate $\Rfree_t$ and $W_t$, which are distributed back to the consumers along with the aggregate shocks and new capital ratio, so that they can simulated another period.

After generating a history of several thousand periods, the \texttt{CobbDouglasEconomy} can calculate a new dynamic rule for the capital ratio with its \texttt{calcDynamics} method.  The dynamics calculator simply throws out the first 200 periods of the history and runs a one-period-lag autoregression on the log capital ratio.  This generates a new function for \texttt{kNextFunc}, which is distributed to the consumer types in \texttt{agents} to re-solve their micro models.  This process continues until successive \texttt{kNextFunc}s are sufficiently close to consider the process converged (as determined by the \texttt{tolerance} attribute).

\newpage
\section{TractableBufferStockModel.py}

Defines the ``tractable buffer stock'' model from Chris Carroll's \href{http://www.econ2.jhu.edu/people/ccarroll/public/LectureNotes/Consumption/TractableBufferStock.pdf}{lecture notes}.

\subsection{Tractable Buffer Stock}

Consider a consumer with CRRA utility who faces only a single, very specific risk: that he will become permanently unemployed and receive no income until the end of time.  Otherwise, he faces an infinite horizon problem with a steady stream of income that grows by a fixed factor each period, and earns a constant rate of return on assets retained betweed periods.  His model when still employed can be written in Bellman form as:\footnote{For technical / teaching reasons, permanent income growth while employed is ``risk compensated'' so that human wealth does not vary with the unemployment probability.}
\begin{eqnarray*}
\vFunc^e(m_t) &=& \max_{c_t} \utilFunc(c_t) + \beta  \left( (1-\mho)\vFunc^e(m^e_{t+1}) + \mho \vFunc^u(m^u_{t+1}) \right) \\
a_t &=& m_t - c_t \\
m^e_{t+1} &=& (\Rfree/\widehat{\Gamma}) a_t + 1, \qquad \widehat{\Gamma} = \Gamma/(1-\mho)\\
m^u_{t+1} &=& (\Rfree/\widehat{\Gamma}) a_t.
\end{eqnarray*}
His model while unemployed is simply:
\begin{eqnarray*}
\vFunc^u(m_t) &=& \max_{c_t} \utilFunc(c_t) + \beta  \vFunc^u(m^u_{t+1}) \\
a_t &=& m_t - c_t \\
m^u_{t+1} &=& (\Rfree/\widehat{\Gamma}) a_t.
\end{eqnarray*}

This model is solved by the class \texttt{TractableConsumerType} when its \texttt{solve()} method is invoked.  An instance of this class is specified by the five parameters in the table below:
\begin{table}[h!]
\centering
\begin{tabular}{c c c}
Var & Description & Code \\
\hline
$\CRRA$ & Coefficient of relative risk aversion & \texttt{CRRA} \\
$\beta$ & Intertemporal discount factor & \texttt{DiscFac} \\
$\Rfree$ & Interest factor on assets & \texttt{Rfree} \\
$\Gamma$ & Permanent income growth factor & \texttt{PermGroFac} \\
$\mho$ & Probability of becoming unemployed & \texttt{UnempPrb} \\
\end{tabular}
\end{table}

Unlike other models in HARK, tractable buffer stock is not solved by backward induction beginning from an initial guess of the solution.  Because of the very specific form of risk faced by the agent, it is possible to calculate\footnote{As long as the consumer is both ``return impatient'' and ``growth impatient'', else there is no steady state or no solution at all.} analytical values of the steady state $(m_t,c_t)$ and to find several derivatives of the consumption function at this point (i.e.\ the MPC, MMPC, etc).  Further, the Euler and transition equations can be inverted to yield $(m_{t-1},c_{t-1})$ as a function of $(m_t,c_t)$ conditional on being employed in both periods.  Beginning from a small perturbation along a Taylor approximation of the consumption function around the steady state, the solution method generates a sequence of ``stable arm points'' along the consumption function.  After reaching specified bounds (and appending the lower bound at $(0,0)$), the (employed) consumption function is constructed as a cubic spline interpolation.

After running the \texttt{solve} method, the \texttt{solution} attribute of a \texttt{TractableConsumerType} will have a list with a single instance of \texttt{TractableConsumerSolution}.  This object has the following attributes:

\begin{table}[h!]
\centering
\begin{tabular}{c c c}
Var & Description & Code \\
\hline
$\{m_t\}$ & List of market resources values on the stable arm & \texttt{mNrm\_list} \\
$\{c_t\}$ & List of consumption values on the stable arm & \texttt{cNrm\_list} \\
$\{\kappa_t\}$ & List of MPCs at points on the stable arm & \texttt{MPC\_list} \\
$\cFunc^e(m_t)$ & Consumption function when employed & \texttt{cFunc} \\
$\cFunc^u(m_t)$ & Consumption function when unemployed & \texttt{cFunc\_U} \\
(none) & Number of stable arm points included & \texttt{PointCount}
\end{tabular}
\end{table}

\subsection{Tractable Buffer Stock as Markov}

The tractable buffer stock model can also be solved by the standard backward induction approach if it is framed in terms of the Markov model in section 3.  There are two discrete state, \textit{employed} and \textit{unemployed}; transition probabilities from the former are $(1-\mho,\mho)$ and the latter is an absorbing state.  The interest factor and permanent income growth rate are identical in the two states, and both have degenerate income distributions: $\psi_e = \theta_e = 1$, while $\psi_u = 1$ and $\theta_u = 0$ for sure.  The model takes about 300 times longer to solve using the ``Markov formulation'' as the backshooting method, yielding a nearly identical solution.

\end{document}


% This is part of the TFTB Reference Manual.
% Copyright (C) 1996 CNRS (France) and Rice University (US).
% See the file refguide.tex for copying conditions.

\markright{fmpower}
\section*{\hspace*{-1.6cm} fmpower}

\vspace*{-.4cm}
\hspace*{-1.6cm}\rule[0in]{16.5cm}{.02cm}
\vspace*{.2cm}

{\bf \large \sf Purpose}\\
\hspace*{1.5cm}
\begin{minipage}[t]{13.5cm}
Signal with power-law frequency modulation.
\end{minipage}
\vspace*{.5cm}

{\bf \large \sf Synopsis}\\
\hspace*{1.5cm}
\begin{minipage}[t]{13.5cm}
\begin{verbatim}
[x,iflaw] = fmpower(N,k,P1)
[x,iflaw] = fmpower(N,k,P1,P2)
\end{verbatim}
\end{minipage}
\vspace*{.5cm}

{\bf \large \sf Description}\\
\hspace*{1.5cm}
\begin{minipage}[t]{13.5cm}
        {\ty fmpower} generates a signal with a
        power-law frequency modulation :
        \[x(t) = \exp(j2\pi(f_0 t + \frac{c}{1-k} |t|^{1-k})).\]

\hspace*{-.5cm}\begin{tabular*}{14cm}{p{1.5cm} p{8.5cm} c}
Name & Description & Default value\\
\hline
        {\ty N}  & number of points in time\\
        {\ty k}  & degree of the power-law ({\ty k}$\neq$1)\\
        {\ty P1} & if {\ty nargin==3, P1} is a
            vector containing the two coefficients {\ty (f0 c)} for a
            power-law instantaneous frequency (sampling frequency is set to 1).
            If {\ty nargin=4, P1} (as {\ty P2}) is a time-frequency point of the
            form {\ty (ti fi)}. {\ty ti} is in seconds and {\ty fi} is a
	    normalized frequency (between 0 and 0.5). The coefficients {\ty f0}
            and {\ty c} are then deduced such that the frequency modulation
            law fits the points {\ty P1} and {\ty P2}\\
        {\ty P2} & same as {\ty P1} if {\ty nargin=4}         & optional\\
  \hline {\ty x}  & time row vector containing the modulated signal samples\\
        {\ty iflaw} & instantaneous frequency law\\

\hline
\end{tabular*}

\end{minipage}
\vspace*{1cm}

{\bf \large \sf Example}
\begin{verbatim}
         [x,iflaw]=fmpower(200,0.5,[1 0.5],[180 0.1]);
         subplot(211); plot(real(x));
         subplot(212); plot(iflaw);
\end{verbatim}
\vspace*{.5cm}

{\bf \large \sf See Also}\\
\hspace*{1.5cm}
\begin{minipage}[t]{13.5cm}
\begin{verbatim}
gdpower, fmconst, fmlin, fmhyp, fmpar, fmodany, fmsin.
\end{verbatim}
\end{minipage}


\section{Ideals, Quotients, and Isomorphism Theorems}
\subsection{Definitions}
\begin{definition}
    Let $R,S$ be rings.
    A function $\phi:R\to S$ is called a ring homomorphism if it for any $r_1,r_2\in R$\\
    1. $\phi(r_1+r_2)=\phi(r_1)+\phi(r_2)$.\\
    2. $\phi(r_1r_2)=\phi(r_1)\phi(r_2)$.\\
    3. $\phi(1_R)=1_S$.\\
    If additionally this map is bijective, we call this an isomorphism.\\
    The kernel of $\phi$ is the set $\ker\phi=\{r\in R:\phi(r)=0_S\}$.
\end{definition}
\begin{lemma}
    A ring homomorphism $\phi:R\to S$ is injective iff $\ker\phi=\{0_R\}$.
\end{lemma}
\begin{proof}
    $\phi$ is also a group homomorphism $(R,+)\to (S,+)$.
\end{proof}
\begin{definition}
    A subset $I\subset R$ is called an ideal, written as $I\unlhd R$, if $(I,+)\le (R,+)$ and $\forall r\in R,rI\subset I$.
\end{definition}
\begin{remark}
    Note that an ideal needs not to be a subring since it might not contain $1$.
    In fact, if $1\in I$, then $\forall r\in R, r=r1\in I$, so $I=R$.
    In general, if $I$ contains a unit $u$, then $\forall r\in R,r=(ru^{-1})u\in I$, so again $I=R$.\\
    Therefore, a field can only have two ideals, $\{0\}$ and itself.
\end{remark}
An ideal $I\neq R,\{0\}$ is called proper.
\begin{lemma}
    Let $\phi:R\to S$ be a ring homomorphism, then $\ker\phi\unlhd R$.
\end{lemma}
\begin{proof}
    $\ker\phi$ is obviously an additive subgroup of $R$.
    Also $\forall r\in R,i\in I,\phi(ri)=\phi(r)\phi(i)=\phi(r)0_S=0_S\implies ri\in\ker\phi$.
    Hence $\ker\phi\unlhd R$.
\end{proof}
\begin{lemma}
    The only ideals of $\mathbb Z$ are $n\mathbb Z,n\in\mathbb Z$.
\end{lemma}
\begin{proof}
    All of them are ideals and these are all possible additive subgroups.
\end{proof}
\begin{definition}
    For $a\in R$, the ideal generated by $a$ is the ideal $(a)=\{ra:r\in R\}$.
\end{definition}
Note that $(a)$ is the smallest ideal that contains $a$.
More generally,
\begin{definition}
    For $a_1,\ldots,a_n\in R$, the ideal generated by them is the ideal $(a_1,\ldots,a_n)=\{r_1a_1+\cdots+r_na_n:r_i\in R\}$.
\end{definition}
\begin{definition}
    An ideal $I\unlhd R$ is principle if $I=(a)$ for some $a\in R$.
\end{definition}
So every ideal of $\mathbb Z$ is principle.
\begin{theorem}
    Let $I$ be an ideal of $R$, then we take the quotient $R/I$ as if they are additive groups.
    We can define the multiplication on $R/I$ by defining $(a+I)(b+I)=ab+I$ which is well-defined and makes $R/I$ a ring.
\end{theorem}
Such $R/I$ is called the quotient ring.
Note that the canonical projection (or quotient map) $\pi:R\to R/I$ becomes a ring homomorphism with kernel $I$, hence every ideal is the kernel of a homomorphism.
\begin{proof}
    If $a+I=a'+I,b+I=b'+I$, then $a-a',b-b'\in I$, so $ab-a'b'=a(b-b')+(a-a')b'\in I$, therefore $ab+I=a'b'+I$, hence this multiplication is well-defined.
    The rest follows.
\end{proof}
\begin{example}
    1. For $R=\mathbb Z$, then the quotients are $\mathbb Z/n\mathbb Z$ with modulo $n$ addition and multiplication.\\
    2. Consider the ideal generated by $X$ inside the poynomial $R[X]$, then $(X)$ consists of polynomials without a constant term.
    The quotient is then $R[X]/(X)\cong R$ with the isomorphism $r(X)\mapsto r$.\\
    3. Consider the ring of real polynomials $\mathbb R[X]$ and the ideal $(X^2+1)$, then $\mathbb R[X]/(X^2+1)=\{f(X)+(X^2+1):f(X)\in R[X]\}$.
    Now $\mathbb R$ is a field, so every nonzero element is a unit, hence we can always do division algorithm.
    So by applying this algorithm on $f(X)$, we have $\mathbb R[X]/(X^2+1)=\{a+bX+(X^2+1):f(X)\in R[X]\}$.
    Now suppose $a+bX+(X^2+1)=a'+b'X+(X^2+1)$, then $(b-b')X+(a-a')=Q(X)(X^2+1)$ for some polynomial $Q$, but by looking at the degree, we must have $Q=0$, therefore $a=a',b=b'$, so each cosets are uniquely represented like this.
    We then identify $a+bX+(X^2+1)\mapsto a+bi\in\mathbb C$, but this is a ring isomorphism, so $\mathbb R[X]/(X^2+1)\cong\mathbb C$.
\end{example}
\subsection{Isomorphism Theorems of Rings}
\begin{theorem}[(First) Isomorphism Theorem]\label{ring_iso}
    Let $\phi:R\to S$ be a ring homomorphism, then $\ker\phi$ is an ideal of $R$ and the quotient ring $R/\ker\phi$ is isomorphic to $\operatorname{Im}\phi\le S$.
\end{theorem}
\begin{proof}
    We already saw that the kernel is an ideal and the quotient as additive group is isomorphic to $\operatorname{Im}\phi$ which we know is a subgroup of $(S,+)$.
    Also $\operatorname{Im}\phi$ is closed under multiplication since $\phi(r)\phi(s)=\phi(rs)$.
    In addition $\phi(1_R)=1_S$, so it is a subring of $S$.
    Consider $\Phi:R/\ker\phi\to\operatorname{Im}\phi$ which takes a coset $r+\ker\phi$ to $\phi(r)$.
    This is well defined from results in groups.
    It is obviously also a bijection and a group homomorphism under addition.
    To check it is a ring homomorphism, we have $\Phi(1_R+\ker\phi)=\phi(1_R)=1_S$.
    Also, $\Phi((r+\ker\phi)(s+\ker\phi))=\Phi(rs+\ker\phi)=\phi(rs)=\phi(r)\phi(s)=\Phi(r+\ker\phi)\Phi(s+\ker\phi)$.
    So it is a ring isomorphism.
\end{proof}
\begin{corollary}[Second Isomorphism Theorem]
    Let $R\le S$ and $J\unlhd S$, then $R\cap I\unlhd R$ and $R+J\le S$ and
    $$R/(R\cap J)\cong (R+J)/J\le S/J$$
\end{corollary}
\begin{proof}
    $R\cap I\unlhd R$ and $R+J\le S$ are trivial.
    Now consider the map $\phi:R\to S/J$ by $\phi(r)=r+J$.
    It is obviously a well-defined ring homomorphism as the composition of the inclusion $R\to S$ and the quotient map $S\to S/J$.
    Its image is $(S+J)/J$ and its kernel is $R\cap J$.
    The result follows from Theorem \ref{ring_iso}.
\end{proof}
Analogous to the situation in groups, we have (or want to have) a bijection between certain ideals of the ring $R$ and the ideals of the quotient ring $R/I$.
Start with an ideal $K$ containing $I$, we can send it to $\{r\in R:r+I\in K\}$.
Its inverse is just $J\mapsto J/I$.
This motivates the Third Isomorphism Theorem.
\begin{corollary}[Third Isomorphism Theorem]
    Let $I,J\unlhd R$ such that $I\subset J$, then $J/I\unlhd R/I$ and
    $$(R/I)/(J/I)\cong R/J$$
\end{corollary}
\begin{proof}
    Consider $\phi:R/I\to R/J$ by $r+I\mapsto r+J$.
    Since $I\subset J$, this is well-defined and obviously a ring homomorphism with kernel $J/I$.
    Finish by Theorem \ref{ring_iso}.
\end{proof}
\begin{example}
    There is a surjective ring homomorphism $\mathbb R[X]\to\mathbb C$ by
    $$\sum_{k=0}^na_kX^k\mapsto \sum_{k=0}^na_ki^k$$
    Then the kernel, by division algorithm, would be $(X^2+1)$, hence we immediately obtain $\mathbb R[X]/(X^2+1)\cong\mathbb C$ by Thoerem \ref{ring_iso}
\end{example}
\begin{example}[Characteristic of a Ring]
    For a ring $R$, there is an unique ring homomorphism $\mathbb Z\to R$.
    The uniqueness is obvious since a ring homomorphism must map the multiplicative identity to multiplicative identity.
    The existence can be shown by simply constructing $\iota:n\mapsto 1_R+1_R+\cdots +1_R$ where there are $n$ of $1_R$'s added together.
    Similarly $\iota:-n\mapsto -(1_R+1_R+\cdots +1_R)$ where again there are $n$ of $1_R$'s in the bracket.
    So $\ker\iota\unlhd\mathbb Z$, hence $\ker\iota=n\mathbb Z$ for some $n\in\mathbb N_0$.
\end{example}
\begin{definition}
    We say $n$ is the characteristic $\operatorname{char}(R)$ of $R$.
\end{definition}
By Theorem \ref{ring_iso}, $\mathbb Z/n\mathbb Z\cong\operatorname{Im}\iota\le R$.
\begin{example}
    $\mathbb Z,\mathbb Q,\mathbb R,\mathbb C$ all have characteristic $0$, and $\mathbb Z/p\mathbb Z$ has characteristic $p$.
\end{example}


\section{Chebyshev and Lagrange interpolation}

In the following functions, the domains are defined for all $\delta>0$ or $r>0$, so in finding Chebyshev nodes for interpolation, only nodes
in this domain are filtered from a list of possibilities. Thus, when selecting $n$ nodes, we actually select more, of which the negative values are discarded.
Using the Lagrange polynomial interpolation method, these nodes are used to find an approximating polynomial.

\subsection{Interpolation of \texorpdfstring{$\phi_0,\phi_\mathrm{min}$}{}}

In Figure \ref{phi0lg} and \ref{phimlg}, 9 Chebyshev nodes were used to generate an approximating polynomial.

\begin{figure}[H]
    \centering
    \begin{minipage}{0.45\textwidth}
        \centering
        \includegraphics[scale=0.45]{plots/phi0_lagrange.pdf}
        \caption{Lagrange polynomial approximation of $\phi_0$ with equation $g$}\label{phi0lg}
    \end{minipage}\hfill
    \begin{minipage}{0.45\textwidth}
        \centering
        \includegraphics[scale=0.45]{plots/phimin_lagrange.pdf}
        \caption{Lagrange polynomial approximation of $\phi_\mathrm{min}$}\label{phimlg}
    \end{minipage}
\end{figure}

Polynomial for $\phi_0$:

\begin{equation}
    f_1(\delta)=1044\delta^{8}-4892\delta^{7}+9693\delta^{6}-10531\delta^{5}+6800\delta^{4}-2638\delta^{3}+589\delta^{2}-67\delta^{1}+3
\end{equation}

Polynomial for $\phi_\mathrm{min}$:

\begin{equation}
    f_2(\delta)=3968\delta^{8}-18749\delta^{7}+37405\delta^{6}-40874\delta^{5}+26519\delta^{4}-10327\delta^{3}+2311\delta^{2}-263\delta^{1}+11
\end{equation}

The coefficients displayed here are rounded to the nearest whole number in order to make for readable output.

\subsection{Interpolation of \texorpdfstring{$y(r)$}{}}

As shown in Figure \ref{yrpoly}, the Cheybshev node method yielded far more accurate results for the function $y(r)$, save for the initial spike/irregularity in the function when it is increasing.

\begin{figure}[H]
    \centering
    \includegraphics[scale=0.8]{plots/yr_poly.pdf}
    \caption{Lagrange polynomial approximation for $y(r)$}\label{yrpoly}
\end{figure}

The equation of the Lagrange polynomial is:
\begin{equation}
    f_3(r)=-282r^{8}+3195r^{7}-15828r^{6}+44706r^{5}-78750r^{4}+88591r^{3}-62158r^{2}+24872r^{1}-4346
\end{equation}

\subsubsection{Integral approximation for \texorpdfstring{$\frac{dr}{dt}=y(r)$}{}}

The definition given is $y(r)=\frac{dr}{dt}$. This can be rearranged to

\begin{equation}
    \frac{dr}{y(r)}=dt
\end{equation}

Taking the indefinite integral on both sides (the limit on the side with $r$ is from $r_0=1$ to $r_m$ where $y(r_m)=1|r_m > 1$ and from $0$ to some $t_f$ for the side with $t$) we get

\begin{equation}
    \int_{1}^{r_m}\frac{dr}{y(r)}=\int_0^{t_f}dt
\end{equation}

Using the approximation in Eq. 30, this becomes

\begin{equation}
    \int_{1}^{r_m}\frac{dr}{f_3(r)}=\int_0^{t_f}dt
\end{equation}

Using an optimized solver, the unknown is $t_f=4.52624262$.

\subsection{Limitations and future goals}

\begin{itemize}
    \item The NumPy Lagrange solver does not allow for specification of some tolerance $\epsilon$
    \begin{itemize}
        \item A potential solution could be to implement the Lagrange polynomial method from scratch, where a tolerance could be specified
    \end{itemize}
    \item Another interpolation routine that could be used is the Newton polynomial method, which could also be implemented manually in order to specify a tolerance
\end{itemize}


\mychapter{7}{Lesson 7} %181017

\subsubsection{\textsc{Ggm}-tree (cont'd)}

% Reminders: k is the scheme key
As stated in the previous lesson, given a \prg{} $G \in \binary^\lambda \to \binary^{2\lambda}$, we can build a function family $f_k$ by repeatedly taking halves of $G$'s images, and plugging them back into $G$. Our goal is to prove the following theorem:

\begin{theorem}
    If $G$ is a \prg, then $f_k$ is a \prf.
\end{theorem}

% AP190103: All notation is still left in an inconsistent state, it's difficult here to establish which things can go where...
\begin{proof}

    Before starting to prove the \prf-ness of $f_k$, we make a brief consideration about its time complexity: computing $f_k(x)$ consists in computing $G$ and taking half of the resulting image as many times as is the length of $x$. Since the length of $x$ is polynomial in $\lambda$, so is the number of $G$'s iterations; combine this with the fact that $G$ is itself polynomial by definition, and we conclude that $f_k$ is polynomial too.

    Having cleared any doubts about $f_k$'s time complexity, we now turn to the essential point of interest: its pseudo-randomness. The proof will proceed by induction over the length of $x$, which is also the height of the tree-like structure modeling the algorithm.

    \textbf{Base case} ($n = 1$): $f_k$'s domain is restricted to $\binary$, meaning that its images will be respectively the two halves on a single iteration of $G(k)$; they are, of course, pseudorandom by $G$'s definition:
    \[
        (f_k(0), f_k(1)) = (G_0(k), G_1(k)) \compindist U_{2\lambda}
    \]
    therefore, in this case, $F_k$ is pseudorandom.

    % AP190103: Here too...
    \textbf{Inductive step}: Let $f'_k : \binary^{n - 1} \to \binary^\lambda$ be a \prf. Define $f_k$ as follows:
    \[
        f_k : \binary^n \to \binary^\lambda : (b, x) \in \binary \times \binary^{n - 1} \mapsto G_b(f'_k(x))
    \]
    It must be proven that if $f_k'$ is a \prf, then so is $f_k$. To help ourselves, we'll define some hybrid games as usual. These are depicted in figures \ref{cryptogame:ggmhyb1} and \ref{cryptogame:ggmhyb2}.

    \begin{cryptogame}
        {ggmhyb1}
        {$\hybridg{1}[f_k](\lambda, b)$: The \ggm{} construct is put against randomly driven \prg}
        {n-th}

        \cseqchallenger{\shortstack[l]{
            $k \pickUAR \binary^\lambda$ \\
            $\overline{R} \pickUAR \mathfrak{R}(n-1, \lambda)$ \\
            $b \pickUAR \binary$
        }}

        \cseqdelay
        \cseqbeginloop
        \send{}{$r = (r_0, r_{1 \upto n})$}{}
        \receive{\shortstack[l]{
            $y_0 = G_{r_0}(f'_k(r_{1 \upto n})) = f_k(r)$ \\
            $y_1 = G_{r_0}(\overline{R}(r_{1 \upto n}))$
        }}{$y_b$}{}
        \cseqendloop
        \cseqdelay

        \send{}{$b'$}{\textsc{Output 1 iff} $b = b'$}

    \end{cryptogame}

    \begin{cryptogame}
        {ggmhyb2}
        {$\hybridg{2}[\overline{R} \circ G](\lambda, b)$: The randomly driven \prg{} against a true random function}
        {n-th}

        \cseqchallenger{\shortstack[l]{
            $\overline{R} \pickUAR \mathfrak{R}(n-1, \lambda)$ \\
            $R \pickUAR \mathfrak{R}(n, \lambda)$ \\
            $b \pickUAR \binary$
        }}

        \cseqdelay
        \cseqbeginloop
        \send{}{$r = (r_0, r_{1 \upto n})$}{}
        \receive{\shortstack[l]{
            $y_0 = G_{r_0}(\overline{R}(r_{1 \upto n}))$ \\
            $y_1 = R(r)$
        }}{$y_b$}{}
        \cseqendloop
        \cseqdelay

        \send{}{$b'$}{\textsc{Output 1 iff} $b = b'$}

    \end{cryptogame}

    We are going to prove, in the scope of a single induction step, that these hybrids bridge indistinguishability for the original game. It is all that's needed to complete the proof.

    \begin{lemma}
        $\hybridg{1}[f_k](\lambda, 0) \compindist \hybridg{1}[f_k](\lambda, 1)$
    \end{lemma}

    \begin{proof}
        Assume $\exists \distinguisher^{\textsc{n-th}} \in \ppt$ that can distinguish $f_k$ from $\overline{R} \circ G$ at the $n$-th step; then an adversary \adversary{} can use it to break in turn $f'_k$'s \prf-ness, and distinguish it from $\overline{R} \circ G$ as shown in figure \ref{cryptoredux:ggmhyb1}:

        % AP190103: It is not immediately clear by the sequence that we're simulating two games in two different "inductive" steps, instead of trying to break one standard assumption
        % The reasoning is: distinguish the hybrids, simulate the induction steps
        \begin{cryptoredux}
            {ggmhyb1}
            {Using $\distinguisher^{\textsc{n-th}}$ to break $f'_k$}
            {f'-prf}
            {n-th}

            \cseqchallenger{\shortstack[l]{
                $k \pickUAR U_{\lambda - 1}$ \\
                $\overline{R} \pickUAR \mathfrak{R}(n - 1, \lambda)$ \\
                $b \pickUAR \binary$
            }}

            \cseqbeginloop
            \return{}{$(r_0, r_{1 \dots n})$}{}

            \send{}{$r_{1 \dots n}$}{}

            \receive{\shortstack[l]{
                $z_0 = f_k'(r_{1 \dots n})$ \\
                $z_1 = \overline{R}(r_{1 \dots n})$
            }}{$z_b$}{}

            \cseqdelay

            \invoke{\shortstack[l]{
                $y_b = G_{r_0}(z_b)$  % AP190909 - IMPORTANT : Make a note here: y is either f_k or R \circ G
            }}{$y_b$}{}

            \cseqendloop

            \return{}{$b'$}{}

            \send{}{$b'$}{\textsc{Output 1 iff} $b' = b$}

        \end{cryptoredux}

    \end{proof}

    Before tackling $\hybridg{2}[\overline{R}](\lambda, b)$, it is best to introduce another lemma:

    \begin{lemma}
        If $G : \binary^\lambda \to \binary^{2 \lambda}$ is a \prg, then:
        \[
            \forall K_i \sim \unifdist(\lambda) \iid \implies (G(K_1), \dots , G(K_t)) \compindist (U_{2 \lambda}, \dots , U_{2\lambda}) \qedhere
        \]
    \end{lemma}

    \begin{proof}
        \todo{Idea: all values are independent and pseudorandom on their own, hybridize progressively...}
        % AP190909: Wait: isn't that a property of a PRG already? No, the definition states indist for a single sample, not for an arbitrary sequence; hence the idea, btw
    \end{proof}

    Now for the final lemma:

    \begin{lemma}
        $\hybridg{2}[\overline{R} \circ G](\lambda, 0) \compindist \hybridg{2}[\overline{R} \circ G](\lambda, 1)$
    \end{lemma}

    %AP190912: May need to flesh out some images here, especially a cryptoredux drawing...
    \begin{proof}

        \todo{Need figures here}

        This proof is trickier: the problem lies in the inherent difference between the task of detecting a \prg{} from that of detecting a \prf{}. The aforementioned lemma helps us with the aspect of polynomial queries on a \prg{}, bringing it in line with the \prf{} game; yet, we're far from done.

        Let's delve into the details: from \adversary's perspective, the game of distinguishing $\overline{R} \circ G$ from $R$ , where \distinguisher{} performs a number of queries $q$ polynomial in $\lambda$, is perfectly modeled by the act of distinguishing a sequence of evaluations $(G(K_1), \dots, G(K_q))$ from $(U_{2\lambda}, \dots, U_{2\lambda})$. Therefore, the game can be twisted in a way that \adversary{} receives either one of the two whole sequences beforehand, and respects the rules by sending to $D$ the right piece of information on each of its queries, in order to simulate the $\overline{R} \circ G$/$R$ game correctly.

        At this point, the simple way for A to send the right info on each query $i$ would be to check whether the query's first bit $r_0$ would be $0$ or $1$, and give back to \distinguisher{} either the first or the second half of the i-th value of the sequence he received from \challenger{}; this is exactly how \ggm{} operates. However, there's a catch: \distinguisher{} might make two queries where the r1---n parts are the same, the only difference is in the first bit: essentially, D is asking for both parts of G(r) from two distinct queries. In this case, if \adversary{} just sends the i-th value's corresponding half, the simulation would break, because the halves come from different samples.

        Thus, the adversary must keep track of which suffixes he has been already queried about, and make sure to send the value's other half (there are only two) whenever he is queried on a suffix for a second time. This final touch solves the problem of simulating the game for D, and now the task of A is changed to an equivalent one of breaking the lemma stated at the beginning.

        \todo{Prata's notes:

        Let T1, T2 be empty tables.

        Given query x input x1---n let xbar=x1---i

        if xbar notin T1 then x <-\$ binarylambda and add k\_xbar to T2

        if xbar in T2 let k\_xbar = T2[T1[xbar]]

        output y = G\_x\_n(g\_x\_n-1(...G\_x\_i+1(k\_xbar)))

        H\_0: GGM tree

        H\_n: random function

        exploit lemma prg => prf
        }

    \end{proof}

    In the end the hybrids are proven to mutually indistinguishable, therefore the inductive step is correct, proving the theorem.

\end{proof}

\section{\textsc{Cpa}-security}

Now it's time to define a stronger notion of security, which is widely used in cryptology for first assessments of cryptographic strength. Let $\Pi := (\Enc, \Dec)$ be a \ske{} scheme, and consider the game depicted in figure \ref{cryptogame:cpadef}. Observe that this time, the adversary can ``query'' the challenger for the ciphertexts of any messages of his choice, with the only reasonable restriction that the query amount must be polynomially bound by $\lambda$. This kind of game/attack is called the \emph{Chosen Plaintext Attack}, because of the adversary's capability of obtaining ciphertexts from messages. The usual victory conditions found in n-time security games, which are based on ciphertext distinguishability, apply.

\begin{cryptogame}
    {cpadef}
    {The \cpa-security game: $\cryptog{cpa}(\lambda, b)$}
    {cpa}

    \cseqchallenger{$k \pickUAR \binary^\lambda$}

    \cseqbeginloop
    \send{}{$m$}{}
    \receive{$c \pickUAR \Enc(k, m)$}{$c$}{}
    \cseqendloop

    \cseqdelay

    \send{}{$m_0^*, m_1^*$}{}
    \receive{\shortstack[l]{
        $b \pickUAR \binary$ \\
        $c^* \pickUAR \Enc(k, m_b^*)$
    }}{$c^*$}{}

    \cseqdelay

    \cseqbeginloop
    \send{}{$m$}{}
    \receive{$c \pickUAR \Enc(k, m)$}{$c$}{}
    \cseqendloop

    \cseqdelay

    \send{}{$b'$}{\textsc{Output 1 iff} $b' = b$}

\end{cryptogame}

\begin{definition}
    A scheme is \cpa-secure if $\cryptog{cpa}(\lambda, 0) \compindist \cryptog{cpa}(\lambda, 1)$
\end{definition}

Having given this definition of security, recall the $\Pi_\oplus$ scheme defined in the previous lesson. It is easy to see that $\Pi_\oplus$ is not \cpa-secure for the same reasons that it is not computationally 2-time secure; however this example sheds some new light about a deeper problem:

%AP181230: Refer to page 72 of Katz-Lindell for a good explanation
\begin{observation}
    No deterministic scheme can achieve \cpa-security.
\end{observation}

This is true, because nothing prevents the adversary from asking the challenger to encrypt either $m_0$ or $m_1$, or even both, before starting the actual challenge; just as in the 2-time case for $\Pi_\oplus$, he will know the messages' ciphertexts in advance, so he will be able to tell which message the challenger has encrypted every time. The solution for obtaining a \cpa-secure encryption scheme consists of returning different ciphertexts for the same message, even better if they look random. This can be achieved by using \prf{}s.

Consider the following \ske{} scheme $\Pi_{f_k}$, where $f_k$ is a \prf{} structured as follows:

\begin{itemize}
    \item $\Enc(k, m) = (c_1, c_2) = (r, f_k(r) \oplus m)$, where $k \pickUAR \binary^\lambda$ and $r \pickUAR \binary^n$

    \item $\Dec(k, (c_1, c_2)) = f_k(c_1) \oplus c_2$
\end{itemize}

Observe that the random value $r$ is part of the ciphertext, making it long $n+l$ bits; also more importantly, the adversary can and will always see $r$. The key $k$ though, which gives a \textit{flavour} to the \prf, is still secret.

\begin{theorem} \label{thm:prfcpa}
    If $f_k$ is a \prf, then $\Pi_{f_k}$ is \cpa-secure.
\end{theorem}

\begin{proof}
    We have to prove that $\cryptog{cpa}[\Pi_{f_k}](\lambda, 0) \compindist \cryptog{cpa}[\Pi_{f_k}](\lambda, 1)$; to this end, the hybrid argument will be used. Let the first hybrid $\hybridg{0}$ be the original game, the second hybrid $\hybridg{1}$ will have a different encryption routine:

    \begin{itemize}
        \item $r \pickUAR \binary^n$
        \item $R \pickUAR \mathfrak{R}(n, l)$
        \item $c = (r, R(r) \oplus m)$, where $m$ is the plaintext to be encrypted
    \end{itemize}

    and then the last hybrid $\hybridg{2}$ will simply output $(r_1, r_2) \pickUAR U_{n + l}$.

    \begin{lemma}
        $\forall b \in \binary \implies \hybridg{0}(\lambda, b) \compindist \hybridg{1}(\lambda, b)$.
    \end{lemma}

    \begin{proof}
        As usual, the proof is by reduction: suppose there exists a distinguisher \distinguisher{} capable of telling the two hybrids apart; then \distinguisher{} can be used to break $f_k$'s property of being a \prf. The way to use \distinguisher{} is to make it play a \cpa-like game, as shown in figure \ref{cryptoredux:prfcpa}\footnotemark, where the adversary attempting to break $f_k$ decides which message to encrypt between $m_0$ and $m_1$ beforehand, and checks whether it guesses which message has been encrypted. Either way, the adversary can get a sensible probability gain in guessing if the received values from the challenger were random, or generated by $f_k$. Thus, assuming such \distinguisher{} exists, \adversary{} can efficiently break $f_k$, contradicting its \prf-ness.

        \footnotetext{An observant student may notice a striking similarity with a previously exposed reduction in figure \ref{cryptoredux:xorotprg}}

        % AP190101: Potrei includere una definizione alternativa di prf più su, in modo tale che questa riduzionie sia un po' più chiara

        \begin{cryptoredux}
            {prfcpa}
            {Breaking a \prf, for fixed message choice of $m_0$}
            {prf}
            {cpa}

            \cseqchallenger{\shortstack[l]{
                $k \pickUAR \binary^\lambda$ \\
                $R \pickUAR \mathfrak{R}(n, l)$ \\
                $b \pickUAR \binary$
            }}

            \cseqbeginloop
            \return{}{$m$}{}
            \send{$r \pickUAR \binary^n$}{$r$}{}
            \receive{\shortstack[l]{
                $z_0 \pickUAR f_k(r)$ \\
                $z_1 \pickUAR R(r)$
            }}{$z_b$}{}
            \invoke{$c = (r, z_b \oplus m)$}{$c$}{}
            \cseqendloop

            \cseqdelay

            \return{}{$m_0^*, m_1^*$}{}
            \send{$r^* \pickUAR \binary^n$}{$r^*$}{}
            \receive{\shortstack[l]{
                $z_0^* \pickUAR f_k(r)$ \\
                $z_1^* \pickUAR R(r)$
            }}{$z_b^*$}{}
            \invoke{$c^* = (r^*, z_b^* \oplus m_0^*)$}{$c^*$}{}

            \cseqdelay

            \cseqbeginloop
            \return{}{$m$}{}
            \send{$r \pickUAR \binary^n$}{$r$}{}
            \receive{\shortstack[l]{
                $z_0 \pickUAR f_k(r)$ \\
                $z_1 \pickUAR R(r)$
            }}{$z_b$}{}
            \invoke{$c = (r, z_b \oplus m)$}{$c$}{}
            \cseqendloop

            \cseqdelay

            \return{}{$b'$}{}

            \cseqdelay

            \send{$b'' = \begin{cases}
                0 &\textsc{iff } b' = 0 \\
                1 &\textsc{else}
            \end{cases}$
            }{$b''$}{\textsc{Output 1 iff} $b'' = b$}

        \end{cryptoredux}

    \end{proof}

    \begin{lemma}
        $\forall b \in \binary \implies \hybridg{1}(\lambda, b) \compindist \hybridg{2}(\lambda, b)$.
    \end{lemma}

    \begin{proof}
        Firstly, it can be safely assumed that any ciphertext $(r_i, R(r_i) \oplus m_b)$ distributes equivalently with its own sub-value $R(r_i)$, because of $R$'s true randomness, and independency from $m_b$.

        %AP190102: An image visualizing the repeat event might be very useful
        Having said that, the two hybrids apparently distribute uniformly, making them perfectly equivalent; however there is a caveat: if both games are run and one value $\overline{r}$ is queried twice in both runs, then on the second query the adversary will receive the same image in $\hybridg{1}$, but almost certainly a different one in $\hybridg{2}$. This is because the first hybrid uses a function, which is deterministic by its nature, whereas the image in the second hybrid is picked completely randomly from the codomain. Nevertheless, this sneaky issue about "collisions" can be proven to happen with negligible probability.

        Call \textsc{Repeat} this collision event on $\overline{r}$ between 2 consecutive games. Then:

        % AP190102: Could use some clarifications? Especially about what the indices represent
        \begin{align*}
        \Pr[\textsc{Repeat}] &= \Pr[\exists i, j \in q \text{ such that } r_i = r_j] \\
            &\leq \sum_{i \neq j} \Pr[r_i=r_j] \\
            &= Col(U_n) \\
            &= \sum_{i \neq j} \sum_{e \in \binary^n} \Pr[r_1 = r_2 = e] \\
            &= \sum_{i \neq j} \sum_{e \in \binary^n} \Pr[r = e]^{2} \\
            &= \binom{q}{2} 2^{n} \frac{1}{2^{2n}} \\
            &= \binom{q}{2} 2^{-n} \\
            &\leq q^{2}2^{-n} \in \negl{\lambda}
        \end{align*}

        which proves that the \textsc{Repeat} influences negligibly on the two hybrids' equivalence. Thus $\hybridg{1}(\lambda, b) \compindist \hybridg{2}(\lambda, b)$\footnotemark.

        \footnotetext{Do note that the hybrids lose their originally supposed perfect equivalence ($\hybridg{1}(\lambda, b) \equiv \hybridg{2}(\lambda, b)$) because of the \textsc{Repeat} event. Nevertheless, the lemma is still proven because it includes computational bounds into \adversary}
    \end{proof}

    With the above lemmas, and observing that $\hybridg{2}(\lambda, 0) \equiv \hybridg{2}(\lambda, 1)$, we can reach the conclusion that $\hybridg{0}(\lambda, 0) \compindist \hybridg{0}(\lambda, 1)$, which is what we wanted to demonstrate.

\end{proof}


\documentclass[12pt]{article}
\usepackage{amsfonts}
\usepackage{bm}

% symbol used for sqrt(-1)
\newcommand{\Ci}{{\rm i}}

\newcommand{\C}{\mathbb{C}}
\newcommand{\R}{\mathbb{R}}

\newcommand{\code}[1]{{\tt{#1}}}

\newcommand{\boost}[1][]{{\ensuremath{ {\bf H}{#1}_{\bm{\hat m}}(\beta) }}}
\newcommand{\rotat}[1][]{{\ensuremath{ {\bf U}{#1}_{\bm{\hat n}}(\phi) }}}

\newcommand{\pauli}[1]{\ensuremath{ {\bm\sigma}_{\rm #1} }}

\newcommand{\pdi}[2]{\ensuremath{ {{\delta {#2}}\over{\delta {#1}}} }}

\begin{document}

\section{Quaternion Differentiation}

A quaternion, $\bm{H}$, may be represented by the linear combination,
\begin{equation}
\bm{H}=\sum_{i=0}^3 h_i\pauli{i}
\end{equation}
where:
\begin{equation}\label{eqn:properties}
\pauli{i}^2 = \pauli{i}\pauli{j}\pauli{k} = -\pauli{0},
\end{equation}
and $\{i,j,k\}$ is chosen from cyclic permutations of $\{1,2,3\}$.
A quaternion function, $\bm{F}(\bm{H})$, may then be written as
\begin{equation}
\bm{F}(\bm{H})=\sum_{i=0}^3 f_i(h_0,h_1,h_2,h_3)\pauli{i}
\end{equation}
If $\bm{F}(\bm{H})$ is single-valued function of $\bm{H}$, the derivative
of $\bm{F}(\bm{H})$ is defined as
\begin{equation}
\bm{F}^\prime(\bm{H}) = \lim_{\bm{\Delta H}\to0}
	{ {\bm{F}(\bm{H}+\bm{\Delta H}) - \bm{F}(\bm{H})}\over{\bm{\Delta H}} }
\end{equation}
provided that the limit exists independent of the manner in which
$\bm{\Delta H}\to0$.  Consider four possible ways that $\bm{\Delta H}$ may
approach zero, in which all but one of $\Delta h_i$ equals zero.  The
four cases may be written as:
\begin{equation}
\bm{F}^\prime(\bm{H})_j = \sum_{i=0}^3
{ {\delta{f_i}\pauli{i}}\over{\delta{h_j}\pauli{j}} }
\end{equation}
which can be expanded to produce
\begin{eqnarray}
\bm{F}^\prime(\bm{H})_0 =
  { {\delta{f_0}}\over{\delta{h_0}} }\pauli{0}
+ { {\delta{f_1}}\over{\delta{h_0}} }\pauli{1}
+ { {\delta{f_2}}\over{\delta{h_0}} }\pauli{2}
+ { {\delta{f_3}}\over{\delta{h_0}} }\pauli{3} \\
\bm{F}^\prime(\bm{H})_1 =
  { {\delta{f_1}}\over{\delta{h_1}} }\pauli{0}
- { {\delta{f_0}}\over{\delta{h_1}} }\pauli{1}
- { {\delta{f_3}}\over{\delta{h_1}} }\pauli{2}
+ { {\delta{f_2}}\over{\delta{h_1}} }\pauli{3} \\
\bm{F}^\prime(\bm{H})_2 =
  { {\delta{f_2}}\over{\delta{h_2}} }\pauli{0}
+ { {\delta{f_3}}\over{\delta{h_2}} }\pauli{1}
- { {\delta{f_0}}\over{\delta{h_2}} }\pauli{2}
- { {\delta{f_1}}\over{\delta{h_2}} }\pauli{3} \\
\bm{F}^\prime(\bm{H})_3 =
  { {\delta{f_3}}\over{\delta{h_3}} }\pauli{0}
- { {\delta{f_2}}\over{\delta{h_3}} }\pauli{1}
+ { {\delta{f_1}}\over{\delta{h_3}} }\pauli{2}
- { {\delta{f_0}}\over{\delta{h_3}} }\pauli{3}
\end{eqnarray}
Equating (6)-(9) yields:
\begin{eqnarray}
+ { {\delta{f_0}}\over{\delta{h_0}} } = + { {\delta{f_1}}\over{\delta{h_1}} } =
+ { {\delta{f_2}}\over{\delta{h_2}} } = + { {\delta{f_3}}\over{\delta{h_3}} }\\
+ { {\delta{f_1}}\over{\delta{h_0}} } = - { {\delta{f_0}}\over{\delta{h_1}} } =
+ { {\delta{f_3}}\over{\delta{h_2}} } = - { {\delta{f_2}}\over{\delta{h_3}} }\\
+ { {\delta{f_2}}\over{\delta{h_0}} } = - { {\delta{f_3}}\over{\delta{h_1}} } =
- { {\delta{f_0}}\over{\delta{h_2}} } = + { {\delta{f_1}}\over{\delta{h_3}} }\\
+ { {\delta{f_3}}\over{\delta{h_0}} } = + { {\delta{f_2}}\over{\delta{h_1}} } =
- { {\delta{f_1}}\over{\delta{h_2}} } = - { {\delta{f_0}}\over{\delta{h_3}} }
\end{eqnarray}
Define the quaternion ``del'' operator:
\begin{equation}
\bm{\Delta}= {\delta\over\delta h_0}\pauli{0}
	- \sum_{i=1}^3{\delta\over\delta h_i}\pauli{i}
\end{equation}
then
\begin{eqnarray}
(\bm{\Delta F})_0
  = \pdi{h_0}{f_0} + \pdi{h_1}{f_1} + \pdi{h_2}{f_2} + \pdi{h_3}{f_3}
  = 4\pdi{h_0}{f_0}
\end{eqnarray}
and
\begin{eqnarray}
(\bm{\Delta F})_1
  = \pdi{h_0}{f_1} - \pdi{h_1}{f_0} - \pdi{h_2}{f_3} + \pdi{h_3}{f_2} = 0 \\
(\bm{\Delta F})_2
  = \pdi{h_0}{f_2} + \pdi{h_1}{f_3} - \pdi{h_2}{f_0} - \pdi{h_3}{f_1} = 0 \\
(\bm{\Delta F})_3
  = \pdi{h_0}{f_3} - \pdi{h_1}{f_2} + \pdi{h_2}{f_1} - \pdi{h_3}{f_0} = 0
\end{eqnarray}
That is, if a quaternion function is differentiable, then its gradient
is scalar and equal to four times the partial derivative of the scalar
component of $\bm{F}$ ($f_0$) with respect to the scalar component of
$\bm{H}$ ($h_0$).
\end{document}


\subsection{Data} \label{subsec:data_linear_regression}
In this project, we are fitting $2D$ polynomials to the Franke function with gaussian noise. The Franke function is defined as
\begin{equation}
    \begin{split}
        f(x_1,x_2) := \frac{3}{4}\exp{\left(-\frac{(9x_1-2)^2}{4}-\frac{(9x_2-2)^2}{4}\right)} \\ + \frac{3}{4}\exp{\left(-\frac{(9x_1+1)^2}{49}-\frac{(9x_2+1)}{10}\right)} \\+ \frac{1}{2}\exp{\left(-\frac{(9x_1-7)^2}{4}-\frac{(9x_2-3)^2}{4}\right)} \\ - \frac{1}{5}\exp{\left(-(9x_1-4)^2-(9x_2-7)^2 \right)}
    \end{split}
\end{equation}
To this Franke function, we add noise sampled from a Gaussian distribution $\mathcal{N}(0, var)$ to get a noisy Franke function:  $\tilde{f}(x_1,x_2)$. Figure \ref{fig:franke_function} shows a plot of the Franke function with and without noise.
\begin{figure}[H]
\centering
\begin{subfigure}{.5\textwidth}
  \centering
  \includegraphics[width=.9\linewidth]{Images/franke_function.png}
  \caption{}
  \label{fig:franke}
\end{subfigure}%
\begin{subfigure}{.5\textwidth}
  \centering
  \includegraphics[width=.9\linewidth]{Images/franke_function_noise.png}
  \caption{}
  \label{fig:franke_noise}
\end{subfigure}
\caption{Plot of the Franke function with noise (b) and without noise (a). The variance of the added noise is 0.1.}
\label{fig:franke_function}
\end{figure}


At Stage~3, an approximation of the quantity of interest is constructed using
the interpolation algorithm presented in this section. The algorithm constitutes
the core of the framework proposed in this chapter, and it features a sparse
structure, hierarchical construction, and hybrid adaptivity. The benefits of
these characteristics are interconnected and can be summarized as follows:
\one~the ability to efficiently address multidimensional problems, \two~the
ability to progressively refine the approximation, and \three~the ability to
perform this refinement strategically by virtue of fine-grained error control.

Hierarchical interpolation is introduced in \xref{hierarchical-interpolation},
and here we rely heavily on the results discussed in that section. The
mathematics presented in \xref{hierarchical-interpolation} and below are based
on the development in \cite{klimke2006, ma2009, jakeman2012}.

Consider the quantity of interest \g as a function of \vz via $\transform$ as
shown in \sref{frame-transformation}. Assume that \g belongs to $\continuous{[0,
1]^\nz}$, the space of continuous functions on $[0, 1]^\nz$; the assumption is
not limiting in practice. As shown in \xref{hierarchical-interpolation}, \g can
be approximated by means of the following interpolant:
\begin{equation} \elab{frame-interpolant}
  \g \approx \interpolant{\nz}{\ls}(\g)
  = \interpolant{\nz}{\ls - 1}(\g) + \sum_{\vi \in \Delta\sparseindex{\nz}{\ls}} \sum_{\vj \in \Delta\tensorindex{\nz}{\vi}} \Delta(\g \circ \transform)(\vx_{\vi \vj}) e_{\vi \vj}
\end{equation}
where $\vi \in \natural^\nz$ is called a level index; $\vj \in \natural^\nz$ is
called an order index; $\set{\vx_{\vi \vj}}$ and $\set{e_{\vi \vj}}$ are
collocation nodes and basis functions, respectively; $\set{\Delta(\g \circ
\transform)(\vx_{\vi \vj})}$ are hierarchical surpluses defined in
\eref{interpolant-sparse-surplus}; and $\Delta\sparseindex{\nz}{\ls}$ and
$\Delta\tensorindex{\nz}{\vi}$ are index sets defined in
\eref{interpolant-sparse-index-delta} and \eref{interpolant-tensor-index-delta},
respectively.

Due to the reasons clarified in \sref{frame-adaptivity}, the interpretation of
\eref{frame-interpolant} used in this chapter is different from the one used in
\xref{hierarchical-interpolation}. Specifically, $\ls \in \natural$ no longer
represents an interpolation level but rather an interpolation step. Accordingly,
$\interpolant{\nz}{\ls}(\g)$ represents the interpolant obtained by a certain
interpolation step. In addition, all the index sets discussed here are generally
subsets of their full-fledged counterparts defined in
\xref{hierarchical-interpolation}.

Let us now turn to the choice of collocation nodes and basis functions.

\subsection{Collocation Nodes}
\slab{frame-grid}

In order to gain computational efficiency, the integration grid should be fully
nested, which is explained in \xref{hierarchical-interpolation}. Such a grid can
be constructed using the family of Newton--Cotes rules \cite{ma2009}. In one
dimension, a Newton--Cotes rule is a set of equidistant nodes on $[0, 1]$. There
are two types of Newton--Cotes rules: open and closed. The only difference
between the two types is that the latter includes the endpoints (zero and one),
whereas the former does not.

Technically, in order to be able to proceed to hierarchical interpolation, the
chosen rules have to fulfill a certain condition, which is discussed in
\xref{hierarchical-interpolation} and can be seen in
\eref{interpolant-tensor-exactness}. Closed Newton--Cotes rules satisfy this
condition, and they are the ones used in the original version of local
adaptivity presented in \cite{ma2009}. The open rules, on the other hand, do not
fulfill the condition close to the boundaries of the unit interval. However,
according to our experience, open Newton--Cotes rules are a viable option, since
they perform well in practice, which is also noted in \cite{klimke2006}. In
fact, we are able to obtain better results with open rules and, therefore,
present them here.

\inputfigure{frame-grid}
The open Newton--Cotes rule of level $i \in \natural$ is
\[
  \X^1_i = \set{\x_{ij}}{j \in \tensorindex{1}{i}}
\]
where
\begin{align*}
  & \x_{ij} = \frac{j + 1}{n_i + 1}, \\
  & \tensorindex{1}{i} = \set{i - 1}_{i = 1}^{n_i}, \text{ and} \\
  & n_i = 2^{i + 1} - 1.
\end{align*}
\fref{frame-grid} depicts the first three levels of this rule. It can be seen
that the number of nodes grows as 1, 3, 7, and so on, and that the rule is fully
nested. In multiple dimensions, collocation nodes are formed as shown in
\eref{interpolant-tensor}.

\subsection{Basis Functions}
\slab{frame-basis}

The basis functions that go hand in hand with open Newton--Cotes rules are
piecewise linear functions. For $i = 0$ and $j = 0$,
\[
  e_{00}(\x) = 1.
\]
For $i > 0$ and $j = 0$ (close to the left endpoint),
\[
  e_{i0}(\x) =
  \begin{cases}
    2 - \left(n_i + 1\right) \x, & \text{if } \x < \frac{2}{n_i + 1}; \\
    0, & \text{otherwise}.
  \end{cases}
\]
For $i > 0$ and $j = n_i - 1$ (close to the right endpoint),
\[
  e_{i, n_i - 1}(\x) =
  \begin{cases}
    \left(n_i + 1\right) \x - n_i + 1, & \text{if } \x > \frac{n_i - 1}{n_i + 1}; \\
    0, & \text{otherwise}.
  \end{cases}
\]
In other cases,
\[
  e_{ij}(\x) =
  \begin{cases}
    1 - \left(n_i + 1\right)|\x - \x_{ij}|, & \text{if } |\x - \x_{ij}| < \frac{1}{n_i + 1}; \\
    0, & \text{otherwise}.
  \end{cases}
\]
The basis functions that correspond to the first three levels of one-dimensional
interpolation are depicted in \fref{frame-basis}. In multiple dimensions, basis
functions are formed as shown in \eref{interpolant-tensor}, which results in
\[
  e_{\vi \vj}(\vx) = \prod_{k = 1}^n e_{i_k j_k}(x_k).
\]

\inputfigure{frame-basis}
Additionally, let us calculate the volumes (the integrals over the whole domain)
of the aforementioned piecewise linear functions; these volumes are required in
the continuation. For $i = 0$ and $j = 0$,
\[
  w_{00} = 1.
\]
For $i > 0$ and $j \in \set{0, n_i - 1}$,
\[
  w_{ij} = \frac{2}{n_i + 1}.
\]
In other cases,
\[
  w_{ij} = \frac{1}{n_i + 1}.
\]
The volumes of multidimensional basis functions are products of the
corresponding one-dimensional volumes as follows:
\begin{equation} \elab{frame-volume}
  w_{\vi \vj} = \prod_{k = 1}^\nz w_{i_k j_k}.
\end{equation}

Now, imagine a function that is nearly flat on the first half of $[0, 1]$ and
rather irregular on the other. Under these circumstances, it is natural to
expect that, in order to attain the same accuracy, the first half should require
many fewer collocation nodes than the other one; recall the example given in
\fref{frame-motivation}. However, if we followed the usual construction
procedure described in \xref{hierarchical-interpolation}, we would not be able
to benefit from this idiosyncrasy. Both sides would be treated equally, and all
the nodes of each interpolation level would be added to the interpolant, which
is wasteful. The solution to this problem is to make the interpolation algorithm
adaptive, which we discuss next.

\subsection{Hybrid Adaptivity}
\slab{frame-adaptivity}

In order to make the algorithm adaptive, we first need to decide on a criterion
used for measuring the accuracy of the interpolant $\interpolant{\nz}{\ls}(\g)$
in \eref{frame-interpolant} at any point in $[0, 1]^\nz$. Then, when refining
the interpolant, instead of evaluating the quantity of interest \g at all
possible nodes, we choose only those that are located in the regions with poor
accuracy as indicated by the criterion.

We already have a good foundation for building the above-mentioned criterion.
Hierarchical surpluses, which are introduced in
\xref{hierarchical-interpolation} and defined in
\eref{interpolant-sparse-surplus}, are natural indicators of the interpolation
error: they are the difference between the true values of \g and those estimated
by $\interpolant{\nz}{\ls}(\g)$ at the nodes of the underlying integration grid.
Therefore, hierarchical surpluses can be recycled in order to effectively
identify problematic regions.

We proceed as follows. First, a score is assigned to each node $\vx_{\vi \vj}$
or, equivalently, to each pair of a level index \vi and an order index \vj as
follows:
\begin{equation} \elab{frame-score}
  s_{\vi \vj} = \absolute{\Delta(\g \circ \transform)(\vx_{\vi \vj}) w_{\vi \vj}}
\end{equation}
where $\Delta(\g \circ \transform)(\vx_{\vi \vj})$ is the surplus at the node as
defined in \eref{interpolant-sparse-surplus}, and $w_{\vi \vj}$ is the volume of
the corresponding basis function as shown in \eref{frame-volume}. The above
score is utilized for guiding the algorithm as explained below.

Each hierarchical interpolant $\interpolant{\nz}{\ls}$ is characterized by a set
of level indices $\sparseindex{\nz}{\ls}$, and each level index $\vi \in
\sparseindex{\nz}{\ls}$ by a set of order indices
$\Delta\tensorindex{\nz}{\vi}$. At each interpolation step $\ls \in \natural$, a
single level index
\[
  \vi_{\ls} \in \sparseindex{\nz}{\ls - 1}
\]
is chosen where $\sparseindex{\nz}{-1} = \set{\v{0}}$. This index gives birth to
$\Delta\sparseindex{\nz}{\ls}$ and $\set{\Delta\tensorindex{\nz}{\vi}}{\vi \in
\Delta\sparseindex{\nz}{\ls}}$, forming the increment given on the right-hand
side of \eref{frame-interpolant}.

The level index set $\Delta\sparseindex{\nz}{\ls}$ contains so-called admissible
forward neighbors of the chosen $\vi_{\ls}$. The forward neighbors of an
index~\vi are given by
\[
  \set{\vi + \v{1}_k}_{k = 1}^\nz
\]
where $\v{1}_k \in \set{0, 1}^\nz$ is a vector whose elements are zero except
for element~$k$, which is equal to unity. An index~\vi is called admissible if
its inclusion into the index set $\sparseindex{\nz}{\ls}$ under consideration
keeps the set admissible. Finally, $\sparseindex{\nz}{\ls}$ is admissible if it
satisfies the following condition \cite{klimke2006}:
\[
  \vi - \v{1}_k \in \sparseindex{\nz}{\ls}
\]
for $\vi \in \sparseindex{\nz}{\ls}$ and $k \in \set{\range{1}{\nz}}$ where the
cases with $i_k = 0$ need no check.

Let us now turn to the content of $\Delta\tensorindex{\nz}{\vi}$ where $\vi =
\vi_{\ls} + \v{1}_k$ for some $k$. It also contains admissible forward
neighbors; however, they are order indices, and their construction is different
from the one used in the case of $\Delta\sparseindex{\nz}{\ls}$. These indices
are identified by inspecting the backward neighborhood of \vi, which is
analogous to the forward one but in the other direction. For each backward
neighbor $\vi - \v{1}_m$ and each $\vj \in \Delta\tensorindex{\nz}{\vi -
\v{1}_m}$, we first check the condition
\[
  s_{\vi - \v{1}_m, \vj} \geq \error{s}
\]
where \error{s} is a user-defined constant referred to as the score error. If
the condition holds, the forward neighbors of \vj in dimension~$k$ are added to
$\Delta\tensorindex{\nz}{\vi}$. This procedure is illustrated in
\fref{frame-grid} for open Newton--Cotes rules in one dimension. The arrows
emerging from a collocation node connect the node with its forward neighbors. In
general, each node has two forward neighbors in each dimension. The order
indices of these nodes are
\begin{align*}
  & (j_1, \dots, 2 j_k \phantom{{} + 2}, \dots, j_{\nz}) \text{ and} \\
  & (j_1, \dots, 2 j_k + 2,              \dots, j_{\nz}).
\end{align*}
The above refinement procedure should be performed for each level index $\vi \in
\Delta\sparseindex{\nz}{\ls}$ with respect to each dimension $k \in
\set{\range{1}{\nz}}$.

The choice of $\vi_{\ls} \in \sparseindex{\nz}{\ls - 1}$ at each step \ls in
\eref{frame-interpolant} is made as follows. First, each index can be picked at
most once. The rest is resolved by prioritizing the candidates. It is reasonable
to compute the priority of a level index~\vi based on the scores of the order
indices associated with this level index, that is, based on the scores of
$\tensorindex{\nz}{\vi}$. We set the priority to the average score
\[
  s_{\vi} = \frac{1}{\cardinality{\Delta\tensorindex{\nz}{\vi}}} \sum_{\vj \in \Delta\tensorindex{\nz}{\vi}} s_{\vi \vj}.
\]
Thus, at each step \ls, the index~\vi with the highest $s_{\vi}$ is promoted to
$\vi_{\ls}$.

The final question to answer is the stopping condition of the approximation
process in \eref{frame-interpolant}. Apart from the natural constraints on the
maximum number of function evaluations and the maximum interpolation level (the
original \ls in \xref{hierarchical-interpolation}), we rely on the following
criterion. Given two additional user-defined constants \error{a} and \error{r},
which are referred to as the absolute and relative errors, respectively, the
process is terminated as soon as
\begin{equation} \elab{frame-stop}
  \max_{\vi \vj} \absolute{\Delta(\g \circ \transform)(\vx_{\vi \vj})} \leq \max \set{\error{a}, \error{r} (\g_\maximum - \g_\minimum)}
\end{equation}
where $\g_\minimum$ and $\g_\maximum$ are the minimum and maximum observed
values of \g, respectively. The left-hand side of \eref{frame-stop} corresponds
to the largest surplus whose level index has not been refined yet, that is, has
not been considered as $\vi_{\ls}$ at some step \ls. The above criterion is an
adequate technique for curtailing the interpolation process, since it is based
on the actual progress.

The adaptivity presented in this subsection is referred to as hybrid, since it
combines features of global and local adaptivity \cite{jakeman2012}. Local
adaptivity operates on the level of individual nodes \cite{ma2009} and is
discussed in \sref{frame-motivation}. By contrast, global adaptivity operates on
the level of individual dimensions \cite{klimke2006}. The intuition behind
global adaptivity is that, in general, the input variables manifest themselves
(impact \g) differently, and the interpolation algorithm is likely to benefit by
prioritizing those variables that are the most influential.

\conclusioncut
So far, we have formalized an efficient algorithm for adaptive hierarchical
interpolation in multiple dimensions. The main equation is
\eref{frame-interpolant} where $\Delta(\g \circ \transform)(\vx_{\vi \vj})$,
$\vx_{\vi \vj}$, and $e_{\vi \vj}$ are the ones in
\eref{interpolant-sparse-surplus}, \sref{frame-grid}, and \sref{frame-basis},
respectively; and the interpolation is undertaken according to the rules in
\sref{frame-adaptivity}. Next, we discuss a few implementation details.

\subsection{Implementation}

The life cycle of interpolation has roughly two stages: construction and usage.
The construction stage invokes \g at a set of collocation nodes and produces
certain artifacts. The usage stage estimates the values of \g at a set of
arbitrary points by manipulating these artifacts. In this subsection, we provide
the pseudocode for the two stages in order to give a better sense of the
technique.

Let us first make a general note. According to our experience, it is beneficial
to the clarity and ease of implementation to collapse the two sums in
\eref{frame-interpolant} into one. This requires storing a level index $\vi =
(i_k) \in \natural^\nz$ and an order index $\vj = (j_k) \in \natural^\nz$ for
each node. It is also advantageous to encode each pair $(i_k, j_k)$ as a single
unsigned integer, which, in particular, eliminates excessive memory usage. In
multiple dimensions, this results in a vector $\v{\iota} = (\iota_k) \in
\natural^\nz$, which we simply call an index. Our encoding is
\[
  \iota_k = i_k \lor (j_k \ll \n{\mathrm{bits}})
\]
where $\lor$ and $\ll$ stand for the bitwise \up{OR} and logical left shift,
respectively, and \n{\mathrm{bits}} is the number of bits reserved for storing
level indices, which can be adjusted according to the maximum permitted depth of
interpolation.

\inputalgorithm{frame-construction}
The pseudocode for the construction stage is given in \aref{frame-construction}.
The input is a subroutine called Algorithm~G that evaluates $\g \circ
\transform$. The output is a structure \texttt{interpolant} that contains the
artifacts of the interpolation. These artifacts are a set of tuples
$\set{(\v{\iota}_k, \Delta\g(\vx_{\v{\iota}_k}))}$, which is a comprehensive
description of a hierarchical interpolant. The pseudocode works as follows.

Line 1: Each iteration of the loop corresponds to an interpolation step \ls in
\eref{frame-interpolant}. The progress is captured by a structure
\texttt{state}. The \texttt{strategy} object represents the adaptation strategy
utilized, and it operates in accordance with \sref{frame-adaptivity}. The
\texttt{Continue?} method of \texttt{strategy} checks if any of the stopping
conditions is satisfied, in which case the process is terminated.

Line 2: The \texttt{Next} method of \texttt{strategy} consumes the previous
state and returns the initial state of the ongoing interpolation step. In
particular, it populates the \texttt{indices} field of \texttt{state} with the
indices of the step. The rest of the loop's body populates the rest of
\texttt{state}'s fields so that \texttt{strategy} can adequately execute its
functionality at the beginning of the next iteration.

Line 3: The \texttt{grid} object represents the interpolation grid that is being
utilized, and its \texttt{Compute} method calculates the collocation nodes
$\set{\vx_{\v{\iota}_k}}$ that correspond to the given indices
$\set{\v{\iota}_k}$; see \sref{frame-grid}.

Line 4: Algorithm~G evaluates $\g \circ \transform$ at the collocation nodes.
This is by far the most time consuming operation of the algorithm, as \g is
generally expensive to execute. This operation is also a prominent candidate for
parallelization, since the algorithm does not impose any particular evaluation
order.

Line 5: \aref{frame-evaluation} is a subroutine that exercises the interpolant
constructed so far at the collocation nodes and thereby approximates the values
obtained on line~4. This algorithm will be discussed separately later on.

Line 6: The \texttt{Subtract} subroutine computes the difference between the
actual and approximated values of \g, which yields the hierarchical surpluses
$\set{\Delta(\g \circ \transform)(\vx_{\v{\iota}_k})}$ (see
\eref{interpolant-sparse-surplus}) of the current interpolation step.

Line 7: The \texttt{Score} method of \texttt{strategy} calculates the scores of
the collocation nodes based on their surpluses as described in
\sref{frame-adaptivity}.

Line 8: The \texttt{Append} method of \texttt{interpolant} refines the
interpolant by extending it with the indices and surpluses of the completed
iteration.

\inputalgorithm{frame-evaluation}
We now turn our attention to the usage stage of an interpolant. The pseudocode
is given in \aref{frame-evaluation}. This subroutine is also used in
\aref{frame-construction} on line~5. Let us make a couple of observations
regarding this subroutine.

Line 3: The inner loop corresponds to an unfolded version of
\eref{frame-interpolant}; that is, there is no separation into the individual
interpolation steps taken.

Line 4: The \texttt{basis} object represents the interpolation basis that is
being used, and its \texttt{Compute} method evaluates the basis functions
$\set{e_{\v{\iota}_k}}$ that correspond to the given indices $\set{\v{\iota}_k}$
at arbitrary points; see \sref{frame-basis}.

It is worth noting that the \texttt{strategy}, \texttt{grid}, and \texttt{basis}
objects conform to certain interfaces and can be easily swapped out. This makes
the two algorithms very general and reusable with different configurations. In
particular, the adaptation strategy can be fine-tuned for each particular
problem.

\conclusioncut
To recapitulate, in this section, the approximation engine of our framework for
probabilistic analysis of electronic systems under workload variation has been
presented. It is consolidated in \aref{frame-construction} and
\aref{frame-evaluation}.