Rrn-Time Models

Purpose

Allows a FLIGHTLAB model to be used in end-user applications without requiring the Scope development system.

Procedure

1. Requirements analysis
2. Specify FLIGHTLAB model data to be accessed by defining Scope variable lists
3. Define corresponding C data structures
4. Integrate application with FCM library
5. Dump the model from FLIGHTLAB with FCMDUMP command
6. Load model into C application at runtime

Improvements over CTRAN

• New since FLIGHTLAB 2.9.2
• Can instantiate more than one model in a process
• No need to recompile user application when model changes
• Single self-contained data file
• Component library is dynamically loaded
• Run-time version checking against individual methods
• Extensible file format

Scope API -- Dumping a model

1. Load model
2. Set initial conditions, trim, etc.
3. Set up and declare variable lists
4. Run FCMDUMP("filename.fcm")

Scope API -- Example

// Load model:
exec("$FL_DIR/flme/models/articulated/arti-rgd-3iv-qs.def",1);

// Set initial conditions:
world_model_airframe_cpg_testcond_veq = 20;
exec("xatestcond.exc",1);
exec("xamodeltrim.exc",1);

// Set up and declare variable lists:
pushg(world_model_airframe_cpg_xaout)
    varlist @STATES "Position, orientation, and velocity" =  ..
       posxi,posyi,poszi, vxb,vyb,vzb, phi,theta,psi ;
popg;
fcmdump(@states);

// Dump model:
fcmdump("articulated.fcm");

C API -- Overview

• Compile-time components:
  • #include "fcm.h" in C source files
  • Link with -lfcm ($FL_DIR/lib$FL_MACHTYPE/libfcm.a)
• Run-time components:
  • model.fcm model data file -- generated by Scope FCMDUMP command
  • flcomp.so component library -- included with FLIGHTLAB

C API -- Data Types

• FCM_FILE: master handle;
• FCM_MODEL: model instance handle;
  contains complete state of a model instance
• FCM_OPERATION: operation handle;
  used to invoke computations
• FCM_VARLIST: variable list handle;
  used to access structured data
• FCM_FIELD: field handle;
  used to access individual model variables

C API -- Initialization

• Call fcm_open to obtain an FCM_FILE handle
• Obtain other handles from the FCM_FILE:
  • variable lists
  • operations
  • fields
• Call fcm_create to create an FCM_MODEL instance
• Other operations performed on the FCM_MODEL(s)
• fcm_destroy() to destroy an FCM_MODEL instance
• fcm_close() to free all resources associated with an FCM_FILE
• All FCM_MODELs created from the same FCM_FILE can use the same operation and variable list handles

C API -- Operations

• Obtain operation handle:
  FCM_OPERATION op_handle = fcm_lookup_operation(fcm, "opname")
• Call operation:
  fcm_invoke(model_handle,op_handle)
• model_handle: model instance handle obtained from fcm_create()

C API -- Variable lists

• Obtain variable list handle:
  FCM_VARLIST vl_handle = fcm_lookup_varlist(fcm, "@name")
• Read model data:
  fcm_fetch(model_handle, vl_handle, buf, len)
• Write model data:
  fcm_store(model_handle, vl_handle, buf, len)
• buf: pointer to array of len doubles
• model_handle: model instance handle obtained from fcm_create()
• Alternate routines:
  fcm_read(model, vl_handle, &structvar, size) fcm_write(model, vl_handle,&structvar, size)

C API -- Checkpoint and Restore

• Save model test conditions at a checkpoint:
  fcm_checkpoint(model_handle, filename)
• Restore model test conditions:
  fcm_restore(model_handle, filename)
• Reload a model:
  fcm_reload(model_handle)

C API -- Example

#include "fcm.h"
... /* Initialization: */
FCM_FILE       fcm        = fcm_open("articulated.fcm");
FCM_OPERATION  op_step    = fcm_lookup_operation(fcm,"STEP");
FCM_VARLIST    vl_states  = fcm_lookup_varlist(fcm,"@STATES");
FCM_MODEL      model      = fcm_create(fcm);
double         state_buf[N_STATES];
... /* Run-time, once per frame: */
fcm_invoke(model, op_step);
fcm_fetch(model, vl_states, state_buf, N_STATES);
... /* Cleanup: */
fcm_close(fcm);

Error reporting

• Most FCM routines return NULL on failure
• const char *fcm_error_message() - returns a textual description of the most recent error

• FCM_FILE fcm = fcm_open(filename);
  if (fcm == NULL)
      fprintf(stderr, "FCM error: %s\n", fcm_error_message());

• fcm_error_code() returns a numeric code:
  • FCM_ERR_FORMAT - file format error
  • FCM_ERR_NOT_FOUND - object not found
  • ... others, see fcm.h for full list.

Locating the components library

1. Explicitly specified with fcm_load_components()
2. $FL_FCM_COMPONENTS environment variable
3. flcomp.so in current working directory

Note: fcm_load_components(NULL); called automatically by libflcomms when needed

Thread-safety issues

• Thread-unsafe functions:
  • fcm_open()
  • fcm_create()
  • fcm_load_components()
  • Anything which obtains a handle
  • Error reporting routines
• Only one thread may access an FCM_MODEL at a time

Thread-safety -- suggested policy

• Open FCM file(s), create model instance(s), and obtain handles in a master thread
• Assign each FCM_MODEL to a single subthread
• Alternately, use mutexes to protect FCM_FILE and FCM_MODEL handles between threads

Conclusion

• Questions?