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.16 2010/04/09 12:44:06 jberndt 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 <propeller name="{string}">
  66   <ixx> {number} </ixx>
  67   <diameter unit="IN"> {number} </diameter>
  68   <numblades> {number} </numblades>
  69   <gearratio> {number} </gearratio>
  70   <minpitch> {number} </minpitch>
  71   <maxpitch> {number} </maxpitch>
  72   <minrpm> {number} </minrpm>
  73   <maxrpm> {number} </maxrpm>
  74   <constspeed> {number} </constspeed>
  75   <reversepitch> {number} </reversepitch>
  76   <sense> {1 | -1} </sense>
  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).
 123     \<p_factor>      - P factor.
 124     \<ct_factor>     - A multiplier for the coefficients of thrust.
 125     \<cp_factor>     - A multiplier for the coefficients of power.
 126 </pre>
 127
 128     Two tables are needed. One for coefficient of thrust (Ct) and one for
 129     coefficient of power (Cp).
 130
 131     Two tables are optional. They apply a factor to Ct and Cp based on the
 132     helical tip Mach.
 133     <br>
 134
 135     Several references were helpful, here:<ul>
 136     <li>Barnes W. McCormick, "Aerodynamics, Aeronautics, and Flight Mechanics",
 137      Wiley & Sons, 1979 ISBN 0-471-03032-5</li>
 138     <li>Edwin Hartman, David Biermann, "The Aerodynamic Characteristics of
 139     Full Scale Propellers Having 2, 3, and 4 Blades of Clark Y and R.A.F. 6
 140     Airfoil Sections", NACA Report TN-640, 1938 (?)</li>
 141     <li>Various NACA Technical Notes and Reports</li>
 142     </ul>
 143     @author Jon S. Berndt
 144     @version $Id: FGPropeller.h,v 1.16 2010/04/09 12:44:06 jberndt Exp $
 145     @see FGEngine
 146     @see FGThruster
 147 */
 148
 149 /*%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 150 CLASS DECLARATION
 151 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%*/
 152
 153 class FGPropeller : public FGThruster {
 154
 155 public:
 156   /** Constructor for FGPropeller.
 157       @param exec a pointer to the main executive object
 158       @param el a pointer to the thruster config file XML element
 159       @param num the number of this propeller */
 160   FGPropeller(FGFDMExec* exec, Element* el, int num = 0);
 161
 162   /// Destructor for FGPropeller - deletes the FGTable objects
 163   ~FGPropeller();
 164
 165   /** Sets the Revolutions Per Minute for the propeller. Normally the propeller
 166       instance will calculate its own rotational velocity, given the Torque
 167       produced by the engine and integrating over time using the standard
 168       equation for rotational acceleration "a": a = Q/I , where Q is Torque and
 169       I is moment of inertia for the propeller.
 170       @param rpm the rotational velocity of the propeller */
 171   void SetRPM(double rpm) {RPM = rpm;}
 172
 173   /// Returns true of this propeller is variable pitch
 174   bool IsVPitch(void) {return MaxPitch != MinPitch;}
 175
 176   /** This commands the pitch of the blade to change to the value supplied.
 177       This call is meant to be issued either from the cockpit or by the flight
 178       control system (perhaps to maintain constant RPM for a constant-speed
 179       propeller). This value will be limited to be within whatever is specified
 180       in the config file for Max and Min pitch. It is also one of the lookup
 181       indices to the power and thrust tables for variable-pitch propellers.
 182       @param pitch the pitch of the blade in degrees. */
 183   void SetPitch(double pitch) {Pitch = pitch;}
 184
 185   void SetAdvance(double advance) {Advance = advance;}
 186
 187   /// Sets the P-Factor constant
 188   void SetPFactor(double pf) {P_Factor = pf;}
 189
 190   /// Sets propeller into constant speed mode, or manual pitch mode
 191   void SetConstantSpeed(int mode) {ConstantSpeed = mode;}
 192
 193   /// Sets coefficient of thrust multiplier
 194   void SetCtFactor(double ctf) {CtFactor = ctf;}
 195
 196   /// Sets coefficient of power multiplier
 197   void SetCpFactor(double cpf) {CpFactor = cpf;}
 198
 199   /** Sets the rotation sense of the propeller.
 200       @param s this value should be +/- 1 ONLY. +1 indicates clockwise rotation as
 201                viewed by someone standing behind the engine looking forward into
 202                the direction of flight. */
 203   void SetSense(double s) { Sense = s;}
 204
 205   /// Retrieves the pitch of the propeller in degrees.
 206   double GetPitch(void)         { return Pitch;         }
 207
 208   /// Retrieves the RPMs of the propeller
 209   double GetRPM(void)     const { return RPM;           }
 210
 211   /// Retrieves the propeller moment of inertia
 212   double GetIxx(void)           { return Ixx;           }
 213
 214   /// Retrieves the coefficient of thrust multiplier
 215   double GetCtFactor(void)      { return CtFactor;      }
 216
 217   /// Retrieves the coefficient of power multiplier
 218   double GetCpFactor(void)      { return CpFactor;      }
 219
 220   /// Retrieves the propeller diameter
 221   double GetDiameter(void)      { return Diameter;      }
 222
 223   /// Retrieves propeller thrust table
 224   FGTable* GetCThrustTable(void) const { return cThrust;}
 225   /// Retrieves propeller power table
 226   FGTable* GetCPowerTable(void)  const { return cPower; }
 227
 228   /// Retrieves propeller thrust Mach effects factor
 229   FGTable* GetCtMachTable(void) const { return CtMach; }
 230   /// Retrieves propeller power Mach effects factor
 231   FGTable* GetCpMachTable(void) const { return CpMach; }
 232
 233   /// Retrieves the Torque in foot-pounds (Don't you love the English system?)
 234   double GetTorque(void)        { return vTorque(eX);    }
 235
 236   /** Retrieves the power required (or "absorbed") by the propeller -
 237       i.e. the power required to keep spinning the propeller at the current
 238       velocity, air density,  and rotational rate. */
 239   double GetPowerRequired(void);
 240
 241   /** Calculates and returns the thrust produced by this propeller.
 242       Given the excess power available from the engine (in foot-pounds), the thrust is
 243       calculated, as well as the current RPM. The RPM is calculated by integrating
 244       the torque provided by the engine over what the propeller "absorbs"
 245       (essentially the "drag" of the propeller).
 246       @param PowerAvailable this is the excess power provided by the engine to
 247       accelerate the prop. It could be negative, dictating that the propeller
 248       would be slowed.
 249       @return the thrust in pounds */
 250   double Calculate(double PowerAvailable);
 251   FGColumnVector3 GetPFactor(void);
 252   string GetThrusterLabels(int id, string delimeter);
 253   string GetThrusterValues(int id, string delimeter);
 254
 255   void   SetReverseCoef (double c) { Reverse_coef = c; }
 256   double GetReverseCoef (void) { return Reverse_coef; }
 257   void   SetReverse (bool r) { Reversed = r; }
 258   bool   GetReverse (void) { return Reversed; }
 259   void   SetFeather (bool f) { Feathered = f; }
 260   bool   GetFeather (void) { return Feathered; }
 261   double GetThrustCoefficient(void) const {return ThrustCoeff;}
 262   double GetHelicalTipMach(void) const {return HelicalTipMach;}
 263   int    GetConstantSpeed(void) const {return ConstantSpeed;}
 264   void   SetInducedVelocity(double Vi) {Vinduced = Vi;}
 265   double GetInducedVelocity(void) const {return Vinduced;}
 266
 267 private:
 268   int   numBlades;
 269   double J;
 270   double RPM;
 271   double Ixx;
 272   double Diameter;
 273   double MaxPitch;
 274   double MinPitch;
 275   double MinRPM;
 276   double MaxRPM;
 277   double Pitch;
 278   double P_Factor;
 279   double Sense;
 280   double Advance;
 281   double ExcessTorque;
 282   double D4;
 283   double D5;
 284   double HelicalTipMach;
 285   double Vinduced;
 286   FGColumnVector3 vTorque;
 287   FGTable *cThrust;
 288   FGTable *cPower;
 289   FGTable *CtMach;
 290   FGTable *CpMach;
 291   double CtFactor;
 292   double CpFactor;
 293   int    ConstantSpeed;
 294   void Debug(int from);
 295   double ReversePitch; // Pitch, when fully reversed
 296   bool   Reversed;     // true, when propeller is reversed
 297   double Reverse_coef; // 0 - 1 defines AdvancePitch (0=MIN_PITCH 1=REVERSE_PITCH)
 298   bool   Feathered;    // true, if feather command
 299 };
 300 }
 301 //%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 302 #endif
 303