src/FDM/JSBSim/models/propulsion/FGPropeller.h

   1 /*%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
   2
   3  Header:       FGPropeller.h
   4  Author:       Jon S. Berndt
   5  Date started: 08/24/00
   6
   7  ------------- Copyright (C) 2000  Jon S. Berndt (jon@jsbsim.org) -------------
   8
   9  This program is free software; you can redistribute it and/or modify it under
  10  the terms of the GNU Lesser 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 Lesser General Public License for more
  17  details.
  18
  19  You should have received a copy of the GNU Lesser 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 Lesser General Public License can also be found on
  24  the world wide web at http://www.gnu.org.
  25
  26 HISTORY
  27 --------------------------------------------------------------------------------
  28 08/24/00  JSB  Created
  29
  30 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  31 SENTRY
  32 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%*/
  33
  34 #ifndef FGPROPELLER_H
  35 #define FGPROPELLER_H
  36
  37 /*%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  38 INCLUDES
  39 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%*/
  40
  41 #include "FGThruster.h"
  42 #include "math/FGTable.h"
  43
  44 /*%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  45 DEFINITIONS
  46 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%*/
  47
  48 #define ID_PROPELLER "$Id: FGPropeller.h,v 1.20 2011/10/31 14:54:41 bcoconni Exp $"
  49
  50 /*%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  51 FORWARD DECLARATIONS
  52 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%*/
  53
  54 namespace JSBSim {
  55
  56 /*%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  57 CLASS DOCUMENTATION
  58 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%*/
  59
  60 /** FGPropeller models a propeller given the tabular data for Ct and Cp,
  61     indexed by the advance ratio "J".
  62
  63 <h3>Configuration File Format:</h3>
  64 @code
  65 <sense> {1 | -1} </sense>
  66 <propeller name="{string}">
  67   <ixx> {number} </ixx>
  68   <diameter unit="IN"> {number} </diameter>
  69   <numblades> {number} </numblades>
  70   <gearratio> {number} </gearratio>
  71   <minpitch> {number} </minpitch>
  72   <maxpitch> {number} </maxpitch>
  73   <minrpm> {number} </minrpm>
  74   <maxrpm> {number} </maxrpm>
  75   <constspeed> {number} </constspeed>
  76   <reversepitch> {number} </reversepitch>
  77   <p_factor> {number} </p_factor>
  78   <ct_factor> {number} </ct_factor>
  79   <cp_factor> {number} </cp_factor>
  80
  81   <table name="C_THRUST" type="internal">
  82     <tableData>
  83       {numbers}
  84     </tableData>
  85   </table>
  86
  87   <table name="C_POWER" type="internal">
  88     <tableData>
  89       {numbers}
  90     </tableData>
  91   </table>
  92
  93   <table name="CT_MACH" type="internal">
  94     <tableData>
  95       {numbers}
  96     </tableData>
  97   </table>
  98
  99   <table name="CP_MACH" type="internal">
 100     <tableData>
 101       {numbers}
 102     </tableData>
 103   </table>
 104
 105
 106 </propeller>
 107 @endcode
 108
 109 <h3>Configuration Parameters:</h3>
 110 <pre>
 111     \<ixx>           - Propeller rotational inertia.
 112     \<diameter>      - Propeller disk diameter.
 113     \<numblades>     - Number of blades.
 114     \<gearratio>     - Ratio of (engine rpm) / (prop rpm).
 115     \<minpitch>      - Minimum blade pitch angle.
 116     \<maxpitch>      - Maximum blade pitch angle.
 117     \<minrpm>        - Minimum rpm target for constant speed propeller.
 118     \<maxrpm>        - Maximum rpm target for constant speed propeller.
 119     \<constspeed>    - 1 = constant speed mode, 0 = manual pitch mode.
 120     \<reversepitch>  - Blade pitch angle for reverse.
 121     \<sense>         - Direction of rotation (1=clockwise as viewed from cockpit,
 122                         -1=anti-clockwise as viewed from cockpit). Sense is
 123                        specified in the parent tag of the propeller.
 124     \<p_factor>      - P factor.
 125     \<ct_factor>     - A multiplier for the coefficients of thrust.
 126     \<cp_factor>     - A multiplier for the coefficients of power.
 127 </pre>
 128
 129     Two tables are needed. One for coefficient of thrust (Ct) and one for
 130     coefficient of power (Cp).
 131
 132     Two tables are optional. They apply a factor to Ct and Cp based on the
 133     helical tip Mach.
 134     <br>
 135
 136     Several references were helpful, here:<ul>
 137     <li>Barnes W. McCormick, "Aerodynamics, Aeronautics, and Flight Mechanics",
 138      Wiley & Sons, 1979 ISBN 0-471-03032-5</li>
 139     <li>Edwin Hartman, David Biermann, "The Aerodynamic Characteristics of
 140     Full Scale Propellers Having 2, 3, and 4 Blades of Clark Y and R.A.F. 6
 141     Airfoil Sections", NACA Report TN-640, 1938 (?)</li>
 142     <li>Various NACA Technical Notes and Reports</li>
 143     </ul>
 144     @author Jon S. Berndt
 145     @version $Id: FGPropeller.h,v 1.20 2011/10/31 14:54:41 bcoconni Exp $
 146     @see FGEngine
 147     @see FGThruster
 148 */
 149
 150 /*%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 151 CLASS DECLARATION
 152 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%*/
 153
 154 class FGPropeller : public FGThruster {
 155
 156 public:
 157   /** Constructor for FGPropeller.
 158       @param exec a pointer to the main executive object
 159       @param el a pointer to the thruster config file XML element
 160       @param num the number of this propeller */
 161   FGPropeller(FGFDMExec* exec, Element* el, int num = 0);
 162
 163   /// Destructor for FGPropeller - deletes the FGTable objects
 164   ~FGPropeller();
 165
 166   /** Sets the Revolutions Per Minute for the propeller. Normally the propeller
 167       instance will calculate its own rotational velocity, given the Torque
 168       produced by the engine and integrating over time using the standard
 169       equation for rotational acceleration "a": a = Q/I , where Q is Torque and
 170       I is moment of inertia for the propeller.
 171       @param rpm the rotational velocity of the propeller */
 172   void SetRPM(double rpm) {RPM = rpm;}
 173
 174   /** Sets the Revolutions Per Minute for the propeller using the engine gear ratio **/
 175   void SetEngineRPM(double rpm) {RPM = rpm/GearRatio;}
 176
 177   /// Returns true of this propeller is variable pitch
 178   bool IsVPitch(void) const {return MaxPitch != MinPitch;}
 179
 180   /** This commands the pitch of the blade to change to the value supplied.
 181       This call is meant to be issued either from the cockpit or by the flight
 182       control system (perhaps to maintain constant RPM for a constant-speed
 183       propeller). This value will be limited to be within whatever is specified
 184       in the config file for Max and Min pitch. It is also one of the lookup
 185       indices to the power and thrust tables for variable-pitch propellers.
 186       @param pitch the pitch of the blade in degrees. */
 187   void SetPitch(double pitch) {Pitch = pitch;}
 188
 189   void SetAdvance(double advance) {Advance = advance;}
 190
 191   /// Sets the P-Factor constant
 192   void SetPFactor(double pf) {P_Factor = pf;}
 193
 194   /// Sets propeller into constant speed mode, or manual pitch mode
 195   void SetConstantSpeed(int mode) {ConstantSpeed = mode;}
 196
 197   /// Sets coefficient of thrust multiplier
 198   void SetCtFactor(double ctf) {CtFactor = ctf;}
 199
 200   /// Sets coefficient of power multiplier
 201   void SetCpFactor(double cpf) {CpFactor = cpf;}
 202
 203   /** Sets the rotation sense of the propeller.
 204       @param s this value should be +/- 1 ONLY. +1 indicates clockwise rotation as
 205                viewed by someone standing behind the engine looking forward into
 206                the direction of flight. */
 207   void SetSense(double s) { Sense = s;}
 208
 209   /// Retrieves the pitch of the propeller in degrees.
 210   double GetPitch(void) const     { return Pitch;         }
 211
 212   /// Retrieves the RPMs of the propeller
 213   double GetRPM(void) const       { return RPM;           }
 214
 215   /// Calculates the RPMs of the engine based on gear ratio
 216   double GetEngineRPM(void) const { return RPM * GearRatio;  }
 217
 218   /// Retrieves the propeller moment of inertia
 219   double GetIxx(void) const       { return Ixx;           }
 220
 221   /// Retrieves the coefficient of thrust multiplier
 222   double GetCtFactor(void) const  { return CtFactor;      }
 223
 224   /// Retrieves the coefficient of power multiplier
 225   double GetCpFactor(void) const  { return CpFactor;      }
 226
 227   /// Retrieves the propeller diameter
 228   double GetDiameter(void) const  { return Diameter;      }
 229
 230   /// Retrieves propeller thrust table
 231   FGTable* GetCThrustTable(void) const { return cThrust;}
 232   /// Retrieves propeller power table
 233   FGTable* GetCPowerTable(void)  const { return cPower; }
 234
 235   /// Retrieves propeller thrust Mach effects factor
 236   FGTable* GetCtMachTable(void) const { return CtMach; }
 237   /// Retrieves propeller power Mach effects factor
 238   FGTable* GetCpMachTable(void) const { return CpMach; }
 239
 240   /// Retrieves the Torque in foot-pounds (Don't you love the English system?)
 241   double GetTorque(void) const  { return vTorque(eX); }
 242
 243   /** Retrieves the power required (or "absorbed") by the propeller -
 244       i.e. the power required to keep spinning the propeller at the current
 245       velocity, air density,  and rotational rate. */
 246   double GetPowerRequired(void);
 247
 248   /** Calculates and returns the thrust produced by this propeller.
 249       Given the excess power available from the engine (in foot-pounds), the thrust is
 250       calculated, as well as the current RPM. The RPM is calculated by integrating
 251       the torque provided by the engine over what the propeller "absorbs"
 252       (essentially the "drag" of the propeller).
 253       @param PowerAvailable this is the excess power provided by the engine to
 254       accelerate the prop. It could be negative, dictating that the propeller
 255       would be slowed.
 256       @return the thrust in pounds */
 257   double Calculate(double EnginePower);
 258   FGColumnVector3 GetPFactor(void) const;
 259   string GetThrusterLabels(int id, const string& delimeter);
 260   string GetThrusterValues(int id, const string& delimeter);
 261
 262   void   SetReverseCoef (double c) { Reverse_coef = c; }
 263   double GetReverseCoef (void) const { return Reverse_coef; }
 264   void   SetReverse (bool r) { Reversed = r; }
 265   bool   GetReverse (void) const { return Reversed; }
 266   void   SetFeather (bool f) { Feathered = f; }
 267   bool   GetFeather (void) const { return Feathered; }
 268   double GetThrustCoefficient(void) const {return ThrustCoeff;}
 269   double GetHelicalTipMach(void) const {return HelicalTipMach;}
 270   int    GetConstantSpeed(void) const {return ConstantSpeed;}
 271   void   SetInducedVelocity(double Vi) {Vinduced = Vi;}
 272   double GetInducedVelocity(void) const {return Vinduced;}
 273
 274 private:
 275   int   numBlades;
 276   double J;
 277   double RPM;
 278   double Ixx;
 279   double Diameter;
 280   double MaxPitch;
 281   double MinPitch;
 282   double MinRPM;
 283   double MaxRPM;
 284   double Pitch;
 285   double P_Factor;
 286   double Sense;
 287   double Advance;
 288   double ExcessTorque;
 289   double D4;
 290   double D5;
 291   double HelicalTipMach;
 292   double Vinduced;
 293   FGColumnVector3 vTorque;
 294   FGTable *cThrust;
 295   FGTable *cPower;
 296   FGTable *CtMach;
 297   FGTable *CpMach;
 298   double CtFactor;
 299   double CpFactor;
 300   int    ConstantSpeed;
 301   void Debug(int from);
 302   double ReversePitch; // Pitch, when fully reversed
 303   bool   Reversed;     // true, when propeller is reversed
 304   double Reverse_coef; // 0 - 1 defines AdvancePitch (0=MIN_PITCH 1=REVERSE_PITCH)
 305   bool   Feathered;    // true, if feather command
 306 };
 307 }
 308 //%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 309 #endif
 310