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

   1 /*%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
   2
   3  Header:       FGFilter.h
   4  Author:       Jon S. Berndt
   5  Date started: 4/2000
   6
   7  ------------- Copyright (C) 2000 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 FGFILTER_H
  34 #define FGFILTER_H
  35
  36 /*%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  37 INCLUDES
  38 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%*/
  39
  40 #include "FGFCSComponent.h"
  41 #include <input_output/FGXMLElement.h>
  42
  43 /*%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  44 DEFINITIONS
  45 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%*/
  46
  47 #define ID_FILTER "$Id$"
  48
  49 /*%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  50 FORWARD DECLARATIONS
  51 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%*/
  52
  53 namespace JSBSim {
  54
  55 /*%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  56 CLASS DOCUMENTATION
  57 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%*/
  58
  59 /** Encapsulates a filter for the flight control system.
  60 The filter component can simulate any first or second order filter. The
  61 Tustin substitution is used to take filter definitions from LaPlace space to the
  62 time domain. The general format for a filter specification is:
  63
  64 @code
  65 <typename name="name">
  66   <input> property </input>
  67   <c1> value|property </c1>
  68   [<c2> value|property </c2>]
  69   [<c3> value|property </c3>]
  70   [<c4> value|property </c4>]
  71   [<c5> value|property </c5>]
  72   [<c6> value|property </c6>]
  73   [<clipto>
  74     <min> {[-]property name | value} </min>
  75     <max> {[-]property name | value} </max>
  76   </clipto>]
  77   [<output> property </output>]
  78 </typename>
  79 @endcode
  80
  81 For a lag filter of the form,
  82
  83 @code
  84   C1
  85 ------
  86 s + C1
  87 @endcode
  88
  89 the corresponding filter definition is:
  90
  91 @code
  92 <lag_filter name="name">
  93   <input> property </input>
  94   <c1> value|property </c1>
  95   [<clipto>
  96     <min> {[-]property name | value} </min>
  97     <max> {[-]property name | value} </max>
  98   </clipto>]
  99   [<output> property <output>]
 100 </lag_filter>
 101 @endcode
 102
 103 As an example, for the specific filter:
 104
 105 @code
 106   600
 107 ------
 108 s + 600
 109 @endcode
 110
 111 the corresponding filter definition could be:
 112
 113 @code
 114 <lag_filter name="Heading Roll Error Lag">
 115   <input> fcs/heading-command </input>
 116   <c1> 600 </c1>
 117 </lag_filter>
 118 @endcode
 119
 120 For a lead-lag filter of the form:
 121
 122 @code
 123 C1*s + C2
 124 ---------
 125 C3*s + C4
 126 @endcode
 127
 128 The corresponding filter definition is:
 129
 130 @code
 131 <lead_lag_filter name="name">
 132   <input> property </input>
 133   <c1> value|property <c/1>
 134   <c2> value|property <c/2>
 135   <c3> value|property <c/3>
 136   <c4> value|property <c/4>
 137   [<clipto>
 138     <min> {[-]property name | value} </min>
 139     <max> {[-]property name | value} </max>
 140   </clipto>]
 141   [<output> property </output>]
 142 </lead_lag_filter>
 143 @endcode
 144
 145 For a washout filter of the form:
 146
 147 @code
 148   s
 149 ------
 150 s + C1
 151 @endcode
 152
 153 The corresponding filter definition is:
 154
 155 @code
 156 <washout_filter name="name">
 157   <input> property </input>
 158   <c1> value </c1>
 159   [<clipto>
 160     <min> {[-]property name | value} </min>
 161     <max> {[-]property name | value} </max>
 162   </clipto>]
 163   [<output> property </output>]
 164 </washout_filter>
 165 @endcode
 166
 167 For a second order filter of the form:
 168
 169 @code
 170 C1*s^2 + C2*s + C3
 171 ------------------
 172 C4*s^2 + C5*s + C6
 173 @endcode
 174
 175 The corresponding filter definition is:
 176
 177 @code
 178 <second_order_filter name="name">
 179   <input> property </input>
 180   <c1> value|property </c1>
 181   <c2> value|property </c2>
 182   <c3> value|property </c3>
 183   <c4> value|property </c4>
 184   <c5> value|property </c5>
 185   <c6> value|property </c6>
 186   [<clipto>
 187     <min> {[-]property name | value} </min>
 188     <max> {[-]property name | value} </max>
 189   </clipto>]
 190   [<output> property </output>]
 191 </second_order_filter>
 192 @endcode
 193
 194 For an integrator of the form:
 195
 196 @code
 197  C1
 198  ---
 199   s
 200 @endcode
 201
 202 The corresponding filter definition is:
 203
 204 @code
 205 <integrator name="name">
 206   <input> property </input>
 207   <c1> value|property </c1>
 208   [<trigger> property </trigger>]
 209   [<clipto>
 210     <min> {[-]property name | value} </min>
 211     <max> {[-]property name | value} </max>
 212   </clipto>]
 213   [<output> property </output>]
 214 </integrator>
 215 @endcode
 216
 217 For the integrator, the trigger features the following behavior. If the trigger
 218 property value is:
 219   - 0: no action is taken - the output is calculated normally
 220   - not 0: (or simply greater than zero), all current and previous inputs will
 221            be set to 0.0
 222
 223 In all the filter specifications above, an \<output> element is also seen.  This
 224 is so that the last component in a "string" can copy its value to the appropriate
 225 output, such as the elevator, or speedbrake, etc.
 226
 227 @author Jon S. Berndt
 228 @version $Revision$
 229
 230 */
 231
 232 /*%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 233 CLASS DECLARATION
 234 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%*/
 235
 236 class FGFilter  : public FGFCSComponent
 237 {
 238 public:
 239   FGFilter(FGFCS* fcs, Element* element);
 240   ~FGFilter();
 241
 242   bool Run (void);
 243
 244   /** When true, causes previous values to be set to current values. This
 245       is particularly useful for first pass. */
 246   bool Initialize;
 247   void ResetPastStates(void) {Input = 0.0; Initialize = true;}
 248
 249   enum {eLag, eLeadLag, eOrder2, eWashout, eIntegrator, eUnknown} FilterType;
 250
 251 private:
 252   double dt;
 253   double ca;
 254   double cb;
 255   double cc;
 256   double cd;
 257   double ce;
 258   double C[7]; // There are 6 coefficients, indexing is "1" based.
 259   double PropertySign[7];
 260   double PreviousInput1;
 261   double PreviousInput2;
 262   double PreviousOutput1;
 263   double PreviousOutput2;
 264   FGPropertyManager* Trigger;
 265   FGPropertyManager* PropertyNode[7];
 266   void CalculateDynamicFilters(void);
 267   void ReadFilterCoefficients(Element* el, int index);
 268   bool DynamicFilter;
 269   void Debug(int from);
 270 };
 271 }
 272 #endif
 273