% !TEX root=/home/tavant/these/manuscript/src/manuscript.tex

% \FloatBarrier

\section{Comparison of the sheath model with PIC simulations} \label{subsec-picandmodel}

  % \begin{figure}[hbt]
  %   \centering
  %   \includegraphics[width=\textwidth]{dphi_polytropic_noSEE}
  %   \caption{PIC simulation results (with SEE) compared to the polytropic limit without SEE.}
  %   \label{fig-polytropic_pic_noSEE}
  % \end{figure}
  %
  % \begin{figure}[hbt]
  %   \centering
  %   \includegraphics[width=\textwidth]{Summary_polytropic_SEE.pdf}
  %   \caption{Comparison of the PIC simulation results with the polytropic model with SEE.}
  %   \label{fig-polytropic_see_summary}
  % \end{figure}

  We compare in this section the characteristics of the plasma wall interaction observed in the \ac{PIC} simulations with the fluid model developed in \cref{sec-fluid_poly_see}.
  We first compare the mean values in the parametric study over the crossover energy $\crover$, then we investigate the oscillations of regime {\bf II}.

  \subsection{Parametric study of the modified sheath model} \label{subsec-param_sheath_see}

    The variables of interest to characterize the plasma-wall interaction are the averaged electron emission rate $\rate$ and the plasma potential drop to the wall.
    The only inputs of the modified sheath model are the electron mean temperature in the bulk $\Teb$, as well as the polytropic index $\gamma$.
    As seen in \cref{subsec-fluid_see_polyfit}, the polytropic index of the total electron population is measured in the \ac{PIC} simulations to be $\gamma=1.36$.
    However, the electrons going toward the wall present a different index, measured from the bulk \ac{EVDF} to $\gamma=1.28$.
    These two values will be compared.

    \paragraph{One polytropic index: $\gamma=1.36$\\}

    Using the mean electron temperature measured in the \ac{PIC} simulations, we first compute the plasma potential drop $\dphi$ by solving \cref{eq-costseepoly} with $\gamma=1.36$.
    As shown in \cref{fig-Te2_epsi}, up to three solutions are possible.
    The emission rate $\rate$ is computed using \cref{eq-seemaxw_poly}.
    As discussed previously, the rate is limited to $\ratecr=0.982$ to take into account the \ac{SCL} regime.

    The results of the sheath modeled are compared to the \ac{PIC} simulation results in \Cref{fig-Poly_model_vs_pic}.
    The plasma potential drop in \cref{fig-Poly_model_vs_pic}.{\bf a} is increased by $\sqrt{\gamma} \Teb/2$ to account for the pre-sheath drop.

    \begin{figure}[!hbt]
      \centering
      \includegraphics[width=\textwidth]{Poly_model_vs_pic_gamma136.pdf}
      \caption{Comparison of the PIC simulations and the sheath model using $\gamma=1.28$ for ({\bf a}) the plasma potential drop from the center to the wall, and ({\bf b}) the electron emission yield calculated with \cref{eq-seemaxw_poly}. On the panel ({\bf b}) the red dotted line correspond to the value of $\ratemaxw$ obtained with \cref{eq-seemaxw_poly} using the value of $\dphi$ showed on the panel ({\bf a}).   }
      \label{fig-Poly_model_vs_pic}
    \end{figure}

    Concerning $\dphi$, we see that the sheath model combining the polytropic state law and the electron emission is in good agreement with the \ac{PIC} simulations.
    We see that the region where the three solutions coexist corresponds well with the regime {\bf II}.

    Concerning the emission rate $\rate$, we observe that the value $\gamma=1.36$ under estimates $\rate$ compared to the values of the \ac{PIC} simulations for $\crover > 70\,\volt$.
    On the other hand, $\gamma=1.28$ is in very good agreement on the whole range of $\crover$.
    Interestingly, the saturation of the mean electron emission rate for low values of $\crover$ in the \ac{PIC} simulation is greater than the critical value $\ratecr$.
    This is because the critical value corresponds to the start of the \ac{SCL} regime, with a radial electric at the wall equal to zero.
    However, we observe in the \ac{PIC} simulation a small potential well, meaning that the \ac{SEE} rate is slightly above $\ratecr$.

    \paragraph{Two polytropic index: $\gamma=1.36$ and $1.28$\\}
    We saw in \cref{fig-Poly_model_vs_pic} that $\rate$ is better described using $\gamma=1.28$.
    Therefore, we modify the sheath model to take into account two polytropic index\string: $\gamma=1.36$ is used to described the electron density, but now $\gamma=1.28$ is used to compute the temperature at the wall of the forward electron population, hence the  \ac{SEE} rate.
    The results of the modified sheath model is shown in \Cref{fig-Poly_model_vs_pic2}.
    We see that the modified sheath modeled using two values of $\gamma$ does not affect significantly the value of the sheath potential drop $\dphi$.
    However, the secondary electron emission rate is in better agreement with the \ac{PIC} simulation results.

    \begin{figure}[!hbt]
      \centering
      \includegraphics[width=\textwidth]{Poly_model_vs_pic_2gamma.pdf}
      \caption{Comparison of the PIC simulations and the sheath model using two values of $\gamma$ ($\gamma=1.36$ for the electron density, and $\gamma=1.28$ for the forward electron temperature at the wall) for ({\bf a}) the plasma potential drop from the center to the wall, and ({\bf b}) the electron emission yield calculated with \cref{eq-seemaxw_poly}. }
      \label{fig-Poly_model_vs_pic2}
    \end{figure}

  \subsection{Sheath oscillations of regime {\bf II}} \label{subsec-pic_scheath_RSO}

    The regime {\bf II} is characterized by the presence of oscillations between two meta-stable regimes {\bf III} and {\bf I}, one with a low emissivity and the other with a high emissivity.
    \Cref{fig-long_time} shows the temporal evolution of the electron temperature and the plasma potential relative to the wall for $\crover=45\,\volt$.
    The electron temperature is computed over the whole electron population in the \ac{PIC} simulations.
    Both the radial temperature $\Te_{,R}$ and the total temperature $\Te$ are shown (see \cref{eq-3Te} for their definition).
    The plasma potential $\dphi$ shown is measured at the center of the radial direction of the simulation, averaged over the azimuthal direction.

     \renewcommand\subfigurewidth{0.7\textwidth}
    \begin{figure}[!hbt]
      \centering
      % \begin{tabular}{@{} c }
      %   %\subfigure{long_time_dphi}{a}{20,20}\\
      %   \subfigure{long_time_Te}{b}{20,20}
      % \end{tabular}
      \includegraphics[width=\textwidth]{long_time_Te}
      \caption{Temporal evolution of ({\bf a}) the plasma potential $\dphi$ and ({\bf b}) the electron temperatures\string: $\Te_{,R}$ is the radial temperature, and $\Te$ is the total temperature.}
      \label{fig-long_time}
    \end{figure}
    \renewcommand\subfigurewidth{0.47\textwidth}

    We clearly see in \cref{fig-long_time} the quasi-periodic oscillations between the two states.
    We observe that the electron temperature is slightly anisotropic, with the radial temperature smaller than the axial temperature.
    This anisotropy observed was not taken into account in the sheath model developed in this chapter.
    More precisely, the radial temperature $\Te_{,R}$ is linked to the thermal flux of electron toward the wall, while the total temperature $\Te$ changes the electron emission rate $\ratemaxw$.
    However, the degree of anisotropy is not very high, as it is of the order of 10\% when the sheath is not inverted.
    When the sheath is inverted, the anisotropy is of the order of 25\%, as the electrons with a large radial energy are quickly absorbed.
    However in the \ac{SCL} regime, we assume that the electron emission rate saturates at $\rate=\ratecr$, hence in this regime the impact of the total energy is less important with respect of the radial energy.
    Hence, we will compare the prediction using only the radial temperature $\Te_{,R}$ or the total, averaged, temperature $\Te$, but not the two of them together.

    \Cref{fig-dphi_te_PIc2} shows the potential drop as a function of the radial electron temperature $\Te_R$ and the total electron temperature $\Te = (\Te_R + \Te_{\theta} + \Te_z)/3$ measured in the \ac{PIC} simulation (same case as \cref{fig-long_time}).
    Is also shown the theoretical solutions obtained with the model of \cref{sec-fluid_poly_see} using constant polytropic indexes $\gamma=1.36$ and $1.28$, and $\crover=45\,\volt$, and a pre-sheath potential drop of $\Teb/2$.

    \begin{figure}[hbt]
      \centering
      \includegraphics[width=0.5\textwidth]{parametric_PIC_dphi_Te_two_gamma_bis}
      \caption{Plasma potential as a function of (left) the radial electron temperature $\Te_R$ and (right) the total electron temperature. The blue line is the \acs{PIC} results presented in \cref{fig-long_time}, the orange dashed lines correspond to the theoretical values with $\gamma=1.36$, and the green dotted-dashed line is computed with $\gamma=1.28$.}
      \label{fig-dphi_te_PIc2}
    \end{figure}
    %
    %
    % \begin{figure}[hbt]
    %   \centering
    %   \includegraphics[width=\textwidth]{parametric_PIC_dphi_Te_bis}
    %   \caption{Plasma potential as a function of (left) the radial electron temperature and (right) the total electron temperature. The blue markers represent the \acs{PIC} results presented in \cref{fig-long_time}, and the orange dashed lines correspond to the theoretical values with $\gamma=1.35$.}
    %   \label{fig-dphi_te_PIc}
    % \end{figure}

    We see in \cref{fig-dphi_te_PIc2} that the sheath characteristics observed in the \ac{PIC}  simulations match relatively well the theoretically values obtained from the sheath model.
    In particular, we see the co-existence of the two solutions of $\dphi$ observed for the same electron temperature, which corresponds to the domain of electron temperature for which the sheath model also predicts multiple solutions.

    During the state corresponding to regime {\bf III} (high value of  $\dphi$), the \ac{PIC} values are too noisy to clearly determine if the sheath follows the first or the second branch of the solutions.
    On the other hand, we see relatively well the correspondence between the \ac{PIC} results and the theory for the regime {\bf I} (low value of $\dphi$.
    The agreement with the polytropic sheath model using $\gamma = 1.36$ is better during the standard sheath regime, as the maximum electron temperature $\Te^{(1)}$ observed in the simulation is higher than the value at $\gamma=1.28$.
    However, during the \ac{SCL} regime the two values return the same plasma potential.

    % As discussed previously, the value of the polytropic index computed by propagating the \ac{EVDF}, is $\gamma=1.28$.
    % \Cref{fig-dphi_te_PIc2} shows the same results as \cref{fig-dphi_te_PIc}, but  the theoretical values of $\dphi$ using $\gamma=1.28$ are overlaid.
    % We see that using the value $\gamma=1.28$ does not change significantly the value of the solution, except for the maximum value of the electron temperature $\Te^{(1)}$ for the first branch of the solution, hence the domain of temperature where the three solutions coexist.
    % In the case of $\gamma=1.28$, the \ac{PIC} simulation result agreement with the theory is worse than for $\gamma=1.35$.

    % \begin{figure}[hbt]
    %   \centering
    %   \includegraphics[width=\textwidth]{parametric_PIC_dphi_Te_two_gamma_bis}
    %   \caption{Similarly to \cref{fig-dphi_te_PIc}, Plasma potential as a function of (left) the radial electron temperature and (right) the total electron temperature. The blue markers represent the \acs{PIC} results presented in \cref{fig-long_time}, the orange dashed lines correspond to the theoretical values with $\gamma=1.35$, and the green dotted-dashed line is computed with $\gamma=1.28$.}
    %   \label{fig-dphi_te_PIc2}
    % \end{figure}

    \paragraph{Electron power balance\\}
    The total electron power balance integrated aver the simulation domain can be expressed as
    \begin{equation} \label{eq-GMel}
      \deriv{}{t} \lp \frac{3}{2} V n_e e \Te \rp = P_{\rm abs} - P_{\rm loss},
    \end{equation}
    with $V$ the  volume of the simulation domain, $n_e$ the average electron density,  $P_{\rm abs}$ the total absorbed power, and $P_{\rm loss}$ the total power lost.
    The absorbed power $P_{\rm abs}$ is assumed to be the Joule heating
    \begin{equation} \label{eq-pabs}
      P_{\rm abs} = V n_e e \vect{v_e} \cdot \vect{E} = V n_e e v_{e, z} E_z = V n_e e \mu_e  E_z^2
    \end{equation}
    with $E_z$ the imposed axial electric field and $\mu_e$ the electron axial mobility.
    From the parametric study of \cref{ch-2}, we have $\mu_e \simeq 5.6 \,\meter\squared\per\volt\per\second$.
    As $E_z$ is imposed and the electron density is constant, then the absorbed power is constant.

    The power loss $P_{\rm loss}$ is assumed to be governed by losses at the wall.
    Hence, as developed in \cref{sec-fluid}
    \begin{equation} \label{eq-Ploss}
      P_{\rm loss} = S \frac{1}{4} h n_e u_b 2 e\Tew
    \end{equation}
    with $S$ the surface of the wall of the simulation domain, $h \sim 1$ is the ratio between the mean plasma density and the plasma density at the sheath edge, $u_b = \sqrt{\frac{\gamma e \Te}{m_i}}$ is the modified Bohm velocity and $\Tew$ is the electron temperature at the wall.
    Hence, we have
    \begin{equation} \label{eq-MG_bis}
    \deriv{}{t} \Te = \frac{2}{3} \mu_e  E_z^2 - \frac{S}{V} \frac{1}{3} \sqrt{\frac{\gamma e \Te}{m_i}}  \lp \Te - \frac{\gamma - 1}{\gamma} \dphi \rp,
    \end{equation}
    where $\frac{V}{S} = L_R$.
    \Cref{eq-MG_bis} is coupled with the sheath model that returns $\dphi$ as a function of $\Te$.
    Concerning the three co-existing solutions, we assume that the sheath follows the same branch until the threshold temperature $\Te^{(2)}$, or $\Te^{(1)}$, is reached when the electron temperature increases, or decreases, respectively.
    When $\Te^{(1)}$ or $\Te^{(2)}$ is reached, the sheath jumps to the other solution.

    \begin{figure}[!hbt]
      \centering
      \includegraphics[width=0.9\textwidth]{Power_balance_Te.pdf}
      \caption{Evolution of the power balance $P_{\rm abs}-P_{\rm loss}$ as a function of the electron temperature for ({\bf a}) $L_R=2\,\centi\meter$ and ({\bf b}) $L_R=4\,\centi\meter$, with $\crover=45\,\volt$. The blue line corresponds to the increasing temperature for the standard sheath solution, and the orange line correspond to the decreasing temperature in the inverted sheath solution. The markers represent the limit values of the power balance.}
      \label{fig-powerbalance}
    \end{figure}

    \Cref{fig-powerbalance} shows the evolution of the power balance with the electron temperature for two values of $L_R=2$ and $4\,\centi\meter$.
    We see for $L_R=2\,\centi\meter$ in \cref{fig-powerbalance}.{\bf a} that starting from $\Te=20\,\volt$ the power balance is positive until $\Te\simeq50\,\volt$.
    In this condition, the system present a stable solution at that temperature.
    In contrast for $L_R=4\,\centi\meter$ in \cref{fig-powerbalance}.{\bf b} the power balance is positive along all of the blue curve, meaning that the electron temperature will rise until the sheath jumps to the \ac{SCL} regime.
    There, the power balance is negative, so the electron temperature will decreases until $\Te\simeq35\,\volt$ for which the power is balanced.

    The power balance of \cref{eq-MG_bis} cannot present an oscillating evolution, as there is a temperature for which the power is balance.
    This is because the maximum power balance in the \ac{SCL} regime (blue circle markers in  \cref{fig-powerbalance}) is above the minimum value in the standard regime (black triangular markers)
    In order to observe the oscillations, one should have the circle marker below the triangular one.

    % \begin{figure}[hbtp]
    %   \centering
    %   \includegraphics[width=\textwidth]{global_model.pdf}
    %   \caption{Results of the electron power balance. ({\bf a}) shows the temporal evolution of the electron power balance from \cref{eq-MG_bis}, ({\bf b}) shows the temporal evolution of the electron temperature, and ({\bf c}) shows the evolution of the plasma potential $\dphi$ as a function of $\Te$. }
    %   \label{fig-GM_results}
    % \end{figure}
    %
    % \Cref{fig-GM_results} shows the results obtained by using the electron power balance.
    % \cref{fig-GM_results}.{\bf a} and {\bf b} shows the temporal evolution of the power balance and the electron temperature $\Te$, and \cref{fig-GM_results}.{\bf c} shows the plasma potential as a function of $\Te$.
    % Starting from an initial value $\Te=10\,\volt$, the electron temperature increases until reaching $\Te^{(1)}$.
    % Then, the sheath enters the \ac{SCL} regime and $\Te$ decreases until reaching $\Te^{(2)}$.
    %
    % The period of the oscillation is of the order of $0.1\,\micro\second$, which is significantly shorter than the \ac{PIC} simulation.
    % Indeed, the period of the sheath oscillations observed in \cref{fig-long_time} is approximately $T = 2\,\micro\second$.

    \paragraph{ Ion dynamics \\}

    One has to note that the modified sheath model is stationary, while the oscillations observed are relatively fast.
    The ion dynamics can be estimated to be
    \begin{equation} \label{eq-ti}
      \tau_i = \frac{2 \pi}{\opi} = 0.1 \,\micro\second.
    \end{equation}

    Another estimation of the ion time scale is the time needed by an ion to reach the sheath edge from the center of the discharge.
    Assuming a constant electric field $E_{\rm ps} = \frac{\Te}{L_R}$ in the pre-sheath, we have
    \begin{equation} \label{eq-tof}
      t_{\rm flight} = L_R \sqrt{\frac{m_i}{e \Te}} = 3.7 \,\micro\second.
    \end{equation}
    with $L_R=2\,\centi\meter$ and $\Te=40\,\volt$.
    The period of the sheath oscillations observed $T = 2\,\micro\second$ is between $\tau_i$ and $t_{\rm flight}$.
    Hence, we can expect the ion dynamics to affect the plasma sheath characteristics during the sheath oscillations of the regime {\bf II}.

    The sheath oscillations of regime {\bf II} have been observed in \citet{croes2017} with three different ion masses: xenon, krypton and argon.
    The results are shown in \cref{fig-RSO_altern}.
    We see that the period of the oscillations vary with the ion mass.
    More precisely, the period of oscillations decreases with the decrease of the ion mass.
    This observation confirms that the ions have a role in the dynamics of the oscillations.

    \begin{figure}[hbt]
      \centering
      \includegraphics[width=\defaultwidth]{SEE_RSOs.png}
      \caption{Temporal evolution of the SEE rate $\rate$ measured in the PIC simulations for different gases (xenon, krypton, and argon), taken from \citet{croes2017}.}
      \label{fig-RSO_altern}
    \end{figure}


\documentclass[a4paper,11pt]{article}
\usepackage[utf8]{inputenc}
\usepackage{algorithmic}
\usepackage{algorithm}
\usepackage{pst-plot}
\usepackage{graphicx}
\usepackage{endnotes}
\usepackage{graphics}
\usepackage{floatflt}
\usepackage{wrapfig}
\usepackage{amsfonts}
\usepackage{amsmath}
\usepackage{verbatim}
\usepackage{hyperref}
\usepackage{multirow}
\usepackage{pdflscape}
 \usepackage{enumitem}

\usepackage{hyperref}
\hypersetup{pdfborder={0 0 0 0}}

\pdfpagewidth 210mm
\pdfpageheight 297mm
\setlength\topmargin{0mm}
\setlength\headheight{0mm}
\setlength\headsep{0mm}
\setlength\textheight{250mm}
\setlength\textwidth{159.2mm}
\setlength\oddsidemargin{0mm}
\setlength\evensidemargin{0mm}
\setlength\parindent{7mm}
\setlength\parskip{0mm}

\newenvironment{exercise}[3]{\paragraph{Exercise #1: #2 (#3pt)}\ \\}{
\medskip}
\newcommand{\question}[2]{\setlength\parindent{0mm}\ \\$\mathbf{Q_#1:}$ #2\ \\}

\author{\large{Ilya Kuzovkin, Raul Vicente}}
\title{\huge{Introduction to Computational Neuroscience}\\\LARGE{Practice on Single Neuron Models}}

\begin{document}
\maketitle

\textbf{A request:} Please track how long it will take to complete this set of exercises. Add this time to your final report.
\ \\

%
% Intro
%
In this session we will have a brief look on three different computational models of a neuron: McCulloch-Pitts, Intergrate-and-Fire and Hodgkin-Huxley.

%
% Logic gates
%
\begin{exercise}{1}{Logic gates}{1}
On the lecture we have seen how to construct \texttt{AND}, \texttt{OR} and \texttt{NOT} logic gates using the the McCulloch-Pitts model of a neuron. Your task is to construct more. Please construct the following two gates:
\begin{enumerate}
\itemsep 0em
	\item \texttt{NAND}
	\item \texttt{XOR}
\end{enumerate}
\paragraph{Hint 1}For the \texttt{XOR} gate you will need more than one neuron.
\paragraph{Hint 2}Same input can go simultaneously to several neurons.
\end{exercise}

%
% Integrate and Fire
%
\begin{exercise}{2}{Integrate and Fire neuron model}{2.5}
Integrate and Fire neuron accumulates voltage until it reaches the \emph{threshold}. After that it fires and resets voltage back to initial value. In this exercise we will model behaviour of such neuron and study its properties. Follow the instructions in the \texttt{integratefire.m} file and report all figures, essential pieces of code, answers, interpretations and conclusions you will make during the work.

\paragraph{Note} The \texttt{TODO} marker will indicate the places where you have to do something: complete the code, plot and report a figure, give an interpretation, etc.\\
\ \\
The very final result in this exercise should look something like this
\begin{figure}[H]
   \centering
   \includegraphics[width=0.8\textwidth]{raster_plot.png}
   \caption{10 trials of data generated using Integrate-and-Fire neuron model.}
   \label{fig:rasterplot}
\end{figure}
\end{exercise}

%
% Hodgkin-Huxley
%
\begin{exercise}{3}{Hodgkin-Huxley neuron model}{1.5}
Hodgkin-Huxley model is considered to be the most important computational neuronal model in the neuroscience today. We have the model already implemented in the file \texttt{HH0.m}, study it. Follow the instructions in the \texttt{hodgkinhuxley.m} file and report all figures, thoughts, interpretations and conclusions you will have during the work.

\paragraph{Note} The \texttt{TODO} marker will indicate places where you have to do something: complete the code, plot and report a figure, give an interpretation, etc.
\end{exercise}

%
% Integrate and Fire with synapses
%
\begin{exercise}{4}{Integrate and fire with synapses}{1}
In this exercise we will play with somewhat more realistic version of integrate-and-fire model, which receives input not from constant current as we did before, but from incoming (\emph{presynaptic}) spikes. \emph{Temporal summation} can lead to the voltage reaching the threshold and then the \emph{postsynaptic} neuronal response (firing) occurs. Read the tutorial\footnote{\url{http://www.dreamincode.net/forums/topic/72868-a-simple-neuron-model-the-integrate-and-fire-neuron}} and study the code given there. Slightly modified code is provided to you in the file \texttt{integratefiresynapses.m}. Your task is to compe up with three different configurations of spikes on the line 41:
\begin{enumerate}
	\item Inside the time window from 0 to 200 ms there will be 4 incoming spikes and 1 output spike.
	\item Inside the time window from 200 to 400 ms there will 5 incoming spikes and 0 output spikes.
	\item Is is possible to produce 2 output spikes with 5 incoming spikes? If yes, then produce it in time window 400 to 600 ms, if not show the maximal voltages you can achieve with 5 input spikes.
\end{enumerate}
\end{exercise}

%
% SR latch
%
\begin{exercise}{5*}{Simulate memory with $\neg S$-$\neg R$ latch}{bonus 2}
In electronics there is a circuit, which can \emph{store} a state. This means that after we \emph{set} it to some state, it will remain there until we \emph{reset} it. The whole thing is called \emph{D latch}, it has a sub-part called \emph{SR latch}, which again has a subpart called \emph{$\neg S$-$\neg R$ latch}.
\begin{enumerate}
\itemsep 0em
	\item Watch this video \url{https://www.youtube.com/watch?v=PCT76PsDr6g} (until 12:26)
	\item and build $\neg S$-$\neg R$ latch using McCulloch-Pitts neurons.
\end{enumerate}
\end{exercise}

\ \\
\ \\
\ \\
\ \\
\ \\
Please submit a \texttt{pdf} report with answers to the questions and comments about your solutions. Include figures, explanations and essential pieces of code. Do not include the code itself as a separate file, your report should give good understanding of what you have done. Please mark how long it took to complete this set of exercises. Upload the \texttt{pdf} to the practice session page on the course website.

\end{document}

2015/Practices/05 - Single Neuron Models/text/cns-singleneuron.tex


\documentclass[notitlepage,11pt]{article}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\usepackage{amsfonts}
\usepackage{amsmath}
\usepackage{geometry}
\usepackage{graphicx}
\usepackage{amssymb}
\usepackage{makeidx}
\usepackage{multicol}

\setcounter{MaxMatrixCols}{10}
%TCIDATA{OutputFilter=Latex.dll}
%TCIDATA{Version=5.50.0.2960}
%TCIDATA{<META NAME="SaveForMode" CONTENT="1">}
%TCIDATA{BibliographyScheme=Manual}
%TCIDATA{LastRevised=Monday, October 19, 2020 03:11:11}
%TCIDATA{<META NAME="GraphicsSave" CONTENT="32">}
%TCIDATA{Language=American English}

\geometry{left=1in,right=1in,top=1.25in,bottom=1in}
\input{tcilatex}
\begin{document}

\author{Richard Dennis\thanks{%
Address for Correspondence: Adam Smith Business School, University of
Glasgow, Main Building, University Avenue, Glasgow G12 8QQ; email:
richard.dennis@glasgow.ac.uk.} \\
%EndAName
University of Glasgow and CAMA}
\title{SolveDSGE v0.3.10 --- A User Guide}
\date{October 2020}
\maketitle

\begin{abstract}
SolveDSGE is a Julia package for solving nonlinear Dynamic Stochastic
General Equilibrium models. \ A varietry of solution methods are available,
and they are interchangable so that one solution can be used subsequently as
an initialization to obtain a more accurate solution.\noindent\ \ The
package can compute one- second- and third-order perturbation solutions and
Chebyshev-based, Smolyak-based and piecewise linear-based projection
solutions. \ Once a model has been solved, the package can used used to
simulate data and/or compute impulse response functions.

\vspace{0.12in}\noindent {JEL Classification: E3, E4, E5.}
\end{abstract}

\thispagestyle{empty}\newpage \setlength{\baselineskip}{18.95pt}%
\setcounter{page}{1}

\section{Introduction}

SolveDSGE is a framework for solving and analyzing Dynamic Stochastic
General Equilibrium (DSGE) models that is implemented in the programming
language Julia. \ SolveDSGE will solve nonlinear DSGE models using
perturbation methods, producing solutions that are accurate to first,
second, and third order, but this is not its focus. \ The package's focus is
on applying projection methods to obtain solutions that are globally
accurate.

Obtaining globally accurate solutions to nonlinear DSGE models is
notoriously difficult. \ Solutions are invariably slow to obtain and
model-specific characteristics are often exploited to speed up the solution
process. \ SolveDSGE does not exploit model-specific characteristics in
order to solve a model. \ Instead, SolveDSGE applies the same general
solution strategy to all models. \ Nonetheless, making use of Julia's speed,
SolveDSGE allows models to be solved \textquotedblleft relatively
quickly\textquotedblright , and it provides users with an easy, unified, way
of organizing and expressing their model. \ At the user's request, globally
accurate\ solutions can be obtained using Chebyshev polynomials, Smolyak
polynomials, or piecewise linear approximations, with the solution obtained
from one approximation scheme able to be used as an initialization for the
others, allowing greater speed and accuracy to be obtained via a form of
homotophy.

To use SolveDSGE to solve a model, two files must be supplied. \ The first
file (the model file) summarizes the model to be solved. \ The second file
(the solution file) reads the model file, solves the model, and performs any
post-solution analysis.

Quite a lot of time and effort has gone into writing SolveDSGE, together
with the underlying modules: ChebyshevApprox, SmolyakApprox, and
PiecewiseLinearApprox, but it is far from perfect. \ SolveDSGE may not be
able to solve your model, or it may not obtain a solution quickly enough to
be useful to you. \ You are welcome to suggest improvements to fix bugs or
add functionality. \ At the same time, I am hopeful that you will find the
package useful for your research. \ If it is, then please cite this User
Guide and add an acknowledgement of SolveDSGE to your paper/report.

\section{What types of models can be solved?}

SolveDSGE is designed to solve models that can be written in the following
standard form:%
\begin{equation}
E_{t}\left[ \mathbf{f}\left( \mathbf{x}_{t},\mathbf{y}_{t},\mathbf{x}_{t+1},%
\mathbf{y}_{t+1},\mathbf{\varepsilon }_{t+1}\right) \right] =\mathbf{0},
\end{equation}%
where $\mathbf{x}_{t}$ is a vector of state variables, $\mathbf{y}_{t}$ is a
vector of jump variables, and $\mathbf{\varepsilon }_{t+1}$ is a vector of
shocks. \ The first-order conditions and constraints for the DSGE model are
specified equation-by-equation. \ The shocks, state variables, and jump
variables are defined and then SolveDSGE takes the model and expresses it in
the form of equation (1) in preparation for solution. \ Equation (1) covers
a wide set of models, but obviously not all models. \ In principle SolveDSGE
can handle standard business cycle models of the real and new Keynesian
varieties, and it can handle models with volatility shocks, but it cannot
handle heterogeneous agents models, nor models with generalized Euler
equation like those that emerge from discretionary policy problems or from
models with quasi-geometric discounting. \ Allowing for models that contain
generalized Euler equations is a topic for future work. \ Another set of
models that are not fully accommodated are those where the shocks are
contemporaneously correlated. \ Such models can be solved via the
perturbation methods, but not via the projection methods (due to the
techniques used for quadrature).

\section{The model file}

SolveDSGE requires that the model that is to be solved be stored in a model
file. \ The model file is simply a text file so there is nothing
particularly special about it. \ Every model file must contain the following
five information categories: \textquotedblleft states:\textquotedblright ,
\textquotedblleft jumps:\textquotedblright , \textquotedblleft
shocks:\textquotedblright , \textquotedblleft parameters:\textquotedblright
, and \textquotedblleft equations:\textquotedblright ; each category name
must end with a colon. \ Each category will begin with its name, such as
\textquotedblleft states:\textquotedblright\ and conclude with an
\textquotedblleft end\textquotedblright . \ The model file can present these
five categories in any order.

The information in each category can be presented with one element per line,
or with multiple elements on each line with each element separated by either
a comma or a semi-colon. \ So if the jump variables in the model are labor,
consumption, and output, then this could be presented in a variety of ways,
such as:

\bigskip

\textit{jumps:}

\textit{labor}

\textit{consumption}

\textit{output}

\textit{end}

\bigskip

or:

\textit{jumps:}

\textit{labor, consumption, output}

\textit{end}

\bigskip

or:

\textit{jumps:}

\textit{labor; consumption, output}

\textit{end}

\bigskip

The first lag of a variable is denoted with a -1, so the lag of consumption
is consumption(-1). \ Similarly the first lead of a variable is denoted with
a +1, so the lead of consumption is denoted consumption(+1). \ The first lag
of any model variable is automatically included as a state variable, second
and higher lags should be given a name, defined by an equation, and included
as state variables explicitly. \ The package may allow higher lags to
processed automatically at a later stage.

Shocks in the model refers to the innovations to the shock processes, so if
the shock process is given by%
\begin{equation*}
tech(+1)=rho\ast tech+sd\ast epsilon,
\end{equation*}%
then \textquotedblleft $tech$\textquotedblright\ will be a state variable,
\textquotedblleft $epsilon$\textquotedblright\ will be a shock, and
\textquotedblleft $rho$\textquotedblright\ and \textquotedblleft $sd$%
\textquotedblright\ will be parameters. \ If the model is deterministic,
then it will contain no shocks.

Every element in the parameters category and the equations category must
contain an \textquotedblleft $=$\textquotedblright\ sign, such as
\textquotedblleft $alpha=0.33$\textquotedblright\ in the case of the
parameters category and \textquotedblleft $output=exp(tech)\ast capital%
\symbol{94}alpha\ast labor\symbol{94}(1.0-alpha)$\textquotedblright\ in the
case of the equations category.

\subsection{Example}

The following is an example of a model file for the stochastic growth model:

\bigskip

\textit{states:}

\textit{cap, tech}

\textit{end}

\textit{\bigskip }

\textit{jumps:}

\textit{cons}

\textit{end}

\textit{\bigskip }

\textit{shocks:}

\textit{epsilon}

\textit{end}

\textit{\bigskip }

\textit{parameters:}

\textit{betta = 0.99}

\textit{sigma = 1.1}

\textit{delta = 0.025}

\textit{alpha = 0.30}

\textit{rho = 0.8}

\textit{sd = 0.01}

\textit{end}

\textit{\bigskip }

\textit{equations:}

\textit{cap(+1) = (1.0 - delta)*cap + exp(tech)*cap\symbol{94}alpha - cons}

\textit{cons\symbol{94}(-sigma) = betta*cons(+1)\symbol{94}(-sigma)*(1.0 -
delta + alpha*exp(tech(+1))*cap(+1)\symbol{94}(alpha - 1.0))}

\textit{tech(+1) = rho*tech + sd*epsilon}

\textit{end}

\section{Solving a model}

Solving a model is straightforward; it consists of the following steps:

\begin{enumerate}
\item Read and process the model file. \ During the processing the order of
variables in the system may be changed, typically the changes are to place
the shocks at the top of the system. \ After processing is complete you will
be told what the variable-order is.

\item Solve for the model's steady state.

\item Specify a SolutionScheme. \ A SolutionScheme specifies the solution
method along with any parameters needed to implement that solution method.

\item Solve the model according to the chosen SolutionScheme.
\end{enumerate}

\subsection{Reading the model and solving for its steady state}

To read and process a model file we simply supply the path/filename to the
get\_model() function, for example:

\bigskip

\textit{process\_model("c:/desktop/model.txt")}

\bigskip

The processed model is saved in the same folder as the model file, which in
then retrieved and stored in a structure:

\bigskip

\textit{dsge = retrieve\_processed\_model("c:/desktop/model\_processed.txt")}

\bigskip

We can then solve for the model's steady state as follows:

\bigskip

\textit{ss = compute\_steady\_state(dsge,tol,maxiters)}

\bigskip

where \textit{dsge} is the model whose steady state is to be computed,
\textit{tol} is a convergence tolerance, and \textit{maxiters} is an integer
specifying the maximum number of iterations before the function exits.

\subsection{Specifying a SolutionScheme}

To solve a model a SolutionScheme must be supplied. \ A SolutionScheme
specifies the solution method and the parameters upon which that solution
method relies. \ The solution methods in SolveDSGE are either perturbation
methods or projection methods. \ Accordingly, the SolutionSchemes can be
divided into PerturbationSchemes or ProjectionSchemes. \ We present each in
turn.

\subsubsection{PerturbationSchemes}

To solve a model using a perturbation method requires and
PerturbationScheme. \ Regardless of the model or the order of the
perturbation, a PerturbationScheme is a structure with three fields: the
point about which to perturb the model (the steady state), a cutoff
parameter that separates unstable from stable eigenvalues (eigenvalues whose
modulus is greater than cutoff will be placed in the model's unstable
block), and the order of the perturbation. \ For a first-order perturbation,
a typical PerturbationScheme might be the following

\bigskip

\textit{N = PerturbationScheme(ss,cutoff,"first")}

\bigskip

while those for second and third order perturbations might be

\bigskip

\textit{NN = PerturbationScheme(ss,cutoff,"second")}

\bigskip

and

\bigskip

\textit{NNN = PerturbationScheme(ss,cutoff,"third")}

\bigskip

The method used to compute a first-order perturbation follows Klein (2000),
that for a second-order perturbation follows Gomme and Klein (2011), while
that for a third-order perturbation follows Binning (2013) with a refinement
from Levintal (2017). \ At this point, perturbation solutions higher than
third order are not supported.

\subsubsection{ProjectionSchemes}

ProjectionSchemes are either ChebyshevSchemes, SmolyakSchemes, or
PiecewiseLinearSchemes, and for each of these there is a stochastic (for
stochastic models) and a deterministic (for deterministic models) version. \
The SolutionScheme for the deterministic case is a special case of the
stochastic one, so we focus on the stochastic case in what follows.

\paragraph{ChebyshevSchemes}

Solutions based on Chebyshev polynomials rely on and make use of all of the
functionality of the module ChebyshevApprox. \ This means that an arbitrary
number of state variables can be accommodated (if you have enough time!) and
both tenser-product and complete polynomials can be used. \ A stochastic
ChebyshevScheme requires the following arguments:

\begin{itemize}
\item initial\_guess --- This will usually be a vector containing the
model's steady state. \ It is used as the initial guess at the solution for
the case where an initializing solution is not provided (see the section on
model solution below).

\item node\_generator --- This is the name of the function used to generate
the nodes for the Chebyshev polynomial. \ Possible options include:
chebyshev\_nodes and chebyshev\_extrema.

\item node\_number --- This gives the number of nodes to be used for each
state variable. \ If there is only one state variables then node\_number
will be an integer. \ When there are two of more state variables it will be
a vector of integers.

\item num\_quad\_nodes --- This is an integer specifying the number of
quadrature points used to compute expectations.

\item order --- This defines the order of the Chebyshev polynomial to be
used in the approximating functions. \ For a complete polynomial order will
be an integer; for a tenser-product polynomial order will be a vector of
integers.

\item domain --- This contains the domain for the state variables over which
the solution is obtained. \ Domain will be a $2-$element vector in the
one-state-variable case and a $2\times n$ array in the $n$-state-variable
case, with the first row of the array containing the upper values of the
domain and the second row containing the lower values of the domain. \ If an
initializing solution is provided, then the domain associated with that
initializing solution can be used by setting domain to an empty array,
Float64[].

\item tol\_fix\_point\_solver --- This specifies the tolerance to be used in
the inner loop to determine convergence at each solution node.

\item tol\_variables --- This specifies the tolerance to be used in the
outer loop to determine convergence of the overall solution.

\item maxiters --- This is an integer specifying the maximum number of
outer-loop iterations before the solution exits.
\end{itemize}

\bigskip

An example of a stochastic ChebyshevScheme is:

\bigskip

\textit{C = ChebyshevSchemeStoch(ss,chebyshev\_nodes,[21,21], 9, 4,[0.1
30.0; -0.1 20.0],1e-8,1e-6,1000)}

\bigskip

In the deterministic case the number of quadrature nodes is not needed, i.e.,

\bigskip

\textit{Cdet = ChebyshevSchemeDet(ss,chebyshev\_nodes,[21,21],4,[0.1 30.0;
-0.1 20.0],1e-8,1e-6,1000)}

\paragraph{SmolyakSchemes}

Underlying the Smolyak polynomial based solution is the module
SmolyakApprox. \ This module allows for both isotropic polynomials and
ansiotropic polynomials and several different methods for producing nodes. \
SolveDSGE exploits all of this functionality. \ A stochastic SmolyakScheme
requires the following arguments:

\begin{itemize}
\item initial\_guess --- This will usually be a vector containing the
model's steady state. \ It is used as the initial guess at the solution for
the case where an initializing solution is not provided (see the section on
model solution below).

\item node\_generator ---This is the name of the function used to generate
the nodes for the Smolyak polynomial. \ Possible options include:
chebyshev\_gauss\_lobatto and clenshaw\_curtis\_equidistant

\item num\_quad\_nodes --- This is an integer specifying the number of
quadrature points used to compute expectations.

\item layer --- This is an integer (isotropic case) or a vector of integers
(ansiotropic case) specifying the number of layers to be used in the
approximation.

\item domain --- This contains the domain for the state variables over which
the solution is obtained. \ Domain will be a $2-$element vector in the
one-state-variable case and a $2\times n$ array in the $n$-state-variable
case, with the first row of the array containing the upper values of the
domain and the second row containing the lower values of the domain. \ If an
initializing solution is provided, then the domain associated with that
initializing solution can be used by setting domain to an empty array,
Float64[].

\item tol\_fix\_point\_solver --- This specifies the tolerance to be used in
the inner loop to determine convergence at each solution node.

\item tol\_variables --- This specifies the tolerance to be used in the
outer loop to determine convergence of the overall solution.

\item maxiters --- This is an integer specifying the maximum number of
outer-loop iterations before the solution exits.
\end{itemize}

\bigskip

An example of a stochastic SmolyakScheme is:

\bigskip

\textit{S = SmolyakSchemeStoch(ss,chebyshev\_gauss\_lobatto,9,3,[0.1 30.0;
-0.1 20.0],1e-8,1e-6,1000)}

\bigskip

In the deterministic case the number of quadrature nodes is not needed, i.e.,

\bigskip

\textit{Sdet = SmolyakSchemeDet(ss,chebyshev\_gauss\_lobatto,3,[0.1 30.0;
-0.1 20.0],1e-8,1e-6,1000)}

\paragraph{PiecewiseLinearSchemes}

To obtain piecewise linear solutions, SolveDSGE employs the module
PiecewiseLinearApprox, which allows approximations over an arbitrary number
of state variables. \ A stochastic PiecewiseLinearScheme requires the
following arguments:

\begin{itemize}
\item initial\_guess --- This will usually be a vector containing the
model's steady state. \ It is used as the initial guess at the solution for
the case where an initializing solution is not provided (see the section on
model solution below).

\item node\_number --- This gives the number of nodes to be used for each
state variable. \ If there is only one state variables then node\_number
will be an integer. \ When there are two of more state variables it will be
a vector of integers.

\item num\_quad\_nodes --- This is an integer specifying the number of
quadrature points used to compute expectations.

\item domain --- This contains the domain for the state variables over which
the solution is obtained. \ Domain will be a $2-$element vector in the
one-state-variable case and a $2\times n$ array in the $n$-state-variable
case, with the first row of the array containing the upper values of the
domain and the second row containing the lower values of the domain. \ If an
initializing solution is provided, then the domain associated with that
initializing solution can be used by setting domain to an empty array,
Float64[].

\item tol\_fix\_point\_solver --- This specifies the tolerance to be used in
the inner loop to determine convergence at each solution node.

\item tol\_variables --- This specifies the tolerance to be used in the
outer loop to determine convergence of the overall solution.

\item maxiters --- This is an integer specifying the maximum number of
outer-loop iterations before the solution exits.
\end{itemize}

\bigskip

An example of a stochastic PiecewiseLinearScheme is:

\bigskip

\textit{P = PiecewiseLinearStoch(ss,[21,21],9,[0.1 30.0; -0.1
20.0],1e-8,1e-6,1000)}

\bigskip

In the deterministic case the number of quadrature nodes is not needed, i,e,,

\bigskip

\textit{Pdet = PiecewiseLinearDet(ss,[21,21],9,[0.1 30.0; -0.1
20.0],1e-8,1e-6,1000)}

\subsection{Model solution}

Once a SolutionScheme is specified we are in a position to solve the model.
\ In order to do so we use the solve\_model() function, which takes either
two or three arguments. \ For a perturbation solution solve\_model()
requires two arguments: the model to be solved and the SolutionScheme, as
follows:

\bigskip

\textit{soln\_first\_order = solve\_model(dsge,N)}

\bigskip

\textit{soln\_second\_order = solve\_model(dsge,NN)}

\bigskip

\textit{soln\_third\_order = solve\_model(dsge,NNN)}

\bigskip

Alternatively, for a projection solution solve\_model() takes either two or
three arguments. \ To provide a concrete example, suppose we wish to solve
our model using Chebyshev polynomials. \ If we want the projection solution
to be initialized using the steady state, then solve\_model() requires only
two arguments: the model to be solved and the SolutionScheme:

\bigskip

\textit{soln\_chebyshev = solve\_model(dsge,C)}

\bigskip

If we want the projection solution to be initialized using the third order
perturbation solution, then solve\_model() requires three arguments: the
model to be solved, the initializing solution, and the SolutionScheme:

\bigskip

\textit{soln\_chebyshev = solve\_model(dsge,soln\_third\_order,C)}

\bigskip

Although this example uses a third order perturbation as the initializing
solution, any solution (first order, second order, third order, Chebyshev,
Smolyak, or piecewise linear) can be used.

\subsubsection{A comment on third-order perturbation}

Sometimes it can be useful to add skewness to the shocks, but this is not
easy to do through the model file. \ If you want your shocks to be skewed,
then you can access the third order perturbation solution by calling:

\bigskip

\textit{soln\_third\_order = solve\_third\_order(dsge,NNN,skewness)}

\bigskip

where skewness is a 2D array containing the skewness coefficients. \ If
there is only one shock, then the skewness array is:%
\begin{equation*}
skewness=E\left[ \epsilon _{1}\epsilon _{1}\epsilon _{1}\right] .
\end{equation*}%
If there are two shocks, then the skewness array is:%
\begin{equation*}
skewness=E\left[
\begin{array}{cccc}
\epsilon _{1}\epsilon _{1}\epsilon _{1} & \epsilon _{1}\epsilon _{1}\epsilon
_{2} & \epsilon _{1}\epsilon _{2}\epsilon _{1} & \epsilon _{1}\epsilon
_{2}\epsilon _{2} \\
\epsilon _{2}\epsilon _{1}\epsilon _{1} & \epsilon _{2}\epsilon _{1}\epsilon
_{2} & \epsilon _{2}\epsilon _{2}\epsilon _{1} & \epsilon _{2}\epsilon
_{2}\epsilon _{2}%
\end{array}%
\right] .
\end{equation*}%
Etc.

\subsubsection{Solution structures}

When a model is solved the solution is returned in the form of a structure.
\ The exact structure returned depends on the solution method.

\paragraph{First-order perturbation}

The first-order perturbation solution takes the following form:%
\begin{eqnarray*}
\mathbf{x}_{t+1} &=&\mathbf{h}_{\mathbf{x}}\mathbf{x}_{t}+\mathbf{k\epsilon }%
_{t+1}, \\
\mathbf{y}_{t} &=&\mathbf{g}_{\mathbf{x}}\mathbf{x}_{t}.
\end{eqnarray*}%
The solution structure for a stochastic first-order perturbation has the
following fields:

\begin{itemize}
\item hbar --- The steady state of the state variables

\item hx --- The first-order coefficients in the state-transition equation

\item k --- The loading matrix on the shocks in the state-transition
equation.

\item gbar --- The steady state of the jump variables

\item gx --- The first-order coefficients in the jump's equation

\item sigma --- An identy matrix

\item grc --- The number of eigenvalues with modulus greater than cutoff.

\item Soln\_type --- Either \textquotedblleft determinate\textquotedblright
, \textquotedblleft indeterminate\textquotedblright , or \textquotedblleft
unstable\textquotedblright .
\end{itemize}

The solution to a deterministic model has the same fields as the stochastic
solution with the exceptions of $\mathbf{k}$ and sigma.

\paragraph{Second-order perturbation}

The second-order perturbation solution takes the following form:%
\begin{eqnarray*}
\mathbf{x}_{t+1} &=&\mathbf{h}_{\mathbf{x}}\mathbf{x}_{t}+\frac{1}{2}\mathbf{%
h}_{\mathbf{ss}}+\frac{1}{2}\left( \mathbf{I}\otimes \mathbf{x}_{t}\right)
\mathbf{h}_{\mathbf{xx}}\left( \mathbf{I}\otimes \mathbf{x}_{t}\right) +%
\mathbf{k\epsilon }_{t+1}, \\
\mathbf{y}_{t} &=&\mathbf{g}_{\mathbf{x}}\mathbf{x}_{t}+\frac{1}{2}\mathbf{g}%
_{\mathbf{ss}}+\frac{1}{2}\left( \mathbf{I}\otimes \mathbf{x}_{t}\right)
\mathbf{g}_{\mathbf{xx}}\left( \mathbf{I}\otimes \mathbf{x}_{t}\right) .
\end{eqnarray*}

The solution structure for a stochastic second-order perturbation has the
following fields:

\begin{itemize}
\item hbar --- The steady state of the state variables

\item hx --- The first-order coefficients in the state-transition equation

\item hss --- The second-order stochastic adjustment to the mean in the
state-transion equation

\item hxx --- The second-order coefficients in the state-transition equation

\item k --- The loading matrix on the shocks in the state-transition
equation.

\item gbar --- The steady state of the jump variables

\item gx --- The first-order coefficients in the jump's equation

\item gss --- The second-order stochastic adjustment to the mean in the
jump's equation

\item gxx --- The second-order coefficients in the jump's equation

\item sigma --- An identy matrix

\item grc --- The number of eigenvalues with modulus greater than cutoff.

\item Soln\_type --- Either \textquotedblleft determinate\textquotedblright
, \textquotedblleft indeterminate\textquotedblright , or \textquotedblleft
unstable\textquotedblright .
\end{itemize}

The solution to a deterministic model has the same fields as the stochastic
solution with the exceptions of $\mathbf{h}_{\mathbf{ss}}$, $\mathbf{k}$, $%
\mathbf{g}_{\mathbf{ss}}$, and sigma.

\paragraph{Third-order perturbation}

The third-order perturbation solution takes the following form:%
\begin{eqnarray*}
\mathbf{x}_{t+1} &=&\mathbf{h}_{\mathbf{x}}\mathbf{x}_{t}+\frac{1}{2}\mathbf{%
h}_{\mathbf{ss}}+\frac{1}{2}\mathbf{h}_{\mathbf{xx}}\left( \mathbf{x}%
_{t}\otimes \mathbf{x}_{t}\right) +\frac{1}{6}\mathbf{h}_{\mathbf{sss}}+%
\frac{1}{6}\mathbf{h}_{\mathbf{ssx}}\mathbf{x}_{t}+\frac{1}{6}\mathbf{h}_{%
\mathbf{xxx}}\left( \mathbf{x}_{t}\otimes \mathbf{x}_{t}\otimes \mathbf{x}%
_{t}\right) +\mathbf{k\epsilon }_{t+1}, \\
\mathbf{y}_{t} &=&\mathbf{g}_{\mathbf{x}}\mathbf{x}_{t}+\frac{1}{2}\mathbf{g}%
_{\mathbf{ss}}+\frac{1}{2}\mathbf{g}_{\mathbf{xx}}\left( \mathbf{x}%
_{t}\otimes \mathbf{x}_{t}\right) +\frac{1}{6}\mathbf{g}_{\mathbf{sss}}+%
\frac{1}{6}\mathbf{g}_{\mathbf{ssx}}\mathbf{x}_{t}+\frac{1}{6}\mathbf{g}_{%
\mathbf{xxx}}\left( \mathbf{x}_{t}\otimes \mathbf{x}_{t}\otimes \mathbf{x}%
_{t}\right) .
\end{eqnarray*}

The solution structure for a stochastic third-order perturbation has the
following fields:

\begin{itemize}
\item hbar --- The steady state of the state variables

\item hx --- The first-order coefficients in the state-transition equation

\item hss --- The second-order stochastic adjustment to the mean in the
state-transion equation

\item hxx --- The second-order coefficients in the state-transition equation

\item hsss --- The third-order stochastic adjustment to the mean in the
state-transition equation

\item hssx --- The skewness adjustment \ othe state-transition equation

\item hxxx --- The third-order coefficents in the state-transition equation

\item k --- The loading matrix on the shocks in the state-transition
equation.

\item gbar --- The steady state of the jump variables

\item gx --- The first-order coefficients in the jump's equation

\item gss --- The second-order stochastic adjustment \ othe mean in the
jump's equation

\item gxx --- The second-order coefficients in the jump's equation

\item gsss --- The third-order stochastic adjustment to the mean in the
jump's equation

\item gssx --- The skewness adjustment in the jump's equation

\item gxxx --- The third-order coefficients in the jump's equation

\item sigma --- An identy matrix

\item grc --- The number of eigenvalues with modulus greater than cutoff.

\item Soln\_type --- Either \textquotedblleft determinate\textquotedblright
, \textquotedblleft indeterminate\textquotedblright , or \textquotedblleft
unstable\textquotedblright .
\end{itemize}

The solution to a deterministic model has the same fields as the stochastic
solution with the exceptions of $\mathbf{h}_{\mathbf{ss}}$, $\mathbf{h}_{%
\mathbf{sss}}$, $\mathbf{h}_{\mathbf{ssx}}$, $\mathbf{k}$, $\mathbf{g}_{%
\mathbf{ss}}$, $\mathbf{g}_{\mathbf{sss}}$, $\mathbf{g}_{\mathbf{ssx}}$, and
sigma.

\paragraph{Chebyshev solution}

The solution structure for the Chebyshev solution has the following fields:

\begin{itemize}
\item variables \ --- A vector of arrays containing the solution for each
variable

\item weights --- A vector of arrays containing the weights for the
Chebyshev polynomials

\item nodes --- A vector of vectors containing the Chebyshev nodes

\item order --- The order of the Chebyshev polynomials

\item domain --- The domain for the state variables

\item sigma --- The variance-covariance matrix for the shocks

\item iteration\_count --- The number of iterations needed to achieve
convergence
\end{itemize}

The solution to a deterministic model has the same fields with the exception
of sigma.

\paragraph{Smolyak solution}

The solution structure for the Smolyak solution has the following fields:

\begin{itemize}
\item variables --- A vector of arrays containing the solution for each
variable

\item weights: --- A vector of vectors containing the weights for the
Chebyshev polynomials

\item grid --- A matrix containing the Smolyak grid

\item multi\_index --- A matrix containing the multi-index underlying the
polynominals

\item layer --- The number of layers in the approximation

\item domain --- The domain for the state variables

\item sigma --- The variance-covariance matrix for the shocks

\item iteration\_count --- The number of iterations needed to achieve
convergence
\end{itemize}

The solution to a deterministic model has the same fields with the exception
of sigma.

\paragraph{Piecewise linear solution}

The solution structure for the piecewise linear solution has the following
fields:

\begin{itemize}
\item variables --- A vector of arrays containing the solution for each
variable

\item nodes --- A vector of vectors containing the Chebyshev nodes

\item domain --- The domain for the state variables

\item sigma --- The variance-covariance matrix for the shocks

\item iteration\_count --- The number of iterations needed to achieve
convergence
\end{itemize}

The solution to a deterministic model has the same fildls with the exception
of sigma.

\section{Post-solution analysis}

Once you have solved your model there are many things that you might want to
use the solution for. \ Some of the more obvious things, such as simulating
data from the solution and computing impulse response functions have been
built into SolveDSGE to make things easier for you.

\subsection{Simulation}

To simulate data from the solution to a model the function to use is
simulate(), whose arguments are a model solution, an initial state, and the
number of observations to simulate. \ An optimal final argument is the seed
for the random number generator. \ An example of simulate() in action would
be:

\bigskip

\textit{data\_states, data\_jumps = simulate(soln,[0.0, 25.0],100000)}

\bigskip

As this example makes clear, the simulate function returns two 2D arrays. \
The first array contains simulated data for the state variables, the second
array contains simulated data for the jump variables. \ The simulate
function can be applied to both stochastic and deterministic models.

\subsection{Impulse response functions}

Impulse responses are obtained using the impulses() function, which takes
three arguments: the model solution, the length of the impulse response
function (number of periods), the nature of the impulse to apply, and the
number of repetitions to use for the Monte Carlo integration. \ Responses to
both a positive and a negative innovation are generated. \ An optimal final
argument is the seed for the random number generator. \ For a model with two
shocks, an example of impulses() in use would be:

\bigskip

\textit{pos\_responses, neg\_responses = impulses(soln,50,[2,0],10000)}

\bigskip

which applies a two standard deviation impulse to the first shock and no
impulse to the second shock. \ For the nonlinear solutions (second-order
perturbation, third-order perturbation, and the projection-based solutions)
the initial state is \textquotedblleft integrated-out\textquotedblright\ via
a Monte Carlo that averages over draws taken from the unconditional
distribution of the state variables. \ At this stage in the package's
development, the impulses need to be computed one shock at a time; this will
probably change at some point.

\subsection{PDFs and CDFs}

SolveDSGE contains functions for approximating the probability density
function and the cumulative distribution function of a variable, where the
approximation is based on Fourier series (Kronmal and Tarter, 1968). \ Most
of the functionality relates to the univariate case, but some functionality
is included to approximate and evaluate the PDF\ in the multivariate case.

\subsubsection{Univariate}

To approximate the probability density function and evaluate the
approximated function at a point the function is:

\bigskip

\textit{f =
approximate\_density(sample,point,order,lower\_bound,upper\_bound)}

\bigskip

where \textit{sample} is a vector of data, \textit{point} is the value at
which the PDF is evaluated, \textit{order} is the order of the Fourier
series approximation, and \textit{lower\_bound} and \textit{upper\_bound}
specify the support over which the PDF is constructed. \ If an approximation
of the entire PDF is sought, then the function is:

\bigskip

\textit{nodesf, f =
approximate\_density(sample,order,lower\_bound,upper\_bound)}

\bigskip

Similarly, the cumulative distribution function is approximated and
evaluated at a point using the function:

\bigskip

\textit{F =
approximate\_distribution(sample,point,order,lower\_bound,upper\_bound)}

\bigskip

where \textit{sample} is a vector of data, \textit{point} is the value at
which the CDF is evaluated, \textit{order} is the order of the Fourier
series approximation, and \textit{lower\_bound} and \textit{upper\_bound}
specify the support over which the CDF is constructed. \ If an approximation
of the entire CDF is sought, then the function is:

\bigskip

\textit{nodesF, F =
approximate\_distribution(sample,order,lower\_bound,upper\_bound)}

\bigskip

\subsubsection{Multivariate}

In the multivaraite case the PDF can be approximated and evaluated at a
point using the function:

\bigskip

\textit{f =
approximate\_density(sample,point,order,lower\_bound,upper\_bound)}

\bigskip

where \textit{sample} is a 2D array of data, \textit{point} is a vector,
\textit{order} is a vector of integers, and \textit{lower\_bound} and
\textit{upper\_bound} are vectors. \ Similarly, the CDF can be approximated
and evaluated at a point using the function:

\bigskip

\textit{F =
approximate\_distribution(sample,point,order,lower\_bound,upper\_bound)}

\bigskip

where \textit{sample} is a 2D array of data, \textit{point} is a vector,
\textit{order} is a vector of integers, and \textit{lower\_bound} and
\textit{upper\_bound} are vectors.

\subsection{Evaluating accuracy}

At this point SolveDSGE doesn't have routines to assess numerical accuracy
according to conventional metrics like Euler equation errors. \ What
SolveDSGE does do, however, is compare two solutions and assess the
magnitudes of any differences. \ This facilitates an adaptive approach to
approximation and it allows robustness of the solution to be assessed across
approximation schemes. \ When comparing two models, SolveDSGE looks at the
predicted values for the jump variables, returning the maximum absolute
difference for each jump variable found for a random sample of 100,000
realizations of the state variables. \ We compare two solution according to:

\bigskip

\textit{errors = compare\_solutions(solna,solnb,domain,seed)}

\bigskip

where \textit{solna} and \textit{solnb} are the two solutions to be
compared, \textit{domain} is the domain for the state variables over which
the comparison takes place, and \textit{seed} is an optional argument that
sets the seed for the random number generator.

\begin{thebibliography}{99}
\bibitem{} Andreasen, M., Fern\'{a}ndez-Villaverde, J., and J.
Rubio-Ramirez, (2017), \textquotedblleft The Pruned State-Space System for
Non-Linear DSGE Models: Theory and Empirical Applications\textquotedblright
, \textit{Review of Economic Studies}, 0, pp. 1---49.

\bibitem{} Binning, A., (2013), \textquotedblleft Third-order approximation
of dynamic models without the use of tensors\textquotedblright , \textit{%
Norges Bank Working Paper} 2013--13.

\bibitem{} Gomme, P., and P. Klein, (2011), \textquotedblleft Second-Order
Approximation of Dynamic Models Without the Use of Tensors\textquotedblright
, \textit{Journal of Economic Dynamics and Control}, 35, pp. 604---615.

\bibitem{} Judd, K. (1992), \textquotedblleft Projection Methods for Solving
Aggregate Growth Models\textquotedblright , \textit{Journal of Economic
Theory}, 58, pp.410---452.

\bibitem{} Judd, K., Maliar, L., Maliar, S., and R. Valero, (2014),
\textquotedblleft Smolyak Method for Solving Dynamic Economic Models:
Lagrange Interpolation, Anisotropic Grid and Adaptive
Domain\textquotedblright , \textit{Journal of Economic Dynamics and Control}%
, 44, pp. 92---123.

\bibitem{} Judd, K., Maliar, L., Maliar, S., and I. Tsener, (2017),
\textquotedblleft How to Solve Dynamic Stochastic Models Computing
Expectations just Once\textquotedblright , \textit{Quantitative Economics},
8, pp.851---893.

\bibitem{} Klein, P., (2000), \textquotedblleft Using the Generalized Schur
Form to Solve a Multivariate Linear Rational Expectations
Model\textquotedblright , \textit{Journal of Economic Dynamics and Control},
24, pp. 1405---1423.

\bibitem{} Kronmal, R., and M. Tarter, (1968), \textquotedblleft The
Estimation of Probability Densities and Cumulatives by Fourier Series
Methods\textquotedblright , \textit{Journal of the American Statistical
Association}, 63, 323, pp.925--952.

\bibitem{} Levintal, O., (2017), \textquotedblleft Fifth-Order Perturbation
Solution to DSGE models\textquotedblright , \textit{Journal of Economic
Dynamics and Control}, 80, pp. 1--16.

\bibitem{} Potter, S., (2000), \textquotedblleft Nonlinear Impulse Response
Functions\textquotedblright , \textit{Journal of Economic Dynamics and
Control}, 24, pp. 1425---1446.
\end{thebibliography}

\end{document}


\XtoCBlock{L2Norm}
\label{block:L2Norm}
\begin{figure}[H]\includegraphics{L2Norm}\end{figure}

\begin{XtoCtabular}{Inports}
u1 & Input u1\tabularnewline
\hline
u2 & Input u2\tabularnewline
\hline
\end{XtoCtabular}

\begin{XtoCtabular}{Outports}
Out & Euclidean norm of u1 and u2\tabularnewline
\hline
\end{XtoCtabular}

\subsubsection*{Description:}
Calculation of L2-norm (euclidean norm).

% include optional documentation file
\InputIfFileExists{\XcHomePath/Library/Math/Doc/L2Norm_Info.tex}{\vspace{1ex}}{}

\subsubsection*{Implementations:}
\begin{tabular}{l l}
\textbf{FiP8} & 8 Bit Fixed Point Implementation\tabularnewline
\textbf{FiP16} & 16 Bit Fixed Point Implementation\tabularnewline
\textbf{FiP32} & 32 Bit Fixed Point Implementation\tabularnewline
\textbf{Float32} & 32 Bit Floating Point Implementation\tabularnewline
\textbf{Float64} & 64 Bit Floating Point Implementation\tabularnewline
\end{tabular}

\XtoCImplementation{FiP8}
\index{Block ID!5056}
\nopagebreak[0]
% Implementation details
\begin{tabular}{l l}
\textbf{Name} & FiP8 \tabularnewline
\textbf{ID} & 5056 \tabularnewline
\textbf{Revision} & 0.1 \tabularnewline
\textbf{C filename} & L2Norm\_FiP8.c \tabularnewline
\textbf{H filename} & L2Norm\_FiP8.h \tabularnewline
\end{tabular}
\vspace{1ex}

8 Bit Fixed Point Implementation

% Implementation data structure
\XtoCDataStruct{Data Structure:}
\begin{lstlisting}
typedef struct {
     uint16        ID;
     int8          *u1;
     int8          *u2;
     int8          Out;
} L2NORM_FIP8;
\end{lstlisting}

\ifdefined \AddTestReports
\InputIfFileExists{\XcHomePath/Library/Math/Doc/Test_L2Norm_FiP8.tex}{}{}
\fi
\XtoCImplementation{FiP16}
\index{Block ID!5057}
\nopagebreak[0]
% Implementation details
\begin{tabular}{l l}
\textbf{Name} & FiP16 \tabularnewline
\textbf{ID} & 5057 \tabularnewline
\textbf{Revision} & 0.1 \tabularnewline
\textbf{C filename} & L2Norm\_FiP16.c \tabularnewline
\textbf{H filename} & L2Norm\_FiP16.h \tabularnewline
\end{tabular}
\vspace{1ex}

16 Bit Fixed Point Implementation

% Implementation data structure
\XtoCDataStruct{Data Structure:}
\begin{lstlisting}
typedef struct {
     uint16        ID;
     int16         *u1;
     int16         *u2;
     int16         Out;
} L2NORM_FIP16;
\end{lstlisting}

\ifdefined \AddTestReports
\InputIfFileExists{\XcHomePath/Library/Math/Doc/Test_L2Norm_FiP16.tex}{}{}
\fi
\XtoCImplementation{FiP32}
\index{Block ID!5058}
\nopagebreak[0]
% Implementation details
\begin{tabular}{l l}
\textbf{Name} & FiP32 \tabularnewline
\textbf{ID} & 5058 \tabularnewline
\textbf{Revision} & 0.1 \tabularnewline
\textbf{C filename} & L2Norm\_FiP32.c \tabularnewline
\textbf{H filename} & L2Norm\_FiP32.h \tabularnewline
\end{tabular}
\vspace{1ex}

32 Bit Fixed Point Implementation

% Implementation data structure
\XtoCDataStruct{Data Structure:}
\begin{lstlisting}
typedef struct {
     uint16        ID;
     int32         *u1;
     int32         *u2;
     int32         Out;
} L2NORM_FIP32;
\end{lstlisting}

\ifdefined \AddTestReports
\InputIfFileExists{\XcHomePath/Library/Math/Doc/Test_L2Norm_FiP32.tex}{}{}
\fi
\XtoCImplementation{Float32}
\index{Block ID!5059}
\nopagebreak[0]
% Implementation details
\begin{tabular}{l l}
\textbf{Name} & Float32 \tabularnewline
\textbf{ID} & 5059 \tabularnewline
\textbf{Revision} & 0.1 \tabularnewline
\textbf{C filename} & L2Norm\_Float32.c \tabularnewline
\textbf{H filename} & L2Norm\_Float32.h \tabularnewline
\end{tabular}
\vspace{1ex}

32 Bit Floating Point Implementation

% Implementation data structure
\XtoCDataStruct{Data Structure:}
\begin{lstlisting}
typedef struct {
     uint16        ID;
     float32       *u1;
     float32       *u2;
     float32       Out;
} L2NORM_FLOAT32;
\end{lstlisting}

\ifdefined \AddTestReports
\InputIfFileExists{\XcHomePath/Library/Math/Doc/Test_L2Norm_Float32.tex}{}{}
\fi
\XtoCImplementation{Float64}
\index{Block ID!5060}
\nopagebreak[0]
% Implementation details
\begin{tabular}{l l}
\textbf{Name} & Float64 \tabularnewline
\textbf{ID} & 5060 \tabularnewline
\textbf{Revision} & 0.1 \tabularnewline
\textbf{C filename} & L2Norm\_Float64.c \tabularnewline
\textbf{H filename} & L2Norm\_Float64.h \tabularnewline
\end{tabular}
\vspace{1ex}

64 Bit Floating Point Implementation

% Implementation data structure
\XtoCDataStruct{Data Structure:}
\begin{lstlisting}
typedef struct {
     uint16        ID;
     float64       *u1;
     float32       *u2;
     float64       Out;
} L2NORM_FLOAT64;
\end{lstlisting}

\ifdefined \AddTestReports
\InputIfFileExists{\XcHomePath/Library/Math/Doc/Test_L2Norm_Float64.tex}{}{}
\fi