/* ---------------------------------------------------------------------------

nlmdl: nlmdl.h

nlmdl is a C++ implementation of the statistical methods in A. Ronald 
Gallant, "Nonlinear Statistical Models," New York: John Wiley and Sons, 
1987, ISBN 0-471-80260-3, using a matrix class realmat that is distributed 
with it.  The header files nlmdl.h and realmat.h describe the use of the 
program and matrix class, respectively.  

Copyright (C) 1990, 1991, 1993, 1994, 2002.

A. Ronald Gallant
Post Office Box 659
Chapel Hill NC 27514-0659 
USA   

Permission to use, copy, modify, and distribute this software and its 
documentation for any purpose and without fee is hereby granted, provided 
that the above copyright notice appears in all copies and that both that 
copyright notice and this permission notice appear in supporting 
documentation.  

This software is provided "as is" without any expressed or implied warranty.

----------------------------------------------------------------------------- 

This header describes the program nlmdl.cc for estimating theta of the model 
e=q(t,theta).  The user supples a file named starting.dat whose contents are 
described by the template:

  switches This line is passed to class model as a string.
  method   What estimation method?  Code SUR, TSLS, or GMM.
  n        Number of observations, t = 1, ..., n.
  M        Number of equations in the system, i.e. dimension of e.
  K        Number of instruments, i.e. dimension of Z, code K=0 with SUR.
  p        Number of parameters, i.e. dimension of theta.
  itheta   Upper limit on Gauss-Newton iterations.
  ivar     Number of var iterates, ivar=0 means none.
  vartype  Code homoskedastic or heteroskedastic.
  MA       Number of moving average terms for var estimate, code MA=0 if e iid.
  weights  Code none or Parzen, coding none when MA>0 is asking for trouble.
  tol      Convergence tolerance, tol=1.0e-8 is reasonable.
  eps      Inversion tolerance, eps=1.0e-13 is reasonable (if REAL is double).
  detail   How much output?  Code none, minimal, or full.
           Blank line.
           Blank line.
           Blank line.
           Blank line.
           Blank line.
  theta(1) Starting values for theta.  These must be supplied.
           
    to

  theta(p) 
  var(1)   Starting values for variance estimate.  These can be omitted.  
           Matrix is stored columnwise.  If method = SUR or TSLS then then 
    to     l=M and var corresponds to C(e,e').  If method = GMM then l=M*K 
           and var corresponds to the variance of sum on t of e Kronecker 
  var(l*l) product Z.  


See class status for more detail, especially status::from.  The file 
starting.dat is read twice.  At the first reading it must contain at least 
the first line, switches.  Class model, described next, can supply entries 
for the second reading.  

The user also supplies the class model as files model.h and model.cc.  The 
class model is declared in model.h which should match the following template:

   #include "status.h"

   extern    status s;

   class model
   {   
   private:
     //...

   public:
            model();          
            ~model();           
   realmat  e_t;               // e_t    is s.M by 1
   realmat  dele_t;            // dele_t is s.M by s.p
   realmat  Z_t;               // Z_t    is s.K by 1, null if s.K = 0;
   int      initialize();
   int      terminate();
   void     e(INTEGER t);      // e    fills in e_t
   void     dele(INTEGER t);   // dele fills in dele_t = del e_t wrt theta
   void     Z(INTEGER t);      // Z    fills in Z_t
   }

For SUR, code the function Z as follows:

   void model::Z(INTEGER t) { }

In writing the class model, the relevant facts regarding program flow in 
nlmdl.cc are as follows: 

  1. First, s is tentatively filled in by reading starting.dat using 

       status s;
       s.from(s.starting);

     The primary purpose of this read is to get the first line from 
     starting.dat so as to make it available to model as the string 
     s.switches.  Nonetheless, everything in starting.dat is read and 
     put in s.  

  2. Next, initialize() of class model is called.  The function initialize() 
     can read starting.dat, can read other data, etc.  Since all of class 
     status's data is public, any of it can be filled in or changed by 
     initialize().  One could, for example, fill in all of class status's 
     data and write it using 

       s.to(s.starting);

     One could also switch to a different starting status file using 

       s.starting="filename";

     or a different ending status file using 

       s.ending="filename";

     If initialize() returns 0, execution stops.

  3. Then, class status's data is definitively filled in by the call

       s.from(s.starting);

     and m.e_t, m.dele_t, and m.Z_t are dimensioned as

       m.e_t.resize(s.M,1);
       m.dele_t.resize(s.M,s.p);
       if (s.K > 0) m.Z_t.resize(s.K,1);
                          
     Estimation proceeds using these settings and dimensions.  

  4. Finally, terminate() of class model is called; terminate() can read data, 
     write data, etc.  If terminate() returns 0 execution stops, otherwise 
     initialize() is called again and the cycle repeats (from Step 2).  One 
     can use this feature to loop over a grid of starting values.


Reference:

Gallant, A. Ronald (1987), "Nonlinear Statistical Models,"  New York: John 
Wiley and Sons. ISBN 0-471-80260-3.

--------------------------------------------------------------------------- */


#ifndef __FILE_NLMDL_H_SEEN__


#include "usual.h"      //This header is also in status.h
#include "realmat.h"    //This header is also in status.h
#include "tools.h"      //This header is also in status.h

#include "status.h"
#include "model.h"

using namespace std;
using namespace tools;

#define  VERSION "2.2"

#define __FILE_NLMDL_H_SEEN__ 1
#endif
