From 4f7330cb52975b8e579f3b7528693dd7beccb3df Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?S=C3=A9bastien=20Villemot?=
Date: Wed, 30 Jan 2019 19:05:32 +0100
Subject: [PATCH] Dynare++: add LaTeX overview of the Tensor Library
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
The material of this document comes from the introduction to the library that
had been lost in the move away from CWEB (formerly tl/cc/main.web).
This file gives a good overview of the library. It has been adapted from TeX to
LaTeX. Also I fixed a mistake in the FaĆ di Bruno's tensor formula.
---
dynare++/tl/Makefile.am | 15 +++
dynare++/tl/tl.tex | 245 ++++++++++++++++++++++++++++++++++++++++
windows/dynare.nsi | 2 +-
3 files changed, 261 insertions(+), 1 deletion(-)
create mode 100644 dynare++/tl/tl.tex
diff --git a/dynare++/tl/Makefile.am b/dynare++/tl/Makefile.am
index ffebab6fe..476329431 100644
--- a/dynare++/tl/Makefile.am
+++ b/dynare++/tl/Makefile.am
@@ -1 +1,16 @@
SUBDIRS = cc testing
+
+PDF_TARGETS =
+
+if HAVE_PDFLATEX
+PDF_TARGETS += tl.pdf
+endif
+
+pdf-local: $(PDF_TARGETS)
+
+tl.pdf: tl.tex
+ $(PDFLATEX) tl
+ $(PDFLATEX) tl
+
+clean-local:
+ rm -f *~ *.pdf *.log *.aux *.out
diff --git a/dynare++/tl/tl.tex b/dynare++/tl/tl.tex
new file mode 100644
index 000000000..9996a4d87
--- /dev/null
+++ b/dynare++/tl/tl.tex
@@ -0,0 +1,245 @@
+\documentclass[11pt,a4paper]{article}
+
+\usepackage{amssymb}
+\usepackage{amsmath}
+
+\usepackage{fullpage}
+
+\begin{document}
+\author{Ondra Kamenik}
+\title{Multidimensional Tensor Library \\ for perturbation methods applied to DSGE
+models}
+
+\date{2004}
+\maketitle
+
+\section{Introduction}
+
+The design of the library was driven by the needs of perturbation
+methods for solving Stochastic Dynamic General Equilibrium models. The
+aim of the library is not to provide an exhaustive interface to
+multidimensional linear algebra. The tensor library's main purposes
+include:
+\begin{itemize}
+
+\item Define types for tensors, for a multidimensional index of a
+tensor, and types for folded and unfolded tensors. The tensors defined
+here have only one multidimensional index and one reserved
+one-dimensional index. The tensors should allow modelling of higher
+order derivatives with respect to a few vectors with different sizes
+(for example $\left[g_{y^2u^3}\right]$). The tensors should allow
+folded and unfolded storage modes and conversion between them. A
+folded tensor stores symmetric elements only once, while an unfolded
+stores data as a whole multidimensional cube.
+
+\item Define both sparse and dense tensors. We need only one particular
+type of sparse tensor. This in contrast to dense tensors, where we
+need much wider family of types.
+
+\item Implement the Faa Di Bruno multidimensional formula. So, the main
+purpose of the library is to implement the following step of Faa Di Bruno:
+$$\left[B_{s^k}\right]_{\alpha_1\ldots\alpha_k}
+=\left[h_{y^l}\right]_{\gamma_1\ldots\gamma_l}
+\left(\sum_{c\in M_{l,k}}
+\prod_{m=1}^l\left[g_{s^{\vert c_m\vert}}\right]^{\gamma_m}_{c_m(\alpha)}\right)$$
+where $s$ can be a compound vector of variables, where $h_{y^l}$ and $g_{s^i}$
+are tensors, $M_{l,k}$ is a set of
+all equivalences of $k$ element set having $l$ classes, $c_m$ is
+$m$-th class of equivalence $c$, $\vert c_m\vert$ is its
+ cardinality, and $c_m(\alpha)$ is a tuple of
+picked indices from $\alpha$ by class $c_m$.
+
+Note that the sparse tensors play a role of $h$ in the Faa Di Bruno, not
+of $B$ nor $g$.
+
+\end{itemize}
+
+\section{Classes}
+
+The following list is a road-map to various classes in the library.
+
+\begin{description}
+
+\item[Tensor]
+Virtual base class for all dense tensors, defines \emph{index} as the
+multidimensonal iterator
+\item[FTensor]
+Virtual base class for all folded tensors
+\item[UTensor]
+Virtual base class for all unfolded tensors
+\item[FFSTensor]
+Class representing folded full symmetry dense tensor,
+for instance $\left[g_{y^3}\right]$
+\item[FGSTensor]
+Class representing folded general symmetry dense tensor,
+for instance $\left[g_{y^2u^3}\right]$
+\item[UFSTensor]
+Class representing unfolded full symmetry dense tensor,
+for instance $\left[g_{y^3}\right]$
+\item[UGSTensor]
+Class representing unfolded general symmetry dense tensor,
+for instance $\left[g_{y^2u^3}\right]$
+\item[URTensor]
+Class representing unfolded/folded full symmetry, row-oriented,
+dense tensor. Row-oriented tensors are used in the Faa Di Bruno
+above as some part (few or one column) of a product of $g$'s. Their
+fold/unfold conversions are special in such a way, that they must
+yield equivalent results if multiplied with folded/unfolded
+column-oriented counterparts.
+\item[URSingleTensor]
+Class representing unfolded/folded full symmetry, row-oriented,
+single column, dense tensor. Besides use in the Faa Di Bruno, the
+single column row oriented tensor models also higher moments of normal
+distribution.
+\item[UPSTensor]
+Class representing unfolded, column-oriented tensor whose symmetry
+is not that of the $\left[B_{y^2u^3}\right]$ but rather of something
+as $\left[B_{yuuyu}\right]$. This tensor evolves during the product
+operation for unfolded tensors and its basic operation is to add
+itself to a tensor with nicer symmetry, here $\left[B_{y^2u^3}\right]$.
+\item[FPSTensor]
+Class representing partially folded, column-oriented tensor whose
+symmetry is not that of the $\left[B_{y^3u^4}\right]$ but rather
+something as $\left[B_{yu\vert y^3u\vert u^4}\right]$, where the
+portions of symmetries represent folded dimensions which are combined
+in unfolded manner. This tensor evolves during the Faa Di Bruno
+for folded tensors and its basic operation is to add itself to a
+tensor with nicer symmetry, here folded $\left[B_{y^3u^4}\right]$.
+\item[USubTensor]
+Class representing unfolded full symmetry, row-oriented tensor which
+contains a few columns of huge product
+$\prod_{m=1}^l\left[g_{c_m}\right]^{\gamma_m}_{c_m(\alpha)}$. This is
+needed during the Faa Di Bruno for folded matrices.
+\item[IrregTensor]
+Class representing a product of columns of derivatives
+$\left[z_{y^ku^l}\right]$, where $z=[y^T,v^T,w^T]^T$. Since the first
+part of $z$ is $y$, the derivatives contain many zeros, which are not
+stored, hence the tensor's irregularity. The tensor is used when
+calculating one step of Faa Di Bruno formula, i.e.
+$\left[f_{z^l}\right]\sum\prod_{m=1}^l\left[z_{c_m}\right]^{\gamma_m}_{c_m(\alpha)}$.
+\item[FSSparseTensor]
+Class representing full symmetry, column-oriented, sparse tensor. It
+is able to store elements keyed by the multidimensional index, and
+multiply itself with one column of row-oriented tensor.
+\item[FGSContainer]
+Container of \texttt{FGSTensor}s. It implements the Faa Di Bruno with
+unfolded or folded tensor $h$ yielding folded $B$. The methods are
+\texttt{FGSContainer::multAndAdd}.
+\item[UGSContainer]
+Container of \texttt{UGSTensor}s. It implements the Faa Di Bruno with
+unfolded tensor $h$ yielding unfolded $B$. The method is
+\texttt{UGSContainer::multAndAdd}.
+\item[StackContainerInterface]
+Virtual pure interface describing all logic
+of stacked containers for which we will do the Faa Di Bruno operation.
+\item[UnfoldedStackContainer]
+Implements the Faa Di Bruno operation for stack of
+containers of unfolded tensors.
+\item[FoldedStackContainer]
+Implements the Faa Di Bruno for stack of
+containers of folded tensors.
+\item[ZContainer]
+The class implements the interface \texttt{StackContainerInterface} according
+to $z$ appearing in context of DSGE models. By a simple inheritance,
+we obtain \texttt{UnfoldedZContainer} and also \texttt{FoldedZContainer}.
+\item[GContainer]
+The class implements the interface \texttt{StackContainerInterface} according
+to $G$ appearing in context of DSGE models. By a simple inheritance,
+we obtain \texttt{UnfoldedGContainer} and also \texttt{FoldedGContainer}.
+\item[Equivalence]
+The class represents an equivalence on $n$-element set. Useful in the
+Faa Di Bruno.
+\item[EquivalenceSet]
+The class representing all equivalences on $n$-element set. Useful in the
+Faa Di Bruno.
+\item[Symmetry]
+The class defines a symmetry of general symmetry tensor. This is it
+defines a basic shape of the tensor. For $\left[B_{y^2u^3}\right]$,
+the symmetry is $y^2u^3$.
+\item[Permutation]
+The class represents a permutation of $n$ indices. Useful in the
+Faa Di Bruno.
+\item[IntSequence]
+The class represents a sequence of integers. Useful everywhere.
+\item[TwoDMatrix and ConstTwoDMatrix]
+These classse provide an interface to a code handling two-dimensional
+matrices. The code resides in Sylvester module, in directory {\tt
+sylv/cc}. There is
+no similar interface to \texttt{Vector} and \texttt{ConstVector} classes from the
+Sylvester module and they are used directly.
+\item[KronProdAll]
+The class represents a Kronecker product of a sequence of arbitrary
+matrices and is able to multiply a matrix from the right without
+storing the Kronecker product in memory.
+\item[KronProdAllOptim]
+The same as \texttt{KronProdAll} but it optimizes the order of matrices in
+the product to minimize the used memory during the Faa Di Bruno
+operation. Note that it is close to optimal flops.
+\item[FTensorPolynomial and UTensorPolynomial]
+Abstractions representing a polynomial whose coefficients are
+folded/unfolded tensors and variable is a column vector. The classes
+provide methods for traditional and horner-like polynomial
+evaluation. This is useful in simulation code.
+\item[FNormalMoments and UNormalMoments]
+These are containers for folded/unfolded single column tensors for
+higher moments of normal distribution. The code contains an algorithm
+for generating the moments for arbitrary covariance matrix.
+\item[TLStatic]
+The class encapsulates all static information needed for the
+library. It includes a Pascal triangle (for quick computation of
+binomial coefficients), and precalculated equivalence sets.
+\item[TLException]
+Simple class thrown as an exception.
+\end{description}
+
+\section{Multi-threading}
+
+The tensor library is multi-threaded. The basic property of the
+thread implementation in the library is that we do not allow running
+more concurrent threads than the preset limit. This prevents threads
+from competing for memory in such a way that the OS constantly switches
+among threads with frequent I/O for swaps. This may occur since one
+thread might need much own memory. The threading support allows for
+detached threads, the synchronization points during the Faa Di Bruno
+operation are relatively short, so the resulting load is close to the
+preset maximum number parallel threads.
+
+\section{Tests}
+
+A few words to the library's test suite. The suite resides in
+directory {\tt tl/testing}. There is a file {\tt tests.cpp} which
+contains all tests and {\tt main()} function. Also there are files
+{\tt factory.h} and {\tt factory.cpp} implementing random generation
+of various objects. The important property of these random objects is
+that they are the same for all object's invocations. This is very
+important in testing and debugging. Further, one can find files {\tt
+monoms.h} and {\tt monoms.cpp}. See below for their explanation.
+
+There are a few types of tests:
+\begin{itemize}
+\item We test for tensor indices. We go through various tensors with
+various symmetries, convert indices from folded to unfolded and
+vice-versa. We test whether their coordinates are as expected.
+\item We test the Faa Di Bruno by comparison of the results of
+\texttt{FGSContainer::multAndAdd} against the results of \texttt{UGSContainer::multAndAdd}. The two
+ implementations are pretty different, so this is a good test.
+\item We use a code in {\tt monoms.h} and {\tt monoms.cpp} to generate a
+ random vector function $f(x(y,u))$ along with derivatives of
+ $\left[f_x\right]$, $\left[x_{y^ku^l}\right]$, and
+ $\left[f_{y^ku^l}\right]$. Then we calculate the resulting derivatives
+ $\left[f_{y^ku^l}\right]$ using \texttt{multAndAdd} method of \texttt{UGSContainer}
+ or \texttt{FGSContainer} and compare the derivatives provided by {\tt
+ monoms}. The functions generated in {\tt monoms} are monomials with
+ integer exponents, so the implementation of {\tt monoms} is quite
+ easy.
+\item We do a similar thing for sparse tensors. In this case the {\tt monoms}
+ generate a function $f(y,v(y,u),w(y,u))$, provide all the derivatives
+ and the result $\left[f_{y^ku^l}\right]$. Then we calculate the
+ derivatives with \texttt{multAndAdd} of \texttt{ZContainer} and compare.
+\item We test the polynomial evaluation by evaluating a folded and
+ unfolded polynomial in traditional and horner-like fashion. This gives
+ four methods in total. The four results are compared.
+\end{itemize}
+
+
+\end{document}
\ No newline at end of file
diff --git a/windows/dynare.nsi b/windows/dynare.nsi
index c3d9dd874..35fc2da52 100644
--- a/windows/dynare.nsi
+++ b/windows/dynare.nsi
@@ -146,7 +146,7 @@ Section "Documentation and examples (Dynare and Dynare++)"
File ..\doc\dynare.html\*.html ..\doc\dynare.html\*.png
SetOutPath $INSTDIR\doc\dynare++
- File ..\dynare++\doc\dynare++-tutorial.pdf ..\dynare++\doc\dynare++-ramsey.pdf ..\dynare++\sylv\sylvester.pdf
+ File ..\dynare++\doc\dynare++-tutorial.pdf ..\dynare++\doc\dynare++-ramsey.pdf ..\dynare++\sylv\sylvester.pdf ..\dynare++\tl\tl.pdf
CreateShortcut "${SMLOC}\Documentation.lnk" "$INSTDIR\doc"
--
GitLab