\documentstyle[aps]{revtex}
%\def\btt#1{{\tt$\backslash$#1}}
\begin{document}
\title{Architecture of a Vector Auto-Regressive (VAR) Time Series Generator\\
with\\
Vector Auto-Regressive Conditional Heteroskedastic (ARCH) Noise:\\
VARCH Server\\
}
\vskip 1truecm
\renewcommand{\thefootnote}{*}
\author{Miloje S. Makivi\'c\footnote{
Northeast Parallel Architectures Center (NPAC), Syracuse University,\\
111 College Place, Syracuse, NY 13244-4100\\ 
{\bf e-mail}: miloje@npac.syr.edu\\ 
{\bf Mosaic} http://www.npac.syr.edu/users/miloje/}
}
\date{\today}
\maketitle
\vskip 2truecm
\centerline{NPAC/Sailfish  Technical Note 3}
\vskip 2truecm

\section{Overview}
\label{sec:intro}

As a prototypical application of the Monte Carlo  simulator, consider the
implementation of a VARCH module which generates VAR time series of order $k$:
\begin{equation}
{\bf X} (t) = {\bf\alpha} + {\bf A_1}{\bf X}(t-1) + {\bf A_2} {\bf X} (t-2) +\dots + {\bf A_k} {\bf X} (t-k) + {\bf U} (t)
\label{var}
\end{equation}
with a vector ARCH noise of order $m$:
\begin{equation}
{\bf U} (t) = ({\bf\xi} + {\bf B_1} {\bf U}^2 (t-1) + {\bf B_2} {\bf U}^2 (t-2) +\dots + {\bf B_m} {\bf U}^2 (t-m))^{1/2} \epsilon(t)
\label{arch}
\end{equation}
${\bf X} (t)$ is vector of observed rates at time $t$ which has $N$ components. It is assumed that
all $N$ rates are correlated. Rate levels are given by ${\bf{\alpha}}$.
${\bf X} (t)$ is regressed on $k$ previous time steps via $k$ matrices
${\bf A_p},p=1\dots k$ which are assumed to be time independent. ${\bf U} (t)$ is an $N$-component
noise vector which is also regressed onto $m$ previous time steps via ${\bf B_p},p=1\dots m$ matrices.
Noise levels are given by the vector ${\bf {\xi}}$.

Noise vector contains $N$-component disturbance vector $\epsilon(t)$ which is sampled from an
arbitrary distribution using the Metropolis Monte Carlo simulator. 

\section{Proxy Rate Server Architecture}
\label{sec:pimc}

It will be assumed for now that the only purpose of the VARCH module is to generate a proxy rate time
series, given the parameters of the time series.
Top level module of this proxy rate server consists of a single routine:
\begin{verbatim}

rateVector **VARCH_ProxyRateServer
                                 (
                                 char *PROXY_RATE_description_file,
                                 char *MC_description_file,
                                 char *DISTURBANCE_description_file,
                                 char *VAR_TimeSeries_description_file,
                                 char *ARCH_NOISE_description_file
                                 )
\end{verbatim}

which takes as inputs names of files with descriptions of all the components of the simulation.
It returns a $rateVector$ pointer array which contains proxy rate histories and also stores them
in the output file which is one of the parameters specified in $PROXY\_RATE\_description\_file$.

{\bf PROXY\_RATE\_description\_file} is the only input file directly used by the Proxy Rate Server.
This input file specifies:
\begin{verbatim}
Number of rates (= number of components in vector AR and vector ARCH processes)
3
Start date   (beginning date of the simulation)
0
End date     (ending date of the simulation)
10
Period length in days (number of days between successive time steps)
1
Order of vector AR time series
2
Order of vector ARCH noise
2
Output file to store proxy rates
proxy.out
\end{verbatim}
The other files are passed as parameters to slave servers.
$VARCH\_ProxyRateServer$ calls the ARCH noise server:
\begin{verbatim}
Noise = ARCH_GenerateNoise
                                    (
                                    NumTimeSteps,
                                    NumRates,
                                    ARCH_NOISE_ProcessOrder,
                                    MC_description_file,
                                    DISTURBANCE_description_file,
                                    ARCH_NOISE_description_file
                                    )           
\end{verbatim}
to obtain a sample of ARCH noise in ${\bf Noise}$. It then calls a VAR time series server:
\begin{verbatim}
Rates = VAR_GenerateTimeSeries
                                    (
                                    NumTimeSteps,
                                    NumRates,
                                    TIME_SERIES_ProcessOrder,
                                    VAR_TimeSeries_description_file
                                    )    
\end{verbatim} 
which returns a VAR time series in ${\bf Rates}$. 
VARCH Proxy Rate Server adds the noise to the time series:
\begin{verbatim}
Rates += Noise
\end{verbatim}
{\bf Rates} and {\bf Noise} are data structures of type {\bf PATH}. A detailed  description of 
the {\bf PATH} structure is given in a supporting  document.
Time series data are converted into the {\bf rateVector} format and written into a file by
calling:
\begin{verbatim}
RateVectors = ProxyRates
                              (
                              Rates,
                              StartDate,
                              PeriodLength,
                              ProxyRatesContainer
                              )                  
\end{verbatim}
{\bf  ProxyRates} returns an array of pointers to {\bf rateVector}s.

These routines are interfaces to separate modules which then provide the requested services.

\section{VAR Server}
\label{sec:var}

The purpose of VAR Server is to generate a VAR time series:
\begin{equation}
{\bf X} (t) = {\bf\alpha} + {\bf A_1}{\bf X}(t-1) + {\bf A_2} {\bf X} (t-2) +\dots + {\bf A_k} {\bf X} (t-k)
\end{equation}
The server is accessed through:
\begin{verbatim}
PATH *VAR_GenerateTimeSeries
                           (
                           int NumTimeSteps,  /* number of time steps in the time series       */
                           int NumRates,      /* dimensionality of the vector process          */
                           int VAR_ProcessOrder, /* process order                              */
                           char *TS_description_file /* input file with time series parameters */
                           )
{
  int err = 0;
  PATH *VAR_Rates  = NULL;
  VAR  *VAR_Params = NULL;

  if((VAR_Rates = CreatePath  /* Create PATH data structure to store rate time series */
                           (
                           NumTimeSteps,
                           NumRates,
                           VAR_ProcessOrder
                           )                              ) == NULL) {
     fprintf(stderr,"VAR_GenerateTimeSeries(): Could not create VAR TS path\n");
     exit(1);
  }

  if((VAR_Params = VAR_SetParams  /* Create data structure VAR which will store time series 
                                     parameters and fill with parameters values from 
                                     TS_description_file    */
                                (
                                NumTimeSteps,NumRates,TS_Lag,
                                VAR_Rates,
                                TS_description_file
                                )                         ) == NULL) {
     fprintf(stderr,"VAR_GenerateTimeSeries(): Could not set  VAR TS parameters\n");
     exit(1);
  }

  if(err = VAR_TimeSeries(VAR_Rates, VAR_Params) ) { /* compute VAR time series               */
    fprintf(stderr,"VAR_GenerateTimeSeries(): Failed to obtain VAR time series\n");
    exit(1);
  }

  VAR_Free(VAR_Params, NumRates);  /* free storage for VAR parameters                         */

  return VAR_Rates;
}
\end{verbatim}
VAR structure is defined in {\bf NPACdefs.h}:
\begin{verbatim}
typedef struct var{
int TS_Lag;   /* order of the VAR time series             */
float *Level; /* time series level                        */
float ***ARMatrices; /* the stack of auto-regression matrices, earlier lags are stored first   */ 
} VAR;
\end{verbatim}
{\bf VAR\_GenerateTimeSeries} server uses rotines in the {\bf modvar.c} module to accomplish the
tasks which require manipulation of VAR structure. It also issues a {\bf CreatePath()}
request to the {\bf modpath.c} module to provide and maintain storage for time series.

The input file format for an $N$-dimensional VAR of order $Q$ is as follows:
\begin{verbatim}
Levels for each component of the VAR process
1 8.0
2 8.0
.
.
.
N 8.0
Initial values of each component of the VAR process (# of initial values = process order)
Initial value #1 (first lag)
1 9.0
2 9.0
.
.
.
N 9.0
Initial value #2 (second lag)
1 7.0
2 7.0
.
.
.
N 7.0
Initial value #3 (third lag)
...
...
...
Initial value #Q (Qth lag)
1 7.0
2 7.0
.
.
.
N 7.0
Matrices which determine vector AR process (# of matrices equals process order)
Matrix for the first lag
1 1 0.5
1 2 0.05
.
.
.
1 N 0.05
2 1 0.05
2 2 0.5
.
.
.
2 N 0.05
...
...
...
N 1 0.05
N 2 0.05
.
.
.

N N 0.5
Matrix for the second lag
1 1 0.5
1 2 0.05
.
.
.
1 N 0.05
2 1 0.05
2 2 0.5
.
.
.
2 N 0.05
...
...
...
N 1 0.05
N 2 0.05
.
.
.

N N 0.5
Matrix for the third lag
...
...
...
Matrix for the Qth lag
1 1 0.5
1 2 0.05
.
.
.
1 N 0.05
2 1 0.05
2 2 0.5
.
.
.
2 N 0.05
...
...
...
N 1 0.05
N 2 0.05
.
.
.

N N 0.5
\end{verbatim}
Parameters are separated by comment lines. All vector and matrix parameters are listed so that
both the indices and the parameter values are given, therefore the ordering of the parameters
is irrelevant.

\section{ARCH Server}
\label{sec:arch}

The purpose of VAR Server is to generate ARCH noise samples for all rates and time steps of the time series:
\begin{equation}
{\bf U} (t) = ({\bf\xi} + {\bf B_1} {\bf U}^2 (t-1) + {\bf B_2} {\bf U}^2 (t-2) +\dots + {\bf B_m} {\bf U}^2 (t-m))^{1/2} \epsilon(t)
\label{arch1}
\end{equation}
ARCH noise server is the one which requests services from the Monte Carlo Simulator. The interface to the
Monte Carlo Simulator is described in a separate document.
Monte Carlo simulator provides samples of disturbance
vectors ${\bf \epsilon} (t)$ for each time slice $t$ to the ARCH server. 

The server is accessed via:
\begin{verbatim}
PATH *ARCH_GenerateNoise
                       (
                       int NumTimeSteps,     /* number of time steps in the time series   */
                       int NumRates,         /* dimensionality of the noise vector        */
                       int NOISE_ProcessOrder, /* ARCH noise process order                */
                       char *MC_description_file, /* Description file for the Metropolis 
                                                     Monte Carlo Simulator which is passed
                                                     as input parameter to the Simulator  */
                       char *DISTURBANCE_description_file, /* Description file for the 
                                                              disturbance process which is
                                                              passed as input parameter to
                                                              the Monte Carlo Simulator   */
                       char *ARCH_NOISE_description_file /* Description file for the ARCH noise
                                                            process which contains parameters
                                                            of the noise process           */
                       )
{
  FILE *nfile = NULL;
  int err = 0;
  int DisturbanceLag = 0;
  PATH *Disturbance = NULL;
  PATH *Noise = NULL;
  ARCH *NoiseParams = NULL;
  PROCESS *DisturbanceParams = NULL;

  /*****
  Create data structures which will store disturbance arrays and ARCH noise vectors
  ******/
  if((Disturbance = CreatePath(NumTimeSteps,NumRates,DisturbanceLag))== NULL)  {
     fprintf(stderr,"Generate_ARCH_Noise(): Could not create disturbance path\n");
     exit(1);
  }

  if((Noise = CreatePath(NumTimeSteps,NumRates,NOISE_Lag))== NULL) {
     fprintf(stderr,"Generate_ARCH_Noise(): Could not create ARCH noise path\n");
     exit(1);
  }

  /*******
  Setup disturbance probability parameters for the Monte Carlo Simulator
  *******/
  if((DisturbanceParams = SetProcessParams(
                              NumTimeSteps,NumRates,
                              DISTURBANCE_description_file))== NULL) {
     fprintf(stderr,"Generate_ARCH_Noise(): Could not set disturbance parameters\n");
     exit(1);
  }

  /*******
  Setup ARCH noise parameters 
  *******/

  if((NoiseParams = ARCH_SetParams(
                              NumTimeSteps,NumRates,NOISE_Lag,
                              Noise,
                              ARCH_NOISE_description_file))== NULL) {
     fprintf(stderr,"Generate_ARCH_Noise(): Could not set ARCH noise parameters\n");
     exit(1);
  }

  /*******
  Setup Metropolis Simulator
  .........
  For a detailed description of the mechanics of invoking the Metropolis Monte Carlo
  Simulator, please see the accompanying document
  *******/
  if(err = SetupMetropolisMCSimulation(MC_description_file)) {
     fprintf(stderr,"Generate_ARCH_Noise(): Metropolis set up failed\n");
     exit(1);
  }
  /*****
  Reqest disturbance arrays from the Monte Carlo Simulator
  *****/

  if(err = GetDisturbanceSample(Disturbance,DisturbanceParams)) {
    fprintf(stderr,"Generate_ARCH_Noise(): Failed to obtain disturbance sample\n");
    exit(1);
  }

  /****
  Use the disturbance samples to produce ARCH noise time series
  *****/
  if(err = ARCH_GetNoiseSample(Noise,Disturbance,NoiseParams)) {
    fprintf(stderr,"Generate_ARCH_Noise(): Failed to obtain ARCH noise sample\n");
    exit(1);
  }

  PATH_Free(Disturbance);
  ARCH_Free(NoiseParams, NumRates);
  PROCESS_Free(DisturbanceParams, NumRates);

  return Noise;  /* return pointer to ARCH noise container */
}

\end{verbatim}
There is a similarity between definitions of a VAR series  and ARCH series, which
is reflected in essentially the same structure used to store the parameters of the
ARCH noise:
\begin{verbatim}
typedef struct arch{
int Lag;
float *Level;
float ***ARMatrices;
} ARCH;
\end{verbatim}
ARCH structure is accessed and maintained by routines in the {\bf modarch.c} module.
Parameters of the ARCH process are read from the input file with has the same
format as the VAR module input file (it is assumed that we have an $N$-dimensional 
ARCH process of order $Q$):
\begin{verbatim}
Levels for each component of the ARCH noise process
1 8.0
2 8.0
.
.
.
N 8.0
Initial values of each component of the ARCH process (# of initial values = process order)
Initial value #1 (first lag)
1 9.0
2 9.0
.
.
.
N 9.0
Initial value #2 (second lag)
1 7.0
2 7.0
.
.
.
N 7.0
Initial value #3 (third lag)
...
...
...
Initial value #Q (Qth lag)
1 7.0
2 7.0
.
.
.
N 7.0
Matrices which determine vector ARCH process (# of matrices = process order)
Matrix for the first lag
1 1 0.5
1 2 0.05
.
.
.
1 N 0.05
2 1 0.05
2 2 0.5
.
.
.
2 N 0.05
...
...
...
N 1 0.05
N 2 0.05
.
.
.

N N 0.5
Matrix for the second lag
1 1 0.5
1 2 0.05
.
.
.
1 N 0.05
2 1 0.05
2 2 0.5
.
.
.
2 N 0.05
...
...
...
N 1 0.05
N 2 0.05
.
.
.

N N 0.5
Matrix for the third lag
...
...
...
Matrix for the Qth lag
1 1 0.5
1 2 0.05
.
.
.
1 N 0.05
2 1 0.05
2 2 0.5
.
.
.
2 N 0.05
...
...
...
N 1 0.05
N 2 0.05
.
.
.

N N 0.5




\end{verbatim}

\end{document}

