FGInitialConditions

The class FGState provides for initialization of JSBSim's main loop and the arguments it requires are quite fundamental to its operation but not necessarily familiar to most. The prototype is:

void FGState::Initialize( float U,
                          float V,
                          float W,
                          float phi,
                          float tht,
                          float psi,
                          float Latitude,
                          float Longitude,
                          float H          );

The body components of speed, U, V, and W, must be in feet per second, the Euler angles and position in radians, and altitude in feet. An example making use of this method can be found in Chapter 2. This method satisfies the needs of JSBSim well, however, the ability to initialize using more familiar quantities and units is needed.

The services provided by the class FGInitialCondition make this possible. It encapsulates the various calculations needed to reduce speed, attitude, and position from the descriptions which might be found on a typical flight deck to those required by FGState::Initialize(float ...), above. All of the supported services are detailed in the table below:

The units listed are those accepted as user input. See the header file for the units returned as output for each quantity.

Some logic is required in order to keep the internal data consistent and properly initialize the main loop. Interdepencies exist among airspeed, Mach number, altitude, and the aerodynamic angles primarily for two reasons. The first is the relationship of Mach number to temperature and true airspeed. The second is the relationship of the body speed components to true airspeed, angle of attack, and sideslip angle. The common thread here is true airspeed, so FGInitialCondition calculates true airspeed when any other speed or Mach number is set and vice versa, calculates the remaining speeds and Mach number if true airspeed is set. If any of the body components are set, angle of attack, sideslip angle, all speeds, and Mach number are recalculated. In order to allow for setting altitude after speed, FGInitialCondition remembers which speed is set so that all the remaining speeds can be recalculated once altitude is set. Note that while FGInitialCondition internally prioritizes true airspeed, speed in the main loop must be initialized using the body components. These are calculated using true airspeed, angle of attack, and sideslip angle on demand.

Another set of dependencies that must be maintained are the relationships that exist between longitudinal flight path angle, pitch angle, and angle of attack. In order to maintain these relationships, the assumption of zero pitch rate is made so that the pitch angle can be computed as the sum of the flight path angle and angle of attack. The side-effects of setting each angle are detailed in the table above. The restriction the zero pitch rate assumption places on the use of FGInitialCondition is one the user should consider carefully. It is not possible, for example, to use this class to set up for a trim in a steady pull-up.

This class is a support class and, as such, is not scheduled by the executive to run every frame. It does, however, require the services of the atmosphere model built into JSBSim so a valid object of FGFDMExec is required by its constructor. The snippet below provides an example of its usage.

...
#include "FGInitialCondition.h"
...
// create an object of the executive and load a model
// See the example in Chapter 2 
...
// now create an object of FGInitialCondition 
FGInitialCondition *fgic = new FGIntialCondition(FDMExec);
fgic->SetVcalibratedKtsIC(100);
fgic->SetAltitudeFtIC(1000);

// IMPORTANT - loop the sim with the new values 
FDMExec->RunIC(fgic);
// time does not pass and no integration is performed when 
// using RunIC()

// trim the model if desired 
...
// the FGInitialCondition object is no longer needed 
delete fgic;

while(FDMExec->GetState()-Getsim_time() < 10.0) {
...
FDMExec->Run();
...
}

One further point needs to be made. While FGInitialCondtion does make it possible to initialize the sim using convenient quantities it does not, in any way, attempt to assure that the entire sim is consistent with those initial conditions. The nature of simulations is such that dynamics will result and the model will quickly go off condition if integration is begun immediately after setting the initial conditions unless the user is very clever about choosing both the initial conditions and the positions of the appropriate flight controls. If the user requires the sim to stay on condition once it begins integrating, then a steady flight condition needs to be chosen and the trimming routine used in conjunction with this class.