src/FDM/JSBSim/math/FGTable.h

   1 /*%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
   2
   3  Header:       FGTable.h
   4  Author:       Jon S. Berndt
   5  Date started: 1/9/2001
   6
   7  ------------- Copyright (C) 2001  Jon S. Berndt (jsb@hal-pc.org) --------------
   8
   9  This program is free software; you can redistribute it and/or modify it under
  10  the terms of the GNU General Public License as published by the Free Software
  11  Foundation; either version 2 of the License, or (at your option) any later
  12  version.
  13
  14  This program is distributed in the hope that it will be useful, but WITHOUT
  15  ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
  16  FOR A PARTICULAR PURPOSE.  See the GNU General Public License for more
  17  details.
  18
  19  You should have received a copy of the GNU General Public License along with
  20  this program; if not, write to the Free Software Foundation, Inc., 59 Temple
  21  Place - Suite 330, Boston, MA  02111-1307, USA.
  22
  23  Further information about the GNU General Public License can also be found on
  24  the world wide web at http://www.gnu.org.
  25
  26 HISTORY
  27 --------------------------------------------------------------------------------
  28 JSB  1/9/00          Created
  29
  30 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  31 SENTRY
  32 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%*/
  33
  34 #ifndef FGTABLE_H
  35 #define FGTABLE_H
  36
  37 /*%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  38 INCLUDES
  39 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%*/
  40
  41 #include <input_output/FGXMLElement.h>
  42 #include "FGParameter.h"
  43 #include <input_output/FGPropertyManager.h>
  44 #include <sstream>
  45 #include <vector>
  46
  47 /*%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  48 DEFINITIONS
  49 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%*/
  50
  51 #define ID_TABLE "$Id$"
  52
  53 /*%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  54 FORWARD DECLARATIONS
  55 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%*/
  56
  57 using std::vector;
  58 using std::stringstream;
  59
  60 namespace JSBSim {
  61
  62 /*%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  63 CLASS DOCUMENTATION
  64 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%*/
  65
  66 /** Lookup table class.
  67     Models a one, two, or three dimensional lookup table for use in FGCoefficient,
  68     FGPropeller, etc.  A one-dimensional table is called a "VECTOR" in a coefficient
  69     definition. For example:
  70 <pre>
  71     \<COEFFICIENT NAME="{short name}" TYPE="VECTOR">
  72       {name}
  73       {number of rows}
  74       {row lookup property}
  75       {non-dimensionalizing properties}
  76       {row_1_key} {col_1_data}
  77       {row_2_key} {...       }
  78       { ...     } {...       }
  79       {row_n_key} {...       }
  80     \</COEFFICIENT>
  81 </pre>
  82     A "real life" example is as shown here:
  83 <pre>
  84     \<COEFFICIENT NAME="CLDf" TYPE="VECTOR">
  85       Delta_lift_due_to_flap_deflection
  86       4
  87       fcs/flap-pos-deg
  88       aero/qbar-psf | metrics/Sw-sqft
  89       0   0
  90       10  0.20
  91       20  0.30
  92       30  0.35
  93     \</COEFFICIENT>
  94 </pre>
  95     The first column in the data table represents the lookup index (or "key").  In
  96     this case, the lookup index is fcs/flap-pos-deg (flap extension in degrees).
  97     If the flap position is 10 degrees, the value returned from the lookup table
  98     would be 0.20.  This value would be multiplied by qbar (aero/qbar-psf) and wing
  99     area (metrics/Sw-sqft) to get the total lift force that is a result of flap
 100     deflection (measured in pounds force).  If the value of the flap-pos-deg property
 101     was 15 (degrees), the value output by the table routine would be 0.25 - an
 102     interpolation.  If the flap position in degrees ever went below 0.0, or above
 103     30 (degrees), the output from the table routine would be 0 and 0.35, respectively.
 104     That is, there is no _extrapolation_ to values outside the range of the lookup
 105     index.  This is why it is important to chose the data for the table wisely.
 106
 107     The definition for a 2D table - referred to simply as a TABLE, is as follows:
 108 <pre>
 109     \<COEFFICIENT NAME="{short name}" TYPE="TABLE">
 110       {name}
 111       {number of rows}
 112       {number of columns}
 113       {row lookup property}
 114       {column lookup property}
 115       {non-dimensionalizing}
 116                   {col_1_key   col_2_key   ...  col_n_key }
 117       {row_1_key} {col_1_data  col_2_data  ...  col_n_data}
 118       {row_2_key} {...         ...         ...  ...       }
 119       { ...     } {...         ...         ...  ...       }
 120       {row_n_key} {...         ...         ...  ...       }
 121     \</COEFFICIENT>
 122 </pre>
 123     A "real life" example is as shown here:
 124 <pre>
 125     \<COEFFICIENT NAME="CYb" TYPE="TABLE">
 126       Side_force_due_to_beta
 127       3
 128       2
 129       aero/beta-rad
 130       fcs/flap-pos-deg
 131       aero/qbar-psf | metrics/Sw-sqft
 132                0     30
 133       -0.349   0.137  0.106
 134        0       0      0
 135        0.349  -0.137 -0.106
 136     \</COEFFICIENT>
 137 </pre>
 138     The definition for a 3D table in a coefficient would be (for example):
 139 <pre>
 140     \<COEFFICIENT NAME="{short name}" TYPE="TABLE3D">
 141       {name}
 142       {number of rows}
 143       {number of columns}
 144       {number of tables}
 145       {row lookup property}
 146       {column lookup property}
 147       {table lookup property}
 148       {non-dimensionalizing}
 149       {first table key}
 150                   {col_1_key   col_2_key   ...  col_n_key }
 151       {row_1_key} {col_1_data  col_2_data  ...  col_n_data}
 152       {row_2_key} {...         ...         ...  ...       }
 153       { ...     } {...         ...         ...  ...       }
 154       {row_n_key} {...         ...         ...  ...       }
 155
 156       {second table key}
 157                   {col_1_key   col_2_key   ...  col_n_key }
 158       {row_1_key} {col_1_data  col_2_data  ...  col_n_data}
 159       {row_2_key} {...         ...         ...  ...       }
 160       { ...     } {...         ...         ...  ...       }
 161       {row_n_key} {...         ...         ...  ...       }
 162
 163       ...
 164
 165     \</COEFFICIENT>
 166 </pre>
 167     [At the present time, all rows and columns for each table must have the
 168     same dimension.]
 169
 170     In addition to using a Table for something like a coefficient, where all the
 171     row and column elements are read in from a file, a Table could be created
 172     and populated completely within program code:
 173 <pre>
 174     // First column is thi, second is neta (combustion efficiency)
 175     Lookup_Combustion_Efficiency = new FGTable(12);
 176     *Lookup_Combustion_Efficiency << 0.00 << 0.980;
 177     *Lookup_Combustion_Efficiency << 0.90 << 0.980;
 178     *Lookup_Combustion_Efficiency << 1.00 << 0.970;
 179     *Lookup_Combustion_Efficiency << 1.05 << 0.950;
 180     *Lookup_Combustion_Efficiency << 1.10 << 0.900;
 181     *Lookup_Combustion_Efficiency << 1.15 << 0.850;
 182     *Lookup_Combustion_Efficiency << 1.20 << 0.790;
 183     *Lookup_Combustion_Efficiency << 1.30 << 0.700;
 184     *Lookup_Combustion_Efficiency << 1.40 << 0.630;
 185     *Lookup_Combustion_Efficiency << 1.50 << 0.570;
 186     *Lookup_Combustion_Efficiency << 1.60 << 0.525;
 187     *Lookup_Combustion_Efficiency << 2.00 << 0.345;
 188 </pre>
 189     The first column in the table, above, is thi (the lookup index, or key). The
 190     second column is the output data - in this case, "neta" (the Greek letter
 191     referring to combustion efficiency). Later on, the table is used like this:
 192
 193     combustion_efficiency = Lookup_Combustion_Efficiency->GetValue(equivalence_ratio);
 194
 195     @author Jon S. Berndt
 196     @version $Id$
 197     @see FGCoefficient
 198     @see FGPropeller
 199 */
 200
 201 /*%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 202 CLASS DECLARATION
 203 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%*/
 204
 205 class FGTable : public FGParameter
 206 {
 207 public:
 208   /// Destructor
 209   ~FGTable();
 210
 211   /** This is the very important copy constructor.
 212       @param table a const reference to a table.*/
 213   FGTable(const FGTable& table);
 214
 215   /// The constructor for a table
 216   FGTable (FGPropertyManager* propMan, Element* el);
 217   FGTable (int );
 218   double GetValue(void) const;
 219   double GetValue(double key) const;
 220   double GetValue(double rowKey, double colKey) const;
 221   double GetValue(double rowKey, double colKey, double TableKey) const;
 222   /** Read the table in.
 223       Data in the config file should be in matrix format with the row
 224       independents as the first column and the column independents in
 225       the first row.  The implication of this layout is that there should
 226       be no value in the upper left corner of the matrix e.g:
 227       <pre>
 228            0  10  20 30 ...
 229       -5   1  2   3  4  ...
 230        ...
 231        </pre>
 232
 233        For multiple-table (i.e. 3D) data sets there is an additional number
 234        key in the table definition. For example:
 235
 236       <pre>
 237        0.0
 238            0  10  20 30 ...
 239       -5   1  2   3  4  ...
 240        ...
 241        </pre>
 242        */
 243
 244   void operator<<(stringstream&);
 245   FGTable& operator<<(const double n);
 246   FGTable& operator<<(const int n);
 247
 248   inline double GetElement(int r, int c) {return Data[r][c];}
 249   inline double GetElement(int r, int c, int t);
 250
 251   void SetRowIndexProperty(FGPropertyManager *node) {lookupProperty[eRow] = node;}
 252   void SetColumnIndexProperty(FGPropertyManager *node) {lookupProperty[eColumn] = node;}
 253
 254   void Print(void);
 255
 256 private:
 257   enum type {tt1D, tt2D, tt3D} Type;
 258   enum axis {eRow=0, eColumn, eTable};
 259   bool internal;
 260   FGPropertyManager *lookupProperty[3];
 261   double** Data;
 262   vector <FGTable*> Tables;
 263   int  FindNumColumns(string);
 264   int nRows, nCols, nTables, dimension;
 265   int colCounter, rowCounter, tableCounter;
 266   mutable int lastRowIndex, lastColumnIndex, lastTableIndex;
 267   double** Allocate(void);
 268   FGPropertyManager* const PropertyManager;
 269
 270   void Debug(int from);
 271 };
 272 }
 273 //%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 274
 275 #endif
 276