src/FDM/JSBSim/models/flight_control/FGGain.h

   1 /*%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
   2
   3  Header:       FGGain.h
   4  Author:       Jon Berndt
   5  Date started: 1998 ?
   6
   7  ------------- Copyright (C) 1998 by 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
  29 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  30 SENTRY
  31 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%*/
  32
  33 #ifndef FGGAIN_H
  34 #define FGGAIN_H
  35
  36 /*%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  37 INCLUDES
  38 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%*/
  39
  40 #include "FGFCSComponent.h"
  41 #include "math/FGTable.h"
  42
  43 /*%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  44 DEFINITIONS
  45 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%*/
  46
  47 #define ID_GAIN "$Id: FGGain.h,v 1.14 2009/10/24 22:59:30 jberndt Exp $"
  48
  49 /*%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  50 FORWARD DECLARATIONS
  51 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%*/
  52
  53 namespace JSBSim {
  54
  55 class FGFCS;
  56 class Element;
  57
  58 /*%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  59 CLASS DOCUMENTATION
  60 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%*/
  61
  62 /** Encapsulates a gain component for the flight control system.
  63     The gain component merely multiplies the input by a gain.  The <b>pure gain</b> form
  64     of the component specification is:
  65
  66     @code
  67     <pure_gain name="name">
  68       <input> {[-]property} </input>
  69       <gain> {property name | value} </gain>
  70       [<clipto>
  71         <min> {property name | value} </min>
  72         <max> {property name | value} </max>
  73       </clipto>]
  74       [<output> {property} </output>]
  75     </pure_gain>
  76     @endcode
  77
  78     Example:
  79
  80     @code
  81     <pure_gain name="Roll AP Wing Leveler">
  82       <input>fcs/attitude/sensor/phi-rad</input>
  83       <gain>2.0</gain>
  84       <clipto>
  85         <min>-0.255</min>
  86         <max>0.255</max>
  87       </clipto>
  88     </pure_gain>
  89     @endcode
  90
  91     Note: the input property name may be immediately preceded by a minus sign to
  92     invert that signal.
  93
  94     The <b>scheduled gain</b> component multiplies the input by a variable gain that is
  95     dependent on another property (such as qbar, altitude, etc.).  The lookup
  96     mapping is in the form of a table.  This kind of component might be used, for
  97     example, in a case where aerosurface deflection must only be commanded to
  98     acceptable settings - i.e at higher qbar the commanded elevator setting might
  99     be attenuated.  The form of the scheduled gain component specification is:
 100
 101     @code
 102     <scheduled_gain name="name">
 103       <input> {[-]property} </input>
 104       <table>
 105         <tableData>
 106           ...
 107         </tableData>
 108       </table>
 109       [<clipto>
 110         <min> {[-]property name | value} </min>
 111         <max> {[-]property name | value} </max>
 112       </clipto>]
 113       [<gain> {property name | value} </gain>]
 114       [<output> {property} </output>]
 115     </scheduled_gain>
 116     @endcode
 117
 118     Example:
 119
 120     @code
 121     <scheduled_gain name="Scheduled Steer Pos Deg">
 122         <input>fcs/steer-cmd-norm</input>
 123         <table>
 124             <independentVar>velocities/vg-fps</independentVar>
 125             <tableData>
 126                 10.0        80.0
 127                 50.0        15.0
 128                 150.0       2.0
 129             </tableData>
 130         </table>
 131         <gain>0.017</gain>
 132         <output>fcs/steer-pos-rad</output>
 133     </scheduled_gain>
 134     @endcode
 135
 136     An overall GAIN may be supplied that is multiplicative with the scheduled gain.
 137
 138     Note: the input property name may be immediately preceded by a minus sign to
 139     invert that signal.
 140
 141     In the example above, we see the utility of the overall gain value in
 142     effecting a degrees-to-radians conversion.
 143
 144     The <b>aerosurface scale</b> component is a modified version of the simple gain
 145     component.  The purpose for this component is to take control inputs from the
 146     domain minimum and maximum, as specified (or from -1 to +1 by default) and
 147     scale them to map to a specified range. This can be done, for instance, to match
 148     the component outputs to the expected inputs to a flight control system.
 149
 150     The zero_centered element dictates whether the domain-to-range mapping is linear
 151     or centered about zero. For example, if zero_centered is false, and if the domain
 152     or range is not symmetric about zero, and an input value is zero, the output
 153     will not be zero. Let's say that the domain is min=-2 and max=+4, with a range
 154     of -1 to +1. If the input is 0.0, then the "normalized" input is calculated to
 155     be 33% of the way from the minimum to the maximum. That input would be mapped
 156     to an output of -0.33, which is 33% of the way from the range minimum to maximum.
 157     If zero_centered is set to true (or 1) then an input of 0.0 will be mapped to an
 158     output of 0.0, although if either the domain or range are unsymmetric about
 159     0.0, then the scales for the positive and negative portions of the input domain
 160     (above and below 0.0) will be different. The zero_centered element is true by
 161     default. Note that this feature may be important for some control surface mappings,
 162     where the maximum upper and lower deflections may be different, but where a zero
 163     setting is desired to be the "undeflected" value, and where full travel of the
 164     stick is desired to cause a full deflection of the control surface.
 165
 166     The form of the aerosurface scaling component specification is:
 167
 168     @code
 169     <aerosurface_scale name="name">
 170       <input> {[-]property name} </input>
 171       <domain>
 172         <min> {value} </min>   <!-- If omitted, default is -1.0 ->
 173         <max> {value} </max>   <!-- If omitted, default is  1.0 ->
 174       </domain>
 175       <range>
 176         <min> {value} </min>   <!-- If omitted, default is 0 ->
 177         <max> {value} </max>   <!-- If omitted, default is 0 ->
 178       </range>
 179       <zero_centered< value </zero_centered>
 180       [<clipto>
 181         <min> {[-]property name | value} </min>
 182         <max> {[-]property name | value} </max>
 183       </clipto>]
 184       [<gain> {property name | value} </gain>]
 185       [<output> {property} </output>]
 186     </aerosurface_scale>
 187     @endcode
 188
 189     Note: the input property name may be immediately preceded by a minus sign to
 190     invert that signal.
 191
 192     For instance, the normal and expected ability of a
 193     pilot to push or pull on a control stick is about 50 pounds.  The input to the
 194     pitch channel block diagram of a flight control system is often in units of pounds.
 195     Yet, the joystick control input usually defines a span from -1 to +1. The aerosurface_scale
 196     form of the gain component maps the inputs to the desired output range. The example
 197     below shoes a simple aerosurface_scale component that maps the joystick
 198     input to a range of +/- 50, which represents pilot stick force in pounds for the F-16.
 199
 200     @code
 201     <aerosurface_scale name="Pilot input">
 202       <input>fcs/elevator-cmd-norm</input>
 203       <range>
 204         <min> -50 </min>   <!-- If omitted, default is 0 ->
 205         <max>  50 </max>   <!-- If omitted, default is 0 ->
 206       </range>
 207     </aerosurface_scale>
 208     @endcode
 209
 210     @author Jon S. Berndt
 211     @version $Revision: 1.14 $
 212 */
 213
 214 /*%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 215 CLASS DECLARATION
 216 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%*/
 217
 218 class FGGain  : public FGFCSComponent
 219 {
 220 public:
 221   FGGain(FGFCS* fcs, Element* element);
 222   ~FGGain();
 223
 224   bool Run (void);
 225
 226 private:
 227   FGTable* Table;
 228   FGPropertyManager* GainPropertyNode;
 229   double GainPropertySign;
 230   double Gain;
 231   double InMin, InMax, OutMin, OutMax;
 232   int Rows;
 233   bool ZeroCentered;
 234
 235   void Debug(int from);
 236 };
 237 }
 238 #endif