FGRotor.h

/*%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

 Header:       FGRotor.h
 Author:       T. Kreitler
 Date started: 08/24/00

 ------------- Copyright (C) 2010  T. Kreitler (t.kreitler@web.de) -------------

 This program is free software; you can redistribute it and/or modify it under
 the terms of the GNU Lesser General Public License as published by the Free Software
 Foundation; either version 2 of the License, or (at your option) any later
 version.

 This program is distributed in the hope that it will be useful, but WITHOUT
 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
 FOR A PARTICULAR PURPOSE.  See the GNU Lesser General Public License for more
 details.

 You should have received a copy of the GNU Lesser General Public License along with
 this program; if not, write to the Free Software Foundation, Inc., 59 Temple
 Place - Suite 330, Boston, MA  02111-1307, USA.

 Further information about the GNU Lesser General Public License can also be found on
 the world wide web at http://www.gnu.org.

HISTORY
--------------------------------------------------------------------------------
01/01/10  T.Kreitler test implementation
01/10/11  T.Kreitler changed to single rotor model
03/06/11  T.Kreitler added brake, clutch, and experimental free-wheeling-unit
02/05/12  T.Kreitler brake, clutch, and FWU now in FGTransmission class

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
SENTRY
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%*/

#ifndef FGROTOR_H
#define FGROTOR_H

/*%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
INCLUDES
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%*/

#include "FGThruster.h"
#include "FGTransmission.h"

/*%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
DEFINITIONS
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%*/

#define ID_ROTOR "$Id: FGRotor.h,v 1.17 2015/09/27 10:03:53 bcoconni Exp $"

/*%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
FORWARD DECLARATIONS
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%*/

namespace JSBSim {

/*%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
CLASS DOCUMENTATION
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%*/

/*%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
CLASS DECLARATION
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%*/

class FGRotor :  public FGThruster {

  enum eCtrlMapping {eMainCtrl=0, eTailCtrl, eTandemCtrl};

public:

  FGRotor(FGFDMExec *exec, Element* rotor_element, int num);

  ~FGRotor();

  double GetPowerRequired(void)const { return PowerRequired; }

  double Calculate(double EnginePower);


  double GetRPM(void) const { return RPM; }
  void   SetRPM(double rpm) { RPM = rpm; }
  
  double GetEngineRPM(void) const {return EngineRPM;} //{ return GearRatio*RPM; }
  void SetEngineRPM(double rpm) {EngineRPM = rpm;} //{ RPM = rpm/GearRatio; }
  double GetGearRatio(void) { return GearRatio; }
  double GetThrust(void) const { return Thrust; }

  double GetA0(void) const { return a0; }
  double GetA1(void) const { return a1s; }
  double GetB1(void) const { return b1s; }

  double GetLambda(void) const { return lambda; }
  double GetMu(void) const { return mu; }
  double GetNu(void) const { return nu; }
  double GetVi(void) const { return v_induced; }
  double GetCT(void) const { return C_T; }
  double GetTorque(void) const { return Torque; }
  
  double GetThetaDW(void) const { return theta_downwash; }
  double GetPhiDW(void) const { return phi_downwash; }

  double GetGroundEffectScaleNorm(void) const { return GroundEffectScaleNorm; }
  void   SetGroundEffectScaleNorm(double g) { GroundEffectScaleNorm = g; }

  double GetCollectiveCtrl(void) const { return CollectiveCtrl; }
  double GetLateralCtrl(void) const { return LateralCtrl; }
  double GetLongitudinalCtrl(void) const { return LongitudinalCtrl; }

  void SetCollectiveCtrl(double c) { CollectiveCtrl = c; }
  void SetLateralCtrl(double c) { LateralCtrl = c; }
  void SetLongitudinalCtrl(double c) { LongitudinalCtrl = c; }

  // Stubs. Only main rotor RPM is returned
  std::string GetThrusterLabels(int id, const std::string& delimeter);
  std::string GetThrusterValues(int id, const std::string& delimeter);

private:

  // assist in parameter retrieval
  double ConfigValueConv( Element* e, const std::string& ename, double default_val=0.0, 
                                      const std::string& unit = "", bool tell=false);

  double ConfigValue( Element* e, const std::string& ename, double default_val=0.0,
                                  bool tell=false);

  double Configure(Element* rotor_element);

  void CalcRotorState(void);

  // rotor dynamics
  void calc_flow_and_thrust(double theta_0, double Uw, double Ww, double flow_scale = 1.0);
  void calc_coning_angle(double theta_0);
  void calc_flapping_angles(double theta_0, const FGColumnVector3 &pqr_fus_w);
  void calc_drag_and_side_forces(double theta_0);
  void calc_torque(double theta_0);
  void calc_downwash_angles();

  // transformations
  FGColumnVector3 hub_vel_body2ca( const FGColumnVector3 &uvw, const FGColumnVector3 &pqr, 
                                   double a_ic = 0.0 , double b_ic = 0.0 );
  FGColumnVector3 fus_angvel_body2ca( const FGColumnVector3 &pqr);
  FGColumnVector3 body_forces(double a_ic = 0.0 , double b_ic = 0.0 );
  FGColumnVector3 body_moments(double a_ic = 0.0 , double b_ic = 0.0 );

  // interface
  bool bindmodel(FGPropertyManager* pm);
  void Debug(int from);

  // environment
  double dt;
  double rho;
  Filter damp_hagl;

  // configuration parameters
  double Radius;
  int    BladeNum;

  // rpm control
  double Sense;
  double NominalRPM;
  double MinimalRPM;
  double MaximalRPM;
  int    ExternalRPM;
  int    RPMdefinition;
  FGPropertyNode_ptr ExtRPMsource;
  double SourceGearRatio;

  // 'real' rotor parameters
  double BladeChord;
  double LiftCurveSlope;
  double BladeTwist;
  double HingeOffset;
  double BladeFlappingMoment;
  double BladeMassMoment;
  double PolarMoment;
  double InflowLag;
  double TipLossB;

  // groundeffect
  double GroundEffectExp;
  double GroundEffectShift;
  double GroundEffectScaleNorm;

  // derived parameters
  double LockNumberByRho;
  double Solidity; // aka sigma
  double R[5]; // Radius powers
  double B[5]; // TipLossB powers

  // Some of the calculations require shaft axes. So the
  // thruster orientation (Tbo, with b for body) needs to be
  // expressed/represented in helicopter shaft coordinates (Hsr).
  FGMatrix33 InvTransform;
  FGMatrix33 TboToHsr;
  FGMatrix33 HsrToTbo;

  // dynamic values
  double RPM;
  double Omega;          // must be > 0 
  double beta_orient;    // rotor orientation angle (rad)
  double a0;             // coning angle (rad)
  double a_1, b_1, a_dw; // flapping angles
  double a1s, b1s;       // cyclic flapping relative to shaft axes, /SH79/ eqn(43)
  double H_drag, J_side; // Forces

  double Torque;
  double C_T;        // rotor thrust coefficient
  double lambda;     // inflow ratio
  double mu;         // tip-speed ratio 
  double nu;         // induced inflow ratio
  double v_induced;  // induced velocity, usually positive [ft/s]

  double theta_downwash;
  double phi_downwash;

  // control
  eCtrlMapping ControlMap;
  double CollectiveCtrl;
  double LateralCtrl;
  double LongitudinalCtrl;

  // interaction with engine
  FGTransmission *Transmission;
  double EngineRPM;
  double MaxBrakePower;
  double GearLoss;
  double GearMoment;

};

}
//%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
#endif