File: documentation.tex

package info (click to toggle)
stopt 6.1%2Bdfsg-1
links: PTS, VCS
area: main
in suites: forky, sid
size: 9,264 kB
sloc: cpp: 75,778; python: 6,012; makefile: 72; sh: 57
file content (6403 lines) | stat: -rw-r--r-- 433,779 bytes
parent folder | download | duplicates (3)
\documentclass[12pt]{report}
\usepackage{amssymb,amsmath}
\usepackage{mathrsfs}
\usepackage{listings}
%\usepackage{algorithm2e}
\usepackage{algorithm,algpseudocode}
%\usepackage[algostore]{algpseudocode}
\usepackage{graphicx}
\usepackage{float}
\usepackage{ulem}
\usepackage[usenames,dvipsnames,svgnames,table]{xcolor}
\usepackage[dvipsnames,prologue]{pstricks}
\usepackage{hyperref}
\usepackage{subcaption}
\usepackage{rotating}
\usepackage{color}
\usepackage{bbm}
\usepackage{empheq}
%\usepackage{algorithm}
%\usepackage[noend]{algpseudocode}
%\usepackage{algorithm2e}
%\usepackage{algorithmic}
%\usepackage[noend]{algpseudocode}


\newtheorem{Theorem}{Theorem}
\newtheorem{Proposition}{Proposition}
\newtheorem{Remark}{Remark} 
\newtheorem{definition}{Definition}

\definecolor{listinggray}{gray}{0.9}
\definecolor{lbcolor}{rgb}{0.9,0.9,0.9}
\definecolor{darkgreen}{rgb}{0,.6,0}


\def\Ac{\mathcal{A}}
\def \E{\mathbb{E}}
\def \R{\mathbb{R}}
\def \M{\mathbb{M}}
\def \S{\mathbb{S}}
\def \W{\mathbb{W}}
\def \V{\mathbb{V}}
\def\Lc{{\cal L}}
\def\x{\times}
\def \Fb{\overline F}
\def\1{{\bf 1}}
\def \I{{\bf I}}
\def \N{\mathbb{N}}
\newcommand{\un}{1\hspace{-1mm}{\rm I}}   % 1
\def\Qc{{\mathcal Q}}

\lstdefinestyle{CStyle}
%\lstset
{
  backgroundcolor=\color{lbcolor},
  tabsize=4,
  language=C++,
  captionpos=b,
  tabsize=3,
  frame=lines,
  numbers=left,
  numberstyle=\tiny,
  numbersep=5pt,
  breaklines=true,
  showstringspaces=false,
  basicstyle=\ttfamily\scriptsize,
%  identifierstyle=\color{magenta},
  keywordstyle=\color[rgb]{0,0,1},
  commentstyle=\color{darkgreen},
  stringstyle=\color{red}
  }

%\lstset{
\lstdefinestyle{PStyle}
{
  backgroundcolor=\color{lbcolor},
  tabsize=2,
  language=Python,
  captionpos=b,
  tabsize=3,
  frame=lines,
  numbers=left,
  numberstyle=\tiny,
  numbersep=5pt,
  breaklines=true,
  showstringspaces=false,
  basicstyle=\ttfamily\scriptsize,
  %  identifierstyle=\color{magenta},
  keywordstyle=\color[rgb]{0,0,1},
  commentstyle=\color[rgb]{1,0,0},
  stringstyle=\color{red}
}
%\lstset{language=C++}
%\lstset{language=Python}

\renewcommand{\baselinestretch}{1}

\makeatletter
\newcommand{\algmargin}{\the\ALG@thistlm}
\makeatother

% The command \longState is for correctly indenting long texts inside
% the algorithmic environment. Instead of using the command \State,
% the command \longState should be preferred for texts that span over
% multiple lines.
\algnewcommand{\longState}[1]{\State%
  \parbox[t]{\dimexpr\linewidth-\algmargin}{\strut #1\strut}}

% The commands \BLUE, \RED, \YELLOW, and \GREY have two parameters:
% one optional and one mandatory. The optional parameter is the width
% of the box. Its default value is relative to the margin of the
% algorithmic environment. This is so for making the box occupy the
% exact space within the algorithm. Outside of the algorithmic
% environment, this value does not make sense and it should be
% set. The second parameter is the content of the box.
\newcommand{\BLUE}[2][\linewidth-(\fboxsep+\fboxrule)*2-\algmargin]
{\fcolorbox{blue}{blue!10}{\parbox{#1}{#2}}}

\newcommand{\RED}[2][\linewidth-(\fboxsep+\fboxrule)*2-\algmargin]
{\fcolorbox{red}{red!10}{\parbox{#1}{#2}}}

\newcommand{\YELLOW}[2][\linewidth-(\fboxsep+\fboxrule)*2-\algmargin]
{\fcolorbox{yellow}{yellow!10}{\parbox{#1}{#2}}}

\newcommand{\GREY}[2][\linewidth-(\fboxsep+\fboxrule)*2-\algmargin]
{\fcolorbox{gray}{gray!10}{\parbox{#1}{#2}}}

%\usepackage[htt]{hyphenat}

% Justifying the text within the \code command. The idea is that it should
% break line to avoid the text within \code to exceed the margin of the
% text. This is done by automatic hyphenation and we try to hide the
% hyphenation character by replacing it with an "empty" one.
\newcommand*\justify{%
  \fontdimen2\font=0.4em% interword space
  \fontdimen3\font=0.2em% interword stretch
  \fontdimen4\font=0.1em% interword shrink
  \fontdimen7\font=0.1em% extra space
  \hyphenchar\font=200% trying to hide the hyphenation character by choosing
                      % an "empty" character. If some hyphenation character
                      % appears in a text within a \code command, this number
                      % must be replaced by a suitable one. If a hyphen is
                      % desired, replace this number by 45.
}
\newcommand{\code}[1]{\texttt{\justify#1}}
\newcommand{\centercode}[1]{\begin{center}\code{#1}\end{center}}
\newtheorem{lem}{\protect\lemmaname}[section]
\providecommand{\lemmaname}{Lemma}

\def\Du#1{\Frac{\partial #1}{\partial u}}
\def\Dt#1{\Frac{\partial #1}{\partial t}}
\def\Dv#1{\Frac{\partial #1}{\partial v}}
\def\Dvv#1{\Frac{\partial^2 #1}{\partial v^2}}
\def\Ds#1{\Frac{\partial #1}{\partial s}}
\def\Dx#1{\Frac{\partial #1}{\partial x}}
\def\Dxx#1{\Frac{\partial^2 #1}{\partial x^2}}
\def\Dy#1{\Frac{\partial #1}{\partial y}}
\def\Dyy#1{\Frac{\partial^2 #1}{\partial y^2}}
\def\Dvy#1{\Frac{\partial^2 #1}{\partial v \partial y}}

\def \Sum{\displaystyle\sum}
\def \Prod{\displaystyle\prod}
\def \Int{\displaystyle\int}
\def \Frac{\displaystyle\frac}
\def \Inf{\displaystyle\inf}
\def \Sup{\displaystyle\sup}
\def \Lim{\displaystyle\lim}
\def \Liminf{\displaystyle\liminf}
\def \Limsup{\displaystyle\limsup}
\def \Max{\displaystyle\max}
\def \Min{\displaystyle\min}

\def\argmax{\mbox{\rm arg}\max}
\def\argmin{\mbox{\rm arg}\min}
\def\essinf{{\rm ess}\!\inf\limits}
\def\esssup{{\rm ess}\!\sup\limits}

\def\be{\begin{eqnarray}}
\def\ee{\end{eqnarray}}
\def\b*{\begin{eqnarray*}}
\def\e*{\end{eqnarray*}}
\def\ipN{\frac{i+1}{N}}
\def\iN{\frac{i}{N}}
\def \chg{\color{magenta}}
\def\vp{\varphi}

\def \E{\mathbb{E}}
\def \F{\mathbb{F}}
\def \G{\mathbb{G}}
\def \N{\mathbb{N}}
\def \P{\mathbb{P}}
\def \Q{\mathbb{Q}}
\def \R{\mathbb{R}}
\def \Z{\mathbb{Z}}


\def \Ac{{\cal A}}
\def \Bc{{\cal B}}
\def \Cc{{\cal C}}
\def \Dc{{\cal D}}
\def \Ec{{\cal E}}
\def \Fc{{\cal F}}
\def \Gc{{\cal G}}
\def \Hc{{\cal H}}
\def \Ic{{\cal I}}
\def \Lc{{\cal L}}
\def \Pc{{\cal P}}
\def \Mc{{\cal M}}
\def \Oc{{\cal O}}
\def \Nc{{\cal N}}
\def \Sc{{\cal S}}
\def \Tc{{\cal T}}
\def \Vc{{\cal V}}
\def \Wc{{\cal W}}
\def \Yc{{\cal Y}}
\def \Zc{{\cal Z}}
\def \Xc{{\cal X}}



\def \bP{{\bf P}}
\def \bE{{\bf E}}

\def \eps{\varepsilon}


\def \ep{\hbox{ }\hfill$\Box$}


\def\Dt#1{\Frac{\partial #1}{\partial t}}
\def\Dv#1{\Frac{\partial #1}{\partial v}}
\def\Dvv#1{\Frac{\partial^2 #1}{\partial v^2}}
\def\Dy#1{\Frac{\partial #1}{\partial y}}
\def\Dyy#1{\Frac{\partial^2 #1}{\partial y^2}}
\def\Dvy#1{\Frac{\partial^2 #1}{\partial v \partial y}}




\def\reff#1{{\rm(\ref{#1})}}

\addtolength{\oddsidemargin}{-0.1 \textwidth}
\addtolength{\textwidth}{0.2 \textwidth}
\addtolength{\topmargin}{-0.1 \textheight}
\addtolength{\textheight}{0.2 \textheight}


%\topmargin -0.5cm
%\textheight 22.5cm
%\textwidth 17cm
%\oddsidemargin -0.54cm
%\evensidemargin -0.54cm

\def \Om{\Omega}
\def \bF{{\bf F}}
\def \bG{{\bf G}}
\def \cA{{\cal A}}
\def \cB{{\cal B}}
\def \cF{{\cal F}}
\def \cE{{\cal E}}
\def \cD{{\cal D}}
\def \cG{{\cal G}}
\def \cH{{\cal H}}
\def \cI{{\cal I}}
\def \cJ{{\cal J}}
\def \cL{{\cal L}}
\def \cP{{\cal P}}
\def \cQ{{\cal Q}}
\def \cM{{\cal M}}
\def \cN{{\cal N}}
\def \cT{{\cal T}}
\def \cC{{\cal C}}
\def \cS{{\cal S}}
\def \cV{{\cal V}}
\def \cZ{{\cal Z}}
\def \ind{1\!\!1}
\def \loi {\stackrel{law}{=}}
\def \egal {\stackrel{def}{=}}
\def \benu {\begin{enumerate}}
\def \eenu {\end{enumerate}}

\def\beqs{\begin{eqnarray*}}
\def\enqs{\end{eqnarray*}}
\def\beq{\begin{eqnarray}}
\def\enq{\end{eqnarray}}

\def \dep{\text{dep}}
\def \ind{\text{ind}}

\begin{document}
\vspace{1.5cm}

\author{Hugo Gevret \thanks{EDF R\&D, \texttt{Hugo.Gevret@edf.fr}}
  \and Nicolas Langren\'e \thanks{CSIRO Data61, Australia, \texttt{Nicolas.Langrene@csiro.au} }
  \and Jerome Lelong \thanks{Ensimag, Laboratoire Jean Kuntzmann,  700 avenue Centrale Domaine Universitaire - 38401 St Martin d'Hères }
  \and Rafael D. Lobato \thanks{Department of Computer Science, University of Pisa, Italy, \texttt{Rafael.Lobato@di.unipi.it}}
  \and Thomas Ouillon \thanks{EDF R\&D, \texttt{Thomas.Ouillon@edf.fr}}
  \and Xavier Warin \thanks{EDF R\&D \& FiME, Laboratoire de Finance des March\'es de l'Energie, ANR PROJECT CAESARS, \texttt{Xavier.Warin@edf.fr}}
  \and Aditya Maheshwari \thanks{University of California, Santa Barbara, USA, \texttt{aditya\_maheshwari@umail.ucsb.edu} }}
%\author{Hugo Gevret, Jerome Lelong, Xavier Warin}
\title{STochastic OPTimization  library in C++}
 \vspace{1cm}\renewcommand{\today}

\maketitle
\tableofcontents

\part{Introduction}
\chapter{General context}

Optimizing while dealing with uncertainties is a shared goal by many sectors in the industry.\\
For example in the banking system:
\begin{itemize}
  \item Some options such as American options need, in order to be valuated,  to find an optimal exercise strategy to maximize the gain on average.
  \item When dealing with assets management, a fund manager may want to find a strategy  to optimize his gains by investing in different assets while trying to satisfy some risk constraints.
  \item When dealing with credit risk in the case of option selling, some CVA modelization necessitates  to solve some high dimensional problem in order to evaluate the option value.
\end{itemize}
In the energy financial sector, many problems involve stochastic optimization:
\begin{itemize}
\item some options, known as swing options, permit the owner to get  some energy at some chosen dates with constraints on volumes. The price paid is either deterministic such as in the electricity market or can be an index which is an average of some commodity prices such as in the gas market.
\item When some batteries are installed on a network, the battery has to be filled in or discharged  optimally in order to avoid the use of some expensive thermal units.
\item The optimal management of certain gas storage or certain thermal assets taking into account the prices of raw materials is a goal shared by all asset owners in the sector.
\item Even in regulated energy market, when water is used to generate electricity, a common target consists in finding an optimal water management in order to maximize the profit on average.
\end{itemize}
A goal shared by many industries is the problem of risk management: which financial assets to buy to guarantee a given gain by immunizing a financial portfolio against certain uncertainties.\\
All these problems and many more require:
\begin{itemize}
\item either to resolve certain PDEs when the control must be evaluated continuously,
\item or to calculate a certain conditional expectation in the event that control must be taken on certain discrete dates. The problem is then solved by a
  dynamic programming method.
\end{itemize}


The STochastic OPTimization library (StOpt) \\
 \url{https://gitlab.com/stochastic-control/StOpt}\\
 aims to provide tools to solve certain stochastic optimization problems encountered in finance or in industry.
 This library is a toolbox used to facilitate the work of developers whishing to solve certain stochastic optimization problems by
 providing a general framework and some objects commonly used in stochastic programming.
 Many effective methods are implemented and the toolkit must be flexible enough to use the library at different
 levels being either an expert or only whishing to use the general framework. \\
 The python interface allows you to use the library at a low level.
 The test cases are either in C++ , or in python or in the both language.\\
 The user is invited to consult the different test cases proposed in order to have global view of the resolution methods.
 All the test cases are described in the last section of the documentation and deal with problems encountered in the banking system or the energy sector.
 \begin{itemize}
 \item The American options are solved by a part of dynamic programming \ref{part:dynProg} in python or C++ using regression (section \ref{sec::regression}) or using a scenario tree  \ref{sec::tree}.\\
   Regression are  achieved:
   \begin{enumerate}
   \item either by local polynomials  or with base support of the same size (subsection \ref{subsec::localSameSize}) or with an adapted size of the support (subsection \ref{subsec::local}) ,
   \item either by global polynomials (section \ref{sec:globPol})
   \item either by sparse grid regression (section \ref{sec:sparseGridReg})  useful in high dimension
   \item or by kernel regression (section\ref{sec:kernelReg})
   \end{enumerate}
   In the test, a trinomial tree is developed as an example and the valorisation of an American option for the Black-Scholes model is given using this tree.
 \item Gas storage problems are solved  
   \begin{itemize}
     \item either by dynamic programming (part \ref{part:dynProg})  in python or C++ using regression (section \ref{sec::regression}) or tree (section \ref{sec::tree}) 
   and stock interpolation ( chapter \ref{gridChapter}).\\
    Regression are  achieved:
   \begin{enumerate}
   \item  either by Local polynomials   with an adapted size  of the support (subsection \ref{subsec::local}) ,
   \item  either by global polynomials (section \ref{sec:globPol})
   \item or kernel regression  (section \ref{sec:kernelReg})
   \end{enumerate}
   As before the trinomial tree developed in tests is used in the tree methods.\\
   The interpolation between stock points is either linear or quadratic.
 \item either by the SDDP method (chapter \ref{chap:SDDP}) in C++ using both regression and tree methods.
   \end{itemize}
 \item  The swing options are solved by dynamic programming (part \ref{part:dynProg}) in python or C++ using regression with local polynomials with a suitable size of the support (subsection \ref{subsec::local})
 \item The optimal management of a lake with stochastic inflows is solved by dynamic programming (part \ref{part:dynProg}) in python or C++ using local polynomials   with an adapted support size (subsection \ref{subsec::local})
 \item The optimal hedging of an option using a average variance criterion of the hedged portfolio is resolved in C++ by dynamic programming (part \ref{part:dynProg}) using the methodology in  chapter \ref{chap:variance}.
 \item A certain management of the reservoirs is solved by the SDDP method (chapter \ref{chap:SDDP}) in C++ trying to minimize the cost of the energy supply to satisfy a given demand with the possibility of buying energy at a price that can be stochastic.
 \item The  continuous optimization of a  portfolio  made up of a few assets following a Heston model is achieved by solving C++ the corresponding PDE with the Monte Carlo nesting method (part \ref{part:nesting}).
 \item Some microgrid problems in the energy sector are solved using the python interface by dynamic programming methods (part \ref{part:dynProg}) using grids with linear interpolation
   (subsection \ref{lineargridsection})  to discretize the energy level in the battery and the different regressors using:
   \begin{enumerate}
   \item  either local polynomials with an suitable support size (subsection \ref{subsec::local}) ,
   \item  either global polynomials (section \ref{sec:globPol})
   \item or kernel regression  (section \ref{sec:kernelReg})
    \end{enumerate}
 \end{itemize}

 
 \chapter{General mathematical setting}
In a continuous frame, the controlled state is given by a stochastic differential equation
\begin{equation}
\label{eds}
\left \{
\begin{array}{lll}
dX^{x,t}_s & = & b_a(t,X^{x,t}_s) ds + \sigma_a(s,X^{x,t}_s) dW_s \nonumber \\
X^{x,t}_t &=& x \nonumber
\end{array}
\right .
\end{equation}
where 
\begin{itemize}
\item $W_t$  is a $d$-dimensional Brownian motion on a probability space $(\Omega,\Fc,\P)$ endowed with the natural (complete and continuous line) filtration $\F=(\Fc_t)_{t\le T}$ generated by    $W$ up to a fixed time horizon $T>0$,
\item $\sigma_{a}$ is a Lipschitz continuous function of $(t,x,a)$  defined on $[0,T] \times \R^d \times \R^n$ and taking values in the set of $d$-dimensional square matrices,
\item $b_{a}$ is a  Lipschitz continuous function of $(t,x,a)$  defined on $[0,T]\times \R^d \times \R^n$ and taking values  in $\R^d$,
\item $a$ a control adapted to the filtration taking values in $\R^n$.
\end{itemize}
Suppose we want to minimize a cost function  $J(t,x,a) =  \mathbb{E}[\int_{t}^T f_a(s,X^{x,t}_s) e^{\int_t^s c_a(u,X^{x,t}_u) du } ds + e^{\int_t^T c_a(u,X^{x,t}_u) } g(X^{x,t}_T)]$  compared to the $a$ control. It is well known \cite{fleming2006controlled} that the optimal value $ \hat J(t,x) = \inf_{a} J(T-t,x,a)$ is a viscosity solution of the equation 
\begin{eqnarray}
\frac{\partial v}{\partial t}(t,x) &  -&  \inf_{a \in \mathop{A}} \left( \frac{1}{2} tr(\sigma_a(t,x)\sigma_a(t,x)^T D^2 v(t,x)) + b_a(t,x) D v(t,x) \right.  \nonumber  \\
  &  & \left .  + c_a(t,x) v(t,x)+ f_a(t,x) \vphantom{\int_t} \right)  =  0  \mbox{ in  } \R^d \nonumber  \\
v(0,x)& = & g(x) \mbox{ in } \R^d
\label{hjb}
\end{eqnarray}
According to certain classical hypotheses on the coefficients \cite{fleming2006controlled}, the previous equation known as the Hamilton Jacobi Bellman equation admits a solution of unique viscosity (\cite{ishii1990viscosity}).\\
Solving the previous equation is quite difficult, especially in dimensions larger than 3 or 4.\\
The library provides tools to solve this equation and simplified versions of it.
\begin{itemize}
\item a first method supposes that $X^{x,t}_s  = (X^{x,t}_{1,s},X^{x,t}_{2,s})$ where $X^{x,t}_{1,s}$ is not controlled
\begin{equation}
\label{eds1}
\left \{
\begin{array}{lll}
dX^{x,t}_{1,s} & = & b(t,X^{x,t}_{1,s}) ds + \sigma_(s,X^{x,t}_{1,s})dW_s  \\
X^{x,t}_{1,t} &=& x 
\end{array}
\right .
\end{equation}
and $X^{x,t}_{2,s}$ has no diffusion term
\begin{equation}
\label{eds2}
\left \{
\begin{array}{lll}
dX^{x,t}_{2,s} & = & b_a(t,X^{x,t}_{2,s}) ds  \nonumber \\
X^{x,t}_{2,t} &=& x \nonumber
\end{array}
\right .
\end{equation}
In this case, we can use Monte Carlo methods based on regression to solve the problem. The method is based on the principle of dynamic programming and can be used even if the uncontrolled SDE is controlled by a general Levy process. This method can be used even if the controlled state takes only a few discrete values.\\
A second approach based on dynamic programming uses scenario trees: in this case, the uncertainties evolve on a tree taking only discrete values.
\item The second case is a special case of the previous one when the problem to be solved is linear and the controlled state takes values at continuous intervals. The value function must be convex or concave with respect to the controlled variables.
This method, the SDDP method, is used when the dimension of the controlled state is large, which prevents the use of the dynamic programming method.
As before, the uncertainties can be described either by scenarios or by a scenario tree.
\begin{Remark}
The use of this method requires other assumptions which will be described in the dedicated chapter.
\end{Remark}
\item A third method solves the Monte Carlo problem when a process is controlled but by an uncontrolled process. this is generally the optimization of a portfolio:
\begin{itemize}
\item The value of the portfolio is deterministically controlled and discretized on a network,
\item The evolution of the portfolio is driven by an uncontrolled exogenous process: market prices.
\end{itemize}
\item In the fourth method, we will assume that the state takes continuous values, we will solve equation \reff{hjb} using semi-Lagrangian methods discretizing the Brownian motion with two values and using some interpolations on grids.
  \item Finally, we present a general pure Monte Carlo method based on automatic differentiation and randomization of the time step to solve general non-linear equations and which can be used to solve certain control problems.
\end{itemize}
In what follows, we assume that a temporal discretization is given for the resolution of the optimization problem. We assume that the step discretization is constant and equal to $h$ such that $t_i= i h$.
First, we describe some useful tools developed in the library for stochastic control.
Then, we explain how to solve certain optimization problems using these developed tools.\\
\begin{Remark}
  In the library, we rely a lot on the 
  \href{http://eigen.tuxfamily.org}{Eigen library}: \code{ArrayXd}which represents a double vector, \code{ArrayXXd} for a double matrix and \code{ArrayXi} for a vector of integer.
\end{Remark}


\part{Useful tools for stochastic control} 
\chapter{The grids and their interpolators}
\label{gridChapter}
In this chapter we develop the tools used to interpolate a discretized function on a given grid.
A grid is  a set of point in $\R^d$ defining meshes which can be used to interpolate a function on an open set in  $\R^d$.
These tools are  used  to interpolate a given function, for example at certain stock points, when it comes to storage.
These are also useful for semi-Lagrangian methods, which require efficient interpolation methods.
In StOpt four types of grids are currently available:
\begin{itemize}
\item the first and second are grids used to interpolate a function linearly on a grid;
\item the third type of grid, starting from a regular grid, makes it possible to interpolate on a grid at Gauss - Lobatto points on each mesh;
\item the last grid allows to interpolate a function in high dimension using the sparse gridmethod. The approximation is linear, quadratic,
or cubic in each direction.
\end{itemize}
Each type of grid is associated with iterators.
An iterator on a grid makes it possible to iterate on all the points of the grids. All iterators derive from abstract class \href{run:../StOpt/StOpt/core/grids/GridIterator.h}{\code{GridIterator}}

\lstinputlisting[style=CStyle]{../StOpt/StOpt/core/grids/GridIterator.h}
All iterators share some common characteristics:
\begin{itemize}
\item  the \code{getCount} method provides the number associated with the current grid point,
\item  the \code{next} method allows you to go to the next point, while the \code{nextInc} method allows you to go to the point\code{p\_incr},
\item  the \code{isValid} method checks that we are still on a grid point,
\item  the  \code{getNbPointRelative} allows to get the number of points on which a given iterator can iterate,
\item   the \code{getRelativePosition} retrieves the number of points already iterated by the iterator.
\end{itemize}
In addition, we can go directly to a given point: this functionality is useful for "mpi'' when some calculations on the grid are distributed on some processors and threads. This possibility is given by the method \code{jumpToAndInc}. \\
Using a grid  \code{regGrid} the following source code makes it possible to iterate over the points of the grids and obtain coordinates.
For each coordinate, a function $f$ is used to fill an array of values.
As mentioned earlier, each type of grid has its own grid iterator which can be obtained by the \code{getGridIterator} method.
\begin{lstlisting}[style=CStyle]
    ArrayXd data(regGrid.getNbPoints()); // create an array to store the values of the function f 
    shared_ptr<GridIterator> iterRegGrid  =  regGrid.getGridIterator();
    while (iterRegGrid->isValid())
    {
        ArrayXd pointCoord = iterRegGrid->getCoordinate(); // store the coordinates of the point
        data(iterRegGrid->getCount()) = f(pointCoord); // the value is stored in data at place iterRegGrid->getCount()
        iterRegGrid->next(); // go to next point
    }
\end{lstlisting}
It is also possible to ``skip''  certain points and repeat for the "p''  points afterwards. This possibility is useful for multithreaded tasks on points.\\
For each type of grid, an interpolator is provided to interpolate a given function on a grid. Note that the interpolator is created {\bf for a given point} where we want to interpolate.
All interpolators  (which are not spectral interpolators) derive from
\code{Interpolator}  whose source code is given below.
\lstinputlisting[style=CStyle]{../StOpt/StOpt/core/grids/Interpolator.h}
All interpolators provide a constructor  specifying the point where the interpolation is carried out and the two functions \code{apply} and \code{applyVec} interpolating either a function (and returning a value)
 or
an array of functions returning an array of interpolated values.\\

All grid classes derive from an abstract class \code{SpaceGrid} below allowing to retrieve an iterator associated with the points of the grid (with possible jumps) and
to create an interpolator associated with the grid.
\lstinputlisting[style=CStyle]{../StOpt/StOpt/core/grids/SpaceGrid.h}
 All the grids objects, interpolators and iterators on grids point are in
 \centercode{StOpt/core/grids}
 Grid objects are mapped to python, giving the possibility of retrieving the iterators and interpolators associated with a grid. Examples of  Python can be found
in \centercode{test/python/unit/grids}
\section{Linear grids}
\subsection{Definition and C++ API}
\label{lineargridsection}
Two kinds of grids are developed:
\begin{itemize}
\item the first one  is the \href{run:../StOpt/StOpt/core/grids/GeneralSpaceGrid.h}{\code{GeneralSpaceGrid}} with Constructor
\begin{lstlisting}[style=CStyle]
GeneralSpaceGrid(const  std::vector<shared_ptr<Eigen::ArrayXd> >   &p_meshPerDimension)
\end{lstlisting}
where \code{std::vector<shared\_ptr<Eigen::ArrayXd>>}  is a vector of (pointer to) arrays defining the grid points in each dimension.
In this case the grid is not regular and the mesh varies in space (see figure \ref{genGrid}).

\begin{figure}[h]
\centerline{
\includegraphics[width=4cm]{generalGrid.png}}
\caption{2D general grid}
\label{genGrid}
\end{figure}

\item the second one is the \href{run:../StOpt/StOpt/core/grids/RegularSpaceGrid.h}{\code{RegularSpaceGrid}}  with Constructor
\begin{lstlisting} [style=CStyle]
RegularSpaceGrid(const Eigen::ArrayXd &p_lowValues, const Eigen::ArrayXd &p_step, const  Eigen::ArrayXi &p_nbStep)
\end{lstlisting}
The \code{p\_lowValues} corresponds to the bottom of the grid, \code{p\_step} the size of each mesh, \code{p\_nbStep} the number of steps in each direction (see figure \ref{regGrid}) 
\begin{figure}[h]
\centerline{
\includegraphics[width=7cm]{regularGrid.png}}
\caption{2D regular grid}
\label{regGrid}
\end{figure}
\end{itemize}
For each grid, a linear interpolator can be generated  by calling the \code{createInterpolator} method or by directly creating the interpolator:
\begin{lstlisting}[style=CStyle]
  /** \brief Constructor
   *  \param p_grid   is the grid used to interpolate
   *  \param p_point  is the coordinates of the points used for interpolation
   */
 LinearInterpolator( const FullGrid *   p_grid , const Eigen::ArrayXd &p_point):
\end{lstlisting}
Its construction from a  grid (\code{regLin}) and from an array \code{data} containing the values of the function at the points of the grid is given below (taking an example above for fill in the table \code{data})
\begin{lstlisting}[style=CStyle]
    ArrayXd data(regGrid.getNbPoints()); // create an array to store the values of the function f 
    shared_ptr<GridIterator> iterRegGrid  =  regGrid.getGridIterator();
    while (iterRegGrid->isValid())
    {
        ArrayXd pointCoord = iterRegGrid->getCoordinate(); // store the coordinate of the point
        data(iterRegGrid->getCount()) = f(pointCoord); // the value is stored in the data at location iterRegGrid->getCount()
        iterRegGrid->next(); // go to next point
    }
    // point where to interpolate
    ArrayXd point = ArrayXd::Constant(nDim, 1. / 3.);
    // create the interpolator
    LinearInterpolator  regLin(&regGrid, point); 
    // get back the interpolated value
    double interpReg = regLin.apply(data);
\end{lstlisting}
Let $I_{1,\Delta X}$ be the linear interpolator where the mesh is $\Delta x = (\Delta x^1, \dots, \Delta x^d)$. We obtain for a function $f$  in $C^{k+1}(\R^d)$ with $k \le 1$
\begin{eqnarray}
|| f - I_{1,\Delta x} f ||_{\infty} \le c \sum_{i=1}^d  \Delta x^{k+1}_i \sup_{x \in [-1,1]^d} |\frac{\partial^{k+1} f}{\partial x_i^{k+1}}|
\label{InterpRegulier}
\end{eqnarray}
In particular if $f$ is only Lipschitz
\begin{eqnarray*}
|| f - I_{1,\Delta x} f ||_{\infty} \le K \sup_{i} \Delta x_i.
\end{eqnarray*}
\subsection{The python API}
The python API allows you to use grids with a syntax similar to the C++ API. Here, we give an example with a regular grid
\lstinputlisting[style=PStyle]{../StOpt/test/python/unit/grids/testRegularGrids.py}
A similar example can be given for a general grid with linear interpolation
\lstinputlisting[style=PStyle]{../StOpt/test/python/unit/grids/testGrids.py}

\section{Legendre grids}
\label{legendregridsection}
With linear interpolation, to obtain a precise solution, it is necessary to refine the mesh so that $\Delta x$ goes to zero.
Another approach consists in trying to fit a polynomial on each mesh using a high degree interpolator.
\subsection{Approximation of a function in 1 dimension}
From now on, by resizing we assume that we want to interpolate a function $f$  on $[-1,1]$.  All the following results can be extended by tensorization in dimension greater than 1.
$\mathop{P_N}$ is the set of polynomials of total degree less than or equal to $N$.
The minmax approximation of $f$ of degree $N$ is the polynomial $P^*_N(f)$ such that:
$$
|| f - P^*_N(f)||_\infty = \min_{p \in {\mathop P_N}} || f -p||_{\infty}
$$
We call  $I^X_N$  interpolator from $f$  on a grid of $N+1$ points of $[-1,1]$ $X= (x_0, \dots, x_N)$, the unique polynomial of degree $N$ such that
$$ I^X_N(f)(x_i) = f(x_i),  0 \le i \le N$$
This polynomial can be expressed in terms of the Lagrange polynomial $l^X_i,  0 \le i \le N$  associated with the grid ($l^X_i$ is the unique polynomial
of degree $N$ taking a value equal to 1 at the point $i$ and $0$ at the other interpolation points).
$$
 I^X_N(f)(x)  = \sum_{i=0}^N f(x_i) l^X_i(x)
$$
The interpolation error can be expressed in terms of interpolation points:
$$ 
|| I^X_N(f)(x) - f ||_\infty  \le (1 + \lambda_N(X)) || f- P_N^{*}(f) ||_\infty 
$$
where $\lambda_N(X)$ is the Lebesgue constant associated with the Lagrange quadrature on the grid:
$$
\lambda_N(X) = \max_{x \in[-1,1]} \sum_{i=0}^N | l_i^X(x) |.
$$
We have the following bound 
$$
|| I^X_N(f)(x)||_\infty \le  \lambda_N(X) sup_{x_i \in X} |f(x_i)| \le \lambda_N(X) || f ||_\infty
$$
and the Erd\"os theorem states that 
$$
\lambda_N(X) > \frac{2}{\Pi} log(N+1)-C
$$
It is well--known that the use of a uniform grid $X_u$ is not optimal, because like $N \longrightarrow \infty$, the Lebesgue constant satisfies
$$
\lambda_N(X_u) \simeq \frac{2^{N+1}}{e N \ln N}
$$
and the quadrature error  in $L_\infty$ increases a lot with $N$. Its use brings some oscillations giving the Runge effect.
On Figures~\ref{fig::rungeEffect1}, \ref{fig::rungeEffect2},  \ref{fig::rungeEffect3}, \ref{fig::rungeEffect4}, we trace the function Runge $\frac{1}{1 + 25 x^2}$ against its interpolation with polynomial with equidistant interpolation.
\begin{figure}[h]
\centering
\begin{subfigure}[b]{0.4\textwidth}
  \includegraphics[width=6cm]{RungeDeg3.png}
  \caption{}\label{fig::rungeEffect1}
\end{subfigure}
\qquad
\begin{subfigure}[b]{0.4\textwidth}
  \includegraphics[width=6cm]{RungeDeg4.png}
   \caption{}\label{fig::rungeEffect2}
\end{subfigure}
\qquad
\begin{subfigure}[b]{0.4\textwidth}
  \includegraphics[width=6cm]{RungeDeg8.png}
  \caption{}\label{fig::rungeEffect3}
\end{subfigure}
\qquad
\begin{subfigure}[b]{0.4\textwidth}
\includegraphics[width=6cm]{RungeDeg18.png}
\caption{}\label{fig::rungeEffect4}
\end{subfigure}
\caption{Runge function $\frac{1}{1 + 25 x^2}$ and its polynomial interpolations at degrees 3, 4, 8, and 18.}
\label{fig::rungeEffect}
\end{figure}
We therefore wish to have a quadrature with a "optimal'' Lebesgue constant. For example Gauss--Chebyshev interpolation points (corresponding to the $0$ of the polynomial
$T_{N+1}(x)= \cos ((N+1) \arccos(x))$ give a Lebesgue constant $\lambda_N(X_{GC})$ equal to 
$$
\lambda_N(X_{GC}) \simeq  \frac{2}{\Pi} \ln(N+1)
$$
For our problem, we want to interpolate a function on meshes with great precision on the mesh while respecting the continuity of the function between the meshes. In order to 
ensure this continuity we want  the extreme points of the resized mesh $[-1,-1]$ (therefore $-1$, $1$) to be on the interpolation grid.
This leads to the Gauss--Lobatto--Chebyshev interpolation grid.\\
In  the library we choose to use the Gauss--Lobatto--Legendre interpolation grids which are as efficient as the Gauss--Lobatto--Chebyshev grids (in term of Lebesgue constant) but less costly in calculation due to the absence of trigonometric function.
We recall that the Legendre polynomial satisfies the recurrence
\begin{eqnarray*}
(N+1) L_{N+1}(x) = (2N+1) x L_N(x) - N L_{N-1}(x)
\end{eqnarray*}
with $L_0 =1$, $L_1(x)=x$.\\
These polynomials are orthogonal with the scalar product $(f,g) = \int_{-1}^1 f(x)g(x) dx$.
We are interested in the derivatives of these polynomials $L^{'}_N$ which satisfy the recurrence
\begin{eqnarray}
N L^{'}_{N+1}(x) = (2N+1) x L^{'}_N(x) -(N+1) L^{'}_{N-1}(x) \nonumber
\end{eqnarray}
These polynomials are orthogonal with the scalar product  $(f,g) = \int_{-1}^1 f(x)g(x)(1-x^2) dx$.
The Gauss--Lobatto--Legendre grids points for a grid with $N+1$ points are $\eta_1 = -1, \eta_{N+1} =1$ and the $\eta_i$ $(i=2,\dots,N)$   zeros of $L^{'}_{N}$.
The $\eta_i$ $(i=2,\dots,N)$ are eigenvalues of the matrix $P$
\begin{eqnarray*}
P &=& \left ( \begin{array}{ccccc}
              0  & \gamma_1 & \dots& 0 & 0 \\
              \gamma_1 & 0 & \dots   & 0 & 0 \\
              \vdots      & \vdots & \ddots & \vdots & \vdots \\
              0  & 0 & \dots & 0 & \gamma_{N-2} \\
              0  & 0 & \dots & \gamma_{N-2} & 0 
              \end{array}
 \right), \nonumber  \\
\gamma_n & = & \frac{1}{2} \sqrt{\frac{n(n+2)}{(n+\frac{1}{2})(n+\frac{3}{2})}}  , 1 \le n \le N-2 , \nonumber
\end{eqnarray*}
The interpolation $I_{N}(f)$ is expressed in terms of Legendre polynomials by
\begin{eqnarray*}
I_{N}(f) & =&  \sum_{k=0}^{N} \tilde f_k L_k(x) , \nonumber  \\
\tilde f_k &  =  &   \frac{1}{\gamma_k} \sum_{i=0}^{N} \rho_i f(\eta_i) L_k( \eta_i) , \nonumber \\
\gamma_k & = & \sum_{i=0}^{N} L_k(\eta_i)^2 \rho_i,
\end{eqnarray*}
 and the weights satisfy
\begin{eqnarray*}
\rho_{i} &  = & \frac{2.}{(M+1)M L_{M}^2(\eta_i)} ,  1 \le i \le N+1.
\end{eqnarray*}
More details can be found in \cite{azaiez1993methodes}. In the figure \ref{fig:gllRunge}, we give the interpolation obtained with the Gauss--Lobatto--Legendre quadrature with two degrees of approximation.
\begin{figure}[h]
\centering
\begin{subfigure}[b]{0.3\textwidth}
\includegraphics[width=6cm]{GLL6.png}
\end{subfigure}
\qquad
\begin{subfigure}[b]{0.3\textwidth}
\includegraphics[width=6cm]{GLL10.png}
\end{subfigure}
\caption{Interpolation with Gauss--Legendre--Lobatto grids}
\label{fig:gllRunge}
\end{figure}
\begin{itemize}
  \item 
When the function is not regular we introduce a weaker notion than the notion of derivative. We denote $w( f, \delta )$ The modulus of continuityon $[-1,1]$ of a function
$f$ as
\begin{eqnarray}
w(f, \delta)= \sup_{ \begin{array}{c}
                    x_1,x_2 \in [-1,1] \\
                    | x_1- x_2| < \delta 
                   \end{array}
                  }
  | f(x_1)- f(x_2)| \nonumber
\end{eqnarray}
The modulus of continuity makes it possible to express the best approximation of a function by a polynomial with the Jackson theorem:
\begin{Theorem}
For a continuous function  $f$ on  $[-1,1]$ 
\begin{eqnarray*}
 || f - P_N^*(f) ||_{\infty}  \le K w(f, \frac{1}{N}) 
\end{eqnarray*}
\end{Theorem}
and we deduce that for an interpolation grid$X$
\begin{eqnarray*}
|| I^{X}_N(f)(x) - f ||_\infty &  \le &   M(N)  \\
M(N) & \simeq  & K  w(f, \frac{1}{N}) \lambda_N(X) 
\end{eqnarray*}
a function is Dini--Lipschitz continues if $ w(f, \delta) log(\delta) \longrightarrow 0$ as $\delta \longrightarrow 0$. It is clear that the functions of Lipschitz are Dini--Lipschitz continuously
because $w(f, \delta) log(\delta) \le K log(\delta) \delta$.
\item
When the solution is more regular, we can express the interpolation error as a function of its derivatives and we obtain the following Cauchy theorem for an interpolation grid  $X$ (see \cite{quarteroni2000methodes})
\begin{Theorem}
If $f$ is  $C^{N+1}$, and  $X$  an interpolation grid with $N+1$ points, the interpolation error checks 
\begin{eqnarray}
E(x) &=& f(x) - I_N^X(f)(x) = \frac{f^{N+1}(\eta)}{(N+1)!} W_{N+1}^X(x)
\end{eqnarray}
where $\eta \in [-1,1]$ and $W_{N+1}^X(x)$ is the nodal polynomial of degree $N+1$ (the polynomial with the monomial of the highest degree with coefficient 1 being zero at all points  $N+1$  of $X$)
\end{Theorem}
If we partition a domain  $I =[a,b]$ into a few meshes of size $h$ and we use a Lagrange interpolator for the function $f \in C^{k+1}$ , $k \le N$
we obtain
\begin{eqnarray*}
|| f - I^X_{N,\Delta x} f ||_{\infty} \le c h^{k+1} || f^{(k+1)} ||_\infty
\end{eqnarray*}
\end{itemize}
\subsection{Extension in dimension $d$}
In the dimension $d$, we denote $P_{N}^*$ the best multivariate polynomial approximation of $f$ of total degree less than $N$ on $[-1,1]^d$.
On a $d$ multidimensional grid $X =X_{N}^d$,  we define the multivariate interpolator as the composition of one-dimensional interpolator
$ I^{X}_{N}(f)(x) =  I^{X_{N},1}_{N} \times I^{X_{N},2}_{N} \dots \times I^{X_{N},d}_{N} (f)(x)$ where $ I^{X_{N},i}_{N}$  represents for the interpolator in dimension $i$.
We get the following interpolation error
\begin{eqnarray*}
|| I^{X}_{N}(f) - f ||_\infty  \le (1 + \lambda_{N}(X_{N}))^d || f- P_{N}^*(f) ||_\infty, \nonumber
\end{eqnarray*}
The error associated with the min max approximation is given by Feinerman and Newman \cite{feinerman1974polynomial}, Soardi \cite{soardi1984serie}
\begin{eqnarray*}
|| f - P_{N}^*(f)||_\infty & \le &  (1+  \frac{\pi^2}{4} \sqrt{d}) w(f,\frac{1}{N+2}) \nonumber
\end{eqnarray*}
We deduce that if $f$ is only Lipschitz
\[
\boxed{
|| I^{X}_{N}(f)(x) - f ||_\infty  \le  C \sqrt{d} \frac{(1+\lambda_N(X))^d}{N+2}
}
\]
If the function is regular (in $C^{k+1}([-1,1]^d)$, $k < N$) we get 
\begin{eqnarray*}
|| f - P_{N}^*(f)||_\infty & \le & \frac{C_k}{N^k} \sum_{i=1}^d  \sup_{x \in [-1,1]^d} |\frac{\partial^{k+1} f}{\partial x_i^{k+1}}| \nonumber
\end{eqnarray*}
If we partition the domain $I =[a_1,b_1] \times \dots \times [a_d,b_d] $ in meshes of size $ \Delta x = (\Delta x_1,\Delta x_2,\dots,\Delta x_d)$ and use a Lagrange interpolation on each mesh we obtain
\begin{eqnarray*}
\boxed{
|| f - I^X_{N,\Delta x} f ||_{\infty} \le c \frac{(1+\lambda_N(X))^d}{N^k}   \sum_{i=1}^d  \Delta x^{k+1}_i \sup_{x \in [-1,1]^d} |\frac{\partial^{k+1} f}{\partial x_i^{k+1}}|
}
\end{eqnarray*}
On figure \ref{GLLpoints2D} we give the Gauss--Legendre--Lobatto points in 2D for $2\times 2$ meshes and a polynomial of degree $8$ in each direction
\begin{figure}[h]
\centerline{
\includegraphics[width=7cm]{GLLPoint2D.png}}
\caption{Gauss--Legendre--Lobatto points on $2 \times 2 $ meshes.}
\label{GLLpoints2D}
\end{figure}
\subsection{Truncature}
In order to avoid oscillations during the interpolation, a truncation is used on each mesh so that the modified interpolator $\hat I^X_{N,\Delta x}$ checks:
\beq
\hat I^X_{N,\Delta x} f (x) =   \min_{x_i \in M} f(x_i) \wedge I^X_{N,\Delta x} f (x) \vee  \max_{x_i \in M} f(x_i)
\enq
where the $x_i$ are the interpolation points on the mesh $M$ containing the point $x$.
For all the characteristics of this modified operator, we can see \cite{warin2016some}.
\subsection{The C++ API}
The grid using Gauss--Legendre--Lobatto points can be created using this constructor:
\begin{lstlisting}[style=CStyle]
    RegularLegendreGrid(const Eigen::ArrayXd &p_lowValues, const Eigen::ArrayXd &p_step, const  Eigen::ArrayXi &p_nbStep, const Eigen::ArrayXi & p_poly);
\end{lstlisting}
The \code{p\_lowValues} corresponds to the bottom of the grid, \code{p\_step} the size of each mesh, \code{p\_nbStep} the number of steps in each direction (see figure \ref{regGrid}).
On each mesh the polynomial approximation in each dimension is specified by the table \code{p\_poly}.\\
\begin{Remark}
If we take a polynomial of degree 1 in each direction this interpolator is equivalent to the linear interpolator. It’s sort of less
efficient than the linear interpolator on a Regular grid described in the section above.
\end{Remark}

We illustrate the use of the grid, its iterator and its interpolator used to draw the figures \ref{fig:gllRunge}.
\begin{lstlisting}[style=CStyle]

    ArrayXd lowValues = ArrayXd::Constant(1,-1.); // corner  point
    ArrayXd step=  ArrayXd::Constant(1,2.); // mesh size
    ArrayXi  nbStep = ArrayXi::Constant(1,1); // number of meshes in each direction
    ArrayXi nPol = ArrayXi::Constant(1,p_nPol); // polynomial approximation
    // regular Legendre
    RegularLegendreGrid regGrid(lowValues, step, nbStep, nPol);

    // Data table to store values on the grid points
    ArrayXd data(regGrid.getNbPoints());
    shared_ptr<GridIterator> iterRegGrid  =  regGrid.getGridIterator();
    while (iterRegGrid->isValid())
    {
      ArrayXd pointCoord = iterRegGrid->getCoordinate();
      data(iterRegGrid->getCount()) = 1./(1.+25*pointCoord(0)*pointCoord(0)); // runge storage function
      iterRegGrid->next();
    }
    // point
    ArrayXd point(1);
    int nbp =  1000;
    double dx = 2./nbp;
    for (int ip =0; ip<= nbp; ++ip)
      {
        point(0)= -1+ ip* dx;
	// create interpolator
        shared_ptr<Interpolator> interp = regGrid.createInterpolator( point);
        double  interpReg = interp->apply(data); // interpolated value
     }
\end{lstlisting}
The operator defined above is more efficient when we interpolate several functions at the same point. Its is
the case for example for the valuation of a storage with regression where one wishes to interpolate all the simulations at the same level of stock.

In some cases it is more practical to build an interpolator acting on a global function.
This is the case when you have only one function
and you want to interpolate at several points for this function.
In this specific case an interpolator deriving from the class \code{InterpolatorSpectral} can be constructed:
\lstinputlisting[style=CStyle]{../StOpt/StOpt/core/grids/InterpolatorSpectral.h}
Its constructor is given by:
\begin{lstlisting}[style=CStyle]
    /** \brief Constructor taking values on the grid
     *  \param p_grid is the grid used to interpolate
     *  \param p_values Value of the function at the points of the grid.
     */
    LegendreInterpolatorSpectral(const shared_ptr< RegularLegendreGrid>  &p_grid , const Eigen::ArrayXd &p_values) ;
\end{lstlisting}
This class has a member allowing to interpolate at a given point:
\begin{lstlisting}[style=CStyle]
    /**  \brief  interpolate
     *  \param  p_point  coordinates of the point for interpolation
     *  \return interpolated value
     */
    inline double apply(const Eigen::ArrayXd &p_point) const
\end{lstlisting}
We give an example of using this class, by interpolating a function $f$ function in dimension 2.
\begin{lstlisting}[style=CStyle]
    ArrayXd lowValues = ArrayXd::Constant(2,1.); // bottom of the domain
    ArrayXd step  = ArrayXd::Constant(2,1.); // mesh size
    ArrayXi  nbStep = ArrayXi::Constant(2,5); // number of meshes in each direction
    ArrayXi  nPol = ArrayXi::Constant(2,2) ; // polynomial of degree 2 in each direction
    // regular
    shared_ptr<RegularLegendreGrid> regGrid(new RegularLegendreGrid(lowValues, step, nbStep, nPol));
    ArrayXd data(regGrid->getNbPoints()); // Data table
    shared_ptr<GridIterator> iterRegGrid  =  regGrid->getGridIterator(); // iterator on the grid points
    while (iterRegGrid->isValid())
    {
        ArrayXd pointCoord = iterRegGrid->getCoordinate();
       data(iterRegGrid->getCount()) =  f(pointCoord);
         iterRegGrid->next();
    }

    // spectral interpolator 
    LegendreInterpolatorSpectral interpolator(regGrid,data);
    // interpolation point
    ArrayXd pointCoord(2, 5.2);
    // interpolated value
    double vInterp = interpolator.apply(pointCoord);
\end{lstlisting}

\subsection{The python API}
Here is an example using Legendre grids:
\lstinputlisting[style=PStyle]{../StOpt/test/python/unit/grids/testLegendreGrid.py}

\section{Sparse grids}
\label{sec::Sparse}
A representation of a function of dimension $d$ for $d$ small (less than 4) is obtained by tensorization in the preceding methods of interpolation.
When the function is smooth and its cross derivatives are bounded,  the function can be represented using the sparse grid methods.
This method makes it possible to represent the function with much less points than the traditional one without losing too much by interpolating.
The sparse grid method was used for the first time by assuming that the function $f$ to be represented is zero at the boundary $\Gamma$ of the domain. 
This assumption is important because it makes it possible to limit the explosion of the number of points to the dimension of the problem.
In many application this assumption is not realistic or it is impossible to work on $f - f_{|\Gamma}$. 
In this library we will assume that the function is not zero at the borderand provide grid object, iterators and interpolators to interpolate certain functions
depicted on the sparse grid.
However, for the sake of clarity of presentation, we will start  with the case of a function disappearing on the border.
\subsection{The sparse linear grid method}
\label{linearSection}
We recall some classic results on sparse grids which can be found in \cite{pfluger2010spatially}. 
We first assume that the function we are interpolating is zero at the border.
By a change of coordinates a hyper-cube domain can be changed to a domain $\omega = [0,1]^d$.
By Introducing the hat function $\phi^{(L)}(x)= \max(1-|x|,0)$ (where $(L)$ means linear),  we obtain the followingl one-dimensional local hat function by translation and dilation  
$$\phi_{l,i}^{(L)}(x) = \phi^{(L)}(2^l x-i)$$
according to the level $l$ and the index $i$, $0< i< 2^l$. 
The grid points used for the interpolation are noted  $x_{l,i}=2^{-l}i$. 
In the dimension $d$, we introduce the basis functions 
$$ \phi_{\underline l, \underline i}^{(L)}(x) = \prod_{j=1}^d \phi_{l_j,i_j}^{(L)}(x_j)$$
via a tensorial approach for a point $ \underline x = (x_1, \dots, x_d)$, a multi-level $ \underline l := (l_1, \dots, l_d)$ and a multi-index $\underline i := (i_1, \dots , i_d).$ 
The grid points used for interpolation are noted $x_{\underline l,\underline i} := (x_{l_1,i_1}, \dots, x_{l_d,i_d})$.\\
We then present the index set $$B_{\underline l} := \left \{ \underline i: 1 \le i_j \le 2^{l_j}-1,  i_j \mbox{ odd }, 1 \le j \le d \right\}$$
 and the hierarchical base space.
\begin{eqnarray*}
 W_{\underline l}^{(L)}&:=& span\left \{ \phi^{(L)}_{\underline l, \underline i}(\underline x): \underline i \in B_{\underline l} \right\} 
\end{eqnarray*}
A representation of the space $W_{\underline l}^{(L)}$ is given in dimension 1 on the figure \ref{figWFunction1D}. 
\begin{figure}[h]
\centering
\includegraphics[width=5cm]{WSpace1S.png}
\caption{One dimensional $W^{(L)}$ spaces: $W_1^{(L)}$, $W_2^{(L)}$, $W_3^{(L)}$, $W_4^{(L)}$ and the nodal representation $W^{(L,N)}_4$ }
\label{figWFunction1D}
\end{figure}
The sparse mesh space is defined as follows:
\begin{eqnarray}
V_n &=& \underset{|\underline l|_1 \le n+d-1}{\oplus} W_{\underline l}^{(L)}
\label{classSparse}
\end{eqnarray}
\begin{Remark}
The conventional full grid space is defined as  $V_n^F =  \underset{|\underline l|_\infty \le n}{\oplus} W_{\underline l}^{(L)}$.
\end{Remark} 
At hierarchical increment space $W_{\underline l}^{(L)}$ corresponds to a nodal function space $W_{\underline l}^{(L,N)}$ such that
\begin{eqnarray*}
 W_{\underline l}^{(L,N)} &:=& span\left \{ \phi^{(L)}_{\underline l, \underline i}(\underline x): \underline i \in B^N_{\underline l} \right\}
\end{eqnarray*}
with  $$B^N_{\underline l} := \left \{ \underline i: 1 \le i_j \le 2^{l_j}-1,   1 \le j \le d \right\}.$$
In the figure \ref{figWFunction1D} the one-dimensional nodal base $W_4^{(L,N)}$ is generated by $W_4^{(L)}$ and the dotted base function.
The space $V_n$ can be represented as the space spawn by the $W^{(L,N)}_{\underline l}$ such that $|\underline l|_1= n+d-1$:
\begin{eqnarray}
V_n &=&  span\left  \{ \phi^{(L)}_{\underline l, \underline i}(\underline x): \underline i \in B_{\underline l}^N ,  |\underline l|_1 = n+d-1 \right \}
\label{classNodl}
\end{eqnarray}
A function $f$ is interpolated on the hierarchical basis like 
\begin{eqnarray*}
I^{(L)}(f) &=& \sum_{|\underline l|_1 \le n+d-1,  \underline i \in B_{\underline l}} \alpha_{\underline l, \underline i}^{(L)} \phi^{(L)}_{\underline l, \underline i}
\label{basisRecons}
\end{eqnarray*}
where  $\alpha_{\underline l, \underline i}^{(L)}$ are called the surplus (we give on the figure \ref{figWSurplus1D} a representation of these coefficients).
\begin{figure}[h]
\centering
\includegraphics[width=6cm]{figWSurplus1D.png}
\caption{Example of hierarchical coefficients}
\label{figWSurplus1D}
\end{figure}
These surpluses associated with a function $f$ are calculated  in the one-dimensional case for a node $m = x_{l,i}$  as the difference of the value of the function at the node and the linear representation of the calculated function with neighboring nodes. For example in figure  \ref{figFatherTree}, the hierarchical value is given by the relation:
\begin{eqnarray*}
\alpha^{(L)}(m) := \alpha_{l, i}^{(L)} = f(m) -0.5 (f(e(m)) + f(w(m)))
\end{eqnarray*}
where $e(m)$ is the east neighbor of $m$ and $w(m)$ the west one.
The procedure is generalized in dimension $d$ by successive hierarchy in all directions.
\begin{figure}[h]
\centering
\includegraphics[width=6cm]{figFatherTree.png}
\caption{Node involved in the linear, quadratic and cubic representation of a function at the node $m$ and $n$}
\label{figFatherTree}
\end{figure}
On figure \ref{figureSubSpace2D}, we give a representation of the subspace $W$  for $\underline l \le 3$ in dimension 2.\\
\begin{figure}[h]
\centering
\includegraphics[width=6cm]{figureSubSpace2D.png}
\caption{The two-dimensional subspace $W_{\underline l}^{(L)}$ up to $l=3$ in each dimension. Additional hierarchical functions corresponding to an approximation
on the complete grid are indicated by dotted lines.}
\label{figureSubSpace2D}
\end{figure}
In order to deal with functions non-zero at the boundary, two more basis are added to the first level as shown on figure \ref{figWFunction1DBound}.
\begin{figure}[h]
\centering
\includegraphics[width=5cm]{WSpace1SBound.png}
\includegraphics[width=5cm]{WSpace1SBoundMod.png}
\caption{One dimensional $W^{(L)}$ spaces  with linear functions with ``exact'' boundary (left) and ``modified'' boundary (right): $W_1^{(L)}$, $W_2^{(L)}$, $W_3^{(L)}$, $W_4^{(L)}$ }
\label{figWFunction1DBound}
\end{figure}
This approach leads to many more points than the one without the border. As indicated in \cite{pfluger2010spatially} for n =5, in dimension 8 have almost 2.8 million points in this approximation but only 6401 inside the domain.
On the figure \ref{fig2DBound} we give the points of the grids including boundary points in dimension 2 and 3 for a level $5$ of the sparse grid.
\begin{figure}[h]
\centering
\begin{subfigure}[b]{0.3\textwidth}
\includegraphics[width=6cm]{SparseBound2D.png}
\end{subfigure}
\qquad
\begin{subfigure}[b]{0.3\textwidth}
\includegraphics[width=6cm]{SparseBound3D.png}
\end{subfigure}
\caption{Sparse grid in dimension 2 and 3 with boundary points}
\label{fig2DBound}
\end{figure}


  If the boundary conditions are not important (infinite truncated domain in finance for example) the hat functions near the borders are modified by extrapolation (see figure \ref{figWFunction1DBound}) as explained in \cite{pfluger2010spatially}.
At level 1, we have only one degree of freedom assuming that the function is constant on the domain. At all the other levels, we extrapolate linearly towards the boundary the basis functions left and right, the other functions remaining unchanged. So the new function base in 1D $\tilde \phi$ becomes
\begin{equation}
\begin{array}{ccc}
\tilde \phi_{l,i}^{(L)}(x) &=& \left \{ \begin{array}{cc}
                                  1   &   \mbox{ if } l=1 \mbox{ and } i =1 \\
                                   \left \{ \begin{array}{cc}
                                         2 -2^l x &  \mbox{ if } x  \in [0,2^{-l+1}] \\
                                         0        & \mbox{ else}
                                         \end{array} \right \}  & \mbox{ if } l > 1 \mbox{ and } i=1 \\
                                   \left \{ \begin{array}{cc}
                                         2^l (x-1) +2 &  \mbox{ if } x  \in [1-2^{-l+1},1] \\
                                         0        & \mbox{ else }
                                         \end{array} \right \}  & \mbox{ if } l > 1 \mbox{ and } i= 2^l-1 \\
                                   \phi_{l,i}^{(L)}(x) & \mbox{ otherwise } 
                                   \end{array}
                               \right. \nonumber
\end{array}
\end{equation}
On the figure \ref{fig2DNoBound} we give the grid points by eliminating the boundary points in dimension 2 and 3 for a level $5$ of the sparse grid.
\begin{figure}[h]
\centering
\begin{subfigure}[b]{0.3\textwidth}
\includegraphics[width=6cm]{SparseNoBound2D.png}
\end{subfigure}
\qquad
\begin{subfigure}[b]{0.3\textwidth}
\includegraphics[width=6cm]{SparseNoBound3D.png}
\end{subfigure}
\caption{Sparse grid in dimensions 2 and 3 without boundary points}
\label{fig2DNoBound}
\end{figure}

The interpolation error associated with the linear operator $I^1 := I^{(L)}$ is related to the regularity of the crossed derivatives of the function \cite{bungartz1992dunne,bungartz1996concepts,bungartz1997multigrid}.
If $f$ is zero at the boundary and admits derivatives such as $ || \frac{\partial^{2d} u}{\partial x_1^{2} \dots \partial x_d^{2}}||_{\infty}  < \infty$ then
\begin{eqnarray}
|| f - I^1(f)||_\infty =  O(N^{-2} log(N)^{d-1}),
\label{ErrorInterpLin}
\end{eqnarray}
with $N$ the number of points per dimension.
\section{High order sparse grid methods}
\label{highOrderSection}
Changing the interpolator allows us to obtain a higher convergence rate mainly in the region where the solution is smooth.
By following \cite{bungartz1996concepts} and \cite{bungartz1997multigrid}, it is possible to obtain higher order interpolators. 
Using a quadratic interpolator, the reconstruction on the nodal base gives a quadratic function
on the support of the hat function previously defined and a continuous function of the whole domain.
The polynomial quadratic base is defined on $[2^{-l}(i-1),2^{-l}(i+1)]$ by $$\phi_{ l, i}^{(Q)}(x) = \phi^{(Q)}(2^l x-i)$$ with
$\phi^{(Q)}(x)= 1- x^2$. \\
The hierarchical surplus (coefficient on the basis) in a dimension is the difference between the value function at the node and the quadratic representation of the function using nodes available at the previous level. With the notation of figure  \ref{figFatherTree} 
\begin{eqnarray*}
\alpha(m)^{(Q)} & =&  f(m) -(\frac{3}{8} f(w(m))+\frac{3}{4} f(e(m)) - \frac{1}{8} f(ee(m))) \\
               &= & \alpha(m)^{(L)}(m) -\frac{1}{4}\alpha(m)^{(L)}(e(m))\\
               &= & \alpha(m)^{(L)}(m) -\frac{1}{4}\alpha(m)^{(L)}(df(m))
\end{eqnarray*}
where $df(m)$ is the direct father of the node $m$ in the tree structure.\\
Once again, the quadratic surplus of dimension $d$ is obtained by successive hierarchization in the different dimensions.\\
In order to take into account the boundary conditions, two linear functions $1-x$ and $x$ are added at the first level  (see figure \ref{figWFunction1DQuadBound}).\\
A version with modified boundary conditions can be derived for example by using linear interpolation at the boundary so that 
\begin{equation}
\begin{array}{ccc}
\tilde \phi_{l,i}^{(Q)}(x) &=& \left \{ \begin{array}{cc}
                                  \tilde \phi_{l,i}^{(L)}   &   \mbox{ if } i=1 \mbox{ or } i =  2^l-1 , \\
                                  \phi_{l,i}^{(Q)}(x) & \mbox{ otherwise } 
                                   \end{array}
                               \right. \nonumber
\end{array}
\end{equation}
\begin{figure}[h]
\centering
\includegraphics[width=5cm]{WSpace1SQuadBound.png}
\includegraphics[width=5cm]{WSpace1DQuadBoundMod.png}
\caption{One dimensional $W^{(Q)}$ spaces  with quadratic with ``exact'' boundary (left) and ``modified'' boundary (right): $W_1^{(Q)}$, $W_2^{(Q)}$, $W_3^{(Q)}$, $W_4^{(Q)}$ }
\label{figWFunction1DQuadBound}
\end{figure}
In the case of the cubic representation, on  figure \ref{figFatherTree} we need 4 points to define a function basis. In order to keep the same data structure, we use a cubic function base at node $m$ with value 1 at this node and 0 at the node $e(m)$, $w(m)$ and $ee(m)$ and we keep only the basic function between $w(m)$ and $e(m)$ \cite{bungartz1996concepts}. \\
Note that there are two basic types of function depending on the position in the tree. The basic functions are given on  $[2^{-l+1}i,2^{-l+1}(i+1)]$ by
\begin{eqnarray*}
\phi_{ l, 2i+1}^{(C)}(x) & = & \phi^{(C),1}(2^l x-(2i+1)) , \mbox{ if } i \mbox{ even }  \\
 & = & \phi^{(C),2}(2^l x-(2i+1)) , \mbox{ if } i  \mbox{ odd } 
\end{eqnarray*}
with $\phi^{(C),1}(x) = \frac{(x^2-1)(x-3)}{3}$, $\phi^{(C),2}(x) = \frac{(1-x^2)(x+3)}{3}$.\\
The surplus coefficient can be defined as above as the difference between the value function at the node and the cubic representation of the function at the parent node. Due to the two basis functions involved there are two types of cubic coefficient.
\begin{itemize}
\item 
For a node $m = x_{l,8i+1}$ or   $m = x_{l,8i+7}$ , $\alpha^{(C)}(m)  = \alpha^{(C,1)}(m)$, with $$\alpha^{(C,1)}(m) =   \alpha^{(Q)}(m) - \frac{1}{8} \alpha^{(Q)}(df(m))$$ 
\item 
For a node $m = x_{l,8i+3}$ or   $m = x_{l,8i+5}$ , $\alpha^{(C)}(m)  = \alpha^{(C,2)}(m)$, with $$\alpha^{(C,2)}(m) =    \alpha^{(Q)}(m) + \frac{1}{8} \alpha^{(Q)}(df(m))$$
\end{itemize} 
Note that a cubic representation is not available for $l=1$ so a quadratic approximation is used. 
As before, the boundary conditions are treated by adding two linear basis functions at the first level and a modified version is available. We choose the following basis functions as defined in figure \ref{figWFunction1DCubicBound}:
\begin{equation}
\begin{array}{ccc}
\tilde \phi_{l,i}^{(C)}(x) &=& \left \{ \begin{array}{cc}
                                  \tilde \phi_{l,i}^{(Q)}   &   \mbox{ if } i \in \{ 1, 3, 2^{l}-3, 2^l-1 \} , \\
                                  \phi_{l,i}^{(C)}(x) & \mbox{ otherwise } 
                                   \end{array}
                               \right. \nonumber
\end{array}
\end{equation}
\begin{figure}[h]
\centering
\includegraphics[width=5cm]{WSpace1DCubicB.png}
\includegraphics[width=5cm]{WSpace1DCubicBMod.png}
\caption{One dimensional $W^{(C)}$ spaces  with cubic and ``exact'' boundary (left) and ``modified'' boundary (right): $W_1^{(C)}$, $W_2^{(C)}$, $W_3^{(C)}$, $W_4^{(C)}$ }
\label{figWFunction1DCubicBound}
\end{figure}

According to \cite{bungartz1992dunne,bungartz1996concepts,bungartz1997multigrid}, if the function $f$  is zero at the boundary and admits derivatives such as 
$\sup_{\alpha_i \in \{2,\dots,p+1\}} \left \{ || \frac{\partial^{\alpha_1+ \dots +\alpha_d} u}{\partial x_1^{\alpha_1} \dots \partial x_d^{\alpha_d}}||_{\infty} \right \} < \infty$
then the interpolation error can be generalized for $I^2:= I^{(Q)}$, $I^3 :=  I^{(C)}$ by:
\begin{eqnarray*}
|| f - I^p(f)||_\infty =  O(N^{-(p+1)} log(N)^{d-1}), \quad p=2,3
\end{eqnarray*}
with $N$ the number of points per dimension.

\section{Anisotropy}
In many situations, there is no point in refining as much in each direction. For example, when we process multidimensional storage, we expect the mesh to be the same
order in each direction.
When the different storages have very different sizes, we want to further refine the storage with the largest capacity.
In order to treat this anisotropy, an extension of the sparse grids can be obtained by defining the weight $w$ in each direction.
The definition \ref{classSparse} is replaced by:
 \begin{eqnarray}
V_n = \underset{ \sum_{i=1}^d l_i w(i) \le n+d-1}{\oplus} W_{\underline l}^{(L)}
\label{anisotropicSparse}
\end{eqnarray}

 \section{Adaptation}
When the solution is not smooth, typically Lipschitz, there is no hope of obtaining convergence results for the classical rare grids (see above the interpolation error linked to crossed derivatives of the function).
The classic sparse grids must therefore be adapted so that the solution is refined near the singularities. 
In all adaptation methods, the hierarchical surplus  $\alpha_{\underline l, \underline i}$ is used to obtain an estimate of the local error. These coefficients give an estimate of the regularity of the value of the function at the discrete points by representing the second derivative of the discrete mixture of the function.
There are mainly two types of adaptation used:
\begin{itemize}
\item the first performs a local adaptation and only adds points locally \cite{bungartz2004sparse,griebel1998adaptive,griebel2005sparse,ma2009adaptive},
\item the second performs the adaptation at the level of the hierarchical space $W_{\underline l}$ (anisotropic sparse grid).
This approach detects the important dimensions that need to be refined and refines all the points of that dimension \cite{gerstner2003dimension}. This refinement is also achieved in areas where the solution can be smooth. A more local version has been developed in \cite{jakeman2011local}.
\end{itemize}
In the current version of the library, only the dimension adaptation is available. Details of the algorithm can be linked in \cite{gerstner2003dimension}.
After a first initialization with a first initialization with a space
 \begin{eqnarray}
V_n = \underset{ \sum_{i=1}^d l_i  \le n+d-1}{\oplus} W_{\underline l}^{(L)}
 \end{eqnarray}
 An active level set $\cal{A}$ is created grouping all the levels $\underline{l}$ so that $\sum_{i=1}^d l_i =  n+d-1$.
 All the other levels are grouped into a set $\cal{O}$.
 At each level $\underline{l}$ in $\cal{A}$ an error is estimated $e_{\underline{l}}$ and with any local error $e_{\underline{l}}$  a global error $E$ is calculated.
 Then the refinement algorithm~\ref{dimRef} is used by noting $\mathbf{e}_k$ the canonical basis in the dimension $k$.
\begin{algorithm}[h]
\caption{Dimension refinement for a given tolerance $\eta$}
\label{dimRef}
\begin{algorithmic}[1]
  \While{ $ E > \eta$}
  \State select $\underline{l}$ with the highest local error  $e_{\underline{l}}$
  \State $\cal{A} = \cal{A}  \setminus$ $\{ \underline l \}$
  \State $\cal{O} = \cal{O} $ $\cup $ $ \{ \underline{l} \}$
  \For{ $k=1$ to $d$}
  \State $\underline{m} = \underline{l} + \mathbf{e}_k$
  \If{  $ \underline{m} - \mathbf{e}_q \in \cal{O}$ for $q \in [1,d]$}
  \State $\cal{A} = \cal{A} $ $\cup $ $ \{ \underline{m} \}$
  \State Hierarchize all points belonging to $\underline{m}$
  \State calculate $e_{\underline{m}}$
  \State update $E$
  \EndIf
  \EndFor
  \EndWhile
\end{algorithmic}
\end{algorithm}
Sometimes, using sparse grids during time iterations, it can be interesting to enlarge the meshes. A similar algorithm~\ref{dimCoars} can be used to eliminate the levels
with a very small local error.
\begin{algorithm}[h]
\caption{Dimension coarsening for a given tolerance $\eta$}
\label{dimCoars}
\begin{algorithmic}
  \State  $\cal{B}$ all elements of $\cal{A}$ with a local error below $\eta$
  \While{ $\cal{B} $ non nonempty}
  \State select $\underline{l} \in \cal{B}$ with the lowest local error  $e_{\underline{l}}$
  \For{ $k=1$ to $d$}
  \State $\underline{m} = \underline{l} - \mathbf{e}_k$
  \If{ $m_k >0$}
  \If{  $ \underline{m} + \mathbf{e}_q \in \cal{B}$ for $q \in [1,d]$}
  \State $\cal{A} = \cal{A} $ $\setminus $ $ \{ \underline{m} + \mathbf{e}_q, q \in [1,d] \}$
  \State $\cal{B} = \cal{B} $ $\setminus $ $ \{ \underline{m} + \mathbf{e}_q, q \in [1,d] \}$
  \State  $\cal{A}  = \cal{A} $  $\cup  $ $ \{ \underline{m} \}$
  \State Add  $\underline{m}$ to $\cal{B}$ if local error below $\eta$
  \State $\cal{O} = \cal{O}$ $ \setminus$ $ \{ \underline{m} \}$
  \State Break
  \EndIf
  \EndIf
  \EndFor
  \If{$\underline{l} \in \cal{B}$}
  \State $\cal{B} = \cal{B} $ $\setminus $ $ \{ \underline{l} \}$
  \EndIf
  \EndWhile
\end{algorithmic}
\end{algorithm}


\newpage
\section{C++ API}
The construction of the sparse grid, including the boundary points is carried out by the following constructor
\begin{lstlisting}[style=CStyle]
  SparseSpaceGridBound(const Eigen::ArrayXd   &p_lowValues, const Eigen::ArrayXd &p_sizeDomain, const int &p_levelMax,  const Eigen::ArrayXd &p_weight,
		       const size_t &p_degree) 
\end{lstlisting}
with
\begin{itemize}
\item \code{p\_lowValues} corresponds to the bottom of the grid,
\item \code{p\_sizeDomain} corresponds to the size of the resolution domain in each dimension,
\item \code{p\_levelMax} is the level of the sparse grids, the $n$ in the equation \ref{anisotropicSparse},
\item \code{p\_weight} the weight of anisotropic sparse grids, the equation $w$ \ref{anisotropicSparse},
\item \code{p\_degree} is  equal to 1 (linear interpolator), or 2 (quadratic interpolator) or 3 (for cubic interpolator),
\end{itemize}
With the same notations the construction eliminating boundary points is carried out by the following constructor
 \begin{lstlisting}[style=CStyle]
  SparseSpaceGridNoBound(const Eigen::ArrayXd   &p_lowValues, const Eigen::ArrayXd &p_sizeDomain, const int &p_levelMax,  const Eigen::ArrayXd &p_weight,
		       const size_t &p_degree) 
 \end{lstlisting}
 The data structure of type \code{SparseSet} to store the sparse grid is defined by a map with keys an array A storing a multiple level and values a map with keys an array B storing the multi index associated with a point (A,B) and values the number of points (A,B):
\begin{lstlisting}[style=CStyle] 
  #define     SparseSet std::map<  Eigen::Array<char,Eigen::Dynamic,1 > , std::map<   Eigen::Array<unsigned int,Eigen::Dynamic,1> , size_t, OrderTinyVector< unsigned int >  > ,OrderTinyVector< char>  >
\end{lstlisting}
It is sometimes convenient to retrieve this data structure from the \code{SparseGrid} object: this is done by the following method:
\begin{lstlisting}[style=CStyle] 
  std::shared_ptr<SparseSet> getDataSet() const ;
\end{lstlisting}
The two preceding classes have two specific member functions for hierarchizing (see the section above) the known value function at the points of the grid for the entire grid.
\begin{itemize}
\item the first work on a single function:
\begin{lstlisting}[style=CStyle]
    /// \brief Hierarchize a function defined on the grid
    /// \param p_toHierarchize function to hierarchize
    void toHierarchize( Eigen::ArrayXd & p_toHierarchize );
\end{lstlisting}
\item the second work on a matrix, allowing to hierarchize several functions in a single call (each row corresponds to a function representation)
\begin{lstlisting}[style=CStyle]

   /// \brief Hierarchize a set of functions defined on the grid
    /// \param p_toHierarchize   function to hierarchize
    void toHierarchizeVec( Eigen::ArrayXXd & p_toHierarchize )
\end{lstlisting}
\end{itemize}
The two classes have two specific member functions to hierarchize point by point a value function at given points in the sparse grid:
\begin{itemize}
\item the first work on a single function:
\begin{lstlisting}[style=CStyle]
    /// \brief Hierarchize certain points defined on sparse grids
    ///        Hierarchization is carried out point by point
    /// \param p_nodalValues         function to hierarchize
    /// \param p_sparsePoints        vector of sparse points to hierarchize (all points must belong to the structure of the dataset)
    /// \param p_hierarchized        array of all hierarchical values (it is updated)
    virtual  void toHierarchizePByP(const Eigen::ArrayXd &p_nodalValues, const  std::vector<SparsePoint>  &p_sparsePoints, Eigen::ArrayXd &p_hierarchized) const 
 
\end{lstlisting}
\item the second work on a matrix, allowing to hierarchize several functions in a single call (each row corresponds to a function representation)
\begin{lstlisting}[style=CStyle]
    /// \brief Hierarchize certain points defined on the sparse grids for a set of functions
    ///        The hierarchy is carried out point by point
    /// \param p_nodalValues         functions to hierarchize (the row corresponds to the function number)
    /// \param p_sparsePoints        vector of sparse points to hierarchize (all points must belong to the structure of the dataset)
    /// \param p_hierarchized        array of all hierarchized values (it is updated)
    virtual void toHierarchizePByPVec(const Eigen::ArrayXXd &p_nodalValues, const  std::vector<SparsePoint>  &p_sparsePoints, Eigen::ArrayXXd &p_hierarchized) const 
\end{lstlisting}
\end{itemize}
The \code{SparsePoint} object is only a "typedef'':
\begin{lstlisting}[style=CStyle]
 #define SparsePoint std::pair< Eigen::Array<char, Eigen::Dynamic, 1> , Eigen::Array<unsigned int, Eigen::Dynamic, 1> >
\end{lstlisting}
where the first array allows to store the multi-level associated with the point and the second the associated multi-index .\\
It is finally possible to hierarchize all the points associated with a multi level. As before, two methods are available:
\begin{itemize}
  \item a first makes it possible to hierarchize all the points associated with a given level. The hierarchical values are updated with these new values.
    \begin{lstlisting}[style=CStyle]
     /// \brief Hierarchize all points defined at a given level of the sparse grids
    ///        Hierarchization is carried out point by point
    /// \param p_nodalValues         function to hierarchize
    /// \param p_iterLevel           	iterator on the level of the point to hierarchize
    /// \param p_hierarchized        array of all hierarchized values (it is updated)
     virtual  void toHierarchizePByPLevel(const Eigen::ArrayXd &p_nodalValues, const  SparseSet::const_iterator &p_iterLevel, Eigen::ArrayXd &p_hierarchized) const 
\end{lstlisting}
\item the second permits to hierarchize different functions together
 \begin{lstlisting}[style=CStyle]
    /// \brief Hierarchize all points defined on a given level of the sparse grids for a set of functions
    ///        Hierarchization is performed point by point
    /// \param p_nodalValues         function to hierarchize (the row corresponds to the function number)
    /// \param p_iterLevel           iterator on the level of the point to hierarchize
    /// \param p_hierarchized        array of all hierarchized values (it is updated)
    virtual void toHierarchizePByPLevelVec(const Eigen::ArrayXXd &p_nodalValues, const  SparseSet::const_iterator &p_iterLevel, Eigen::ArrayXXd &p_hierarchized) const 
 
\end{lstlisting}
\end{itemize}

 In the following example, sparse grids with boundary points is constructed. The values of a function $f$ at each coordinates are stored in an array \code{valuesFunction}, storing the functions $2$ to be interpolated.
 The $2$ global functions are hierarchized (see the section above) in the array \code{hierarValues}, and then the interpolation can be performed using these hierarchized values.
\begin{lstlisting}[style=CStyle]
    ArrayXd  lowValues = ArrayXd::Zero(5); // bottom of the grid
    ArrayXd  sizeDomain = ArrayXd::Constant(5,1.); // size of the grid
    ArrayXd  weight  = ArrayXd::Constant(5,1.); // weights
    int degree =1 ; // linear interpolator
    bool bPrepInterp = true; // precalculate neighbors of nodes
    level = 4 ; // level of the sparse grid

    // sparse grid generation
    SparseSpaceGridBound sparseGrid(lowValues, sizeDomain, level, weight, degree, bPrepInterp);

    //  grid iterators
    shared_ptr<GridIterator > iterGrid = sparseGrid.getGridIterator();
    ArrayXXd valuesFunction(1,sparseGrid.getNbPoints());
    while (iterGrid->isValid())
    {
        ArrayXd pointCoord = iterGrid->getCoordinate();
        valuesFunction(0,iterGrid->getCount()) = f(pointCoord) ;
        valuesFunction(1,iterGrid->getCount()) = f(pointCoord)+1 ;
        iterGrid->next();
    }

    // Hierarchize
    ArrayXXd hieraValues =valuesFunction;
    sparseGrid.toHierarchizeVec(hieraValues);

    // interpolate
     ArrayXd pointCoord = ArrayXd::Constant(5,0.66);
     shared_ptr<Interpolator > interpolator = sparseGrid.createInterpolator(pointCoord);
     ArrayXd  interVal  = interpolator->applyVec(hieraValues);
\end{lstlisting}
\begin{Remark}
  The Point-by-point hierarchization on the global grid could have been calculated as below
 \begin{lstlisting}[style=CStyle]
    std::vector<SparsePoint> sparsePoints(sparseGrid.getNbPoints());
    std::shared_ptr<SparseSet> dataSet =  sparseGrid.getDataSet();
    // iterate on points
    for (typename SparseSet::const_iterator iterLevel = dataSet->begin(); iterLevel != dataSet->end(); ++iterLevel)
        for (typename SparseLevel::const_iterator iterPosition = iterLevel->second.begin(); iterPosition != iterLevel->second.end(); ++iterPosition)
        {
            sparsePoints[iterPosition->second] = make_pair(iterLevel->first, iterPosition->first);
        }
        ArrayXXd hieraValues = sparseGrid.toHierarchizePByPVec(valuesFunction, sparsePoints);
 \end{lstlisting}
       
 \end{Remark}
In some cases, it is more convenient to build  an interpolator acting on a global function. This is the case when you have only one function
and you want to interpolate at several points for this function.
In this specific case an interpolator deriving from the class \code{InterpolatorSpectral} (similarly to  Legendre grid interpolators) can be constructed:
\begin{lstlisting}[style=CStyle]
    /** \brief Constructor taking in values on the grid
     *  \param p_grid      is the sparse  grid used to interpolate
     *  \param p_values    Function values on the sparse grid
     */
  SparseInterpolatorSpectral(const shared_ptr< SparseSpaceGrid>  &p_grid , const Eigen::ArrayXd &p_values)
\end{lstlisting}
This class has a member to interpolate at a given point:
\begin{lstlisting}[style=CStyle]
    /**  \brief  interpolate
     *  \param  p_point  coordinates of the point for interpolation
     *  \return interpolated value
     */
    inline double apply(const Eigen::ArrayXd &p_point) const
\end{lstlisting}
See the \ref{legendregridsection} section for an example (similar but with Legendre grids)  to use this object.\\
Sometimes, we want to iterate on points on a given level. In the example below , for each level an iterator over all points belonging to a given level is retrieved and the values of a function $f$ at each point are calculated and stored.
\begin{lstlisting}[style=CStyle]
  // sparse grid generation
    SparseSpaceGridNoBound sparseGrid(lowValues, sizeDomain, p_level, p_weight, p_degree, bPrepInterp);

    //  test iterator on each level
    ArrayXd valuesFunctionTest(sparseGrid.getNbPoints());
    std::shared_ptr<SparseSet> dataSet =  sparseGrid.getDataSet();
     for (SparseSet::const_iterator iterLevel = dataSet->begin(); iterLevel != dataSet->end(); ++iterLevel)
      {
    	// get back iterator on this level
	shared_ptr<SparseGridIterator> iterGridLevel = sparseGrid.getLevelGridIterator(iterLevel);
	while(iterGridLevel->isValid())
	  {
	    Eigen::ArrayXd pointCoord = iterGridLevel->getCoordinate();
 	    valuesFunctionTest(iterGridLevel->getCount()) = f(pointCoord);
	    iterGridLevel->next();
	  }
      }
\end{lstlisting}

Finally, adaptation can be realized with two member functions:
\begin{itemize}
\item A first one permits to refine adding points where the error is important. Note that a function is provided to calculate from hierarchical values the error at each level of the sparse grid and that a second one is provided to get a global error from the error calculated at each level.
  This makes it possible to specialize the refining depending, for example, whether the calculation is achieved for integration or interpolation purpose.
  
\begin{lstlisting}[style=CStyle]
    /// \brief Dimension adaptation nest
    /// \param p_precision       precision required for adaptation
    /// \param p_fInterpol      function to interpolate
    /// \param p_phi            function for the error on a given level in the m_dataSet structure
    /// \param p_phiMult         from an error defined at different levels, return a global error at the different levels
    /// \param p_valuesFunction  an array storing the nodal values
    /// \param  p_hierarValues  an array storing hierarchized values (updated)
    void refine(const double &p_precision, const std::function<double(const Eigen::ArrayXd &p_x)> &p_fInterpol,
                const std::function< double(const SparseSet::const_iterator &, const Eigen::ArrayXd &)> &p_phi,
                const std::function< double(const std::vector< double> &) > &p_phiMult,
                Eigen::ArrayXd &p_valuesFunction,
                Eigen::ArrayXd &p_hierarValues); 
\end{lstlisting}
with
\begin{itemize}
\item \code{p\_precision} the $\eta$ tolerance in the algorithm,
\item \code{p\_fInterpol} the function permitting to calculate the nodal values,
\item \code{p\_phi} function permitting to calculate $e_{\underline l}$ the local error for a given $\underline l$,
\item \code{p\_phiMult} a function taking as argument all the $e_{\underline l}$ (local errors) and giving back the global error $E$,
\item \code{p\_valuesFunction} an array storing the nodal values (updated during refinement)
\item \code{p\_hierarValues} an array storing the hierarchized values  (updated during refinement)
\end{itemize}
\item A second one enlarges the mesh, eliminating the point where the error is too small
\begin{lstlisting}[style=CStyle]
   /// \brief Dimension adaptation coarsening: modify the structure of the data by trying to delete al thel levels with local error
    ///        below a local precision
    /// \param p_precision      Precision under which coarsening will be realized
    /// \param p_phi            function for the error on a given level in the m_dataSet structure
    /// \param p_valuesFunction  an array storing the nodal values (modified on the new structure)
    /// \param p_hierarValues   Hierarchical values on a data structure (modified on the new structure)
    void coarsen(const double &p_precision, const std::function< double(const SparseSet::const_iterator &, const Eigen::ArrayXd &)> &p_phi,
                 Eigen::ArrayXd &p_valuesFunction,
                 Eigen::ArrayXd   &p_hierarValues);
\end{lstlisting}
with arguments similar to the previous function.
  
  \end{itemize}
                     
\section{Python API}
Here is an example of the python API used for interpolation with Sparse grids with boundary points and without boundary points.
Adaptation and coarsening is available with an error calculated for interpolation only.
\lstinputlisting[style=PStyle]{../StOpt/test/python/unit/grids/testSparseGrids.py}


\chapter{Introducing regression resolution}
\label{sec::regression}
Suppose the the stochastic differential equation in the optimization problem is not controlled:
$$ d X^{x,t} = b(t,X^{x,t}_s) ds + \sigma_(s,X^{x,t}_s) dW_s $$
This  case is for example encountered during the valuation of American options in finance, when an arbitration is carried out between the pay-off and the expected future gain if it is not exercised right now.
In order to estimate this conditional  expectation (according of Markov state), first suppose that a set of $N$ Monte Carlo Simulation is available at dates $t_i$ for a process $X_t := X^{0,x}_t$ where $x$ is the initial state at date $t=0$ and that we want to estimate $ f(x) :=   \E[  g(t+h,X_{t+h})~|~ X_t =x]$ for a given $x$ and a given function $g$.   This function $f$ is located in the infinite dimensional space of the functions $L_2$.
In order to approximate it, we try to find it in a finite dimensional space.
By choosing a set of basis functions $\psi_k$ for $k=1$ to $M$, the conditional expectation can be approximated by
\begin{equation}
f(x) \simeq \sum_{k=1}^M   \alpha_k \psi_k(X_t)
\label{regressed}
\end{equation}
where  $(\hat \alpha^{t_i,N}_k)_{k\le M}$ minimizes 
\begin{equation}
\sum_{\ell=1}^N \left| g(X_{t+h}^l)- \sum_{k=1}^M   \alpha_k \psi_k(X_t^l) \right|^2
\end{equation}
over $(\alpha_k)_{k\le M} \in \R^M$.
We have to solve a quadratic optimization problem of the form
\begin{equation}\label{reg}
 \min_{\alpha \in \R^M} \| A \alpha - B \|^2
\end{equation} 
Classically the previous equation is reduced to the normal equation 
\begin{equation}
\label{eq: normal eq}
 A'A \alpha = A' B\;,
 \end{equation}
which is solved by a Cholesky-type approach when the matrix $A'A$ is defined otherwise the solution with the standard $L_2$ minimum can be calculated using the pseudo-inverse of $A'A$.\\
When the different components of $X^{x,t}$ are strongly correlated it can be convenient to rotate the dataset on its main components using the PCA method.
Rotating the dataset before performing a regression has been recommended in \cite{wand1994fast} and \cite{scott2015multivariate} for example.
 The right-hand side of Figure \ref{fig:evaluation grid}
illustrates the new evaluation grid obtained on the same dataset.
We can observe better coverage and fewer empty areas when using local regression that we will detail in this section.
\begin{figure}[h]
\begin{centering}
\includegraphics[width=0.7\paperwidth]{rotation}
\par\end{centering}
\caption{Evaluation grid: rotation\label{fig:evaluation grid}}
\end{figure}

\section{C++ global API}
All regression classes are derived from the \code{BaseRegression}  abstract class, which stores a pointer to the ``particles'' (a matrix storing the simulations of $X^{x,t}$: the first dimension of the matrix corresponds to the dimension of $X^{x,t}$, and the second dimension corresponds to the number of particle), and stores if the current date $t$ is  $0$ (then the conditional expectation is only an expectation).
\lstinputlisting[style=CStyle]{../StOpt/StOpt/regression/BaseRegression.h}
All regression classes share the same constructors:
\begin{itemize}
  \item a first constructor stores the members of the class and calculates the matrices for the regression: it is used for example to build a regression object at each time step of a resolution method,
  \item the second constructor is used to prepare data which will be shared by all future regressions. It must be used with the \code{updateSimulation} method to update the actual matrix construction. In a resolution method with many time steps, the object will be constructed only once and at each time step, the Markov state will be updated by the method \code{updateSimulation}.
\end{itemize}
All regression classes share the common methods:
\begin{itemize}
\item \code{updateSimulationBase} (see above),
\item  \code{getCoordBasisFunction} takes the values $g(t+h,X_{t+h})$ for all simulations and returns the coefficients $\alpha_k$ of the basis functions,
\item  \code{getCoordBasisFunctionMultiple} is used if we want to do the previous calculation on several $g$ functions in a single call. In the matrix given as an argument, the first dimension has a size equal to the number of  Monte Carlo simulations, while the second dimension has a size equal to the number of functions to regress. At output, the first dimension has a size equal to the number of functions to regress and the second equal to the number of basis functions.
\item \code{getAllSimulations}  takes the values $g(t+h,X_{t+h})$ for all simulations and returns the regressed values for all simulations $f(X_t)$  
\item \code{getAllSimulationMultiple} is used if we want to do the previous calculation on several $g$ functions in a single call. In the matrix given as an argument, the first dimension has a size equal to the number of  Monte Carlo simulations, while the second dimension has a size equal to the number of functions to regress. The regressed values are rendered in the same format.
\item \code{reconstruction} takes as input the coefficient  $\alpha_k$  of the basis functions and returns all  $f(X_t)$ for the stored simulations by applying the equation \reff{regressed}.
\item \code{reconstructionMultiple} is used if we want to do the previous calculation on several $g$ functions in a single call. As input the coefficients $\alpha_k$  of the basis functions are given
  (number of function to regress for the first dimension, number of basis functions for second dimension). Consequently, the $f(X_t)$ for all the simulations and all the functions $f$ are returned (number of Monte Carlo simulations in the first dimension, number of functions to regress in the second dimension).
  \item \code{reconstructionASim}  takes a number of simulations $isim$ (optimization part) and  $\alpha_k$ coefficient of the basis functions as input and returns  $f(X_t^{isim})$ by applying the equation \reff{regressed},
\item \code{getValue} takes as its first argument samples of $X_t$, the basis function $\alpha_k$ and reconstructs the regressed solution of the equation \reff{regressed}.
\item \code{getValues} takes as its first argument samples of $X_t$ (dimension of uncertainty by number of samples), the basis function $\alpha_k$ and reconstructs the regressed solution of the equation \reff{regressed} (an array).
\end{itemize}
\section{Adapted local polynomial basis with same probability}
\label{subsec::local}
The  description of the method and its properties can be found in \cite{bouchard2012monte}. We simply recall the methodology.
These adapted local methods can benefit from a rotation in its main axis through the PCA method. Rotation is activated by a flag in the objects builder.
\subsection{Description of the method}
The method essentially consists in applying a non-conforming finite element approach rather than a spectral type method as presented above.

The idea is to use, at each time step $t_i$, a set of   functions $\psi_q, q \in [0,M_M]$ with local hyper cube  support  $D_{i_1,i_2,\dots,i_d}$ where $i_j= 1$ to $I_j$, $M_M= \prod_{k=1,d} I_k$, and $\{D_{i_1,\dots,i_d}\}_{(i_1,\dots,i_d)\in [1,I_1]\times\cdots\times [1,I_d]}$ is a partition of 
$[\min_{k=1,N} X_{t_i}^{1,(k)},$ $\max_{k=1,N} X_{t_i}^{1,(k)}] \times$ $\cdots$ $ \times [ \min_{k=1,N} X_{t_i}^{d,(k)},\max_{k=1,N} X_{t_i}^{d,(k)}]$.
On each $D_{l}$, $l=(i_1,\dots,i_d)$,  depending on the selected method, $\psi_l$ is
\begin{itemize}
\item either a constant function, so the global number of degrees of freedom is equal to $M_M$,
\item or a linear function  with $1+d$ degrees of freedom, so the global number of degrees of freedom is equal to $M_M*(1+d)$.
\end{itemize}

 This approximation is "non conform'' in the sense that we do not ensure the continuity of the approximation. However, it has the advantage of being able to adapt to any function, even discontinuous. 
In order to avoid oscillations and to allow classical regression by the Cholesky method, the supports are chosen so as to contain roughly the same number of particles. 

On the figure \ref{Mesh}, we have drawn an example of supports in the case of $6=4 \times 4$ local base cells, in the dimension  $2$.\\
\begin{figure}[h!]
\centerline{
\includegraphics[width=7cm]{fig_maill_regre.png}}
\caption{ Support of 2D function basis}
\label{Mesh}
\end{figure}
Sometimes we can further leverage knowledge about the value of continuation. In the case of an American basket option for example, we have a convexity of this
continuation value as a function of the underlying price.
It is possible to modify the previous algorithm to try to impose that the numerical method repeats this convexity. The algorithm
in \cite{magnani2009convex} has been optionally implemented. This algorithm may not converge when used in multi-dimensional but it allows
to improve the convexity of the solution by iterating  several times.
  
\subsection{C++ API}
\subsubsection{The constant per cell approximation}
\label{sec:ApiLocalConst}
The constructor of the local constant regression object is obtained by
\begin{lstlisting}[style=CStyle]
    LocalConstRegression(const Eigen::ArrayXi   &p_nbMesh,  bool  p_bRotationAndRecale = false);
\end{lstlisting}
where:
\begin{itemize}
\item \code{p\_nbMesh} is an array giving the number of meshes used in each direction ( $(4,4)$  for the figure \ref{Mesh} for example).
\item \code{p\_bRotationAndRecale} is an optional argument defined as \code{ false} by default which means that no data rotation in its axis of main components is performed. In the case of rotation, the directions are sorted with their decreasing singular values and the number of meshes in \code{p\_nbMesh} is defined for these sorted directions: \code{p\_nbMesh(0)} is associated with first direction with the highest singular value, \code{p\_nbMesh(1)} with the direction associated with the second highest singular value etc.
\end{itemize}
The second constructor allows to build the regression matrix, 
\begin{lstlisting}[style=CStyle]
    LocalConstRegression(const bool &p_bZeroDate,
        const shared_ptr< ArrayXXd>  &p_particles,
        const Eigen::ArrayXi   &p_nbMesh,
        bool  p_bRotationAndRecale = false)
\end{lstlisting}
where 
\begin{itemize}
\item \code{p\_bZeroDate} is \code{true} if the regression date is $0$,
\item \code{p\_particles} the particles $X_t$ for all simulations (dimension of $X_t$ for first dimension, number of Monte Carlo simulations in second dimension),
\item \code{p\_nbMesh} is an array giving the number of meshes used in each direction $(4,4)$  for the figure \ref{Mesh},
\item \code{p\_bRotationAndRecale} is an optional argument defined as \code{ false} by default which means that no data rotation in its axis of main components is performed. In the case of rotation, the directions are sorted with their decreasing singular values and the number of meshes in \code{p\_nbMesh} is defined for these sorted directions: \code{p\_nbMesh(0)} is associated with first direction with the highest singular value, \code{p\_nbMesh(1)} with the direction associated with the second highest singular value etc.
\end{itemize}
\subsubsection{Linear approximation per cell}
The constructor of the local linear regression object is obtained by
\begin{lstlisting}[style=CStyle]
    LocalLinearRegression(const Eigen::ArrayXi   &p_nbMesh,  bool  p_bRotationAndRecale = false);
\end{lstlisting}
where
\begin{itemize}
\item \code{p\_nbMesh} is an array giving the number of meshes used in each direction ( $(4,4)$  for the figure \ref{Mesh} for example),
\item \code{p\_bRotationAndRecale} is an optional argument defined as \code{ false} by default which means that no data is rotated in its  main components axis. In the case of rotation, the directions are sorted with their decreasing singular values and the number of meshes in \code{p\_nbMesh} is defined for these sorted directions: \code{p\_nbMesh(0)} is associated with the first direction with the highest singular value, \code{p\_nbMesh(1)} with the direction associated with the second highest singular value, etc. 
  \end{itemize}
The second constructor allows to build the regression matrix, 
\begin{lstlisting}[style=CStyle]
    LocalLinearRegression(const bool &p_bZeroDate,
        const shared_ptr< ArrayXXd>  &p_particles,
        const Eigen::ArrayXi   &p_nbMesh,
        bool  p_bRotationAndRecale = false)
\end{lstlisting}
where 
\begin{itemize}
\item \code{p\_bZeroDate} is \code{true} if the regression date is $0$,
\item \code{p\_particles} the particles $X_t$ for all simulations (dimension of $X_t$ for the first dimension, number of Monte Carlo simulations in the second dimension),
\item \code{p\_nbMesh} is an array giving the number of meshes used in each direction $(4,4)$  for the figure \ref{Mesh}
\item \code{p\_bRotationAndRecale} is an optional argument defined as \code{ false} by default which means that no data is rotated in its  main components axis. In the case of rotation, the directions are sorted with their decreasing singular values and the number of meshes in \code{p\_nbMesh} are defined for these sorted directions: \code{p\_nbMesh(0)} is associated with first direction with the highest singular value, \code{p\_nbMesh(1)} with the direction associated with the second highest singular value etc.
\end{itemize}
This class can benefit from the methodology in \cite{magnani2009convex} implementing a generalization of the member function \code{getAllSimulations}:
\begin{lstlisting}[style=CStyle]
  Eigen::ArrayXd getAllSimulationsConvex(const Eigen::ArrayXd &p_fToRegress, const int &p_nbIterMax)
\end{lstlisting}
where 
\begin{itemize}
\item \code{p\_fToRegress} is the set of points that we want to regress while preserving the convexity of the regressed function value
\item \code{p\_nbIterMax} is the maximum number of iterations of the method.
\end{itemize}
It returns the regressed values for all the simulations of the uncertainties.
\subsubsection{An example in the linear case}

Below, we give a small example where \code{toRegress} corresponds to $g(t+h, X_{t+h})$ for all simulations and $x$ store $X_t$ for all simulations.
\begin{lstlisting}[style=CStyle]
   // create the mesh for a 2 dim problem, 4 meshes per direction
    ArrayXi  nbMesh = ArrayXi::Constant(2, 4);
    // t is not zero
    bool bZeroDate = 0;
    // constructor, no rotation of the data
    LocalLinearRegression localRegressor(nbMesh);
    // update particles values
    localRegressor.updateSimulations(bZeroDate, x);
    // regressed values
     ArrayXd  regressedValues = localRegressor.getAllSimulations(toRegress);
\end{lstlisting}
\subsection{Python API}
\label{sec:pythonRegAdapt}
Here is a similar example using the second constructor of the linear case
\begin{lstlisting}[style=PStyle]
        import StOptReg 
        nbSimul = 5000000;
        np.random.seed(000)
        x = np.random.uniform(-.,1.,size=(1,nbSimul));
        # real function
        toReal = (2+x[0,:]+(+x[0,:])*(1+x[0,:]))
        # function to regress
        toRegress = toReal + 4*np.random.normal(0.,nbSimul)
        # mesh
        nbMesh = np.array([6],dtype=np.int32)
        # Regressor without rotation of data
        regressor = StOptReg.LocalLinearRegression(False,x,nbMesh)
        y = regressor.getAllSimulations(toRegress).transpose()[0]
\end{lstlisting}
Of cours,e the constant per cell case in python is similar.
As in C++, the linear case allows us to try to regress while preserving the convexity using the $getAllSimulationsConvex$ method.

\section{Adapted local basis by K-Means clustering methods}
This method can be interesting when a small number of particles is available to calculate the regressions and
we propose a K-Means clustering method to cluster simulations together. \\
The classical K-Means clustering method is as follows:
N points $X^k$ with $k=1$ to $N$ are given. A  partition of the domain $S=(S_m)_{m \le p}$ with $p \le N$ domains is obtained by minimizing
\begin{flalign*}
\argmin_{S} \sum_{k=1}^p  \sum_{X^{j} \in S_k} ||X^{j} - \mu_k ||^2 ,
\end{flalign*}
where $\mu_k$ is the barycenter of all points $X^{j} \in S_k$.\\
The classic Lloyd algorithm is used to calculated the cluster:
\begin{algorithm}[H]
  \caption{Lloyd algorithm}
  \label{LloydAlgo}
  \begin{algorithmic}[1]
    \State Choose $p$  points as initialization for $\mu_k^1$,  $k=1, p$
    \While{Not converged}
    \State affect each particle to its Voronoi cell:
    \begin{flalign*}
      S^{l}_k= \{ X^i : || X^i - \mu^l_k|| \le || X^i - \mu^l_m||, m =1, p \}
    \end{flalign*}
    \State Update
    \begin{flalign*}
      \mu^{l+1}_k = \frac{1}{|S_k^l|} \sum_{X^i \in S_k^l} X^i
      \end{flalign*}
    \EndWhile
\end{algorithmic}
\end{algorithm}
This algorithm is effective in 1D by sorting the coordinates of the particles. Its extension in the general case is costly due the calculation of the Voronoi cells and the distance between all points.\\
We suppose that, as in the adaptive case with same probability, we want to have a partition such that the number of meshes in each direction is $I_k$ for $k=1,d$.\\
We propose a recursive algorithm to calculate the meshes.
This algorithm is given by \ref{algo:LloydAlgo1DR} and \ref{algo:LloydAlgoModified},
\begin{algorithm}[H]
  \caption{Recursive 1D Lloyd algorithm}
  \label{algo:LloydAlgo1DR}
  \begin{algorithmic}[1]
    \Procedure{RecurKMeans}{$id$,$X_{i_1,\dots,i_{id-1}}$, $S_{i_1,\dots,i_{id-1}}$}
    \State  Sort the particle in dimension  $id$ and use Lloyd algorithm to partition $S_{i_1,\dots,i_{id-1}}$ in the dimension $id$ and get
    $S^{i_1,\dots,i_{id}}$ , $i_{id} =1 , I_{id}$.
    \For{$i_{id}=1, I_{id}$}
    \State $X_{i_1,\dots,i_{id}} = \{ X \in X_{i_1,\dots,i_{id-1}} / X \in S_{i_1,\dots,i_{id}} \}$
    \If{ $id < d$}
    \State RecurKMeans( $id+1$, $X_{i_1,\dots,i_{id}}$, $ S_{i_1,\dots,i_{id}}$)
    \EndIf
    \EndFor
    \EndProcedure
\end{algorithmic}
\end{algorithm}
\begin{algorithm}[H]
  \caption{Modified Lloyd algorithm}
  \label{algo:LloydAlgoModified}  
  \begin{algorithmic}[1]
    \State  $S= \R^d$, $X = \{ X^i / i =1,N\}$
    \State  RecurKMeans($1,X,S$)
\end{algorithmic}
\end{algorithm}
and an example of a resulting partition is given on figure \ref{fig:2DModifCluster} in 2D for $I_1=3, I_2=4$.
\begin{figure}[H]
\begin{centering}
\includegraphics[width=0.3\paperwidth]{ModifiedLloyd.png}
\par\end{centering}
\caption{Possible 2D partition due to modified K-Means algorithm \label{fig:2DModifCluster}}
\end{figure}
Once the partition has been performed, a regression is performed with a constant representation per mesh: \\
We note $(S^{i}_k)_{k=1,p}$ , a partition with the above method at the date $t_i$ using Monte Carlo particles $X_{t_i}^{(k)}$, $k=1, N$.
To calculate the conditional expectation of a function $g$ of $X_{t_{i+1}}$,
we use the constant representation by mesh and we then have:
\begin{flalign*}
  \E[ g(X_{t_{i+1}}) / X_{t_i}= X_{t_i}^{k}] \simeq
  \frac{1}{ |S^{i}_p|} \sum_{j / X_{t_i}^{j} \in S^{i}_p} g(X_{t_{i+1}}^j)
\end{flalign*}
where $X_{t_{i+1}}^k \in  |S^{i}_p|$.
\subsection{C++ API}
The constructor of the local K-Means  regression object is similar to that of the LocalConstRegression object inthe \ref{sec:ApiLocalConst} section. We do not then recall the signification of all the arguments. \\
A first constructor is:
\begin{lstlisting}[style=CStyle]
    LocalKMeansRegression(const Eigen::ArrayXi   &p_nbMesh,  bool  p_bRotationAndRecale = false);
\end{lstlisting}
and the second constructor permits the build the regression matrix, 
\begin{lstlisting}[style=CStyle]
    LocalKMeansRegression(const bool &p_bZeroDate,
        const shared_ptr< ArrayXXd>  &p_particles,
        const Eigen::ArrayXi   &p_nbMesh,
        bool  p_bRotationAndRecale = false)
\end{lstlisting}
\subsection{Python api}
Since the C++ API is the same as that of the \code{LocalConstRegression} object, we have the same python binding  as in the \ref{sec:pythonRegAdapt} section.

\section{Local polynomial basis with meshes of same size}
\label{subsec::localSameSize}
In certain cases, instead of using adapted meshes, one can prefer to fix the mesh with a constant step in each direction with $I_k$ meshes in each direction so that
the total number of cells is $M_M= \prod_{k=1,d} I_k$.
On each cell as in section \ref{subsec::local}, one can have two approximations:
\begin{itemize}
\item either a linear per mesh  representation, so the global number of degrees of freedom is equal to $M_M$,
\item or a linear function  with $1+d$ degrees of freedom,  so the global number of degrees of freedom is equal to $M_M*(1+d)$.
\end{itemize}
Because we define in each direction, the domain for the local basis, we do not use any data rotation.
\subsection{C++ API}
\subsubsection{The constant per cell approximation}
The constructor of the local constant regression object is achieved by
\begin{lstlisting}[style=CStyle]
    LocalSameSizeConstRegression(const Eigen::ArrayXd &p_lowValues, const Eigen::ArrayXd &p_step, const  Eigen::ArrayXi &p_nbStep);
\end{lstlisting}
\begin{itemize}
\item \code{p\_lowValues} is an array giving the first point of the grid in each direction,
\item \code{p\_step} is an array giving the size of the meshes in each direction,
\item \code{p\_nbStep} is an array giving the number of meshes used in each direction.
\end{itemize}
The second constructor allows to build the regression matrix, 
\begin{lstlisting}[style=CStyle]
    LocalSameSizeConstRegression(const bool &p_bZeroDate,
                                 const std::shared_ptr< Eigen::ArrayXXd > &p_particles,
                                 const Eigen::ArrayXd &p_lowValues,
                                 const Eigen::ArrayXd &p_step,
                                 const  Eigen::ArrayXi &p_nbStep);
\end{lstlisting}
where 
\begin{itemize}
\item \code{p\_bZeroDate} is \code{true} if the regression date is $0$,
\item \code{p\_particles} the particles $X_t$ for all simulations (dimension of $X_t$ for first dimension, number of Monte Carlo simulations in second dimension),
\item \code{p\_lowValues} is an array giving the first point of the grid in each direction,
\item \code{p\_step} is an array giving the size of the meshes in each direction,
\item \code{p\_nbStep} is an array giving the number of meshes used in each direction.
\end{itemize}
\subsubsection{The linear per cell approximation}
The constructor of the local linear regression object is achieved by
\begin{lstlisting}[style=CStyle]
     LocalSameSizeLinearRegression(const Eigen::ArrayXd &p_lowValues, const Eigen::ArrayXd &p_step, const  Eigen::ArrayXi &p_nbStep);
\end{lstlisting}
where 
\begin{itemize}
\item \code{p\_lowValues} is an array giving the first point of the grid in each direction,
\item \code{p\_step} is an array giving the size of the meshes in each direction,
\item \code{p\_nbStep} is an array giving the number of meshes used in each direction.
\end{itemize}
The second constructor allows to build the regression matrix, 
\begin{lstlisting}[style=CStyle]
        LocalSameSizeLinearRegression(const bool &p_bZeroDate,
                                  const std::shared_ptr< Eigen::ArrayXXd > &p_particles,
                                  const Eigen::ArrayXd &p_lowValues,
                                  const Eigen::ArrayXd &p_step,
                                  const  Eigen::ArrayXi &p_nbStep)
\end{lstlisting}
where 
\begin{itemize}
\item \code{p\_bZeroDate} is \code{true} if the regression date is $0$,
\item \code{p\_particles} the particles $X_t$ for all simulations (dimension of $X_t$ for first dimension, number of Monte Carlo simulations in second dimension),
\item \code{p\_lowValues} is an array giving the first point of the grid in each direction,
\item \code{p\_step} is an array giving the size of the meshes in each direction,
\item \code{p\_nbStep} is an array giving the number of meshes used in each direction.
\end{itemize}
\subsection{An example in the linear case}

Below we give a small example where \code{toRegress} is the array to regress as a function of x an array ``x'' in dimension \code{p\_nDim}:
\begin{lstlisting}[style=CStyle]
     // create a random  ``x'' array
     shared_ptr<ArrayXXd> x(new ArrayXXd(ArrayXXd::Random(p_nDim, p_nbSimul)));
    // create the mesh by getting min and max value on the samples
    double xMin = x->minCoeff() - tiny;
    double xMax = x->maxCoeff() + tiny;
    ArrayXd  lowValues = ArrayXd::Constant(p_nDim, xMin);
    ArrayXd  step = ArrayXd::Constant(p_nDim, (xMax - xMin) / p_nMesh);
    ArrayXi  nbStep = ArrayXi::Constant(p_nDim, p_nMesh);
    // constructor
    LocalLinearRegression localRegressor(lowValues,step,  nbStep);
    // update particles values
    localRegressor.updateSimulations(bZeroDate, x);
    // regressed values
     ArrayXd  regressedValues = localRegressor.getAllSimulations(toRegress);
\end{lstlisting}
\subsection{Python API}
Here is a similar example using the second constructor of the linear case
\begin{lstlisting}[style=PStyle]
        import StOptReg 
        nbSimul = 5000000;
        np.random.seed(000)
        x = np.random.uniform(-.,1.,size=(1,nbSimul));
        # real function
        toReal = (2+x[0,:]+(+x[0,:])*(1+x[0,:]))
        # function to regress
        toRegress = toReal + 4*np.random.normal(0.,,nbSimul)
        # mesh
        nStep = 20
        lowValue =  np.array([-1.0001],dtype=np.float)
        step =  np.array([2.0002/nStep],dtype=np.float)
        nbMesh = np.array([nStep],dtype=np.int32)
        # Regressor
        regressor = StOptReg.LocalSameSizeLinearRegression(False,x,lowValue,step,nbMesh)
        y = regressor.getAllSimulations(toRegress).transpose()[0]
\end{lstlisting}
Of course, the constant per cell  in python is similar.


\section{Sparse grid regressor}
\label{sec:sparseGridReg}
In the case of a sparse regressor, the grid is  an object \href{run:../StOpt/StOpt/core/grids/SparseSpaceGridNoBound.h}{\code{SparseSpaceGridNoBound}} (extrapolation for the boundary conditions).
The basis functions are given by the section \ref{sec::Sparse} for a linear, quadratic or cubic function base. No data rotation is available.
\subsection{C++ API}
Two specific constructor are available:
\begin{itemize}
\item The first one to be used with the \code{updateSimulations} methods
\begin{lstlisting}[style=CStyle]
    SparseRegression(const int &p_levelMax, const Eigen::ArrayXd &p_weight, const int &p_degree, bool p_bNoRescale = false);
\end{lstlisting}
where
\begin{itemize}
\item \code{p\_levelMax} corresponds to $n$ in the equation \reff{classSparse},
\item \code{p\_weight} the weight of the sparse anisotropic grids (see equation \reff{anisotropicSparse},
\item \code{p\_degree}  is  equal to  (linear basis function ), or 2 (quadratic basis) or 3 (for cubic basis functions),
\item \code{p\_bNoRescale} if \code{true} no rescaling of the particles is used. Otherwise a new scaling of the mesh size is obtained (as for local basis functions, see section \ref{subsec::local})
\end{itemize}
\item The second take the same arguments as the first constructor but adds  a Boolean
to check if the regression date is $0$ and the particles $X_t$ (here the scaling is always performed):
\begin{lstlisting}[style=CStyle]
   SparseRegression(const bool &p_bZeroDate,
                     const shared_ptr< Eigen::ArrayXXd > &p_particles,
                     const int &p_levelMax, const Eigen::ArrayXd &p_weight,
                     const int &p_degree);
\end{lstlisting}
\end{itemize}
A simple example to express the regression of \code{toRegress}
\begin{lstlisting}[style=CStyle]
        // second member to regress
         ArrayXd toRegress(p_nbSimul);
        // for testing
        toRegress.setConstant(.);
        shared_ptr<ArrayXXd> x(new ArrayXXd(ArrayXXd::Random(p_nDim, p_nbSimul)));
        // constructor : the current date is not  zero
        bool bZeroDate = 0;
        // constructor
        SparseRegression sparseRegressor(p_level , weight, p_degree);
        sparseRegressor.updateSimulations(bZeroDate, x); // update the state
         // then just calculate function basis coefficient
        ArrayXd regressedFuntionCoeff = sparseRegressor.getCoordBasisFunction(toRegress);
        // use the getValue method to get back the regressed values
        for (int is = 0; is < p_nbSimul; ++is)
        {
            Map<ArrayXd> xloc(x->col(is).data(), p_nDim);
            double reg = sparseRegressor.getValue(xloc, regressedFuntionCoeff);
        }
        // get back all values once for all
        ArrayXd regressedAllValues  = localRegressor.getValues(*x,regressedFuntionCoeff) ;
         
\end{lstlisting}
\subsection{Python API}
Here is a simple example of the python API:
\begin{lstlisting}[style=PStyle]
        import StOptReg
        nbSimul = 2000000;
        np.random.seed(000)
        x = np.random.uniform(-.,1.,size=(1,nbSimul));
        # real function
        toReal = (2+x[0,:]+(+x[0,:])*(1+x[0,:]))
        # function to regress
        toRegress = toReal + 4*np.random.normal(0.,,nbSimul)
        # level for sparse grid
        iLevel = 5;
        # weight for anisotropic sparse grids
        weight= np.array([],dtype=np.int32)
        # Regressor degree 
        regressor = StOptReg.SparseRegression(False,x,iLevel, weight, )
        y = regressor.getAllSimulations(toRegress)
         # get back basis function
        regressedFuntionCoeff= regressor.getCoordBasisFunction(toRegress)
        # get back all values
        ySecond= regressor.getValues(x,regressedFuntionCoeff)
\end{lstlisting}
\section{Global polynomial basis}
\label{sec:globPol}
\subsection{Description of the method}
In this section, the $\psi_k(X_t)$ involved  in equation \ref{regressed} are given polynomials.
The available polynomials are the canonical polynominals, those of Hermite and Chebyshev.\\
\begin{itemize}
\item Hermite polynomials $H_m(x) = (-1)^n e^{\frac{x^2}{2}} \frac{d^n}{dx^n}  e^{-\frac{x^2}{2}} $ are orthogonal with respect to the weight $w(x) =  e^{-\frac{x^2}{2}}$  and we get
  $$ \int_{-\infty}^{+\infty} H_m(x) H_n(x) dx  =\delta_{mn} \sqrt{2 \pi} n!$$
  they satisfy the recurrence:
  $$ H_{n+1}(x)= x H_n(x) - H_n^{'}(x)$$
  assuming $H_n(x)= \sum_{k=0}^n a_{n,k} x^k$, we get the recurrence
  \begin{eqnarray}
    a_{n+1,k}= a_{n,k-1} - n a_{n-1,k}, k> 0 \\
    a_{n+1,0} = - n a_{n-1,0}
  \end{eqnarray}
\item Chebyshev polynomials are $T_{N+1}(x)= cos ((N+1) arcs(x))$. They are orthogonal to the weight $w(x) = \frac{1}{\sqrt{1-x^2}}$ and
  $$ \int_{-1}^{1}  T_{N}(x)T_{M}(x) w(x)  dx = \left \{ \begin{array}{l}
  0 , \mbox{ if } M  \ne N \\
  \pi,  \mbox{ if } M=N=0 \\
  \frac{\pi}{2}, \mbox{ if } M=N \ne 0
\end{array}
  \right.
  $$
  They satisfy the following recurrence:
  $$T_{N+2}(x) = 2x T_{N+1}(x) - T_N(x)$$
\end{itemize}
Optionally, data rotation is possible even if the advantage of rotation seems limited for global polynomials.

\subsection{C++ API}
The class \code{GlobalRegression} is templated by the type of the polynomial (\code{Canonical}, \code{Tchebychev} or \code{Hermite})
The first constructor:

\begin{lstlisting}[style=CStyle]
    GlobalRegression(const int & p_degree, const int & p_dim, bool  p_bRotationAndRecale = false);
\end{lstlisting}
where \code{p\_degree} is the total degree of the polynomial approximation, \code{p\_dim} is the dimension of the problem, \code{p\_bRotationAndRecale} is an optional flag set to \code{true} if  data rotation must be performed (by default, no rotation).
A second constructor is provided:
\begin{lstlisting}[style=CStyle]
   GlobalRegression(const bool &p_bZeroDate,
		     const std::shared_ptr< Eigen::ArrayXXd > &p_particles,
		     const int & p_degree, bool  p_bRotationAndRecale = false)
\end{lstlisting}
where 
\begin{itemize}
\item \code{p\_bZeroDate} is \code{true} if the regression date is $0$,
\item \code{p\_particles} the particles $X_t$ for all simulations (dimension of $X_t$ for first dimension, number of Monte Carlo simulations in second dimension),
\item \code{p\_degree} is the total degree of the polynomial approximation,
\item \code{p\_bRotationAndRecale} is an optional flag set to \code{true} if data rotation is to be performed (default, no rotation)
\end{itemize}
Below, we give a small example where \code{toRegress} corresponds to $g(t+h, X_{t+h})$ for all simulations and $x$ store $X_t$ for all simulations.
\begin{lstlisting}[style=CStyle]
   // total degree equal to 2
    int degree=2;
    // t is not zero
    bool bZeroDate = 0;
    // constructor with Hermite polynomials, no rotation
    GlobalRegression<Hermite> localRegressor(degree,x.rows());
    // update particles values
    localRegressor.updateSimulations(bZeroDate, x);
    // regressed values
     ArrayXd  regressedValues = localRegressor.getAllSimulations(toRegress);
\end{lstlisting}
In the example above, the Hermite regression can be replaced by the canonical regression:
\begin{lstlisting}[style=CStyle]
  GlobalRegression<Canonical> localRegressor(degree,x.rows());
\end{lstlisting}
or by a Chebyshev:
\begin{lstlisting}[style=CStyle]
  GlobalRegression<Tchebychev> localRegressor(degree,x.rows());
\end{lstlisting}
\subsection{Python API}
Here is a similar example using the second  constructor
\begin{lstlisting}[style=PStyle]
        import StOptReg 
        nbSimul = 5000000;
        np.random.seed(1000)
        x = np.random.uniform(-.,1.,size=(1,nbSimul));
        # real function
        toReal = (2+x[0,:]+(+x[0,:])*(1+x[0,:]))
        # function to regress
        toRegress = toReal + 4*np.random.normal(0.,,nbSimul)
        # degree
        degree =2
        # Regressor, no rotation
        regressor = StOptReg.GlobalHermiteRegression(False,x,degree)
        y = regressor.getAllSimulations(toRegress).transpose()[0]
\end{lstlisting}
  The available regressors are \code{GlobalHermiteRegression} as in the example above , \code{GlobalCanonicalRegression} and \code{GlobalTchebychevRegression} with obvious correspondence.
  \section{Kernel regression with Epanechnikov kernel}
\label{sec:kernelReg}  
Let $(x_{1},y_{1}),(x_{2},y_{2}),\ldots,(x_{N},y_{N})$ be a sample of
 $N$ input points $x_{i}$ and output points $y_{i}$ drawn from
a joint distribution $(X,Y)$. The kernel density estimator (aka Parzen--Rosenblatt
estimator) of the density of $X$ at the evaluation point $z$ is
given by:
\begin{equation}
\hat{f}_{\mathrm{KDE}}(z):=\frac{1}{N}\sum_{i=1}^{N}K_{h}(x_{i}-z)\label{eq:localdens}
\end{equation}

where $K_{h}(u):=\frac{1}{h}K\left(\frac{u}{h}\right)$ with kernel
$K$ and bandwidth $h$. The Nadaraya--Watson kernel regression estimator
of $\mathbb{E}\left[Y\left|X=z\right.\right]$ is given by:
\begin{equation}
\hat{f}_{\mathrm{NW}}(z):=\frac{\sum_{i=1}^{N}K_{h}(x_{i}-z)y_{i}}{\sum_{i=1}^{N}K_{h}(x_{i}-z)}\label{eq:localreg0}
\end{equation}

The estimator $\hat{f}_{\mathrm{NW}}(z)$ performs a kernel-weighted
local average of the response points $y_{i}$ that are such that their
corresponding inputs $x_{i}$ are close to the evaluation point $z$.
It can be described as a locally constant regression. More generally,
locally linear regressions can be performed:
\begin{equation}
\hat{f}_{\mathrm{L}}(z):=\min_{\alpha(z),\beta(z)}\sum_{i=1}^{N}K_{h}(x_{i}-z)\left[y_{i}-\alpha(z)-\beta(z)x_{i}\right]^{2}\label{eq:localreg1}
\end{equation}
The well known computational problem with the implementation of the
kernel smoothers \eqref{eq:localdens}-\eqref{eq:localreg0}-\eqref{eq:localreg1}
is that their direct evaluation on a set of $M$ evaluation points 
would require $\mathcal{O}(M\times N)$ operations. In particular,
when the evaluation points coincide with the input points $x_{1},x_{2},\ldots,x_{N}$,
a direct evaluation requires a quadratic $\mathcal{O}(N^{2})$ number
of operations.
StOpt implements the methodology described in \cite{langrene2017fast} to bring the computational cost down to $\mathcal{O}(N \log N)$.

\subsection{The univariate case}
In one dimension, StOpt uses the one-dimensional Epanechnikov kernel 
\begin{flalign*}
  K(u)=\frac{3}{4}(1-u^{2})\mathbbm{1}\{\left|u\right|\leq1\}
  \end{flalign*}
and the fast summation algorithm is used:
 Let $(x_{1},y_{1}),(x_{2},y_{2}),\ldots,(x_{N},y_{N})$
be a sample of $N$ input points (source) $x_{i}$ and output points
$y_{i}$, and let $z_{1},z_{2},\ldots,z_{M}$ be a set of $M$ evaluation 
(target) points. Without loss of generality, we assume that the input
points and evaluation points are sorted: $x_{1}\leq x_{2}\leq\ldots\leq x_{N}$
and $z_{1}\leq z_{2}\leq\ldots\leq z_{M}$. In order to compute the
kernel density estimator \eqref{eq:localdens}, kernel regression
\eqref{eq:localreg0} and locally linear regression \eqref{eq:localreg1}
for every evaluation point $z_{j}$, we need to compute sums of
the type
\begin{equation}
\mathbf{S}_{j}=\mathbf{S}_{j}^{p,q}:=\frac{1}{N}\sum_{i=1}^{N}K_{h}(x_{i}-z_{j})x_{i}^{p}y_{i}^{q}=\frac{1}{Nh}\sum_{i=1}^{N}K\left(\frac{x_{i}-z_{j}}{h}\right)x_{i}^{p}y_{i}^{q}\,,p=0,1,\,q=0,1\label{eq:sum_unidim}
\end{equation}
for each $j\in\{1,2,\ldots,M\}$. Direct and independent evaluation
of these sums would require $\mathcal{O}(N\times M)$ operations (a
sum of $N$ terms for each $j\in\{1,2,\ldots,M\}$). The idea of fast
sum updating consists in using the information in the sum $\mathbf{S}_{j}$
to calculate the next sum $\mathbf{S}_{j+1}$ without going through
all the $N$ input points again. Using the Epanechnikov
kernel (parabolic) $K(u)=\frac{3}{4}(1-u^{2})\mathbbm{1}\{\left|u\right|\leq1\}$ we get:
\begin{align}
 & \mathbf{S}_{j}^{p,q}=\frac{1}{Nh}\sum_{i=1}^{N}\frac{3}{4}\left(1-\left(\frac{x_{i}-z_{j}}{h}\right)^{2}\right)x_{i}^{p}y_{i}^{q}\mathbbm{1}\{z_{j}\!-\!h\leq x_{i}\leq z_{j}\!+\!h\}\nonumber \\
 & =\frac{1}{Nh}\frac{3}{4}\sum_{i=1}^{N}\left(1-\frac{z_{j}^{2}}{h^{2}}+2\frac{z_{j}}{h^{2}}x_{i}-\frac{1}{h^{2}}x_{i}^{2}\right)x_{i}^{p}y_{i}^{q}\mathbbm{1}\{z_{j}\!-\!h\leq x_{i}\leq z_{j}\!+\!h\}\nonumber \\
 & =\frac{3}{4Nh}\left\{ \!\left(\!1\!-\!\frac{z_{j}^{2}}{h^{2}}\!\right)\!\mathcal{S}^{p,q}([z_{j}\!-\!h,z_{j}\!+\!h])+2\frac{z_{j}}{h^{2}}\mathcal{S}^{p+1,q}([z_{j}\!-\!h,z_{j}\!+\!h])-\frac{1}{h^{2}}\mathcal{S}^{p+2,q}([z_{j}\!-\!h,z_{j}\!+\!h])\!\right\} \label{eq:parabolic-kernel-development}
\end{align}
where 
\begin{equation}
\mathcal{S}^{p,q}([L,R]):=\sum_{i=1}^{N}x_{i}^{p}y_{i}^{q}\mathbbm{1}\{L\leq x_{i}\leq R\}\label{eq:SpqLR}
\end{equation}
These sums $\mathcal{S}^{p,q}([z_{j}-h,z_{j}+h])$ can be evaluated
quickly from $j=1$ to $j=M$ as long as the input points $x_{i}$
and the evaluation points $z_{j}$ are sorted in ascending order.
Indeed,
\begin{align}
 & \mathcal{S}^{p,q}([z_{j+1}\!-\!h,z_{j+1}\!+\!h])=\sum_{i=1}^{N}x_{i}^{p}y_{i}^{q}\mathbbm{1}\{z_{j+1}\!-\!h\leq x_{i}\leq z_{j+1}\!+\!h\}\nonumber \\
 & =\sum_{i=1}^{N}x_{i}^{p}y_{i}^{q}\mathbbm{1}\{z_{j}\!-\!h\leq x_{i}\leq z_{j}\!+\!h\}\nonumber \\
 & -\sum_{i=1}^{N}x_{i}^{p}y_{i}^{q}\mathbbm{1}\{z_{j}\!-\!h\leq x_{i}<z_{j+1}\!-\!h\}+\sum_{i=1}^{N}x_{i}^{p}y_{i}^{q}\mathbbm{1}\{z_{j}\!+\!h<x_{i}\leq z_{j+1}\!+\!h\}\nonumber \\
 & =\mathcal{S}^{p,q}([z_{j}\!-\!h,z_{j}\!+\!h])-\mathcal{S}^{p,q}([z_{j}\!-\!h,z_{j+1}\!-\!h[)+\mathcal{S}^{p,q}(]z_{j}\!+\!h,z_{j+1}\!+\!h])\label{eq:1d_updating}
\end{align}
Therefore, we can simply update the sum $\mathcal{S}^{p,q}([z_{j}-h,z_{j+1}+h])$
for the evaluation point $z_{j}$ to obtain the next sum $\mathcal{S}^{p,q}([z_{j+1}-h,z_{j+1}+h])$
for the next evaluation point $z_{j+1}$ by subtracting the terms
$x_{i}^{p}y_{i}^{q}$ for which $x_{i}$ is between $z_{j}-h$ and
$z_{j+1}-h,$ and adding the terms $x_{i}^{p}y_{i}^{q}$ for which
$x_{i}$ is between $z_{j}+h$ and $z_{j+1}+h$. This can be achieved
in a fast $\mathcal{O}(M+N)$ operations by going through the input
points $x_{i}$, stored in increasing order at a cost of $\mathcal{O}(N\log N)$ operations,
and through the evaluation points $z_{j}$, stored in
increasing order at a cost of $\mathcal{O}(M\log M)$ operations.\\
\subsection{The multivariate case}
We now turn to the multivariate case. Let $d$ be the dimension of
the inputs. We consider again a sample $(x_{1},y_{1}),(x_{2},y_{2}),\ldots,(x_{N},y_{N})$
of $N$ input points $x_{i}$ and output points $y_{i}$, where the
input points are now multivariate:
\[
x_{i}=\left(x_{1,i},x_{2,i},\ldots,x_{d,i}\right)\,,\,i\in\{1,2,\ldots,N\}
\]
The StOpt library implements the additive Epanechnikov kernel in the multi-dimensional case (\cite{langrene2017fast}).
\begin{equation}
K_{d}\left(u_{1},\ldots,u_{d}\right)=\frac{1}{d2^{d-1}}\sum_{k=1}^{d}K(u_{k})\prod_{k_{0}=1}^{d}\mathbbm{1}\{\left|u_{k_{0}}\right|<1\}=\frac{3}{d2^{d+1}}\sum_{k=1}^{d}\left(1-u_{k}^{2}\right)\prod_{k_{0}=1}^{d}\mathbbm{1}\{\left|u_{k_{0}}\right|<1\}\label{eq:kernel_mean}
\end{equation}
We can show (\cite{langrene2017fast})
that calculating the multivariate version of the smoothing kernels
\eqref{eq:localdens}, \eqref{eq:localreg0} and \eqref{eq:localreg1}
boils down to the calculation of the following sums:
\begin{eqnarray}
\mathbf{S}_{j} & = & \mathbf{S}_{k_{1},k_{2},j}^{p_{1},p_{2},q}:=\frac{1}{N}\sum_{i=1}^{N}K_{d,h}(x_{i}-z_{j})x_{k_{1},i}^{p_{1}}x_{k_{2},i}^{p_{2}}y_{i}^{q}\nonumber \\
 & = & \frac{1}{N\Pi_{k=1}^{d}h_{k}}\sum_{i=1}^{N}K_{d}\left(\frac{x_{1,i}-z_{1,j}}{h_{1}},\frac{x_{2,i}-z_{2,j}}{h_{2}},\ldots,\frac{x_{d,i}-z_{d,j}}{h_{d}}\right)x_{k_{1},i}^{p_{1}}x_{k_{2},i}^{p_{2}}y_{i}^{q}\label{eq:sum_multidim}
\end{eqnarray}
for each evaluation point $z_{j}=(z_{1,j},z_{2,j},\ldots,z_{d,j})\in\mathbb{R}^{d}$,
$j\in\{1,2,\ldots,M\}$, for powers $p_{1},p_{2},q=0,1$ and for dimension
indices $k_{1},k_{2}=1,2,\ldots,d$.

\subsubsection{Kernel expansion}

Using the multivariate kernel \eqref{eq:kernel_mean}, we can expand
the sum \eqref{eq:sum_multidim} as follows:

\begin{align}
 & \mathbf{S}_{j}=\frac{1}{N\prod_{k=1}^{d}h_{k}}\sum_{i=1}^{N}K_{d}\left(\frac{x_{1,i}-z_{1,j}}{h_{1}},\frac{x_{2,i}-z_{2,j}}{h_{2}},\ldots,\frac{x_{d,i}-z_{d,j}}{h_{d}}\right)x_{k_{1},i}^{p_{1}}x_{k_{2},i}^{p_{2}}y_{i}^{q}\nonumber \\
 & =\frac{3}{d2^{d+1}N\prod_{k=1}^{d}h_{k}}\sum_{i=1}^{N}\sum_{k=1}^{d}\left(1-\frac{(x_{k,i}-z_{k,j})^{2}}{h_{k}^{2}}\right)x_{k_{1},i}^{p_{1}}x_{k_{2},i}^{p_{2}}y_{i}^{q}\prod_{k_{0}=1}^{d}\mathbbm{1}\{\left|x_{k_{0},i}-z_{k_{0},j}\right|\leq1\}\nonumber \\
 & =\frac{3}{d2^{d+1}N\prod_{k=1}^{d}h_{k}}\sum_{k=1}^{d}\sum_{i=1}^{N}\left(1-\frac{z_{k,j}^{2}}{h_{k}^{2}}+2\frac{z_{k,j}}{h_{k}^{2}}x_{k,i}-\frac{1}{h_{k}^{2}}x_{k,i}^{2}\right)x_{k_{1},i}^{p_{1}}x_{k_{2},i}^{p_{2}}y_{i}^{q}\prod_{k_{0}=1}^{d}\mathbbm{1}\{\left|x_{k_{0},i}-z_{k_{0},j}\right|\leq1\}\nonumber \\
 & =\frac{3}{d2^{d+1}N\prod_{k=1}^{d}h_{k}}\sum_{k=1}^{d}\left\{ \left(1-\frac{z_{k,j}^{2}}{h_{k}^{2}}\right)\mathcal{S}_{[k,k_{1},k_{2}]}^{[0,p_{1},p_{2}],q}([z_{j}-h_{j},z_{j}+h_{j}])+\right.\nonumber \\
 & =\left.2\frac{z_{k,j}}{h_{k}^{2}}\mathcal{S}_{[k,k_{1},k_{2}]}^{[1,p_{1},p_{2}],q}([z_{j}-h_{j},z_{j}+h_{j}])-\frac{1}{h_{k}^{2}}\mathcal{S}_{[k,k_{1},k_{2}]}^{[2,p_{1},p_{2}],q}([z_{j}-h_{j},z_{j}+h_{j}])\right\} \label{eq:parabolic-kernel-development-multivariate}
\end{align}

where
\begin{equation}
\mathcal{S}^{\mathrm{idx}}([\mathbf{L},\mathbf{R}]):=\mathcal{S}_{\mathbf{k}}^{\mathbf{p},q}([\mathbf{L},\mathbf{R}]):=\sum_{i=1}^{N}\left(\prod_{l=1}^{3}(x_{k_{l},i})^{p_{l}}\right)y_{i}^{q}\prod_{k_{0}=1}^{d}\mathbbm{1}\{L_{k_{0}}\leq x_{k_{0},i}\leq R_{k_{0}}\}\label{eq:SpqLRd}
\end{equation}

for any hyperrectangle $[\mathbf{L},\mathbf{R}]:=\left[L_{1},R_{1}\right]\times\left[L_{2},R_{2}\right]\times\ldots\times\left[L_{d},R_{d}\right]\subseteq\mathbb{R}^{d}$,
powers $\mathbf{p}:=(p_{1},p_{2},p_{3})\in\mathbb{N}^{3}$, $q\in\mathbb{N}$, indices $\mathbf{k}:=(k_{1},k_{2},k_{3})\in\{1,2,\ldots,d\}^{3}$,
and where $[z_{j}-h_{j},z_{j}+h_{j}]:=\left[z_{1,j}-h_{1,j},z_{1,j}+h_{1,j}\right]\times\ldots\times\left[z_{d,j}-h_{d,j},z_{d,j}+h_{d,j}\right]$. To simplify notations, we make use of the multi-index $\mathrm{idx}:=(\mathbf{p},q,\mathbf{k})$.

To sum up what has been established so far, computing multivariate kernel
smoothers (kernel density estimation, kernel regression, locally linear
regression) boils down to computing sums of type \eqref{eq:SpqLRd}
on hyperrectangles of the type $[z_{j}-h_{j},z_{j}+h_{j}]$ for every evaluation
point $j\in\{1,2,\ldots,M\}$. In the univariate case, these sums
could be computed efficiently by sorting the input points $x_{i}$,
$i\in\{1,2,\ldots,N\}$ and updating the sums from one evaluation
point to the next (equation \eqref{eq:1d_updating}). We now describe a similar efficient fast sum updating algorithm for
multivariate sums \eqref{eq:SpqLRd}, first established in \cite{langrene2017fast}. To do so, we first 
partition the input data into a multivariate rectilinear grid (subsection
\ref{subsec:Data-partition}), taking advantage of the fact that
the evaluation grid is rectilinear
and that the supports of the kernels have a hyperrectangle shape. Then, we set
up a fast sweeping algorithm using the sums on each hyperrectangle of the
partition as the unit blocks to be added and removed (subsection \ref{subsec:Fast-multivariate-sweeping}),
unlike the univariate case where the input points themselves were
being added and removed iteratively.

\subsubsection{Data partition\label{subsec:Data-partition}}

The first stage of the multivariate fast sum updating algorithm is
to partition the sample of input points into boxes. To do so, define
the sorted lists
$\tilde{\mathcal{G}}_{k}=\left\{ \tilde{g}_{k,1},\tilde{g}_{k,2},\ldots,\tilde{g}_{k,2M_{k}}\right\} :=\mathrm{sort}\!\left(\left\{ z_{k,j_{k}}-h_{k,j_{k}}\right\} _{j_{k}\in\{1,2,\ldots,M_{k}\}}\bigcup\left\{ z_{k,j_{k}}+h_{k,j_{k}}\right\} _{j_{k}\in\{1,2,\ldots,M_{k}\}}\right)$ in each dimension $k\in\{1,2,\ldots,d\}$, and define the partition
intervals $\tilde{I}_{k,l}:=\left[\tilde{g}_{k,l},\tilde{g}_{k,l+1}\right]$
for $l\in\left\{ 1,2,\ldots,2M_{k}-1\right\} $. By definition of
$\tilde{\mathcal{G}}_{k}$, all the bandwidths edges $z_{k,j_{k}}-h_{k,j_{k}}$
and $z_{k,j_{k}}+h_{k,j_{k}}$, $j_{k}\in\{1,2,\ldots,M_{k}\}$, belong
to $\tilde{\mathcal{G}}_{k}$. Therefore, there exists some indices
$\tilde{L}_{k,j_{k}}$ and $\tilde{R}_{k,j_{k}}$ such that $[z_{k,j_{k}}-h_{k,j_{k}},z_{k,j_{k}}+h_{k,j_{k}}]=[\tilde{g}_{k,\tilde{L}_{k,j_{k}}},\tilde{g}_{k,\tilde{R}_{k,j_{k}}\!+1}]=\bigcup_{l_{k}\in\{\tilde{L}_{k,j_{k}}\!,\ldots,\tilde{R}_{k,j_{k}}\!\}}\!\!\tilde{I}_{k,l_{k}}$.
From there, for any evaluation point $z_{j}=\left(z_{1,j_{1}},z_{2,j_{2}},\ldots,z_{d,j_{d}}\right)\in\mathbb{R}^{d}$,
the box $[z_{j}-h_{j},z_{j}+h_{j}]\subset\mathbb{R}^{d}$ can be decomposed
into a union of smaller boxes:
\vspace{-1mm}
\begin{align}
[z_{j}-h_{j},z_{j}+h_{j}] & =\left[z_{1,j_{1}}-h_{1,j_{1}},z_{1,j_{1}}+h_{1,j_{1}}\right]\times\ldots\times\left[z_{d,j_{d}}-h_{d,j_{d}},z_{d,j_{d}}+h_{d,j_{d}}\right]\nonumber \\
 & =\left[\tilde{g}_{1,\tilde{L}_{1,j_{1}}},\tilde{g}_{1,\tilde{R}_{1,j_{1}}\!+1}\right]\times\ldots\times\left[\tilde{g}_{d,\tilde{L}_{d,j_{d}}},\tilde{g}_{d,\tilde{R}_{d,j_{d}}\!+1}\right]\nonumber \\
 & =\bigcup_{(l_{1}\!,\ldots,l_{d})\in\{\tilde{L}_{1,j_{1}}\!,\ldots,\tilde{R}_{1,j_{1}}\!\}\!\times\ldots\times\!\{\tilde{L}_{d,j_{d}}\!,\ldots,\tilde{R}_{d,j_{d}}\!\}}\!\!\!\tilde{I}_{1,l_{1}}\!\times\ldots\times\tilde{I}_{d,l_{d}}\label{eq:pavement-1}
\end{align}
In other words, the set of boxes $\tilde{I}_{1,l_{1}}\times\tilde{I}_{2,l_{2}}\times\ldots\times\tilde{I}_{d,l_{d}}$
s.t. $l_{k}\in\{\tilde{L}_{k,j_{k}},\tilde{L}_{k,j_{k}}+1,\ldots,\tilde{R}_{k,j_{k}}\}$
in each dimension $k\in\left\{ 1,2,\ldots,d\right\} $ forms a partition
of the box $[z_{j}-h_{j},z_{j}+h_{j}]$. Consequently, the sum \eqref{eq:SpqLRd}
evaluated on the box $[z_{j}-h_{j},z_{j}+h_{j}]$ can be decomposed
as follows:
\begin{equation}
\mathcal{S}^{\mathrm{idx}}([z_{j}-h_{j},z_{j}+h_{j}])=\!\sum_{(l_{1}\!,\ldots,l_{d})\in\{\tilde{L}_{1,j_{1}}\!,\ldots,\tilde{R}_{1,j_{1}}\!\}\!\times\ldots\times\!\{\tilde{L}_{d,j_{d}}\!,\ldots,\tilde{R}_{d,j_{d}}\!\}}\!\!\!\mathcal{S}^{\mathrm{idx}}\!\left(\tilde{I}_{1,l_{1}}\times\ldots\times\tilde{I}_{d,l_{d}}\right)\label{eq:sum_partition_full-1}
\end{equation}
where we assume without loss of generality that the bandwidth grid
$h_{j}\!=\!\left(h_{1,j_{1}},\!h_{2,j_{2}},\!\ldots\!,\!h_{d,j_{d}}\right)$,
$j_{k}\in\{1,2,\ldots,M_{k}\},\,k\in\{1,2,\ldots d\}$ is such that
the list $\tilde{\mathcal{G}}_{k}$ does not contain any input $x_{k,i}$,
$i\in\left\{ 1,2,\ldots,N\right\} $ (as such boundary points would
be counted twice in the right-hand side of \eqref{eq:sum_partition_full-1}). The sum decomposition \eqref{eq:sum_partition_full-1} is the cornerstone
of the fast multivariate sum updating algorithm, but before going
further, one can simplify the partitions $\tilde{\mathcal{G}}_{k}$ while maintaining a sum decomposition
of the type \eqref{eq:sum_partition_full-1}. Indeed, in general some
intervals $\tilde{I}_{k,l}$ might be empty (i.e. they might not contain
any input point $x_{k,i}$). To avoid keeping track of sums $\mathcal{S}^{\mathrm{idx}}$
on boxes known to be empty, one can trim the partitions $\tilde{\mathcal{G}}_{k}$
by replacing each succession of empty intervals by one new partition
threshold. For example, if $\tilde{I}_{k,l}=[\tilde{g}_{k,l},\tilde{g}_{k,l+1}]$
is empty, one can remove the two points $\tilde{g}_{k,l}$ and $\tilde{g}_{k,l+1}$
and replace them by, for example, $(\tilde{g}_{k,l}+\tilde{g}_{k,l+1})/2$.
Denote by $\mathcal{G}_{k}=\left\{ g_{k,1},g_{k,2},\ldots,g_{k,m_{k}}\right\} $
the sorted simplified list, where $2\leq m_{k}\leq2M_{k}$, $k\in\left\{ 1,2,\ldots,d\right\} $,
and $m:=\prod_{k=1}^{d}m_{k}\leq2^{d}M$. Define the new partition
intervals $I_{k,l}:=\left[g_{k,l},g_{k,l+1}\right]$, $l\in\left\{ 1,2,\ldots,m_{k}-1\right\} $.
Because the trimming from $\tilde{\mathcal{G}}_{k}$ to $\mathcal{G}_{k}$
only affects the empty intervals, the following still holds:
\begin{lem}
\label{lem:sum_decomposition}For any evaluation point $z_{j}=(z_{1,j_{1}},z_{2,j_{2}},\ldots,z_{d,j_{d}})\in\mathbb{R}^{d}$,
$j_{k}\in\{1,2,\ldots,M_{k}\}$, $k\in\{1,2,\ldots d\}$ , there exists
indices $(L_{1,j_{1}},L_{2,j_{2}},\ldots,L_{d,j_{d}})$ and $(R_{1,j_{1}},R_{2,j_{2}},\ldots,R_{d,j_{d}})$
where $L_{k,j_{k}}$ and $R_{k,j_{k}}\in\{1,2,\ldots,m_{k}-1\}$ with
$L_{k,j_{k}}\leq R_{k,j_{k}}$ such that
\begin{equation}
\mathcal{S}^{\mathrm{idx}}([z_{j}-h_{j},z_{j}+h_{j}])=\!\sum_{(l_{1}\!,\ldots,l_{d})\in\{L_{1,j_{1}}\!,\ldots,R_{1,j_{1}}\!\}\!\times\ldots\times\!\{L_{d,j_{d}}\!,\ldots,R_{d,j_{d}}\!\}}\!\!\!\mathcal{S}^{\mathrm{idx}}\!\left(I_{1,l_{1}}\times\ldots\times I_{d,l_{d}}\right)\label{eq:sum_partition_slim}
\end{equation}
For later use, we introduce the compact notation $\mathcal{S}_{l_{1},l_{2},\ldots,l_{d}}^{\mathrm{idx}}\hspace{-0.1em}:=\mathcal{S}^{\mathrm{idx}}(I_{1,l_{1}}\hspace{-0.1em}\!\times\!\ldots\!\times\hspace{-0.1em}I_{d,l_{d}})$. Recalling equation \eqref{eq:SpqLRd}, the sum $\mathcal{S}_{l_{1},l_{2},\ldots,l_{d}}^{\mathrm{idx}}$ corresponds to the sum of the polynomials $(\prod_{l=1}^{3}(x_{k_{l},i})^{p_{l}})y_{i}^{q}$ over all the data points within the box $I_{1,l_{1}}\!\times\ldots\times I_{d,l_{d}}$.
\end{lem}
%


\subsubsection{Fast multivariate sweeping algorithm\label{subsec:Fast-multivariate-sweeping}}

So far, we have shown that computing multivariate kernel smoothers
is based on the computation of the kernel sums \eqref{eq:sum_multidim},
which can be decomposed into sums of the type \eqref{eq:SpqLRd},
which can themselves be decomposed into the smaller sums \eqref{eq:sum_partition_slim}
by decomposing every kernel support of every evaluation point onto
the box partition described in the previous subsection \ref{subsec:Data-partition}.
The final task is to define an efficient algorithm to traverse all
the hyperrectangle unions $\bigcup_{(l_{1}\!,\ldots,l_{d})\in\{L_{1,j_{1}}\!,\ldots,R_{1,j_{1}}\!\}\!\times\ldots\times\!\{L_{d,j_{d}}\!,\ldots,R_{d,j_{d}}\!\}}I_{1,l_{1}}\!\times\ldots\times I_{d,l_{d}}$,
so as to compute the right-hand side sums in equations \eqref{eq:sum_partition_slim} (Lemma \ref{lem:sum_decomposition}) in an efficient fast sum updating way similar to the univariate \eqref{eq:1d_updating}. We precompute all the sums $\mathcal{S}_{l_{1},l_{2},\ldots,l_{d}}^{\mathrm{idx}}$ with $\mathrm{idx}=\left(\mathbf{p},q,\mathbf{k}\right)\in\{0,1,2\}\times\{0,1\}^{3}\times\{1,2,\ldots,d\}^{3}$, 
and use them as input material for fast multivariate sum updating.

We start with the bivariate case. We first provide an algorithm to compute the
sums $\mathcal{T}_{1,l_{2}}^{\mathrm{idx}}:=\sum_{l_{1}=L_{1,j_{1}}}^{R_{1,j_{1}}}\mathcal{S}_{l_{1},l_{2}}^{\mathrm{idx}}$
, for every $l_{2}\in\left\{ 1,2,\ldots,m_{2}-1\right\} $ and every
index interval $\left[L_{1,j_{1}},R_{1,j_{1}}\right]$, $j_{1}\in\{1,2,\ldots,M_{1}\}$.
Starting with $j_{1}=1$, we first compute $\mathcal{T}_{1,l_{2}}^{\mathrm{idx}}=\sum_{l_{1}=L_{1,1}}^{R_{1,1}}\mathcal{S}_{l_{1},l_{2}}^{\mathrm{idx}}$
for every $l_{2}\in\left\{ 1,2,\ldots,m_{2}-1\right\} $. Then we
iteratively increment $j_{1}$ from $j_{1}=1$ to $j_{1}=M_{1}$. After each incrementation of $j_{1}$, we update $\mathcal{T}_{1,l_{2}}^{\mathrm{idx}}$
by fast sum updating
\begin{equation}
\sum_{l_{1}=L_{1,j_{1}}}^{R_{1,j_{1}}}\mathcal{S}_{l_{1},l_{2}}^{\mathrm{idx}}=\sum_{l_{1}=L_{1,j_{1}-1}}^{R_{1,j_{1}-1}}\mathcal{S}_{l_{1},l_{2}}^{\mathrm{idx}}+\sum_{l_{1}=R_{1,j_{1}-1}+1}^{R_{1,j_{1}}}\mathcal{S}_{l_{1},l_{2}}^{\mathrm{idx}}-\sum_{l_{1}=L_{1,j_{1}-1}}^{L_{1,j_{1}}-1}\mathcal{S}_{l_{1},l_{2}}^{\mathrm{idx}}\label{eq:2d_updating_1}
\end{equation}

The second stage is to perform a fast sum updating in the second dimension,
with the sums $\mathcal{T}_{1,l_{2}}^{\mathrm{idx}}=\sum_{l_{1}=L_{1,j_{1}}}^{R_{1,j_{1}}}\mathcal{S}_{l_{1},l_{2}}^{\mathrm{idx}}$
as input material. Our goal is to compute the sums $\mathcal{T}_{2}^{\mathrm{idx}}:=\sum_{l_{2}=L_{2,j_{2}}}^{R_{2,j_{2}}}\mathcal{T}_{1,l_{2}}^{\mathrm{idx}}$
for every index interval $\left[L_{2,j_{2}},R_{2,j_{2}}\right]$,
$j_{2}\in\{1,2,\ldots,M_{2}\}$. In a similar manner, we start from
$j_{2}=1$ with the initial sum $\mathcal{T}_{2}^{\mathrm{idx}}=\sum_{l_{2}=L_{2,1}}^{R_{2,1}}\mathcal{T}_{1,l_{2}}^{\mathrm{idx}}$.
We then increment $j_{2}$ from $j_{2}=1$ to $j_{2}=M_{2}$ iteratively.
After each incrementation of $j_{2}$, we update $\mathcal{T}_{2}^{\mathrm{idx}}$
by fast sum updating:
\begin{equation}
\sum_{l_{2}=L_{2,j_{2}}}^{R_{2,j_{2}}}\mathcal{T}_{1,l_{2}}^{\mathrm{idx}}=\sum_{l_{2}=L_{2,j_{2}-1}}^{R_{2,j_{2}-1}}\mathcal{T}_{1,l_{2}}^{\mathrm{idx}}+\sum_{l_{2}=R_{2,j_{2}-1}+1}^{R_{2,j_{2}}}\mathcal{T}_{1,l_{2}}^{\mathrm{idx}}-\sum_{l_{2}=L_{2,j_{2}-1}}^{L_{2,j_{2}}-1}\mathcal{T}_{1,l_{2}}^{\mathrm{idx}}\label{eq:2d_updating_2}
\end{equation}
Using Lemma \ref{lem:sum_decomposition}, the resulting sum $\sum_{l_{2}=L_{2,j_{2}}}^{R_{2,j_{2}}}\mathcal{T}_{1,l_{2}}^{\mathrm{idx}}=\sum_{l_{1}=L_{1,j_{1}}}^{R_{1,j_{1}}}\sum_{l_{2}=L_{2,j_{2}}}^{R_{2,j_{2}}}\mathcal{S}_{l_{1},l_{2}}^{\mathrm{idx}}$
is equal to $\mathcal{S}^{\mathrm{idx}}([z_{j}-h_{j},z_{j}+h_{j}])$,
which can be used to compute the kernel sums $\mathbf{S}_{j}$
using equation \eqref{eq:parabolic-kernel-development-multivariate},
from which the bivariate kernel smoothers can be computed.


This ends the description of the fast sum updating algorithm in the
bivariate case. 
Finally, the general multivariate case is a straightforward extension
of the bivariate case (see \cite{langrene2017fast}).
\subsection{C++ API}
The constructor allows to define the kernel regressor:
\begin{lstlisting}[style=CStyle]
LocalGridKernelRegression(const bool &p_bZeroDate,
                              const std::shared_ptr< Eigen::ArrayXXd > &p_particles,
                              const double &p_coeffBandWidth,
                              const double &p_coefNbGridPoint,
                              const bool &p_bLinear);
\end{lstlisting}
where
\begin{itemize}
\item \code{p\_bZeroDate} is \code{true} if the regression date is $0$,
\item \code{p\_particles} the particles $X_t$ for all simulations (dimension of $X_t$ for first dimension, number of Monte Carlo simulations in second dimension),
\item \code{p\_coeffBandWidth} between 0 and 1 defines the percentage of points to use to define the bandwidth for each point.
\item \code{p\_coefNbGridPoint} is a multiplying factor defining the number of points $z$ used for the multi-grid approximation: a PCA is used to define a data rotation. The kernel regression is performed according the basis defined by the eigenvectors associated with the PCA.  The number of points along the axes defined by the eigenvectors is given as a function of the singular value associated with the eigenvector.
The total number of evaluation points along the axes of the new base is approximately the number of simulations (p\_particles.cols()) by \code{p\_coefNbGridPoint}.
\item \code{p\_bLinear} when set to \code{false} indicates that the simple estimate of the density of the kernel \eqref{eq:localreg0} is used. When \code{p\_bLinear} is \code{true}, the linear regression of the kernel  \eqref{eq:localreg1} is used.
\end{itemize}
Below we give a small example where \code{toRegress} corresponds to $g(t+h, X_{t+h})$ for all simulations and $x$ stores $X_t$ for all simulations.
\begin{lstlisting}[style=CStyle]
   
     // t is not zero
     bool bZeroDate = 0;
     // proportion of points used to define the bandwidth
     double prop =0.1;
     //  multiplicative factor equal to one: number of evaluation points equal to the number of particles
     double q  =1.
     // choose a linear regression
     bool bLin= true;
     // constructor
     LocalGridKernelRegression kernelReg(bZeroDate, x, prop, q, bLin);
     // update particles values
     localRegressor.updateSimulations(bZeroDate, x);
    // regressed values
     ArrayXd  regressedValues = localRegressor.getAllSimulations(toRegress);
\end{lstlisting}
\subsection{Python API}
As usual the Python constructors are similar to the C++ constructors. Here is a small example of the use of the kernel regression method.
\begin{lstlisting}[style=PStyle]
        import StOptReg 
        nbSimul = 5000000;
        np.random.seed(1000)
        x = np.random.uniform(-.,1.,size=(1,nbSimul));
        # real function
        toReal = (2+x[0,:]+(+x[0,:])*(1+x[0,:]))
        # function to regress
        toRegress = toReal + 4*np.random.normal(0.,,nbSimul)
        # bandwidth
        bandwidth = 0.1
        # factor for the number of points
        factPoint=1
        # Regressor
        regressor = StOptReg.LocalGridKernelRegression(False,x,bandwidth,factPoint, True)
        # get regressed
        y = regressor.getAllSimulations(toRegress).transpose()[0]
\end{lstlisting}

\section{Kernel regression with Laplacian  kernels}
This subsection is based on the work \cite{langrene2020fast}. Keeping in mind the notations of section \ref{sec:kernelReg}, we focus on the Laplacian kernel, defined by 
\begin{equation}
K(u)=\frac{1}{2}e^{-|u|}\label{eq:Laplacian_kernel_1D}
\end{equation}
The Laplacian kernel density estimator is defined by: 

\begin{equation}
\hat{f}_{\mathrm{KDE}}(z)=\frac{1}{N}\sum_{i=1}^{N}\frac{1}{2h}e^{-\frac{|x_{i}-z|}{h}}\label{eq:Laplacian_kde_1D}
\end{equation}

\subsection{ Reducing the problem to empiral CDF calculations}
This kernel density estimator can be decomposed as follows in one dimension:
\begin{align}
\hat{f}_{\mathrm{KDE}}(z)= & \frac{1}{N}\sum_{i=1}^{N}\frac{1}{2h}e^{-\frac{|x_{i}-z|}{h}}\nonumber \\
= & \frac{1}{2hN}\left(\sum_{i=1}^{N}e^{\frac{x_{i}-z}{h}}\mathbbm{1}\{x_{i}\leq z\}+\sum_{i=1}^{N}     e^{\frac{z-x_{i}}{h}}\mathbbm{1}\{x_{i}>z\}\right)\nonumber \\
= & \frac{1}{2hN}\left(e^{-\frac{z}{h}}\sum_{i=1}^{N}     e^{\frac{x_{i}}{h}}\mathbbm{1}\{x_{i}\leq z\}+e^{\frac{z}{h}}\sum_{i=1}^{N}     e^{-\frac{x_{i}}{h}}\mathbbm{1}\{x_{i}>z\}\right)\nonumber \\
= & \frac{1}{2h}\left(e^{-\frac{z}{h}}F_{N}(z;x,we^{\frac{x}{h}})+e^{\frac{z}{h}}\bar{F}_{N}(z;x,we^{-\frac{x}{h}})\right)\label{eq:Laplacian_decomposition_1d}
\end{align}
where the empirical CDF $F_{N}$ and the empirical complementary CDF
$\bar{F}_{N}$ are defined by equations 
\begin{equation}
F_{N}(z)=F_{N}(z;x,y)\triangleq\frac{1}{N}\sum_{i=1}^{N}y_{i}\mathbbm{1}\{x_{1,i}\leq z_{1},\ldots,x_{d,i}\leq z_{d}\}\,.\label{eq:ECDF}
\end{equation}
\begin{equation}
\bar{F}_{N}(z)=\bar{F}_{N}(z;x,y)\triangleq\frac{1}{N}\sum_{i=1}^{N}y_{i}\mathbbm{1}\{x_{1,i}>z_{1},\ldots,x_{d,i}>z_{d}\}\,.\label{eq:ESF}
\end{equation}
Crucially, such a CDF decomposition of KDE also holds in the multivariate
setting. The multivariate Laplacian kernel is defined by

\begin{equation}
K_{\hspace{-0.0833em}d}(u)=\frac{1}{2^{d}}e^{-|u|}=\frac{1}{2^{d}}e^{-\sum_{k=1}^{d}|u_{k}|}\label{eq:Laplacian_kernel_nD}
\end{equation}
and the      multivariate Laplacian kernel density estimator is
given by

\begin{equation}
\hat{f}_{\mathrm{KDE}}(z)=\frac{1}{2^{d}N\Pi_{k=1}^{d}h_{k}}\sum_{i=1}^{N} e^{-\left|\frac{x_{i}-z}{h}\right|}=\frac{1}{2^{d}N\Pi_{k=1}^{d}h_{k}}\sum_{i=1}^{N} e^{-\sum_{k=1}^{d}\frac{\left|x_{k,i}-z_{k}\right|}{h_{k}}}\label{eq:Laplacian_kde_nD}
\end{equation}
where $h=(h_{1},h_{2},\ldots,h_{d})\in\mathbb{R}^{d}$ is a multivariate
bandwidth. \\
We introduce :
\begin{align}
F_{N}(z,\delta) & =F_{N}(z,\delta;x,y)\triangleq\frac{1}{N}\sum_{i=1}^{N}y_{i}\mathbbm{1}\{x_{1,i}\leq_{\delta_{1}}z_{1},\ldots,x_{d,i}\leq_{\delta_{d}}z_{d}\}\label{eq:ECDFdelta}
\end{align}
where $\delta=\left\{ \delta_{1},\delta_{2},\ldots,\delta_{d}\right\} \in\left\{ -1,1\right\} ^{d}$,
and where the generalized inequality operator $\leq_{c}$ corresponds
to $\leq$ (lower or equal) if $c\geq0$, and to $<$ (strictly lower) if $c<0$. In particular $F_{N}(z)=F_{N}(z,1;x,y)$
and $\bar{F}_{N}(z)=F_{N}(-z,-1;-x,y)$ respectively.\\
Using the same approach as equation \eqref{eq:Laplacian_decomposition_1d},
the sum \eqref{eq:Laplacian_kde_nD} can be decomposed as follows:
\begin{align}
\hat{f}_{\mathrm{KDE}}(z)= & \frac{1}{2^{d}N\Pi_{k=1}^{d}h_{k}}\sum_{i=1}^{N} \prod_{k=1}^{d}\left(e^{-\frac{z_{k}}{h_{k}}}e^{\frac{x_{k,i}}{h_{k}}}\mathbbm{1}\{x_{k,i}\leq z_{k}\}+e^{\frac{z_{k}}{h_{k}}}e^{-\frac{x_{k,i}}{h_{k}}}\mathbbm{1}\{-x_{k,i}<-z_{k}\}\right)\nonumber \\
= & \frac{1}{2^{d}N\Pi_{k=1}^{d}h_{k}}\sum_{i=1}^{N} \sum_{\delta\in\{-1,1\}^{d}}\prod_{k=1}^{d}e^{-\frac{\delta_{k}z_{k}}{h_{k}}}e^{\frac{\delta_{k}x_{k,i}}{h_{k}}}\mathbbm{1}\{\delta_{k}x_{k,i}\leq_{\delta_{k}}\delta_{k}z_{k}\}\nonumber \\
= & \frac{1}{2^{d}\Pi_{k=1}^{d}h_{k}}\sum_{\delta\in\{-1,1\}^{d}}e^{-\sum_{k=1}^{d}\frac{\delta_{k}z_{k}}{h_{k}}}\frac{1}{N}\sum_{i=1}^{N} e^{\sum_{k=1}^{d}\frac{\delta_{k}x_{k,i}}{h_{k}}}\mathbbm{1}\{\delta_{1}x_{1,i}\leq_{\delta_{1}}\delta_{1}z_{1},\ldots,\delta_{d}x_{d,i}\leq_{\delta_{d}}\delta_{d}z_{d}\}\nonumber \\
= & \frac{1}{2^{d}\Pi_{k=1}^{d}h_{k}}\sum_{\delta\in\{-1,1\}^{d}}e^{-\sum_{k=1}^{d}\frac{\delta_{k}z_{k}}{h_{k}}}F_{N}(\delta z,\delta;\delta x,y)\label{eq:Laplacian_decomposition_nD}
\end{align}
with $y_{i}=y_{i}(\delta):=e^{\sum_{k=1}^{d}\frac{\delta_{k}x_{k,i}}{h_{k}}}$.
Equation \eqref{eq:Laplacian_decomposition_nD} shows that the computation
of the multivariate Laplacian kernel density estimator
can be decomposed into the computation of $2^{d}$ generalized empirical
CDF \eqref{eq:ECDFdelta}.

\subsection{Fast computation of ECDFs}
We present two ways to compute efficiently an expression such as \ref{eq:Laplacian_decomposition_nD}.
The first is based on the use of a rectilinear grid as evaluation points and an interpolation is needed to get back the conditional expectation at the sample points.
The second one, based on the divide and conquer approach,  is exact but much  more costly.
\subsubsection{Fast sum updating in lexicographical order\label{subsec:Fast-lexicographical-sweep}}

Let $z_{j}=(z_{1,j},z_{2,j},\ldots,z_{d,j})\in\mathbb{R}^{d}$, $j\in\{1,2,\ldots,M\}$,
be a set of $M$ evaluation (target) points.

We require this evaluation grid to be rectilinear, i.e., the $M$
evaluation points $z_{1},z_{2},\ldots,z_{M}$ lie on a regular grid
with possibly non-uniform mesh, of dimension $M_{1}\times M_{2}\times\ldots\times M_{d}=M$:
\[
\mathbf{z}=\left\{ (z_{1,j_{1}},z_{2,j_{2}},\ldots,z_{d,j_{d}})\in\mathbb{R}^{d},\,j_{k}\in\{1,2,\ldots,M_{k}\},\,k\in\{1,2,\ldots,d\}\right\} 
\]
For convenience, we extend the definition of the grid with the notational conventions $z_{k,0}\triangleq-\infty$ and $z_{k,M_{k}+1}\triangleq\infty$.

In each dimension $k\in\{1,2,\ldots,d\}$, the vector $(z_{k,1},z_{k,2},\ldots,z_{k,M_{k}})\in\mathbb{R}^{M_{k}}$
is assumed to be sorted in increasing order:
\[
z_{k,1}<z_{k,2}<\ldots<z_{k,M_{k}},\,k\in\{1,2,\ldots,d\}
\]
We partition the input data $\mathbf{x}$ along this evaluation grid
$\mathbf{z}$. For each evaluation grid index $(j_{1},j_{2},\ldots,j_{d})\in\{1,2,\ldots,M_{1}+1\}\times\ldots\times\{1,2,\ldots,M_{d}+1\}$
we define the following local sum
\begin{equation}
s_{j_{1},j_{2},\ldots,j_{d}}:=\frac{1}{N}\sum_{i=1}^{N}y_{i}\mathbbm{1}\{z_{1,j_{1}-1}<x_{1,i}\leq z_{1,j_{1}},\ldots,z_{d,j_{d}-1}<x_{d,i}\leq z_{d,j_{d}}\}\label{eq:partial_sums}
\end{equation}
Together, the sums \eqref{eq:partial_sums}
form a generalized multivariate histogram (classical histogram
in the case $y\equiv1$). For completeness, the computation of the local sums \eqref{eq:partial_sums}
is detailed in algorithm \ref{algo:local_sum_general}.

\begin{algorithm}[H]
\caption{Fast computation of local sums by independent sorting in  each dimension \label{algo:local_sum_general}}
\begin{algorithmic}[1]
  \State Input: sample $x_{i}=(x_{1,i},\ldots,x_{d,i})$, $i=1,2,\ldots,N$
  \State Input :  evaluation grid $(z_{1,j_{1}},z_{2,j_{2}},\ldots,z_{d,j_{d}})$, $j_{k}\in\{1,2,\ldots,M_{k}\}$, $k\in\{1,2,\ldots,d\}$
  \State
  Define index matrix $\mathrm{INDEX}[k,i]$ \Comment{local sum
    index $\in\{1,2,M_{k}+1\}$}
  where $k=1,2,\ldots,d$ and $i=1,2,\ldots,N$
  \For $\textcolor{blue}{\mathbf{(}}$ $k=1,2,...\hspace{0.0833em},d$
  $\textcolor{blue}{\mathbf{)}}$
  \State
  Sort the set $\left\{ x_{k,1},\ldots x_{k,N}\right\} $ in increasing
  order, using for example quicksort or
mergesort ($\mathcal{O}(N\log N)$): define the permutation $\phi_{k}:\{1,2,\ldots,N\}\mapsto\{1,2,\ldots,N\}$

such that
\begin{equation}
x_{k,\phi_{k}(1)}<x_{k,\phi_{k}(2)}<\cdots<x_{k,\phi_{k}(N)}\label{eq:sorted_kdim}
\end{equation}

\State $x_{\mathrm{idx}}=1$ \Comment{input index $\in\{1,2,\ldots,N\}$}

\State $z_{\mathrm{idx}}=1$ \Comment{evaluation grid index $\in\{1,2,\ldots,M_{k}\}$}

\While $\textcolor{blue}{\mathbf{(}}$ $x_{\mathrm{idx}}\leq N$
$\textcolor{blue}{\mathbf{)}}$

\If  $\textcolor{blue}{\mathbf{(}}$ $x_{k,\phi_{k}(x_{\mathrm{idx}})}\leq z_{k,z_{\mathrm{idx}}}$
$\textcolor{blue}{\mathbf{)}}$
\State $\mathrm{INDEX}[k,\phi_{k}(x_{\mathrm{idx}})]=z_{\mathrm{idx}}$
\State $x_{\mathrm{idx}}\,+\hspace{-0.0833em}\!=1$
\Else
\State $z_{\mathrm{idx}}\,+\hspace{-0.0833em}\!=1$
\EndIf
\EndWhile
\EndFor
\State $s_{j_{1},j_{2},\ldots,j_{d}}=0$, ${\scriptstyle \forall(j_{1},j_{2},\ldots,j_{d})\in\{1,2,\ldots,M_{1}+1\}\times\ldots\times\{1,2,\ldots,M_{d}+1\}}$

\For $\textcolor{blue}{\mathbf{(}}$ $i=1,2,...\hspace{0.0833em},N$ $\textcolor{blue}{\mathbf{)}}$
\State $s_{\mathrm{INDEX}[1,i],\,\mathrm{INDEX}[2,i],\,\ldots,\,\mathrm{INDEX}[d,i]}\,+\hspace{-0.0833em}\!=y_{i}/N$
\EndFor

\State \Return  $s_{j_{1},j_{2},\ldots,j_{d}}=\frac{1}{N}\sum_{i=1}^{N}y_{i}\mathbbm{1}\{z_{1,j_{1}-1}<x_{1,i}\leq z_{1,j_{1}},\ldots,z_{d,j_{d}-1}<x_{d,i}\leq z_{d,j_{d}}\}$

for every local sum index ${\scriptstyle (j_{1},j_{2},\ldots,j_{d})\in\{1,2,\ldots,M_{1}+1\}\times\ldots\times\{1,2,\ldots,M_{d}+1\}}$
\end{algorithmic}
\end{algorithm}


In particular, using equation \eqref{eq:ECDF}, the following key
equality holds:
\begin{equation}
F_{N}(z)=\sum_{l_{1}=1}^{j_{1}}\!\sum_{l_{2}=1}^{j_{2}}\cdots\sum_{l_{d}=1}^{j_{d}}s_{l_{1},l_{2},\ldots,l_{d}}\label{eq:ECDF_decomposition}
\end{equation}
for any evaluation point $z=(z_{1,j_{1}},z_{2,j_{2}},\ldots,z_{d,j_{d}})\in\mathbf{z}$.

We propose a simple fast summation algorithm, Algorithm \ref{algo:fast_sum_CDF}, to compute the ECDFs $F_N(z)$ for every $z\in\mathbf{z}$ in lexicographical order based on the local sum decomposition \eqref{eq:ECDF_decomposition}. One can easily verify that the number of operations is proportional to $M_{1}\times M_{2}\times\ldots\times M_{d}=M$. As the computation of the local sums \eqref{eq:partial_sums} costs $\mathcal{O}(N{\log}N)$ operations (or only $\mathcal{O}(N)$ if the grid is uniform or the data already sorted), the overall computational complexity of Algorithm \ref{algo:fast_sum_CDF} is $\mathcal{O}(M+N{\log}N)$, or $\mathcal{O}(N{\log}N)$ when $M{\approx}N$ (respectively $\mathcal{O}(M+N)$ and $\mathcal{O}(N)$ when the grid is uniform or the data already sorted).\\

\begin{algorithm}[H]
  \caption{Fast joint empirical cumulative distribution function\label{algo:fast_sum_CDF}}
  \begin{algorithmic}[1]

    \State Input :precomputed sums $s_{l_{1},l_{2},\ldots,l_{d}}$
    \State $\mathcal{S}_{1,l_{2},l_{3},\ldots,l_{d}}=0$
    \For $\textcolor{blue}{\mathbf{(}}$  $j_{1}=1,...,M_{1}+1$ $\textcolor{blue}{\mathbf{)}}$
    \State $\mathcal{S}_{1,l_{2},l_{3},\ldots,l_{d}}\,\,+\!=\,s_{j_{1},l_{2},l_{3},\ldots,l_{d}}$,~~${\scriptstyle \forall l_{k}\in\left\{ 1,2,\ldots, M_{k}+1 \right\} }$,~${\scriptstyle k\in\{2,3,\ldots,d\}}$
    \Comment{Here $\mathcal{S}_{1,l_{2},l_{3},\ldots,l_{d}}\!=\sum_{l_{1}=1}^{j_{1}}\!s_{l_{1},l_{2},\ldots,l_{d}}$,~${\scriptstyle \forall l_{k}\in\left\{ 1,2,\ldots,M_{k}+1\right\} }$,~${\scriptstyle k\in\{2,3,\ldots,d\}}$}
    \State $\mathcal{S}_{2,l_{3},\ldots,l_{d}}=0$

    \For $\textcolor{blue}{\mathbf{(}}$ $j_{2}=1,...,M_{2}+1$ $\textcolor{blue}{\mathbf{)}}$
    \State $\mathcal{S}_{2,l_{3},\ldots,l_{d}}\,\,+\!=\,\mathcal{S}_{1,j_{2},l_{3},\ldots,l_{d}}$,~~${\scriptstyle \forall l_{k}\in\left\{ 1,2,\ldots,M_{k}+1\right\} }$,~${\scriptstyle k\in\{3,\ldots,d\}}$
\Comment{Here $\mathcal{S}_{2,l_{3},\ldots,l_{d}}\!=\sum_{l_{1}=1}^{j_{1}}\!\sum_{l_{2}=1}^{j_{2}}\!\!s_{l_{1},l_{2},\ldots,l_{d}}$,~${\scriptstyle \forall l_{k}\in\left\{ 1,\ldots, M_{k}+1\right\} }$,~${\scriptstyle k\in\{3,\ldots d\}}$}
     \State $\mathcal{S}_{d}=0$

     \For $\textcolor{blue}{\mathbf{(}}$ $j_{d}=1,...,M_{d}+1$ $\textcolor{blue}{\mathbf{)}}$
     \State $\mathcal{S}_{d}\,\,+\!=\,\mathcal{S}_{d-1,j_{d}}$ \\
     \Comment{Here $\mathcal{S}_{d}=\sum_{l_{1}=1}^{j_{1}}\!\sum_{l_{2}=1}^{j_{2}}\cdots\sum_{l_{d}=1}^{j_{d}}s_{l_{1},l_{2},\ldots,l_{d}}$}
     \Comment{$=F_{N}(z_{1,j_{1}},z_{2,j_{2}},\ldots,z_{d,j_{d}})=F_{N}(z)$ from equation \eqref{eq:ECDF_decomposition}}
     \EndFor
    \EndFor
 \EndFor
\State \Return $F_{N}(z)$ for all $z\in\mathbf{z}$
\end{algorithmic}
\end{algorithm}
\subsection{Divide-and-conquer approach}
Consider the case when the evaluation points $z_j$ are equal to the input points $x_i$. The calculation of the ECDFs $\{F_{N}(x_{i})\}_{i=1,N}$ (equation \eqref{eq:ECDF}) corresponds to a domination
problem in dimension $d$. An algorithm based on a recursive divide-and-conquer sequence has first been proposed in \cite{Bentley1980} for this problem.
An adaptation was proposed in \cite{bouchard2012monte} to solve this problem for
the case of the calculation of conditional expectation using Malliavin
weights. The computational complexity was shown to be $O(c(d)N\log(N)^{(d-1){\vee}1})$.
We do not repeat the construction of this algorithm here, and the interested reader can refer to \cite{langrene2020fast}.


\subsection{C++ API  for fast summation method}
The constructor allows to define the  Laplacian kernel regressor with the fast summation method:
\begin{lstlisting}[style=CStyle]
 LaplacianGridKernelRegression(const bool &p_bZeroDate,
                                  const Eigen::ArrayXXd  &p_particles,
                                  const Eigen::ArrayXd   &p_h,
                                  const double   &p_coefNbGridPoint,
                                  const bool &p_bLinear);
\end{lstlisting}
where
\begin{itemize}
\item \code{p\_bZeroDate} is \code{true} if the regression date is $0$,
\item \code{p\_particles} the particles $X_t$ for all simulations (dimension of $X_t$ for first dimension, number of Monte Carlo simulations in second dimension),
\item \code{p\_h}  bandwidth array per dimension.
\item \code{p\_coefNbGridPoint} is a multiplying factor defining the number of points $z$ used for the multi-grid approximation. The total number of points on the rectilinear grid is the number of samples by \code{p\_coefNbGridPoint}.
\item \code{p\_bLinear} when set to \code{false} indicates that the simple estimate of the density of the kernel \eqref{eq:localreg0} is used. When \code{p\_bLinear} is \code{true}, the linear regression of the kernel  \eqref{eq:localreg1} is used.
\end{itemize}
Below we give a small example where \code{toRegress} corresponds to $g(t+h, X_{t+h})$ for all simulations and $x$ store $X_t$ for all simulations.
\begin{lstlisting}[style=CStyle]

     // t is not zero
     bool bZeroDate = false;

     // use linear regression
     bool bLinear = true;
     
     // bandwidth
     ArrayXd hB = ArrayXd::Constant(1, p_h);

    // test regression object
    double q = 50; // coeff for the number of grid points used
    LaplacianGridKernelRegression kernelReg(bZeroDate, x, hB, q, bLinear);

    // regress on grid
    ArrayXd regressed = kernelReg.getAllSimulations(y);

\end{lstlisting}    

\subsection{Python  API  for fast summation method}
For example, using the linear regressor we get the following Python code:
\begin{lstlisting}[style=PStyle]
        import StOptReg 
        nbSimul = 100000;
        np.random.seed(1000)
        x = np.random.uniform(-1.,1.,size=(1,nbSimul));
        # real function
        toReal = (4+x[0,:]+(3+x[0,:])*(2+x[0,:]))
        # function to regress
        toRegress = toReal + 4*np.random.normal(0.,1,nbSimul)
        # bandwidth
        bandwidth = 0.05*np.ones(1)
        # multiplicative for rectilinear grid
        coeffMul = 2
        # Linear or constant regressions
        bLinear= False
        # Regressor
        regressor = StOptReg.LaplacianGridKernelRegression(False,x,bandwidth, coeffMul,bLinear)
        # test particules
        y = regressor.getAllSimulations(toRegress).transpose()
\end{lstlisting}
  

\subsection{C++ API  for exact divid and conquer method}
The constructor allows to defines the  Laplacian kernel regressor with the divide and conquer method  and a constant regression
\begin{lstlisting}[style=CStyle]
LaplacianConstKernelRegression(const bool &p_bZeroDate,
                              const std::shared_ptr< Eigen::ArrayXXd > &p_particles,
                              const double &p_h);
\end{lstlisting}
where
\begin{itemize}
\item \code{p\_bZeroDate} is \code{true} if the regression date is $0$,
\item \code{p\_particles} the particles $X_t$ for all simulations (dimension of $X_t$ for first dimension, number of Monte Carlo simulations in second dimension),
\item \code{p\_h}  bandwidth array per dimension.
\end{itemize}
And the following one deals with the linear regression case.
\begin{lstlisting}[style=CStyle]
LaplacianLinearKernelRegression(const bool &p_bZeroDate,
                              const std::shared_ptr< Eigen::ArrayXXd > &p_particles,
                              const double &p_h);
\end{lstlisting}
where
\begin{itemize}
\item \code{p\_bZeroDate} is \code{true} if the regression date is $0$,
\item \code{p\_particles} the particles $X_t$ for all simulations (dimension of $X_t$ for first dimension, number of Monte Carlo simulations in second dimension),
\item \code{p\_h}  bandwidth array per dimension.
\end{itemize}

\subsection{Python API for exact divide-and-conquer method}
As usual, the Python constructor is similar to the C++ constructor.
For example, using the linear regressor we get the following Python code:
\begin{lstlisting}[style=PStyle]
        import StOptReg 
        nbSimul = 100000;
        np.random.seed(1000)
        x = np.random.uniform(-1.,1.,size=(1,nbSimul));
        # real function
        toReal = (4+x[0,:]+(3+x[0,:])*(2+x[0,:]))
        # function to regress
        toRegress = toReal + 4*np.random.normal(0.,1,nbSimul)
        # bandwidth
        bandwidth = 0.05*np.ones(1)
        # Regressor
        regressor = StOptReg.LaplacianConstKernelRegression(False,x,bandwidth)
        # test particules
        y = regressor.getAllSimulations(toRegress).transpose()
\end{lstlisting}


\chapter{Calculating conditional expectation by trees}
\label{sec::tree}
A popular method for calculating conditional expectation is to use scenario trees.\\
In the financial community, binary and trinomial trees are generally used to evaluate options.
When the asset is modeled by a Black Scholes model, a binary model is used, while a trinomial model is used to model the average reversion using a Vaciseck model for interest rate, for example \cite{hull2003options}.
An example of a trinomial tree is given in the figure \ref{fig:trinomial} for an Ornstein--Uhlenbeck model (so in dimension 1).
\begin{figure}[h]
\centerline{
\includegraphics[width=8cm]{trinomialTree.png}}
\caption{Trinomial tree}
\label{fig:trinomial}
\end{figure}
This tree models the possible evolution of a state $X_t$ in dimension 1 and each node corresponds to a possible value of $X_t$.
These trees recombine. The nodes at each dates $i$  are numbered from $0$ to $N_i-1$  with increasing values $X_t^i$ of the state.\\
From a node $i$ on a date $t$, 3 nodes can be reached on the date $t+1$. The probability transition from going to a node down $f(i,t)-1$ is $p_d^{t,i}$ while the probability of going to a middle node $f(i,t)$  is $p_m^{t,i}$ and the probability of going to a node up to $f(i,t)+1$  is $p_u^{t,i}$.\\
The conditional expectation of a function  with the values $g_j^{t+1}= g(X_{t+1}^j)$ at the node $j$ on the date $i+1$ is simply given by:
\begin{flalign}
  \E[ g(X_{t+1})/ X_{t} = X_t^i ] \simeq  p_d^{t,i} g_{f(t,i)-1}^{t+1} + p_m^{t,i}  g_{f(t,i)}^{t+1} + p_u^{t,i} g_{f(t,i)+1}^{t+1}
\end{flalign}
In the literature, non-recombining scenario trees are used by the discrete stochastic optimization community.
These non-recombining trees can be obtained by reducing certain recombining trees (see \cite{heitsch2003scenario} for example, or \cite{koc2012optimal} for a more recent survey  developing algorithm minimizing the  Kantorovich or Wasserstein metric between the initial tree and a subtree of the  initial tree). An example of non-recombining tree is given in the figure \ref{fig:arbre}.\\
\begin{figure}[h]
\centerline{
\includegraphics[width=6cm]{tree.png}}
\caption{Non-recombining tree}
\label{fig:arbre}
\end{figure}
On figure \ref{fig:arbre}, assuming that $X_2$ has the possible values $Y_2$, $Y_3$ at node $2$ and $3$, assuming that $X_3$ have discrete values at nodes $4, \dots, 9$ on the date $t=3$  and that values of $g(X_3)$ have the value $g_i$ at the node $i$ on the date $3$, then
\begin{flalign}
 \E[ g(X_{3}/ X_{2} = Y_3 ] = P_{3,7} g_7 + P_{3,8} g_8 + P_{3,9} g_9
\end{flalign}

\subsection{C++ API}

\subsubsection{Calculation of conditional expectation}
As explained, conditional expectations are easy to calculate with trees. The library provides an object \code{Tree} allowing to make such calculations.
\begin{lstlisting}[style=CStyle]
  Tree(const std::vector<double> &p_proba, const std::vector< std::vector< std::array<int, 2> >  > &p_connected)
\end{lstlisting}
with
\begin{itemize}
\item \code{p\_proba} a probability vector at a given date defining the probability transition between the nodes at the current date and the nodes at the next date. 
\item \code{p\_connected} the connection between the nodes and the index in the probability vector.
  \begin{center}
    \code{p\_proba[p\_connected[i][j].second]}
  \end{center}
is the probability of going from the node $i$ at the current date to the node \code{p\_connected[i][j].first} at the next date. So \code{p\_connected[i].size()} gives the number of nodes connected to the node $i$.
\end{itemize}
For regression objects, some methods are provided to calculate conditional expectations:
\begin{itemize}
\item \code{expCond} takes an Eigen array with the size equal to the number of nodes at the next date and calculates the conditional expectation of the node values of current date,
  \item \code{expCondMultiple} does the same so that several functions regress (size of the number of functions by number of nodes at the following date) and return a two-dimensional Eigen array (size of functions by number of nodes at the current date).
\end{itemize}

\subsubsection{Python API}
\label{sec:pyTree}
The python interface for tree is obtained importing the StOptTree module.
An example taking a trinomial simulator is given below
\lstinputlisting[style=PStyle,firstline=21,lastline=64]{../StOpt/test/python/unit/tree/testTree.py}

\chapter{Continuation values objects and similar ones}
\label{sec:continuation}
In the first part, we develop the different continuation objects by using regression to calculate conditional expectations.
Next, we explain the structure of the continuation object with tree to calculate the conditional expectations.
\section{Continuation values objects with regression methods}
In the first part we describe a way to store and use continuation values calculated when using regression methods to estimate conditional expectations.
In a second part, we introduce an object used to interpolate a function  both discretized on  grids for its deterministic part and estimated by regressor for its stochastic part.
The second object is similar to the first in spirit, but being dedicated to interpolation is more effective to use in simulations performed after the optimization part of a problem.\\
A third object is the continuation cut object used to approximate the concave or convex Bellman values by cuts.\\
It is used when the transition problem is solved using a LP.

\subsection{Continuation values object}
A special case is the case where the state $X^{x,t}$ in the equation \reff{eds} can be separated into two parts $X^{x,t} = (X^{x,t}_1,X^{x,t}_2)$ where
\begin{enumerate}
\item the first part is given by the following equation 
  \begin{equation}
    d X^{x,t}_{s,1} = b(t,X^{x,t}_{s,1}) ds + \sigma_(s,X^{x,t}_{s,1}) dW_s
    \label{eq:X1}
    \end{equation}
and is not controlled: the stochastic process is exogenous,
\item the second part is given by the following equation 
  \begin{equation}
    d X^{x,t}_{s,2} =  b_a(t) ds
    \label{eq:X2}
  \end{equation}
so that $ X^{x,t}_2 $ is a degenerate version of \ref{eds} without distribution, $a$ representing the control.
\end{enumerate}
This first case is encountered, for example, in the valuation of American options in finance. In this case, $X_1^{x,t}$ contains the values of the assets involved in the option
and $ X^{x,t}_2$ is for example an integer value process equal to one if the option is not exercised and to 0 if it has already been exercised.\\
Another classical case that occurs when dealing with stocks for example is a gas storage valuation. In this simple case, the process $X_1^{x,t}$ is the market value of the gas
and $X^{x,t}_2$ is the position (in volume) in the gas storage.
The library proposes to store the conditional expectation  for all states $X^{x,t}_2$.
\begin{itemize}
\item $X^{x,t}_2$ will be stored at the  points of the grid (see section \ref{gridChapter})
\item for each point $i$ of the grid the conditional expectation of a function
  $g_i(X^{x,t}_2)$  associated with the point $i$ using a regressor (see section \ref{gridChapter}) can be calculated and stored so that the continuation value $C$  is a function of $(X^{x,t}_1,X^{x,t}_2)$.
\end{itemize}
\subsubsection{C++ API}
Regarding regressions, two constructors are provided

\begin{itemize}
\item  The first is the default construction: it is used in the simulation algorithm with the \code{loadForSimulation} method to store the basis
  coefficients $\alpha_k^i$ for the grid point $i$ (see the equation \reff{regressed}),
\item The second 
\begin{lstlisting}[style=CStyle]
     ContinuationValue(const  shared_ptr< SpaceGrid > &  p_grid ,
                      const shared_ptr< BaseRegression >  & p_condExp,
                      const Eigen::ArrayXXd &p_cash) 
\end{lstlisting}
with
\begin{itemize}
\item  \code{p\_grid}  the grids associated with the deterministic control space,
\item  \code{p\_condExp} the conditional expectation operator
\item  \code{p\_cash} the function to regress as a function of the grid position (first dimension the number of simulations, second dimension the size of the grid)
\end{itemize}
This constructor builds for all point $i$  all the $\alpha_k^i$ (see equation \reff{regressed}).
\end{itemize}

The main methods provided are:
\begin{itemize}
\item a first method used in simulation allowing to load for the grid point $i$ the coefficient $\alpha_k^i$ associated with the function $g_i$,
 \begin{lstlisting}[style=CStyle]
     void loadForSimulation(const  shared_ptr< SpaceGrid > & p_grid ,
                           const shared_ptr< BaseRegression >  & p_condExp,
                           const Eigen::ArrayXXd &p_values)
 \end{lstlisting}
with
\begin{itemize}
\item \code{p\_grid}  the grid associated with the controlled deterministic space,
\item \code{p\_condExp} the conditional expectation operator,
\item \code{p\_values} the  $\alpha_k^i$ for all grid points $i$ (size the  number of basis function, the number of grid points)
\end{itemize}
 
\item  a second  method taking as input a point to be interpolated in the grid and returning the conditional expectation at the interpolated point for all simulations:

\begin{lstlisting}[style=CStyle]
     Eigen::ArrayXd getAllSimulations(const Eigen::ArrayXd &p_ptOfStock)
 \end{lstlisting}
 \item  a   method taking as input an interpolator in the grid and returning the conditional expectation for all simulations at the interpolated point  used to build the interpolator:

\begin{lstlisting}[style=CStyle]
     Eigen::ArrayXd getAllSimulations(const Interpolator   &p_interpol)
 \end{lstlisting}

\item a method taking as input a simulation number used in optimization and a point used to  interpolate in the grid and returning the conditional expectation at the interpolated point for the given simulation used in optimization.

\begin{lstlisting}[style=CStyle]
     double  getASimulation(const int &p_isim, const Eigen::ArrayXd &p_ptOfStock)
 \end{lstlisting}
 \item  a method taking as input a simulation number used in optimization and  an interpolator in the grid and returning the conditional expectation at the interpolated point used to construct the interpolator for the given simulation used in optimization:

\begin{lstlisting}[style=CStyle]
     double  getASimulation(const int &p_isim, const Interpolator   &p_interpol)
 \end{lstlisting}
 
\item a method which calculates the conditional expectation for a sample of $X^{x,t}_1$:

 \begin{lstlisting}[style=CStyle]
    double getValue(const Eigen::ArrayXd &p_ptOfStock, const Eigen::ArrayXd &p_coordinates) const
 \end{lstlisting}
where:
\begin{itemize}
\item \code{p\_ptOfStock} the point where we interpolate the conditional expectation (a realization of $X^{x,t}_2$)
\item \code{p\_coordinates} the sample of $X^{x,t}_1$ used to estimate the conditional expectation
\item and the function returns $C(X^{x,t}_1,X^{x,t}_2)$.
\end{itemize}
\end{itemize}
Below we regress an identical function for all the points of the grid (here a grid of 4  points in dimension 1):
\begin{lstlisting}[style=CStyle]
          int sizeForStock  = 4;
         // second member to regress with a stock
        ArrayXXd toRegress = ArrayXXd::Constant(p_nbSimul,sizeForStock, 1.);
        // grid for stock
        Eigen::ArrayXd lowValues(1), step(1);
        lowValues(0) = 0. ;
        step(0) = 1;
        Eigen::ArrayXi  nbStep(1);
        nbStep(0) = sizeForStock - 1;
        // grid
        shared_ptr< RegularSpaceGrid > regular = MyMakeShared<RegularSpaceGrid>(lowValues, step, nbStep);
        // conditional espectation (local basis functions)
        ArrayXi  nbMesh = ArrayXi::Constant(p_nDim, p_nbMesh);
         shared_ptr<LocalLinearRegression> localRegressor = MyMakeShared<LocalLinearRegression>(false, x, nbMesh);

        // create continuation value object
        ContinuationValue continuation(regular, localRegressor, toRegress);

        // regress with continuation value object
        ArrayXd ptStock(1) ; 
        ptStock(0) = sizeForStock / 2; // point where we regress
        // compute regression values for the current point for all the simulations
        ArrayXd regressedByContinuation = continuation.getAllSimulations(ptStock);
\end{lstlisting}

\subsubsection{Python API}
\label{subsec:pythonCont}
Here is an example of the use of the mapping
\lstinputlisting[style=PStyle]{../StOpt/test/python/unit/continuation/testContinuation.py}

\subsection{The GridAndRegressedValue object}
As explained above, when we want to interpolate a partially discretized function on a grid and by regression, a specific object can be used.
As for the continuation object, it has a \code{getValue} to estimate the function at a state with both a deterministic and a stochastic part.
\subsubsection{C++ API}
The object has five constructors and we have only described the two most commonly used:
\begin{itemize}
\item The first one
\begin{lstlisting}[style=CStyle]
   GridAndRegressedValue(const  std::shared_ptr< SpaceGrid >   &p_grid ,
                          const std::shared_ptr< BaseRegression >   &p_reg,
                          const Eigen::ArrayXXd &p_values) 

\end{lstlisting}
with
\begin{itemize}
\item  \code{p\_grid}   the grid associated with the deterministic control space,
\item  \code{p\_reg}    the regressor object
\item  \code{p\_values}  the functions at certain points of the deterministic and stochastic grid.
\end{itemize}
\item A second constructor stores only the grid and the regressor:
\begin{lstlisting}[style=CStyle]
GridAndRegressedValue(const  std::shared_ptr< SpaceGrid >   &p_grid ,
                          const std::shared_ptr< BaseRegression >   &p_reg)
\end{lstlisting}
\end{itemize}

The main methods are the following ones:
\begin{itemize}
\item 
 the main  method for calculating the function $C(X^{x,t}_{1,s},X^{x,t}_{2,s})$ value for a point $X^{x,t}_s  = (X^{x,t}_{1,s},X^{x,t}_{2,s})$ where $X^{x,t}_{2,s}$ is on the grid and $X^{x,t}_{1,s}$ is the part treated by regression.

 \begin{lstlisting}[style=CStyle]
    double getValue(const Eigen::ArrayXd &p_ptOfStock, const Eigen::ArrayXd &p_coordinates) const
 \end{lstlisting}
where:
\begin{itemize}
\item \code{p\_ptOfStock}  $X^{x,t}_{2,s}$ part of $X^{x,t}_s$
\item \code{p\_coordinates} $X^{x,t}_{1,s}$ part of $X^{x,t}_s$.
\end{itemize}
\item 
the method \code{getRegressedValues}  which allows to obtain all the regression coefficients for all points of the grid. The returned array has  a size (base number of function, number of points on the grid)
 \begin{lstlisting}[style=CStyle]
Eigen::ArrayXXd getRegressedValues() const
 \end{lstlisting}
\item the method \code{setRegressedValues} allows to store all the values of the regressed coefficients on a grid of a function  of $X^{x,t}_s  = (X^{x,t}_{1,s},X^{x,t}_{2,s})$. 
\begin{lstlisting}[style=CStyle]
void setRegressedValues(const Eigen::ArrayXXd &p_regValues)
\end{lstlisting}
where \code{p\_regValues} has  a size (number of function basis, number of points on the grid).
\end{itemize}
\subsubsection{Python API}
The python API is similar to that of the \code{ContinuationValue} object (see Section~\ref{subsec:pythonCont}).

\subsection{The continuation cut object}
\label{sec:contCutReg}
Suppose that the control problem is continuous and that the state of the system has the dynamics given by \eqref{eq:X1} et \eqref{eq:X2}.
This is the case for certain modeled storage associated with the maximization of a certain objective function.
The Bellman value associated with this problem is then concave.
For a given value of a margin  process  $X^{x,t}_{s,1}$,  the Bellman curve can be approximated by cuts (see \ref{cutBell})
\begin{figure}[h]
\centerline{
\includegraphics[width=12cm]{cutfig.png}}
\caption{Bellman cuts}
\label{cutBell}
\end{figure}
By solving a PL for a given uncertainty and state in the storage levels $\hat y_i$ in  dimension $d$, we obtain a cut
\begin{align*}
   \kappa(X^{x,t}_{s,1}, y) =&  a_0(X^{x,t}_{s,1}) + \sum_{i=1}^g a_i(X^{x,t}_{s,1}) (y_i- \hat y_i)
\end{align*}
For $s^{'} \le s$ a conditional cut can be obtained by calculating
\begin{align*}
  \theta(X^{x,t}_{s^{'},1}, y) = \E \left[a_0(X^{x,t}_{s,1}) | X^{x,t}_{s^{'},1} \right] + \sum_{i=1}^d \E \left[a_0(X^{x,t}_{s,1}) | X^{x,t}_{s^{'},1} \right] ( y_i-  \hat y_i)
\end{align*}
Using a regressor (see chapter \ref{sec::regression}) it is possible to represent each conditional cut on a basis for $j=0, \dots , d$.
\begin{align}
  \E \left[a_i(X^{x,t}_{s,1}) | X^{x,t}_{s^{'},1} \right] = \sum_{j=1}^N a_{i,j} \psi_j(X^{x,t}_{s^{'},1})
  \label{eq:coeffCut}
\end{align}
where $\psi_j$ corresponds to a basis function.\\

\subsubsection{C++ API}The first is the default construction: it is used in the simulation algorithm with the \code{loadForSimulation} method to store the database
Regarding regressions, two constructors are provided

\begin{itemize}
\item  The first is the default construction: it is used in  simulation algorithm with the \code{loadForSimulation} method to store the basis
  coefficients $a_{i,j}^k$ for the grid point $k$,
\item The second is 
\begin{lstlisting}[style=CStyle]
     ContinuationCuts(const  shared_ptr< SpaceGrid > &  p_grid ,
                      const shared_ptr< BaseRegression >  & p_condExp,
                      const Eigen::ArrayXXd &p_values) 
\end{lstlisting}
with
\begin{itemize}
\item  \code{p\_grid} the grids associated with the deterministic control space,
\item  \code{p\_condExp} the conditional expectation operator
\item  \code{p\_values} the coefficients of the cut to regress according to the position of the grid (first dimension the number of simulations by the number of components of the cut (nb storage+1), second dimension the size of the grid)
\end{itemize}
This constructor builds for all stock points the coefficients $a_{i,j}$ of the cuts \eqref{eq:coeffCut}.
Note that for a stock point $k$ with the coordinates $y^k$, the stored coefficients are $ \hat a_{0,j}^k = a_{0,j}^k - \sum_{i=1}^d a_{i,j}^k y_i^k$ and the $ \hat a_{i,j}^k = a_{i,j}^k$, $i=1,\dots d$.
The conditional cut can then be written:
\begin{align*}
  \theta(X^{x,t}_{s^{'},1}, y) =  \sum_{j=1}^N \hat a_{0,j} \psi_j(X^{x,t}_{s^{'},1})  + \sum_{i=1}^d  \sum_{j=1}^N \hat a_{i,j} \psi_j(X^{x,t}_{s^{'},1})  y_i
\end{align*}

\end{itemize}

The main methods provided are:
\begin{itemize}
\item a first method used in simulation allowing to load for the grid point $i$ the coefficient $\alpha_k^i$ associated with the function $g_i$,
 \begin{lstlisting}[style=CStyle]
     void loadForSimulation(const  shared_ptr< SpaceGrid > & p_grid ,
                           const shared_ptr< BaseRegression >  & p_condExp,
                           const  Eigen::Array<Eigen::ArrayXXd> &p_values)
 \end{lstlisting}
with
\begin{itemize}
\item \code{p\_grid} the grid associated with the controlled deterministic space,
\item \code{p\_condExp} the conditional expectation operator,
\item \code{p\_values} the $a_{i,j}$  coefficients to reconstruct the cuts: its size corresponds to the number of cutting coefficients. The $i$ element of \code{p\_values} then allows you to store 
   the coefficients $a_{i,j}$  for $j=1, \dots, N$ and all stock points.
\end{itemize}
 
\item  a second method taking as input the description of a hypercube (nb storages,2)  described by its extreme coordinates:
  \begin{itemize}
    \item  The coordinate  (i,0) corresponds to the minimum coordinate value in dimension i
    \item The coordinate  (i,1) corresponds to the maximum coordinate value in dimension i
  \end{itemize}
  
\begin{lstlisting}[style=CStyle]
     Eigen::ArrayXXd getCutsAllSimulations(const Eigen::ArrayXXd &p_hypStock) const
\end{lstlisting}
It return an array of cuts coefficients for all particles  state stored in its BaseRegression member.
\begin{itemize}
\item The first dimension corresponds to the number of cut coefficients by the number of simulations.
\item The second dimension corresponds to the number of points in the hypercube \code{p\_hypStock}.
 \end{itemize}

\item  a method to obtain an array of cuts for a given uncertainty.

\begin{lstlisting}[style=CStyle]
     Eigen::ArrayXXd getCutsASim(const Eigen::ArrayXXd &p_hypStock, const Eigen::ArrayXd &p_coordinates) const
\end{lstlisting}
where:
\begin{itemize}
\item \code{p\_hypStock} corresponds to a hypercube used to select certain stock points as before,
\item \code{p\_coordinates} corresponds to the coordinates of the uncertainty to be considered. 
\end{itemize}
It returns an array with in first dimension the cut coefficient number, the second dimension corresponds to the number of the cut (corresponding to a stock point in the hypercube).
\item a method that permits to get the coefficients calculated. 
 \begin{lstlisting}[style=CStyle]
    const Eigen::Array< Eigen::ArrayXXd, Eigen::Dynamic, 1 >   &getValues() const
 \end{lstlisting}
\end{itemize}

\subsubsection{Python API}
\label{subsec:pythonContCut}
Here is an example of the use of the mapping
\lstinputlisting[style=PStyle]{../StOpt/test/python/unit/continuation/testContinuationCut.py}


\section{Continuation objects and associated with trees}
\subsection{Continuation object}
Likewise, instead of using a regressor, a tree can be used to create a continuation object.
\subsubsection{C++ API}
As for the object \code{ContinuationValue}, two constructors are provided:
\begin{itemize}
\item A default constructor, allowing to load the grid coefficients at each node of the tree with the \code{loadForSimulation} method,
\item And the second:
  \begin{lstlisting}[style=CStyle]
    ContinuationValueTree(const  std::shared_ptr< SpaceGrid >   &p_grid,
                          const std::shared_ptr< Tree >   &p_condExp,
                          const Eigen::ArrayXXd &p_valuesNextDate)
\end{lstlisting}
with
\begin{itemize}
\item  \code{p\_grid} the grids associated with the deterministic control space,
\item  \code{p\_condExp} the tree object used to calculate the conditional expectation: by taking a few values defined at the nodes of the following date, it calculates the expected values conditional on each node at the current date.
\item  \code{p\_valuesNext} the value of the function at the following date (first dimension the number of nodes on the following date, second dimension the size of the grid)
\end{itemize}
\end{itemize}
The main methods provided are:
\begin{itemize}
\item a first method used in simulation allowing to load for the grid point $i$ the expected value of the function $g_i$ (valuesNextDate) for all the nodes in the tree  at the current date,
 \begin{lstlisting}[style=CStyle]
     void loadForSimulation(const  shared_ptr< SpaceGrid > & p_grid ,const Eigen::ArrayXXd &p_values)
 \end{lstlisting}
with
\begin{itemize}
\item \code{p\_grid} the grid associated with the controlled deterministic space,
\item \code{p\_values} the continuation values for all the nodes and stock points (size:  the number of nodes by number of grid points at the current date)
\end{itemize}
 
\item  a second  method taking as input a point to be interpolated in the grid and returning the conditional expectation at the interpolated point for all nodes:

\begin{lstlisting}[style=CStyle]
     Eigen::ArrayXd getValueAtNodes(const Eigen::ArrayXd &p_ptOfStock)
 \end{lstlisting}
\item  a method taking as input an interpolator in the grid and returning the conditional expectation for all the nodes at the interpolated point used to build the interpolator:

\begin{lstlisting}[style=CStyle]
     Eigen::ArrayXd getValueAtNodes(const Interpolator   &p_interpol)
 \end{lstlisting}

\item a method taking as input a node number used in optimization and a point used to interpolate in the grid and returning the conditional expectation at the interpolated point for the given node used in optimization.

\begin{lstlisting}[style=CStyle]
     double getValueAtANode(const int &p_node, const Eigen::ArrayXd &p_ptOfStock)
 \end{lstlisting}
 \item  a method taking as input a simulation number used in optimization and  an interpolator in the grid and returning the conditional expectation at the interpolated point used to build the interpolator for the given node used in optimization:

\begin{lstlisting}[style=CStyle]
     double  getValueAtANode(const int &p_node, const Interpolator   &p_interpol)
 \end{lstlisting}
 
\item a method which makes it possible to recover all the conditional expectations for all the nodes:

 \begin{lstlisting}[style=CStyle]
    double getValues() const
 \end{lstlisting}
\end{itemize}
\subsubsection{Python API}
Used when importing the StOptTree module, the syntax is similar to that of c++.
Follwing examples in the section \ref{sec:pyTree};
\lstinputlisting[style=PStyle,firstline=66,lastline=74]{../StOpt/test/python/unit/tree/testTree.py}
\subsection{GridTreeValues}
This object allows you to interpolate in certain grid values for a function defined at the node values and the grid values.\\
The constructor
\begin{lstlisting}[style=CStyle]
  GridTreeValue(const  std::shared_ptr< SpaceGrid >   &p_grid,
  const Eigen::ArrayXXd &p_values)
\end{lstlisting}
where:
\begin{itemize}
\item \code{p\_grid} the grids associated with the deterministic control space,
\item \code{p\_values} value to store at nodes and on grid (size : number of nodes at the current date by number of points in the grid)
\end{itemize}
The methods:
\begin{itemize}
\item
  The following is used to interpolate at a given stock point for a given node
  \begin{lstlisting}[style=CStyle]
    double getValue(const Eigen::ArrayXd &p_ptOfStock, const int & p_node) const
  \end{lstlisting}
  \begin{itemize}
\item \code{p\_ptOfStock}  corresponds to a value of  $X^{x,t}_{2,s}$ part of $X^{x,t}_s$
\item \code{p\_node} node number in the tree describing $X^{x,t}_{1,s}$
  \end{itemize}
  \item The second gives the interpolated values at all the nodes
    \begin{lstlisting}[style=CStyle]
      Eigen::ArrayXd  getValues(const Eigen::ArrayXd &p_ptOfStock) const
  \end{lstlisting}
    \subsubsection{Python API}
    Importing the StOptTree, previous constructor and methods are available.
\end{itemize}
\subsection{Continuation Cut with trees}
As for the regressor (section \ref{sec:contCutReg}), we can provide cuts during the approximation of a concave or convex function at each node of the tree.
\subsubsection{C++ API}
\begin{itemize}
\item  The first is the default construction: it is used in the simulation algorithm with the \code{loadForSimulation} method to load the values at the grid points nodes,
\item The second 
\begin{lstlisting}[style=CStyle]
     ContinuationCutsTree(const  std::shared_ptr< SpaceGrid >   &p_grid,
                         const  std::shared_ptr< Tree >   &p_condExp,
                         const  Eigen::ArrayXXd &p_values)
\end{lstlisting}
with
\begin{itemize}
\item  \code{p\_grid}  the grids associated with the controlled deterministic space,
\item  \code{p\_condExp} the conditional expectation operator for tree
\item  \code{p\_values}   the coefficients of the cut from which we take the conditional expectation depending on the grid position (first dimension the number of nodes  by the number of components of the cut (nb storage+1), second dimension the grid size)
\end{itemize}
This constructor constructs for all the stock points the coefficients of the cuts $a_i$ for $i=0, d$.
Note that for a stock point $k$ with the coordinates $y^k$, the stored coefficients are $ \hat a_{0}^k = a_{0}^k- \sum_{i=1}^d a_{i}^k y_i^k$ and the $ \hat a_{i}^k = a_{i}^k$, $i=1,\dots d$ so that a cut has an affine representation at a point $y$:  $\hat a_{0}^k + \sum_{i=1}^d \hat a_i^k y_i$. 
\end{itemize}

The main methods provided are:
\begin{itemize}
\item a first method used in simulation allowing to load for the grid point $i$ the values of cuts at the nodes.
 \begin{lstlisting}[style=CStyle]
     void loadForSimulation(const  shared_ptr< SpaceGrid > & p_grid ,
                           const shared_ptr< Tree >  & p_condExp,
                           const  const std::vector< Eigen::ArrayXXd  > &p_values)
 \end{lstlisting}
with
\begin{itemize}
\item \code{p\_grid}  the grid associated with the deterministic controlled space,
\item \code{p\_condExp} the conditional expectation operator by tree,
\item \code{p\_values} the  $a_{i}$  coefficients to reconstruct the cuts: its size corresponds to the number of cutting coefficients. Tthe element $i$ of \code{p\_values} then allows you to store 
   the coefficients $a_{i}$ for all the nodes and all the stock points.
\end{itemize}
 
\item  a second  method taking as input the description of a hypercube (nb storages,2)  described by its extreme coordinates:
  \begin{itemize}
    \item (i,0) coordinate corresponds to minimum coordinate value in dimension i
    \item (i,1) coordinate corresponds to maximum coordinate value in dimension i
  \end{itemize}
  
\begin{lstlisting}[style=CStyle]
     Eigen::ArrayXXd getCutsAllNodes(const Eigen::ArrayXXd &p_hypStock) const
\end{lstlisting}
It returns an array of cut coefficients for all nodes in the tree structure at the grid points inside the hypercube.
\begin{itemize}
\item The first dimension corresponds to the number of cuts coefficients by the number of nodes.
\item  The second dimension corresponds to the number of points in the hypercube \code{p\_hypStock}.
 \end{itemize}

\item  a method to obtain an array of cuts for a given node.

\begin{lstlisting}[style=CStyle]
     Eigen::ArrayXXd getCutsANode(const Eigen::ArrayXXd &p_hypStock, const int &p_node) const
\end{lstlisting}
where:
\begin{itemize}
\item \code{p\_hypStock} corresponds to a hypercube used to select certain stock points as before,
\item \code{p\_node} corresponds to the node number in the tree structure.
\end{itemize}
It returns an array with in the first dimension the cut coefficient number, the second dimension corresponds to the number of the cutting (corresponding to a stock point in the hypercube).
\item a method for calculating the coefficients. 
 \begin{lstlisting}[style=CStyle]
    const std::vector< Eigen::ArrayXXd>     getValues() const
 \end{lstlisting}
\end{itemize}
\subsubsection{Python API}
By importing the \code{StOptTree} module, the \code{ContinuationCutsTree} object is available in python.

\part{Solving optimization problems with dynamic programming methods}
\label{part:dynProg}
\chapter{Creating simulators}
In order to optimize the control problem,  the user must develop simulators allowing to trace some trajectories of uncertainties.
This trajectories are used during optimization or in a simulation part testing the optimal control.
\section{Regression methods simulators}
In the following, we assume that we have developed a Simulator generating Monte Carlo simulations at different optimizations dates.
In order to use the different frameworks developed in the following, we assume that the simulator is derived from the abstract class
\code{SimulatorDPBase}.
\lstinputlisting[style=CStyle]{../StOpt/StOpt/dp/SimulatorDPBase.h}

Suppose that the Simulator is a Black Scholes simulator for the assets $P$, simulating $M$ the Monte Carlo simulations, on the dates $N+1$  $t_0,\dots,t_N$,
the Markov state for the particle $j$, the date $t_i$, the Monte Carlo simulation $k$ and the asset $p$  is $X_{p,i}^k$ and 
we give below the meaning of the different methods of \code{SimulatorDPBase}:
\begin{itemize}
\item the \code{getParticle} method gives at the current optimization/simulation date $t_i$  the Markov states $X_{p,i}^k$ in a matrix $A$ such that $A(p,k)= X_{p,i}^k$,
\item  the \code{stepForward} method  is used while simulating the assets evolution in forward: a step forward is realized from $t_i$ to $t_{i+1}$ and  Brownian motions used for the assets are 
updated at the new time step,
\item  the \code{stepBackward} method is used for the simulation of the asset from the last date to time 0. This method is used during an asset optimization by Dynamic Programming,
\item  the method \code{stepForwardAndGetParticles}: second and first method in one call,
\item  the method \code{stepBackwardAndGetParticles}: third and first method in one call,
\item  the method \code{getDimension} returns the number of assets,
\item  the method \code{getNbStep} returns the number of step ($N$),
\item  the \code method{getStep} retu+++
rns the number of steps $t_{i+1}-t_i$ at the current time $t_i$,
\item  the method \code{getNbSimul}  returns $M$.
\item  the method \code{getActuStep} returns the actualization factor over a time step
\item  the method\code{getActu} returns a discount factor at date ``0''.
\end{itemize}
\section{Simulators for trees}
In order to develop solvers using tree-based methods, the user has to  create a simulator derived from the  \code{SimulatorDPBaseTree} class.
This simulator reads at each date  in a geners archive, the values of the uncertainties at the nodes and the probability transition.
It  is used deterministically in backward mode: the values of the nodes are all explored sequentially.
In forward mode, it allows to sample discrete values of the state through the tree.
\lstinputlisting[style=CStyle]{../StOpt/StOpt/dp/SimulatorDPBaseTree.h}
  When designing their tree, the user must call the based simulator constructor by providing a geners archive giving
  \begin{itemize}
  \item An Eigen \code{ArrayXd} of the set of dates (size $N$) associated with the tree.
  \item A vector of probabilities \code{P} at each of the first $N-1$ dates.
  \item A vector of vector of pair of int at each of the first $N-1$ dates. Such a vector \code{v}, at a given date, has the size equal to the number of nodes in the tree at this date. For a node $i$, \code{v[i]} is the vector of arrival nodes number and probability index in \code{P}. Then \code{v[i][j].first} is the number of  a node at next date connected to node $i$ at current date. The transition probability is given by \code{P[v[i][j].second]}.
  \end{itemize}
In the geners archive, storage is carried out as in the \code{dump} function in the file \code{TrinomialTreeOUSimulator.cpp} storing the connection matrix probabilities of a trinomial tree.
  
  \lstinputlisting[style=CStyle,firstline=175,lastline=194]{../StOpt/test/c++/tools/simulators/TrinomialTreeOUSimulator.cpp}

 The different methods that the user has to provide are
\begin{itemize}
\item  the \code{stepForward} method  is used when simulating the evolution of forward assets: a step forward is made from $t_i$ to $t_{i+1}$ and samples are generated to give discrete uncertainties in the tree.
\item  the \code{stepBackward} method is used when optimizing an asset from the last date to time 0 by Dynamic Programming. The structure of the tree should be updated (probabilities, connection between nodes)
\item  the \code{getNbSimul} giving the number of samples used in forward mode,
\item the \code{getValueAssociatedToNode} method taking the number of a node and giving back the state associated with this node,
  \item the \code{getNodeAssociatedToSim} method giving for a trajectory number in forward mode, the number of the node visited at current date.
 \end{itemize}


An example of simulator for HJM model with trinomial tree for the OU process is \code{MeanRevertingSimulatorTree}.


\chapter{Using conditional expectation to solve simple problems}
In this chapter, we give some examples for valuing an American option. This use of conditional expectation operators can be extended to many stochastic problems using these previously developed objects.
\section{American option by regression}
\subsection{The American option valuing by Longstaff--Schwartz}
Suppose in this example that the payoff of the American option is given by $g$ and that the interest rate is 0. The value of the option is given by
\begin{equation}
\label{StoppingTime}
P_t = {\rm esssup}_{\tau \in {\cal T}_{[t,T]}}\E(g(\tau,X_\tau)~|~{ \cal F}_t) \;\;\mbox{ for } \;t\le T\;\;\mathbb{P}-\mbox{a.s.}\;,
\end{equation}
where   $\Tc_{[t,T]}$ denotes the set of stopping times with values in $[t,T]$.\\

We recall the classic Longstaff--Schwartz Algorithm~\ref{Longstaff} estimating the empirical conditional expectation using the regression estimation seen previously.
\begin{algorithm}[h]
\caption{{ Algorithm with regression  [optimal exercise time estimation]}
\label{Longstaff}}
\begin{algorithmic}
\State  Initialization: 
\State Set  $\hat \tau^{1,\pi,(j)}_\kappa:=T$, $j\le N$
\State Backward induction:
\For{ $i=\kappa-1$ to $0$}
\State  set    $\hat\tau^{1,\pi}_i:=t_i{\bf 1}_{A^1_i}+ \hat \tau^{1,\pi}_{i+ 1}{\bf
1}_{(A^1_i)^c}$ where  $A^1_i:=\{g(t_i,  X_{t_i})\ge \hat \E[g(\hat \tau^{1,\pi}_{i+
1},X_{\hat \tau^{1,\pi}_{i+1}})~|~{ \cal F}_{t_i}]\}$.
\EndFor
\State  Price estimator at $0$:   $\hat P^{1,\pi}_{0}:=\hat \E[g(\hat \tau^{1,\pi}_{0},  X_{\hat \tau^{1,\pi}_{0}})]$.
\end{algorithmic}
\end{algorithm}
\subsubsection{American option by regression with the C++ API}
We value in the algorithm below an American option using a simulator \code{p\_sim}, a regressor \code{p\_regressor}, a payoff function \code{p\_payoff}:
\begin{lstlisting}[style=CStyle]
    double step = p_sim.getStep(); // time step increment
    // asset simulated under the neutral risk probability: get the trend of  the first asset to get the interest rate
    double expRate = exp(-step * p_sim.getMu()(0));
    // Terminal pay off
    VectorXd Cash(p_payOff(p_sim.getParticles()));
    for (int iStep = 0; iStep < p_sim.getNbStep(); ++iStep)
    {
        shared_ptr<ArrayXXd> asset(new ArrayXXd(p_sim.stepBackwardAndGetParticles())); // asset = Markov state
        VectorXd payOffLoc = p_payOff(*asset); // pay off 
        // update conditional expectation operator for current Markov state
        p_regressor.updateSimulations(((iStep == (p_sim.getNbStep() - 1)) ? true : false), asset);
        // conditional  expectation
        VectorXd condEspec = p_regressor.getAllSimulations(Cash) * expRate;
        // arbitrage between pay off and cash delivered after
        Cash = (condEspec.array() < payOffLoc.array()).select(payOffLoc, Cash * expRate);
    }
    return Cash.mean();
\end{lstlisting}
\subsubsection{American option with the Python API}
Using the python API the American resolution is given below:
\lstinputlisting[style=PStyle]{../StOpt/test/python/functional/utils/americanOption.py}

\section{American options by tree}
Using trees, American options are solved  calculating the Bellman values at each date instead of valuing them as expectation of payoff at optimal stopping time.
\begin{algorithm}[h]
\caption{{ Algorithm with tree: Bellman value  (0 interest rate)}
\label{AmrVal}}
\begin{algorithmic}
\State  Initialization: 
\State Set  $P^j := g(X_{T}^j)$, $j\le  N(\kappa)$  \Comment{Number of node at last date}
\State Backward induction:
\For{ $i=\kappa-1$ to $0$}
\State  set    $ P^j = \max [ \E[ P ~|~ X^j_{t_i}], g(X_{t_i}^j]$, $j \le N(i)$
\EndFor
\State  Price estimator at $0$:   $P^0$.
\end{algorithmic}
\end{algorithm}

\subsection{The American option by tree}
\lstinputlisting[style=CStyle, firstline=87,lastline=121]{../StOpt/test/c++/functional/testAmericanOptionTree.cpp}
\subsection{Python API}
\lstinputlisting[style=CStyle, firstline=55, lastline =87]{../StOpt/test/python/functional/testAmericanOptionTree.py}

\chapter{Using the general framework to manage stock problems }
\label{SecParal}
In this chapter the state is  separated into three parts $X^{x,t} = (X^{x,t}_1,X^{x,t}_2, I_t)$. $(X^{x,t}_1,X^{x,t}_2)$, which corresponds to the special case of chapter \ref{sec:continuation} where  $X^{x,t}_1$ is not controlled and $X^{x,t}_2$ is  controlled.
Two cases can be tackled:
\begin{itemize}
\item the first case corresponds to the case where  $X^{x,t}_2$ is deterministic  (think of storage management),
\item the second case corresponds to the case where $X^{x,t}_2$ is stochastic  (think of portfolio optimization).
\end{itemize}
 $I_t$ takes integers values and is here to describe some finite discrete regimes (to deal with some switching problems).
A general framework is available to solve this type of problem. \\
First of all, the second part $X^{x,t}_2$ is discretized on a grid as explained in chapter \ref{sec:continuation}.
\begin{itemize}
\item Either a full grid is used for $X^{x,t}_2$ and two types of sequential or parallel resolutions be can considered:
  \begin{itemize}
  \item a resolution can be obtained sequentially or a parallelization with MPI on the computations can be carried out (acceleration but no increase in size). This approach can be used for small dimension problems.
   \item  a resolution can be obtained with a parallelization by the MPI framework by spreading the work to be done on the  points of the grid, and by distributing the data between processors (acceleration and dimensioning). We will call this parallelization technique a ``distribution'' technique. This approach is necessary to tackle very large optimization problems where the overall solution cannot be stored in the memory of a single processor.
 \end{itemize}
\item or the grid  for $X^{x,t}_2$ is not full (therefore sparse) and only a parallelization by thread and MPI can be carried out on the calculations  (acceleration and no increase in size). With sparse grids, only the deterministic  $X^{x,t}_2$ case  is treated.
\end{itemize}
In the case of the MPI parallelization technique distributing task and the data (full grids only),  \cite{makassikis2008large} and \cite{vialle2008stochastic} are used.
Suppose that the grid is the same at each time step (only here to facilitate the case), and that we have 4  processors (figure \ref{Parallfig}) then:
\begin{itemize}
  \item at the last time step, the final values at each point of each simulation are calculated (each processor calculates the values for its own  grid points),
\item in the previous time step, from a grid point, specific to a processor, we are able to locate the grid points reached in the next time step by all the commands,
\item on figure \ref{Parallfig}, we give the points belonging to other processors wich can be reached from points belonging to processor 3,
\item certain MPI communications are carried out by bringing back the data (values calculated at the previous processed time step) necessary for processor 3 to be able to update the calculated value by dynamic programming at the moment for all the points belonging to processor 3,
\item all communications between all processors are done together.
\end{itemize}

\begin{figure}[h]
\centering
\includegraphics[width=8cm]{Paral.png}
\caption{Data to send to processor  3}
\label{Parallfig}
\end{figure}
The overall status of the problem is stored in the \href{run:../StOpt/StOpt/core/utils/StateWithStocks.h}{\code{StateWithStocks}} object.\\

\section{General requirement for the business object}
In order to use the framework, the developer must describe the problem he wants to solve in one step from a state $X^{x,t}$.
This business object must offer common methods and it is derived from \code{OptimizerBase}.
\lstinputlisting[style=CStyle]{../StOpt/StOpt/dp/OptimizerBase.h}
We detail all the methods to be implemented for all the resolution methods (with or without regressions).
\begin{itemize}
\item the \code{getNbRegime} makes it possible to obtain the number of regimes of the problem: for example, in switching problems, when there is a switching cost, the working regime has to be incorporated in the state. Another example is the case of the conditional delta to calculate for an asset: two regimes can be used: one to calculate the value of the asset and the second to calculate the $\Delta$. This number of regimes can depend on time: in this case for a current resolution date $t$ the \code{getNbRegime} method sends the number of regimes at the very beginning of the time step (in $t^{-}$) such such that a switch to a new regime can take place in $t^{+}$.
\item the \code{getSimulator} method is used to retrieve the simulator giving the Monte Carlo simulations,
\item the \code{getSimuFuncSize} method is used in simulation to define the number of functions to follow in the simulation part. For example in a stochastic target problem where the target is a given wealth with a given probability, one may want to follow the evolution of the probability at each time step and of the wealth obtained in trading. In this case the \code{getSimuFuncSize} returns $2$.
\item the \code{getCone} method is only relevant if the MPI framework with distribution is used. As argument it takes a vector of  size the dimension of the grid. Each component of the vector is an array containing
the minimum and maximum coordinate values of the points of the current grid defining an hyper cube $H1$. It returns for each dimension, the min and max coordinates of the hyper cube $H2$ containing the points which can be reached by applying a command from a point of the grid in $H1$.
\item the \code{getDimensionToSplit} method is used to define in the MPI framework with distribution the directions to be divided for the solution on the processors. For each dimension, it returns a Boolean where \code{true} means that the direction is a candidate for splitting.
\item the \code{stepSimulateControl} method is used after the optimization using the optimal controls calculated in the optimization part. From a state \code{p\_state} (storing the $X^{x,t}$), the calculated optimal control in optimization \code{p\_control}, the values of optimal functions along the current path are stored in \code{p\_phiInOut}. The state \code{p\_state} is updated at the end of the call function.
\end{itemize}


\hspace{1cm}
In the first part, we present the framework of the problems where the conditional expectation is calculated by regression (case where $X^{t,x}_2$  is not controlled).
Next, we develop the framework that does not use regression for the conditional expectation calculations. All conditional expectations are calculated using exogenous particles and interpolation.
This will generally be the case for portfolio optimization.

\section{Solving the problem using conditional expectation calculated by regressions}
In this part, we assume that $X^{x,t}_2$ is controlled and deterministic so that regression methods can be used.
\subsection{Requirement to use the framework }
The \code{OptimizerBaseInterp} is an optimizer class common to all regression methods used by dynamic programming for stocks problems.
We detail the methods of \code{OptimizerBaseInterp} which is a derived from \code{OptimizerBase}. Only one method is added:
\begin{itemize}
\item the \code{stepSimulateControl} method is used after optimization using the optimal controls calculated in the optimization part. From a state \code{p\_state} (storing the $X^{x,t}$), the calculated optimal control  
in the \code{p\_control} optimization, the values of the optimal functions along the current path are stored in \code{p\_phiInOut}. The state \code{p\_state}  is updated at the end of the call function.
\end{itemize}

\subsection{Classical regression}
By classical regression, we mean regression problems with storages where the optimal command is calculated on one time step and estimated by testing all
possible discretized commands.\\ 
In order to use the framework with regression for conditional expectation, a business object describing  the business at a time step from a state is derived from \code{OptimizerDPBase} itself derived from \code{OptimizerBaseInterp}.
\lstinputlisting[style=CStyle]{../StOpt/StOpt/dp/OptimizerDPBase.h}
We detail the different methods derived from \code{OptimizerDPBase} to implement in addition to the  \code{OptimizerBaseInterp} methods:
\begin{itemize}
\item the \code{stepOptimize} method is used in optimization. We want to calculate the optimal value at the current $t_i$ at a grid point \code{p\_stock} using  a \code{p\_grid} grid at the following date $t_{i+1}$,
  the continuation values for all the \code{p\_condEsp} regimes allowing to calculate the conditional expectation of the optimal value function calculated in the previous one
  treated time step $t_{i+1}$.
  From a grid point \code{p\_stock} it calculates the function values and the optimal controls. It returns a  pair where the
  \begin{itemize}
  \item the first element  is a matrix (first dimension is the number of simulations, the second dimension the number of regimes) giving the value of the function,
  \item the second element is a matrix (the first dimension is the number of simulations, the second dimension the number of controls) giving the optimal control.
  \end{itemize}
\item the \code{stepSimulate} method is used after the optimization using the continuation values calculated in the optimization part. From a \code{p\_state} state (storing the $X^{x,t}$), the calculated continuation values 
  in optimization \code{p\_continuation}, the optimal functions values along the current path are stored in \code{p\_phiInOut}.
\end{itemize}
In the case of \cite{warin2012gas} gas storage, the storage holder can inject gas from the grid into the storage (by paying the market price) or withdraw gas from the storage on the grid (by receiving the market price). 
In this case the Optimize object  is given in the file \href{run:../StOpt/test/c++/tools/dp/OptimizeGasStorage.h}{\code{OptimizeGasStorage.h}}. You can take a look at the implementation of the \code{getCone} method.
\subsubsection{The framework in optimization with classical regressions}
\label{subsec:framework}
Once an Optimizer is derived for the project, and assuming a full grid is used for inventory discretization, the framework provides a \href{run:../StOpt/StOpt/dp/TransitionStepRegressionDPDist.h}{\code{TransitionStepRegressionDPDist}} object in MPI which allows to solve the
optimization problem with data distribution over a time step with the following constructor:
\begin{lstlisting}[style=CStyle]
    TransitionStepRegressionDPDist(const  shared_ptr<FullGrid> &p_pGridCurrent,
                                  const  shared_ptr<FullGrid> &p_pGridPrevious,
                                  const  shared_ptr<OptimizerDPBase > &p_pOptimize)
\end{lstlisting}
with
\begin{itemize}
\item \code{p\_pGridCurrent} is the grid at the current time step ($t_i$),
\item \code{p\_pGridPrevious} is the grid at the previously processed time step ($t_{i+1}$),
\item \code{p\_pOptimize} the optimizer object
\end{itemize}
\begin{Remark}
  A similar object is available without the MPI distribution framework \href{run:../StOpt/StOpt/dp/TransitionStepRegressionDP.h}{\code{TransitionStepRegressionDP}} with always the activation of parallelization with threads and MPI on calculations on the full points grid.
\end{Remark}
\begin{Remark}
  In the case of sparse grids with only parallelization on the calculations (threads and MPI) \href{run:../StOpt/StOpt/dp/TransitionStepRegressionDPSparse.h}{\code{TransitionStepRegressionDPSparse}}
  object can be used.
  
\end{Remark}
 The main method is 
\begin{lstlisting}[style=CStyle]
    std::vector< shared_ptr< Eigen::ArrayXXd > > OneStep(const std::vector< shared_ptr< Eigen::ArrayXXd > > &p_phiIn,
            const shared_ptr< BaseRegression>  &p_condExp)
\end{lstlisting}
with
\begin{itemize}
\item  \code{p\_phiIn} the vector (its size corresponds to the number of regimes) of the matrix of optimal values calculated at the previous time iteration for each regime. Each matrix is a number of simulations per matrix of number of stock points matrix.
\item \code{p\_condExp} the conditional expectation operator,
\end{itemize}
returning a pair:
\begin{itemize}
\item The first element is a vector of  matrix  with new optimal values at the current time step  (each element of the vector corresponds to a regime and each matrix is a number of simulations per matrix of number of stock points).
\item The second element is vector of  matrix with new optimal controls at the current time step (each element of the vector corresponds to a control and each matrix is a number of simulations per number of stock points matrix).
\end{itemize}
\begin{Remark}
  All \code{TransitionStepRegressionDP} derive from a \code{TransitionStepRegressionBase} object having a pure virtual \code{OneStep} method.
\end{Remark}
A second method is provided permitting to dump the continuation values of the problem and the optimal control at each time step:
\begin{lstlisting}[style=CStyle]
    void dumpContinuationValues(std::shared_ptr<gs::BinaryFileArchive> p_ar , const std::string &p_name, const int &p_iStep,
                                const std::vector< std::shared_ptr< Eigen::ArrayXXd > > &p_phiInPrev,
                                const std::vector< std::shared_ptr< Eigen::ArrayXXd > >   &p_control,
                                const  std::shared_ptr<BaseRegression>    &p_condExp,
                                const bool &p_bOneFile) const
\end{lstlisting}
with:
\begin{itemize}
\item  \code{p\_ar} is the archive where the controls and solutions are dumped,
\item  \code{p\_name} is a base name used in the archive to store the solution and the control,
\item  \code{p\_phiInPrev} is the previous time step solution used to calculate the continuation values that are stored,
\item  \code{p\_control} stores the optimal controls calculated at the current time step,
\item  \code{p\_condExp} is the conditional expectation object allowing to calculate the conditional expectation of the functions defined at the previous time step processed \code{p\_phiInPrev} and allowing to store a representation of the optimal control.
 \item \code{p\_bOneFile} is set if the continuation and optimal controls calculated by each processor are flushed to a single file. Otherwise, the continuation and optimal controls calculated by each processor are flushed to different files (one by processor). If the problem results in optimal continuation and control values on the global grid that can be stored in the memory of the computate node, it may be more interesting to dump the continuation/control values to a file for policy simulation optimal.
\end{itemize}
\begin{Remark}
 As for the \code{TransitionStepRegressionDP} object and the \code{TransitionStepRegressionDPSparse} object, their \code{dumpContinuationValues} does not need an argument \code{p\_bOneFile}: the optimal controls are obviously stored in a single file.
\end{Remark}
Here we give a simple example of temporal resolution using this method when MPI data distribution is used
\lstinputlisting[style=CStyle]{../StOpt/test/c++/tools/dp/DynamicProgrammingByRegressionDist.cpp}
An example without data distribution can be found in the file \href{run:../StOpt/test/c++/tools/dp/DynamicProgrammingByRegression.cpp}{\code{DynamicProgrammingByRegression.cpp}}.
We finally give an array with the different \code{TransitionStepRegression} objects to use depending on the type of parallelization used.
\begin{table}[h!]
  \caption {Which object \code{TransitionStepRegression} to use depending on the grid used and the type of parallelization used.}
  \scalebox{0.8}{
  \begin{tabular}{|c|c|c|}
    \hline
    &   Full grid   & Sparse grid \\ \hline
    Sequential                     &   \code{TransitionStepRegressionDP}          &  \code{TransitionStepRegressionDPSparse}       \\   \hline
    Parallelization on calculations&   \code{TransitionStepRegressionDP}          &  \code{TransitionStepRegressionDPSparse}        \\                                     
    threads and MPI                &            &                                                  \\  \hline
    Distribution of calculations &    \code{TransitionStepRegressionDPDist}       &  Not available     \\   
    and data                     &    &  \\  \hline
  \end{tabular}
  }
 \end{table}


\subsubsection {The framework in simulation with classical regressions}
\label{subsec::simulation}
Once the optimization is done, the continuation values are saved in a file (or in some files) at each time step.
In order to simulate the optimal policy, we can use the previously calculated continuation values (see chapter \ref{sec:continuation}) or we can use the optimal controls
calculated in optimization. In continuous optimization, the use of control is more efficient in terms of computational cost. When the control is discrete, the interpolation of the controls can lead to inadmissible controls and the simulation with the value function is more precise.\\
When simulating optimal control, two cases can occur:
\begin{itemize}
\item 
In most cases (small dimension case), the optimal control or optimal function value can be stored in the compute node memory and the function values and controls are stored in a single file. In this case, an optimum control simulation can be easily performed by distributing the Monte Carlo simulations on the available compute nodes: this can be done using the \code{SimulateStepRegression} or
\code{SimulateStepRegressionControl} objects at each time step of the simulation.
\item When it comes to very large problems, optimization is achieved by distributing the data across the processors and it is impossible to store the optimal command on a node.
 In this case, the optimal controls and the optimal solutions are stored in the memory of the node which was used to calculate them in optimization.
 The simulations are reorganized at each time step and gathered so as to occupy the same part of the global grid. Each processor will then get from the other processors a version of the optimal control or solution it needs. This methodology is used in the \code{SimulateStepRegressionDist} and \code{SimulateStepRegressionControlDist} objects.
 \end{itemize}
We detail the simulations objects using the optimal function value calculated in optimization and the optimal control for the case of very large problems.
\begin{itemize}
\item \underline{Simulation step using the value function calculated in optimization}: \\
  
In order to simulate one step of the optimal policy, an object \href{run:../StOpt/StOpt/dp/SimulateStepRegressionDist.h} {\code{SimulateStepRegressionDist}} is provided with constructor
\begin{lstlisting}[style=CStyle]
   SimulateStepRegressionDist(gs::BinaryFileArchive &p_ar,  const int &p_iStep,  const std::string &p_nameCont,
                              const   shared_ptr<FullGrid> &p_pGridFollowing, const  shared_ptr<OptimizerDPBase > &p_pOptimize,
                              const bool &p_bOneFile)
\end{lstlisting}
where
\begin{itemize}
\item \code{p\_ar} is the binary archive where the continuation values are stored,
\item \code{p\_iStep} is the number associated with the current time step (0 at the start date of the simulation, the number is increased by one at each simulated time step ),
\item \code{p\_nameCont} is the base name for continuation values,
\item \code{p\_GridFollowing} is the grid at the next time step (\code{p\_iStep+1}),
\item \code{p\_Optimize} the Optimizer describing the passage from one time step to the next,
\item \code{p\_OneFile} equal to \code{true} if only one archive is used to store continuation values.
\end{itemize}
\begin{Remark}
A version without data distribution but with multithreaded and with possible MPI on calculations is available with the object \href{run:../StOpt/StOpt/dp/SimulateStepRegression.h} {\code{SimulateStepRegression}}. The \code{p\_OneFile} argument is omitted during construction.
\end{Remark}
This object implements the method \code{oneStep}
\begin{lstlisting}[style=CStyle]
void oneStep(std::vector<StateWithStocks > &p_statevector , Eigen::ArrayXXd  &p_phiInOut)
\end{lstlisting}
where:
\begin{itemize}
\item \code{p\_statevector} stores the states of all simulations: this state is updated by applying the optimal command,
\item \code{p\_phiInOut} stores the gain/cost functions for all the simulations: it is updated by the function call. The size of the array is $(nb, nbSimul)$ where $nb$  is given by the \code{getSimuFuncSize} method of the optimizer and $ nbSimul $ the number of Monte Carlo simulations.
\end{itemize}

An example of using this method to simulate an optimal policy with distribution is given below:
\lstinputlisting[style=CStyle]{../StOpt/test/c++/tools/dp/SimulateRegressionDist.h}
The version of the previous example using a single archive storing the control/solution is given in the \href{run:../StOpt/test/c++/tools/dp/SimulateRegression.h}{\code{SimulateRegression.h}} file.

\item \underline{Simulation step using the optimal controls  calculated in optimization}:\\
  
  \begin{lstlisting}[style=CStyle]
    SimulateStepRegressionControlDist(gs::BinaryFileArchive &p_ar,  const int &p_iStep,  const std::string &p_nameCont,
                                     const   std::shared_ptr<FullGrid> &p_pGridCurrent,
                                     const   std::shared_ptr<FullGrid> &p_pGridFollowing,
                                     const  std::shared_ptr<OptimizerDPBase > &p_pOptimize,
                                     const bool &p_bOneFile);

  \end{lstlisting}
  where
\begin{itemize}
\item \code{p\_ar} is the binary archive where the continuation values are stored,
\item \code{p\_iStep} is the number associated with the current time step (0 at the start date of simulation, the number is increased by one at each simulated time step ),
\item \code{p\_nameCont} is the base name of the control values,
\item \code{p\_GridCurrent} is the grid at the current time step (\code{p\_iStep}),
\item \code{p\_GridFollowing} is the grid at the next time step (\code{p\_iStep+1}),
\item \code{p\_Optimize} is the Optimizer describing the passage from one time step to the next,
\item \code{p\_OneFile} is equal to \code{true} if only one archive is used to store continuation values.
\end{itemize}
\begin{Remark}
A version in which a single archive storing the control/solution is used is available with the object \href{run:../StOpt/StOpt/dp/SimulateStepRegressionControl.h} {\code{SimulateStepRegressionControl}}
\end{Remark}
This object implements the method \code{oneStep}
\begin{lstlisting}[style=CStyle]
void oneStep(std::vector<StateWithStocks > &p_statevector , Eigen::ArrayXd  &p_phiInOut)
\end{lstlisting}
where:
\begin{itemize}
\item \code{p\_statevector} stores the state for all simulations: this state is updated by applying optimal commands,
\item \code{p\_phiInOut} stores the gain/cost functions for all simulations: it is updated by the function call. The size of the array is $(nb, nbSimul)$ where $nb$  is given by the \code{getSimuFuncSize} method of the optimizer and $ nbSimul $ the number of Monte Carlo simulations.
\end{itemize}

An example of using this method to simulate an optimal policy with distribution is given below:
\lstinputlisting[style=CStyle]{../StOpt/test/c++/tools/dp/SimulateRegressionControlDist.h}
The version of the previous example using a single archive storing the control/solution is given in the \href{run:../StOpt/test/c++/tools/dp/SimulateRegressionControl.h}{\code{SimulateRegressionControl.h}} file.

\end{itemize}
In the table below, we indicate which simulation object should be used at each time step depending on the \code{TransitionStepRegressionDP} object used in optimization.

\begin{sidewaystable}
 \centering
  %\label{tabOptSim}
  \caption{ Which simulation object to use depending on the TransitionStepRegression object used.}
    \scalebox{0.6}{
  \begin{tabular}{|c|c|c|c|c|}
    \hline
                                       &  \code{TransitionStepRegressionDP} & \code{TransitionStepRegressionDPDist} &  \code{TransitionStepRegressionDPDist} &  \code{TransitionStepRegressionDPSparse} \\
                                       &                                  &   \code{bOneFile = true} &     \code{bOneFile = false} &       \\   \hline
  \code{SimulateStepRegression}             &   Yes                            &     Yes  &   No  &    Yes   \\   \hline
  \code{SimulateStepRegressionControl}       &   Yes                            &     Yes  &   No  &  Yes   \\   \hline
  \code{SimulateStepRegressionDist}        &   No                             &     Yes  &   Yes &  No \\   \hline
  \code{SimulateStepRegressionControlDist} &   No                             &     Yes  &   Yes &  No   \\ \hline
  \end{tabular}
   }
\end{sidewaystable}
\clearpage
\subsection{Regressions and cuts for continuous linear transition problems with certain characteristics of concavity and convexity}
\label{sec:withCuts}
During the optimization for example a storage, one can want to solve the transition problem on certain time steps by supposing that the uncertainties are known.
The Bellman values for a given uncertainty are then concave compared to the storage when one tries to maximize certain gains for example.
When the problem is continuous linear, we can use bender cuts to approximate the Bellman value with respect to the storage level as in the SDDP method \ref{chap:SDDP}.
To use this cuts a business object using an LP solver must be created. This business object is derived from \code{OptimizerDPCutBase} itself derived from \code{OptimizerBaseInterp}.
\lstinputlisting[style=CStyle]{../StOpt/StOpt/dp/OptimizerDPCutBase.h}
We detail the different methods to implement in addition to the \code{OptimizerBaseInterp} methods:
\begin{itemize}
\item the \code{stepOptimize} method is used in optimization.  We want to calculate the optimal value  and the corresponding sensibilities with respect to the stocks at current $t_i$ at a grid point \code{p\_stock} using  a grid \code{p\_grid} at the next date $t_{i+1}$,
  the continuation cuts values  for all regimes \code{p\_condEsp} permitting to calculate an upper estimation  (when maximizing) of  conditional expectation of the optimal values  using some optimization  calculated at the previously
  treated time step $t_{i+1}$.
  From a grid point \code{p\_stock} it calculates the function values and the corresponding sensibilities. It returns  a matrix (first dimension is the number of simulations by the number of cuts components (number of storage +1), second dimension  the number of regimes) giving the function value and sensibilities.
\item the \code{stepSimulate} method  is used after optimization using the continuation cuts values   calculated in the optimization part. From a state \code{p\_state} (storing the $X^{x,t}$), the continuation cuts values  calculated
  in optimization \code{p\_continuation}, the optimal  cash flows  along the current trajectory are stored in \code{p\_phiInOut}.
\end{itemize}
In the case of gas storage, the Optimize object is given in the \href{run:../StOpt/test/c++/tools/dp/OptimizeGasStorageCut.h}{\code{OptimizeGasStorageCut.h}} file.
\subsubsection{The framework in optimization using certain cutting methods}
\label{subsec:frameworkCut}
Once an Optimizer object describing the business problem to be solved with cuts is created for the project, and assuming that a full grid is used for the discretization of the stock, the framework provides a \href{run:../StOpt/StOpt/dp/TransitionStepRegressionDPCutDist.h}{\code{TransitionStepRegressionDPCutDist}} object in MPI which solves the optimization problem with data adistribution over a time step with the following constructor:
\begin{lstlisting}[style=CStyle]
    TransitionStepRegressionDPCutDist(const  shared_ptr<FullGrid> &p_pGridCurrent,
                                  const  shared_ptr<FullGrid> &p_pGridPrevious,
                                  const  shared_ptr<OptimizerDPCutBase > &p_pOptimize):
\end{lstlisting}
with
\begin{itemize}
\item \code{p\_pGridCurrent} is the grid at the current time step ($t_i$),
\item \code{p\_pGridPrevious} is the grid at the previously processed time step ($t_{i+1}$),
\item \code{p\_pOptimize} the optimizer object
\end{itemize}
The construction is very similar to the classical regression methods using only the discretization by command. 
\begin{Remark}
  A similar object is available without the MPI distribution framework \href{run:../StOpt/StOpt/dp/TransitionStepRegressionDPCut.h}{\code{TransitionStepRegressionDPCut}} with always the activation of parallelization with threads and MPI on calculations on the full grid points.
\end{Remark}
The main method is 
\begin{lstlisting}[style=CStyle]
    std::vector< shared_ptr< Eigen::ArrayXXd > > OneStep(const std::vector< shared_ptr< Eigen::ArrayXXd > > &p_phiIn,
            const shared_ptr< BaseRegression>  &p_condExp)
\end{lstlisting}
with
\begin{itemize}
\item  \code{p\_phiIn} the vector (its size corresponds to the number of regimes) of the matrix of optimal values and sensitivities calculated at the previous time iteration for each regime. Each matrix has a number of rows equal to the number of simulations by the number of stock plus one. The number of columns is equal to the number of stock points on the grid.
In the row, the number of simulations by the number of stock plus one value is stored as follows:
  \begin{itemize}
  \item The first values (number of simulations : $NS$) correspond to the optimal Bellman values at a given stock point,
    \item The  $NS$ values following corresponds to sensitivities $ \frac{ \partial V}{\partial S_1} $ at first storage
    \item The  $NS$ values following corresponds to sensitivities at the second storage...
    \item $\dots$
    \end{itemize}
\item \code{p\_condExp} the conditional expectation operator,
\end{itemize}
returning a vector of  matrix with new optimal values and sensitivities to the current time step (each element of the vector corresponds to a regime and each matrix has a size equal to (number of simulations by (the number of storage plus one))  by the number of stock points). The structure of the output is then similar to the \code{p\_phiIn}  input.\\
A second method is provided allowing to dump the continuation values and  cuts of the problem and the optimal control at each time step:
\begin{lstlisting}[style=CStyle]
    void dumpContinuationCutsValues(std::shared_ptr<gs::BinaryFileArchive> p_ar , const std::string &p_name, const int &p_iStep,
                                const std::vector< std::shared_ptr< Eigen::ArrayXXd > > &p_phiInPrev,
                                const  std::shared_ptr<BaseRegression>    &p_condExp,
                                const bool &p_bOneFile) const
\end{lstlisting}
with:
\begin{itemize}
\item  \code{p\_ar} is the archive where controls and solutions are dumped,
\item  \code{p\_name} is a base name used in the archive to store the solution and the control,
\item  \code{p\_phiInPrev} is the solution to the previous time step used to calculate the values of continuation cuts which are stored,
\item  \code{p\_condExp} is the conditional expectation object allowing to calculate the conditional expectation of the functions defined at the preceding time step processed \code{p\_phiInPrev}.
 \item \code{p\_bOneFile} is set if the continuation cut values calculated by each processor are dumped on a single file. Otherwise the continuation cut values calculated by each processor are dumped on different files (one per processor). If the problem results from the cuts of the values on the global grid that can be stored in the memory of the compute node, it may be more interesting to dump them  in a single file for the simulation of the optimal policy.
\end{itemize}
Here we give a simple example of temporal resolution using this method when MPI data distribution is used
\lstinputlisting[style=CStyle]{../StOpt/test/c++/tools/dp/DynamicProgrammingByRegressionCutDist.cpp}
An example without data distribution can be found in the file \href{run:../StOpt/test/c++/tools/dp/DynamicProgrammingByRegressionCut.cpp}{\code{DynamicProgrammingByRegressionCut.cpp}}.


\subsubsection{The simulation framework using cuts to approximate the Bellman's values}
\label{subsec::simulationCut}
Once the optimization carried out, the values of the continuation cuts are saved in a file (or in certain files) at each time step.
In order to simulate the optimal policy, we use previously calculated continuation cut values.
\begin{itemize}
\item 
In most cases (small dimension case),  the optimal values of the cut function can be stored in the compute node memory and the cut values are stored in a single file. In this case, a simulation of the optimal control can be easily performed by distributing the Monte Carlo simulations on the available compute nodes: this can be done by using the object \code{SimulateStepRegressionCut}  at each time step of the simulation.
\item When it comes with very large problems, optimization is achieved by distributing the data across the processors and it is impossible to store the optimal cuts values on a node.
In this case, the optimal cuts values are stored in the memory of the node which was used to calculate them in optimization.
The simulations are reorganized at each time step and gathered so as to occupy the same part of the global grid. Each processor will then get from the other processors a localized version of the optimal control or solution that it needs. This methodology is used in the  \code{SimulateStepRegressionCutDist} objects.
 \end{itemize}
We detail the simulations objects using the optimal cut values calculated in optimization  for the case of very large problems.\\
In order to simulate an  optimal policy  time  step, a \href{run:../StOpt/StOpt/dp/SimulateStepRegressionCutDist.h} {\code{SimulateStepRegressionCutDist}} object is provided with constructor
\begin{lstlisting}[style=CStyle]
   SimulateStepRegressionCutDist(gs::BinaryFileArchive &p_ar,  const int &p_iStep,  const std::string &p_nameCont,
                              const   shared_ptr<FullGrid> &p_pGridFollowing, const  shared_ptr<OptimizerDPCutBase > &p_pOptimize,
                              const bool &p_bOneFile)
\end{lstlisting}
where
\begin{itemize}
\item \code{p\_ar} is the binary archive where the continuation values are stored,
\item \code{p\_iStep} is the number associated with the current time step (0 at the start date of the simulation, the number is increased by one at each simulated time step),
\item \code{p\_nameCont} is the base name for continuation values,
\item \code{p\_GridFollowing} is the grid at the next time step (\code{p\_iStep+1}),
\item \code{p\_Optimize} the Optimizer describing the transition problem solved using a LP program.
\item \code{p\_OneFile} equal to \code{true} if only one archive is used to store continuation values.
\end{itemize}
\begin{Remark}
A version without data distribution but with multithreaded and with MPI possible on the calculations is available with the object \href{run:../StOpt/StOpt/dp/SimulateStepRegressionCut.h} {\code{SimulateStepRegressionCut}}. The \code{p\_OneFile} argument is omitted during construction.
\end{Remark}
This object implements the \code{oneStep} method
\begin{lstlisting}[style=CStyle]
void oneStep(std::vector<StateWithStocks > &p_statevector , Eigen::ArrayXXd  &p_phiInOut)
\end{lstlisting}
where:
\begin{itemize}
\item \code{p\_statevector} stores the states of all the simulations: this state is updated by applying the optimal command,
\item \code{p\_phiInOut} stores the gain/cost functions for all simulations: it is updated by the function call. The size of the array is $(nb, nbSimul)$ where $nb$  is given by the \code{getSimuFuncSize} method of the optimizer and $ nbSimul $ the number of Monte Carlo simulations.
\end{itemize}

An example of using this method to simulate an optimal policy with distribution is given below:
\lstinputlisting[style=CStyle]{../StOpt/test/c++/tools/dp/SimulateRegressionCutDist.h}
The version of the previous example using a single archive storing the control/solution is given in \href{run:../StOpt/test/c++/tools/dp/SimulateRegressionCut.h}{\code{SimulateRegressionCut.h}} file.

\section{Solve the problem for $X^{x,t}_2$  stochastic}
In this part, we assume that $X^{x,t}_2$ is controlled but is stochastic.
\subsection{Requirement to use the framework }
To use the framework, a business object describing the business at a time step from a state is derived from \code{OptimizerNoRegressionDPBase} itself derived from \code{OptimizerBase}.
\lstinputlisting[style=CStyle]{../StOpt/StOpt/dp/OptimizerNoRegressionDPBase.h}
In addition to the \code{OptimizerBase} methods, the following method is required:
\begin{itemize}
\item the \code{stepOptimize} method is used in optimization. We want to calculate the optimal value regressed to  $t_i$ current at a grid point \code{p\_stock} using a \code{p\_grid} grid at the following date $t_{i+1}$,

From a  \code{p\_stock} grid point, it calculates the regressed function values and the regressed optimal controls. It returns a pair where the
  \begin{itemize}
  \item the first element is a matrix (the first dimension is the number of functions in the regression, the second dimension  the number of regimes) giving the value of the regressed function,
  \item the second element  is a matrix (the first dimension is the number of functions in the regression, the second dimension  the number of controls) giving the optimal regressed control.
  \end{itemize}
\end{itemize} 
In this case of the optimization of an updated portfolio with dynamic:
\begin{eqnarray*}
dX^{x,t}_2 = X^{x,t}_2 \frac{dX^{x,t}_1}{X^{x,t}_1}
\end{eqnarray*}
where ${X^{x,t}_1}$ is the value of the risky asset, 
the Optimize object is given in the file \href{run:../StOpt/test/c++/tools/dp/OptimizePortfolio.h}{\code{OptimizePortfolio.h}}.

\subsection{The framework in optimization}
Once an Optimizer is derived for the project, and assuming a full grid is used for stock discretization, the framework provides a \href{run:../StOpt/StOpt/dp/TransitionStepDPDist.h}{\code{TransitionStepDPDist}} object in MPI which solves the optimization problem with the distribution of data over a time step with the following constructor:
\begin{lstlisting}[style=CStyle]
    TransitionStepDPDist(const  shared_ptr<FullGrid> &p_pGridCurrent,
    const  shared_ptr<FullGrid> &p_pGridPrevious,
    const  std::shared_ptr<BaseRegression> &p_regressorCurrent,
    const  std::shared_ptr<BaseRegression> &p_regressorPrevious,
    const  shared_ptr<OptimizerNoRegressionDPBase > &p_pOptimize):
\end{lstlisting}
with
\begin{itemize}
\item \code{p\_pGridCurrent} is the grid at the current time step ($t_i$),
\item \code{p\_pGridPrevious} is the grid at the previously processed time step ($t_{i+1}$),
\item \code{p\_regressorCurrent} is a regressor at the current date (to evaluate the function at the current date)
\item \code{p\_regressorPrevious} is a previously processed time step regressor ($t_{i+1}$) allowing to evaluate a function at date $t_{i+1}$,
\item \code{p\_pOptimize} the optimizer object
\end{itemize}
\begin{Remark}
A similar object is available without the MPI distribution framework \href{run:../StOpt/StOpt/dp/TransitionStepDP.h}{\code{TransitionStepDP}} with always the activation of parallelization with threads and MPI on the calculations on the full grid points.
\end{Remark}
\begin{Remark}
The case of sparse grids is not currently dealt with in the framework.
\end{Remark}
The main method is 
\begin{lstlisting}[style=CStyle]
    std::pair< std::shared_ptr< std::vector< Eigen::ArrayXXd > > , std::shared_ptr< std::vector< Eigen::ArrayXXd  > > >   oneStep(const std::vector< Eigen::ArrayXXd  > &p_phiIn) 
\end{lstlisting}
with
\begin{itemize}
\item  \code{p\_phiIn} the vector (its size corresponds to the number of regimes) of the matrix of calculated optimal values  regressed at the previous time iteration for each regime. Each matrix is a number of regressor function on the previous date  by number of matrix stock points.
\end{itemize}
return a pair:
\begin{itemize}
\item the first element is a vector of matrix with  new optimal values regressed at the current time step (each element of the vector corresponds to a regime and each matrix is a number of functions regressed at the current date by the number of stock points of the matrix).
\item the second element is a vector of matrix with new optimal controls regressed at the current time step (each element of the vector corresponds to a control and each matrix is a number of controls regressed by the number of matrix stock points).
\end{itemize}
\begin{Remark}
All \code{TransitionStepDP} derive from a \code{TransitionStepBase} object with a pure virtual \code{OneStep} method.
\end{Remark}
A second method is provided allowing to dump the optimal control at each time step:
\begin{lstlisting}[style=CStyle]
     void dumpValues(std::shared_ptr<gs::BinaryFileArchive> p_ar ,
                    const std::string &p_name, const int &p_iStep,
                    const std::vector<  Eigen::ArrayXXd  > &p_control, const bool &p_bOneFile) const
\end{lstlisting}
with:
\begin{itemize}
\item  \code{p\_ar} is the archive where controls and solutions are dumped,
\item  \code{p\_name} is a base name used in the archive to store the solution and the control,
\item  \code{p\_control} stores the optimal controls calculated at the current time step,
\item  \code{p\_bOneFile} is set to one if the optimal controls calculated by each processor are dumped on a single file. Otherwise the optimal controls calculated by each processor are dumped on different files (one by processor). If the problem gives  optimal control values on the global grid  that can be stored in the memory of the computation node, it can be  more interesting to dump the control values in one file for the simulation of the optimal policy.
\end{itemize}
\begin{Remark}
As for the \code{TransitionStepDP}, its \code{dumpValues} does not need a \code{p\_bOneFile} argument: obviously optimal controls are stored in a single file.
\end{Remark}
Here we give a simple example of temporal resolution using this method when MPI data distribution is used
\lstinputlisting[style=CStyle]{../StOpt/test/c++/tools/dp/DynamicProgrammingPortfolioDist.cpp}
An example without data distribution can be found in the file \href{run:../StOpt/test/c++/tools/dp/DynamicProgrammingPortfolio.cpp}{\code{DynamicProgrammingPortfolio.cpp}}.
\subsection{The simulation framework}
No special framework is available in simulation. Use the \code{SimulateStepRegressionControl} or \code{SimulateStepRegressionControlDist} function described in the \ref{subsec::simulation} section.

\section{Solving stock problems with trees}
In this section we detail how to solve problems
\begin{itemize}
\item Either by discretizing the control,
  \item Or by solving a Linear Program problem approaching Bellman values by cuts.
  \end{itemize}
\subsection{Resolution of dynamic programming problems with the discretization of commands}
\subsubsection{Framework usage condition}
The \code{OptimizerDPTreeBase} is the base object from which each business object is to be derived.
\lstinputlisting[style=CStyle]{../StOpt/StOpt/dp/OptimizerDPTreeBase.h}

Since the \code{OptimizerDPTreeBase} class is derived from \code{OptimizerBase}, we detail the additional methods required:
\begin{itemize}
\item the \code{stepOptimize} method is used in optimization. We want to calculate the optimal value at the current $t_i$ at a grid point \code{p\_stock} using a \code{p\_grid} grid at the following date $t_{i+1}$,
the continuation values for all the \code{p\_condEsp} regimes making it possible to calculate the conditional expectation of the optimal value function calculated at the previously processed time step $t_{i+1}$.
From a grid point \code{p\_stock} it calculates the function values and the optimal controls. It returns a pair where the
  \begin{itemize}
  \item the first element is a matrix (the first dimension is the number of nodes, the second dimension the number of regimes) giving the value of the function,
  \item the second element is a matrix (the first dimension is the number of nodes, the second dimension the number of controls) giving the optimal control.
  \end{itemize}
\item the \code{stepSimulate} method is used after the optimization using the continuation values calculated in the optimization part: these continuation values are stored in a GridTreeValue object for interpolation. From a \code{p\_state} state (storing the $X^{x,t}$), the continuation values calculated in the optimization \code{p\_continuation}, the optimal  values of the stored functions in \code{p\_phiInOut}.
  \item the \code{stepSimulateControl} simulates the strategy by direct interpolation of the control for a given node in the tree (sampled) and a position in the stock.
\end{itemize}
\subsubsection{The framework}
Most of the objects used with regression have their counterparts with tree methods.\\
In optimization:
  
  \href{run:../StOpt/StOpt/dp/TransitionStepTreeDPDist.h}{\code{TransitionStepTreeDPDist}} resolves the transition to the date for all grid point and tree nodes using the distribution (MPI).
  \begin{lstlisting}[style=CStyle]
    TransitionStepTreeDPDist(const  std::shared_ptr<FullGrid> &p_pGridCurrent,
                             const  std::shared_ptr<FullGrid> &p_pridPrevious,
                             const  std::shared_ptr<OptimizerDPTreeBase > &p_pOptimize
   \end{lstlisting}
with
\begin{itemize}
\item \code{p\_pGridCurrent} is the grid at the current time step ($t_i$),
\item \code{p\_pGridPrevious} is the grid at the previously processed time step ($t_{i+1}$),
\item \code{p\_pOptimize} the optimizer object
\end{itemize}
A similar object is available without the MPI distribution framework \href{run:../StOpt/StOpt/dp/TransitionStepTreeDP.h}{\code{TransitionStepTreeDP}} with always the activation of parallelization with threads and MPI on calculations on the full grid points.\\
The main method is 
\begin{lstlisting}[style=CStyle]
    std::pair< std::vector< std::shared_ptr< Eigen::ArrayXXd > >, std::vector<  std::shared_ptr<  Eigen::ArrayXXd > > >  oneStep(const std::vector< std::shared_ptr< Eigen::ArrayXXd > > &p_phiIn,
            const std::shared_ptr< Tree>     &p_condExp) const
\end{lstlisting}
with
\begin{itemize}
\item  \code{p\_phiIn} the vector (its size corresponds to the number of regimes)  of the matrix of optimal values calculated at the previous time iteration for each regime. Each matrix is a number of nodes the next date per number of stock points matrix.
\item \code{p\_condExp} the conditional expectation operator,
\end{itemize}
return a pair:
\begin{itemize}
\item  first element is a vector of matrix with new optimal values at the current time step  (each element of the vector corresponds to a regime and each matrix is a number of nodes at current date  by number of points of stock  matrix).
\item The second element is a vector of matrix with new optimal controls at the current time step (each element of the vector corresponds to a control and each matrix is a number of nodes at the current date by number of points of stock matrix).
\end{itemize}
A second method is provided allowing to dump the continuation values of the problem and the optimal control at each time step:
\begin{lstlisting}[style=CStyle]
     void dumpContinuationValues(std::shared_ptr<gs::BinaryFileArchive> p_ar,
                                const std::string &p_name, const int &p_iStep,
                                const std::vector< std::shared_ptr< Eigen::ArrayXXd > > &p_phiIn,
                                const std::vector< std::shared_ptr< Eigen::ArrayXXd > > &p_control,
                                const std::shared_ptr< Tree>      &p_tree,
                                const bool &p_bOneFile) const;
\end{lstlisting}
with:
\begin{itemize}
\item  \code{p\_ar} is the archive where the controls and solutions are dumped,
\item  \code{p\_name} is a base name used in the archive to store the solution and the control,
\item  \code{p\_phiInPrev} is the previous time step solution used to calculate the continuation values that are stored,
\item  \code{p\_control} stores the optimal controls calculated at the current time step,
\item  \code{p\_tree} is the conditional expectation object allowing to calculate the conditional expectation of the functions defined at the previous time step processed \code{p\_phiInPrev} and allowing to store a representation of the optimal control.
\item \code{p\_bOneFile} is set to one if the continuation and optimal controls calculated by each processor are dumped on a single file. Otherwise the continuation and optimal controls calculated by each processor are dumped on different files (one per processor).
  \end{itemize}
  \begin{Remark}
The \code{p\_bOneFile} is not present for \code{TransitionStepTreeDP} objects.
  \end{Remark}
  In simulation (see detail in section for regressions)
  \begin{itemize}
  \item
    A first object allowing the recalculation of the optimal control in simulation.
   \begin{lstlisting}[style=CStyle] 
  SimulateStepTreeDist(gs::BinaryFileArchive &p_ar,  const int &p_iStep,  const std::string &p_nameCont,
                         const   std::shared_ptr<FullGrid> &p_pGridFollowing, const  std::shared_ptr<OptimizerDPTreeBase > &p_pOptimize,
                         const bool &p_bOneFile)
   \end{lstlisting}
   where
\begin{itemize}
\item \code{p\_ar} is the binary archive where the continuation values are stored,
\item \code{p\_iStep} is the number associated with the current time step (0 at the start date of the simulation, the number is increased by one at each simulated time step),
\item \code{p\_nameCont} is the base name for continuation values,
\item \code{p\_GridFollowing} is the grid at the next time step (\code{p\_iStep+1}),
\item \code{p\_Optimize} the Optimizer describing the transition from one time step to the next,
\item \code{p\_OneFile} equal to \code{true} if only one archive is used to store continuation values.
\end{itemize}
This object implements the method \code{oneStep}
\begin{lstlisting}[style=CStyle]
void oneStep(std::vector<StateTreeStocks > &p_statevector, Eigen::ArrayXXd  &p_phiInOut) const
\end{lstlisting}
where:
\begin{itemize}
\item \code{p\_statevector} stores the states of all the simulations: this state is updated by applying the optimal command,
\item \code{p\_phiInOut} stores the gain/cost functions for all simulations: it is updated by the function call. The size of the array is $(nb, nbSimul)$ where $nb$  is given by the \code{getSimuFuncSize} method of the optimizer and $ nbSimul $ the number of Monte Carlo simulations.
\end{itemize}
\begin{Remark}
  The version without distribution of Bellman values is available in the object \code{SimulateStepTree}.
\end{Remark}
\item A second object directly interpolating the control
  \begin{lstlisting}[style=CStyle]
SimulateStepTreeControlDist(gs::BinaryFileArchive &p_ar,  const int &p_iStep,  const std::string &p_nameCont,
                                const   std::shared_ptr<FullGrid> &p_pGridCurrent,
                                const   std::shared_ptr<FullGrid> &p_pGridFollowing,
                                const  std::shared_ptr<OptimizerDPTreeBase > &p_pOptimize,
                                const bool &p_bOneFile);
 \end{lstlisting}
  where
\begin{itemize}
\item \code{p\_ar} is the binary archive where the continuation values are stored,
\item \code{p\_iStep} is the number associated with the current time step (0 at the start date of the simulation, the number is increased by one at each simulated time step),
\item \code{p\_nameCont} is the base name of the control values,
\item \code{p\_GridCurrent} is the grid at the current time step (\code{p\_iStep}),
\item \code{p\_GridFollowing} is the grid at the next time step (\code{p\_iStep+1}),
\item \code{p\_Optimize} is the Optimizer describing the transition from one time step to the next,
\item \code{p\_OneFile} is equal to \code{true} if only one archive is used to store continuation values.
\end{itemize}
This object implements the method \code{oneStep}
\begin{lstlisting}[style=CStyle]
   void oneStep(std::vector<StateTreeStocks > &p_statevector, Eigen::ArrayXXd  &p_phiInOut) const;

\end{lstlisting}
where:
\begin{itemize}
\item \code{p\_statevector} stores the state for all the simulations : this state is updated by applying optimal commands,
\item \code{p\_phiInOut} stores the gain/cost functions for all simulations: it is updated by the function call. The size of the array is $(nb, nbSimul)$ where $nb$  is given by the \code{getSimuFuncSize} method of the optimizer and $ nbSimul $ the number of Monte Carlo simulations.
\end{itemize}  
\begin{Remark}
  The undistributed version is given by the object \code{SimulateStepTreeControl}.
  \end{Remark}
  \end{itemize}

  \subsection{Solving Dynamic Programming by solving LP problems}
  This approach can only be used for continuous problems with convex or concave Bellman values. See section \ref{sec:withCuts} for an explanation of the cut approximation.
  \subsubsection{Framework usage requirement}
  The expanded business object must derive from the \code{OptimizerDPCutBase} object derived from the \code{OptimizerBase} object.
  \lstinputlisting[style=CStyle]{
    ../StOpt/StOpt/dp/OptimizerDPCutTreeBase.h}
We detail the different methods to implement in addition to the \code{OptimizerBase} methods:
\begin{itemize}
\item the \code{stepOptimize} method is used in optimization. We want to calculate the optimal value and the corresponding sensitivities with respect to stocks at $t_i$ current at a grid point \code{p\_stock} using a grid \code{p\_grid} at the next date $t_{i+1}$,
  the continuation cuts the values for all the regimes \code{p\_condEsp} allowing to calculate a upper estimate (during the maximization) of the conditional expectation of the optimal values by using an optimization calculated at the previously treated time step $t_{i+1}$.
  From a \code{p\_stock} grid point, it calculates the function values and the corresponding sensitivities. It returns a matrix (the first dimension is the number of nodes at the current cate by the number of components cuts (number of storage +1), the second dimension the number of regimes) giving the value of the function and sensitivities.
\item the \code{stepSimulate} method is used after the optimization using the continuation cuts the values calculated in the optimization part. From a \code{p\_state} state (storing the $X^{x,t}$), the sequence cuts the calculated values
  in optimization \code{p\_continuation}, the optimal cash flows are stored in \code{p\_phiInOut}.
\end{itemize}
In the case of a gas storage  the Optimize object  is given  in the file \href{run:../StOpt/test/c++/tools/dp/OptimizeGasStorageTreeCut.h}{\code{OptimizeGasStorageTreeCut.h}}.
\subsubsection{The framework in optimization using certain cutting methods}
We treat it exactly as in \ref{subsec:frameworkCut} section.
The framework provides an \href{run:../StOpt/StOpt/dp/TransitionStepTreeDPCutDist.h}{\code{TransitionStepTreeDPCutDist}} object in MPI which solves the optimization problem with data distribution over a time step with the following constructor:
\begin{lstlisting}[style=CStyle]
    TransitionStepTreeDPCutDist(const  std::shared_ptr<FullGrid> &p_pGridCurrent,
                                const  std::shared_ptr<FullGrid> &p_pGridPrevious,
                                const  std::shared_ptr<OptimizerDPCutTreeBase > &p_pOptimize);
\end{lstlisting}
with
\begin{itemize}
\item \code{p\_pGridCurrent} is the grid at the current time step ($t_i$),
\item \code{p\_pGridPrevious} is the grid at the previously processed time step ($t_{i+1}$),
\item \code{p\_pOptimize} the optimizer object
\end{itemize}
The construction is very similar to the classical regression methods using only the discretization by command. 
\begin{Remark}
A similar object is available without the MPI distribution framework \href{run:../StOpt/StOpt/dp/TransitionStepRegressionDPCut.h}{\code{TransitionStepTreeDPCut}} with always the activation of parallelization with threads and MPI on calculations on the full points grid .
\end{Remark}
 The main method is 
\begin{lstlisting}[style=CStyle]
     std::vector<  std::shared_ptr< Eigen::ArrayXXd > >  oneStep(const std::vector< std::shared_ptr< Eigen::ArrayXXd > > &p_phiIn,
            const std::shared_ptr< Tree>     &p_condExp) const
\end{lstlisting}
with
\begin{itemize}
\item  \code{p\_phiIn} the vector (its size corresponds to the number of regimes) of the matrix of optimal values and sensitivities calculated at the previous time iteration for each regime. Each matrix has a number of rows equal to the number of nodes on the next date by the number of stock plus one. The number of columns is equal to the number of stock points on the grid.
In the row, the number of simulations by the number of stock plus one value is stored as follows:
  \begin{itemize}
  \item The first values (number of nodes on the following date: $NS$) correspond to the optimal Bellman values at a given stock point,
    \item The  $NS$ values following corresponds to sensitivities $ \frac{ \partial V}{\partial S_1} $ to first storage
    \item The  $NS$ values following corresponds to sensitivities to the second storage...
    \item $\dots$
    \end{itemize}
\item \code{p\_condExp} the conditional expectation operator,
\end{itemize}
returning a  vector of matrix with new optimal values and sensitivities at the current time step (each element of the vector corresponds to a regime and each matrix has a size equal to (number of nodes at the current date by (the number of storage plus one))  by the number of stock points). The structure of the output is then similar to the \code{p\_phiIn} input.\\
A second method is provided allowing to dump the continuation values  and the cuts of the problem and the optimal control at each time step:
\begin{lstlisting}[style=CStyle]
    void dumpContinuationCutsValues(std::shared_ptr<gs::BinaryFileArchive> p_ar, const std::string &p_name, const int &p_iStep,
                                    const std::vector< std::shared_ptr< Eigen::ArrayXXd > > &p_phiInPrev, const std::shared_ptr< Tree>     &p_condExp,
                                    const bool &p_bOneFile) const
\end{lstlisting}
with:
\begin{itemize}
\item  \code{p\_ar} is the archive where controls and solutions are dumped,
\item  \code{p\_name} is a base name used in the archive to store the solution and the control,
\item  \code{p\_phiInPrev} is the solution to the previous time step used to calculate the values of continuation cuts which are stored,
\item  \code{p\_condExp} is the conditional expectation object allowing to calculate the conditional expectation of the functions defined at the preceding time step processed \code{p\_phiInPrev}.
 \item \code{p\_bOneFile} is set to one if the continuation cuts values calculated by each processor are dumped on a single file. Otherwise the continuation cuts values calculated by each processor are dumped on different files (one per processor).
\end{itemize}
Here we give a simple example of a temporal resolution using this method when MPI data distribution is used
\lstinputlisting[style=CStyle]{../StOpt/test/c++/tools/dp/DynamicProgrammingByTreeCutDist.cpp}
An example without data distribution can be found in the file \href{run:../StOpt/test/c++/tools/dp/DynamicProgrammingByTreeCut.cpp}{\code{DynamicProgrammingByTreeCut.cpp}}.
\subsubsection{Using the framework in simulation}
Similar to the \ref{subsec::simulationCut} section, we can use the cuts calculated in optimization to test the optimal strategy found.
In order to simulate an optimal policy step, a \href{run:../StOpt/StOpt/dp/SimulateStepTreeCutDist.h} {\code{SimulateStepTreeCutDist}} object is provided with the constructor
\begin{lstlisting}[style=CStyle]
   SimulateStepTreeCutDist(gs::BinaryFileArchive &p_ar,  const int &p_iStep,  const std::string &p_nameCont,
                            const  std::shared_ptr<FullGrid> &p_pGridFollowing,
                            const  std::shared_ptr<OptimizerDPCutTreeBase > &p_pOptimize,
                            const bool &p_bOneFile);
\end{lstlisting}
where
\begin{itemize}
\item \code{p\_ar} is the binary archive where the continuation values are stored,
\item \code{p\_iStep} is the number associated with the current time step (0 at the start date of the simulation, the number is increased by one at each simulated time step),
\item \code{p\_nameCont} is the base name for continuation values,
\item \code{p\_GridFollowing} is the grid at the next time step (\code{p\_iStep+1}),
\item \code{p\_Optimize} the Optimizer describing the transition problem solved using an LP program.
\item \code{p\_OneFile} equal to \code{true} if only one archive is used to store continuation values.
\end{itemize}
\begin{Remark}
A version without data distribution but with multithreaded and with possible MPI on the calculations is available with the \href{run:../StOpt/StOpt/dp/SimulateStepTreeCut.h} {\code{SimulateStepTreeCut}} object. The \code{p\_OneFile} argument is omitted during construction.
\end{Remark}
This object implements the method \code{oneStep}
\begin{lstlisting}[style=CStyle]
void oneStep(std::vector<StateTreeStocks > &p_statevector, Eigen::ArrayXXd  &p_phiInOut) const
\end{lstlisting}
where:
\begin{itemize}
\item \code{p\_statevector} stores the states of all the simulations: this state is updated by applying the optimal command,
\item \code{p\_phiInOut} stores the gain/cost functions for all simulations: it is updated by the function call. The size of the array is $(nb, nbSimul)$ where $nb$  is given by the \code{getSimuFuncSize} method of the optimizer and $ nbSimul $ the number of Monte Carlo simulations.
\end{itemize}

An example of using this method to simulate an optimal policy with distribution is given below:
\lstinputlisting[style=CStyle]{../StOpt/test/c++/tools/dp/SimulateTreeCutDist.h}
The version of the previous example using a single archive storing the control/solution is given in \href{run:../StOpt/test/c++/tools/dp/SimulateTreeCut.h}{\code{SimulateTreeCut.h}} file.

\chapter{The Python API to manage stocks}
\section{Mapping to the framework}
To use the Python API, it is possible to use only the mapping of grids, continuation values, and regression object and program an equivalent of  \href{run:../StOpt/StOpt/dp/TransitionStepRegressionDP.h}{\code{TransitionStepRegressionDP}} and of \href{run:../StOpt/StOpt/dp/SimulateStepRegression.h}{
  \code{SimulateStepRegression}}, \href{run:../StOpt/StOpt/dp/SimulateStepRegressionControl.h}{
  \code{SimulateStepRegressionControl}} in python. 
No mapping is currently available for \href{run:../StOpt/StOpt/dp/TransitionStepDP.h}{\code{TransitionStepDP}}.
An example using python is given by
\lstinputlisting[style=PStyle]{../StOpt/test/python/functional/dp/TransitionStepRegressionDP.py}
Some examples are available   in the test directory (for example \href{run:../StOpt/test/python/functional/testSwingOption.py}{for swing options}).\\
Another approach more effective in term of computational cost consists in mapping the simulator object  derived from  the \href{run:../StOpt/StOpt/dp/SimulatorDPBase.h}{\code{SimulatorDPBase}} object  and optimizer object
derived from  the \href{run:../StOpt/StOpt/dp/OptimizerDPBase.h}{\code{OptimizerDPBase}} object  and to use the high level python mapping of  \href{run:../StOpt/StOpt/dp/TransitionStepRegressionDP.h}{\code{TransitionStepRegressionDP}} and \href{run:../StOpt/StOpt/dp/SimulateStepRegression.h}{\code{SimulateStepRegression}}.
In the test part of the library some \href{run:../StOpt/test/c++/tools/simulators/BlackScholesSimulator.h}{Black-Scholes simulator} and some \href{run:../StOpt/test/c++/tools/simulators/MeanRevertingSimulator.h}{Mean reverting  simulator for a future curve deformation} are developed and some examples of the mapping are achieved in the
\href{run:../StOpt/test/c++/python/Pybind11Simulators.cpp}{\code{Pybind11Simulators.cpp}} file.
Likewise, \href{run:../StOpt/test/c++/tools/dp/OptimizeSwing.h}{optimizer class for swings options}, \href{run:../StOpt/test/c++/tools/dp/OptimizeFictitiousSwing.h}{optimizer for a fictitious swing in dimension 2}, \href{run:../StOpt/test/c++/tools/dp/OptimizeGasStorage.h}{optimizer for a gas storage}, \href{run:../StOpt/test/c++/tools/dp/OptimizeGasStorageSwitchingCost.h}{optimizer for a gas storage with switching cost} are mapped to python in the \href{run:../StOpt/test/c++/python/Pybind11Optimizers.cpp}{\code{Pybind11Optimizers.cpp}} file.\\
In the example below, we describe the use of this high level interface for swing options with a Black Scholes simulator: in this example we give the mapping of the most used objects:
\lstinputlisting[style=PStyle]{../StOpt/test/python/unit/global/testGlobal.py}
Its variation in terms of timing loop for optimization is given below ( note that the object \code{TransitionStepRegressionDP}  is the result of the mapping between python and c++ and given in the module \code{StOptGlobal})
\lstinputlisting[style=PStyle]{../StOpt/test/python/functional/dp/DynamicProgrammingByRegressionHighLevel.py}
Likewise, a python temporal loop in simulation using the control previously calculated in optimization can be given as an example by:
\lstinputlisting[style=PStyle]{../StOpt/test/python/functional/dp/SimulateRegressionControlHighLevel.py}
The equivalent of using MPI and the distributing calculations and data can be used using the \code{mpi4py} package. An example of its use can be found in \href{run:../StOpt/test/python/functional/dp/testSwingOptimSimuHighLevelDist.py}{the MPI version of a swing optimization and valuation}.

\section{Special python binding}
Some specific features have been added to the python interface to increase the flexibility of the library.
A special mapping of the geners library was carried out for certain specific needs.
\subsection{A first binding to use the framework}
The \code{BinaryFileArchive} in the python module \code{StOptGeners} permits for:
\begin{itemize}
\item  a grid on point, 
\item  a list of numpy array (dimension 2)  of size the number of simulations used by the number of points on the grid (the size of the list corresponds to the number of regimes used in the event of a regime switching problem: if a regime, this list contains only one item which is a two-dimensional array)
\item a regressor
\end{itemize}
to create a regressed set of values from numpy arrays and store them in the archive. This feature allows you to store the continuation values associated with a problem.\\
The \code{dumpGridAndRegressedValue} dump method in the \code{BinaryFileArchive} class permits this dump.\\
It is also possible to retrieve the continuation values obtained using the \code{readGridAndRegressedValue} method.
\lstinputlisting[style=PStyle]{../StOpt/test/python/unit/geners/testBinaryArchive.py}
\subsection{Binding to store/read a regressor and a two-dimensional array}
Sometimes users prefer to avoid using the provided framework and prefer to only use the python binding associated with regression methods.
When some regressions are performed for different sets of particles (meaning that one or more functions are regressed), it it possible to dump the regressor used and some values associated with these regressions:
\begin{itemize}
\item the \code{dumpSome2DArray}, \code{readSome2DArray} allows you to dump and read 2-dimensional numpy arrays,
\item  the \code{dumpSomeRegressor} , \code{readSomeRegressor} allows to dump and read a regressor.
\end{itemize}
\lstinputlisting[style=PStyle]{../StOpt/test/python/unit/geners/testSomeBinaryArchiveStorage.py}

\chapter{Framework to solve some switching problems with integer state constraints by regressions}
\label{switchng}
Switching problem with  integer state are special case of the previous chapter where the state is separated in 3 parts as previously $X^{x,t} = (X^{x,t}_1,X^{x,t}_2, I_t)$ where 
$X^{x,t}_1$ is not controlled, $I_t$ is an integer giving the regime mode and  $X^{x,t}_2$ is  a purely deterministic tensor   taking {\bf some  integer values}. As the values taken by  $X^{x,t}_2$  are purely integer no interpolation is needed.\\
Therefore, in each regime, $X^{x,t}_2$ is discretized on a special grid taking some discrete integer values.
The grid is a full grid, and as previously for stocks problems, some MPI parallelization can be carried out to calculate the asset values at the different dterministic cases.

\paragraph{Exemple of some switching problems}
\label{parthermalSwitching}
We want to manage a thermal asset where prices of electricity and gas are given by a one factor model.
Then $X^{x,t}_1$ is two dimensional:
\begin{itemize}
\item  $X^{x,t}_{1,1}$ is the price for electricity
  \item $X^{x,t}_{1,2}$ is the price of  gas multiplied by some heat rate.
  \end{itemize}
  When the asset is on, the gain is $X^{x,t}_{1,1}-X^{x,t}_{1,2}$ and the asset is off, the gain is null.
  The asset has therefore two regime ($I_t$ takes 2 values for exemple 0 (off) and 1 (on)).\\
  Some constraints are added :
  \begin{itemize}
  \item When the asset is ``on'', it has to be ``on'' during at least $nMinOn$ time steps and the state $X^{x,t}_2$ is one dimensional and can take some values from $0$ to $nMinoOn-1$ storing the number of time step since it is on. The state value $nMinoOn-1$ corresponds to the case where the number of time steps it is on  at least $nMinoOn$ and the asset is allowed to switch off.
    \item When the asset is  ``off'', it has to be $off$ during at least $nMinOff$ time steps and the state $X^{x,t}_2$ is one dimensional and can take some values from $0$ to $nMinoOff-1$ storing the number of time step since it is off.
    \end{itemize}
Some cost can be added, for exemple when the asset switch from $off$ to $on$.

\section{Business object for switching problems}
As previously, in order to use the framework, the developer describes the problem he wants to solve
in one step from a state $X^{x,t}$ . This business object must offer common methods and it is
derived from \code{OptimizerSwitchBase}.
\lstinputlisting[style=CStyle]{../StOpt/StOpt/dp/OptimizerSwitchBase.h}
\begin{itemize}
\item the \code{getNbRegime} makes it possible to obtain the number of regimes of the problem. The number of regimes is fixed.
\item the \code{getSimulator} method is used to retrieve the simulator giving the Monte Carlo simulations,
\item the \code{getSimuFuncSize} method is used in simulation to define the number of functions to follow in the simulation part (see chapter \ref{SecParal}).
\item the \code{getCone} method is only relevant if the MPI framework with distribution is used. As argument it takes the regime and a vector of  size the dimension of the grid for this regime. Each component of the vector is an array containing for the given regime,
the minimum and maximum  integer coordinate values of the deterministic state  of the current grid defining an hyper cube $H1$. It returns for each dimension, the min and max integer coordinates of the hyper cube $H2$ containing the state which can be reached  from a state of the grid in $H1$.
\item the \code{getDimensionToSplit} method is used to define in the MPI framework with distribution the directions to be divided for the solution on the processors. For each regime, for each dimension, it returns a Boolean where \code{true} means that the direction is a candidate for splitting.
\item the \code{stepOptimize} method is used in optimization. We want to calculate the optimal value at the current $t_i$ at a grid state \code{p\_state}, and for the regime \code{p\_ireg}  using  a  vector  \code{p\_grid} of grids of state  (one for each regime) at the following date $t_{i+1}$, \code{p\_condEsp} is the object permitting to calculate conditional expectations of some functions calculated in the previous one
  treated time step $t_{i+1}$.
  At a grid point \code{p\_state} the function  calculates the function values. It returns an array  (its dimension is the number of simulations) giving the value of the function for the regime treated.
\item the \code{stepSimulate} method is used after the optimization using the continuation values calculated at each (integer) point of the grid in the optimization part. From a \code{p\_state} state (storing the $X^{x,t}$),  the conditional expectation operator \code{p\_condExp}, and the basis functions \code{p\_basisFunc} for  each point of the grid state for each regime, the values followed during simulation  along the current path are stored in \code{p\_phiInOut}.
\end{itemize}
\section{Using the framework to optimize or simulate on a time step}
\subsection{Optimize on one time step}
Once an Optimizer is derived for the project, and assuming a  RegularSpaceIntGrid  grid is used for inventory discretization, the framework provides a \href{run:../StOpt/StOpt/dp/TransitionStepRegressionSwitchDist.h}{\code{TransitionStepRegressionSwitchDist}} object in MPI which allows to solve the
optimization problem with data distribution over a time step with the following constructor:
\begin{lstlisting}[style=CStyle]
  TransitionStepRegressionSwitchDist(const  vector< shared_ptr<RegularSpaceIntGrid> >  &p_pGridCurrent,
                                     const  vector< shared_ptr<RegularSpaceIntGrid> >  &p_pGridPrevious,
                                     const  sshared_ptr<OptimizerSwitchBase > &p_pOptimize)
  \end{lstlisting}
with
\begin{itemize}
\item \code{p\_pGridCurrent} is the vector of grids at the current date: one by regime (so it is a vector) containing the grids describing the discrete integer values taken by the deterministic state.
\item \code{p\_pGridPrevious} is the vector of grids at the  previous time step treated (so the next time step as the resolution is backward)
  \item \code{p\_pOptimize} is the business model describing the physical problem to optimize;
  \end{itemize}
  \begin{Remark}
  A similar object is available without the MPI distribution framework \href{run:../StOpt/StOpt/dp/TransitionStepRegressionSwitch.h}{\code{TransitionStepRegressionSwitch}} with always the activation of parallelization with threads and MPI on calculations on the full points grid.
\end{Remark}
The main method associated to this class:
\begin{lstlisting}[style=CStyle]
  vector< shared_ptr< ArrayXXd >>  TransitionStepRegressionSwitchDist::oneStep(const vector< shared_ptr< ArrayXXd > > &p_phiIn,
                             const shared_ptr< BaseRegression>  &p_condExp)
\end{lstlisting}
with
\begin{itemize}
\item  \code{p\_phiIn} the vector (its size corresponds to the number of regimes) of the matrix of optimal values calculated at the previous time iteration for each regime. Each matrix is a number of simulations per the  number of integer state points.
  \item \code{p\_condExp} the conditional expectation operator,
  \end{itemize}
  returning  a vector of  matrix  with new optimal values at the current time step  (each element of the vector corresponds to a regime and each matrix of this regime  is a number of simulations per the  number of state points).\\
  A second method is provided permitting to dump the continuation values of the problem  at each time step:
\begin{lstlisting}[style=CStyle]
    void dumpContinuationValues(std::shared_ptr<gs::BinaryFileArchive> p_ar , const std::string &p_name, const int &p_iStep,
                                const std::vector< std::shared_ptr< Eigen::ArrayXXd > > &p_phiInPrev,
                                const  std::shared_ptr<BaseRegression>    &p_condExp) const
\end{lstlisting}
with:
\begin{itemize}
\item  \code{p\_ar} is the archive where the solution is dumped,
\item  \code{p\_name} is a base name used in the archive to store the solution,
\item  \code{p\_phiInPrev} is the previous time step solution used to calculate the continuation values that are stored,
\item  \code{p\_condExp} is the conditional expectation object allowing to calculate the conditional expectation of the functions defined at the previous time step processed \code{p\_phiInPrev}.
 \end{itemize}
 \begin{Remark}
   All  continuation values are reconstructed on the whole grid associated to the problem and not only on the calculation grid associated a to given processor.
 \end{Remark}
 Here we give a simple example of temporal resolution using this method when MPI data distribution is used
\lstinputlisting[style=CStyle]{../StOpt/test/c++/tools/dp/DynamicProgrammingSwitchingByRegressionDist.cpp}
An example without data distribution can be found in the file \href{run:../StOpt/test/c++/tools/dp/DynamicProgrammingSwitchingByRegression.cpp}{\code{DynamicProgrammingSwitchingByRegression.cpp}}.
 \subsection{Simulate on one time step}
 Once the optimization is done, the function basis associated to continuation values are saved at each point of each grids in a file  at each time step.
 The following simulation object \href{run:../StOpt/StOpt/dp/SimulateStepSwith.h} {\code{SimulateStepSwitch}} permits to simulate the optimal management on one time step.
 
  \begin{lstlisting}[style=CStyle]
    SimulateStepSwitch(gs::BinaryFileArchive &p_ar,  const int &p_iStep,  const string &p_nameCont,
                                       const   vector< shared_ptr<RegularSpaceIntGrid> > &p_pGridFollowing,
                                       const  shared_ptr<OptimizerSwitchBase > &p_pOptimize)
  \end{lstlisting}
  where
\begin{itemize}
\item \code{p\_ar} is the binary archive where the continuation values are stored,
\item \code{p\_iStep} is the number associated with the current time step (0 at the start date of simulation, the number is increased by one at each simulated time step ),
\item \code{p\_nameCont} is the base name of the control values,
\item \code{p\_GridFollowing} is the vector of grids for the deterministic state  at the next time step (\code{p\_iStep+1}),
\item \code{p\_Optimize} is the Optimizer describing the transition from one time step to the next,
\end{itemize}

This object implements the method \code{oneStep}
\begin{lstlisting}[style=CStyle]
void oneStep(std::vector<StateWithIntState > &p_statevector , Eigen::ArrayXXd  &p_phiInOut)
\end{lstlisting}
where:
\begin{itemize}
\item \code{p\_statevector} stores the states of all simulations: this state is updated by applying the optimal command,
\item \code{p\_phiInOut} stores the gain/cost functions for all the simulations: it is updated by the function call. The size of the array is $(nb, nbSimul)$ where $nb$  is given by the \code{getSimuFuncSize} method of the optimizer and $ nbSimul $ the number of Monte Carlo simulations.
\end{itemize}

An example of using this method to simulate an optimal policy with distribution is given below for a classical termal asset dumping in spot prices and the optimal regime during simulation:
\lstinputlisting[style=CStyle]{../StOpt/test/c++/tools/dp/SimulateRegressionSwitch.h}

\section{Using the python API}
As the the cas of stock management, a simulator describing the uncertainties  deriving from  the \href{run:../StOpt/StOpt/dp/SimulatorDPBase.h}{\code{SimulatorDPBase}} object has to be developed. A C++ optimizer deriving from the \href{run:../StOpt/StOpt/dp/OptimizerSwitchBase.h}{\code{OptimizerSwitchBase}} object  has to be mapped and   we have to use the high level python mapping of  \href{run:../StOpt/StOpt/dp/TransitionStepRegressionSwitch.h}{\code{TransitionStepRegressionSwitch}} and \href{run:../StOpt/StOpt/dp/SimulateStepSwitch.h}{\code{SimulateStepSwitch}}.\\
This object can be used as in a time step optimization as follows
\lstinputlisting[style=PStyle]{../StOpt/test/python/functional/dp/DynamicProgrammingSwitchingByRegressionHighLevel.py}
and a simulation using a loop on the \code{SimulateStepSwitch} object can be used.
\lstinputlisting[style=PStyle]{../StOpt/test/python/functional/dp/SimulateSwitchingRegression.py}
An example of the use of these python functions for a thermal asset with integer states is then given by:
\lstinputlisting[style=PStyle]{../StOpt/test/python/functional/testThermalAssetHighLevel.py}


\chapter{Using the  C++ framework to solve some hedging problem}
\label{chap:variance}
In this chapter we present an algorithm developed in StOpt to solve some hedging problem supposing that a mean variance criterion is chosen. The methodology follows the article \cite{warin2017variance}
In this section we suppose that $(\Omega, \Fc, (\Fc_t)_{t \in [0,T]})$ is a filtered probability space.
We define a set of trading dates $\mathcal{T}= \{t_0=0, t_1, \dots , t_{N-1}, t_{N}=T \}$ and
we suppose that we are given an asset used as an hedging product $(S_t)_{t_0.t_N}$ which is almost surely positive, square integrable so that $\E[ S_t^2] < \infty$  and adapted so that $S_{t}$ is $\Fc_t$-measurable
for $t=t_0,\dots, t_N$.\\ 
At last we suppose that the risk free rate is zero so that a bond has always a value of $1$.\\
\section{The problem}
Suppose we are given a contingent claim  $H \in \Lc^2(P)$ which is assumed to be a random variable $\Fc_T$-measurable.
In the case of a European call option on an asset $S_t$ with strike $K$ and maturity $T$, $H(\omega)= (S_T(\omega)-K)^+$. \\
We are only interested in self-financing strategies with limited orders, therefore with limited controls. By extending the definition \cite{motoczynski2000multidimensional},  \cite{beutner2007mean}, we define:
\begin{definition}
A $(\bar m, \bar l)$ self-financing strategy $\Vc =(\Vc_{t_i})_{i=0,\dots,N-1}$ is a pair of adapted process $(m_{t_i},l_{t_i})_{i=0, \dots,N-1}$ defined for
$(\bar m, \bar l) \in (0, \infty) \times (0, \infty)$ such that:
\begin{itemize}
\item   $ 0 \le m_{t_i} \le \bar m,  \quad 0 \le l_{t_i} \le \bar l  \quad \quad    P.a.s. \quad \forall i = 0 ,\dots,N-1$,
\item   $m_{t_i} l_{t_i} = 0  \quad P.a.s.  \quad \forall i = 0 ,\dots,N-1$.
\end{itemize}
\end{definition}
In this definition $m_t$ corresponds to the number of shares sold on the date $t$, and $l_t$ the number of shares purchased on this date.
\begin{Remark}
The strategies defined in \cite{motoczynski2000multidimensional} and \cite{beutner2007mean} do not require that $m_t l_t= 0$ therefore a buy and sell check could take place on the same given date.
\end{Remark}

We denote $\Theta^{(\bar m, \bar l)}$ the set of $(\bar m, \bar l)$ self-financing strategy and with obvious notations $\nu= ( m,l)$ for $\nu \in \Theta^{(\bar m, \bar l)}$.\\
We consider a proportional cost model, so that an investor buying a stock on date $t$ will pay $(1+\lambda) S_t$ and an investor selling that stock will only receive $(1-\lambda) S_t$.
Assuming no transaction cost at the last date $T$, the final wealth of an investor with initial wealth $x$ is given by:
\begin{flalign}
x  - \sum_{i=0}^{N-1} (1+\lambda) l_{t_i}S_{t_i} + \sum_{i=0}^{N-1} (1-\lambda) m_{t_i}S_{t_i} + \sum_{i=0}^{N-1} l_{t_i} S_{t_N} -\sum_{i=0}^{N-1} m_{t_i}  S_{t_N}.
\end{flalign}
\begin{Remark}
The transaction costs at the last date $T$ are linked to the nature of the contract. In the case of a pure financial contract, the investor will sell the asset and then some transaction fees will need to be paid to offset the final position. In the energy market, for example, the contract is often associated with a physical delivery and no specific costs are payable.
Furthermore in these markets, even if the contract is purely financial, the futures markets are rather illiquid, which means significant transaction costs while the spot markets are much more liquid, which justifies neglecting final transaction costs.
\end{Remark}
As in \cite{motoczynski2000multidimensional} \cite{beutner2007mean}, we define the minimal risk strategy minimizing the $\Lc^2$ risk of the hedging portfolio:
\begin{definition}
A self-financing strategy $(\bar m, \bar l)$ $\hat \Vc =(\hat m, \hat l)$ is the minimization of the overall risk for the contingent claim $H$ and the initial capital $x$ if:
\begin{flalign}
\label{argminL2}
\hat \Vc = & \argmin_{\Vc = (m, l) \in \Theta^{(\bar m, \bar l)}}  \E[(H-x +\sum_{i=0}^{N-1} (1+\lambda) l_{t_i} S_{t_i} -  \nonumber \\
&   \sum_{i=0}^{N-1} (1-\lambda) m_{t_i} S_{t_i} -  \sum_{i=0}^{N-1} l_{t_i} S_{t_N} +\sum_{i=0}^{N-1} m_{t_i}  S_{t_N})^2 ].
\end{flalign}
\end{definition}
\section{Theoretical algorithm}
it is assumed that the process is Markov and that the gain $H$ is a function of the asset value at maturity only to simplify the presentation of the proposed the Monte Carlo method.\\
We introduce the global position $\nu= (\nu_i)_{i=0, \dots, N-1}$ with:
\begin{flalign*}
\nu_{i} = \sum_{j=0}^i (m_{t_j} - l_{t_j}), \forall  i=0,\dots, N-1.
\end{flalign*}
Using the property $m_{t_i}l_{t_i} =0, \quad \forall i=0, \dots, N-1$, we get $|\nu_{i}-\nu_{i-1}| = l_{t_i} +m_{t_i}$  with the convention that $\nu_{-1} =0$ and
\begin{flalign*}
G_T(\Vc) = \hat G_T(\nu) =  x - \sum_{i=0}^{N-1} \lambda |\Delta \nu_{i-1} |  S_{t_i} + \sum_{i=0}^{N-1} \nu_{i} \Delta S_i,
\end{flalign*}
where $\Delta S_i = S_{t_{i+1}} -S_{t_i}$, $\Delta \nu_i= \nu_{i+1} -\nu_{i}$.\\
We then introduce $\hat \Theta^{(\bar m, \bar l)}$ the set of  adapted random variables $(\nu_{i})_{i=0,\dots,N-1}$ such that
\begin{flalign*}
 - \bar m \le \nu_{i}- \nu_{i-1} \le \bar l, \forall i=1,\dots,N-1.
\end{flalign*}
The problem \eqref{argminL2} can be rewritten as it was done in \cite{schweizer1995variance} by finding $\hat \nu=(\hat \nu_i)_{i=0, \dots, N-1}$ satisfactory:
\begin{flalign}
\label{argminL2Bis}
\hat \nu = & \argmin_{ \nu \in \hat \Theta^{(\bar m, \bar l)}}  \E[\big(H- x- \hat G_T(\nu)\big)^2 ].
\end{flalign}
We introduce the spaces $\kappa_i$,  $i=0,\dots,N$ of the $\Fc_{t_i}$-measurable and square integrable random  variables.
We define for  $i \in 0,\dots,N$ , $V_i \in \kappa_i$   as:
\begin{flalign}
\label{VDef}
V_{N} =&  H, \nonumber \\
V_{i} =& \E[ H - \sum_{j=i}^{N-1}  \nu_{j}  \Delta S_{j} +  \lambda \sum_{j=i}^{N-1} | \Delta \nu_{j-1}|  S_{t_j} \quad |\Fc_{t_i}], \forall i =0,\dots,N-1.
\end{flalign}
then
\begin{flalign}
\label{eq:globMin}
\E[(H- x- \hat G_T(\nu))^2 ] = & E[ \big( \left(V_{N} - \nu_{N-1} \Delta S_{N-1}  +  \lambda |\Delta \nu_{N-2}| S_{t_{N-1}} - V_{N-1} \right)+ \\ 
& \sum_{i=2}^{N-1} \left(V_i +  \lambda | \Delta \nu_{i-2}| S_{t_{i-1}}  - \nu_{i-1} \Delta S_{i-1} - V_{i-1} \right) + \\
&  \left( V_{1} + \lambda |\nu_0| S_{t_{0}}  - \nu_{0}  \Delta S_0  -x\right) \big)^2] 
\end{flalign}
Due to the  definition \eqref{VDef}, we have that
\begin{flalign}
\label{eq:Balance}
 E[  V_{i} +  \lambda |\Delta \nu_{i-2} | S_{t_{i-1}} - \nu_{i-1}  \Delta S_{i-1}-V_{i-1}  |\Fc_{t_{i-1}}] =0, \forall i =1,\dots,N,
\end{flalign}
so that
\begin{flalign*}
\E[(H- x- \hat G_T(\nu))^2 ] = & \E[ \E[ \left(V_N - \nu_{N-1} \Delta S_{N-1}  +  \lambda |\Delta \nu_{N-2}| S_{t_{N-1}}- V_{N-1}\right)^2 | \Fc_{t_{N-1}}]+ \\
 & \E[ \sum_{i=2}^{N-1} \left(V_{i} +  \lambda |\Delta \nu_{i-2}| S_{t_{i-1}} - \nu_{i-1} \Delta S_{i-1} -V_{i-1} \right)^2 +\\
  &   \left( V_{1} +  \lambda |\nu_{0}| S_{t_{0}}  - \nu_{0} \Delta S_0 - x  \right)^2]
\end{flalign*}
and iterating the process gives
\begin{flalign*}
\E[(H- x- \hat G_T(\nu))^2 ] = &  \E[ \left(V_{N} - \nu_{N-1}  \Delta S_{N-1} +  \lambda |\Delta \nu_{N-2}| S_{t_{N-1}} - V_{N-1}\right)^2] + \\
& \sum_{i=2}^{N-1} \E[ \left(V_{i} +  \lambda |\Delta \nu_{i-2}| S_{t_{i-1}} - \nu_{i-1} \Delta S_{i-1} -V_{i-1}\right)^2] + \\
& \E[\left(V_{1} +  \lambda | \nu_{0}| S_{t_0} - \nu_{0}  \Delta S_0 - x \right)^2]
\end{flalign*}
Then we can write the problem \eqref{argminL2Bis}  as:
\begin{flalign}
\label{argminTer}
\hat \nu = & \argmin_{ \nu \in \hat \Theta^{(\bar m, \bar l)}}   \E[ \left(V_{N} - \nu_{N-1} \Delta S_{N-1} +  \lambda |\Delta \nu_{N-2}| S_{t_{N-1}}- V_{N-1}\right)^2] + \nonumber \\
& \sum_{i=2}^{N-1} \E[ \left(V_{i} +   \lambda  |\Delta \nu_{i-2}| S_{t_{i-1}} - \nu_{i-1} \Delta S_{i-1} -V_{i-1}\right)^2] + \nonumber \\
& \E[\left(V_{1} +  \lambda |\nu_{0}| S_{t_0} - \nu_{0}  \Delta S_0- x \right)^2]
\end{flalign} 
We introduce the space
\begin{flalign*}
\rho_i^{\bar m, \bar l}(\eta) = & \{ (V, \nu) / 
V , \nu \mbox{ are } \R \mbox{ valued } \Fc_{t_i}\mbox{-adapted with }  - \bar m \le  \nu - \eta  \le \bar l \},
\end{flalign*}
and the space
\begin{flalign*}
\hat \rho_i^{\bar m, \bar l}(\eta) = & \{ (V, \nu_i,\dots, \nu_{N-1}) / 
 V  \mbox{ is } \R \mbox{ valued, } \Fc_{t_i}\mbox{-adapted , the }  \nu_j , j \ge i \mbox{ are } \R \mbox{ valued } \\
 & \Fc_{t_j}\mbox{-adapted with }   \bar m \le  \nu_i - \eta  \le \bar l   , \bar m \le  \nu_{j+1} - \nu_j  \le \bar l \mbox{ for }   i \le j < N-1\},
\end{flalign*}

As in the scheme introduced in  \cite{bender2007forward} to improve the methodology proposed in \cite{gobet2005regression} to solve Backward Stochastic Differential Equations, we can propose an  algorithm where the update for $\bar R$ is taken $\omega$ by $\omega$ and stores the optimal trading payoff function on each trajectory. Then $\bar R$ satisfies the date $t_{i}$ with an asset value $S_{t_i}$  for an investment $\nu_{i-1}$ chosen at the date $t_{i-1}$:
\begin{align*}
\bar R(t_i, S_{t_i}, \nu_{i-1}) = & H - \sum_{j=i}^{N-1}  \nu_{j}  \Delta S_{j} +  \lambda \sum_{j=i}^{N-1} | \Delta \nu_{j-1}|  S_{t_j},\\
& = R(t_{i+1}, S_{t_{i+1}}, \nu_{i}) -\nu_{i}  \Delta S_{i} +  \lambda | \Delta \nu_{i-1}|  S_{t_i}, 
\end{align*}
and at the date $t_i$ according to the equation \eqref{eq:globMin} the optimal control is the control $\nu$ associated with the minimization  problem:
\begin{align*}
\min_{(V,\nu) \in \rho_{i}^{\bar m, \bar l}(\nu_{i-1})} \E[ (\bar R(t_{i+1}, S_{t_{i+1}}, \nu) -  \nu  \Delta S_{i}
+ \lambda |\nu-\nu_{i-1}| S_{t_{i}} - V )^ 2 | \Fc_{t_{i}}]
\end{align*}
This leads to the ~\ref{algoMeanVar3} algorithm.
\begin{algorithm}[h]
\caption{\label{algoMeanVar3}Backward resolution for $\Lc^2$ minimization problem avoiding conditional expectation iteration.}
\begin{algorithmic}[1]
\State  $ \bar R(t_{N}, S_{t_{N-1}}(\omega), \nu_{N-1})  =  H(\omega),  \quad \forall \nu_{N-1}$
\For{$i = N, 2$}
\State   \begin{eqnarray}
(\tilde V(t_{i-1}, S_{t_{i-1}}, \nu_{i-2}),\nu_{i-1}) = & \argmin_{ (V,\nu) \in \rho_{i-1}^{\bar m, \bar l}(\nu_{i-2})}  \E[ (\bar R(t_i, S_{t_i}, \nu) -  \nonumber \\ & \nu  \Delta S_{i-1}
+ \lambda |\nu-\nu_{i-2}| S_{t_{i-1}} - V )^ 2 | \Fc_{t_{i-1}}]
\label{argminBack} \end{eqnarray}
\State $  \begin{array}{ll}  \bar R(t_{i-1}, S_{t_{i-1}}, \nu_{i-2}) = &  \bar R(t_{i}, S_{t_{i}}, \nu_{i-1}) - \nu_{i-1}   \Delta S_{i-1}
+  \lambda |\Delta \nu_{i-2}| S_{t_{i-1}}
\end{array} $
\EndFor
\State $ \begin{array}{ll}
\nu_{0} = & \argmin_{\nu \in [-\bar m,\bar l]}  \E[ ( \bar R(t_1, S_{t_1}, \nu) + \lambda| \nu| S_{t_0} - \nu \Delta S_{0} - x)^2  ]
\end{array} $
\end{algorithmic}
\end{algorithm}

\begin{Remark}
\label{remarkMeanVar}
In order to deal with the case of the average variance coverage which consists in finding the optimal strategy and the initial wealth to hedge the contingent claim, the last line of the~\ref{algoMeanVar3}  algorithm is replaced by
\begin{flalign*}
(\tilde V,\nu_{0}) = & \argmin_{(V,\nu)}  \E[ (V(t_1,S_{t_1}, \nu) + \lambda |\nu| S_{t_0} - \nu \Delta S_{0} - V)^2 + R(t_{1}, S_{t_{1}}, \nu) ],
\end{flalign*}
and last line of Algorithm~\ref{algoMeanVar3} by
\begin{flalign*}
(\tilde V,\nu_{0}) =  \argmin_{ (V,\nu) \in \R \times [-\bar m,\bar l]}  \E[ ( \bar R(t_1, S_{t_1}, \nu) + \lambda | \nu| S_{t_0} - \nu \Delta S_{0} - V)^2  ].
\end{flalign*}
\end{Remark}
\begin{Remark}
In the two algorithms presented an argmin must be carried out: a discretization in $\nu_{i-2}$ must be carried out on a grid $[\nu_{i-1}-m,\nu_{i-1}+l]$.
\end{Remark}
\section{Practical algorithm based on Algorithm \ref{algoMeanVar3}}
From the theoretical Algorithm~\ref{algoMeanVar3}, we aim to obtain an efficient implementation based on a representation of the function $\tilde V$ as a function of time, $S_t$ and the position $\nu_t$ in plan assets.
\begin{itemize}
    \item In order to represent the dependency in the hedging position, we introduce a time dependent grid  
\begin{flalign*}
\Qc_{i} :=  (\xi k)_{k=- (i+1)\lfloor \frac{\bar m}{\xi} \rfloor,\dots, (i+1)\lfloor \frac{\bar l}{\xi} \rfloor} 
\end{flalign*}
where $\xi$ is the mesh size associated with the set of grids $(\Qc_i)_{i=0,N}$ and, if possible, chosen such that $\frac{\bar l}{\xi} =\lfloor \frac{\bar l}{\xi} \rfloor$ and $\frac{\bar m}{\xi}= \lfloor \frac{\bar m}{\xi} \rfloor$.
\item To represent the dependency in $S_t$ we will use a Monte Carlo method using the simulated path $\left( (S_{t_i}^{(j)})_{i=0,\dots, N}\right)_{j=1,\dots, M}$ and calculate the $\argmin$ in the equation \eqref{argminBack} using a methodology similar so that described in \cite{bouchard2012monte}:  
suppose we are given at each date $t_i$ $(D^i_q)_{q=1,\dots,Q}$ a partition of $[ \min_{j=1,M} S_{t_i}^{(j)}, \max_{j=1,M} S_{t_i}^{(j)}]$ so that each cell contains the same number of samples. We use the cells $Q$  $(D^i_q)_{q=1,\dots,Q}$ to represent the dependency of $\tilde V$ and $\nu$ in the $S_{t_i}$ variable.\\
On each cell $q$ we search $\hat V^q$ a linear approximation of the function $\tilde V$ at a given date $t_i$ and for a position $k \xi$ so that
$\hat V^q(t_i,  S, k) = a_i^q + b_i^q S$ is an approximation of $ \tilde V(t_i,S, k \xi)$. On cell $q$ the optimal numeric hedging command $\hat \nu^q(k)$ for a position $k \xi$ can be seen as a sensitivity, so it is natural to look for a constant control per cell $q$  when the value function is represented as a linear function. 
\end{itemize}
Let us denote $(l_i^q(j))_{j=1,\frac{M}{Q}}$ the set of all the samples belonging to the cell $q$ at date $t_i$. On each mesh the optimal control $\hat \nu^q$ is obtained by discretizing the command $\nu$ on a grid $\eta = ( (k+r) \xi  )_{r = - \lfloor \frac{\bar m}{\xi} \rfloor, \dots, \lfloor \frac{\bar l}{\xi} \rfloor}$, and testing the one giving a value $\hat V^q$  minimizing the risk $\Lc^2$ to solve the equation \eqref{argminBack}.\\
The ~\ref{testCommand} algorithm allows to find the optimal $\nu_i^{(j)}(k)$ command using the ~\ref{algoMeanVar3} algorithm at the date $t_i$, for a position of hedging $k \xi$ and for all Monte Carlo simulations $j$. For each command tested on cell $q$ the corresponding function $\hat V^q$ is calculated by regression.
\begin{algorithm}[h]
\caption{\label{testCommand} Optimize minimal hedging position $(\hat \nu_{t_{i}}^{(l)}(k))_{l=1,\dots,M}$ at date $t_{i-1}$}
\begin{algorithmic}[1]
\Procedure{OptimalControl}{ $\bar R(t_{i+1},.,.) , k, S_{t_i}, S_{t_{i+1}}$}
\For{$q=1, Q$}
\State $P=\infty$, 
\For{$k = -\lfloor \frac{\bar m}{\xi} \rfloor, \dots,   \lfloor \frac{\bar l}{\xi} \rfloor $}
\State $ \begin{array}{ll}
(a_i^q,b_i^q ) = \argmin_{ (a,b )\in \R^2}  &  \displaystyle{\sum_{j=1}^{\frac{M}{Q}}}  \big( \bar R(t_{i+1}, S_{t_{i+1}}^{l^q_i(j)}, (k+l) \xi)  - \\& (k+l) \xi \Delta S_{i}^{l^q_i(j)}
+   \\
&  \lambda |l \xi| S_{t_{i}}^{l^q_i(j)} - (a+b S_{t_{i}}^{l^q_i(j)})  \big)^ 2 
\end{array}
$
\State $\begin{array}{ll} \tilde P = &  \displaystyle{\sum_{j=1}^{\frac{M}{Q}}}  \big( \bar R(t_{i+1}, S_{t_{i+1}}^{l^q_i(j)}, (k+l) \xi)  - (k+l) \xi \Delta S_{i}^{l^q_i(j)}
+   \\ &  \lambda |l \xi| S_{t_{i}}^{l^q_i(j)} -  (a_i^q+ b_i^q S_{t_{i}}^{l^q_i(j)}) \big)^2 \end{array}$
\If{ $ \tilde P < P$}
\State $\nu^{q} = k \xi$, $P =  \tilde P$
\EndIf
\EndFor
\For{$j=1,\frac{M}{Q}$}
\State $\hat \nu_{i}^{(l^q_i(j))}(k) = \nu^{q}$
\EndFor
\EndFor
\Return $( \hat \nu_{t_{i}}^{(j)}(k))_{j=1,\dots,M}$ 
\EndProcedure
\end{algorithmic}
\end{algorithm}

\begin{Remark}
It is possible to use a different discretization $\xi$ to define the set $\eta$ and the set $\Qc_{i}$. Then an interpolation is necessary to obtain the values $\bar R$ at a position not belonging to the grid.
An example of using such an interpolation for a gas storage problem following the optimal cash flow generated along Monte Carlo strategies can be found in \cite{warin2012gas}.
\end{Remark}
\begin{Remark}
This algorithm makes it possible to add a certain global constraint on the overall liquidity of the hedging asset. This is achieved by limiting the possible hedge positions to a subset of $\Qc_{i}$ at each date $t_i$.
\end{Remark}

Then, the global discretized version of the~\ref{algoMeanVar3} algorithm is given on the ~\ref{algoMeanVar4} algorithm where $H^{(j)}$ correspond to $j$ the Monte Carlo realization of the gain.
\begin{algorithm}[h]
\caption{\label{algoMeanVar4}Global backward resolution algorithm, optimal control and optimal variance calculation}
\begin{algorithmic}[1]
\For{$\nu \in \Qc_{N-1}$}
\For{$j\in [1,M]$}
\State$ \bar R(t_N ,S_{t_N}^{(j)}, \nu)  =  H^{(j)}$
\EndFor
\EndFor
\For{$i = N, 2$}
\For{$ k \xi \in \Qc_{i-2}$}
\State $(\nu^{(j)}_{i-1}(k))_{j=1,M} =$ OptimalControl$( \bar R(t_i,.,.), k, S_{t_{i-1}}, S_{t_i})$,
\For{$j\in [1,M]$}
\State $  \begin{array}{ll}  \bar R(t_{i-1}, S_{t_{i-1}}^{(j)}, k\xi) = &  \bar R(t_{i}, S_{t_{i}}^{(j)}, \nu_{i-1}^{(j)}(k)) -   \\
& \nu_{i-1}^{(j)}(k)  \Delta S_{i-1}^{(j)}
+  \lambda |\nu_{i-1}^{(j)}(k)-k \xi | S_{t_{i-1}}^{(j)}
\end{array} $
\EndFor
\EndFor
\EndFor
\State $P=\infty$, 
\For{$k = -\lfloor \frac{\bar m}{\xi} \rfloor, \dots, \lfloor \frac{\bar l}{\xi} \rfloor $}
\State $\begin{array}{ll} \tilde P = &  \displaystyle{\sum_{j=1}^{M}}  \big( \bar R(t_1, S_{t_1}^{(j)}, k \xi)  - k \xi \Delta S_{0}^{(j)}
+   \lambda |k|  \xi  S_0 -  x )^2  \end{array}$
\If{ $ \tilde P < P$}
\State $\nu_0 = k \xi$, $P =  \tilde P$
\EndIf
\EndFor
\State $Var =  \frac{1}{M}\sum_{j=1}^M \big( \bar R(t_1,S_{t_1}^{(j)}, \nu_0) - \nu_0 \Delta S_0^{(j)}+\lambda |\nu_0| S_0 -x\big)^2$
\end{algorithmic}
\end{algorithm}

\part{Semi-Lagrangian methods}
For the semi-Lagrangian methods, the C++ API is the only one available (no python API is currently developed). 
\chapter{Theoretical background}
In this part, we return to solving the equation \reff{hjb}.
\section{Notation and regularity results}
\label{notation}
We denote by $\wedge$ the minimum and $ \vee$ the maximum.
We denote by $|\quad | $ the Euclidean norm of a vector, $Q := (0,T] \times \R^d$.
For a bounded function $w$, we define
\begin{eqnarray}
 | w|_0  = \sup_{(t,x) \in Q} | w(t,x)|, &  \quad  & [w]_1 = \sup_{(s,x) \ne (t,y)} \frac{ |w(s,x) -w(t,y)|}{|x-y| + |t-s|^{\frac{1}{2}}} \nonumber
\end{eqnarray}
and  $|w|_1 = | w|_0 +[w]_1 $. $C_1(Q)$ will stand for the space of functions  with a finite  $|\quad |_1$ norm.\\
For  $t$ given, we denote
\begin{eqnarray}
||w(t,.) ||_{\infty} = \sup_{x \in \R^d } | w(t,x)| \nonumber
\end{eqnarray}
We use the classical assumption on the data of \reff{hjb} for a given $\hat K$: 
\begin{eqnarray}
 \sup_a |g|_1 + |\sigma_a|_1 + |b_a|_1 +  |f_a|_1  + | c_a|_1 \le \hat K
\label{coeff}
\end{eqnarray}

A classic result \cite{ishii1990viscosity} gives us the existence and uniqueness of the solution in space of bounded Lipschitz functions:
\begin{Proposition}
If the coefficients of the equation \reff{hjb} satisfy \reff{coeff}, there is a unique viscosity solution of the equation \reff{hjb} belonging to $C_1(Q)$.  If $ u_1 $ and $u_2$ are respectively sub and super solution of the equation \reff{hjb} satisfying $u_1(0,.) \le u_2(0,.)$  then  $u_1 \le u_2$.
\end{Proposition} 
A spatial discretization length of the problem $\Delta x$  being given, thereafter $(i_1 \Delta x ,\dots,i_d \Delta x)$ with $\bar i = (i_1 , \dots, i_d) \in \mathbf{ Z}^d$ will correspond to the coordinates of a mesh $M_{\bar i}$ defining a hyper-cube in dimension $d$.
For an interpolation grid $(\xi_{i})_{i=0,\dots,N} \in [-1,1]^N$, and for a mesh $\bar i$, the point $y_{\bar i, \tilde j}$ with $\tilde j = (j_1, \dots, j_d) \in [0,N]^d$  will have the coordinate
$(\Delta x (i_1 + 0.5 (1+\xi_{j_1})) ,\dots,\Delta x (i_d + 0.5 (1+\xi_{j_d}))$.
We denote $(y_{\bar i, \tilde j})_{\bar i, \tilde j}$ the set of all the points of the grid over the whole domain.\\
We notice that for a regular mesh with constant volume $\Delta x^d$, we have the following relation for all $x \in \R^d$:
\begin{eqnarray}
\min_{\bar i, \tilde j} | x- y_{\bar i, \tilde j}| \le \Delta x.
\label{MaxDist}
\end{eqnarray}
\section{Temporal discretization for the HJB equation}
The equation \reff{hjb} is discretized in time by the scheme proposed by Camilli Falcone \cite{camilli1995approximation}  for a  discretization in time $h$.
\begin{eqnarray}
v_h(t+h,x) & = &  \inf_{a \in \mathop{A}}  \left[ \sum_{i=1}^q \frac{1}{2q} (v_h(t, \phi^{+}_{a, h, i}(t,x)) +  v_h(t, \phi^{-}_{a, h, i}(t,x)) )
  \right. \nonumber \\ 
&  & \left. +  f_a(t,x) h + c_a(t,x) h v_h(t,x) \vphantom{\int_t}  \right]  \nonumber \\
    & := & v_h(t,x)+ \inf_{a \in \mathop{A}}   L_{a,h}(v_h)(t,x)   \label{hjbCamilli}  
\end{eqnarray}

with
\begin{eqnarray}
L_{a,h}(v_h)(t,x) & = & \sum_{i=1}^q \frac{1}{2q} (v_h(t, \phi^{+}_{a, h, i}(t,x)) + v_h(t, \phi^{-}_{a, h, i}(t,x)) -  2 v_h(t,x))  \nonumber \\
              &    &  + h c_a(t,x) v_h(t,x)+ h f_a(t,x) \nonumber \\
\phi^{+}_{a, h, i}(t,x) & =& x +b_a(t,x) h + (\sigma_a)_i(t,x) \sqrt{h q}  \nonumber\\
\phi^{-}_{a, h, i}(t,x) & =& x +b_a(t,x) h - (\sigma_a)_i(t,x) \sqrt{h q}  \nonumber
\end{eqnarray}
where  $(\sigma_a)_i$ is the $i$-th column of $\sigma_a$. It is noted that it is also possible to choose other types of discretization in the same style as those defined
in \cite{munos2005consistency}.\\
In order to define the solution at each date, a condition on the value chosen for $v_h$ between $0$ and $h$ is required. We choose a temporal linear interpolation once the solution has been calculated at the date  $h$:
\begin{eqnarray}
v_h(t,x) = (1- \frac{t}{h})  g(x)+  \frac{t}{h} v_h(h,x), \forall t \in [0,h]. 
\label{hjbCamilli1}
\end{eqnarray}
We first recall the following result:
\begin{Proposition}
\label{converDisH}
Under the condition on the coefficients given by the equation \reff{coeff}, the solution $v_h$ of the equations \reff{hjbCamilli} and \reff{hjbCamilli1} is uniquely defined and belongs to $C_1(Q)$. We check that if $ h \le (16 \sup_a \left \{ |\sigma_a|_1^2 + | b_a|_1^2 +1 \right \} \wedge 2 \sup_a |c_a|_0)^{-1} $, there is $C$ such that 
\begin{eqnarray}
| v -v_h |_0 \le C h^{\frac{1}{4}}.
\end{eqnarray}
Moreover, there exists $C$ independent of $h$ such that 
\begin{eqnarray}
\label{LipschitVh}
| v_h|_0 & \le & C, \\
|v_h(t,x)-v_h(t,y)| & \le & C |x-y|, \forall (x,y) \in Q^2.
\end{eqnarray}
\end{Proposition}
\section{Space interpolation}
The spacial resolution of the equation \reff{hjbCamilli} is obtained on a grid. The $\phi^{+}$ and $\phi^{-}$  must be calculated using an interpolator
$I$ such that:
\begin{eqnarray*}
  v_h(t, \phi^{+}_{a, h, i}(t,x)) & \simeq &  I(v_h(t,.))(\phi^{+}_{a, h, i}(t,x)), \\
  v_h(t, \phi^{-}_{a, h, i}(t,x)) & \simeq &  I(v_h(t,.))(\phi^{-}_{a, h, i}(t,x)). \\
\end{eqnarray*}
In order to easily prove the convergence of the scheme to the viscosity solution of the problem, the monotony of the scheme is generally required leading
to some linear interpolator slowly converging.
An adaptation to high order interpolator where the function is smooth can be achieved using Legendre grids and Sparse grids with some truncation (see \cite{warin2016some}, \cite{warin2014adaptive}).
\chapter{C++ API}
To perform the interpolation and calculate the semi-Lagrangian value
$$ \sum_{i=1}^q \frac{1}{2q} (v_h(t, \phi^{+}_{a, h, i}(t,x)) + v_h(t, \phi^{-}_{a, h, i}(t,x))$$
a first object \code{SemiLagrangEspCond} is available:
\lstinputlisting[style=CStyle]{../StOpt/StOpt/semilagrangien/SemiLagrangEspCond.h}
Its constructor uses the following arguments:
\begin{itemize}
\item a first \code{p\_interpolator} defines a ``spectral'' interpolator on a grid: this ``spectral'' interpolator is built from a  grid and a function to be interpolated (see section \ref{gridChapter}). In our case, it will be used to interpolate the solution from the previous time step,
\item a second \code{p\_extremalValues} defines for each dimension the minimum and maximum coordinates of the points belonging to the grid,
\item a third one \code{p\_bModifVol} if set to \code{true} allows special processing when the points to be interpolated are  outside the grid: the volatility of the underlying process is modified (keeping the same mean and the same variance) trying to keep points inside the domain (see \cite{warin2016some}).
\end{itemize}
This object has the \code{oneStep} method taking
\begin{itemize}
 \item \code{p\_x} the foot of the characterize (for each dimension),
 \item \code{p\_b} the process trend (for each dimension),
  \item \code{p\_sig} the volatility of the process matrix,
\end{itemize}
such that the interpolation is carried out for a time step $h$ at the points $p\_x + p\_b h \pm p\_sig  \sqrt{h}$. It returns a pair $(a,b)$ where $a$ contains the calculated value if the value $b$ is \code{true}.
When interpolation is not possible, the value $b$ is set to \code{false}.
\\

In order to use the API, an object deriving from the \code{OptimizerSLBase} object must be constructed. This object is used to define the PDE to be solved (with it optimization problem if applicable).
\lstinputlisting[style=CStyle]{../StOpt/StOpt/semilagrangien/OptimizerSLBase.h}
The main methods associated with this object are:
\begin{itemize}
\item \code{stepOptimize} is used to calculate the solution of the PDE at a point.
  \begin{itemize}
    \item It takes a point from the used grid \code{p\_point},
    \item and apply the semi-Lagrangian scheme \code{p\_semiLag} at this point,
    \item on a date given by \code{p\_time}.
  \end{itemize}
  It returns a pair containing:
  \begin{itemize}
  \item the value of the function calculated at \code{p\_point} for each regime,
  \item the optimal control calculated at \code{p\_point} for each control.
  \end{itemize}
  \item \code{stepSimulate} is used when the PDE is associated with an optimization problem and we want to simulate an optimal policy using the function values calculated in the optimization part. The arguments are:
  \begin{itemize}
  \item \code{p\_gridNext} defining the grid used at the next time step,
  \item \code{p\_semiLag} the semi-Lagrangian operator built with an interpolator using the following temporal solution,
  \item \code{p\_state} the vector defining the current state for the current regime,
  \item \code{p\_iReg} the current regime number,
  \item \code{p\_gaussian} is the vector of Gaussian random variables used to calculate the Brownian involved in the underlying process of the current simulation,
   \item \code{p\_phiInP} to the value of the function calculated in optimization at the next time step for the given point,
   \item \code{p\_phiInOut} storing the cost functions: the size of the array is the number of functions to follow in simulation.
  \end{itemize}
\item \code{stepSimulateControl} is used when the PDE is associated with an optimization problem and we want to simulate an optimal policy using the optimal controls calculated in the optimization part. The arguments are:
  \begin{itemize}
  \item \code{p\_gridNext} defining the grid used at the next time step,
  \item \code{p\_controlInterp} a vector (for each control) of interpolators in controls
  \item \code{p\_state} the vector defining the current state for the current regime,
  \item \code{p\_iReg} the current regime number,
  \item \code{p\_gaussian} is the vector of Gaussian random variables used to calculate the Brownian involved in the underlying process of the current simulation.
   \item \code{p\_phiInOut} storing the cost functions: the size of the array is the number of functions to follow in simulation.
  \end{itemize}
On return, the vector \code{p\_state} is modified, the \code{p\_iReg} is modified and the cost function \code{p\_phiInOut} is modified for the current trajectory.
  \item the \code{getCone} method is only relevant if the data distribution (therefore MPI) is used. As argument it takes a vector of size the dimension of the grid. Each component of the vector is an array containing the minimum and maximum coordinate values of the points of the current grid defining a hyper cube $H1$. It returns for each dimension, the min and max coordinates  of the hyper cube $H2$ containing the points that can be reached by applying a command from a point of the grid in $H1$. If no optimization is carried out, it returns the hyper cube $H2$ containing the points that can be reached by the semi-Lagrangian diagram. For an explanation of the parallel formalism, see the \ref{SecParal} chapter.
  \item the \code{getDimensionToSplit} method is only relevant if the data distribution (therefore MPI) is used. The method makes it possible to define the directions to be divided for the distribution of solution on the processors. For each dimension, it returns a Boolean where \code{true} means that the direction is a candidate for splitting,
    
  \item the \code{isNotNeedingBC} allows to define for a point on the limit of the grid if a boundary condition is necessary (\code{true} is returned) or if no limit is necessary (return \code{false}).
\end{itemize}
And example derivation of such an optimizer for a simple stochastic target problem (described in paragraph 5.3.4 in \cite{warin2016some}) is given below:
\lstinputlisting[style=CStyle]{../StOpt/test/c++/tools/semilagrangien/OptimizeSLCase3.cpp}
\section{PDE resolution }
Once the problem is described, temporal recursion can be achieved by using the \code{TransitionStepSemilagrang} object in a sequential resolution of the problem. This object allows to solve the problem in one time step.
\lstinputlisting[style=CStyle]{../StOpt/StOpt/semilagrangien/TransitionStepSemilagrang.h}
It constructor takes the following arguments:
\begin{itemize}
\item \code{p\_gridCurrent} a grid describing the meshes at the current date,
\item \code{p\_gridPrevious} a grid describing the meshes at the previously processed date,
\item \code{p\_optimize} an object derived from \code{OptimizerSLBase} and describing the problem to be solved at a given date and point in the current grid.
\end{itemize}
A first method \code{oneStep} takes the following arguments:
\begin{itemize}
\item \code{p\_phiIn} describes for each regime the solution previously calculated on the grid at the previous time,
\item \code{p\_time} is the current time step,
\item \code{p\_boundaryFunc} is a function giving the Dirichlet solution of the problem according to the number of regimes and the position on the boundary.
\end{itemize}
It returns an estimate of the solution at the current date on the current grid for all the regimes and an estimate of the optimal control calculated for all the controls.
\\
A last method \code{dumpValues} allows to dump calculated the solution \code{p\_phiIn} at step \code{p\_istep+1} and optimal control at step \code{p\_istep} in a \code{p\_ar} archive.\\
A version using the distribution of data and calculations can be found in the  
\href{run:../StOpt/StOpt/semilagrangien/TransitionStepSemilagrangDist.h}{\code{TransitionStepSemilagrangDist}} object.
An example of sequential temporal recursion can be found in the function \href{run:../StOpt/test/c++/tools/semilagrangien/semiLagrangianTime.cpp}{\code{semiLagrangianTime}} and an example with distribution can be found in the \href{run:../StOpt/test/c++/tools/semilagrangien/semiLagrangianTimeDist.cpp}{\code{semiLagrangianTimeDist}} function.
In the two functions developed in the test chapter, the analytical solution of the problem is known and compared to the numerical estimate obtained with the semi-Lagrangian method.
\begin{table}
  \centering
  \caption{ Which object \code{TransitionStepSemilagrang} to use depending on the grid used and the type of parallelization used.}
  \scalebox{0.8}{
  \begin{tabular}{|c|c|c|}
    \hline
    &   Full grid   & Sparse grid \\ \hline
    Sequential                     &   \code{TransitionStepSemilagrang}          &  \code{TransitionStepSemilagrang}     \\   \hline
    Parallelization on calculations&   \code{TransitionStepSemilagrang}          &  \code{TransitionStepSemilagrang}      \\                                     
    threads and MPI                &            &                                                  \\  \hline
    Distribution of calculations &    \code{TransitionStepSemilagrangDist}       &  Not available     \\   
    and data  (MPI)                   &    &  \\  \hline
  \end{tabular}
  }
 \end{table}


\section{Simulation framework}
Once the optimal controls and value functions have been calculated, the optimal policy can be simulated using the function values (recalculate the optimal control for each simulation) or by directly using the optimal controls calculated in optimization
\begin{itemize}
\item \underline{Calculate the optimal strategy in simulation }  \\ \underline{using the function values calculated in optimization}: \\
In order to simulate an optimal policy step, a \href{run:../StOpt/StOpt/semilagrangien/SimulateStepSemilagrangDist.h} {\code{SimulateStepSemilagrangDist}} object is provided with constructor
\begin{lstlisting}[style=CStyle]
    SimulateStepSemilagrangDist(gs::BinaryFileArchive &p_ar,  const int &p_iStep,  const std::string &p_name ,
                               const std::shared_ptr<FullGrid> &p_gridNext, const  std::shared_ptr<OptimizerSLBase > &p_pOptimize ,
                               const bool &p_bOneFile);
\end{lstlisting}
where
\begin{itemize}
\item \code{p\_ar} is the binary archive where the continuation values are stored,
\item \code{p\_iStep} is the number associated with the current time step (0 at the start date of the simulation, the number is increased by one at each simulated time step),
\item \code{p\_name} is the base name to search for in the archive,
\item \code{p\_GridNext} is the grid at the next time step (\code{p\_iStep+1}),
\item \code{p\_Optimize} is the Optimizer describing the passage from one time step to the next,
\item \code{p\_OneFile} is equal to \code{true} if only one archive is used to store continuation values.
\end{itemize}
\begin{Remark}
A version without data distribution but only multithreaded and parallel with MPI on data is available with the object \href{run:../StOpt/StOpt/semilagrangien/SimulateStepSemilagrang.h} {\code{SimulateStepSemilagrang}}.
\end{Remark}
This object implements the \code{oneStep} method 
\begin{lstlisting}[style=CStyle]
void oneStep(const Eigen::ArrayXXd & p_gaussian,Eigen::ArrayXXd &p_statevector , Eigen::ArrayXi   &p_iReg, Eigen::ArrayXd  &p_phiInOuts)
\end{lstlisting}
where:
\begin{itemize}
\item \code{p\_gaussian} is a two-dimensional array (number of Brownian  in the modeling by the number of Monte Carlo simulations).
\item \code{p\_statevector} store continuous state (size of continuous state per number of simulations)
 \item \code{p\_iReg} for each simulation, gives the current regime number, 
\item \code{p\_phiInOut}  stores the gain/cost functions for all simulations: it is updated by the function call. The size of the array is $(nb, nbSimul)$ where $nb$  is given by the \code{getSimuFuncSize} method of the optimizer and $ nbSimul $ the number of Monte Carlo simulations.
\end{itemize}
\begin{Remark}
The previous object \code{SimulateStepSemilagrangDist} is used with MPI for  high dimensional problems. In the case of small dimension (less than or equal to three), parallelization with MPI or the sequential calculations can be carried out by the object \code{SimulateStepSemilagrang}.
\end{Remark}
An example of using this method to simulate an optimal policy with distribution is given below:
\lstinputlisting[style=CStyle]{../StOpt/test/c++/tools/semilagrangien/semiLagrangianSimuDist.cpp}
A sequential or parallel version on the calculations of the previous example is given in the file \href{run:../StOpt/test/c++/tools/semilagrangien/semiLagrangianSimuDist.cpp}{\code{semiLagrangianSimuDist.cpp}}.


\item  \underline{Calculate the optimal strategy in simulation} \\  \underline{ by interpolation of the optimal control calculated in optimization}:\\
In order to simulate an optimal policy step, a \href{run:../StOpt/StOpt/semilagrangien/SimulateStepSemilagrangControlDist.h} {\code{SimulateStepSemilagrangControlDist}} object is provided with constructor
\begin{lstlisting}[style=CStyle]
    SimulateStepSemilagrangControlDist(gs::BinaryFileArchive &p_ar,  const int &p_iStep,  const std::string &p_name ,
                                      const std::shared_ptr<FullGrid>   &p_gridCur,
                                      const std::shared_ptr<FullGrid> &p_gridNext,
                                      const std::shared_ptr<OptimizerSLBase > &p_pOptimize ,
                                      const bool &p_bOneFile)
\end{lstlisting}
where
\begin{itemize}
\item \code{p\_ar} is the binary archive where the continuation values are stored,
\item \code{p\_iStep} is the number associated with the current time step (0 at the start date of simulation, the number is increased by one at each simulated time step),
\item \code{p\_name} is the base name to search for in the archive,
\item \code{p\_GridCur} is the grid at the current time step (\code{p\_iStep}),
\item \code{p\_GridNext} is the grid at the next time step (\code{p\_iStep+1}),
\item \code{p\_Optimize} is the Optimizer describing the passage from one time step to the next,
\item \code{p\_OneFile} is equal to \code{true} if only one archive is used to store continuation values.
\end{itemize}
\begin{Remark}
The previous object \code{SimulateStepSemilagrangControlDist} is used with the MPI distribution of data for  high dimensional problems. In the case of small dimension (less than or equal to three), the parallelization with MPI or the sequential calculations can be carried out by the object \code{SimulateStepSemilagrangControl}.
\end{Remark}
This object implements the method \code{oneStep}
\begin{lstlisting}[style=CStyle]
void oneStep((const Eigen::ArrayXXd & p_gaussian, Eigen::ArrayXXd &p_statevector , Eigen::ArrayXi   &p_iReg, Eigen::ArrayXd  &p_phiInOuts)
\end{lstlisting}
where:
\begin{itemize}
\item \code{p\_gaussian} is a two dimensional array (number of Brownian in the modeling by the number of Monte Carlo simulations).
\item \code{p\_statevector} store continuous state (size of continuous state per number of simulations)
 \item \code{p\_iReg} for each simulation gives the current regime number, 
\item \code{p\_phiInOut}  stores the gain/cost functions for all simulations: it is updated by the function call. The size of the array is $(nb, nbSimul)$ where $nb$  is given by the \code{getSimuFuncSize} method of the optimizer and $ nbSimul $ the number of Monte Carlo simulations.
\end{itemize}

An example of using this method to simulate an optimal policy with distribution is given below:
\lstinputlisting[style=CStyle]{../StOpt/test/c++/tools/semilagrangien/semiLagrangianSimuControlDist.cpp}
The sequential version (or parallelized on calculations) of the preceding example is given in the file \href{run:../StOpt/test/c++/tools/semilagrangien/semiLagrangianSimuControl.cpp}{\code{semiLagrangianSimuControl.cpp}}.
\begin{Remark}
In the previous example, we assume that only one function is tracked in simulation, and that we return an average for that function value accordingly.
\end{Remark}
\end{itemize}

\begin{sidewaystable}
 \centering
  %\label{tabOptSim}
 \caption{ Which simulation object to use depending on the TransitionStepSemilagrang object used.}
    \scalebox{0.8}{
  \begin{tabular}{|c|c|c|c|}
    \hline
                                       &  \code{TransitionStepSemilagrang} & \code{TransitionStepSemilagrangDist} &  \code{TransitionStepSemilagrangDist} \\
                                       &                                   & \code{bOneFile = true} &  \code{bOneFile = false}      \\   \hline
  \code{SimulateStepSemilagrang}            &   Yes                        &     Yes              &   No    \\   \hline
  \code{SimulateStepSemilagrangControl}     &   Yes                        &     Yes              &   No    \\ \hline
  \code{SimulateStepSemilagrangDist}        &   No                         &     Yes              &   Yes   \\   \hline
  \code{SimulateStepSemilagrangControlDist} &   No                         &     Yes              &   Yes   \\ \hline
  \end{tabular}
   }
\end{sidewaystable}




\part{An example with both dynamic programming with regression and PDE}
\label{part:NonEm}
In this chapter we give an example where dynamic programming with regressions and  PDE can be used. It allows to compare the resolution and the solution obtained by both methods.\\
In this example we take the following notations:
\begin{itemize}
\item $D_t$ is a demand process (in electricity) with an Ornstein--Uhlenbeck dynamic:
  \beqs
  dD_t = \alpha( m -D_t) dt + \sigma dW_t,
  \enqs
\item $Q_t$ is the cumulative carbon emission due to the production of electricity to meet demand,
  \beqs
  d Q_t = (D_t-L_t)^{+} dt,
  \enqs
\item $L_t$ the total investment capacity in non-emissive technology to produce electricity
  \beqs
  L_t = \int_0^t l_s ds
  \enqs
  where $l_s$ is an investment intensity in non-emissive technology at the date $s$,
\item $Y_t$ is the carbon price where
  \beqs
   Y_t = \E_t( \lambda 1_{Q_T \ge H}),
   \enqs
   with $\lambda$ and $H$ given.
\end{itemize}
We introduce the following functions:
\begin{itemize}
\item the function of the price of electricity which is a function of the demand and the global investment of non-emitting technology.
  \beqs
  p_t = (1+D_t)^2 -L_t,
  \enqs
\item the profit function  by selling electricity is  given by
  \beqs
  \Pi(D_t,L_t)=  p_t D_t - (D_t-L_t)^{+},
  \enqs
\item $\tilde{c}(l_t,L_t)$ is the investment cost for new non-emissive technology capabilities.
  \beqs
  \tilde{c}(l,L) =  \bar{\beta}(c_{\infty} + (c_0 -c_{\infty}) e^{\beta L}) (1+l)l
  \enqs
\end{itemize}
The value of the company that sells electricity is given by $V(t,D_t,Q_t,L_t)$. It satisfies the coupling equations:
\begin{equation}
\left \{ \begin{array}{l}
  \partial_t v +  \alpha (m- D) \partial_Dv + \frac{1}{2} \sigma^2 \partial^2_{DD} v + (D-L)^{+} \partial_Q v + \Pi(D,L) \\
  + s L^{1-\alpha}  - y (D-L)^{+} + \sup_l \{l \partial_L v - \tilde{c}(l,L) \} =0  \label{eqVal} \\
  v_T =0
  \end{array}
  \right.
\end{equation}
and the carbon price $y(t,D_t,Q_t,L_t)$ is given by:
\begin{equation}
  \left \{ \begin{array}{l}
    \partial_t y +  \alpha (m- D) \partial_Dy + \frac{1}{2} \sigma^2 \partial^2_{DD} y + (D-L)^{+} \partial_Q y +  l^{*} \partial_L y  =0 \\
  y_T = \lambda 1_{Q_T\ge K} \end{array}
  \right.
  \end{equation}
and $l^{*}$ is the optimal control in equation \reff{eqVal}.
The preceding equation can be solved with the semi-Lagrangian method.\\
  After a temporal discretization with a step $\delta t$ a dynamic programming equation can be given by
  \begin{eqnarray}
    v(T-\delta t,D,Q,L) & =  & \sup_l (\Pi(D,L)+ s L^{1-\alpha}  - y_{T- \delta t} (D-L)^{+} - \tilde{c}(l,L)) \delta t  +  \nonumber\\
    & & \E_{T-\delta t}( V(T,D_T^{T-\delta t,D},Q+(D-L)^{+} \delta t ,L + l\delta t)) \label{eqPDV} \\
    Y(T-\delta t,D,Q,L)  & =& \E_{T-\delta t}( Y(T,D_T^{T-\delta t,D},Q+(D-L)^{+} \delta t ,L + l^{*} \delta t)) \label{eqPDY} 
  \end{eqnarray}
The previous equations \reff{eqPDV} and \reff{eqPDY} can be solved with regression methods.\\
In order to use the frameworks previously developed  in parallel, we must define common variables for both method.
  \begin{itemize}
  \item The number of regimes to use (obtained by the \code{getNbRegime} method) is 2: one to store the value $v$, one for the value $y$,
  \item In the example we want to follow during the simulations the values of the functions $v$ and $y$ so we fix the number of functions obtained by the \code{getSimuFuncSize} method to 2.
  \item In order to test the controls in optimization and simulation we define a maximum investment intensity \code{lMax} and a discretization step to test the controls \code{lStep}.
  \end{itemize}
In the following, we store the optimal functions in optimization and recalculate the optimal control in simulation.
  \section{Dynamic programming with the regression approach}
All we have to do is specify an optimizer
 (\href{run:../StOpt/test/c++/tools/dp/OptimizeDPEmissive.h}{\code{OptimizeDPEmissive}}) defining the methods used to optimize and simulate, and the \code{getCone} method for parallelization:
 \lstinputlisting[style=CStyle]{../StOpt/test/c++/tools/dp/OptimizeDPEmissive.cpp}
This 2-dimensional case for inventories can be handled by interpolation on the full two-dimensional grid and on a two-dimensional sparse grid.
The two versions of the resolution are given in a test case (\href{run:../StOpt/test/c++/functional/functional/testDPNonEmissive.cpp}{\code{testDPNonEmissive.cpp}}).

  \section{The PDE approach}
The same can be done with the PDE approach using a simulator for the OU demand (\href{run:../StOpt/test/c++/tools/simulators/AR1Simulator.h}{\code{AR1Simulator}}).
We then define an optimizer (\href{run:../StOpt/test/c++/tools/semilagrangien/OptimizeSLEmissive.h}{\code{OptimizeSLEmissive}}) and the methods used to optimize and simulate, and the method \code{getCone} for parallelization:
  \lstinputlisting[style=CStyle]{../StOpt/test/c++/tools/semilagrangien/OptimizeSLEmissive.cpp}
  The three dimensional grids used can be some full grids or some sparse grids. Both versions of the resolution can be
  found in a test case (\href{run:../StOpt/test/c++/functional/testSLNonEmissive.cpp}{\code{testSLNonEmissive.cpp}}).
 




\part{Stochastic Dual Dynamic Programming}


\chapter{SDDP algorithm}
\label{chap:SDDP}

\section{Some general points about SDDP}
Stochastic Dual Dynamic Programming (SDDP) is an approximate dynamic programming algorithm developed by Pereira and Pinto in 1991~\cite{pereira1991multi}.

To describe the operation of SDDP, we will consider a class of linear programs which have steps $T+1$ stages denoted $\{0,1,\dots,t,\dots,T\}$. We limit our class of problems to linear programs with a relatively complete recourse: the feasible region of the linear program at each step is nonempty and bounded.

Let us formalize the variables and constraints used in the SDDP problem. 

\paragraph{Notations used\\}
The notations described here are used in the general case.   
\begin{itemize}
\item $x_t$ is the decision variable at time $t$. If the data process is step-independent, $x_t$ also designates the state at time $t+1$.
\item $\omega_t \in \Omega_t$ is the random data process at time $t$, where $\Omega_t$ is the random data set.
\item $c_t$ is the vector of cost at time $t$.
\item $A_t$ and $E_t$ denote matrices of constraints.
\item $Q_t(x_{t-1},\omega_t)$ is the expected value of the problem at time $t$, knowing the state $x_{t-1}$ and the random data $\omega_t$.
\item $ \mathscr{Q}_t(x_{t-1}) = \mathbb{E} \lbrack Q_t(x_{t-1},\omega_t) \rbrack $.
\end{itemize}

\paragraph{Decision process \\}
The random data process $\omega_t$ is discovered gradually. Thus from an initial state $x_0$, the state variables $(x_t)_{t \in \{0,1,\dots,T\}}$ are determined in a non-anticipatory manner. The scheme is as follows: \newline

$x_0$ $\rightarrow$ observation of $\omega_1$  $\rightarrow$ decision of $x_1$ \dots \newline
$\indent \indent \rightarrow$ decision of $x_{T-1}$ $\rightarrow$ observation of $\omega_T$  $\rightarrow$ decision of $x_T$ \\
 
A rigorous formulation of the multi-step stochastic linear program to solve is as follows: 

\begin{equation}
\label{ProblemeGeneral}
V^* = 
\min_{\substack{A_0x_0 = \omega_0 \\ x_0 \geq 0}}c_0^{\top}x_0 +  \mathbb{E} \left \lbrack \min_{\substack{E_1x_0+A_1x_1 = \omega_1 \\ x_1 \geq 0}}c_1^{\top}x_1  + \mathbb{E} \left \lbrack \dots + \mathbb{E} \left\lbrack \min_{\substack{E_Tx_{T-1}+A_Tx_T = \omega_T \\ x_T \geq 0}} c_T^{\top}x_T \right\rbrack \right\rbrack\right\rbrack
\end{equation}

The deterministic equivalent of this problem (\ref{ProblemeGeneral}) is obtained by discretizing $\omega_t$ (or by directly using $\omega_t$ if discrete). The number of variables in this problem increases exponentially with the number of steps. It cannot be solved directly even if $T$ or $(\Omega_t)_{t \in \{0,1,\dots,T\}}$ are of reasonable size.

\paragraph{Dynamic programming principle \\}
Dynamic programming consists of dividing the problem (\ref{ProblemeGeneral}) into a series of subproblems delimited by a state variable. The goal is to calculate backwards the functions $Q_t$ and $\mathscr{Q}_{t}$. They fulfill the following equations:

\begin{eqnarray}\label{FctValInt}
{\mathcal [LP_t]}
\begin{cases}
     &Q_t(x_{t-1},\omega_t) = \min c_t^{\top}x_t +  \mathscr{Q}_{t+1}(x_{t}) \\
     s.c. \qquad &\quad A_tx_t = \omega_t - E_t x_{t-1}, \quad \lbrack\pi_t(\omega_t)\rbrack\\
\qquad &\quad x_t\geqslant 0
\end{cases}
\end{eqnarray}
\begin{equation}
\label{FctBel}
 \mathscr{Q}_t(x_{t-1}) = \mathbb{E} \lbrack Q_t(x_{t-1},\omega_t)\rbrack
\end{equation}

 
The function $Q(x_{t-1},\omega_t) $ represents the expected value of a future cost knowing the state $x_{t-1}$ and the random data $\omega_t$. $\mathscr{Q}_t(x_{t-1})$ is the expected value of the future cost knowing the state $x_{t-1}$. The dynamic programming principle guarantees that $V^* = \mathscr{Q}_1(x_0)$.

Given $\mathscr{Q}_T(\cdot)$, the successive computations are achieved backwards switching between the resolution of the linear sub-problem \eqref{FctValInt} and the computation of \eqref{FctBel}.

The implementation of dynamic programming consists in successively approximating the two value functions by equations (\ref{FctValInt} - \ref{FctBel}) by discretizing the state space and by solving the linear subproblems. The number of discretization points increases exponentially with the dimension of the state vector and becomes enormous for our applications (``curse of dimensionality''). Additionally, a linear approximation of $\mathscr{Q}_{t+1}(x_{t})$ must be available to convert the transition problem to LP.


\paragraph{SDDP algorithm \\}
SDDP is a method used to solve a multistep stochastic problem described in \cite{pereira1991multi}. SDDP is based on Benders decomposition described in \cite{benders2005partitioning}. Please note that SDDP was developed in order to solve hydro-thermal scheduling problem. 

SDDP limits the curse of dimensionality by avoiding \textit{a priori} a complete discretization of the state space. Each SDDP iteration is a two-step process. The first step consists in generating a sequence of realistic states  $x_t^*$ from which in the second step the value functions are estimated in their neighborhood. By repeating these two steps successively, the approximation of the value function becomes more and more precise. SDDP is also composed of two passes calculated alternately:

\begin{itemize}
\item one pass back: the objective is to improve the number of cut Benders in the vicinity of well-chosen candidate states. It alsoprovides  a lower limit of the optimal cost.

\item a forward pass: the goal is to provide a set of new candidate states. An estimate of the upper bound of the optimal cost is also calculated.
\end{itemize}

On the other hand, the SDDP method is based on the form of the future value function $\mathscr{Q}_t(x_{t-1})$. Indeed within the framework of a linear problem with complete recourse, the function value is convex and linear by pieces. It can therefore be approached by taking the supremum of a family of minor affine functions. These affine functions are called  \textit{optimality cuts} or \textit{Benders cuts}. 

\section{A method, different algorithms}
The method implemented in this library is based on the different situations presented in a technical report of PSR program \cite{pereira1999application} where three different cases of the basic problem are solved by SDDP. All three cases are implemented in the library. Other cases could be added to those that exist in the future.

\paragraph{Notations \\}
These notations will be used to present the different algorithms of SDDP.

\begin{itemize}
\item $\bar{z}$ designates the optimal cost obtained in forward pass.
\item $\underline{z}$ denotes the optimal cost obtained in return.
\item $\beta_{t}^j$ denotes the slope of the $j^{th}$ Benders cut.
\item $\alpha_{t}^j$ denotes the intercept of the  $j^{th}$ Benders cut.
\end{itemize}
\subsection{The basic case}
To describe this case, the notations above are used. We focus on multistep stochastic problems with the following properties.

\begin{itemize}
\item Random quantities at different stages are independent.
\item Random quantities at time $t$ are summarized in $\omega_t$.
\item At each step, the linear subproblem solution space is nonempty and bounded. 
\end{itemize}
In this case, the functions $\mathscr{Q}_t(\cdot)$ are convex. The primal and dual solutions of the linear problem exist and define optimal cuts. We can now describe precisely how the implemented algorithm works.

\paragraph{Initialization \\}
\label{init}
The following values are fixed:
\begin{itemize}
\item $\{0,1,\dots,T\}$, the set of steps, where $T$ is the time horizon.
\item $n = 0$, is the counter of the number of iterations (\textit{backward-forward}). $n$ is incremented at the end of each iteration.
\item $p \in \mathbb{R}$, the precision to be reached for the convergence test.
\item $n_{step} \in \mathbb{N}$, the number of iterations performed between 2 convergence tests.
\item $n_{iterMax} \in \mathbb{N}$, the maximum number of iterations.  
\item $x_0 \in \mathbb{R}_+^n$, the initial state of the vector.  
\item $L \in \mathbb{N}$, the number of scenarios used in the backward pass.
\item $G \in \mathbb{N}$, the number of scenarios used in the forward pass. It also gives the number of new cuts calculated at each iteration (\textit{backward-forward}) and the number of states near which the Benders cuts are calculated. 

\end{itemize}
\paragraph{Forward pass\\}
The purpose of this pass is to explore new feasible vector state and to obtain an estimate of the upper limit of the optimal cost. To this end, the current strategy is simulated for a set of $G$ scenarios. The set of scenarios can be historical chronicles or raffles.
The ~\ref{alg:forward} algorithm presents the forward pass at the $n$-th iteration of the SDDP method.

\begin{algorithm}[h!]
 \begin{algorithmic}[1]
 \State Simulate defines $\left\lbrace\left(\omega_t^g \right), t \in \lbrace 1,\dots,T \rbrace \right\rbrace$ ofscenarios also distributed: for $g \in \Omega^{\mathscr{G}} = \{1,\dots,G\}$. \;
 \For{$g \in \Omega_{\mathscr{G}}$}
 \State Solve the following linear subproblem. \;
  \begin{eqnarray}
   {\mathcal [AP_{0}^n]} 
	\begin{cases}
      &Q_0 = \min\limits_{x_0,\theta_{1}} c_0^{\top}x_0 +  \theta_{1}\\
     u.c. \qquad &\quad A_0x_0 = \omega_0 , 						\quad\lbrack\pi_0(\omega_0)\rbrack\\
	\qquad &\quad x_0\geqslant 0 \\
	\qquad &\quad \theta_{1} +  (\beta_{1}^j)^{\top} x_0 \geqslant \alpha_{1}^j, \quad j \in \{1,\dots, G,\dots, nG \}
	\end{cases}
  \end{eqnarray}
  \State Store the primal solution $(x_0^g)$ of the problem $\mathcal [AP_{0,g}^n]$.
  \For{$t \in \{1,\dots,T\}$}
    \State Solve the following linear subproblem. \;
   \begin{eqnarray}
   {\mathcal [AP_{t,g}^n]} 
   \begin{cases}
     &Q_t^g(x_{t-1}^g,\omega_t^g) = \min\limits_{x_t,\theta_{t+1}} c_t^{\top}x_t +  \theta_{t+1}\\
     s.c. \qquad &\quad A_tx_t = \omega_t^g - E_t x_{t-1}^g, 		\quad\lbrack\pi_t(\omega_t^g)\rbrack\\
     \qquad &\quad x_t\geqslant 0 \\
     \qquad &\quad \theta_{t+1} +  (\beta_{t+1}^j)^{\top} x_t \geqslant \alpha_{t+1}^j, \quad j \in \{1,\dots, G,\dots, nG \}
   \end{cases}
   \end{eqnarray}
   \State Store the primal solution $(x_t^g)$ of the problem $\mathcal [AP_{t,g}^n]$.
   \EndFor
    \State Calculate the cost of the scenario $g$, at iteration $n$: $\bar{z}^g_n = \sum_{t=0}^T c_t x_t^g$.\;
  \EndFor
  \State Calculate the total cost of the forward pass at iteration $n$: $\bar{z}_n = \frac{1}{G}\sum_{g=1}^G \bar{z}^g_n $.
  \end{algorithmic}
 \caption{Run of forward pass ($n^{th}$ iteration)}
 \label{alg:forward}
\end{algorithm}
%
\paragraph{Backward pass\\}
The purpose of the backward pass is to add, at each stage, a set of new Benders cuts and to provide a new lower bound estimate of the optimal operational cost. For that, we have a set of scenarios of the random quantities (the dimension of the set is $L$) recorded during the initialization.
At each time step cuts $G$ are added using the states $G$ visited  $(x_t^g)_{g=1,\dots,G}$ obtained during the passage forward.
The ~\ref{alg:backward} algorithm presents the backward pass.

 \begin{algorithm}[h!]
   \begin{algorithmic}[1]
\For{$t = T, T-1, \dots,1 $}
 \For{$x_{t-1}^g$, $g \in \{1,\dots,G\}$}
  \For{$\omega_t^l$, $l \in \{1,\dots,L\}$}
   \longState{Solve the following linear subproblem. \;
   \begin{eqnarray}
   {\mathcal [AP_{t,l}^{n,g}]} 
	\begin{cases}
     &Q_t^l(x_{t-1}^g,\omega_t^l) = \min\limits_{x_t,\theta_{t+1}} c_t^{\top}x_t +  \theta_{t+1}\\
     s.c. \qquad &\quad A_tx_t = \omega_t^l - E_t x_{t-1}^g, 		\quad\lbrack\pi_t(\omega_t^l)\rbrack\\
	\qquad &\quad x_t\geqslant 0 \\
	\qquad &\quad \theta_{t+1} +  (\beta_{t+1}^j)^{\top} x_t \geqslant \alpha_{t+1}^j, \quad j \in \{1,\dots, G,\dots, (n+1)G \}
	\end{cases}
	\end{eqnarray}
   }
	\longState{Store the dual solution $\pi_t(\omega_t^l)$ and the primal solution $Q_t^l(x_{t-1}^g,\omega_t^l)$ of the linear subproblem $\mathcal [AP_{t,l}^{n,g}]$.}
	\State Calculate the cutoff that goes with the $l^{th}$ hazard draw:
	\begin{eqnarray}
	\begin{cases}
	&\alpha_{t,l}^g =  Q_t^l(x_{t-1}^g,\omega_t^l) + \pi_t(\omega_t^l)^{\top} E_{t} x_{t-1}^g \\
	&\beta_{t,l}^g =  E_{t}^{\top} \pi_t(\omega_t^l)  
	\end{cases}
	\end{eqnarray}
  \EndFor
  \longState{Calculate the $g^{th}$ new Benders cut at time $t$ at iteration $n$. It is defined as the average value of the cuts obtained before:}
   \begin{equation}
	\begin{cases}
	&\alpha_t^k =  \frac{1}{L}\displaystyle \sum_{l=1}^L \alpha_{t,l}^g  \\
	&\beta_t^k =  \frac{1}{L}\displaystyle \sum_{l=1}^L \beta_{t,l}^g
	\end{cases} \quad \text{ where } k = nG + g
   \end{equation}
 \EndFor
 \EndFor
 \State Solve the following linear subproblem:
  \begin{eqnarray}
   {\mathcal [AP_0^n]} 
	\begin{cases}
      &Q_0 = \min\limits_{x_0,\theta_{1}} c_0^{\top}x_0 +  \theta_{1}\\
     s.c. \qquad &\quad A_0x_0 = \omega_0 , 						\quad\lbrack\pi_0(\omega_0)\rbrack\\
	\qquad &\quad x_0\geqslant 0 \\
	\qquad &\quad \theta_{1} + (\beta_{1}^j)^{\top} x_0 \geqslant \alpha_{1}^j, \quad j \in \{1,\dots,G,\dots,(n+1)G \}
	\end{cases}
	\end{eqnarray}
 \State Save the cost \textit{backward} $\underline{z}_n = Q_0$.
 \end{algorithmic}
 \caption{Run of backward pass}
 \label{alg:backward}
\end{algorithm}

\paragraph{Stopping test \\}
In the literature about SDDP lots of stopping criterion were used and their efficiency has been proved. However a criterion is suitable for each particular problem. Thus it is tough to bring out one which is generic. Due to genericity requirements, two classical criterion are implemented in the library. These can be customized  by the user. The first one defines a maximal number of iterations $n_{iterMax}$ (an iteration is made of the succession of \textit{backward-forward} passes) which shall not be exceeded. The second one is a test of convergence towards each other between the forward and the backward cost. The convergence test uses the following indicator:

\begin{equation}
\psi_{n_{step}i} = \left | \frac{\bar{z}_{n_{step}i} - \underline{z}_{n_{step}i}}{\bar{z}_{n_{step}i}} \right |, \quad \text{with } i \in \mathbb{N}
\end{equation}

This is calculated every  $n_{step}$ iterations. If it is less than a $p$ threshold, the process stops, otherwise it continues. The threshold is set by the user. 

\subsection{Dependence of random quantities}

In the previous case, we limit our problem to independent random quantities in the different stages. The resolution of the SDDP was obtained on the state vector $x_t$ in the basic case. 

But sometimes, in real life, the random quantities can be temporarily correlated. In a hydraulic problem, for example, there is a time dependence of the results. Time dependencies may also exist in the request. However, with time-bound random quantities, Bellman's recurrence formula (\ref{FctValInt} - \ref{FctBel}) does not hold and classical SDDP can not be applied. 

However if the Bellman functions are convex with respect to the temporal random quantities, it suffices to increase the dimension of the state vector by the dimension of the temporal random quantities to find ourselves in the configuration of the base case. In this case, the resolution of a linear program of reasonable size for each random draw is sufficient to calculate new calculations of Benders cuts in the vicinity of a candidate state. 

There are a few options for representing the time dependence of random quantities. However, in order to not increase the size of the problem too much, an ARMA process of order 1 is often chosen. In the random data vector $\omega_t$ two different parts must be distinguished from now on:  
\begin{itemize}
\item $\omega^{\ind}_t$ is the vector of random data corresponding to independent random quantities.
\item $\omega^{\dep}_t$is the vector of random data corresponding to the time-related random quantities.
\end{itemize}
And $\omega^{\dep}_t$ fulfills the following recurrence equation:
\begin{equation}
\frac{\omega^{\dep}_t - \mu_{\omega,t}}{\sigma_{\omega,t}} = \psi_1 \frac{\omega^{\dep}_{t-1} - \mu_{\omega,t-1}}{\sigma_{\omega,t-1}} + \psi_2 \epsilon_t
\end{equation}  

To apply Bellman's recurrence formula, the state of the vector must consist of the decision variable  $x_t$ and the time-bound random quantities $\omega^{\dep}_{t}$. The dimension of the vector state is then increased. $x^{\dep}_t =(x_t,\omega^{\dep}_{t})^{\top}$ designates the new state vector. The Bellman function now satisfies the following two-step linear problem at time $t$:

\begin{eqnarray}
{\mathcal [LP'_t]}
\begin{cases}
\label{FctValInt2}
     &Q_t(x_{t-1},\omega^{\dep}_{t-1},\omega_t) = \min c_t^{\top}x_t +  \mathscr{Q}_{t+1}(x_{t},\omega^{\dep}_{t}) \\
     u.c. \qquad &\quad A_tx_t = P \omega_t^{\dep} - E_t x_{t-1}, \qquad \lbrack\pi_t(\omega_t)\rbrack\\
\qquad &\quad x_t\geqslant 0
\end{cases}
\end{eqnarray}
with P the matrix such that $\omega_{t} = P \omega^{\dep}_{t}$.

The variable $\omega^{\dep}_{t}$ is a random process. Thus, the above problem is solved by using specific $\omega^l_t$ values of this variable. To get them, we apply a Markov process, i.e. we simulate different values of white noise $\epsilon_t^l$. 

The new shape of the state vector involves changes in the sensitivity of the Bellman function. It is therefore a function depending on the decision variable $x_t$ but also on the vector of random quantity linked to time  $\omega^{\dep}_{t}$. The calculation of the Benders cuts is then a little different:
\begin{equation}
\begin{split}
\frac{\partial Q_t(x_{t-1},\omega^{\dep}_{t-1},\omega_{t})}{\partial \omega^{\dep}_{t-1}}  & =  \frac{\partial Q_t(x_{t-1},\omega^{\dep}_{t-1},\omega_{t})}{\partial \omega^{\dep}_{t}} \frac{\partial \omega^{\dep}_{t}}{\partial \omega^{\dep}_{t-1}} \\
& =  \pi_t(\omega_t)^{\top} P \psi_1 \frac{\sigma_{\omega,t}}{\sigma_{\omega,t-1}},
\end{split}
\end{equation}

The backward passage should be changed as shown in the ~\ref{alg:backward_time_related} algorithm. Some new calculation steps must be taken into account.\\
{\small
\begin{algorithm}[htbp!]
 \begin{algorithmic}[1]
  \State Take the following set of pairs: $\{x_t^g,\omega_t^{\dep,g}\}$ for $g \in \{1,\dots,G\}$, $t \in \lbrace 1,\dots,T \rbrace$.
\For{$t = T, T-1, \dots,1 $}
 \For{$(x_{t-1}^g, \omega_{t-1}^{\dep,g})$, $g \in \{1,\dots,G\}$}
  \For{$l \in \{1,\dots,L\}$}
   \State Produce a value for white noise $\epsilon_t^l$.
   \State calculate the element $\hat{\omega}^{l}_t$ knowing the previous random quantity $\omega_{t-1}^{\dep,g}$:
   \begin{equation}  
    \hat{\omega}^{l}_t  = {\sigma_{\omega,t}}\left( \psi_1 \frac{\omega^{\dep,g}_{t-1} - \mu_{\omega,t-1}}{\sigma_{\omega,t-1}} + \psi_2 \epsilon_t^l \right) + \mu_{\omega,t}
\end{equation}         
   \State Solve the following linear subproblem.
   \begin{eqnarray}
   {\mathcal [AP_{t,l}^{' n,g}]} 
	\begin{cases}
     &Q_t^l(x_{t-1}^g,\omega_{t-1}^{\dep,g},\hat{\omega}^l_t) = \min\limits_{x_t,\theta_{t+1}} c_t^{\top}x_t +  \theta_{t+1}\\
     u.c. \qquad &\quad A_tx_t = P \hat{\omega}^{l}_t - E_t x_{t-1}^g, 		\quad\lbrack\pi_t(\hat{\omega}^{l}_t)\rbrack\\
	\qquad &\quad x_t\geqslant 0 \\
	\qquad &\quad \theta_{t+1} +  (\beta_{t+1}^j)^{\top} x_t + (\gamma_{t+1}^j)^{\top}\hat{\omega}^{l}_t \geqslant \alpha_{t+1}^j, \quad j \in \{1,\dots, G,\dots, (n+1)G \}
	\end{cases}
	\end{eqnarray}
\longState{Store the dual solution $\pi_t(\omega_t^l)$ and the primal solution $Q_t^l(x_{t-1}^g,\omega_{t-1}^{\dep,g},\hat{\omega}_t^l)$ of the primal problem $\mathcal [AP_{t,l}^{' n,g}]$.}
\longState{Calculate the cutoff that goes with the draw $l^{th}$:  
	\begin{eqnarray}
	\begin{cases}
	\alpha_{t,l}^g =  Q_t^l(x_{t-1}^g, \omega_{t-1}^{\dep,g},\hat{\omega}^{l}_t) + \pi_t(\hat{\omega}_t^l)^{\top} \left( E_{t} x_{t-1}^g - \psi_1 \frac{\sigma_{\omega,t}}{\sigma_{\omega,t-1}} P \omega_{t-1}^{\dep,g} \right)   \\
	\beta_{t,l}^g = E_{t}^{\top} \pi_t(\hat{\omega}^{l}_t)\\
	\gamma_{t,l}^g = \psi_1 \frac{\sigma_{\omega,t}}{\sigma_{\omega,t-1}} P^{\top} \pi_t(\hat{\omega}^{l}_t)
	\end{cases}
	\end{eqnarray}
}
  \EndFor
  \longState{Calculate the $g^{th}$ new Benders cut at time $t$ at iteration $n$ defined as the average value of the cuts obtained before for $ k = nG + g$:}
   \begin{align*}
	\alpha_t^k =  \frac{1}{L}\displaystyle \sum_{l=1}^L \alpha_{t,l}^g \ , \quad
	\beta_t^k =  \frac{1}{L}\displaystyle \sum_{l=1}^L \beta_{t,l}^g \ ,  \quad
	\gamma_t^k =  \frac{1}{L}\displaystyle \sum_{l=1}^L \gamma_{t,l}^g 
	\end{align*}  
   \EndFor
   \EndFor
  \State Solve the following linear subproblem. 
  \begin{eqnarray}
   {\mathcal [AP_{  0}^{' n}]} 
	\begin{cases}
      &Q_0 = \min\limits_{x_0,\theta_{1}} c_0^{\top}x_0 +  \theta_{1}\\
     u.c. \qquad &\quad A_0x_0 = \omega_0 ,	\quad\lbrack\pi_0(\omega_0)\rbrack\\
	\qquad &\quad x_\geqslant 0 \\
	\qquad &\quad \theta_{1} +  (\beta_{1}^j)^{\top} x_0 + (\gamma_{1}^j)^{\top} \omega_0^{\dep} \geqslant \alpha_{1}^j, %\\
	\quad j \in \{1,\dots, G,\dots, (n+1)G \}
%	\qquad &\qquad \quad j \in \{1,\dots, G,\dots, (n+1)G \}
	\end{cases}
	\end{eqnarray}
 \State Save the back cost $\underline{z}_n = Q_0$.
 \end{algorithmic}
 \caption{Execution of the backward pass with time-bound random quantities (AR1 process)}
 \label{alg:backward_time_related}
\end{algorithm}
}

\subsection{Non-convexity and conditional cuts}

Some random quantities can introduce non-convexity preventing us from applying the classical SDDP algorithm. Indeed when the random quantities appear on the left side of the linear constraints or in the cost function (typically $A_t$ and/or $c_t$ become random) the property of convexity of the Bellman functions with respect to the random quantities is not no longer observed.

In the context of a production management problem, the situation often arise. For example, sometimes the unit running cost of plants is random. It is also observed when we deal with the uncertainty of spot prices for use in stochastic mid-term scheduling. 

In a technical report, Pereira, Campodonico, and Kelman~\cite{pereira1999application} suggested a new algorithm to efficiently approximate Bellman functions by explicitly using the dependence of Bellman functions on these random quantities. This new algorithm is based on a combination of SDDP and ordinary stochastic dynamic programming.  The SDP part deals with the non-convex random quantities, while the other random quantities are dealt with in the SDDP part. It is an extension of the classic SDDP algorithm. It is described in detail in \cite{pereira1999application} and in \cite{gjelsvik1999algorithm}. 

In the library, we propose two  approaches to deal with this non convexity:
\subsubsection{A tree approach}
In \cite{gjelsvik1999algorithm}, the spot price $p_t$ is considered a state. The set of achievable spot prices is discretized into a set of $M$ points $\zeta_1,\dots,\zeta_M$. The following Markov model is then used:

$$\mathbb{P}\left(p_t = \zeta_j | p_{t-1} = \zeta_i\right) = \rho_{ij}(t),$$

This model makes easier the implementation of the SDP. But it implies discretization mistakes that are hard to quantify. It is also tough to discretize with efficiency a random process when only a small number of scenarios is available.

However when the dimension of the non convex uncertainties is low, it is an approach to consider. The finite number of states , and the probabilities linking states between two successive time step leads to a tree representation of the uncertainties.
As the approach is classical, we don't detail this version of the algorithm. We only detail the second approach which is in fact in spirit very similar.

\subsubsection{A regression based  approach}

In this case the modeling used in the library is somewhat different from that described in the two articles.
In order to avoid the discretization with trees in this second approach, the evolution of non-convex random quantities is decided by Monte Carlo simulations. At each stage, a fixed number of Monte-Carlo simulations is provided. Anyway, despite this difference, the overall view of this brand new algorithm is similar to that described in two articles:
\begin{itemize}
\item The non-convex random quantities depend on the realization of the previous one according to a mathematical model (Markov chain).
\item
At each step, the Bellman functions are approximated by the conditional realization of these random quantities.
\item We have used conditional cuts to give an estimate of the Bellman functions. These conditional cuts are calculated using the methods of the \ref{sec::regression} section: two methods are available in the library. Both use adaptive support. The first uses a constant approximation per cell while the second uses a linear approximation per cell.
\end{itemize}
In our algorithm the characteristics of the conditional cuts are revealed thanks to a conditional expectation calculation.

However, conditional expectation calculations are not easy when the exact distribution of the random variable is not known. Some techniques exist but in the library a specific one is used and described above in chapter  \ref{sec::regression}: it is based on local linear regression.

\paragraph{Regression, dynamic stochastic programming and SDDP \\}
The execution of the backward pass in the new algorithm combining SDDP and SDP using local linear regression is described below.

Before describing this algorithm in detail , let's introduce some notations:
\begin{itemize}
\item $S$ is the space of the non-convex random quantities. 
\item $d$ is the dimension of the space of non-convex random quantities $S$
\item At each step, $U$ Monte Carlo simulations in $S$ are provided. We thus obtain scenarios $U$ denoted by $s_t^u$ at each step $t$
\item $\tilde{I}$ is a partition of the space of non-convex random quantities $S$. $$\tilde{I} = \left\lbrace \underline{I} = \left(i_1,\dots,i_d\right), i_1 \in \lbrace 1,\dots,I_1\rbrace, \dots, i_d \in \lbrace 1,\dots,I_d\rbrace \right\rbrace$$
\item $\lbrace D_{\underline{I}}\rbrace_{\underline{I} \in \tilde{I}}$ is the set of meshes of the set of scenarios.
\item $M_M = \displaystyle\prod_{k=1}^d I_k$ designate the number of meshes at each step. 
\end{itemize}

The backward step with both random time-related and non-convex quantities is presented in the algorithm~\ref{alg:backward_time_related_conditional_cuts}.

\begin{algorithm}[H] %[htbp!]
 \begin{algorithmic}[1]
\State Pick up the set of the following pairs: $\{x_t^g,\omega_t^{\dep,g} \}$ for $g \in \{1,\dots,G\}$, $t \in \lbrace 1,\dots, T \rbrace$.
\For{$t = T, T-1, \dots,1 $}
\longState{Generate values for the non-convex random quantities at time $t$ knowing the scenarios at time $t-1$: $s_t^u$, $u \in \{1,\dots,U\}$.}
  \For{$(x_{t-1}^g, \omega_{t-1}^{\dep,g})$, $g \in \{1,\dots,G\}$}
  \For{$u \in \{1,\dots,U\}$}
  \State Consider a scenario $s_{t}^u$ in the mesh $D_{\underline{I}}$.
  \For{$l \in \{1,\dots,L\}$}
    \State Produce a value for the white noise $\epsilon_t^l$.
    \State Compute the element $\hat{\omega}_t^l$ knowing the previous random quantity $\omega^{\dep,g}_{t-1}$: 
   \begin{equation}  
    \hat{\omega}^{l}_t  = {\sigma_{\omega,t}}\left( \psi_1 \frac{\omega^{\dep,g}_{t-1} - \mu_{\omega,t-1}}{\sigma_{\omega,t-1}} + \psi_2 \epsilon_t^l \right) + \mu_{\omega,t}
\end{equation}     
 \longState{Pick up the cuts corresponding the mesh $D_{\underline{I}}$: $\left\lbrace \alpha_{t+1}^{\underline{I},j}(s),\beta_{t+1}^{\underline{I},j}(s), \gamma_{t+1}^{\underline{I},j}(s)\right\rbrace$, $ j \in  \left\lbrace 1, \dots, (n+1)G \right\rbrace$.}
 \longState{Solve the following linear sub-problem:
 \begin{eqnarray}
   \small 
   {\mathcal [AP_{t,l}^{' n,g}]} 
	\begin{cases}
     &Q_t^l(x_{t-1}^g,\omega_{t-1}^{\dep,g},\hat{\omega}_t^l, s_{t}^u) = \min\limits_{x_t,\theta_{t+1}} c_t(s_t^u)^{\top}x_t +  \theta_{t+1}(s_t^u)\\
     s.c. \qquad &\quad A_t(s_t^u)x_t = P\hat{\omega}_t^l - E_t x_{t-1}^g, 		\quad\lbrack\pi_t(\hat{\omega}_t^l,s_t^u)\rbrack\\
	\qquad &\quad x_t\geqslant 0 \\
	\qquad &\quad \theta_{t+1}(s_t^u) +  (\beta_{t+1}^{\underline{I},j}(s_t^u))^{\top} x_t + (\gamma_{t+1}^{\underline{I},j}(s_t^u))^{\top}\hat{\omega}_t^l \geqslant \alpha_{t+1}^{\underline{I},j}(s_t^u), \\ 
	\qquad &\qquad \quad j \in \{1,\dots, G,\dots, nG \} 
	\end{cases}
   \end{eqnarray}
}
   \longState{Store the dual solution $\pi_t(\hat{\omega}_t^l)$ and the primal solution $Q_t^l(x_{t-1}^g,\omega_{t-1}^{\dep,g},\hat{\omega}_t^l,s_{t}^u)$ of the problem $\mathcal [AP_{t,l}^{' n,g}]$.}
   \longState{Calculate the corresponding cut at the  $l^{th}$ draw of uncertainties: 
	\begin{align*}
	\hat{\alpha}_{t,l}^{g,\underline{I}}(s_t^u) &= Q_t^l(x_{t-1}^g, \omega_{t-1}^{\dep,g},\hat{\omega}_t^l) + \pi_t(\hat{\omega}_t^l)^{\top} \left( E_{t} x_{t-1}^g - \psi_1 \frac{\sigma_{\omega,t}}{\sigma_{\omega,t-1}} P \omega_{t-1}^{\dep,g} \right)   \\
	\hat{\beta}_{t,l}^{g,\underline{I}}(s_t^u) &= E_{t}^{\top} \pi_t(\hat{\omega}_t^l)  \\
	\hat{\gamma}_{t,l}^{g,\underline{I}}(s_t^u) &= \psi_1 \frac{\sigma_{\omega,t}}{\sigma_{\omega,t-1}} P^{\top} \pi_t(\hat{\omega}_t^l)
        \end{align*}
}
        \EndFor

        \algstore{condCut}
\end{algorithmic}
 \caption{Run of the backward pass with time-related (AR1) and non-convex random quantities}
 \label{alg:backward_time_related_conditional_cuts}
\end{algorithm}
\begin{algorithm}[H]
  \begin{algorithmic}[1]
  \algrestore{condCut}  
   \longState{Compute the cut for a non-convex random quantity $s_t^u$ at time $t$ at iteration $n$: it is defined as the weighted average on the $L$ Benders cut obtained before:}
   	\begin{align*}
	\hat{\alpha}_{t}^{g,\underline{I}}(s_{t}^u)  &=  \frac{1}{L}\displaystyle \sum_{l=1}^L \hat{\alpha}_{t,l}^{g,\underline{I}}(s_t^u)  \\
	\hat{\beta}_{t}^{g,\underline{I}}(s_t^u) &= \frac{1}{L}\displaystyle \sum_{l=1}^L \hat{\beta}_{t,l}^{g,\underline{I}}(s_t^u),  \qquad  j = nG + g \\
	\hat{\gamma}_{t}^{g,\underline{I}}(s_t^u) &= \frac{1}{L}\displaystyle \sum_{l=1}^L \hat{\gamma}_{t,l}^{g,\underline{I}}(s_t^u) 
          \end{align*}
\EndFor
 \For{${\underline{I}}_i, i \in \lbrace 1,\dots, M_M \rbrace$}
 \longState{Compute the $g^{th}$ new cut of the mesh $D_{{\underline{I}}_i}$ at time $t$ at iteration $n$  defined as the conditional expectation with respect to the scenario $u$ at time $t$:}
   \begin{eqnarray}
	\begin{cases}
	&\alpha_t^{j,I}(s_{t-1}^u) =  \mathbb{E} \left[\hat{\alpha}_{t}^{g,\underline{I}}(s_t^u)|s_{t-1}^u\right], \\
	&\beta_t^{j,I}(s_{t-1}^u) =  \mathbb{E} \left[ \hat{\beta}_{t}^{g,\underline{I}}(s_t^u)|s_{t-1}^u\right], \qquad  j = nG + g\\
	&\gamma_t^{j,I}(s_{t-1}^u) =  \mathbb{E} \left[\hat{\gamma}_{t}^{g,\underline{I}}(s_t^u)|s_{t-1}^u \right] 
	\end{cases}
   \end{eqnarray}
   \EndFor
   \EndFor
   \EndFor
 \State Solve the initial linear sub problem $[AP_{0}^{' n}]$.
 \State Save the backward cost $\underline{z}_n = Q_0$.
 \end{algorithmic}
\end{algorithm}

\clearpage

\section{C++ API}
\renewcommand{\labelitemi}{\textbullet}
The SDDP part of the stochastic library is in \verb!C++! code. This unit is a classic black box: specific inputs must be provided to obtain the expected results. In the SDDP unit, the backward and forward passes are performed successively until the stop criterion is reached. In this unit, the succession of passes is carried out by
\begin{itemize}
  \item the \code{backwardForwardSDDPTree} class for the tree method,
  \item the \code{backwardForwardSDDP} class for the regression-based approach.
\end{itemize}
These classes takes three non-defined classes as input.
\subsection{Inputs \\}
The user must implement three classes.
\begin{itemize}
\item \uline{A class where the transition problem is described} which is shown in the example \code{TransitionOptimizer}. This class is at the core of the problem resolution.
 Therefore, great flexibility is left to the user to implement this class.
The class is used with both the tree approach and the regression-based approach.\\
In a way, this class is where the technical aspects of the problem are adjusted. This class describes backward and forward passes. Four methods must be implemented:
\begin{itemize}
\item \code{updateDates}: establish the new set of dates: $(t, t+dt)$.

%\item \code{oneStepForward}: solves the different transition linear problems during the forward pass for a particle, a random vector and an initial state:
%\begin{itemize}
%\item the state $(x_{t},w^{\dep}_t)$ is  given as input of  the function.
%\item the  $s_t$ values are restored by the simulator.
%\item the LP is solved  between dates $t$ and $t+dt$ for the given $s_t$ and the constraints due to $w^{\dep}_{t}$ (demand, flow constraints) and permits to get
%the optimal $x_{t+dt}$.
%\item Using iid sampling, $w^{\dep}_{t+dt}$ is  estimated
%\item return $(x_{t+dt},w^{\dep}_{t+dt})$ as the following state and  $(x_{t+dt},w^{\dep}_{t})$ that will be used as the state to visit during next backward resolution.
%\end{itemize}

\item
  \code{oneStepForward}: solves the various linear transition problems during the forward pass for a particle, a random vector and an initial state:
\begin{itemize}
\item the state $(x_{t-dt},w^{\dep}_t)$ is given as input to the function.
\item the  $s_t$ values are restored by the simulator.
\item the LP is solved  between the dates $t$ and $t+dt$ for the given $s_t$ and the constraints due to $w^{\dep}_{t}$ (demand, flow constraints) and allows to get the optimum $x_{t}$.
\item Using iid sampling, $w^{\dep}_{t+dt}$ is estimated.
\item return $(x_{t},w^{\dep}_{t+dt})$ as next state and $(x_{t},w^{\dep}_{t})$ which to be used as a state to visit in the next backward resolution.
\end{itemize}

%\item \code{oneStepBackward}: solves the different transition linear problems during the backward pass for a particle, a random vector and an initial state. 
%\begin{itemize}
%\item The state $(x_{t+dt},w^{\dep}_{t})$ is  given as input if $t \ge 0$ otherwise input is $(x_0,w^{\dep}_0)$.
%\item If $t\ge 0$, sample to calculate $w^{\dep}_{t+dt}$ in order to get the state $(x_{t+dt},w^{\dep}_{t+dt})$ at the beginning of the period of resolution of the LP.
%\item Solve the LP from date $t+dt$ to next date $t+2dt$ (if equally spaced periods).
%\item Return the function value and the dual that will be used for cuts estimations.
%\end{itemize}

\item
  \code{oneStepBackward}: solves different linear transition problems during the backward pass for a particle, a random vector and an initial state. 
\begin{itemize}
\item The vector $(x_{t},w^{\dep}_{t})$ is  given as input if $t \ge 0$; otherwise, the input is $(x_{-dt},w^{\dep}_0)$.
\item If $t\ge 0$, sample to calculate $w^{\dep}_{t+dt}$ to obtain the state $(x_{t},w^{\dep}_{t+dt})$ at the start of the LP resolution period. 
If $t < 0$, the state is $(x_{-dt},w^{\dep}_0)$.
\item Solve the LP from date $t$ to next date $t+dt$ (if equally spaced periods) for the variable $x_{t+dt}$.
\item Return the value of the function and the dual that will be used for the cut estimates.
\end{itemize}


\item \code{oneAdmissibleState}: returns an admissible state at time $t$ (respect only the constraints).
\end{itemize}

\code{TransitionOptimizer} must derive from the \code{OptimizerSDDPBase} class defined below. 

\end{itemize}


\lstinputlisting[style=CStyle]{../StOpt/StOpt/sddp/OptimizerSDDPBase.h}

\begin{itemize}
\item \uline{A forward pass simulator}: \code{SimulatorSim}

\item \uline{A backward pass simulator}: \code{SimulatorOpt}. This simulator can use an underlying process to generate scenarios, a set of historical chronicles, or a discrete set of scenarios. Often, in the case of a test carried out, a Boolean is enough to distinguish the forward and the backward simulator. 

\end{itemize}

At the opposite of the class where the transition is described,  the simulator is of course different for the tree approach and the regression approach because the first gives only a finite number of states.


An abstract class for simulators using the regression-based methods is defined below:
\lstinputlisting[style=CStyle]{../StOpt/StOpt/sddp/SimulatorSDDPBase.h}

An abstract class derived from the previous class for simulators using tree-based methods is defined below:
\lstinputlisting[style=CStyle]{../StOpt/StOpt/sddp/SimulatorSDDPBaseTree.h}


\newpage 

\subsection{Architecture}
We only detail the SDDP architecture for the regression based approach because the tree approach uses the same algorithm.\\
The SDDP management part of the library is built following the scheme described below. \\ \\
In the following pseudo-code, you have to keep in mind that some small shortcuts were used in order to make reading friendly (e.g. linear subproblem in the initial case $(t=0)$ should be a little different from that of the other time steps, the entries \code{forwardSDDP}, \code{backwardSDDP}, \code{backwardForwardSDDP} have been omitted for simplicity). A more rigorous theoretical explanation is available in the previous part.
\begin{Remark}
To use the tree method,\\
  \code{forwardSDDP}, \code{backwardSDDP}, \code{backwardforwardSDDP}
  can be replaced with specialized version for trees called \\  \code{forwardSDDPTree}, \code{backwardSDDPTree}, \code{backwardforwardSDDPTree} in the library.
\end{Remark}

Three colors have been used: the blue parts correspond to the use of the functions implemented in the \textbf{TransitionOptimizer} class,the red parts correspond to the use of the \textbf{Simulator} (Sim or Opt) functions while the grey parts correspond to generic functions totally handled by the library. To be more precise, what you need to implement as a StOpt user is only the \textbf{TransitionOptimizer} and the \textbf{Simulator} (blue and red parts), other functions and loops described are already implemented and managed by the library.\\

\begin{algorithm}[h!]
 \begin{algorithmic}[1]
 \State \BLUE{{Init}: $x_{t}^g =$ \textbf{TransitionOptimizer.\textcolor{blue}{oneAdmissibleState($t$)}}, for $g \in \{1,\dots, G\}$ and $t \in \{1,\dots, T-1\}$, $n = 0$, $\psi = \infty$.  }
\While{$\psi>\epsilon$ and $n<n_{max}$}	
\State \textbf{\textcolor{gray}{StOpt}}  
\longState{$V_{b}=$ backwardSDDP() \textit{Using the previously computed set $(x_{t}^g)_{t,g}$ and create
 a set of cuts.}}
\longState{$V_{f}=$ forwardSDDP() \textit{Simulation using the cuts created in all the backward passes and update the set $(x_{t}^g)_{t,g}$.}}
\State $$ \psi = \frac{V_f-V_b}{V_f} $$ 
\State $$ n=n+1$$
\EndWhile
\end{algorithmic}
\caption{Run of backwardforwardSDDP(),the main function)}
\end{algorithm}

\begin{algorithm}[h!]
   \begin{algorithmic}[1]
     \For {$g \in \Omega_{\mathscr{G}}$}
     \State $iStep=0$: index of the date stored in the simulator
     \For{$t \in \{0,\dots,T\}$}
     \State \BLUE{\textbf{TransitionOptimizer.\textcolor{blue}{updateDates($t,t+1$)}}: update the required data following the current time step (iterator over current time step, average demand,\dots)}
     \State \RED{\textbf{SimulatorSim.\textcolor{red}{updateDateIndex($iStep$)}}: give the random quantities  $\left(\omega_t^g \right)$ for the scenario $g$ at time $t$ }
     \State \GREY{\textbf{\textcolor{gray}{StOpt}} Read the previously computed files to gather $\alpha_{t+1}^j,\beta_{t+1}^j$, for $j \in \{1,\dots, G,\dots, nG \}$}
     \State \BLUE{\textbf{TransitionOptimizer.\textcolor{blue}{oneStepForward():}} \\ Solve the following linear sub-problem. \;
       \begin{eqnarray}
         {\mathcal [AP_{t,g}^n]} 
	\begin{cases}
          &Q_t^g(x_{t-1}^g,\omega_t^g) = \min\limits_{x_t,\theta_{t+1}} c_t^{\top}x_t +  \theta_{t+1}\\
          s.c. \qquad &\quad A_tx_t = \omega_t^g - E_t x_{t-1}^g, 		\quad\lbrack\pi_t(\omega_t^g)\rbrack\\
	  \qquad &\quad x_t\geqslant 0 \\
	  \qquad &\quad \theta_{t+1} +  (\beta_{t+1}^j)^{\top} x_t \geqslant \alpha_{t+1}^j, \quad j \in \{1,\dots, G,\dots, nG \} 
	\end{cases}
       \end{eqnarray}\\
       Compute the cost for current time step $c_t^{\top} x_t^g$ \\
       \textbf{Return}: the primal solution $(x_t^g)$ of the problem 
     }
     \State \GREY{\textbf{\textcolor{gray}{StOpt}}{ Store the primal solution $(x_t^g)$ of the problem $\mathcal [AP_{t,g}^n]$}}
     \State $iStep = iStep+1$
     \EndFor
     \State \GREY{\textbf{\textcolor{gray}{StOpt}}{ Compute the cost for scenario $g$, at iteration $n$: $\bar{z}^g_n = \sum_{t=0}^T c_t x_t^g$\;}}
     \EndFor
     \State \GREY{\textbf{\textcolor{gray}{StOpt}}{ Compute the total cost in forward pass at iteration $n$: $\bar{z}_n = \frac{1}{G}\sum_{g=1}^G \bar{z}^g_n $ }}
   \end{algorithmic}
   \caption{Run of  \code{forwardSDDP} ($n^{th}$ iteration)}
\end{algorithm}

\begin{algorithm}[h!]
  \begin{algorithmic}[1]
    \State $iStep = NbStep$: update the simulator time index to  give the uncertainty at $T$
    \For{$t = T, T-1, \dots,0 $}
    \State \GREY{\textbf{\textcolor{gray}{StOpt}} Read the previously computed files to gather $x_{t-1}^g$, for $g \in \{1,\dots, G, \}$} 
    \State\BLUE{\textbf{TransitionOptimizer.\textcolor{blue}{updateDates($t-1,t$)}}: update the required data following the current time step (iterator over current time step, average demand,\dots)}
    \State \RED{   \textbf{SimulatorOpt.\textcolor{red}{updateDateIndex($iStep$)}}: give the random quantities for the $L$  scenarios at time $t$   } \
    \State \GREY{\textbf{\textcolor{gray}{StOpt}} Read the previously computed files to gather $\alpha_{t+1}^j,\beta_{t+1}^j$, for $j \in \{1,\dots, G,\dots, nG \}$}
    \For{$x_{t-1}^g$, $g \in \{1,\dots,G\}$}
    \For{$\omega_t^l$, $l \in \{1,\dots,L\}$}
    \State \BLUE{ \textbf{TransitionOptimizer.\textcolor{blue}{oneStepBackward()}} \\
      Solve the following linear sub-problem. \;
      \begin{eqnarray}
        {\mathcal [AP_{t,l}^{n,g}]} 
	\begin{cases}
          &Q_t^l(x_{t-1}^g,\omega_t^l) = \min\limits_{x_t,\theta_{t+1}} c_t^{\top}x_t +  \theta_{t+1}\\
          s.c. \qquad &\quad A_tx_t = \omega_t^l - E_t x_{t-1}^g, 		\quad\lbrack\pi_t(\omega_t^l)\rbrack\\
	  \qquad &\quad x_t\geqslant 0 \\
	  \qquad &\quad \theta_{t+1} +  (\beta_{t+1}^j)^{\top} x_t \geqslant \alpha_{t+1}^j, \ j \in \{1,\dots, G,\dots, (n+1)G \}
	\end{cases}
      \end{eqnarray}
      \textbf{Return}: the dual solution $\pi_t(\omega_t^l)$ and the primal one $Q_t^l(x_{t-1}^g,\omega_t^l)$ of the linear sub-problem $\mathcal [AP_{t,l}^{n,g}]$ 
    }
    \State $iStep= iStep+1$,
    \EndFor
    \State  \GREY{\textbf{StOpt} Compute the $g^{th}$ new Benders cut at time $t$ at iteration $n$: $\alpha_{t}^j,\beta_{t}^j$, for $j \in \{(n-1)G ,(n-1)G+1 ,\dots, nG \} $}
    \EndFor
    \EndFor
    \State \GREY{\textbf{StOpt}{ Save the cost \textit{backward} $\underline{z}_n = Q_0$ }}
  \end{algorithmic}
  \caption{Run of \code{backwardSDDP}}
\end{algorithm}


\subsection{Implement your problem}

In the next section, some tips and explanations will be given to help you implementing your problem in the library. It is advisable to consult the examples provided by the library. 
This will give you a better understanding of what is needed to calculate the SDDP method via StOpt ( \code{test/c++/tools/sddp} folder for the optimization examples, \code{test/c++/tools/simulators} for the one simulators, and \code{test/c++/functional} for the main instances).

\subsubsection{Implement your own \textbf{TransitionOptimizer} class} 

As described above, your \textbf{TransitionOptimizer} class must be specific to your problem (it is given as an argument to the \code{backwardForwardSDDP} function). Therefore, you must implement it yourself under certain constraints in order to adapt it to the requirements of the library. \\
First, make sure your \textbf{TransitionOptimizer} class inherits from the \code{OptimizerSDDPBase} class.
You will then need to implement the following functions. \\ 
\begin{itemize}

\item The \code{updateDates} function is used to update the data stored by the optimizer, by adjusting the times indicated in argument. 


\lstinputlisting[style=CStyle,firstline=52,lastline=58]{../StOpt/StOpt/sddp/OptimizerSDDPBase.h} % updatedate

If your transition problem is time dependant, for example, you should store the value of these arguments. Depending on your needs, you can also update data such as the average demand at the current stage and at next time step of a gas storage problem. \\ The \code{p\_dateNext} argument is used as the current time step in the backward pass. Therefore, you should store the values of the current and next time step arguments. 

\item The \code{oneAdmissibleState} function gives an admissible state (i.e. a state respecting all the constraints) for the time step given in argument. 

\lstinputlisting[style=CStyle,firstline=62,lastline=62]{../StOpt/StOpt/sddp/OptimizerSDDPBase.h} % one admissible state


\item The \code{oneStepBackward} function is used to compute a step of the backward pass. 

\lstinputlisting[style=CStyle,firstline=40,lastline=40]{../StOpt/StOpt/sddp/OptimizerSDDPBase.h} % backward
The first argument is the cuts already selected for the current time step. They are easy to manage, just use the \code{getCutsAssociatedToAParticle} function as described in the examples you can find in the test folder (\code{OptimizeReservoirWithInflowsSDDP.h} without regression or \code{OptimizeGasStorageSDDP.h} with regression).  You will then have the necessary cuts in the form of an array $cuts$ that you can link to the values described in the theoretical part at the time step $t$  by $cuts(0,j)=\alpha_{t+1}^j$, $cuts(i,j)=\beta_{i-1,t+1}^j$ $j \in \{1,\dots, G,\dots, (n+1)G \}$ ,$i \in \{1,\dots,nb_{state}\}$. \\ You will need to add the cuts to your constraints yourself, using this table and your solver features. 
\\ In addition, as an argument, you have the object containing the state at the start of the time step \code{p\_astate} (\textbf{keep in mind that this argument is given as an Eigen array}), \code{p\_particle} contains the random quantities on which the regression on the expectation of the value function will be based (the computational cost is high so take a look at the theoretical part to know when you really need to use),  finally the last argument is an integer indicating in which scenario index the resolution will be performed. 
\\ The function returns a one-dimensional array of size $nb_{state}+1$ containing as first argument the value of the objective function to the solution, then for $i \in \{1,\dots,nb_{state}\}$ it contains the derivatives of the objective function with respect to each of the dimensions $i$ of the state (we must find a way to have it using the dual solution for example).  

\item The \code{oneStepForward} function allows you to compute a step of the forward pass.

\lstinputlisting[style=CStyle,firstline=48,lastline=48]{../StOpt/StOpt/sddp/OptimizerSDDPBase.h} %

As you can see, the \code{oneStepForward} is quite similar to the \code{oneStepBackward}. A trick, used in the examples and which you should use, is to build a function generating and solving the linear problem $\mathcal [AP_{t,g}^n]$ (for a given scenario $g$ and a given time step $t$) which appears for both the forward and the backward pass. This function creating and generating the linear problem will be called in our two functions \code{oneStepForward} and  \code{oneStepBackward}. Make sure that in the forward pass, the current time step is given via the function \code{updateDates}(current date,next date)  by the current date argument while in the backward pass the current time is given via the next date argument (this is a necessary requirement to compute the regressions exposed in the theoretical part). Finally note that the two functions previously described are \code{const} functions and that you must take them into account during your implementation. 

\item The other functions that you must implement are simple functions (accessors) that are easy to understand.


\end{itemize}

\subsubsection{Implement your own \textbf{Simulator} class} 

This simulator must be the object that will allow you to build random quantities according to a desired law. It must be given as an argument of your optimizer. You can implement it yourself, but a set of simulators (gaussian, AR1, MeanReverting,\dots) is given in the test folder, you can use it directly if it meets your problem requirements. \\

\subsubsection{A simulator for the regression based method}
An implemented \textbf{Simulator} deriving from the \code{SimulatorSDDPBase} class must implement these functions:  

\begin{itemize}

\item The \code{getNbSimul} function returns the number of simulations of random quantities used in the regression part. This is the $U$ mentioned in the theoretical part.

\lstinputlisting[style=CStyle,firstline=27,lastline=27]{../StOpt/StOpt/sddp/SimulatorSDDPBase.h} %

\item The \code{getNbSample} function returns the number of simulations of random quantities that are not used in the regression part. This is the $G$ mentioned in the theoretical part. For example, in some cases we need a Gaussian random quantity to calculate the noise when we are in the ``dependence of random quantities'' part.

\lstinputlisting[style=CStyle,firstline=29,lastline=29]{../StOpt/StOpt/sddp/SimulatorSDDPBase.h} %

\item The \code{updateDateIndex} function is very similar to that of the optimizer. However you have one argument (the index of the time step ) here. It is also where you need to generate new random amounts for solving. 

\lstinputlisting[style=CStyle,firstline=31,lastline=31]{../StOpt/StOpt/sddp/SimulatorSDDPBase.h} %

\item The \code{getOneParticle} and the \code{getParticles} functions should return the quantities used in regression part.

\lstinputlisting[style=CStyle,firstline=36,lastline=36]{../StOpt/StOpt/sddp/SimulatorSDDPBase.h} %
\lstinputlisting[style=CStyle,firstline=38,lastline=38]{../StOpt/StOpt/sddp/SimulatorSDDPBase.h} %

\item The two last functions \code{resetTime} and \code{updateSimulationNumberAndResetTime} are quite explicit.
  \end{itemize}

  \subsubsection{A simulator for the tree approach}
A simulator using tree must be derived from the \code{SimulatorSDDPBaseTree} class. 
Since the \code{SimulatorSDDPBaseTree} class is derived from the \code{SimulatorSDDPBase} class, all of the previously described methods must be given.\\
Besides a geners archive is used to load:
\begin{itemize}
\item The dates used by the simulator to estimate the set of possible states,
\item At each date, a set of $d$ dimensional points defining the set of discrete values of the state in the tree,
\item At each date a two-dimensional array giving the probability of transition in the tree to go from a node $i$ on the current date to a node $j$ on the following date.
\end{itemize}
Then the implemented simulator must call the based constructor loading the archive:
\lstinputlisting[style=CStyle,firstline=39,lastline=45]{../StOpt/StOpt/sddp/SimulatorSDDPBaseTree.h} %

Then the user must have generated such an archive. An example of using a trinomial tree method for an AR1 class is given in the c++ test cases in the simulator directory by the \code{MeanRevertingSimulatorTree} class.\\

The necessary methods to be implemented are as follows:
\begin{itemize}
\item The \code{getNodeAssociatedToSim} method gives for a simulation identified by the particle number the node in the  visited tree.
  
  \lstinputlisting[style=CStyle,firstline=109,lastline=112]{../StOpt/StOpt/sddp/SimulatorSDDPBaseTree.h} %

\item The \code{stepForward} method updates the simulation date index by one, and samples visited nodes in forward resolution.
 
  \lstinputlisting[style=CStyle,firstline=136,lastline=139]{../StOpt/StOpt/sddp/SimulatorSDDPBaseTree.h} %
  
\end{itemize}


\subsection{Set of parameters\\}

\subsubsection{Implementing some regression-based method}
The base function \code{backwardForwardSDDP} must be called to use the SDDP part of the library with conditional cuts calculated by regressions. This function is modeled by the regressor used:
\begin{itemize}
\item  \code{LocalConstRegressionForSDDP} The regressor allows to use a constant approximation by mesh of SDDP cuts,
\item \code{LocalLinearRegressionForSDDP} The regressor allows to use a linear approximation by mesh of SDDP cuts.
\end{itemize}

\lstinputlisting[style=CStyle,firstline=29,lastline=54]{../StOpt/StOpt/sddp/backwardForwardSDDP.h} %

Most of the arguments are pretty straightforward (you can see examples in \code{test/c++/functional}). The strings correspond to the names which will be given by the files which will store cuts, visited states or regressor data. \code{p\_nbSimulCheckForSimu} corresponds to the number of simulations (number of forward passes called) when it is necessaary to check the convergence by comparing the result given by the forward pass and that given by the backward pass. \code{p\_nStepConv} indicates when the convergence is verified (each \code{p\_nStepConv} iteration). \code{p\_finalCut} corresponds to the cut used at the last time step: when the function of final value is zero, the last cut is given by an all zero array of size $nb_{state}+1$.  \code{p\_dates} is an array made up with all the time steps of the study period given as doubles, \code{p\_iter} corresponds to the maximum number of iterations. Finally, \code{p\_stringStream} is a \code{ostringstream} in which the result of the optimization will be stored.

\subsubsection{Implementing a tree based method}

The base function \code{backwardForwardSDDPTree} must be called to use the SDDP part of the library with conditional cuts calculated with trees.

\lstinputlisting[style=CStyle,firstline=29,lastline=54]{../StOpt/StOpt/sddp/backwardForwardSDDPTree.h} %

%\subsection{Set of parameters\\}
%We have seen above that providing a set of parameters in the initialization phase was necessary (convergence criterion, initial state vector, \ldots). They depend on each problem and are based on technical skills.
%Suggestion to the intention of the user: provide a \textit{main} where all these parameters are defined and where the sequence of computations to achieve is described. Basic class \code{backwardForwardSDDP} should be called.


\subsection{The black box\\}
The algorithms described above are applied. As stated earlier, the user controls the implementation of the business side of the problem (transition problem).
But in the library some things are handled automatically and the user should be aware of:
\begin{itemize}
\item The \textbf{Parallelization} When solving the problem is handled automatically. During compilation, if the compiler detects a problem with the MPI (Message Passing Interface) library, the resolution will be carried out in a parallelized manner. 
\item The \textbf{cut management}. All the cuts added with each iteration are currently serialized and stored in an archive initialized by the user. No cut is pruned. In the future, we can consider working on \cite{pfeiffer2012two} cut management. 
\item A \textbf{double stop criterion} is hardly used by the library: a convergence test and a maximum number of iterations. If either of the two criteria exceeds the user-defined thresholds, the resolution stops automatically. Once again further work could be considered on this subject.
\end{itemize}

\subsection{Outputs \\}
SDDP library outputs are not currently defined. Thus during the resolution of an SDDP problem, only the number of iterations, the evolution of the backward and forward costs and of the convergence criterion are recorded.

However, while iterating backwards and forwards the value of the Bellman functions and the associated Benders cuts , the different states visited during the forward pass and the evolution of costs are stored at each moment of the time horizon. This information is useful for users and easy to enter.\\
Once the convergence has been achieved, the user must restart certain simulations by adding a flag to store the results necessary for the application (distribution cost  etc.): these results will be post-processed by the user.


\begin{figure}
\begin{center} 
\hspace{-2cm}
\includegraphics[scale=0.55]{CommonUnit.png}
\caption{Current architecture of the generic SDDP unit} 
\label{archi}
\end{center}
\end{figure}


\section{Python API (only for regression-based methods)}
A high level Python mapping is also available in the SDDP part.
The backward-forward  \verb!C++!  function is exposed in Python by the SDDP \code{StOptSDDP} module.
In this mapping, only the linear per mesh regressor is used.

\begin{lstlisting}[style=PStyle]
import StOptSDDP
dir(StOptSDDP)
\end{lstlisting}
that should give {\tiny $$ ['OptimizerSDDPBase', 'SDDPFinalCut', 'SimulatorSDDPBase', '\_\_doc\_\_', '\_\_file\_\_', '\_\_name\_\_', '\_\_package\_\_', 'backwardForwardSDDP']$$}
The \code{backwardForwardSDDP} performs the forward and backward SDDP sweep giving an SDDP optimizer and an SDDP uncertainty simulator.
The initial final cuts for the last time steps are provided by the \code{SDDPFinalCut} object.\\
Perform the mapping of SDDP optimizers and simulators written in \verb!C++! it is necessary to create a Boost Python wrapper.
In order to expose the \verb!C++!  optimization class \code{OptimizeDemandSDDP} used in the test case \code{testDemandSDDP.cpp}, the following wrapper   can be found in \\ \code{StOpt/test/c++/python/Pybind11SDDPOptimizers.cpp}\\
\lstinputlisting[style=CStyle]{../StOpt/test/c++/python/Pybind11SDDPOptimizers.cpp}
The wrapper used to expose the SDDP simulator is given in 
\\ \code{StOpt/test/c++/python/Pybind11Simulators.cpp}\\
Then it is possible to use the mapping to write a Python version of \code{testDemandSDDP.cpp}
\lstinputlisting[style=PStyle]{../StOpt/test/python/functional/testDemandSDDP.py}


\part{Nesting Monte Carlo for general nonlinear PDEs}
\label{part:nesting}
The described method has been studied in \cite{warin2018nesting}, \cite{warin2018monte} and uses some ideas in \cite{henry2016branching}, \cite{warin2017variations}.\\
Our goal is to solve the complete nonlinear equation
 \begin{flalign}
 \label{eqPDEFull}
  (-\partial_tu-\Lc u)(t,x)  & = f(t,x,u(t,x),Du(t,x),D^2u(t,x)), \nonumber \\
  u_T&=g, \quad  t<T,~x\in\R^d,
 \end{flalign}
 with
\begin{flalign*}
 \Lc u(t,x) := \mu Du(t,x) +  \frac{1}{2} \sigma \sigma^{\top} \!:\! D^2 u(t,x)
 %\label{eq:gen*}
 \end{flalign*}
 so that $\Lc $ is the generator associated with 
 \begin{flalign*}
  X_t = x +  \mu t+ \sigma  dW_t,
 %\label{eq:sde}
 \end{flalign*}
 with $\mu \in \R^d$, and $\sigma \in \M^d$ is a constant matrix.\\
Throughout the article, $\rho$ is the density of a general random variable following a gamma law so that
 \begin{align}
 \rho(x)= \lambda^\alpha x^{\alpha-1} \frac{e^{-\lambda x}}{\Gamma(\alpha)},  1 \ge \alpha >0.
 \label{rho}
 \end{align}
The associated  cumulative distribution function is  $$F(x) =\frac{\gamma(\alpha,\lambda x)}{\Gamma(\alpha)}$$
where $\gamma(s, x) =  \int_0^x t^{s-1} e^{-t} dt$ is the incomplete gamma function and $\Gamma(s)= \int_0^\infty t^{s-1} e^{-t} dt$ is the gamma function.\\
The methodology follows the ideas of \cite{warin2018nesting} and \cite{warin2017variations}.\\
It is assumed here that $\sigma$ is not degenerate so that $\sigma^{-1}$ exists.\\
Let set $p \in \N^{+}$.
For $(N_0,\dots, N_{p-1}) \in \N^p$, we introduce  the sets of i-tuple,
$Q_i = \{ k=(k_1, \dots,k_i)\}$ for $i \in \{1,\dots,p\}$ where all components $k_j \in [1, N_{j-1}]$.
Besides we define $Q^p= \cup_{i=1}^p Q_i$.\\
We construct the sets $Q^o_i$  for $i = 1, \dots, p$, such that
$$Q^o_1= Q_1$$  and 
the set $Q^o_i$  for $i>1$ are defined by recurrence: 
\begin{flalign*}
Q^o_{i+1} = \{ (k_1,\dots,k_i, k_{i+1}) / (k_1,\dots,k_i) \in Q^o_{i}, k_{i+1} \in \{ 1,\dots,N_{i+1}, 1_{1},\dots, (N_{i+1})_1, 1_2,\dots,(N_{i+1})_2 \} \}
\end{flalign*}
 so that to a particle noted $(k_1, \dots, k_i)  \in Q_i^o$ such that $k_i \in \N$, we associate two fictitious particles noted $ k^1 = (k_1,\dots,k_{i-1}, (k_i)_{1})$  and 
 $ k^2 = (k_1,\dots,k_{i-1}, (k_i)_{2})$. \\
To a particle $k=(k_1, \dots, k_i) \in Q^o_i$ we associate its original particle $o(k) \in Q_i$ such that $o(k)= (\hat k_1,\dots, \hat k_i)$ where $\hat k_j = l$ if $k_j = l$, $l_{1}$ or $l_2$.\\
For $k=(k_1, \dots, k_i) \in Q^o_i$ we introduce the set of its non fictitious sons
\begin{align*}
\tilde Q(k) = \{ l =(k_1,\dots,k_i, m )/  m \in \{1,\dots, N_i\} \} \subset Q_{i+1}^o,
\end{align*}
and the set of all sons
\begin{align*}
\hat Q(k) = \{ l =(k_1,\dots,k_i, m )/  m \in \{1,\dots, N_i, 1_1,\dots, (N_i)_1,1_2,\dots,(N_i)_2 \} \} \subset Q_{i+1}^o.
\end{align*}
By convention $\tilde Q(\emptyset) = \{ l =( m )/  m \in \{1,\dots, N_0\} \} =  Q_{1}.$
 Reciprocally the ancestor $k$ of a particle  $\tilde k$ in $\tilde Q(k)$ is noted $\tilde k^{-}$.\\
We define the order  of  a particle $k  \in Q^o_{i}$, $i \ge 0$,  by the function $\kappa$:
\begin{align*}
\kappa(k) =& 0 \mbox{ for } k_i \in \N, \\
\kappa(k) =  &  1  \mbox{ for } k_i = l_1,  l \in \N \\
\kappa(k) =  &  2 \mbox{ for } k_i = l_2 , l \in \N 
\end{align*}
We define the sequence $\tau_{k}$  of switching increments i.i.d. random density variables $\rho$ 
 for $k\in Q^p$.
 The switching dates are defined as follows:
 \begin{equation}
 \left\{
 \begin{array}{lll}
 T_{(j)} &  =&  \tau_{(j)} \wedge T,  j \in \{ 1,., N_{0}\} \\
 T_{ \tilde k} & =&  ( T_{k} + \tau_{ \tilde k}) \wedge T,  k =( k_1,\dots,k_i) \in Q_i, \tilde k \in \tilde Q(k)
 \end{array}
 \right.
 \end{equation}
By convention $T_k = T_{o(k)}$ and $ \tau_k = \tau_{o(k)}$.
For $k = (k_1,\dots,k_i) \in Q^o_i$  and $\tilde k =(k_1,\dots,k_i, k_{i+1})  \in \hat Q(k)$ we define the following trajectories:
	\begin{flalign}\label{eq:brownRenorm}
		W^{\tilde k}_s
		~:=~&
		W^{k}_{T_{k}}
		~+~
		\1_{ \kappa( \tilde k) =0}
		\bar W^{o(\tilde k)}_{s - T_{k}} 
        ~-~
		\1_{ \kappa(\tilde k)=1}
		\bar W^{o(\tilde k)}_{s - T_{k}},
		~~~\mbox{and}~~\\
		X^{\tilde k}_s := &x +\mu s +\sigma  W^{\tilde k}_s,
		~~~\forall s \in [T_{k}, T_{\tilde k}],
	\end{flalign}
where the $\bar W^{ k}$ for $k$ in $Q^p$ are independent $d$-dimensional Brownian motions, independent of the $(\tau_{k})_{k \in Q^p}$.\\
To understand what these different trajectories represent, suppose that $d=1$, $\mu= 0$, $\sigma =1$ and consider the original particle $k= (1,1,1)$  such that $T_{(1,1,1)}=T$.\\
Following equation \eqref{eq:brownRenorm},
\begin{align*}
X^{(1,1,1)}_T = & \bar W^{(1)}_{T_{(1)}} + \bar W^{(1,1)}_{T_{(1,1)}-T_{(1)}} + \bar W^{(1,1,1)}_{T-T_{(1,1)}} \\
X^{(1_{1},1,1)}_T= & -\bar W^{(1)}_{T_{(1)}} + \bar W^{(1,1)}_{T_{(1,1)}-T_{(1)}} + \bar W^{(1,1,1)}_{T-T_{(1,1)}} \\
X^{(1,1_{1},1)} = & \bar W^{(1)}_{T_{(1)}} - \bar W^{(1,1)}_{T_{(1,1)}-T_{(1)}} + \bar W^{(1,1,1)}_{T-T_{(1,1)}} \\
X^{(1_{2},1_{1},1)}_T = & - \bar W^{(1,1)}_{T_{(1,1)}-T_{(1)}} + \bar W^{(1,1,1)}_{T-T_{(1,1)}} \\
...&
\end{align*}
such that all particles are generated from the $\bar W^k$ used to define $X^{(1,1,1)}_T$.\\
Using the previous definitions,
we consider the estimator defined by:
\begin{empheq}[left=\empheqlbrace] {align}
\bar u_\emptyset^p = & \frac{1}{N_0} \sum_{j=1}^{N_0}   \phi\big( 0, T_{(j)}, X^{(j)}_{T_{(j)}}, \bar u_{(j)}^p, D \bar u_{(j)}^p, D^2 \bar u_{(j)}^p\big) , \nonumber\\
\bar u_{k}^p = &  \frac{1}{N_i} \sum_{\tilde k \in \tilde Q(k)}   \frac{1}{2} \big(  \phi\big(T_k,T_{\tilde k},X^{\tilde k}_{T_{\tilde k}},\bar u_{\tilde k}^p, D\bar u_{\tilde k}^p, D^2\bar u_{\tilde k}^p\big) + \nonumber \\
& \quad \quad \phi\big(T_k,T_{\tilde k},  X^{\tilde k^{1}}_{T_{\tilde k}}, \bar u_{\tilde k^{1}}^p D\bar u_{\tilde k^{1}}^p, D^2\bar u_{\tilde k^{1}}^p\big)  \big), \quad \mbox{ for }  k =( k_1,\dots,k_i) \in Q^o_i, 0 < i <p, \nonumber \\
D \bar u_{k}^p = &  \frac{1}{N_i} \sum_{\tilde k \in \tilde Q(k)}   \V^{\tilde k} \frac{1}{2} \big(  \phi\big(T_k,T_{\tilde k},X^{\tilde k}_{T_{\tilde k}},\bar u_{\tilde k}^p, D\bar u_{\tilde k}^p, D^2\bar u_{\tilde k}^p\big) -\nonumber \\
& \quad \quad  \phi\big(T_k,T_{\tilde k},  X^{\tilde k^{1}}_{T_{\tilde k}}, \bar u_{\tilde k^{1}}^p D\bar u_{\tilde k^{1}}^p, D^2\bar u_{\tilde k^{1}}^p\big)  \big), \quad \mbox{ for }  k =( k_1,\dots,k_i) \in Q^o_i, 0 < i < p, \nonumber \\
D^2\bar u_{k}^p = &  \frac{1}{N_i} \sum_{\tilde k \in \tilde Q(k)}   \W^{\tilde k} \frac{1}{2} \big(  \phi\big(T_k,T_{\tilde k },X^{\tilde k}_{T_{\tilde k}}, \bar u_{\tilde k}^p, D\bar u_{\tilde k}^p, D^2\bar u_{\tilde k}^p\big) + \nonumber \\
& \quad \quad \phi\big(T_k,T_{\tilde k},  X^{\tilde k^{1}}_{T_{\tilde k}}, \bar u_{\tilde k^{1}}^p, D\bar u_{\tilde k^{1}}^p, D^2\bar u_{\tilde k^{1}}^p\big) - \nonumber \\
& \quad \quad 2 \phi\big(T_k,T_{\tilde k},  X^{\tilde k^{2}}_{T_{\tilde k}}, \bar u_{\tilde k^{2}}^p, D\bar u_{\tilde k^{2}}^p, D^2\bar u_{\tilde k^{2}}^p\big) \big), \quad \mbox{ for }  k =( k_1,\dots,k_i) \in Q^o_i, 0 < i <p, \nonumber \\
\bar u_{k}^p = &  g(X^{k}_{T_{k}}), \quad  \mbox{for } k \in Q_p^o, \nonumber \\
D\bar u_{k}^p = & D g(X^{ k}_{T_{k}}), \quad  \mbox{for } \tilde k \in Q_p^o, \nonumber \\
D^2\bar u_{k}^p = & D^2 g(X^{k}_{T_{ k}}), \quad  \mbox{for } \tilde k \in Q_p^o
\label{eq:estimFull1}
\end{empheq} 
 where $\phi $ is defined by:
 \begin{flalign}
 \label{defPhi}
  \phi(s, t,x,y,z,\theta) &:= \frac{\1_{\{t\ge T\}}}{ \Fb(T-s)} g(x)\!+\! \frac{\1_{\{t<T\}}}{\rho(t -s)} f(t,x,y,z,\theta).
 \end{flalign}
 and 
 \begin{align*}
 \V^{k} = \sigma^{-\top} \frac{\bar W_{ T_{k}- T_{k^{-}}}^{k}}{T_{ k}- T_{ k^{-}}}
 \end{align*},
 \begin{align}
 \W^{k} = 
  (\sigma^{\top})^{-1} \frac{\bar W^{k}_{T_{k}- T_{k^{-}}}(\bar W^{ k}_{T_{ k}- T_{k^{-}}})^{\top} - (T_{ k}- T_{k^{-}})  I_d}{(T_{ k}- T_{k^{-}})^2} \sigma^{-1}
 \end{align}
As explained previously, the terms $u$ and $Du$ in $f$ are treated as explained in \cite{warin2018nesting} and only the $D^2u$ treatment is new to this scheme.
 \begin{Remark}
In practice, we just have the value $g$ at the deadline $T$ and we want to apply the scheme even if the derivatives of the final solution is not defined.
We can close the system for $k$ in $Q_p^o$ by replacing $\phi$ with $g$ and taking a value for $N_{p+1}$:
 \begin{align*}
 \bar u_{k}^p = &  \frac{1}{N_{p+1}} \sum_{\tilde k \in \tilde Q(k)}   \frac{1}{2} \big(  g\big(X^{\tilde k}_{T_{\tilde k}}\big) + g \big( X^{\tilde k^{1}}_{T_{\tilde k}}\big)  \big) , \\
D\bar u_{ k}^p = & \frac{1}{N_{p+1}} \sum_{\tilde k \in \tilde Q(k)}  \V^{\tilde k} \frac{1}{2} \big(  g\big(X^{\tilde k}_{T_{\tilde k}}\big) -g\big(  X^{\tilde k^{1}}_{T_{\tilde k}},\big) \big), \\
D^2\bar u_{k}^p = &  \frac{1}{N_{p+1}} \sum_{\tilde k \in \tilde Q(k)} 
 \W^{\tilde k}  \frac{1}{2} \big(  g \big(X^{\tilde k}_{T_{\tilde k}},\big) +
g \big( X^{\tilde k^{1}}_{T_{\tilde k}}\big) -  2 g\big( X^{\tilde k^{2}}_{T_{\tilde k}}\big) \big)
 \end{align*}
 \end{Remark}
 \begin{Remark}
 In the case where the coefficient are not constant, some Euler scheme can be added as explained in \cite{warin2018nesting}.
 \end{Remark}
An efficient algorithm for this scheme has these two functions:
 \begin{algorithm}[h]
\caption{\label{algoMC1} External Monte Carlo algorithm ($V$ generates unit Gaussian RV, $\tilde V$ generates an RV with gamma law density)}
\begin{algorithmic}[1]
\Procedure{PDEEval}{$\mu$, $\sigma$, $g$, $f$, $T$, $p$, $x_0$, $\{N_0,\dots, N_{p+1}\}$, $V$, $\tilde V$} 
\State $u_M = 0$ 
\State $x(0,:)= x_0(:)$ \Comment{$x$ is a matrix of size $1 \times n$}
\For{$i = 1, N_0$}
\State   $(u,Du,D^2u)=$ EvalUDUD2U$(x_0,\mu, \sigma,g, T,V,\tilde V,p,1, 0,0)$ 
\State $u_M = u_M + u(0)$
\EndFor \\
\Return $\frac{U_M}{N_0}$
\EndProcedure
\end{algorithmic}
\end{algorithm}
\begin{algorithm}[h]
\caption{\label{algoMC2} Internal Monte Carlo algorithm where $t$ is the current time, $x$ the array of particles positions of size $m \times d$, and $l$ the nesting level.}
\begin{algorithmic}[1]
\Procedure{EvalUDUD2U}{$x,\mu, \sigma,g, T,V,\tilde V,p,m,t,l$} 
\State $\tau = \min ( \tilde V(),T-t)$,  \Comment{Sample the time step}
\State $G=V()$ \Comment{Sample the $n$ dimensional Gaussian vector}
\State  $xS(1:m,:) =  x(:)+ \mu \tau + \sigma G \sqrt{\tau}$
\State  $xS(m+1:2m,:)=   x(:)+ \mu \tau $
\State  $xS(2m+1:3m,:)=   x(:)+ \mu \tau -\sigma G \sqrt{\tau}$
\State $tS =t + \tau$ \Comment{New date}
\If {$ ts \ge T $ or $l = p$}
\State $g_1 = g(xS(1:m,:)) ; g_2 = (xS(m+1:2m,:)) ; g_3 = g(xS(2m+1:3m,:)) $ 
\State $ u(:)= \frac{1}{2} (g_1+g_3)$
\State $ Du(:,:)=  \frac{1}{2} (g_1-g_3) \quad \sigma^{- \top} G$
\State $D^2u(:,:,:)=  \frac{1}{2} (g_1+g_3-2g_2) \sigma^{- \top} \frac{GG^{\top}- \I_d}{\tau} \sigma^{-1}$
\If { $l \ne p$}
\State $(u(:),Du(:,:), D^2u(:,:,:)) /= \frac{1}{\bar F(\tau)}$ 
\EndIf
\Else
\State $ y(:)= 0; z(:,:) = 0; \theta(:,:,:) =0$
\For {$j=1, N_{l+1}$}
\State $(y,z, \theta)+=$EvalUDUD2U$(xS,\mu,\sigma,g,T,V,\tilde V,p,3m,tS,l+1)$
\EndFor
\State $(y,z,\theta) /= N_{l+1}$
\For {$q= 1, m$}
\State $f_1 = f(ts,xS(q),y(q),z(q,:),\theta(q,:,:))$
\State $f_2 = f(ts,xS(m+q),y(m+q),z(m+q,:),\theta(m+q,:,:))$
\State $f_3 = f(ts,xS(2m+q),y(2m+q),z(2m+q,:),\theta(2m+q,:,:))$
\State $u(i)= \frac{1}{2}(f_1+f_3)$
\State $Du(i,:)= \frac{1}{2}(f_1-f_3) \sigma^{- \top} G $
\State  $D^2u(i,:,:)= \frac{1}{2}(f_1+f_3-2f_2) \sigma^{- \top} \frac{GG^{\top}- \I_d}{\tau} \sigma^{-1} $
\EndFor
\EndIf \\
\Return $(u,Du,D^2u)$
\EndProcedure
\end{algorithmic}
\end{algorithm}
\part{Some test cases description}


{Description of some test cases in C++}
In this part, we describe the functional test cases of the library.
The C++ version of these test cases can be found in \code{test/c++/functional} while their python equivalent (if it exists) is in \code{test/python/functional}.
We describe the C++ test cases in detail here.
\section{American option}
The library gives some test cases for the Bermudean options problem (\cite{bouchard2017numerical} for more details on the Bermudean option problem).
All Bermudean test cases use a basket option payoff. The reference for converged methods can be found in \cite{bouchard2017numerical}.
\subsection{testAmerican}
The test case in this file makes it possible to test during the Dynamic Programming resolution different regressors:
\begin{itemize}
\item either by using some local functions with the same size support:
\begin{itemize}
\item Either by using a constant representation by mesh of the function (\code{LocalSameSizeConstRegression} regressor)
\item Either by using a linear representation by mesh of the function (\code{LocalSameSizeLinearRegression} regressor)
\end{itemize}
\item either using some  function basis with adaptive support (\cite{bouchard2017numerical})
\begin{itemize}
\item Either by using a constant representation per mesh of the function (\code{LocalConstRegression} regressor)
\item Either by using a linear representation by mesh of the function (\code{LocalLinearRegression} regressor)
\end{itemize}
\item Either using the global polynomial regressor:
\begin{itemize}
\item Either using Hermite polynomials,
\item Either using Canonical polynomials (monomes),
\item Either using Tchebychev polynomials.
\end{itemize}
\item Either using a sparse regressor,
\item Either using kernel regressors:
  \begin{itemize}
  \item either using a constant kernel regressor,
    \item either using linear kernel regressor.
  \end{itemize}
\end{itemize}
\subsubsection*{testAmericanLinearBasket1D}
Test 1D problem with \code{LocalLinearRegression} regressor.
\subsubsection*{testAmericanConstBasket1D}
Test 1D problem with \code{LocalConstRegression} regressor.
\subsubsection*{testAmericanSameSizeLinearBasket1D}
Test 1D problem with \code{LocalSameSizeLinearRegression} regressor.
\subsubsection*{testAmericanSameSizeConstBasket1D}
Test 1D problem with \code{LocalSameSizeConstRegression} regressor.
\subsubsection*{testAmericanGlobalBasket1D}
Test 1D problem with global Hermite, Canonical and Tchebychev regressor.
\subsubsection{testAmericanGridKernelConstBasket1D}
Test 1D problem with classical kernel regression
\subsubsection{testAmericanGridKernelLinearBasket1D}
Test 1D problem with linear kernel regression
\subsubsection*{testAmericanLinearBasket2D}
Test 2D problem with \code{LocalLinearRegression} regressor.
\subsubsection*{testAmericanConstBasket2D}
Test 2D problem with \code{LocalConstRegression} regressor.
\subsubsection*{testAmericanSameSizeLinearBasket2D}
Test 2D problem with \code{LocalSameSizeLinearRegression} regressor.
\subsubsection*{testAmericanSameSizeConstBasket2D}
Test 2D problem with \code{LocalSameSizeConstRegression} regressor.
\subsubsection*{testAmericanGlobalBasket2D}
Test 2D problem with global Hermite, Canonical and Tchebychev regressor.
\subsubsection*{testAmericanGridKernelConstBasket2D}
Test 2D problem with classical kernel regression
\subsubsection*{testAmericanGridKernelLinearBasket1D}
Test 2D problem with linear kernel regression
\subsubsection*{testAmericanBasket3D}
Test 3D problem with \code{LocalLinearRegression} regressor.
\subsubsection{testAmericanGlobalBasket3D}
Test 3D problem with  global Hermite, Canonical and Tchebychev regressor.
\subsubsection*{testAmericanGridKernelLinearBasket3D}
Test 3D problem with linear kernel regression.
\subsubsection*{testAmericanBasket4D}
Test 4D problem with \code{LocalLinearRegression} regressor.

\subsection{testAmericanConvex}
Three test cases with basket American options are implemented trying to keep the convexity of the solution
\subsubsection*{testAmericanLinearConvexBasket1D}
Linear regression adapted in1D preserving the convexity at each time step.
\subsubsection*{testAmericanLinearConvexBasket2D}
Linear regression adapted in 2D trying to preserve the convexity at each time step.
\subsubsection*{testAmericanLinearConvexBasket3D}
Linear regression adapted  in 3D trying to preserve the convexity at each time step.

\subsection{testAmericanForSparse}
This test case is there to test sparse grid regressors (see section \ref{sec::Sparse}). As described earlier, we can use linear, quadratic or cubic representation on each cell. The reference is the same as in the testAmerican subsection thus linked to a Bermudean basket option.
\subsubsection*{testAmericanSparseBasket1D}
Use sparse 1D grids (thus equivalent to a full grid) for linear, quadratic or cubic representation.
\subsubsection*{testAmericanSparseBasket2D}
Use sparse 2D grids for linear, quadratic or cubic representation.
\subsubsection*{testAmericanSparseBasket3D}
Use sparse in 3D grids for linear, quadratic or cubic representation.
\subsubsection*{testAmericanSparseBasket4D}
Use sparse 4D grids for linear, quadratic or cubic representation.


\subsection{testAmericanOptionCorrel}
Same case as before but with correlations between assets. Used to test that the rotation due to the PCA analysis is working correctly.
\subsubsection*{testAmericCorrel}
Check in 2D that
\begin{itemize}
\item Local Constant by mesh regression with and without rotation gives the same result,
\item Local Linear regression by mesh with and without rotation gives the same result,
\item Global regression with and without rotation gives the same result.
\end{itemize}

\subsection{testAmericanOptionTree}
Simple 1D test case, to test the tree method on American options.
An Ornstein--Uhlenbeck process using an average return parameter close to zero is used to be close to the BS model. The OU model is approximated by a trinomial tree.

\section{testSwingOption}
\label{sec:testSwingOption}
The swing option problem is the generalization of the American option using a Black Scholes model for the underlying asset: on a set of dates \code{nStep} (chosen equal to 20 here), we can choose N dates (N equal to three) to exercise the option. At each exercise date $t$ , we get the pay-off $(S_t-K)^{+}$ where $S_t$ is the value of the underlying asset on the date $t$.
See \cite{jaillet2004valuation} for a description of the swing problem and backward solving techniques.
Due to the classic results on the Snell envelop for the European payoff, the analytical value of this problem is the sum of the payoff $N$ at the last dates $N$ where we can exercise (remember that the value of an American call is the European value).
The Markov state of the problem at a given date $t$ is given by the value of the underlying (Markov) and the number of exercises already performed on the date $t$.
This test case can be run in parallel with MPI.
In all test cases, we use a \code{LocalLinearRegression} to evaluate the conditional expectations used during the Dynamic Programming approach.
\subsubsection*{testSwingOptionInOptimization}
After having calculated the analytical solution of this problem, 
\begin{itemize}
\item a first resolution is provided using the \code{resolutionSwing} function. For this simple problem, only a regressor is needed to decide wether to exercise on the current date of not.
\item a second resolution is provided in the \code{resolutionSwingContinuation} function using the \code{Continuation} object (see chapter \ref{sec:continuation})
 allowing to store continuation values for a value of the underlying and for a stock level. 
This example is provided here to show how to use this object on a simple test case. This approach is not optimal here because obtaining the continuation value of an asset value 
and a stock level (only discrete here) means an unnecessary interpolation on the stock grids (here we choose a \code{RegularSpaceGrid} to describe the stock level and interpolate linearly between stock grids).  In the case of the swing with varying amounts to exercise \cite{jaillet2004valuation} or the gas storage problem, this object is very useful,
\item A final resolution is provided using the general framework described and the \code{DynamicProgrammingByRegressionDist} function described in the \ref{subsec:framework} subsection.
Again, the framework is needed for this simple test case, but it shows that it can be used even for some very simple cases.
\end{itemize}

\subsection{testSwingOption2D}
\label{subsec:swing2D}
Here we assume that we have two swing options similar to valuate and we solve the problem by ignoring that the stocks are independent: this means that we are solving the problem on a two-dimensional grid (for the stocks) instead of twice the same  problem on a grid with a stock.
\begin{itemize}
\item we start with an evaluation of the solution for a single swing with the \code{resolutionSwing} function giving a value $A$.
\item then we solve the two-dimensional problem (in stock) giving a value $B$ with our framework with the function \code{DynamicProgrammingByRegressionDist} .
\end{itemize}
Next, we check that $B=2A$.

\subsection{testSwingOption3}
We do the same as before, but the management of three similar swing options is achieved by solving as a three dimensional stock problem.

\subsection{testSwingOptimSimu / testSwingOptimSimuMpi}
This test case takes the problem described in the \ref{sec:testSwingOption} section, resolves it using the framework \ref{subsec:framework}.
Once the optimization using the regression (\code{LocalLinearRegression} regressor) has been performed, a simulation part is used using the previously calculated Bellman values. 
We check that the values obtained in optimization and simulation are close.
The two files of test cases (\code{testSwingOptimSimu/testSwingOptimSimuMpi}) use the two versions of MPI parallelization distributing or not the data on the processors.

\subsection{testSwingOptimSimuWithHedge}
The test case takes up the problem described in the section \ref{sec:testSwingOption}, solves it using the regression  (\code{LocalLinearRegression} regressor) when calculating the optimal coverage by the conditional tangent method as explained in \cite{warin2012gas}.
After optimization, a simulation part implements the optimal control and the associated optimal hedging policy.
We verify:
\begin{itemize}
\item That the optimization and simulation values are close
\item That the simulated hedge has an average almost equal to zero,
\item That the hedged swing simulations yield a reduced standard deviation from the value of the unhedged option obtained by the unhedged simulation. 
\end{itemize}
This test case shows that the multiple regimes introduced in the \ref{subsec:framework} framework can be used to calculate and store the optimal hedging policy.
This is achieved by creating a dedicated \code{OptimizeSwingWithHedge} optimizer.

\subsection{testSwingOptimSimuND / testSwingOptimSimuNDMpi}
The test case takes the problem described in the \ref{sec:testSwingOption} section, suppose we have two similar options to value and we ignore that the options are independent giving a problem to solve with two stocks managed jointly as in subsection \ref{subsec:swing2D}.
After optimizing the problem using regression (\code{LocalLinearRegression} regressor) 
We simulate the optimal control for this two-dimensional problem and check that the optimization and simulation values are close.
In \code{testSwingOptimSimuND} MPI parallelization, if enabled, parallelize only the calculation, while in \code{testSwingOptimSimuNDMpi} the data is also distributed on processors.
In the latter, two options are tested, 
\begin{itemize}
\item in \code{testSwingOptionOptim2DSimuDistOneFile} the Bellman values are distributed on the different processors but before being dumped, they are recombined to give a single file for the simulation.
\item in \code{testSwingOptionOptim2DSimuDistMultipleFile} Bellman values are distributed across different processors but each processor dumps its own Bellman Values. During simulation, each processor reads back its own Bellman values.
\end{itemize}
The same large-dimensional problem may only be achievable with the second approach.

\section{Gas Storage}
\subsection{testGasStorage / testGasStorageMpi}
\label{sec:testGasStorage}
The model used is a mean return model similar to the one described in \cite{warin2012gas}. We keep only one factor in equation (8) in \cite{warin2012gas}.
The problem consists in maximizing the gain of a gas storage by the methodology described in \cite{warin2012gas}.
All test cases are composed of three parts:
\begin{itemize}
\item an optimization is performed by regression (\code{LocalLinearRegression} regressor),
\item a first simulation of the optimal control using the continuation values stored during the optimization part,
\item a second simulation using directly the optimal controls stored during the optimization part.
\end{itemize}
We check that the three previously calculated values are close. \\
Using a dynamic programming method, we need to interpolate in the stock grid to get the Bellman values at a stock point.
Usually, a simple linear interpolator is used (giving a monotone scheme). As explained in \cite{warin2016some}, it is possible to use still monotonous higher order schemes.
We are testing different interpolators.
In all test cases, we use a \code{LocalLinearRegression} to evaluate conditional expectations. 
The MPI version makes it possible to test the distribution of data when using parallelization.
\subsubsection*{testSimpleStorage}
We use a classic regular grid with equally spaced  points to discretize the gas stock and a linear interpolator to interpolate in the stock.
\subsubsection*{testSimpleStorageLegendreLinear}
We use a Legendre grid with linear interpolation, so the result should be the same as above.
\subsubsection*{testSimpleStorageLegendreQuadratic}
We use a quadratic interpolator for the stock level.
\subsubsection*{testSimpleStorageLegendreCubic}
We use a cubic  interpolator for the stock level.
\subsubsection*{testSimpleStorageSparse}
We use a sparse grid interpolator (equivalent to a full grid interpolator because it is a one dimensional problem).
We only test the sparse grid with a linear interpolator.
\subsection{testGasStorageCut / testGasStorageCutMpi}
We take the previous gas storage problem and solve the transition problem without discretizing the command using an LP solver (see section \ref{sec:withCuts})
The test cases are composed of an optimization part followed by a simulation part comparing the results obtained.
\subsubsection{testSimpleStorageCut}
Test case without MPI distribution of stocks points.
A simple Regular grid object is used and conditional cuts are calculated using Local Linear Regressions.
\subsubsection{testSimpleStorageCutDist}
Test using MPI distribution. In all cases a Local Linear Regressor is used.
A file is used to store the conditional cuts.
\begin{itemize}
\item A first case uses a Regular grid,
  \item A second case uses a RegularLegendre grid.
\end{itemize}
\subsubsection{testSimpleStorageMultipleFileCutDist}
Test using MPI distribution. A Local Linear Regressor is used for cuts and a Regular grid is used.
Bender cuts are stored locally by each processor.
\subsection{testGasStorageTree/testGasStorageTreeMpi}
Optimizing storage for the price of gas modeled by a HJM model approximated by a tree.
The grids are simple regular grids.
In MPI, Bellman values are either stored in one file or in multiple files.
\subsection{testGasStorageTreeCut/testGasStorageTreeCutMpi}
Gas storage is optimized and simulated using cuts and trees for uncertainties. Gas price modeled by a HJM model approximated by a trinomial tree. The grids are simple regular grids.
In MPI, Bellman values are either stored in one file or in multiple files.

\subsection{testGasStorageKernel}
The model used is a mean reverting model similar to the one described in \cite{warin2012gas}. We keep only one factor in equation (8) in \cite{warin2012gas}.
The problem consists in maximizing the gain of a gas storage by the methodology described in \cite{warin2012gas}.
The specificity here is that a kernel regression method is used.
\subsubsection{testSimpleStorageKernel)}
Use the linear kernel regression method to solve the Gas Storage problem using the  Epanechnikov kernel.

\subsection{testGasStorageLaplacianLinearKernel}
The model used is a mean reverting model similar to the one described in \cite{warin2012gas}.
 We keep only one factor in equation (8) in \cite{warin2012gas}.The problem consists in maximizing the gain of a gas storage by the methodology described in \cite{warin2012gas}.
The specificity here is that a Laplacian kernel regression method is used.
\subsubsection{testSimpleStorageLaplacianLinearKernel}
Use the linear kernel regression method to solve the Gas Storage problem using the Laplacian kernel using the divide and conquer method.

\subsection{testGasStorageLaplacianConstKernel}
The model used is a mean reverting model similar to the one described in \cite{warin2012gas}.
 We keep only one factor in equation (8) in \cite{warin2012gas}.The problem consists in maximizing the gain of a gas storage by the methodology described in \cite{warin2012gas}.
The specificity here is that a Laplacian kernel regression method  is used.
\subsubsection{testSimpleStorageLaplacianConstKernel}
Use the constant kernel regression method to solve the Gas Storage problem using the Laplacian kernel using the divide and conquer method.


\subsection{testGasStorageLaplacianGridKernel}
The model used is a mean reverting model similar to the one described in \cite{warin2012gas}. We keep only one factor in equation (8) in \cite{warin2012gas}.The problem consists in maximizing the gain of a gas storage by the methodology described in \cite{warin2012gas}.
The specificity here is that a Laplacian kernel regression method  is used.
\subsubsection{testSimpleStorageLaplacianGridKernel}
Use the constant kernel regression method to solve the Gas Storage problem using the Laplacian kernel using the fast summation method.

\subsection{testGasStorageVaryingCavity}
The stochastic model is the same as in the section \ref{sec:testGasStorage}.
As before, all test cases are composed of three parts:
\begin{itemize}
\item  an optimization is performed by regression (\code{LocalLinearRegression} regressor),
\item a first simulation of the optimal control using the continuation values stored during the optimization part,
\item a second simulation using directly the optimal controls stored during the optimization part.
\end{itemize}
We check that the three previously calculated values are close on this test case where the grid describing the gas storage constraint is variable in time.
This makes it possible to check the splitting of the grids during the parallelization.

\subsection{testGasStorageSwitchingCostMpi}
The test case is similar to that of the \ref{sec:testGasStorage} section (therefore using regression methods): we added an extra cost when switching from one regime to another.
The additional cost results in the fact that the Markov state is composed of the asset price, the level of stock and the current regime in which we are (the latter 
is not present in another test case on the gas storage).
This test case shows that our framework solves regime switching problems.
As before, all test cases are composed of three parts:
\begin{itemize}
\item an optimization is performed by regression (\code{LocalLinearRegression} regressor),
\item a first simulation of the optimal control from the sequence values stored during the optimization part,
\item a second simulation using directly the optimal controls stored during the optimization part.
\end{itemize}
We check that the three previously calculated values are close.

\subsection{testGasStorageSDDP}
Modeling the asset is similar to the other test case.
We assume that we have $N$ similar independent storages. So solving the problem with $N$ stocks should yield $N$ times the value of a stock.
\begin{itemize}
\item First, the storage value is calculated by dynamic programming giving the value $A$,
\item Then the SDDP method (chapter \ref{chap:SDDP}) is used to value the problem giving the $B$ value. Benders cuts must be made subject to price level.
\end{itemize}
We check that $B$ is close to $N A$.
\subsubsection*{testSimpleStorageSDDP1D}
Test the case $N=1$.
\subsubsection*{testSimpleStorageSDDP2D}
Test the case $N=2$.
\subsubsection*{testSimpleStorageSDDP10D}
Test the case $N=10$.

\subsection{testGasStorageSDDPTree}
\subsubsection{testSimpleStorageDeterministicCutTree}
The volatility is set to zero to obtain a deterministic problem.
\begin{itemize}
\item First by Dynamic Programming, the optimal control is calculated and tested in simulation.
\item Then backward part of SDDP and forward part are tested using a point grid for storage
\end{itemize}
\subsubsection{testSimpleStorageCutTree}
In stochastics, the backward and forward resolution of the SDDP solver with tree are tested using points defined on a grid.
Convergence is checked by comparing results from a DP solver with regressions.
\subsubsection{testSimpleStorageSDDPTree1D1Step}
In stochastics, the global SDDP solver iterating forward and backward is used  to value the gas storage.
The comparison with dynamic programming methods with regressions is carried out.

\section{testLake / testLakeMpi}
This is the case of a reservoir with inflows following an AR1 model.
We can withdraw water from the reservoir (maximum withdrawal rate given) to produce energy by selling it at a given price (taken equal to 1 per unit of volume).
We wish to maximize the expected gains obtained by optimal management of the lake.
The problem allows to show how some stochastic flows can be taken into account with dynamic programming with regression (\code{LocalLinearRegression} regressor used).\\
The test case is composed of three parts:
\begin{itemize}
\item an optimization is performed by regression (\code{LocalLinearRegression} regressor),
\item a first simulation of the optimal control from the contination values stored during the optimization part,
\item a second simulation using directly the optimal controls stored during the optimization part.
\end{itemize}
We check that the three previously calculated values are close.

\section{testOptionNIGL2}
In this test case we assume that the log of an asset value follows a NIG process \cite{barndorff1997processes}. We want to price a call option assuming that we use the mean variance criterion using the algorithm developed in chapter \ref{chap:variance}.\\
First, an optimization is carried out then in a simulation part, the optimal hedging strategy is tested.

\section{testDemandSDDP}
This test case is the simplest using the SDDP method.
We assume that we have a demand according to an AR 1 model
\begin{equation*}
D^{n+1} = k (D^n-D) + \sigma_d  g + k D ,
\end{equation*}
where $D$ is the average demand, $\sigma_d$ the standard deviation of the demand on a time step, $k$ the average reverting coefficient, $D^0=D$, and $g$ a centered Gaussian variable on the unit.
We have to meet demand by buying energy at a $P$ price.
We want to calculate the next expected value
\begin{eqnarray*}
  V & = & P \E\left[ \sum_{i=0}^N D_i \right] \\
    & = & (N+1)D_0 P
\end{eqnarray*}
This can be done (artificially) using SDDP.
\subsubsection*{testDemandSDDP1DDeterministic}
It takes  $\sigma_d =0$.
\subsubsection*{testDemandSDDP1D}
It solves the stochastic problem.

\section{testThermalAsset}
Solve a switching problem estimating the value of a thermal asset described in paragraph  \ref{parthermalSwitching}.
The two assets follow an HJM model with one factor each.
The objective function consists in maximizing the gain in expectation  managing the asset that can be switch on or off with some specific minimal time in each regime.
A switching cost switching on the asset is also added.

\section{Reservoir variations with SDDP}
\subsection{testReservoirWithInflowsSDDP}
\label{sec:testReservoirWithInflowsSDDP}
For this SDDP test case, we assume that we have $N$ similar independent reservoirs with inflows given at all times by  independent centered Gaussian variables with standard deviation $\sigma_i$.
We suppose that we must satisfy the dates $M$  a demand given by independent Gaussian variables centered with a standard deviation $\sigma_d$.
In order to meet the demand, we can buy water in the amount $q_t$  at a deterministic price $S_t$ or withdraw water from the reservoir at a pace lower than a withdrawal rate.
Under the demand constraint, we want to minimize:
\begin{equation*}
\E\left[ \displaystyle{\sum_{i=0}^M} q_t S_t \right]
\end{equation*}
Each time we check that the forward and backward methods converge to the same value.
Due to the independence of uncertainties, the dimension of the Markov state is equal to $N$.
\subsubsection*{testSimpleStorageWithInflowsSDDP1DDeterminist}
$\sigma_i=0$ for inflows and $\sigma_d= 0.$ for demand. $N$ taken equal to 1.
\subsubsection*{testSimpleStorageWithInflowsSDDP2DDeterminist}
$\sigma_i=0$  for inflows and  $\sigma_d= 0.$ for demand. $N$ taken equal to 2.
\subsubsection*{testSimpleStorageWithInflowsSDDP5DDeterminist}
$\sigma_i=0$  for inflows and $\sigma_d= 0.$ for  demand. $N$ taken equal to 5.
\subsubsection*{testSimpleStorageWithInflowsSDDP1D}
$\sigma_i=  0.6$, $\sigma_d= 0.8$ for demand. $N=1$
\subsubsection*{testSimpleStorageWithInflowsSDDP2D}
$\sigma_i=  0.6$ for inflows, $\sigma_d= 0.8$ for demand. $N=2$
\subsubsection*{testSimpleStorageWithInflowsSDDPD}
$\sigma_i=  0.6$ for inflows, $\sigma_d= 0.8$ for demand. $N=5$.

\subsection{testStorageWithInflowsSDDP}
\label{sec:testStorageWithInflowsSDDP}
For this SDDP test case, we assume that we have similar independent reservoirs $N$ with inflows following an AR1 model:
\begin{equation*}
X^{n+1} = k (X^n-X) + \sigma  g + X  ,
\end{equation*}
with $X^0=X$, $\sigma$ the associated standard deviation, $g$ a Gaussian variable centered on the unit.

We suppose that we have to satisfy at $M$ dates a demand   following an AR1 process too.
In order to satisfy the demand, we can buy some water with quantity $q_t$  at a deterministic price $S_t$ or withdraw water from the reservoir at a pace lower than a withdrawal rate.
Under the demand constraint, we want to minimize:
\begin{equation*}
  \displaystyle \E \left[ {\sum_{i=0}^M} q_t S_t \right]
\end{equation*}
Each time we check that the forward and backward methods converge to the same value.
Due to the structure of uncertainties the dimension of the Markov state is equal to $2N+1$ ($N$ storage, $N$ inflows,  and demand).

\subsubsection*{testSimpleStorageWithInflowsSDDP1DDeterministic}
All parameters $\sigma$  are set to 0. $N=1$.
\subsubsection*{testSimpleStorageWithInflowsSDDP2DDeterministic}
All parameters $\sigma$  are set to 0. $N=2$.
\subsubsection*{testSimpleStorageWithInflowsSDDP5DDeterministic}
All parameters $\sigma$  are set to 0. $N=5$.
\subsubsection*{testSimpleStorageWithInflowsSDDP10DDeterministic}
All parameters $\sigma$  are set to 0. $N=10$.
\subsubsection*{testSimpleStorageWithInflowsSDDP1D}
$\sigma=  0.3$ for inflows, $\sigma= 0.4$ for demand. $N=1$.
\subsubsection*{testSimpleStorageWithInflowsSDDP5D}
$\sigma=  0.3$ for inflows, $\sigma= 0.4$ for demand. $N=5$.


\subsection{testStorageWithInflowsAndMarketSDDP}
This is the same problem as \ref{sec:testStorageWithInflowsSDDP}, but the price $S_t$ follow an AR 1 model.
We use an SDDP approach to solve this problem.
Due to price dependencies, the reduction of SDDP must be effected conditionally on the price level.
\subsubsection*{testSimpleStorageWithInflowsAndMarketSDDP1DDeterministic}
All volatilities set to 0. $N=1$.
\subsubsection*{testSimpleStorageWithInflowsAndMarketSDDP2DDeterministic}
All volatilities set to 0. $N=2$.
\subsubsection*{testSimpleStorageWithInflowsAndMarketSDDP5DDeterministic}
All volatilities set to 0. $N=5$.
\subsubsection*{testSimpleStorageWithInflowsAndMarketSDDP10DDeterministic}
All volatilities set to 0. $N=10$.
\subsubsection*{testSimpleStorageWithInflowsAndMarketSDDP1D}
$\sigma=  0.3$ for inflows, $\sigma= 0.4$ for demand, $\sigma=0.6$ for the spot price. $N=1$.
\subsubsection*{testSimpleStorageWithInflowsAndMarketSDDP5D}
$\sigma=  0.3$ for inflows, $\sigma= 0.4$ for demand, $\sigma=0.6$ for the spot price. $N=5$.


\section{Semi-Lagrangian}
\subsection{testSemiLagrangCase1/testSemiLagrangCase1}
Test Semi-Lagrangian deterministic methods for HJB equation.
This corresponds to the second test case without control in \cite{warin2016some} (2 dimensional test case).
\subsubsection*{TestSemiLagrang1Lin}
Test the  Semi-Lagrangian method with the linear interpolator.
\subsubsection*{TestSemiLagrang1Quad}
Test the  Semi-Lagrangian method with the quadratic interpolator.
\subsubsection*{TestSemiLagrang1Cubic}
Test the  Semi-Lagrangian method with the cubic interpolator.
\subsubsection*{TestSemiLagrang1SparseQuad}
Test the sparse grid interpolator with a quadratic interpolation.
\subsubsection*{TestSemiLagrang1SparseQuadAdapt}
Test the sparse grid interpolator with a quadratic interpolation and some adaptation in the meshing.

\subsection{testSemiLagrangCase2/testSemiLagrangCase2}
Test Semi-Lagrangian deterministic methods for HJB equation.
This corresponds to the first case without control in \cite{warin2016some} (2 dimensional test case).
\subsubsection*{TestSemiLagrang2Lin}
Test the  Semi-Lagrangian method with the linear interpolator.
\subsubsection*{TestSemiLagrang2Quad}
Test the  Semi-Lagrangian method with the quadratic interpolator.
\subsubsection*{TestSemiLagrang2Cubic}
Test the  Semi-Lagrangian method with the cubic interpolator.
\subsubsection*{TestSemiLagrang2SparseQuad}
Test the sparse grid interpolator with a quadratic interpolation.

\subsection{testSemiLagrangCase2/testSemiLagrangCase2}
Test Semi-Lagrangian deterministic methods for HJB equation.
This corresponds to the stochastic target test case 5.3.4 in \cite{warin2016some}.
\subsubsection*{TestSemiLagrang3Lin}
Test the  Semi-Lagrangian method with the linear interpolator.
\subsubsection*{TestSemiLagrang3Quad}
Test the  Semi-Lagrangian method with the quadratic interpolator.
\subsubsection*{TestSemiLagrang3Cubic}
Test the  Semi-Lagrangian method with the cubic interpolator.


\section{Non emimissive test case}
\subsection{testDPNonEmissive}
Solve the problem described in part \ref{part:NonEm} by dynamic programming and regression.
\begin{itemize}
\item first an optimization is realized,
\item the  an simulation part permit to test the controls obtained.
\end{itemize}

\subsection{testSLNonEmissive}
Solve the problem described in part \ref{part:NonEm} by the Semi-Lagrangian method.
\begin{itemize}
\item first an optimization is realized,
\item the  an simulation part permit to test the controls obtained.
\end{itemize}

\section{Nesting for Non Linear PDE's}
\subsection{Some HJB test}
The control problem where $\mathcal{A}$ is the set of adapted integrable processes.
\begin{align*}
dX = 2 \sqrt{\theta} \alpha dt + \sqrt{2} dW_t, \\
V= \inf_{\alpha \in  \mathcal{A}} E[ \int_0^T | \alpha_s|^2 dt + g(X_T)]
\end{align*}
The HJB equation corresponding 
\[
(-\partial_t u-{\cal L} u)(t,x)  = f(Du(t,x))
\]
 \begin{flalign}
   \Lc u(t,x) := & \mu Du(t,x) +  \frac{1}{2} \sigma \sigma^{\top} \!:\! D^2 u(t,x), \\
  f(z) =&  -\theta ||z||^2_2   \
 \end{flalign}
 such that a solution is
 \begin{align}
\label{eq:semiAnal}
u(t,x) =- \frac{1}{\theta} \log \big(  \E[ e^{ - \theta g(x + \sqrt{2} W_{T-t})}]\big).
\end{align}
 We use the nesting method with  $\mu=0 $, $\sigma = \sqrt{2} I_d $.
These test cases are in the \code{test/c++/unit/branching} directory.
\subsubsection{testHJCConst}
In this test case, we use a special resolution function assuming that the parameters of the PDE are constant: this allows us to precompute the inverse of some matrices.
\subsubsection{testHJCExact}
We test here the particular case where the SDE can be exactly simulated with a scheme
\begin{align*}
     X_{t+dt} =  A(t,dt)  X_t + B(t,dt) + C(t,dt) g
\end{align*}
with a $g$ Gaussian-centered unit vector.
\subsubsection{testHJBEuler}
We use a resolution function assuming that the SDE is discretized by an Euler scheme.
\subsection{Some Toy example: testUD2UTou}
We want to solve:
 \begin{align*}
              (-\partial_t u-{\cal L} u)(t,x)  = f(u,Du(t,x),D^2u(t,x))
 \end{align*}
 with
 \[
 \begin{array}{ll}
   \mu= & \frac{\mu_0}{d} \un_d,\\
   \sigma = & \frac{\sigma_0}{\sqrt{d}} \I_d, \\
   f(t,x,y,z,\theta)=& \cos(\sum_{i=1}^d x_i) (\alpha +\frac{1}{2}\sigma_0^2)
   e^{\alpha (T-t)}+ \sin(\sum_{i=1}^d x_i) \mu_0 e^{\alpha (T-t)} +
   a \sqrt{d} \cos(\sum_{i=1}^d x_i)^2 e^{2\alpha (T-t)} \\
   & + \frac{a}{\sqrt{d}} ( - e^{2\alpha (T-t)} ) \vee ( e^{2\alpha (T-t)} \wedge ( y \sum_{i=1}^d \theta_{i,i})),
 \end{array}
 \]
 with a solution
 \[
 u(t,x)= e^{\alpha (T-t)} \cos( \sum_{i=1}^d x_i)
 \]
 \subsection{Some Portfolio optimization}
We assume that we dispose of $d=4$  securities all of them  being defined by a Heston model:
 \begin{align*} 
 dS_t^i =& \mu^i S_t^i dt +  \sqrt{Y^i_t} S^i_t dW_t^{(2i-1)}  \\
 dY_t^i =&  k^i (m^i-Y_t^i)dt + c^i \sqrt{Y^i_t} dW_t^{(2i)},
 \end{align*}
 where $W=(W^{(1)}, \dots , W^{(2d)})$ is a Brownian motion in $\R^{2d}$.\\
 The non-risky asset $S^0$  has a $0$ return so $dS^0_t=0$, $t\in[0,1]$.\\
 The investor chooses an adapted process $\{\kappa_t,t\in[0,T]\}$ with values in $\R^n$, where $\kappa^i_t$ is the amount he decides to invest into asset $i$.\\
The portfolio dynamic is given by:
 \begin{align*}
 dX^\kappa_t
 =
 \kappa_t\cdot \frac{dS_t}{S_t} +(X^\kappa_t-\kappa_t\cdot \1)\frac{d S^0_t}{S^0_t}
 = 
 \kappa_t\cdot \frac{dS_t}{S_t}.
 \end{align*}
Let $\Ac$ be the collection of all adapted processes $\kappa$ with values in $\R^d$ and which are integrable with respect to $S$. Given an absolute risk aversion coefficient $\eta>0$, the portfolio optimization problem is defined by:
 \begin{align}
 \label{prob-portefeuille}
 v_0
 :=&
 \sup_{\kappa\in\Ac} \E\left[-\exp\left(-\eta X^\kappa_T\right)\right].
 \end{align}
The problem doesn't depend on the $s^i$.
As in \cite{zariphopoulou2001solution}, we can guess that the solution can be expressed as
$$
v(t,x,y^1,\dots,y^d) = e^{-\eta x} u(y^1,\dots, y^d)
$$
and using Feyman Kac it is easy to see that a general solution can be written
\begin{align}
 \label{zariphopoulouND}
 v(t,x,y)=-e^{-\eta x} \E[\prod_{i=1}^d \exp\left(-\frac{1}{2}\int_t^T \frac{(\mu^i)^2}{\tilde Y^i_s}ds \right) ]
 \end{align}
 with
 \begin{align*}
 \tilde Y_t^i=y^i \quad
 &\mbox{  and}&
 d\tilde Y_t^i = k^i (m^i-\tilde Y_t^i)dt +  c^i\sqrt{\tilde Y^i_t} dW^i_t,
 \end{align*}
 where $y^i$ is the initial volatility value on the date $0$ for the asset $i$.\\
 We assume, in our example, that all the assets have the same parameters which are equal to the parameters taken in the two-dimensional case. We also assume that the initial conditions are the same as before.\\
By choosing $ \bar \sigma >0$, we can write the problem as the equation \eqref{eqPDEFull} in dimension $d+1$  where
 \begin{align*}
 \mu = & ( 0, k^1 (m^1-y^1), \dots,k^d (m^d-y^d) )^{\top},  \qquad
 \sigma = \left(  \begin{array}{lllll}
 \bar \sigma & 0 & \dotsb & \dotsb &  0 \\
 0 & c \sqrt{m^1} & 0 & \dotsb & 0 \\
 0  & \dotsb &  \ddots & \dotsb  & 0 \\
 0  & \dotsb &  \dotsb & \ddots  & 0 \\
 0 & \dotsb & \dotsb & 0 & c \sqrt{m^d}
 \end{array} \right)
 \end{align*}
 always with the same terminal condition
 \begin{align*}
 g(x) = - e^{-\eta x}
 \end{align*} 
 and 
 \begin{align}
 f(x,y,z,\theta)= &
 -\frac{1}{2} \bar{\sigma}^2 \theta_{11}  +\frac{1}{2} \sum_{i=1}^d (c^i)^2 ((y^i)^2-m^i) \theta_{i+1,i+1} -  \sum_{i=1}^d  \frac{\mu^i z_1 }{2 y^i \theta_{11}}.
 \end{align}
 In order to have  $f$ Lipschitz, we truncate the control limiting the amount invested by taking
\begin{align*}
f_{M}(y,z,\theta) = &
-\frac{1}{2} \bar \sigma^2 \theta_{11}  +\frac{1}{2} \sum_{i=1}^d (c^i)^2 ((y^i)^2-m^i) \theta_{2,2} + \\
&
 \sup_{ \begin{array}{c}
 \eta = (\eta^1,\dots,\eta^d) \\
 0 \le \eta^i\le M, i=1,d
 \end{array}}   \sum_{i=1}^d \left(\frac{1}{2}(\eta^i)^2 y^i \theta_{11}+(\eta^i) \mu^i z_1\right).
\end{align*}
\subsubsection{testPortfolioExact}
The Ornstein--Uhlenbeck process used as a driving process is simulated exactly.
\subsubsection{testPortfolioEuler}
The  Ornstein--Uhlenbeck process used as a driving process is simulated using an Euler scheme.
 
\chapter{Some  python test cases description}
This part is devoted to some test cases only available in python. These examples uses the low level python interface.

\section{Microgrid Management}
\subsection{testMicrogridBangBang}
\label{sec:testMicrogridBangBang}

A microgrid is a collection of renewable energy sources, a diesel generator, and a battery for energy storage. The objective is to match the residual demand (difference between the demand of electricity and supply from renewables) while minimizing the total expected cost of running the microgrid. In particular a penalty is assessed for insufficient supply that leads to blackouts. The setup is similar to the one described in [\cite{ludkovski2018simulation}, Section 7]. We take the diesel generator as the only control $d_t$; output/input from/into the battery is then a function of the residual demand $X_t$ (exogenous stochastic process), inventory level of the battery $I_t$, and $d_t$. The diesel generator operates under two regimes: OFF and ON. When it is OFF it does not supply power $d_t = 0$, however when it is ON the power output is a deterministic function of the state $d_t = d(X_t,I_t)$. As a result, the problem is a standard stochastic control model with switching-type bang-bang control.

We parameterize the algorithm to easily switch between multiple approximation schemes for the conditional expectation at the core of the Dynamic Programming equation. Particularly the following schemes are implemented:

\begin{itemize}
\item Regularly spaced grid for $I_t$ and local polynomial basis in $X_t$ for each level of the grid.
\item Adaptive piecewise-defined polynomial basis in -2D for $(X_t,I_t)$.
\item Global 2D polynomial basis on $(X_t,I_t)$.
\item Bivariate Kernel regression on $(X_t,I_t)$.
\end{itemize}

\subsection{testMicrogrid}
\label{sec:testMicrogrid}
We extend the previous example to include the recent work \cite{alasseur2018regression} where the action space for the control is $d_t \in \{0\}\cup[1,10]$ kW, rather than being bang-bang. As a result, the optimal control is chosen in two steps: first the controller picks the regime: ON or OFF; if ON, she then decides the optimal, continuous level of the diesel output. Due to the additional flexibility available to the controller compared to the previous example, we expect to observe lower cost compared to Section \ref{sec:testMicrogridBangBang}. The user can switch between this and the previous setting by changing the parameter \code{controlType} in the \code{parameters.py} file.


\section{Dynamic Emulation Algorithm (DEA)}
\subsection{testMicrogridDEA}
\label{sec:DEA}
In this section we discuss the implementation of the Dynamic Emulation Algorithm developed in \cite{ludkovski2018simulation}. In that paper the authors reformulate the stochastic control problem as an ``iterative sequence of machine learning tasks''. The philosophy of DEA is to combine together Regression Monte Carlo (RMC) with Design of Experiments. The algorithm has the following properties:

\begin{itemize}
\item The learning for the continuation value function at each step in the backward-iteration of the Dynamic Programming Equation is completely modularized. As a result, the user can seamlessly switch between different regression schemes (for example: adaptive local polynomial basis in -2D or -1D, multivariate kernel regression, etc.) across different time-steps;
    
\item The empirical approximation uses distinct designs $\mathcal{D}_t$ at each $t$; thus the user can have design sites independently chosen for different $t$'s, which also eliminates the requirement to store the full history of the simulated paths of $(X_t)$. One-step paths can now replace the full history. In Figure \ref{fig:designSpecification} we present examples of two possible designs we use in the implementation. The image in the left panel represents a space-filling design using a Sobol sequence in -2D. This design is appropriate for a bivariate regression over $(X_t, I_t)$.  On the right, we present another space-filling design in -1D  with a regularly spaced grid in $I_t$ (y-axis) and a -1D Sobol sequence in $X_t$ (x-axis). In \cite{ludkovski2018simulation} the authors discuss several further designs which can be easily implemented.
    
\item Batched designs, i.e. a partially nested scheme that generates multiple $X_t$-paths from the same unique design site, can be accommodated.
    
\item Simulation budget (i.e.~the size of $\mathcal{D}_t$) can vary through the time-steps and need not be fixed as in standard RMC.

\end{itemize}


\begin{figure}[!ht]
  \centering
  \begin{subfigure}[b]{0.45\textwidth}
    \includegraphics[width=\textwidth]{sobol2D.png}
    \caption{Sobol-2D QMC sequence}
    \label{fig:sobol2D}
  \end{subfigure}
 \quad
    \begin{subfigure}[b]{0.45\textwidth}
    \includegraphics[width=\textwidth]{sobol1d.png}
    \caption{Gridded design }
    \label{fig:sobol1D}
  \end{subfigure}
\caption{Illustration of two simulation designs. In both panels the $X_t$-coordinate is on the x-axis and $I_t$ on the y-axis.}
\label{fig:designSpecification}
\end{figure}

Several different experiments have confirmed the significant effect of the design  $\mathcal{D}_t$ on the performance of the RMC algorithms. DEA allows us to test for this effect by allowing the user to easily specify $\mathcal{D}_t$. The structure of this library allows for easy implementation of such modular algorithms. As a proof of concept, we re-implement the microgrid example of Section \ref{sec:testMicrogridBangBang} with the following specifications:
\begin{itemize}
\item The 10 time-steps (25\% of the total of 40 time-steps) closest to maturity use adaptive local polynomial basis in -1D with gridded design similar to the Figure \ref{fig:sobol1D}. Moreover, for these $t$'s we used $|\mathcal{D}_t| = 22,000 = N_t$ unique design sites;
    
\item The other 30 steps (first 75\%) use design sites allocated according to Sobol-2D as in figure \ref{fig:sobol2D} with a global polynomial basis regression scheme. For these, we build a batched design of 1000 unique sites, each replicated 10 times for a total simulation budget of $N_t = 1000 \times 10 =10^4$. 
\end{itemize}

\bibliographystyle{plain}
\bibliography{MyBib}

\end{document}