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