dynare/dynare++/kord/global_check.hh

// Copyright 2005, Ondra Kamenik

// Global check

/* The purpose of this file is to provide classes for checking error of
   approximation. If $y_t=g(y^*_{t-1},u)$ is an approximate solution,
   then we check for the error of residuals of the system equations. Let
   $F(y^*,u,u')=f(g^{**}(g^*(y^*,u'),u),g(y^*,u),y^*,u)$, then we
   calculate integral
   $$E[F(y^*,u,u')]$$@q'@>
   which we want to be zero for all $y^*$, and $u$.

   There are a few possibilities how and where the integral is
   evaluated. Currently we offer the following:

   \numberedlist
   \li Along shocks. The $y^*$ is set to steady state, and $u$ is set to
   zero but one element is going from minus through plus shocks in few
   steps. The user gives the scaling factor, for instance interval
   $\langle<-3\sigma,3\sigma\rangle$ (where $sigma$ is a standard error
   of the shock), and a number of steps. This is repeated for each shock
   (element of the $u$ vector).
   \li Along simulation. Some random simulation is run, and for each
   realization of $y^*$ and $u$ along the path we evaluate the residual.
   \li On ellipse. Let $V=AA^T$ be a covariance matrix of the
   predetermined variables $y^*$ based on linear approximation, then we
   calculate integral for points on the ellipse $\{Ax\vert\, \Vert
   x\Vert_2=1\}$. The points are selected by means of low discrepancy
   method and polar transformation. The shock $u$ are zeros.

   \li Unconditional distribution.

   \endnumberedlist */

#ifndef GLOBAL_CHECK_H
#define GLOBAL_CHECK_H

#include <matio.h>

#include "vector_function.hh"
#include "quadrature.hh"

#include "dynamic_model.hh"
#include "journal.hh"
#include "approximation.hh"

/* This is a class for implementing |VectorFunction| interface
   evaluating the residual of equations, this is
   $$F(y^*,u,u')=f(g^{**}(g^*(y^*,u),u'),y^*,u)$$
   is written as a function of $u'$.

   When the object is constructed, one has to specify $(y^*,u)$, this is
   done by |setYU| method. The object has basically two states. One is
   after construction and before call to |setYU|. The second is after
   call |setYU|. We distinguish between the two states, an object in the
   second state contains |yplus|, |ystar|, |u|, and |hss|.

   The vector |yplus| is $g^*(y^*,u)$. |ystar| is $y^*$, and polynomial
   |hss| is partially evaluated $g^**(yplus, u)$.

   The pointer to |DynamicModel| is important, since the |DynamicModel|
   evaluates the function $f$. When copying the object, we have to make
   also a copy of |DynamicModel|. */

class ResidFunction : public VectorFunction
{
protected:
  const Approximation &approx;
  DynamicModel *model;
  Vector *yplus;
  Vector *ystar;
  Vector *u;
  FTensorPolynomial *hss;
public:
  ResidFunction(const Approximation &app);
  ResidFunction(const ResidFunction &rf);
  virtual
  ~ResidFunction();
  virtual VectorFunction *
  clone() const
  {
    return new ResidFunction(*this);
  }
  virtual void eval(const Vector &point, const ParameterSignal &sig, Vector &out);
  void setYU(const Vector &ys, const Vector &xx);
};

/* This is a |ResidFunction| wrapped with |GaussConverterFunction|. */

class GResidFunction : public GaussConverterFunction
{
public:
  GResidFunction(const Approximation &app)
    : GaussConverterFunction(new ResidFunction(app), app.getModel().getVcov())
  {
  }
  GResidFunction(const GResidFunction &rf)
     
  = default;
  virtual ~GResidFunction()
  = default;
  virtual VectorFunction *
  clone() const
  {
    return new GResidFunction(*this);
  }
  void
  setYU(const Vector &ys, const Vector &xx)
  {
    ((ResidFunction *) func)->setYU(ys, xx);
  }
};

/* This is a class encapsulating checking algorithms. Its core routine
   is |check|, which calculates integral $E[F(y^*,u,u')\vert y^*,u]$ for
   given realizations of $y^*$ and $u$. The both are given in
   matrices. The methods checking along shocks, on ellipse and anlong a
   simulation path, just fill the matrices and call the core |check|.

   The method |checkUnconditionalAndSave| evaluates unconditional
   $E[F(y,u,u')]$.

   The object also maintains a set of |GResidFunction| functions |vfs| in
   order to save (possibly expensive) copying of |DynamicModel|s. */

class GlobalChecker
{
  const Approximation &approx;
  const DynamicModel &model;
  Journal &journal;
  GResidFunction rf;
  VectorFunctionSet vfs;
public:
  GlobalChecker(const Approximation &app, int n, Journal &jr)
    : approx(app), model(approx.getModel()), journal(jr),
      rf(approx), vfs(rf, n)
  {
  }
  void check(int max_evals, const ConstTwoDMatrix &y,
             const ConstTwoDMatrix &x, TwoDMatrix &out);
  void checkAlongShocksAndSave(mat_t *fd, const char *prefix,
                               int m, double mult, int max_evals);
  void checkOnEllipseAndSave(mat_t *fd, const char *prefix,
                             int m, double mult, int max_evals);
  void checkAlongSimulationAndSave(mat_t *fd, const char *prefix,
                                   int m, int max_evals);
  void checkUnconditionalAndSave(mat_t *fd, const char *prefix,
                                 int m, int max_evals);
protected:
  void check(const Quadrature &quad, int level,
             const ConstVector &y, const ConstVector &x, Vector &out);
};

/* Signalled resid function. Not implemented yet. todo: */

class ResidFunctionSig : public ResidFunction
{
public:
  ResidFunctionSig(const Approximation &app, const Vector &ys, const Vector &xx);
};

#endif