From 1f515ea54b5ea4ae462bddd4be88f970588832f8 Mon Sep 17 00:00:00 2001
From: sebastien <sebastien@ac1d8469-bf42-47a9-8791-bf33cf982152>
Date: Fri, 17 Oct 2008 10:11:54 +0000
Subject: [PATCH] trunk preprocessor: * added some comments * created
 enumerations for block type and block simulation type

git-svn-id: https://www.dynare.org/svn/dynare/dynare_v4@2165 ac1d8469-bf42-47a9-8791-bf33cf982152
---
 BlockTriangular.cc            | 13 +----------
 include/BlockTriangular.hh    | 12 ++++------
 include/CodeInterpreter.hh    | 41 ++++++++++++++++++++---------------
 include/ExprNode.hh           |  8 ++++++-
 include/ModelBlocks.hh        |  5 +++--
 include/ModelNormalization.hh |  5 +++--
 6 files changed, 41 insertions(+), 43 deletions(-)

diff --git a/BlockTriangular.cc b/BlockTriangular.cc
index 49f4b03c..cae8455f 100644
--- a/BlockTriangular.cc
+++ b/BlockTriangular.cc
@@ -270,8 +270,6 @@ BlockTriangular::Prologue_Epilogue(bool* IM, int* prologue, int* epilogue, int n
             {
               modifie = 1;
               swap_IM_c(IM, *prologue, i, l, Index_Var_IM, Index_Equ_IM, n);
-              Index_Equ_IM[*prologue].available = 0;
-              Index_Var_IM[*prologue].available = 0;
               (*prologue)++;
             }
         }
@@ -298,8 +296,6 @@ BlockTriangular::Prologue_Epilogue(bool* IM, int* prologue, int* epilogue, int n
             {
               modifie = 1;
               swap_IM_c(IM, n - (1 + *epilogue), l, i, Index_Var_IM, Index_Equ_IM, n);
-              Index_Equ_IM[n - (1 + *epilogue)].available = 0;
-              Index_Var_IM[n - (1 + *epilogue)].available = 0;
               (*epilogue)++;
             }
         }
@@ -308,7 +304,7 @@ BlockTriangular::Prologue_Epilogue(bool* IM, int* prologue, int* epilogue, int n
 
 
 void
-BlockTriangular::Allocate_Block(int size, int *count_Equ, int *count_Block, int type, Model_Block * ModelBlock)
+BlockTriangular::Allocate_Block(int size, int *count_Equ, int *count_Block, BlockType type, Model_Block * ModelBlock)
 {
   int i, j, k, l, ls, m, i_1, Lead, Lag, size_list_lead_var, first_count_equ, i1;
   int *list_lead_var, *tmp_size, *tmp_var, *tmp_endo, nb_lead_lag_endo;
@@ -380,7 +376,6 @@ BlockTriangular::Allocate_Block(int size, int *count_Equ, int *count_Block, int
           ModelBlock->in_Block_Equ[Index_Equ_IM[*count_Equ].index] = *count_Block;
           ModelBlock->in_Block_Var[Index_Var_IM[*count_Equ].index] = *count_Block;
           ModelBlock->in_Equ_of_Block[Index_Equ_IM[*count_Equ].index] = ModelBlock->in_Var_of_Block[Index_Var_IM[*count_Equ].index] = 0;
-          Index_Equ_IM[*count_Equ].block = *count_Block;
           if ((Lead > 0) && (Lag > 0))
             ModelBlock->Block_List[*count_Block].Simulation_Type = SOLVE_TWO_BOUNDARIES_SIMPLE;
           else if((Lead > 0) && (Lag == 0))
@@ -473,7 +468,6 @@ BlockTriangular::Allocate_Block(int size, int *count_Equ, int *count_Block, int
       nb_lead_lag_endo = 0;
       for(i = 0;i < size;i++)
         {
-          Index_Equ_IM[*count_Equ].block = *count_Block;
           ModelBlock->Block_List[*count_Block].Equation[i] = Index_Equ_IM[*count_Equ].index;
           ModelBlock->Block_List[*count_Block].Variable[i] = Index_Var_IM[*count_Equ].index;
           ModelBlock->Block_List[*count_Block].Variable_Sorted[i] = -1;
@@ -913,13 +907,11 @@ BlockTriangular::Normalize_and_BlockDecompose_Static_0_Model(const jacob_map &j_
   for(i = 0;i < endo_nbr;i++)
     {
       Index_Equ_IM[i].index = i;
-      Index_Equ_IM[i].available = 1;
     }
   Index_Var_IM = (simple*)malloc(endo_nbr * sizeof(*Index_Var_IM));
   for(i = 0;i < endo_nbr;i++)
     {
       Index_Var_IM[i].index = i;
-      Index_Var_IM[i].available = 1;
     }
   if(ModelBlock != NULL)
     Free_Block(ModelBlock);
@@ -931,7 +923,4 @@ BlockTriangular::Normalize_and_BlockDecompose_Static_0_Model(const jacob_map &j_
   Normalize_and_BlockDecompose(SIM, ModelBlock, endo_nbr, &prologue, &epilogue, Index_Var_IM, Index_Equ_IM, 1, 1, SIM_0, j_m);
   free(SIM_0);
   free(SIM);
-  if(bt_verbose)
-    for(i = 0;i < endo_nbr;i++)
-      cout << "Block=" << Index_Equ_IM[i].block << " Equ=" << Index_Equ_IM[i].index << " Var= " << Index_Var_IM[i].index << "  " << symbol_table.getNameByID(eEndogenous, Index_Var_IM[i].index) << "\n";
 }
diff --git a/include/BlockTriangular.hh b/include/BlockTriangular.hh
index 3d31c748..6e28602a 100644
--- a/include/BlockTriangular.hh
+++ b/include/BlockTriangular.hh
@@ -26,13 +26,9 @@
 #include "ModelNormalization.hh"
 #include "ModelBlocks.hh"
 
-/*!
-  \class  BlockTriangular
-  \brief  Creat the incidence matrice and reorder the model's equations.
-*/
-
 #include "ExprNode.hh"
 
+//! List of incidence matrix (one matrix per lead/lag)
 struct List_IM
 {
   List_IM* pNext;
@@ -40,13 +36,14 @@ struct List_IM
   bool* IM;
 };
 
+//! Matrix of doubles for representing jacobian
 typedef map<pair<int ,int >,double> jacob_map;
 
+//! Create the incidence matrix, computes prologue & epilogue, normalizes the model and computes the block decomposition
 class BlockTriangular
 {
 public:
   BlockTriangular(const SymbolTable &symbol_table_arg);
-  /*! The incidence matrix for each lead and lags */
   const SymbolTable &symbol_table;
   Blocks blocks;
   Normalization normalization;
@@ -63,7 +60,7 @@ public:
   bool Normalize_and_BlockDecompose(bool* IM, Model_Block* ModelBlock, int n, int* prologue, int* epilogue, simple* Index_Var_IM, simple* Index_Equ_IM, bool Do_Normalization, bool mixing, bool* IM_0 , jacob_map j_m);
   void Prologue_Epilogue(bool* IM, int* prologue, int* epilogue, int n, simple* Index_Var_IM, simple* Index_Equ_IM, bool* IM0);
   void swap_IM_c(bool *SIM, int pos1, int pos2, int pos3, simple* Index_Var_IM, simple* Index_Equ_IM, int n);
-  void Allocate_Block(int size, int *count_Equ, int *count_Block, int type, Model_Block * ModelBlock);
+  void Allocate_Block(int size, int *count_Equ, int *count_Block, BlockType type, Model_Block * ModelBlock);
   void Free_Block(Model_Block* ModelBlock) const;
   List_IM *First_IM ;
   List_IM *Last_IM ;
@@ -131,5 +128,4 @@ public:
       }
   };
 };
-//------------------------------------------------------------------------------
 #endif
diff --git a/include/CodeInterpreter.hh b/include/CodeInterpreter.hh
index cfc78b2d..b6d0e528 100644
--- a/include/CodeInterpreter.hh
+++ b/include/CodeInterpreter.hh
@@ -41,21 +41,28 @@ const char FEND=17;
 const char FOK=18;
 const char FENDEQU=19;
 
-const int SIMULTANS=0;
-const int PROLOGUE=1;
-const int EPILOGUE=2;
-const int SIMULTAN=3;
-const int UNKNOWN=-1;
-const int EVALUATE_FOREWARD=0;
-const int EVALUATE_BACKWARD=1;
-const int SOLVE_FOREWARD_SIMPLE=2;
-const int SOLVE_BACKWARD_SIMPLE=3;
-const int SOLVE_TWO_BOUNDARIES_SIMPLE=4;
-const int SOLVE_FOREWARD_COMPLETE=5;
-const int SOLVE_BACKWARD_COMPLETE=6;
-const int SOLVE_TWO_BOUNDARIES_COMPLETE=7;
-const int EVALUATE_FOREWARD_R=8;
-const int EVALUATE_BACKWARD_R=9;
+enum BlockType
+  {
+    SIMULTANS = 0, //<! Simultaneous time separable block
+    PROLOGUE = 1,  //<! Prologue block (one equation at the beginning, later merged)
+    EPILOGUE = 2,  //<! Epilogue block (one equation at the beginning, later merged)
+    SIMULTAN = 3   //<! Simultaneous time unseparable block
+  };
+
+enum BlockSimulationType
+  {
+    UNKNOWN = -1,                      //!< Unknown simulation type
+    EVALUATE_FOREWARD = 0,             //!< Simple evaluation, normalized variable on left-hand side, forward
+    EVALUATE_BACKWARD = 1,             //!< Simple evaluation, normalized variable on left-hand side, backward
+    SOLVE_FOREWARD_SIMPLE = 2,         //!< Block of one equation, newton solver needed, forward
+    SOLVE_BACKWARD_SIMPLE = 3,         //!< Block of one equation, newton solver needed, backward
+    SOLVE_TWO_BOUNDARIES_SIMPLE = 4,   //!< Block of one equation, newton solver needed, forward & ackward
+    SOLVE_FOREWARD_COMPLETE = 5,       //!< Block of several equations, newton solver needed, forward
+    SOLVE_BACKWARD_COMPLETE = 6,       //!< Block of several equations, newton solver needed, backward
+    SOLVE_TWO_BOUNDARIES_COMPLETE = 7, //!< Block of several equations, newton solver needed, forward and backwar
+    EVALUATE_FOREWARD_R = 8,           //!< Simple evaluation, normalized variable on right-hand side, forward
+    EVALUATE_BACKWARD_R = 9           //!< Simple evaluation, normalized variable on right-hand side, backward
+  };
 
 //! Enumeration of possible symbol types
 /*! Warning: do not to change existing values: the order matters for VariableTable (at least for endogenous and exogenous types), and the values matter for homotopy_setup command */
@@ -71,7 +78,6 @@ enum Type
     eUnknownFunction = 12          //!< Function unknown to the preprocessor
   };
 
-
 enum UnaryOpcode
   {
     oUminus,
@@ -92,6 +98,7 @@ enum UnaryOpcode
     oAtanh,
     oSqrt
   };
+
 enum BinaryOpcode
   {
     oPlus,
@@ -110,6 +117,4 @@ enum BinaryOpcode
     oDifferent
   };
 
-
-
 #endif
diff --git a/include/ExprNode.hh b/include/ExprNode.hh
index cb74b35e..2f877821 100644
--- a/include/ExprNode.hh
+++ b/include/ExprNode.hh
@@ -311,15 +311,20 @@ public:
   virtual void compile(ofstream &CompileCode, bool lhs_rhs, ExprNodeOutputType output_type, const temporary_terms_type &temporary_terms, map_idx_type map_idx) const;
 };
 
+//! For one lead/lag of one block, stores mapping of information between original model and block-decomposed model
 struct IM_compact
 {
   int size, u_init, u_finish, nb_endo;
   int *u, *us, *Var, *Equ, *Var_Index, *Equ_Index, *Var_dyn_Index;
 };
 
+//! One block of the model
 struct Block
 {
-  int Size, Sized, Type, Simulation_Type, Max_Lead, Max_Lag, Nb_Lead_Lag_Endo;
+  int Size, Sized;
+  BlockType Type;
+  BlockSimulationType Simulation_Type;
+  int Max_Lead, Max_Lag, Nb_Lead_Lag_Endo;
   bool is_linear;
   int *Equation, *Own_Derivative;
   int *Variable, *Variable_Sorted, *dVariable;
@@ -329,6 +334,7 @@ struct Block
   int Code_Start, Code_Length;
 };
 
+//! The set of all blocks of the model
 struct Model_Block
 {
   int Size, Periods;
diff --git a/include/ModelBlocks.hh b/include/ModelBlocks.hh
index c6362814..cb3557b4 100644
--- a/include/ModelBlocks.hh
+++ b/include/ModelBlocks.hh
@@ -21,7 +21,7 @@
 #define MODELBLOCKS
 #include "ModelNormalization.hh"
 
-
+//! Sparse form of the graph, with strongly connected components
 typedef struct block_result
 {
   int size, n_sets;
@@ -32,7 +32,7 @@ typedef struct block_result
   block_result_t;
 
 
-
+//! Implements Tarjan algorithm
 class Blocks
 {
 public:
@@ -42,6 +42,7 @@ public:
   void block_result_free(block_result_t *r);
   void block_result_print(block_result_t *r);
   void Print_Equation_gr(Equation_set* Equation);
+  //! Converts the output of Tarjan algorithm into reordered incidence matrices
   void block_result_to_IM(block_result_t *r,bool* IM,int prologue, int n,simple* Index_Equ_IM,simple* Index_Var_IM);
   Equation_vertex *vertices;
   int *block_vertices, *sets_s, *sets_f;
diff --git a/include/ModelNormalization.hh b/include/ModelNormalization.hh
index 47460b94..5ee55e76 100644
--- a/include/ModelNormalization.hh
+++ b/include/ModelNormalization.hh
@@ -43,10 +43,11 @@ struct Equation_set
   int edges;
 };
 
+//! Stores result of block decomposition for ONE equation or ONE variable
 struct simple
 {
-  int index, block;
-  bool available;
+  //! New {variable, equation} index after reordering
+  int index;
 };
 
 class Normalization