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