FGFDMExec

class jsbsim.FGFDMExec

Encapsulates the JSBSim simulation executive.

This class is the executive class through which all other simulation classes are instantiated, initialized, and run. When integrated with FlightGear (or other flight simulator) this class is typically instantiated by an interface class on the simulator side.

At the time of simulation initialization, the interface class creates an instance of this executive class. The executive is subsequently directed to load the chosen aircraft specification file:

fdmex = new FGFDMExec( ... );
result = fdmex->LoadModel( ... );

When an aircraft model is loaded, the config file is parsed and for each of the sections of the config file (propulsion, flight control, etc.) the corresponding Load() method is called (e.g. FGFCS::Load()).

Subsequent to the creation of the executive and loading of the model, initialization is performed. Initialization involves copying control inputs into the appropriate JSBSim data storage locations, configuring it for the set of user supplied initial conditions, and then copying state variables from JSBSim. The state variables are used to drive the instrument displays and to place the vehicle model in world space for visual rendering:

copy_to_JSBsim(); // copy control inputs to JSBSim
fdmex->RunIC(); // loop JSBSim once w/o integrating
copy_from_JSBsim(); // update the bus

Once initialization is complete, cyclic execution proceeds:

copy_to_JSBsim(); // copy control inputs to JSBSim
fdmex->Run(); // execute JSBSim
copy_from_JSBsim(); // update the bus

JSBSim can be used in a standalone mode by creating a compact stub program that effectively performs the same progression of steps as outlined above for the integrated version, but with two exceptions. First, the copy_to_JSBSim() and copy_from_JSBSim() functions are not used because the control inputs are handled directly by the scripting facilities and outputs are handled by the output (data logging) class. Second, the name of a script file can be supplied to the stub program. Scripting (see FGScript) provides a way to supply command inputs to the simulation:

FDMExec = new JSBSim::FGFDMExec();
FDMExec->LoadScript( ScriptName ); // the script loads the aircraft and ICs
result = FDMExec->Run();
while (result) { // cyclic execution
  result = FDMExec->Run(); // execute JSBSim
}

The standalone mode has been useful for verifying changes before committing updates to the source code repository. It is also useful for running sets of tests that reveal some aspects of simulated aircraft performance, such as range, time-to-climb, takeoff distance, etc.

JSBSim Debugging Directives

This describes to any interested entity the debug level requested by setting the JSBSIM_DEBUG environment variable. The bitmasked value choices are as follows:

• unset: In this case (the default) JSBSim would only print out the normally expected messages, essentially echoing the config files as they are read. If the environment variable is not set, debug_lvl is set to 1 internally

• 0: This requests JSBSim not to output any messages whatsoever

• 1: This value explicity requests the normal JSBSim startup messages

• 2: This value asks for a message to be printed out when a class is instantiated

• 4: When this value is set, a message is displayed when a FGModel object executes its Run() method

• 8: When this value is set, various runtime state variables are printed out periodically

• 16: When set various parameters are sanity checked and a message is printed out when they go out of bounds

Properties

• simulator/do_trim (write only) Can be set to the integer equivalent to one of tLongitudinal (0), tFull (1), tGround (2), tPullup (3), tCustom (4), tTurn (5). Setting this to a legal value (such as by a script) causes a trim to be performed. This property actually maps toa function call of DoTrim().

check_incremental_hold() → None

Checks if required to hold afer increment.

disable_output() → None

Disables data logging to all outputs.

do_trim(mode: int) → None

Executes trimming in the selected mode.

Parameters:

mode – Specifies how to trim: * tLongitudinal=0 * tFull * tGround * tPullup * tCustom * tTurn * tNone

enable_increment_then_hold(time_steps: int) → None

Turn on hold after increment.

enable_output() → None

Enables data logging to all outputs.

get_aerodynamics() → FGAerodynamics

Returns the

get_aircraft() → FGAircraft

Returns the

get_aircraft_path() → str

Retrieves the aircraft path.

get_atmosphere() → FGAtmosphere

Note

This feature is not yet documented.

get_auxiliary() → FGAuxiliary

Returns the

get_debug_level() → int

Retrieves the current debug level setting.

get_delta_t() → float

Returns the simulation delta T.

get_engine_path() → str

Retrieves the engine path.

get_full_aircraft_path() → str

Retrieves the full aircraft path name.

get_ground_reactions() → FGGroundReactions

Returns the

get_mass_balance() → FGMassBalance

Returns the

get_model_name() → str

Returns the model name.

get_output_filename(n: int) → str

Retrieves the current output filename.

Parameters:

n – index of file

Returns:

the name of the output file for the output specified by the flight model. If none is specified, the empty string is returned.

get_output_path() → str

Retrieves the path to the output files.

get_propagate() → FGPropagate

Returns the

get_property_catalog() → list[str]

Retrieves the property catalog as a list.

get_property_manager() → FGPropertyManager

Returns a pointer to the property manager object.

get_property_value(name: str) → float

Retrieves the value of a property.

Parameters:

property – the name of the property

Returns:

the value of the specified property

get_propulsion() → FGPropulsion

Returns the

get_propulsion_tank_report() → str

Note

This feature is not yet documented.

get_root_dir() → str

Retrieve the Root Directory.

Returns:

the path to the root (base) JSBSim directory.

get_sim_time() → float

Returns the cumulative simulation time in seconds.

get_systems_path() → str

Retrieves the systems path.

get_trim_status() → bool

Note

This feature is not yet documented.

hold() → None

Pauses execution by preventing time from incrementing.

holding() → bool

Returns true if the simulation is Holding (i.e. simulation time is not moving).

incr_time() → float

Increments the simulation time if not in Holding mode.

The Frame counter is also incremented.

Returns:

the new simulation time.

integration_suspended() → bool

Returns the simulation suspension state.

Returns:

true if suspended, false if executing

load_model(model: str, add_model_to_path: bool = True) → bool

Loads an aircraft model.

The paths to the aircraft and engine config file directories must be set prior to calling this. See below.

Parameters:

• model – the name of the aircraft model itself. This file will be looked for in the directory specified in the AircraftPath variable, and in turn under the directory with the same name as the model. For instance: “aircraft/x15/x15.xml”

• addModelToPath – set to true to add the model name to the AircraftPath, defaults to true

Returns:

true if successful

load_model_with_paths(model: str, aircraft_path: str, engine_path: str, systems_path: str, add_model_to_path: bool = True) → bool

Loads an aircraft model.

Parameters:

• AircraftPath – path to the aircraft/ directory. For instance: “aircraft”. Under aircraft, then, would be directories for various modeled aircraft such as C172/, x15/, etc.

• EnginePath – path to the directory under which engine config files are kept, for instance “engine”

• SystemsPath – path to the directory under which systems config files are kept, for instance “systems”

• model – the name of the aircraft model itself. This file will be looked for in the directory specified in the AircraftPath variable, and in turn under the directory with the same name as the model. For instance: “aircraft/x15/x15.xml”

• addModelToPath – set to true to add the model name to the AircraftPath, defaults to true

Returns:

true if successful

load_planet(planet_path: str, useAircraftPath: bool) → bool

Loads the planet.

Loads the definition of the planet on which the vehicle will evolve such as its radius, gravity or its atmosphere characteristics.

Parameters:

• PlanetPath – The name of a planet definition file

• useAircraftPath – true if path is given relative to the aircraft path.

Returns:

true if successful

load_script(script: str, delta_t: float = 0.0, initfile: str = '') → bool

Load a script.

Parameters:

• Script – The full path name and file name for the script to be loaded.

• deltaT – The simulation integration step size, if given. If no value is supplied then 0.0 is used and the value is expected to be supplied in the script file itself.

• initfile – The initialization file that will override the initialization file specified in the script file. If no file name is given on the command line, the file specified in the script will be used. If an initialization file is not given in either place, an error will result.

Returns:

true if successfully loads; false otherwise.

print_property_catalog() → None

Note

This feature is not yet documented.

print_simulation_configuration() → None

Note

This feature is not yet documented.

query_property_catalog(check: str) → str

Retrieves property or properties matching the supplied string.

A string is returned that contains a carriage return delimited list of all strings in the property catalog that matches the supplied check string.

Parameters:

• check – The string to search for in the property catalog.

• end_of_line – End of line (CR+LF if needed for Windows).

Returns:

the carriage-return-delimited string containing all matching strings in the catalog.

reset_to_initial_conditions(mode: int) → None

Resets the initial conditions object and prepares the simulation to run again.

If the mode’s first bit is set the output instances will take special actions such as closing the current output file and open a new one with a different name. If the second bit is set then RunIC() won’t be executed, leaving it to the caller to call RunIC(), e.g. in case the caller wants to set some other state like control surface deflections which would’ve been reset.

Parameters:

mode – Sets the reset mode.

resume() → None

Resumes execution from a “Hold”.

resume_integration() → None

Resumes the simulation by resetting delta T to the correct value.

run() → bool

This function executes each scheduled model in succession.

Returns:

true if successful, false if sim should be ended

run_ic() → bool

Initializes the sim from the initial condition object and executes each scheduled model without integrating i.e.

dt=0.

Returns:

true if successful

set_aircraft_path(path: str) → bool

Set the path to the aircraft config file directories.

Under this path, then, would be directories for various modeled aircraft such as C172/, x15/, etc. Relative paths are taken from the root directory.

Parameters:

path – path to the aircraft directory, for instance “aircraft”.

set_debug_level(level: int) → None

Sets the debug level.

set_dt(dt: float) → None

Sets the integration time step for the simulation executive.

Parameters:

delta_t – the time step in seconds.

set_engine_path(path: str) → bool

Set the path to the engine config file directories.

Relative paths are taken from the root directory.

Parameters:

path – path to the directory under which engine config files are kept, for instance “engine”.

set_logging_rate(rate: float) → None

Sets the logging rate in Hz for all output objects (if any).

set_output_directive(fname: str) → bool

Sets the output (logging) mechanism for this run.

Calling this function passes the name of an output directives file to the FGOutput object associated with this run. The call to this function should be made prior to loading an aircraft model. This call results in an FGOutput object being built as the first Output object in the FDMExec-managed list of Output objects that may be created for an aircraft model. If this call is made after an aircraft model is loaded, there is no effect. Any Output objects added by the aircraft model itself (in an <output> element) will be added after this one. Care should be taken not to refer to the same file name. An output directives file contains an <output> </output> element, within which should be specified the parameters or parameter groups that should be logged.

Parameters:

fname – the filename of an output directives file.

set_output_filename(n: int, fname: str) → bool

Sets (or overrides) the output filename.

Parameters:

• n – index of file

• fname – the name of the file to output data to

Returns:

true if successful, false if there is no output specified for the flight model

set_output_path(path: str) → bool

Set the directory where the output files will be written.

Relative paths are taken from the root directory.

Parameters:

path – path to the directory under which the output files will be written.

set_property_value(name: str, value: float) → None

Sets a property value.

Parameters:

• property – the property to be set

• value – the value to set the property to

set_root_dir(path: str) → None

Set the root directory that is used to obtain absolute paths from relative paths.

Aircraft, engine, systems and output paths are not updated by this method. You must call each methods ( SetAircraftPath(), SetEnginePath(), etc.) individually if you need to update these paths as well.

Parameters:

rootDir – the path to the root directory.

set_sim_time(time: float) → bool

Sets the current sim time.

Parameters:

cur_time – the current time

Returns:

the current simulation time.

set_systems_path(path: str) → bool

Set the path to the systems config file directories.

Relative paths are taken from the root directory.

Parameters:

path – path to the directory under which systems config files are kept, for instance “systems”

set_trim_status(status: bool) → None

Note

This feature is not yet documented.

suspend_integration() → None

Suspends the simulation and sets the delta T to zero.