% !TEX TS-program = pdflatex
% !TEX encoding = UTF-8 Unicode

% This is a simple template for a LaTeX document using the "article" class.
% See "book", "report", "letter" for other types of document.

\documentclass[10pt]{article} % use larger type; default would be 10pt
\usepackage{graphicx}
\usepackage{float}
\usepackage{caption}
\usepackage[utf8]{inputenc} % set input encoding (not needed with XeLaTeX)
\usepackage{amsmath,amsthm,amsfonts}
\usepackage{mathabx}
\usepackage{graphicx}
\usepackage{algorithm}
\usepackage{algorithmic}
\usepackage{hyperref}
\usepackage{listings}
\usepackage{textcomp}
%%% Examples of Article customizations
% These packages are optional, depending whether you want the features they provide.
% See the LaTeX Companion or other references for full information.

%For improved new command:
%(defining macros)
\usepackage{xparse}
%An example with optinal commands.
\NewDocumentCommand\optmin{mgg}%
{\begin{align*}
\text{minimize}&\quad {#1}\IfNoValueTF{#2}{}{\\
\text{subject to}&\quad {#2}}\IfNoValueTF{#3}{}{\\&\quad {#3}}
\end{align*}
}

%%% PAGE DIMENSIONS
\usepackage{geometry} % to change the page dimensions
\geometry{letterpaper} % or letterpaper (US) or a5paper or....
% \geometry{margin=2in} % for example, change the margins to 2 inches all round
% \geometry{landscape} % set up the page for landscape
%   read geometry.pdf for detailed page layout information

\usepackage{graphicx} % support the \includegraphics command and options
% \usepackage[parfill]{parskip} % Activate to begin paragraphs with an empty line rather than an indent

%%% PACKAGES
\usepackage{booktabs} % for much better looking tables
\usepackage{array} % for better arrays (eg matrices) in maths
\usepackage[section]{placeins} % With FloatBarrier control float
\usepackage{paralist} % very flexible & customisable lists (eg. enumerate/itemize, etc.)
\usepackage{verbatim}
%Setup listing for better matlab code display
\usepackage{listings}
\usepackage{color}
\usepackage{textcomp}
\definecolor{listinggray}{gray}{0.9}
\definecolor{lbcolor}{rgb}{0.9,0.9,0.9}
\lstset{
	backgroundcolor=\color{lbcolor},
	tabsize=4,
	rulecolor=,
	language=c++,
        basicstyle=\scriptsize,
        upquote=true,
        aboveskip={1.5\baselineskip},
        columns=fixed,
        showstringspaces=false,
        extendedchars=true,
        breaklines=true,
        prebreak = \raisebox{0ex}[0ex][0ex]{\ensuremath{\hookleftarrow}},
        frame=single,
        showtabs=false,
        showspaces=false,
        showstringspaces=false,
        identifierstyle=\ttfamily,
        keywordstyle=\color[rgb]{0,0,1},
        commentstyle=\color[rgb]{0.133,0.545,0.133},
        stringstyle=\color[rgb]{0.627,0.126,0.941},
}
% adds environment for commenting out blocks of text & for better verbatim
\usepackage{subfig} % make it possible to include more than one captioned figure/table in a single float
% These packages are all incorporated in the memoir class to one degree or another...

%%% HEADERS & FOOTERS
\usepackage{fancyhdr} % This should be set AFTER setting up the page geometry
\pagestyle{plain} % options: empty , plain , fancy
\renewcommand{\headrulewidth}{0pt} % customise the layout...
\lhead{}\chead{}\rhead{}
\lfoot{}\cfoot{\thepage}\rfoot{}

%%% SECTION TITLE APPEARANCE
\usepackage{sectsty}
\allsectionsfont{\sffamily\mdseries\upshape} % (See the fntguide.pdf for font help)
% (This matches ConTeXt defaults)

%%% ToC (table of contents) APPEARANCE
\usepackage[nottoc,notlof,notlot]{tocbibind} % Put the bibliography in the ToC
\usepackage[titles,subfigure]{tocloft} % Alter the style of the Table of Contents
\usepackage{tikz}
\usetikzlibrary{arrows}
\usetikzlibrary{calc}
\renewcommand{\cftsecfont}{\rmfamily\mdseries\upshape}
\renewcommand{\cftsecpagefont}{\rmfamily\mdseries\upshape} % No bold!

%%% shortcuts %%%
\newcommand{\heading}[1]{\vspace{1ex}\par\noindent{\bf #1}}
\def\immediateFigure#1{%
\smallskip\begin{center}#1\end{center}\smallskip }
\newcommand{\immfigw}[2] % immediate figure with prescribed width
{\immediateFigure{\mbox{\includegraphics[width=#2]{#1}}}}
\newcommand\eps{\varepsilon}
\newcommand*\colvec[3][]{
    \begin{bmatrix}\ifx\relax#1\relax\else#1\\\fi#2\\#3\end{bmatrix}
}
\newcommand\scalemath[2]{\scalebox{#1}{\mbox{\ensuremath{\displaystyle #2}}}}
\newcommand\vectt[1]{\boldsymbol{#1}}
\newcommand\inprod[2]{\langle{#1},{#2}\rangle}

%Shorthand for summation
\NewDocumentCommand\sumito{mmg}
{\sum_{\IfNoValueTF{#3}{i = 1}{i = {#3}}}^{#1}{#2}}
\NewDocumentCommand\sumjto{mmg}
{\sum_{\IfNoValueTF{#3}{j = 1}{j = {#3}}}^{#1}{#2}}
\NewDocumentCommand\sumkto{mmg}
{\sum_{\IfNoValueTF{#3}{k = 1}{k = {#3}}}^{#1}{#2}}
\NewDocumentCommand\sumlto{mmg}
{\sum_{\IfNoValueTF{#3}{l = 1}{l = {#3}}}^{#1}{#2}}

%%% END Article customizations
\newcommand\tsub[2]{{#1}_{\text{#2}}}
\newcommand\tsup[2]{{#1}^{\text{#2}}}
\newcommand\tspb[3]{{#1}^{\text{#2}}_{\text{#3}}}
\newcommand\RR{\mathbb{R}}
\newcommand\iprod[2]{\langle{#1},{#2}\rangle}
%%%Generates program flow chart using tikz
\usepackage{tikz}
\usetikzlibrary{shapes,arrows,positioning}
\tikzstyle{decision} = [diamond, draw, fill=blue!20,
    text width=6em, text badly centered, node distance=3cm, inner sep=0pt]
\tikzstyle{block} = [rectangle, draw, fill=blue!20,
    text width=8em, text centered, rounded corners, minimum height=4em]
\tikzstyle{line} = [draw, -latex']
\tikzstyle{cloud} = [draw, ellipse,fill=red!20, node distance=3cm,
    minimum height=2em]
%%%Commands below for this specific document only
\newcommand\infnorm[1]{\|{#1}\|_\infty}
\newcommand\set[1]{\left\{{#1}\right\}}
\NewDocumentCommand\norm{mg}
{\|{#1}\|\IfNoValueTF{#2}{}{_{#2}}}
\newcommand\cunit{C([0,1])}
\DeclareMathOperator{\tr}{tr}
\DeclareMathOperator*{\argmin}{argmin}
\newcommand\bSigma{\mathbf{\Sigma}}
\newcommand\bx{\mathbf{x}}
\newcommand\bv{\mathbf{v}}
\newcommand\bK{\mathbf{K}}
\newcommand\bJ{\mathbf{J}}
\newcommand\bM{\mathbf{M}}
%%% The "real" document content comes below...

\title{Appendix A: user manual for the particle method library}

\author{\sc Ningyuan WANG\\Daniel FORGER
}

\begin{document}
\setlength{\parindent}{0pt}
\maketitle

\section{Building and running the example program with Hodgkin-Huxley model}
\subsection{Structure of the repository}
This repository contains the source code for the method, in the form of a \texttt{C++} library, that consists of \texttt{particle\_method.h} and \texttt{particle\_method.cpp}, as well as an example program, which serves as a suggestion on how the library can be used. The example can be viewed by opening the \texttt{minimal\_HH\_mat\_example.sln} solution file.
The code is written using \texttt{C++}, and the example cmake project is tested to work on a \texttt{Windows} machine using \texttt{Microsoft Visual studio 2019}. The instruction will be based on this environment though the principle for building this program on other platform should be similar.
\subsection{Generating project on \texttt{Windows} using \texttt{cmake-gui}}
The list of required libraries are listed according the specific header and source file loaded. \texttt{cmake} is used to automatically find all the required libraries and generate the project file based on environment. When configuring the \texttt{cmake} project, make sure \texttt{x64} is selected:

\begin{itemize}
\item
\texttt{particle\_method.h} and \texttt{particle\_method.cpp}

There are two options for building these files. If macro \texttt{MATLAB\_VISUALIZE} is enabled, then \texttt{matlab} is required, and \texttt{libeng.lib;libmx.lib;libmat.lib;} are library files needed to be added at \texttt{Linker\textrightarrow Input\textrightarrow Additional dependencies} in the project property pages. Please refer to \href{www.mathworks.com/matlabcentral/answers/406574-how-can-i-compile-a-c-program-that-uses-matlab-engine-c-api-in-visual-studio-2017}{this page from mathworks website} for further instruction. The example project is configured with \texttt{MATLAB\_VISUALIZE} enabled.
\begin{figure}[H]
\includegraphics[width=0.5 \textwidth]{cmake_step1}
\caption{Select \texttt{x64} platform when configuring project}
\end{figure}
Alternatively, when real-time visualization is not required and the use of a commercial software is not preferred, the \texttt{HDF5} serves as an alternative data input output library.

Independent of the two options, \texttt{intel-tbb} is required for parallel computing. Additionally, \texttt{boost} and \texttt{Eigen} are libraries required.

\item
\texttt{minimal\_XX\_neuron\_example.cpp}

The \texttt{boost-program-options} is needed to compile this file. If \texttt{vcpkg} is not used, then the correct version of \texttt{libboost\_program\_options} needs to be added to \texttt{Linker\textrightarrow Input\textrightarrow Additional dependencies}.
\item
\texttt{set\_XX\_eqns.h}
This header file does not require additional library to build.
\end{itemize}
\begin{figure}[H]
\includegraphics[width=0.7 \textwidth]{cmake_step2}
\caption{An example variables if \texttt{cmake} project is configured correctly.}
\end{figure}
\subsection{Building the program}

The projects in the solution are set to use the \texttt{matlab} version out-of-box. The program should build with one click if the external libraries are correctly set.

\subsection{Common issues and solution}
\begin{itemize}
\item
\texttt{LNK2001} at build time. Likely due to libraries not setup correctly, which may occur either when library is missing, or different versions of the same library exist. Using \texttt{vcpkg} would reduce the chance of this happening than manually tracing each library.
\item
undefined reference to \texttt{some\_function} at \texttt{xx.dll} at run time. In addition to the common cause of not properly setting the correct version of \texttt{matlab}, this is also likely to be caused by a conflict in \texttt{dll} file. \texttt{HDF5} and \texttt{matlab} both comes with \texttt{hdf5.dll}, however they are not interchangeable. To make sure the correct \texttt{dll} is loaded, check if \texttt{hdf5.dll} exist in current directory or the \texttt{Windows\textbackslash System32} directory. Then, the order of the directories stored in system \texttt{PATH} variable would determine which \texttt{hdf5.dll} will be used.
\end{itemize}
\subsection{Running the example program}
The program uses \texttt{boost::program\_options} to parse options, and help info can be accessed using the \texttt{-h} option:
\begin{figure}[H]
\includegraphics[width=\textwidth]{help_message}
\caption{Help message produced by the program}
\end{figure}

By default, the program will not produce any visual output as \texttt{-i (--plot\_interval) = 0}, and the only output files are \texttt{HHTestatend.mat}, which stores the end condition of the system as a linear combination of particles, and \texttt{coupling\_strength\_diff\_X\_coup\_Y.mat}, which logs the coupling strength, averaged membrane potential, and particle count through the process.

Using the \texttt{-i \%d} option will generate a visualization that looks as follows:
\begin{figure}[H]
\includegraphics[width=\textwidth]{visualization_screenshot}
\caption{A screenshot of the visualization}
\end{figure}
Note that the plots, especially the density heat map is computationally intensive, and will significantly slow down the program.
\subsection{Program options in the example program}
\begin{itemize}
\item
\texttt{-d --diffusion\_coeff}
Changes the diffusion coefficient. The diffusion coefficient is set to be isotropic in this example program.
\item
\texttt{--tol}
Tolerance for the linear approximation, as relative error, before a particle needs to be split. Increasing tolerance decreases the number of particles, however it can lead to inaccurate results.
\item
\texttt{-s --stepsize} Maximum step size for the adaptive time step differential equation solver. Increasing time step may lead to slower computation time as additional split of particles may be introduced during each time step.
\item
\texttt{-p --projection\_dimension}
Index of dimensions to project to in the scatter plot of population density. The projection can be onto a 1,2, or 3 dimensional subspace. The index starts at 0.
\item
\texttt{-q --density\_projection\_dimension}
Index of dimensions to project to in the density plot of population density. The projection can be onto a 1 or 2 dimensional subspace. The index starts at 0.
\item
\texttt{-v --video}
Generates a video of all plots drawn during the duration of the simulation. Please note that in \texttt{matlab 2019b} or later versions, the default save location for the video is the folder where the \texttt{matlab} executable file is located, instead of the folder where this example program is located. To change the behavior, use \texttt{cd} command in \texttt{matlab} to change the output path to the desired location.
\end{itemize}
\section{Adapting the program to different problems}
The example program is called \emph{minimal} in the sense that only the most common parameters can be adjusted at run time, whereas the model and other parameters are determined at compile time, in order to present a short example. To adapt the program to a different model, the following areas needs to be considered:
\subsection{Modifying models and parameters}
\label{str:Advdiffeqn}
In the example project, the models are contained in the \texttt{set\_hh\_eqns.h} and \texttt{set\_SAN\_eqns.h} for the Hodgkin-Huxley and Simplified averaged neuron model respectively. To set a model, a custom \texttt{struct Advection\_diffusion\_eqn} with the following properties needs to be defined:
\begin{lstlisting}
    vector_vector_function advection_velocity; //defines the time derivative of the system
    coupling_strength_function coupling_strength; //defines the strength of coupling output from a pre-synaptic neuron
    coupling_velocity_function coupling_velocity; // defines how a post-synaptic neuron is affected given a coupling input
    Matrix_type diffusion_coefficient; // a matrix-valued diffusion coefficient
    const index_type dimension; // Dimension of state space
    const bool state_variable_always_valid;// Is true when the state_variable can take any value as long as dimension is correct. Is false when the equation is only valid for a subset of the state space.
\end{lstlisting}
Additionally, if \texttt{state\_variable\_always\_valid} is false, then the following properties are also required:
\begin{lstlisting}
    vector_bool_function state_variable_in_domain;//Returns true if the variable is inside the domain.
    vector_vector_function state_variable_restrict_to_domain;//A method that maps particles out of domain back inside. (Such particles can be produced when particles are splitted.)
    //Note: Since a lambda function cannot change value of input
\end{lstlisting}
The following are two examples of \texttt{struct Advection\_diffusion\_eqn}.

The first example is the $2$-dimensional Van der Pol oscillator with that is coupled by the average value in the first variable:
\begin{lstlisting}
Advection_diffusion_eqn* set_van_der_pol_eqn(const value_type diffusion_coeff) {
    auto eqn_ptr = new Advection_diffusion_eqn(2, diffusion_coeff, true);//defines a 2-dimensional state space with an overloaded diffusion coefficient that is symmetric in each direction (i.e. diffusion coefficient matrix is identity matrix multiplied by scalar diffusion coefficient), and the state variable domain is the whole space.
    vector_vector_function advection_dynamics; //declares dynamics as a vector-valued function
    coupling_velocity_function coupling_velocity;//declares coupling velocity function (see example below)
    coupling_strength_function coupling_strength;//declares coupling strength function (see example below)
    //advection_dynamics is defined as the following lambda-function that returns the time derivative dxdt given the state variable x:
    advection_dynamics = [](const State_variable& x) {
        value_type mu = 1.5;
        State_variable dxdt(2);
        dxdt[0] = mu * (x[0] - pow(x[0], 3) / 3.0 - x[1]);
        dxdt[1] = x[0] / mu;
        return dxdt;
    };
    //A coupling velocity function takes input x as the state variable of the POST-synaptic oscillator, which given the vector-valued coupling_strength, will have its time derivative modified by dxdt:
    coupling_velocity = [](const State_variable& x, const value_type coupling_strength) {
        State_variable dxdt(2);
        dxdt[0] = coupling_strength;
        dxdt[1] = 0.0;
        return dxdt;//In this example, the dxdt is given by coupling_strength in the first coordinate.
    };
    //A coupling strength function computes the coupling strength output from a PRE-synaptic oscillator given its state in the current and a previous state, as well as the time difference between these two states.
    coupling_strength = [](const Particle& current_state, const Particle& prev_state, const value_type delta_t) {
        //NOTE: coupling strength should compute some average flow rate over the time_step period, NOT the instantaneous flow rate at a given time.
        //The choice is made to avoid computing coupling strength on a derivative,
        //which would be very sensitive to choice of timestep, and may miss some firing when time_step is too large.
        //For an "averaged value type" coupling as shown here, this is not a big issue, but it does not hurt to compute average of the two.
        const value_type coupling_coefficient = 0.5;
        return 0.5 * (current_state.center_location[0] + prev_state.center_location[0]) * coupling_coefficient * current_state.weight;//returns the average value in coordinate 1(defined by center_location) weighted with a coupling coefficient and the weight of this particle.
    };
    //NOTE: state_variable_in_domain and state_variable_restrict_to_domain not required since state variable is valid everywhere.
    //defines the return value using pointers. Due to constraint of C++, defining an incomplete class is only possible using pointers.
    eqn_ptr->advection_velocity = advection_dynamics;
    eqn_ptr->coupling_velocity = coupling_velocity;
    eqn_ptr->coupling_strength = coupling_strength;
    return eqn_ptr;
}
\end{lstlisting}
In the following example, the Hodgkin-Huxley equation with a threshold-type coupling is defined. It is copied from \texttt{set\_hh\_eqn.h} with additional comment:
\begin{lstlisting}
Advection_diffusion_eqn* set_Hodgkin_Huxley_eqn(const value_type diffusion_coeff, const value_type coupling_strength_coefficient, const value_type coupling_potential) {
    auto eqn_ptr = new Advection_diffusion_eqn(4, diffusion_coeff, false);//defines a 4-dimensional state space with an overloaded diffusion coefficient that is symmetric in each direction (i.e. diffusion coefficient matrix is identity matrix multiplied by scalar diffusion coefficient), and the state variable domain is restrained. (With restriction defined later)
    vector_vector_function advection_dynamics;
    coupling_velocity_function coupling_velocity;
    coupling_strength_function coupling_strength;
    //definition of a standard HH model:
    advection_dynamics = [](const State_variable& x) {
        //x[0] = V / 100; rest ordered by M, N, H.
        const value_type gna = 120;
        const value_type ena = 115; const value_type gk = 36;
        const value_type ek = -12;
        const value_type gl = 0.3;
        const value_type el = 10.613;
        const value_type appcurr = 8.0;
        State_variable dxdt(4U);
        value_type V = x[0] * 100.0;
        V += 1e-6 * (abs(V - 10.0)<5e-7 || abs(V - 25.0)<5e-7 || abs(V - 50.0)<5e-7);
        const value_type M = x[1];
        const value_type N = x[2];
        const value_type H = x[3];
        dxdt[0] = (appcurr + gna * M*M*M*H*(ena - V) + gk * (pow(N, 4))*(ek - V) + gl * (el - V)) / 100.0;
        //function y = Ah(V)
        const value_type Ah = 0.07*exp(-V / 20.0);
        //function y = Am(V)
        const value_type Am = (25.0 - V) / (10.0*(exp((25.0 - V) / 10.0) - 1.0));
        //function y = An(V)
        const value_type An = (10.0 - V) / (100.0*(exp((10.0 - V) / 10.0) - 1.0));
        //function y = Bh(V)
        const value_type Bh = 1.0 / (exp((30.0 - V) / 10.0) + 1.0);
        //function y = Bm(V)
        const value_type Bm = 4.0*exp(-V / 18.0);
        //function y = Bn(V)
        const value_type Bn = 0.125*exp(-V / 80.0);
        //%Bn = 0.125*exp(-V / 19.7); //this is for the Corrected HH model
        dxdt[1] = Am * (1 - M) - Bm * M;
        dxdt[2] = An * (1 - N) - Bn * N;
        dxdt[3] = Ah * (1 - H) - Bh * H;
        //std::cout << dxdt;
        return dxdt;
    };
    //definition of coupling strength, given PRE-synaptic oscillator particle at current state and a previous state that was coupling_time_step ago:
    coupling_strength = [coupling_strength_coefficient](const Particle& current_state, const Particle& prev_state, const value_type coupling_time_step) {
        //NOTE: coupling strength should compute the average flow rate over the coupling_time_step period, NOT the instantaneous flow rate at a given time.
        //The choice is made to avoid computing coupling strength on a derivative,
        //which would be very sensitive to choice of timestep, and may miss some firing when coupling_time_step is too large.
        //For a "Threshold type" coupling, this means the value should be divided by coupling_time_step
        const value_type threshold_voltage = 0.45;// threshold voltage of 45 mV
        if (current_state.center_location[0] <= prev_state.center_location[0]) {
            //No coupling when the membrane potential is decreasing.
            return 0.0;
        }
        //The following 3 lines compute the proportion (of the whole population) of the population crossing the threshold voltage:
        const value_type V_normalized = (current_state.center_location[0] - threshold_voltage) / sqrt(current_state.covariance_matrix(0,0));
        const value_type V_prev_normalized = (prev_state.center_location[0] - threshold_voltage) / sqrt(prev_state.covariance_matrix(0, 0));
        const value_type population_proportion = (erf(V_normalized / sqrt(2)) - erf(V_prev_normalized / sqrt(2)))*0.5;

        //Which is further adjusted by the coupling_strength_coefficient and weighr of particle, and divided by the time step since the coupling is computed as a velocity term, and should not be scaled by the choice of coupling time step.
        return population_proportion * coupling_strength_coefficient / coupling_time_step * current_state.weight;
    };
    const value_type coupling_potential_rescaled = coupling_potential / 100.0;
    //The coupling velocity defines how the POST-synaptic particle is affected, which in this particular example is a conductance-based coupling model:
    coupling_velocity = [coupling_potential_rescaled](const State_variable& target, const value_type coupling_strength) {
        //dV/dt = k(V_c - V)
        State_variable rval(target.size());
        rval.fill(0.0);
        rval[0] = coupling_strength * (coupling_potential_rescaled - target[0]);
        return rval;
    };
    //Since HH model has 3 variables restricted between 0 and 1, the following function that determines if a coordinate is inside the domain is REQUIRED:
    vector_bool_function state_variable_in_domain;
    state_variable_in_domain = [](const State_variable x) {
        if (x[1]<0.0 || x[1] > 1.0 || x[2] < 0.0 || x[2] > 1.0 || x[3] < 0.0 || x[3] > 1.0)
            return false;
        return true;
    };
    //Additionally, a function to restrict such coordinates back to domain is also needed.
    vector_vector_function state_variable_restrict_to_domain;
    state_variable_restrict_to_domain = [](State_variable x) {
        auto x_copy = x;
        if (x_copy[1] < 0.0)
            x_copy[1] = 0.0;
        else if (x_copy[1] > 1.0)
            x_copy[1] = 1.0;
        if (x_copy[2] < 0.0)
            x_copy[2] = 0.0;
        else if (x_copy[2] > 1.0)
            x_copy[2] = 1.0;
        if (x_copy[3] < 0.0)
            x_copy[3] = 0.0;
        else if (x_copy[3] > 1.0)
            x_copy[3] = 1.0;
        return x_copy;
    };
    //define return value:
    eqn_ptr->advection_velocity = advection_dynamics;
    eqn_ptr->coupling_strength = coupling_strength;
    eqn_ptr->coupling_velocity = coupling_velocity;
    eqn_ptr->state_variable_in_domain = state_variable_in_domain;
    eqn_ptr->state_variable_restrict_to_domain = state_variable_restrict_to_domain;
    return eqn_ptr;
}
\end{lstlisting}
\subsection{Modifying procedural source file}
After changing the model files, additional parameters independent from the model(such as timestep, total timestep count, and scalar parameters) needs modification as well. The procedural setup of the model in \texttt{main} and related functions also needs to be adjusted accordingly. How the desired parameters can be introduced is a generic programming problem and is beyond the scope here. However, we remind readers that:
\begin{itemize}
\item
Inside \texttt{run\_HH\_model}, make sure that the dimension are set correctly
\item
The plot parameters used here are specific to the chosen Hodgkin-Huxley model here
\end{itemize}
\subsection{Modifying initial condition}
The initial condition is defined by a \texttt{mat} file with following variables:
\begin{lstlisting}
%d-dimensional state variable, with initial condition as a linear combination of n particles:
w_array%1* n matrix, defines weight of each particle
x_array%d*n matrix, defines center location of each particle
sigma_array%d*d*n matrix, defines covariance of each particle
\end{lstlisting}
Note since \texttt{mat} uses column-major while \texttt{hdf5} uses row-major, the \texttt{h5} files will have reversed dimension ordering. An initial condition in \texttt{h5} file is defined as follows:
\begin{lstlisting}
//d-dimensional state variable, with initial condition as a linear combination of n particles:
x_array//n*d matrix of 64-bit floating-point
w_array//n*1 matrix of 64-bit floating-point
sigma_array//n*d*d matrix of 64-bit floating-point
\end{lstlisting}
\section{Usage for individual functions in \texttt{particle\_method.h}}
This section documents the usage of the functions and objects defined in \texttt{particle\_method.h}.
\begin{itemize}
\item
\texttt{\#define MATLAB\_VISUALIZE}: defines if the \texttt{matlab} version or \texttt{hdf5} version of data input/output should be used.
\item
Vector and Matrix-valued variables are defined as \texttt{Eigen} vectors and matrices. specifically:
\begin{lstlisting}
typedef Eigen::VectorXd State_variable;
typedef Eigen::MatrixXd Matrix_type;
typedef double value_type;
typedef int index_type;
\end{lstlisting}
\item
Mathematical functions are defined using the lambda functions implemented using the \texttt{C++} standard library. Specifically:
\begin{lstlisting}
typedef std::function<State_variable(const State_variable)> vector_vector_function;
typedef std::function<value_type(const State_variable)> vector_scalar_function;
typedef std::function<bool(const State_variable)> vector_bool_function;
typedef std::function<void(State_variable)> vector_void_function;
\end{lstlisting}
\item
\texttt{struct Particle} An asymmetric particle.
\begin{itemize}
\item
member variables

\begin{lstlisting}
	State_variable center_location;
	Matrix_type covariance_matrix;
	value_type weight;
\end{lstlisting}
\item
constructor

two initializing methods:
\begin{lstlisting}
	Particle(index_type state_space_dimension = 1U) {
		weight = 0.0;
		center_location = Eigen::VectorXd::Zero(state_space_dimension);
		covariance_matrix = Eigen::MatrixXd::Identity(state_space_dimension, state_space_dimension);
	}
	Particle(const value_type weight, const State_variable& center_location, const Matrix_type& covariance_matrix) : weight(weight),center_location(center_location),covariance_matrix(covariance_matrix) {}
\end{lstlisting}

\item
helper functions:

method to find density values at a \texttt{location} in the state space:
\begin{lstlisting}
value_type density_at(const State_variable& location) const;
\end{lstlisting}
Find density for marginal distribution where only a subset of coordinates in the \texttt{location} input is considered:
\begin{lstlisting}
value_type density_projection_at_coordinate(const State_variable& location, const std::vector<bool>& range_dimensions) const;//range_dimensions is of length dimension. e.g. TFTF means projection to dimension 0 and 2
\end{lstlisting}
\end{itemize}
\item
\texttt{struct Center\_level\_set}
This is a struct that is only used internally.
\item
\texttt{struct Adcection\_diffusion\_eqn} Refer to Section \ref{str:Advdiffeqn} for usage of member variables and functions.
\item
\texttt{class Population\_density} The class containing the population density distribution, as a linear combination of particles it contained.
\begin{itemize}
\item
Member variables:
\begin{lstlisting}
	const index_type dimension;
	//private: Note p_vect is not private only due to limit of tbb::concurrent_vector
	particle_vector p_vect;//container for the particles
\end{lstlisting}
where the \texttt{particle\_vector} is defined as follows:
\begin{lstlisting}
typedef tbb::concurrent_vector<Particle> particle_vector;
\end{lstlisting}
Note that \texttt{p\_vect} shall be treated as unavailable to access directly out side of the class scope, since the only reason for it to be not private is due to constraints of the \texttt{tbb} library used.
\item
Constructor

An empty \texttt{Population\_density} can be initialized by the following constructor
\begin{lstlisting}
	Population_density(const index_type state_space_dimension, const value_type tau = 0.01 / 4.0 / log(2.0), const value_type lambda = 1e-6, const value_type alpha = 0.2)
		: dimension(state_space_dimension), tau(tau), lambda(lambda),alpha(alpha) {}
\end{lstlisting}

\item
Container-related methods:
\texttt{Population\_density} can be accessed and modified like a vector, with \texttt{operater []}, \texttt{begin()}, \texttt{end()}, \texttt{size()} \texttt{resize()} and iterators as standard vectors.

To add particles to the population, use \texttt{append} to push back particle into the population:
\begin{lstlisting}
	particle_vector::iterator append(const Particle& particle) {
		p_vect.push_back(particle);
		//p_vect.insert(end(), particle);
		return end();
	}
\end{lstlisting}
\item
Evaluation methods

Information about the population can be obtained by using the following functions:
\begin{lstlisting}
value_type density_at(const State_variable& location) const;//returns population density at location
	value_type density_projection_at_coordinate(const State_variable& location, const std::vector<bool>& range_dimensions) const;//range_dimensions is of length dimension. e.g. TFTF means projection to dimension 0 and 2
	std::vector<value_type> density_at(const std::vector<State_variable>& location) const;//returns population density at all points in the location vector
	std::vector<value_type> density_projection_at_coordinate(const std::vector<State_variable>& location, const std::vector<bool>& range_dimensions) const;//range_dimensions is of length dimension. e.g. TFTF means projection to dimension 0 and 2
	double average_in_index(const int coord_idx) const;//returns the average value for coordinate i. (e.g. in HH model, average_in_index(0) returns average membrane potential.
\end{lstlisting}
\item
Visualization methods

If the macro \texttt{MATLAB\_VISUALIZE} is enabled, then the following plot functions that uses matlab engine is available:
\begin{lstlisting}
    Plot_handle plot_density(std::vector<bool> projection_dimensions, const value_type x_lb, const value_type x_ub, const value_type y_lb, const value_type y_ub, const char* imagesc_options = "") const;
    //Plot the marginal population density projected into the projection_dimensions.
    //e.g.: in a 4-dimensional space, projection_dimensions=TFTF projects the marginal density into 1st and 3rd dimension.
    //The projection can be into a 1-dimensional or 2-dimensional subspace
    //x_lb, x_ub, y_lb, y_ub is the lower and bounds for the coordinates to project to. y_lb, y_ub is not used when projection is into a 1-dimensional subspace
    //imagesc_options passes additional parameters into the imagesc command of matlab.
    Plot_handle plot_density(const value_type x_lb, const value_type x_ub, const value_type y_lb, const value_type y_ub, const char* imagesc_options = "") const;
    //project into first 2 dimensions.
    Plot_handle plot_density(const int projection_dimension, const value_type x_lb, const value_type x_ub, const char *imagesc_options) const;//project into 1 dimension
    //Plot Flags: 1 overwrite, 2 not plot second eigenvec, 4 not plot first eigenvec.
    Plot_handle plot(std::vector<bool> projection_dimensions, const char* plot_options = "", const int plot_flags = 1);
    Plot_handle plot(const char* plot_options = "", const int plot_flags = 1);//project into first 2 dimensions.
    Plot_handle output_center_and_weight() const;
    Plot_handle copy_particle_to_matlab(const index_type i) const;//COPY single particle to matlab workspace
    void output_particle(const index_type i, const char output_filename[] = "particle.mat") const;//OUTPUT single particle to a mat file
\end{lstlisting}

\item
Data I/O methods:

Independent of whether macro \texttt{MATLAB\_VISUALIZE} is enabled or not, the following functions allows input and output of population density as linear combination of particles. Please refer to the end of section \ref{str:Advdiffeqn} for the format of the files.
\begin{lstlisting}
	void output_all_particles(const char output_filename[] = "particles.mat") const;//OUTPUT particles to a mat or h5 file
	void input_all_particles(const char input_filename[] = "particles.mat");//INPUT particles to a mat or h5 file
\end{lstlisting}
\end{itemize}
\item
\texttt{class Population\_density\_with\_equation : public Population\_density} The class containing a population density, and an advection-diffusion equation, which is an inherited class from \texttt{Population\_density}.
\begin{itemize}
\item
Additional member variables:
\begin{lstlisting}
	const value_type tau;
	//tau NOW only affect particle combination. Larger tau leads to less aggressive particle combination.
    const value_type lambda;//regulariztion factor
    const value_type alpha;//advection velocity relative distance. alpha small uses level set closer to center.
\end{lstlisting}
\item
Constructor:
\begin{lstlisting}
    Population_density_with_equation(const Advection_diffusion_eqn& adv_diff_eqn, const index_type state_space_dimension, const value_type tau = 0.01 / 4.0 / log(2.0), const value_type lambda = 1e-6, const value_type alpha = 0.2)
        : Population_density(state_space_dimension),adv_diff_eqn(adv_diff_eqn), tau(tau), lambda(lambda), alpha(alpha) {
        set_ODE(adv_diff_eqn);
    }
\end{lstlisting}
\item
Methods for updating population density for \texttt{timestep}:
\begin{lstlisting}
    void update_ODE_const(const value_type timestep, const index_type stepcount = 1);//Updates population density with fixed timestep
    void update_ODE_adaptive(const value_type timestep, const index_type stepcount = 1);//Update population density with variable timestep that is at most timestep
    void update_ODE_adaptive_split(const value_type coupling_timestep, const index_type stepcount, const value_type rel_error_bound);//Update population density with variable timestep that is at most timestep. Moreover, if particles are too large to be accurate, particles are splitted automatically
\end{lstlisting}
\item
Functions to split and combine particles:
\begin{lstlisting}
    void split_particles(const value_type rel_error_bound = DEFAULT_SPLIT_REL_ERROR);//Split all particles that are too large. No need to call if using update_ODE_adaptive_split
    void combine_particles();//combine particles. Should be called between each update_ODE step
\end{lstlisting}
\item
Additional helper functions:
\begin{lstlisting}
void check_linear_approx(const int particle_index) const;//prints information about accuracy of local linear approximation
\end{lstlisting}

\end{itemize}

\end{itemize}
\end{document}


%Header
\documentclass{report}
\usepackage{blindtext}
\usepackage[T1]{fontenc}
\usepackage[utf8]{inputenc}
\usepackage{comment}
\usepackage{graphicx}
\usepackage{float}
\usepackage{amsmath}
\title{Midterm Report}
\author{Nicholas Wotton}
\date{6 December 2019}

%Begin body
\begin{document}

%Create Title page
\begin{titlepage}
\maketitle
\end{titlepage}

\begin{comment}
Outline
\begin{itemize}
\item What is a Neural Network
\item Derivation of the BSM
\item Combining the Two?
\end{itemize}
\end{comment}

\chapter{Exploring Neural Networks}

\section{Defining a Neural Network}

A neural network is a type of function. It is initialized specifically with input-output pairs. Given sets of these input-output pairs, the function changes to try and replicate the relationship between them. For each pair it makes a best guess at the relationship between them, updating with each new pair. The idea is to create a trained network that can replicate a function given an input. Ideally, complex functions for which there are no mathematical closed solutions can be solved using this network.

The network is made up of layers of Neurons. A layer can have any number of neurons and a network can contain any number of layers. For example, let us create a neural network with 1 layer with 1 neuron. The network guesses at what factor the input, $x$ needs to be scaled by and what constant, if any, needs to be added to achieve $f(x)$. This is just the problem

\begin{equation}
ax+b=f(x)\label{eq:1}
\end{equation}

Where we are solving for $a$ and $b$. If we add another layer of 1 neuron to Equation \ref{eq:1}, our probelm expands to
\begin{equation}
(a_1x+b_1)a_2+b_2 = f(x)
\end{equation}

Where $a_1, a_2$ and $b_1,b_2$ refer to the neuron and constant for each layer respectively. Multiple layers allow for multiple scalars and constants to be employed by the network trying to guess the function. Notice specifically how the second layer's $a_2$ term, the scalar, multiplies the constant from the first layer. This can allow for approximation of non-linear functions.

However, layers of single neurons are not typically used. Adding more neurons in a layer allows for more combinations to be tried at once, that is every neuron in the first layer can try a different scalar. Theoretically, any function could be approximated with a Neural Network using only a single layer composed of a massive number of neurons. The main problem with this is the computational mass and required time.

Figure \ref{fig:basicNN} shows a more complex version of a simple neural network.

%Include a picture
\begin{figure}[H]
\centering
\includegraphics[scale=.7]{Crude-Neural-Net.png}
\centering
\caption{A Basic Neural Network Diagram}
\label{fig:basicNN}
\centering
\end{figure}

Walking through the diagram, we begin with our input-output pair, $(x, f(x))$. Each $a_i$ in the first layer modifies $x$ in some way. Then, $a_ix$ passes through an activation function. The two most common types are ReLU and Sigmoid. They are
$$ReLU: \phi(x) = max\{0,x\}$$
$$Sigmoid: \phi(x) = \frac{1}{1+e^{-x}}$$
After $a_ix$ passes through the activation function, the constant is added and the whole thing is submitted to the next layer. Each neuron in layer 2 then modifies this $a_ix+b_1$ in a different way. Finally, each product of the neurons of the second layer pass through the activation function again. This leads them to a single value. During the training of the model, this value, $N(x)$ is then compared to the true given value, $f(x)$. The loss is assessed and adjustments are made using an optimizer function to minimize the loss.

Mathematically, we can represent this using linear algebra:
\begin{equation}
\phi_2\left(
\left(
  \phi_1\left(\begin{bmatrix} x \end{bmatrix}
  \begin{bmatrix} a_{1} & a_{2} & a_{3} \end{bmatrix} \right)
  +
  \begin{bmatrix} b_{1} & b_{2} & b_{3} \end{bmatrix}
\right)
 \begin{bmatrix} a_{4} \\ a_{5} \\ a_{6} \end{bmatrix}
\right)
 +
 \begin{bmatrix} b_{4} \\ \end{bmatrix}
 =
 \begin{bmatrix} f(x) \end{bmatrix}
\end{equation}

\section{An Example of a Linear Function and Neural Network}

Here we will go through a simple example of using a neural network to reproduce a simple linear function.
%This is explored in its entirety in the Python program in Appendix #
For our target function, we chose
\begin{equation}
f(x) = x + 2
\end{equation}

Next, we create the neural network. We use Python code, specifically the Pytorch package to do this:

\begin{figure}[H]
\includegraphics[scale=0.9]{nnModelCode.png}
\label{nnCode}
\end{figure}

Notice that we have 2 layers of 30 neurons each. Notice also that we have removed the ReLU step from the network. Since our function is linear, having ReLU in the network negatively impacts the accuracy and efficiency of the model. After initializing the model, we create our training data. These are $n$ randomly generated values that are passed through our function, $f(x)$ to create the input-output value pairs. Next, we need to define what we will use to measure accuracy in the iterative process of optimizing the network. Here we will just "cheat" by using the Mean Squared Error as our measure of improvement. That is, on each iteration we are computing
$$MSE =  \sum_{i=1}^n (f(x)-\hat{y})^2$$
where $\hat{y}$ is the estimated value for the function from the Neural Network. Note that this is "cheating" since in more advanced circumstances we would not explicitly know the function $f$ we are trying to replicate. The MSE and Newton's Method is then used to optimize the neural network. Typically, the training data is passed through a certain number of times to increase accuracy.

Once we have established the model and trained it, we need to test it. To do this, we randomly generate another set of points. We feed these to $f$ and our neural network separately and compare the resulting values. The closer our predicted values to the actual values, the more accurate the network has become. The results of our optimized model are in Figure \ref{fig:linNN}.

\begin{figure}[H]
\centering
\includegraphics[scale=0.9]{linNN.png}
\centering
\caption{Actual and Predicted Values of $f(x) = x+2$}
\label{fig:linNN}
\centering
\end{figure}

\chapter{The Black-Scholes Model}

The Balck-Scholes Model is a partial differential equation used for option pricing.
% From Shreve

% Put history of BSM here?

\section{Brief Overview of Options}

An option is a contract on an asset, typically a stock, that can be purchased and sold. There are two important types of options: Calls and Puts. There are also different varieties of these, but the simplest and most important for the Black-Scholes model is the European Option.

Owning an option gives the holder the right, but not the obligation, to sell or buy an asset at a pre-agreed upon price known as the Strike price, denoted $K$. More specifically, a European Call option gives the holder the right to buy an asset while a European Put option gives the holder the right to sell an asset.
Mathemtacially, we have the Payoff for owning an option at time $t$ is:

Call Options:
$P_{Call}(t)=max\{0, S_{t} - K\}$

Put Options:
$P_{Put}(t)=max\{0, K-S_{t}\}$

where $S_t$ is the stock price at time $t$ and $K$ is the strike price.

Graphically, we have the payoffs for Call and Put respectively:

\begin{figure}[H]
\centering
\includegraphics[scale=0.7]{Payoff-Graph-Call.png}
\centering
\caption{Payoff for European Call}
\label{fig:payoffCall}
\centering
\end{figure}

\begin{figure}[H]
\centering
\includegraphics[scale=0.7]{Payoff-Graph-Put.png}
\centering
\caption{Payoff for European Put}
\label{fig:payoffPut}
\centering
\end{figure}

For the Call Option, this means that if at expiry time $T$ the price of the stock is below or equal to $K$, the holder will not exercise it, thus, their Payoff is $\$0$. However, if at expiry the price of the stock is greater than $K$, the holder does exercise the option, thus their Payoff is equal to the difference between $S_T$ and $K$. For example, for a strike price $K = \$110$, if the stock price at time $T$ is
\begin{itemize}
\item $\$100$, the holder makes $\$0$ since $K\geq\$100$.
\item $\$120$, the holder makes $S_T-K=\$120-\$110=\$10$
\end{itemize}

However, for the Put option, at expiry $T$ the holder only exercises the option if the price of the stock, $S_T$ is less than $K$. In that case, their Payoff is equal to the difference between $K$ and $S_T$. If the price of the stock is greater than $K$, then the holder does not exercise the stock, thus making $\$0$. Again, for example, for a strike price $K=\$110$, if the stock price at time $T$ is
\begin{itemize}
\item $\$100$, the holder makes $\$110-\$100=\$10$
\item $\$120$, the holder makes $\$0$ since $K\leq\$120$
\end{itemize}

Note that it is possible to sell, or short, an option. In that case, the payoff diagram is just the same as for holding the option, but reflected on the $S_t$ axis. Mathematically, the payoffs become

Call Options:
$P_{Call}(t)=min\{0, S_{t} - K\}$

Put Options:
$P_{Put}(t)=min\{0, K-S_{t}\}$

\section{The Black-Scholes Model}

The Black-Scholes model assumes the distribution of the stock as lognormal. In particular, it writes
$$\ln \frac{S(T)}{S(0)} \sim \mathcal N((r  - \frac 1 2 \sigma^2) T, \sigma^2 T)$$
with respect to the risk neutral measure. In the above, the parameters stand for

\begin{itemize}
\item $S(0)$: The initial stock price
\item $S(T)$: The stock price at $T$
\item $r$: interest rate
\item $\sigma$: volatility
\end{itemize}

The call and put price with maturity $T$ and strike price $K$ will be known as $C_0$ and $P_0$ given as below:
$$C_0 = S_0  \Phi(d_1) - K e^{-rT} \Phi(d_2),$$
and
$$P_0 = K e^{-rT} \Phi(- d_2) - S_0  \Phi(- d_1),$$
where the $d_i$ are given as
$$d_1 = \frac{1}{\sigma\sqrt{\left( T - t \right)}}
        \left[
          \ln\frac{S_{0}}{K}
          +
          \left(
            r + \frac{\sigma^2}{2}
          \right)
          \left(
            T-t
          \right)
        \right],$$
and
$$d_2 = \frac{1}{\sigma\sqrt{\left( T - t \right)}}
        \left[
          \ln\frac{S_{0}}{K}
          +
          \left(
            r - \frac{\sigma^2}{2}
          \right)
          \left(
            T-t
          \right)
        \right] = d_{1}-\sigma\sqrt{\left( T - t \right)}$$

%
(From $\textit{Stochastic Calculus for Finance II Continuous Time Models}$ by Shreve)

and $\Phi$ is the CDF of the Standard Normal Distribution:
$$\Phi(x)=\frac{1}{\sqrt{2\pi}}\int_{-\infty}^{x}e^{-\frac{t^2}{2}}dt$$

\end{document}


\documentclass[10pt,a4paper]{article}
\usepackage[textwidth=16cm,textheight=23cm]{geometry}
\usepackage[utf8]{inputenc}
\usepackage[T1]{fontenc}
\usepackage{amsmath}
\usepackage{amsfonts}
\usepackage{amssymb}
\usepackage{graphicx}
%\usepackage{url}
\usepackage{hyperref}

\newcommand{\Trans}{\mathcal{T}}
\newcommand{\filterationF}{\mathcal{F}}
\newcommand{\mkt}{\mathrm{mkt}}
\newcommand{\ytw}{\mathrm{ytw}}
\newcommand{\dd}{\mathrm{d}}
\newcommand{\CRdelta}{\mathrm{CR01}}

\parindent=0pt
\parskip=1.5ex

\begin{document}

\title{Note on Callable Bonds}
\author{Youngsuk Lee}
\date{20 May 2020}
\maketitle

\section{Structure: Callable Bonds}

Consider a callable bond with call dates at
\begin{equation}
T_1 < T_2 < \cdots < T_M
\end{equation}
If the issuer calls, or {\em redeems}, the bond on $T_m$, the redemption amount and the outstanding accrued interest is paid to the bond holder at $T_m$ and the remaining cash flows are cancelled. Here, for convenience, the maturity date is treated as the last call date $T_M$.

Typically (at least in old days), callable bonds are structured so that it is most economical for the issuer to redeem on the first call date. For example, the coupon payments after the first call are based on Libor plus very large spread. In past, when callable bonds were not redeemed on the first call date, such events were surprise news to the market.
\begin{itemize}
	\item Deutsche Bank non-call, Dec 2008: \href{https://in.reuters.com/article/deutsche-bank-bond-call/update-2-deutsche-bank-non-call-casts-shadow-over-lt2-bonds-idINLH25709820081217}{Reuters news}
	\item Woori Bank, Feb 2009: \href{https://www.reuters.com/article/woori-bonds/asia-credit-woori-bank-seen-calling-back-400-mln-of-debt-idUSHKG35800620090209}{Reuters news}
	\item Monte dei Paschi di Sienna, Feb 2011:
	\href{https://ftalphaville.ft.com/2011/02/17/491236/another-bank-non-call-an-entirely-different-reaction/}{Financial Times Alphaville}
\end{itemize}

\section{Pricing Models}

\subsection{Yield-to-Worst Pricing Model}
\label{sec:pricing-model-yield-to-worst}

\subsubsection{Yield-to-Worst}
\label{sec:yield-to-worst}

A widely-used pricing model is to search for the call date which results in the worst yield from the investor's perspective (or the best yield from the issuer's perspective), i.e.\ the smallest yield.

Being precise, let
\begin{itemize}
	\item $\bar{V}$: the market value of the bond with the unit principal on the calculation date
	\item $V_m(y)$: the present value, in terms of yield-to-maturity $y$, of the underlying-bond associated with call date $T_m$:
	\begin{equation}
	V_m(y) = \sum_{t_j \le T_M} c_j  e^{-yt_j} + N_m e^{-yT_m}
	\label{eqn:valuation-non-callable-bond}
	\end{equation}
	where $c_j$ is the coupon amount paid on $t_j$ and $N_m$ is the redemption amount.
\end{itemize}
In practice, $c_j$ depends on a floating rate (e.g.\ Libor) after the first call date. But, for discussion purposes, we simply assume it is fixed.

To calculate the yield-to-worst $\bar{y}$,
\begin{enumerate}
	\item For each $m = 1, \cdots, M$, solve the following equation to get the yield-to-maturity $\bar{y}_m$ for the $m$-th call date:
	\begin{equation}
	V_m(\bar{y}_m) = \bar{V}
	\end{equation}
	\item $\bar{y}$ is set to
	\begin{equation}
	\bar{y} := \min_m \bar{y}_m, \quad m = 1, \cdots, M
	\end{equation}
\end{enumerate}

Equivalently, the yield-to-worst $\bar{y}$ is the solution for the following equation:
\begin{equation}
\min_{m} V_m(y) = \bar{V}, \quad m = 1, \cdots, M
\end{equation}
To prove this, we have, by definition,
\begin{equation}
\bar{V} = V_m(\bar{y}_m) \le V_m(\bar{y})
\end{equation}
Taking $\min$,
\begin{equation}
\bar{V} \le \min_m V_m(\bar{y})
\end{equation}
Find $\bar{m}$ such that $\bar{y} = \bar{y}_{\bar{m}}$. Then, we have
\begin{equation}
\bar{V} \le \min_m V_m(\bar{y}) \le V_{\bar{m}}(\bar{y}_{\bar{m}}) = \bar{V}
\end{equation}
Now, we are ready to formally define the yield-to-worst pricing model.

\subsubsection{Formal Definition}
\label{sec:ytw-formal-def}

{\bf Definition}: The {\em yield-to-worst pricing model} is a valuation model where the bond valuation is defined by the following function $V$ in terms of a yield $y$:
\begin{equation}
V(y) = \min_m V_m(y), \quad m = 1, \cdots, M
\label{def:pricing-model-yield-to-worst}
\end{equation}

For a given market value $\bar{V}$,
\begin{itemize}
	\item $\bar{y}$: the yield, referred to as {\em yield-to-worst}, for the callable bond satisfying $V(\bar{y}) = \bar{V}$
	\item $\bar{y}_m$: the yield for the $m$-th non-callable bond such that $V_m(\bar{y}_m) = \bar{V}$.
	\item $\bar{m}$: the index of the call date at which the minimum in (\ref{def:pricing-model-yield-to-worst}) is achieved, {\em assuming} that a unique such call date exists. Under this assumption, we have
	\begin{equation}
	\bar{y} = \bar{y}_{\bar{m}}
	\end{equation}
	If the assumption is invalid, $\bar{m}$ is ill-defined.
\end{itemize}

If $\bar{m}$ is uniquely well-defined, the underlying bond associated with call date $T_{\bar{m}}$ is referred to as the {\em yield-to-worst} bond. Because of its simplicity, the YTW bond is often used as the starting point for analysing the actual callable bond.

\begin{figure}[h!]
	\begin{center}
	\includegraphics[width=10cm]{pics/pv-ytw.png}
	\end{center}
	\caption{
		[thick grey line]: value profile for the callable bond example in Section \ref{sec:ytw-formal-def}. [blue/orange/green solid lines]: value profiles for its 1st/2nd/3rd underlying bonds, respectively.
		[dotted lines]: three market value scenarios at 1.0,conditions 0.95 and 0.9.
		[dashed lines]: yields-to-worst implied from the valuation model  (\ref{def:pricing-model-yield-to-worst}) for the three market value scenarios. The colours match to the worst-to-yield underlying bond. [stars/circles]: yield/market-value pairs implied from the non-callable valuation model (\ref{eqn:valuation-non-callable-bond}) of the underlying bonds for the scenarios. The pairs associated with yields-to-worst are marked with stars and others with circles.}
	\label{fig:pv-ytw}
	\hrule
\end{figure}

To demonstrate the concept using graphs, consider a callable bond with the following structure:
\begin{itemize}
	\item coupon schedule: three annual coupons with
	$$\{(t_j, c_j)\}_{j=1}^{3} = \{(1,0.05), (2,0.08), (3,0.11) \}$$
	\item call dates: $T_1 = 1$, $T_2 = 2$ and $T_3 = 3$ with $M=3$. Recall that $T_M$ is the maturity date.
	\item redemption amount: $1$
\end{itemize}

Figure \ref{fig:pv-ytw} should the value profiles of the callable bond itself (thick grey line) and its three underlying bonds (coloured lines). Three scenarios of the market value are considered with the following observations
\begin{center}
	\begin{tabular}{cccc}
		\hline
		scenario of market value & yield-to-worst & $\bar{m}$ \\
		\hline
		1.0  & 0.04879017 & 1\\
		0.95  & 0.08880587 & 2\\
		0.9  & 0.11273707 & 3\\
		\hline
	\end{tabular}
\end{center}

\subsubsection{P\&L Explain using Yield-to-Worst Bond}

The purpose of this section is to discuss the validity of the YTW bond as an approximation to the callable bond.

If $y$ is sufficiently close to $\bar{y}$, the minimum in (\ref{def:pricing-model-yield-to-worst}) will be achieved at $\bar{m}$ as well. Thus, the callable bond can be valued using the YTW as well:
\begin{equation}
V(y) = V_{\bar{m}}(y)
\end{equation}
for $|y - \bar{y}| < \epsilon$ for some $\epsilon > 0$. Therefore,
\begin{itemize}
	\item The YTW bond model $V_{\bar{m}}(y)$ can be used to calculate any sensitivities of the full model $V(y)$ at $\bar{y}$ and the calculation is {\em exact} without any approximation:
	\begin{equation}
	\frac{\dd^k V}{\dd y^k}(\bar{y}) = \frac{\dd^k V_{\bar{m}}}{\dd y^k}(\bar{y})
	\end{equation}
	\item Consequently, any Taylor expansion to the callable bond can be calculated {\em exactly} using the YTW bond. For example, the first-order expansion is given by
	\begin{equation}
	V(y) - V(\bar{y}) \approx \frac{\dd V_{\bar{m}}}{\dd y}(\bar{y})(y - \bar{y})
	\end{equation}
\end{itemize}

If, however, $y$ is not sufficiently close enough from $\bar{y}$, i.e.\ $|y-\bar{y}| \gg \epsilon$, the minimum in (\ref{def:pricing-model-yield-to-worst})
may be achieved in $m' \ne \bar{m}$, i.e.\
\begin{equation}
V(y) = V_{m'}(y)
\end{equation}
Then, any analysis based on the YTW bond becomes invalid.

To illustrate the above discussions, Figure \ref{fig:error-ytw} shows the error profile $e(y)$ when the callable bond is approximated using the yield-to-worst bond:
\begin{equation}
e(y) = V(y) - V_{\bar{m}}(y)
\end{equation}
The three scenarios in Figure \ref{fig:pv-ytw} are considered.
For each scenario, the error is exactly zero if the yield is near the yield-to-worst, but becomes significantly negative as the yield gets away from it.

\begin{figure}[h!]
	\begin{center}
		\includegraphics[width=10cm]{pics/error-profile-ytw.png}
	\end{center}
	\caption{
		[dashed lines]: Yields-to-worst corresponding to the three scenarios in Figure \ref{fig:pv-ytw}.
		[solid lines]: Error profiles when the yield-to-worst bond valuation model is used. Each line corresponds to each of three market scenarios.}
	\label{fig:error-ytw}
\end{figure}

Summarising,
\begin{itemize}
	\item The YTW bond model $V_{\bar{m}}(y)$ is exact to the callable-bond model $V(y)$ {\em only} for $y$ sufficiently close to $\bar{y}$.
	\item In general, the full revaluation must be adopted in order to calculate the change in value of the callable bond,
	\begin{equation}
	V(y) - V(\bar{y}) = \min_m V_m(y) - \min_m V_m(\bar{y})
	\end{equation}
\end{itemize}
Finally, if there are more than one candidates for $\bar{m}$, one cannot define a YTW bond. Thus, any arguments based on a YTW bond are completely invalid

\subsubsection{Optionality and Option Value}

It is important to notice that, with the Yield-to-Worst pricing model in Eq (\ref{def:pricing-model-yield-to-worst}),
\begin{itemize}
	\item the optionality is captured as the minimum operator is applied across all potential underlying bonds
	\item the option value is zero because the exercise decisions are deterministically decided. In order to have non-zero option value, a stochastic model such as described in Section \ref{sec:pricing-model-stochstic-yield} should be considered.
\end{itemize}

\subsection{Stochastic Yield Pricing Model}
\label{sec:pricing-model-stochstic-yield}

The model described in Section \ref{sec:pricing-model-yield-to-worst} is deterministic where bond yields in future are completely determined from the today's yield. This is not a realistic assumption. Thus, an {\em stochastic yield} (SY) pricing model should be considered
\begin{equation}
P(y) = E\left[ V(Y) \right]
\end{equation}
where $Y$ is a random variable representing the distribution of possible future yields. Because of the $\min$ operator in $V(y)$, we expect to have negative option value:
\begin{equation}
P(y) - V(y) \le 0
\label{eqn:option-value}
\end{equation}
This is in line with the fact that the investors {\em short the option} as the call right is with the issuer.

Whilst it is outside the scope of this document how $Y$ is modelled, its volatility would be calibrated to market variables such as swaption volatilities. Thus, being precise, the SY model should be written as
\begin{equation}
P(y) = P(y, \sigma)
\end{equation}
where $\sigma$ indicates the dependence on, say, swaption volatilities.

The most notable effect of introducing stochastic nature in the yield dynamics is to smooth out the kinks from the deterministic model as illustrated in Figure \ref{fig:pv-sy}.\footnote{Here, we used the following simple model for $Y$:
\begin{equation}
Y \sim N(y, \nu^2)
\end{equation}
with $\nu = 0.03$.}
Notably, the first-order sensitivity becomes continuous (and smooth) as shown in figure (c). Finally, the error profiles are shown in figure (d) when the YTW bond is used to approximate the SY model.

\begin{figure}[h!]
	\begin{center}
		\begin{tabular}{cc}
			(a) bond value & (b) option value \\
		\includegraphics[width=7cm]{pics/pv-sy.png}
		&
		\includegraphics[width=7cm]{pics/option-value.png}
		\end{tabular}

		\begin{tabular}{cc}
			(c) first-order sensitivity & (d) error from yield-to-maturity bond\\
			\includegraphics[width=7cm]{pics/delta.png}
			&
			\includegraphics[width=7cm]{pics/error-profile-sy.png}
		\end{tabular}

	\end{center}

	\caption{
		The same callable bond example and three market value scenarios described in Figure \ref{fig:pv-ytw} are considered.
		(a) [black line]: SY yield model $P(y)$ as a function of yield.
		[coloured lines]: The same lines in Figure \ref{fig:error-ytw}.
		[squares]: yield/value pairs implied from the SY pricing model for each scenario.
		(b) Option-value per (\ref{eqn:option-value}): difference between the black line in Figure (a) and the thick grey line in Figure \ref{fig:pv-ytw}.
		(c) First-order sensitivity profiles from the yield-to-worst model (thick grey line) and the SY yield model (think black line).
		(d) [solid lines]: Error profiles when the yield-to-worst bond valuation model is used. [dotted lines]: Taken from Figure \ref{fig:error-ytw} for comparison.
		}
	\label{fig:pv-sy}
\end{figure}

\subsection{Spread-to-Worst Pricing Model}

Instead of searching for the worst yield, one can search for the worst spread $s$ over a given benchmark interest rate curve $r(t)$:
\begin{equation}
V(s, r(t)) := \min_m V_m(s, r(t))
\end{equation}
where
\begin{equation}
V_m(y, r(t)) = \sum_{t_j \le T_M} c_j  e^{-(r(t_j) + s)t_j} + N_m e^{-(r(t_j) + s)T_m}
\label{eqn:valuation-non-callable-bond-spread}
\end{equation}

\subsection{Stochastic Spread Pricing Model}

Similar to the Stochastic Yield Pricing Model, we consider a random variable $S$ for future spreads over a given benchmark interest rate curve $r(t)$:\footnote{Here, only $s$ is simulated. In addition, $r(t)$ could be simulated as well.}
\begin{equation}
P(s, r(t)) := E\left[V(S,r(t))\right].
\end{equation}

\section{Summary}

Avoid YTW Pricing Model:
\begin{itemize}
	\item We should avoid using the YTW pricing model because the profile is not smooth with kinds.
	\item If the YTW pricing model is the only available option, one should not use the underlying YTW bond because
	\begin{itemize}
		\item Such a bond may be well-defined to begin with.
		\item It can change from one to another as the market changes, making any temporal analysis unstable.
		\item For large market changes, the YTW bond becomes a bad approximation to the original callable bond. Instead, one must use the full pricing model (\ref{def:pricing-model-yield-to-worst}).
	\end{itemize}
\end{itemize}
Equally, we should avoid Spread-to-Worst pricing model.

Use a stochastic model (e.g.\ Stochastic Yield or Spread model) instead:
\begin{itemize}
	\item This will smooth out the value profile. Consequently, all sensitivities are well-defined.
	\item For large market changes, we have to perform full-revaluations as the value profiles are highly non-linear.
\end{itemize}

\end{document}


% Author: ph-u
% Script: FirstExample.tex
% Desc: 1. `LaTeX` file fulfilling assignment needs; 2. as `infile` for testing usability of `CompileLaTeX.sh`
% Input: none
% Output: none
% Arguments: 0
% Date: Oct 2019

\documentclass[12pt]{article}
\title{A Simple Document}
\author{ph-u}
\date{}
\begin{document}
	\maketitle
	\begin{abstract}
		This paper must be cool!
	\end{abstract}
	\section{Introduction}
		Blah Blah!
	\section{Materials \& Methods}
	One of the most famous equations is:
	\begin{equation}
		E = mc^2
	\end{equation}
	This equation was first proposed by Einstein in 1905\cite{einstein1905does}.

	\bibliographystyle{plain}
	\bibliography{FirstBiblio}
\end{document}


\documentclass[bigger]{beamer}

\input{header-beam} % change to header-handout for handouts

% ====================
\title[Lecture 14]{Logic I F13 Lecture 14}
\date{October 29, 2013}
% ====================

\include{header}

\setlength{\fitchprfwidth}{5em}

\section{Review}

\subsec{First-order Logical Notions}{

\bit
\item An argument is \emph{first-order valid}, and its conclusion is a \emph{first-order consequence} of its premises,
if there is no \emph{first-order structure} in which the premises are true and the conclusion is false
\item A sentence is a \emph{first-order validity} if it is true in every first-order stucture
\item Two sentences are \emph{first-order equivalent} if there is no first-order structure in which they have different truth values.
\item A (set of) sentence(s) is \emph{first-order satisfiable} if it is (all) true in at least on first-order structure
\item NB: There is \emph{no mechanical test} for any of these (The Church-Turing Undecidability Theorem), by contrast to the truth-table case!
\eit

}

\subsec{Skorupski Revisited}{

\fitchprf{\pline[1.]{\text{If $\sf x$ is morally wrong, then}}\\
\pline{\qquad \text{$\sf A$ is blameworthy for freely doing $\sf x$}}\\
  \pline[2.]{\text{If $\sf x$ is
  rationally optimal, then }}\\
\pline{\qquad\text{A is not blameworthy for freely doing x.}}}
{\pline[3.]{\text{If $\sf x$ is morally wrong, then $\sf x$ is not rationally
      optimal.}}}

\bigskip

\fitchprf{\pline[1.]{\forall x(Wrong(x) \lif BlameFreelyDoing(a, x))}\\
  \pline[2.]{\forall x(ROpt(x) \lif \lnot BlameFreelyDoing(a, x))}}
{\pline[3.]{\forall x(Wrong(x) \lif \lnot ROpt(x))}}
}

\subsec{Skorupski Revisited}{

\fitchprf{\pline[1.]{\text{If $\sf x$ is morally wrong and $\sf A$ freely does $\sf x$,
    then}}\\
\pline{\qquad\text{$\sf A$ is blameworthy for doing $\sf x$.}}\\
  \pline[2.]{\text{If $\sf x$ is
  rationally optimal, then}}\\
\pline{\qquad\text{there is no reason to blame $\sf A$ for freely doing
  $\sf x$.}}}
{\pline[3.]{\text{If $\sf x$ is morally wrong, then $\sf x$ is not rationally
      optimal.}}}

\bigskip

\fitchprf{\pline[1.]{\forall x((Wrong(x) \land DoesF(a, x)) \lif Blame(a, x))}\\
  \pline[2.]{\forall x((ROpt(x) \land DoesF(a, x)) \lif \lnot Blame(a, x))}}
{\pline[3.]{\forall x(Wrong(x) \lif \lnot ROpt(x))}}

}

\subsec{Skorupski Revisited}{

\fitchprf{\pline[1.]{\forall x((Wrong(x) \land DoesF(a, x)) \lif Blame(a, x))}\\
  \pline[2.]{\forall x((ROpt(x) \land DoesF(a, x)) \lif \lnot Blame(a, x))}}
{\pline[3.]{\forall x(Wrong(x) \lif \lnot ROpt(x))}}

\bigskip

\fitchprf{\pline[1.]{\forall x((Cube(x) \land LeftOf(a, x)) \lif SameRow(a, x))}\\
  \pline[2.]{\forall x((Small(x) \land LeftOf(a, x)) \lif \lnot SameRow(a, x))}}
{\pline[3.]{\forall x(Cube(x) \lif \lnot Small(x))}}
}

\section{Relations Between Logical Notions}

\subsec{Relations Between Different Interpretations}{

\bit
\item Every TW-world is also a possible world
\item Every possible world yields a FO structure
\item Every FO structure determines a truth value for all
  sub\textit{sentences}, i.e., a truth-value assignment for its
  truth-functional form, and the sentence has the same truth value in
  the FO structure as its truth-functional form does in the
  corresponding truth-value assignment \eit }

\subsec{Tautology $\Rightarrow$ FO Validity}{

\bit
\item If there were a FO structure which makes a sentence S false, the corresponding truth-value assignment would make its truth-functional form false
\item If the truth-functional form of S is true in \emph{all} truth-value assignments, S must be true in all FO structures
\item If S is a tautology, it is also a FO validity
\item But not vice versa, e.g., $\sf a = a$, $\sf \forall x(Cube(x) \lor \lnot Cube(x))$
\eit

}

\subsec{FO Validity $\Rightarrow$ Logical Truth}{

\bit
\item If there were a possible world which makes S false, this would also
yield a FO structure which makes S false
\item If S is true in all FO structures, it is true in all possible worlds
\item If S is a FO validity, it is also a logical truth
\item But not vice versa, e.g., $\sf SameSize(a, a)$, $\sf \forall
  x(Larger(x, a) \to Smaller(a, x))$ \eit

}

\subsec{Relations Between Logical Notions}{

\bit
\item tautology $\Rightarrow$ FO validity $\Rightarrow$ logical truth $\Rightarrow$ TW necessity
\item tautologically valid $\Rightarrow$ FO valid $\Rightarrow$\\ logically valid $\Rightarrow$ TW valid
\item TT contradictory $\Rightarrow$ FO unsatisfiable $\Rightarrow$\\ logically contradictory $\Rightarrow$ TW contradictory
\item TW-possible $\Rightarrow$ logically possible $\Rightarrow$\\ FO satisfiable $\Rightarrow$ TT possible
\eit
}

\section{FO Equivalence}

\subsec{FO Equivalence of WFFs}{

\bit
\item Two sentences $\sf A$ and $\sf B$ are \emph{FO equivalent} iff in
  every FO structure they have the same truth value.
\item Two wffs $A(x)$ and $B(x)$ are \emph{FO equivalent}
iff in every FO structure, $A(x)$ is satisfied by the same objects
as $B(x)$, i.e.,
\item Two wffs $A(x)$ and $B(x)$ are \emph{FO equivalent}
iff in every FO structure, $\sf A(x)$ and $\sf B(x)$ have the same extension
\item More generally: $\sf A(x_1, \dots, x_n)$ is \emph{FO equivalent}
  to $\sf B(x_1, \dots, x_n)$ iff they have the same extension in every
  FO structure.  \eit }

\subsec{Important FO Equivalences}{

\let\IFF\Leftrightarrow

\[
\begin{array}{@{}rcl@{}}
\lnot\forall x\,A(x) & \IFF & \exists x\, \lnot A(x)\\
\lnot\exists x\,A(x) & \IFF & \forall x\, \lnot A(x)\\
\forall x(A(x) \land B(x))& \IFF & \forall x\, A(x) \land \forall x\, B(x) \\
\exists x(A(x) \lor B(x))& \IFF & \exists x\, A(x) \lor \exists x\, B(x) \\
\forall x(A(x) \lor B)& \IFF & \forall x\, A(x) \lor B \\
\multicolumn{3}{c}{\text{(provided $x$ not free in B)}} \\
\exists x(A(x) \land B)& \IFF & \exists x\, A(x) \land B \\
\multicolumn{3}{c}{\text{(provided $x$ not free in B)}} \\
\forall x\,A & \IFF & A\\
\multicolumn{3}{c}{\text{(provided $x$ not free in A)}} \\
\exists x\,A & \IFF & \exists x\, A \\
\multicolumn{3}{c}{\text{(provided $x$ not free in A)}} \\
\forall x\,A(x) & \IFF & \forall y\, A(y)\\
\exists x\,A(x) & \IFF & \exists y\, A(y)\\
\end{array}\]
}

\subsec{Proof of a FO Equivalence}{

\[
\forall x(A(x) \land B(x)) \IFF \forall x\, A(x) \land \forall x\, B(x)
\]

\bit
\item First suppose that $\forall x(A(x) \land B(x))$ is true in a FO structure.
\item Then every object in the domain satisfies $A(x) \land B(x)$.
\item So every object satisfies $A(x)$, i.e., $\forall x\, A(x)$ is true.
\item Ditto for $B(x)$
\item Now suppose an structure makes $\forall x\, A(x) \land \forall x\, B(x)$ true
\item Then it makes $\forall x\, A(x)$ true, i.e., every object satisfies $A(x)$
\item Ditto for $B(x)$, so every object satisfies $B(x)$.
\item So every object satisfies $A(x) \land B(x)$, i.e., $\forall x(A(x) \land B(x))$ is true
\eit
}

\subsec{Proof of a FO Non-Equivalence}{

\[
\exists x(A(x) \land B(x)) \IFF  \exists x\, A(x) \land \exists x\, B(x)
\]

\bit
\item The $\Rightarrow$ part holds!
\item Here's a FO interpretation which makes the RHS true but the LHS false:
\bit
\item Domain: $\{1, 2\}$
\item $A(x)$ \dots $\{1\}$
\item $B(x)$ \dots $\{2\}$
\eit
\eit
}

\section{Multiple Uses of a Single Quantifier}

\subsec{Wffs Expressing Relations}{

\bit
\item A wff A(x) with one free variable expresses a \emph{property}
\item A wff B(x, y) with two free variables expresses a \emph{relation}
\item $\sf \forall x\forall y\, B(x, y)$ is a sentence; it's true iff\\
any pair of objects $\alpha$, $\beta$ stand in the relation expressed by $B(x, y)$
\item $\sf \exists x\exists y\, B(x, y)$ is a sentence; it's true iff\\
at least one pair of objects $\alpha$, $\beta$ stand in the relation expressed by $B(x, y)$
\eit
}

\subsec{Multiple Uses of Single Quantifier: Examples}{

\bit
\item SameSize(x, y) \dots x and y are the same size
\item $\sf \forall x\forall y\, SameSize(x, y)$ \dots every pair $\langle \alpha,\beta\rangle$ stands in the relation ``is the same size as''
\item in other words: any pair of objects are the same size
\item NB: ``every pair'' includes pairs $\langle\alpha, \alpha\rangle$, i.e.,
\item $\sf \forall x\forall y\, A(x, y)$ only true if all pairs $\langle \alpha, \alpha\rangle$ satisfy $\sf A(x, y)$
\eit

}

\subsec{Multiple Uses of Single Quantifier: Examples}{

\bit
\item Larger(x, y) \dots x is larger than y
\item $\sf \exists x\exists y\, Larger(x, y)$ \dots at least one pair $\langle \alpha,\beta\rangle$ stands in the relation ``is larger than''
\item in other words: at least one objects is larger than at least one object
\item NB: includes pairs $\langle\alpha, \alpha\rangle$, i.e.,
\item $\sf \exists x\exists y\, A(x, y)$ is already true even if a single pair $\langle \alpha, \alpha\rangle$ satisfies $\sf A(x, y)$
\eit

}

\subsec{Different Variables $\neq$ Different Objects}{

\bits
\item Does $\sf\forall x\forall y\, Adjoins(x, y)$ mean ``any \emph{two} objects adjoin each other''?
\item It does not!
\item \dots true iff any pair $\langle\alpha, \beta\rangle$ satisfies $\sf Adjoins(x, y)$
\item \emph{including pairs where $\alpha = \beta$}
\item Hence, $\sf\forall x\forall y\, Adjoins(x, y)$ is \emph{always false} since no block adjoins itself!
\item Correct: $\sf \forall x\forall y(x \neq y \to Adjoins(x, y))$
\eit

}

\subsec{Different Variables $\neq$ Different Objects}{

\bits
\item Does $\sf\exists x\exists y\, SameRow(x, y)$ mean ``there are \emph{two} objects in the same row''?
\item It does not!
\item \dots true iff at least one pair $\langle\alpha, \beta\rangle$ satisfies $SameRow(x, y)$
\item \emph{including pairs where $\alpha = \beta$}
\item Hence, $\sf\exists x\exists y\, SameRow(x, y)$ is \emph{always true} since any block is in the same row as itself!
\item Correct: $\sf \exists x\exists y(x \neq y \land SameRow(x, y))$
\eit
}

\subsec{Restricted Quantification: All}{

\bit
\item All cubes are left of all tetrahedra.
\item Any pair $\langle \alpha, \beta\rangle$ where $\alpha$ is a cube and $\beta$ is a tetrahedron is so that $\alpha$ is left of $\beta$.\pause
\[\sf
\forall x\forall y((Cube(x) \land Tet(y)) \to LeftOf(x, y))
\]
\eit
}

\subsec{Restricted Quantification: Some}{

\bit
\item A cube is left of a tetrahedron.
\item At least one pair $\langle \alpha, \beta\rangle$ where $\alpha$ is a cube and $\beta$ is a tetrahedron is so that x is left of y.\pause
\[\sf
\exists x\exists y(Cube(x) \land Tet(y) \land LeftOf(x, y))
\]
\eit
}

\subsec{Restricted Quantification: No}{

\bit
\item No two cubes are the same size.
\item Any pair $\langle \alpha, \beta\rangle$ where $\alpha$ and $\beta$ are different cubes is so that $\alpha$ is not the same size as $\beta$.\pause
\[\sf
\forall x\forall y((Cube(x) \land Cube(y) \land x \neq y) \to \lnot SameSize(x, y))
\]
\item There is no pair $\langle \alpha, \beta\rangle$ where $\alpha$ and $\beta$ are different cubes of the same size.\pause
\[\sf
\lnot \exists x\exists y(Cube(x) \land Cube(y) \land x \neq y \land SameSize(x, y)
\]
\eit
}

\end{document}


\input{../../assignment-header}

% Special settings for matlab code on exam
\lstset{morekeywords={runSloppySimulation,runSimBadly,simStepMidpointMethod}}

\newcommand{\scoreMark}[0]{$\rule{1.5cm}{0.15mm}$ / $\rule{1.5cm}{0.15mm}$}

%========================================================================
\title{ME 149:  Midterm Exam Solution}
\date{March 15  ---  Start: 6:00pm  ---  End: 7:15pm}
\author{Optimal Control for Robotics}
%========================================================================
\begin{document}
\maketitle

\begin{abstract*}
No calculators, notes, books, or computers allowed. Total time:  75 minutes.
\end{abstract*}
%=================================================

\vspace{1em}

\section*{Student Name:    SOLUTION}

\vspace{1em}

\section*{How to optimize your score?}

\begin{itemize}  \setlength\itemsep{0.1em} \setlength\itemindent{18pt}
  \item Be neat and well organized
  \item For longer problems, show intermediate steps and box your
  \fbox { \parbox{3em}{answer} }
  \item If you need extra space...
        use the back of the page,
        the final (blank) page of the exam,
        or ask for more paper.
        Clearly indicate where the extra work is.
  \item Define all variables that you use and state any assumptions that you make.
\end{itemize}

\vspace{1em}

\section*{Score:  \scoreMark}
\vspace{1em}
\begin{large}
\begin{multicols}{2}
\begin{enumerate}  \setlength\itemsep{1.1em} \setlength\itemindent{36pt}
\item \scoreMark
\item \scoreMark
\item \scoreMark
\item \scoreMark
\item \scoreMark
\item \scoreMark
\item \scoreMark
\item \scoreMark
\item \scoreMark
\end{enumerate}
\end{multicols}
\end{large}

% Force enumerated lists to use letters
\renewcommand{\theenumi}{\Alph{enumi}}

%~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

\pagebreak
\section{Newton's Method}

\begin{enumerate}
  \item Suppose that you want to solve the scalar nonlinear equation $f(x) = 0$. \\
        The current estimate of the root is given by $x_k$
        and the next estimate of the root is given by $x_{k+1}$.
        Derive the Newton-Rhapson update that computes $x_{k+1}$ given $x_k$.
        \\[1em]

        \begin{align*}

          &f(x) = f(x_0) + \Delta x \cdot f'(x_0) + \mathcal{O}(\Delta x^2)
          \quad &\quad
          &\text{Taylor series approx. for $f(x)$ near $x_0$} \\[1em]

          &f(x) \approx f(x_0) + \Delta x \cdot f'(x_0)
          \quad &\quad
          &\text{Let high order terms $\mathcal{O}(\Delta x^2) \to 0$} \\[1em]

          &0 = f(x_0) + \Delta x \cdot f'(x_0)
          \quad &\quad
          &\text{Set linear approximation equal to zero} \\[1em]

          &0 = f(x_k) + (x_{k+1} - x_k) \cdot f'(x_k)
          \quad &\quad
          &\text{Replace $x_0$ with $x_k$ and $\Delta x$ with $x_{k+1} - x_k$ } \\[1em]

          &x_{k+1} = x_k - \frac{f(x_k)}{f'(x_k)}
          \quad &\quad
          &\text{Solve for $x_{k+1}$ } \\[1em]

        \end{align*}

  \item What is the difference between the Newton--Rhapson
        and the secant methods for scalar root finding?
        In what situation would you prefer one to the other?
        \\[2em]

        \textit{Both methods work by computing the root of a local linear
        approximation of the nonlinear function. The two differ in the way that
        this linear approximation is constructed. Newton's method uses the
        analytic derivative of the function to construct the linear model.
        The secant method uses the function value at the current and previous
        point to construct the linear model --- it uses a finite difference
        equation.}
        \\[2em]

        \textit{The Newton--Rhapson method for root finding is prefered to the
        secant method when the analytic derivative is known:
        it will converge more rapidly than the secant method.
        The secant method is used when the analytic derivative is unknown.}

  \pagebreak
  \item Draw a figure that clearly demonstrates a situation in which
        Newton's method will fail to converge to a root of the function.
        Why does the Newton--Rhapson method fail in this situation?
        \\[2em]

        \textit{The Newton--Rhapson method for root finding can fail to
        converge in a variety of situations. One example is shown in
        Figure \ref{fig:newtonRhapsonStability}. Both the top and bottom
        sub-plots show the method applied to the hyperbolic tangent function.
        A small change in the initialization makes the difference between
        convergence (top plot) and divergence (bottom plot).
        When diverging, each iteration moves the current approximation of the
        root farther from the true root, until the approximation (in this case)
        reaches infinity.

        The method will also fail in situations where there is no root, or
        where there is a local extremum where the function does not cross
        the x-axis. In either situation the solver will get stuck in a limit
        cycle around the extremum.

        Finally, if the solver every finds a point where the slope of the
        function is tiny (or zero) then it will extrapolate to near-infinity,
        which almost always will cause the method to fail.

        One key insight is that the convergence of the Newton--Rhapson method
        depends entirely on the initial condition! You can typically find an
        initial guess that will converge to the root, although it might be
        very difficult to do so.}

  \begin{figure}[ht]
  	\centering
    \includegraphics[width=\textwidth]{newtonRhapsonStability.pdf}
    \caption{Stability of Newton--Rhapson method for root finding}
    \label{fig:newtonRhapsonStability}
  \end{figure}

\end{enumerate}

%~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

\section{Midpoint Method Implementation}

Implement the function \texttt{simStepMidpoint()} on the following page.
This function computes a single simulation step using the midpoint method.
You code should be clear, correct, and follow the best practices that
have been discussed throughout the course.
Use the space below for planning your solution.
Write your Matlab code inside of the function template on the following page.

\pagebreak
\lstset{stepnumber=0}
\lstinputlisting{simStepMidpoint.m}

\pagebreak
\section{Bisection Search}
\begin{NoHyper}
Use a bisection search to iteratively reduce the interval that is known
to bracket the root of the function shown in Figure \ref{fig:RootSolveExampleFigure}.
\textbf{Populate the table below}, showing the bracket for the first five iterations
and the new point that will be evaluated on that iteration.
\end{NoHyper}
\begin{itemize}  \setlength\itemsep{0.3em}
  \item \texttt{Iter 0:   bracket: [-1.000,  \hspace{2.7em}  1.000]  \hspace{1em}  xNew = 0.0}
  \item \texttt{Iter 1:   bracket: [-1.000,  \hspace{2.7em}  0.000]  \hspace{1em}  xNew = -0.5}
  \item \texttt{Iter 2:   bracket: [-0.500,  \hspace{2.7em}  0.000]  \hspace{1em}  xNew = -0.25}
  \item \texttt{Iter 3:   bracket: [-0.500,  \hspace{2.7em} -0.250]  \hspace{1em}  xNew = -0.375}
  \item \texttt{Iter 4:   bracket: [-0.375,  \hspace{2.7em} -0.250]  \hspace{1em}  xNew = -0.3125}
\end{itemize}

\begin{figure}[ht]
	\centering
  \includegraphics[width=\textwidth]{bisectionSearchFigure.pdf}
  \caption{Bisection Search Example Figure}
  \label{fig:RootSolveExampleFigure}
\end{figure}

%~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

\pagebreak
\section{Scalar Taylor Series}

Write the Taylor series approximation of $f(t)$ to second-order around the point $t_0$.

\vspace{1em}
\begin{equation*}
  f(t) \approx f(t_0) + f'(t_0) \cdot (t - t_0) + f''(t_0) \cdot \tfrac{1}{2} (t - t_0)^2
\end{equation*}
\vspace{1em}
\begin{equation*}
  f'(t_0) = \frac{d}{dt} f(t) \big|_{t = t_0}
  \quad \quad \quad \quad
  f''(t_0) = \frac{d^2}{dt^2} f(t) \big|_{t = t_0}
\end{equation*}
\vspace{1em}

\section{Vector Taylor Series}

Write the Taylor series approximation of $f(t, \bm{x}, \bm{u})$ to first-order
about the point: $t_0$, $\bm{x}_0$, and $\bm{u}_0$.

\vspace{2em}
\begin{equation*}
  f(t, \bm{x}, \bm{u}) \approx
  f(t_0, \bm{x}_0, \bm{u}_0) +
  f_t(t_0, \bm{x}_0, \bm{u}_0) \cdot (t - t_0) +
  f_x(t_0, \bm{x}_0, \bm{u}_0) \cdot (\bm{x} - \bm{x}_0) +
  f_u(t_0, \bm{x}_0, \bm{u}_0) \cdot (\bm{u} - \bm{u}_0)
\end{equation*}
\vspace{1em}
\begin{equation*}
  f_t(t_0, \bm{x}_0, \bm{u}_0) = \frac{\delta}{\delta t} f(t, \bm{x}, \bm{u})
  \big|_{t = t_0, \bm{x} = \bm{x}_0, \bm{u} = \bm{u}_0}
\end{equation*}
\vspace{1em}
\begin{equation*}
  f_x(t_0, \bm{x}_0, \bm{u}_0) = \frac{\delta}{\delta x} f(t, \bm{x}, \bm{u})
  \big|_{t = t_0, \bm{x} = \bm{x}_0, \bm{u} = \bm{u}_0}
\end{equation*}
\vspace{1em}
\begin{equation*}
  f_u(t_0, \bm{x}_0, \bm{u}_0) = \frac{\delta}{\delta u} f(t, \bm{x}, \bm{u})
  \big|_{t = t_0, \bm{x} = \bm{x}_0, \bm{u} = \bm{u}_0}
\end{equation*}
\vspace{1em}

%~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

\pagebreak
\section{Function Handle Gymnastics}
\textbf{What will the following script print out?} \\
For each part A, B, C, show your work and then box what will be printed.
\lstinputlisting{functionHandleGymnastics.m}

\subsection*{Part A:}
\texttt{A: 2}
\subsection*{Part B:}
\texttt{B: 12}
\subsection*{Part C: }
\texttt{C: 11}

%~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

\pagebreak
\section{Matlab Programming Style}
The program below simulates a simple pendulum. It works, but is written poorly. \\
\textbf{Clearly identify at least 5 distinct issues with the code.}

\lstset{stepnumber=1}
\lstinputlisting{runSloppySimulation.m}

\begin{itemize}
  \item \textbf{Line 4:} arguments \texttt{@(t, z)} should be replaced with \texttt{@(\~ \,, z)}
  \item \textbf{Line 7:} plotting should include annotations
  \item \textbf{Line 17:} hard-coded time step --- should be a parameter
  \item \textbf{Line 11:} use \texttt{linspace} instead --- as written \texttt{tGrid(end)} is not \texttt{tUpp}
  \item \textbf{Line 12:} missing semicolon
  \item \textbf{Line 12-13:} as written, line 12 does nothing and line 13 allocates a matrix of the wrong size.
    These lines should be replaced by a correctly-written memory allocation
    and then setting the first column to the initial state.
  \item \textbf{Line 14:} \texttt{nDim} is unused --- this line should be deleted
  \item \textbf{Line 15:} upper loop limit should not be hard-coded
  \item \textbf{Line 16:} missing semicolon
  \item \textbf{Line 17:} hard-coded time step --- should be related to tGrid
\end{itemize}

%~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

\pagebreak
\section{Linearized Dynamical System}

Given the non-linear system dynamics described below,

\begin{equation*}

  \dot{\bm{z}} =

  \begin{bmatrix}
    \dot{\alpha}  \\
    \dot{\gamma}  \\
    \dot{\theta}
  \end{bmatrix}

  =

  \begin{bmatrix}
    \beta \gamma + \theta^2 \\
    \alpha \, \sigma  - \theta\\
    \sin(\sigma) + \beta \, \gamma
  \end{bmatrix}

  = \bm{f}(\bm{z}, \bm{u})

  \quad \quad \quad \quad \quad \quad

  \bm{z} =
  \begin{bmatrix}
    \alpha \\
    \gamma \\
    \theta
  \end{bmatrix}

\quad \quad \quad \quad \quad \quad

  \bm{u} =
  \begin{bmatrix}
    \beta \\
    \sigma
  \end{bmatrix}

\end{equation*}

\vspace{0.5em}
\begin{enumerate}
  \item \textbf{List the state variables: } $\alpha, \; \gamma, \; \theta$
  \vspace{0.6em}
  \item \textbf{List the control variables: } $\beta, \; \sigma$
  \vspace{0.6em}
  \item \textbf{What is the difference between a state and a control variable? } \\
  \textit{State variables are those variables that have derivatives in the system dynamics.
          For example, both $\alpha$ and $\dot{\alpha}$ show up in the dynamics above.
          Control variables appear algebraically in the system dynamics.
          For example, $\sigma$ is in the system dynamics, but not $\dot{\sigma}$. }
  \item \textbf{Compute: } $\dfrac{\delta \bm{f}}{\delta \bm{z}}$

  \begin{equation*}
  \dfrac{\delta \bm{f}}{\delta \bm{z}} =
  \begin{bmatrix}
    0      & \beta & 2\theta \\
    \sigma & 0     & -1      \\
    0      & \beta & 0
  \end{bmatrix}
  \end{equation*}

  \item \textbf{Compute: } $\dfrac{\delta \bm{f}}{\delta \bm{u}}$

  \begin{equation*}
  \dfrac{\delta \bm{f}}{\delta \bm{u}} =
  \begin{bmatrix}
    \gamma & 0 \\
    0      & \alpha  \\
    \gamma & \cos{\sigma}
  \end{bmatrix}
  \end{equation*}

\end{enumerate}

%~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
\pagebreak
\section{Trajectory Optimization}

Given the following continuous-time trajectory optimization problem.

\begin{align*}
  & \text{minimize: } \qquad J = \int_0^T \! g(t,\, \bm{x},\, \bm{u}) \, dt \\
  & \text{subject to: } \qquad \bm{0} = \bm{h}(\bm{x}(0), \, \bm{x}(T)) \\
  & \text{dynamics: } \qquad \dot{\bm{x}} = \bm{f}(t,\, \bm{x},\, \bm{u}) \\
\end{align*}

Suppose that you plan to solve the optimization using
direct multiple shooting with Euler's method
on a uniform grid of $N$ segments with one integration step per segment.
Write out the decision variables, objective function, and constraints
that will form the resulting non-linear program.

\begin{enumerate}
  \item \textbf{Decision Variables}
  \vspace{0.5em}
  \begin{equation*}
    \bm{x}_0, \bm{x}_1, \dots ,\bm{x}_N, \quad \bm{u}_0, \bm{u}_1, \dots, \bm{u}_{N-1}
  \end{equation*}
  \vspace{0.5em}
  \item \textbf{Objective Function}
  \vspace{0.5em}
  \begin{equation*}
    J = h \cdot \sum_{k=0}^{N-1} g(t_k,\,  \bm{x}_k,\,  \bm{u}_k)
  \end{equation*}
  \vspace{0.5em}
  \begin{equation*}
    h = \frac{T}{N}  \quad \quad \quad \quad t_k = k \cdot h
  \end{equation*}
  \vspace{0.5em}
  \item \textbf{Boundary Constraints}
  \vspace{0.5em}
  \begin{equation*}
    \bm{0} = \bm{h}(\bm{x}_0, \, \bm{x}_N)
  \end{equation*}
  \vspace{0.5em}
  \item \textbf{System Dynamics Constraints}
  \vspace{0.5em}
  \begin{equation*}
    \bm{x}_{k+1} = \bm{x}_k + h \cdot \bm{f}(t_k,\, \bm{x}_k,\, \bm{u}_k)
    \quad \quad k \in 0 \dots (N-1)
  \end{equation*}
  \vspace{0.5em}
\end{enumerate}

%=================================================
\end{document}