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

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.

A. Ronald Gallant
P.O. Box 5513 
Raleigh NC 27650-5513 
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 appear 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.
  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 must contain at least the first line, switches.  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"
   external status s;

   class model
   {   
   protected:
     //...

   public:
            model();
            ~model();
   int      initialize();
   int      terminate();
   realmat  e(INTEGER t);      // e is M by 1
   realmat  dele(INTEGER t);   // dele is M by p
   realmat  Z(INTEGER t);      // Z is K by 1
   }

For SUR, code the function Z as follows:

   realmat model::Z(INTEGER t)
   {
     realmat z(1,1);
     z.elem(1,1)=1.0;
     return z;
   }

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 estimation proceeds using these settings.  

  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__
#pragma once
#define __FILE_NLMDL_H_SEEN__ 1

#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"

#endif