src/FDM/JSBSim/FGFDMExec.h

   1 /*%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
   2  Header:       FGFDMExec.h
   3  Author:       Jon Berndt
   4  Date started: 11/17/98
   5
   6  ------------- Copyright (C) 1999  Jon S. Berndt (jsb@hal-pc.org) -------------
   7
   8  This program is free software; you can redistribute it and/or modify it under
   9  the terms of the GNU General Public License as published by the Free Software
  10  Foundation; either version 2 of the License, or (at your option) any later
  11  version.
  12
  13  This program is distributed in the hope that it will be useful, but WITHOUT
  14  ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
  15  FOR A PARTICULAR PURPOSE.  See the GNU General Public License for more
  16  details.
  17
  18  You should have received a copy of the GNU General Public License along with
  19  this program; if not, write to the Free Software Foundation, Inc., 59 Temple
  20  Place - Suite 330, Boston, MA  02111-1307, USA.
  21
  22  Further information about the GNU General Public License can also be found on
  23  the world wide web at http://www.gnu.org.
  24
  25 HISTORY
  26 --------------------------------------------------------------------------------
  27 11/17/98   JSB   Created
  28 7/31/99     TP   Added RunIC function that runs the sim so that every frame
  29                  begins with the IC values from the given FGInitialCondition
  30                  object and dt=0.
  31
  32 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  33 SENTRY
  34 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%*/
  35
  36 #ifndef FGFDMEXEC_HEADER_H
  37 #define FGFDMEXEC_HEADER_H
  38
  39 /*%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  40 INCLUDES
  41 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%*/
  42
  43 #include <models/FGModel.h>
  44 #include <models/FGOutput.h>
  45 #include <models/FGInput.h>
  46 #include <initialization/FGTrim.h>
  47 #include <initialization/FGInitialCondition.h>
  48 #include <FGJSBBase.h>
  49 #include <input_output/FGPropertyManager.h>
  50 #include <input_output/FGXMLParse.h>
  51 #include <input_output/FGGroundCallback.h>
  52 #include <models/FGPropagate.h>
  53
  54 #include <vector>
  55
  56 /*%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  57 DEFINITIONS
  58 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%*/
  59
  60 #define ID_FDMEXEC "$Id$"
  61
  62 /*%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  63 FORWARD DECLARATIONS
  64 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%*/
  65
  66 namespace JSBSim {
  67
  68 /*%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  69 CLASS DOCUMENTATION
  70 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%*/
  71
  72 /** Encapsulates the JSBSim simulation executive.
  73     This class is the interface class through which all other simulation classes
  74     are instantiated, initialized, and run. When integrated with FlightGear (or
  75     other flight simulator) this class is typically instantiated by an interface
  76     class on the simulator side.
  77
  78     When an aircraft model is loaded the config file is parsed and for each of the
  79     sections of the config file (propulsion, flight control, etc.) the
  80     corresponding Load() method is called (e.g. LoadFCS).
  81
  82     <h4>JSBSim Debugging Directives</h4>
  83
  84     This describes to any interested entity the debug level
  85     requested by setting the JSBSIM_DEBUG environment variable.
  86     The bitmasked value choices are as follows:
  87     - <b>unset</b>: In this case (the default) JSBSim would only print
  88        out the normally expected messages, essentially echoing
  89        the config files as they are read. If the environment
  90        variable is not set, debug_lvl is set to 1 internally
  91     - <b>0</b>: This requests JSBSim not to output any messages
  92        whatsoever
  93     - <b>1</b>: This value explicity requests the normal JSBSim
  94        startup messages
  95     - <b>2</b>: This value asks for a message to be printed out when
  96        a class is instantiated
  97     - <b>4</b>: When this value is set, a message is displayed when a
  98        FGModel object executes its Run() method
  99     - <b>8</b>: When this value is set, various runtime state variables
 100        are printed out periodically
 101     - <b>16</b>: When set various parameters are sanity checked and
 102        a message is printed out when they go out of bounds
 103
 104     @author Jon S. Berndt
 105     @version $Id$
 106 */
 107
 108 /*%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 109 CLASS DECLARATION
 110 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%*/
 111
 112 class FGFDMExec : public FGJSBBase
 113 {
 114 public:
 115
 116   /// Default constructor
 117   FGFDMExec(FGPropertyManager* root = 0);
 118
 119   /// Default destructor
 120   ~FGFDMExec();
 121
 122   /** This routine places a model into the runlist at the specified rate. The
 123       "rate" is not really a clock rate. It represents how many calls to the
 124       FGFDMExec::Run() method must be made before the model is executed. A
 125       value of 1 means that the model will be executed for each call to the
 126       exec's Run() method. A value of 5 means that the model will only be
 127       executed every 5th call to the exec's Run() method.
 128       @param model A pointer to the model being scheduled.
 129       @param rate The rate at which to execute the model as described above.
 130       @return Currently returns 0 always. */
 131   int  Schedule(FGModel* model, int rate);
 132
 133   /** This executes each scheduled model in succession.
 134       @return true if successful, false if sim should be ended  */
 135   bool Run(void);
 136
 137   /** Initializes the sim from the initial condition object and executes
 138       each scheduled model without integrating i.e. dt=0.
 139       @return true if successful */
 140   bool RunIC(void);
 141
 142   /** Sets the ground callback pointer.
 143       @param gc A pointer to a ground callback object.  */
 144   void SetGroundCallback(FGGroundCallback* gc);
 145
 146   /** Loads an aircraft model.
 147       @param AircraftPath path to the aircraft directory. For instance:
 148       "aircraft". Under aircraft, then, would be directories for various
 149       modeled aircraft such as C172/, x15/, etc.
 150       @param EnginePath path to the directory under which engine config
 151       files are kept, for instance "engine"
 152       @param model the name of the aircraft model itself. This file will
 153       be looked for in the directory specified in the AircraftPath variable,
 154       and in turn under the directory with the same name as the model. For
 155       instance: "aircraft/x15/x15.xml"
 156       @param addModelToPath set to true to add the model name to the
 157       AircraftPath, defaults to true
 158       @return true if successful*/
 159   bool LoadModel(string AircraftPath, string EnginePath, string model,
 160                  bool addModelToPath = true);
 161
 162   /** Loads an aircraft model.  The paths to the aircraft and engine
 163       config file directories must be set prior to calling this.  See
 164       below.
 165       @param model the name of the aircraft model itself. This file will
 166       be looked for in the directory specified in the AircraftPath variable,
 167       and in turn under the directory with the same name as the model. For
 168       instance: "aircraft/x15/x15.xml"
 169       @param addModelToPath set to true to add the model name to the
 170       AircraftPath, defaults to true
 171       @return true if successful*/
 172   bool LoadModel(string model, bool addModelToPath = true);
 173
 174   /** Sets the path to the engine config file directories.
 175       @param path path to the directory under which engine config
 176       files are kept, for instance "engine"  */
 177   bool SetEnginePath(string path)   { EnginePath = path; return true; }
 178
 179   /** Sets the path to the aircraft config file directories.
 180       @param path path to the aircraft directory. For instance:
 181       "aircraft". Under aircraft, then, would be directories for various
 182       modeled aircraft such as C172/, x15/, etc.  */
 183   bool SetAircraftPath(string path) { AircraftPath = path; return true; }
 184
 185   /// @name Top-level executive State and Model retrieval mechanism
 186   //@{
 187   /// Returns the FGAtmosphere pointer.
 188   inline FGAtmosphere* GetAtmosphere(void)    {return Atmosphere;}
 189   /// Returns the FGFCS pointer.
 190   inline FGFCS* GetFCS(void)                  {return FCS;}
 191   /// Returns the FGPropulsion pointer.
 192   inline FGPropulsion* GetPropulsion(void)    {return Propulsion;}
 193   /// Returns the FGAircraft pointer.
 194   inline FGMassBalance* GetMassBalance(void)  {return MassBalance;}
 195   /// Returns the FGAerodynamics pointer
 196   inline FGAerodynamics* GetAerodynamics(void){return Aerodynamics;}
 197   /// Returns the FGInertial pointer.
 198   inline FGInertial* GetInertial(void)        {return Inertial;}
 199   /// Returns the FGGroundReactions pointer.
 200   inline FGGroundReactions* GetGroundReactions(void) {return GroundReactions;}
 201   /// Returns the FGAircraft pointer.
 202   inline FGAircraft* GetAircraft(void)        {return Aircraft;}
 203   /// Returns the FGPropagate pointer.
 204   inline FGPropagate* GetPropagate(void)      {return Propagate;}
 205   /// Returns the FGAuxiliary pointer.
 206   inline FGAuxiliary* GetAuxiliary(void)      {return Auxiliary;}
 207   /// Returns the FGInput pointer.
 208   inline FGInput* GetInput(void)              {return Input;}
 209   /// Returns the FGGroundCallback pointer.
 210   inline FGGroundCallback* GetGroundCallback(void) {return GroundCallback;}
 211   /// Returns the FGState pointer.
 212   inline FGState* GetState(void)              {return State;}
 213   // Returns a pointer to the FGInitialCondition object
 214   inline FGInitialCondition* GetIC(void)      {return IC;}
 215   // Returns a pointer to the FGTrim object
 216   inline FGTrim* GetTrim(void);
 217   //@}
 218
 219   /// Retrieves the engine path.
 220   inline string GetEnginePath(void)          {return EnginePath;}
 221   /// Retrieves the aircraft path.
 222   inline string GetAircraftPath(void)        {return AircraftPath;}
 223
 224   /// Returns the model name.
 225   string GetModelName(void) { return modelName; }
 226
 227   /// Returns a pointer to the property manager object.
 228   FGPropertyManager* GetPropertyManager(void);
 229   /// Returns a vector of strings representing the names of all loaded models (future)
 230   vector <string> EnumerateFDMs(void);
 231   /// Marks this instance of the Exec object as a "slave" object.
 232   void SetSlave(void) {IsSlave = true;}
 233
 234   /** Executes trimming in the selected mode.
 235   *   @param mode Specifies how to trim:
 236   * - tLongitudinal=0
 237   * - tFull
 238   * - tGround
 239   * - tPullup
 240   * - tCustom
 241   * - tTurn
 242   * - tNone
 243   */
 244   void DoTrim(int mode);
 245
 246   /// Disables data logging to all outputs.
 247   void DisableOutput(void);
 248   /// Enables data logging to all outputs.
 249   void EnableOutput(void);
 250   /// Pauses execution by preventing time from incrementing.
 251   void Hold(void) {holding = true;}
 252   /// Resumes execution from a "Hold".
 253   void Resume(void) {holding = false;}
 254   /// Returns true if the simulation is Holding (i.e. simulation time is not moving).
 255   bool Holding(void) {return holding;}
 256
 257   struct PropertyCatalogStructure {
 258     /// Name of the property.
 259     string base_string;
 260     /// The node for the property.
 261     FGPropertyManager *node;
 262   };
 263
 264   /** Builds a catalog of properties.
 265   *   This function descends the property tree and creates a list (an STL vector)
 266   *   containing the name and node for all properties.
 267   *   @param pcs The "root" property catalog structure pointer.  */
 268   void BuildPropertyCatalog(struct PropertyCatalogStructure* pcs);
 269
 270   /** Retrieves property or properties matching the supplied string.
 271   *   A string is returned that contains a carriage return delimited list of all
 272   *   strings in the property catalog that matches the supplied chack string.
 273   *   @param check The string to search for in the property catalog.
 274   *   @return the carriage-return-delimited string containing all matching strings
 275   *               in the catalog.  */
 276   string QueryPropertyCatalog(string check);
 277
 278   /// Use the MSIS atmosphere model.
 279   void UseAtmosphereMSIS(void);
 280
 281   /// Use the Mars atmosphere model. (Not operative yet.)
 282   void UseAtmosphereMars(void);
 283
 284 private:
 285   FGModel* FirstModel;
 286
 287   bool terminate;
 288   bool holding;
 289   bool Constructing;
 290   int  Error;
 291   unsigned int Frame;
 292   unsigned int IdFDM;
 293   FGPropertyManager* Root;
 294   static unsigned int FDMctr;
 295   bool modelLoaded;
 296   string modelName;
 297   bool IsSlave;
 298   static FGPropertyManager *master;
 299   FGPropertyManager *instance;
 300   vector <string> PropertyCatalog;
 301
 302   struct slaveData {
 303     FGFDMExec* exec;
 304     string info;
 305     double x, y, z;
 306     double roll, pitch, yaw;
 307     bool mated;
 308
 309     slaveData(void) {
 310       info = "";
 311       x = y = z = 0.0;
 312       roll = pitch = yaw = 0.0;
 313       mated = true;
 314     }
 315
 316     ~slaveData(void) {
 317       delete exec;
 318     }
 319   };
 320
 321   string AircraftPath;
 322   string EnginePath;
 323
 324   string CFGVersion;
 325   string Release;
 326
 327   FGGroundCallback*  GroundCallback;
 328   FGState*           State;
 329   FGAtmosphere*      Atmosphere;
 330   FGFCS*             FCS;
 331   FGPropulsion*      Propulsion;
 332   FGMassBalance*     MassBalance;
 333   FGAerodynamics*    Aerodynamics;
 334   FGInertial*        Inertial;
 335   FGGroundReactions* GroundReactions;
 336   FGAircraft*        Aircraft;
 337   FGPropagate*       Propagate;
 338   FGAuxiliary*       Auxiliary;
 339   FGInput*           Input;
 340   vector <FGOutput*> Outputs;
 341
 342   FGInitialCondition* IC;
 343   FGTrim *Trim;
 344
 345   vector <slaveData*> SlaveFDMList;
 346
 347   bool ReadFileHeader(Element*);
 348   bool ReadSlave(Element*);
 349   bool ReadPrologue(Element*);
 350
 351   bool Allocate(void);
 352   bool DeAllocate(void);
 353   void Debug(int from);
 354 };
 355 }
 356 //%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 357 #endif
 358