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