A Few “Best Practices”

By paul ~ April 20th, 2006. Filed under: Best Practices, Tips & Tricks.

I wanted to share a few “Best Practices” that we’ve learned from our use of Foresight.  These are not hard-and-fast rules but, if followed, they can make life with large, complex models a lot easier.  Particularly in a team environment.

Divide System into SubSystems For Team Modeling. It is very difficult for multiple people to work on a single subsystem.  For this reason, it is very helpful to divide the system up in such a way that each team member has their own subsystem to work in.  Each team member will create one or more reusables in their subsytem(s) that will be integrated into the overall system model.  When a system is divided in this matter, it is not uncommon to have a subsystem that produces and exports only one component that is used elsewhere in the system.  The system model may end up having many subsystems, but this does not cause problems either in performance for functionality for Foresight.

Use Configuration Management! Use a configuration management tool, such as CVS or ClearCase, to manage your model.  The benefit is that you’ll be able to easily track the activity on your model, go back to examine or use a previous version of a component, or even return to a complete previous configuration.  We recommend managing only the sources, not the binaries.  For Foresight subsystems, this means translating the database to ASCII and then committing the ASCII files.  Similarly, be sure to include external data dictionary files, external function source code and project files, channel configuration and monitor configuration files, foresight.ini,  parameter workbooks, etc.  It is important to manage all of the parts required to completely restore a configuration, if necessary.  Dependent files, such as binary subsystem database folders, object files, etc. take up a lot of space and can easily be reproduced from source.  Generally it is not necessary to manage them.  One thing to be careful of:  be sure to store the ASCII database files as “binary” as they cannot be safely merged!

In v5.3.3, the new xlate_fs.exe tool makes bulk translation of all subsytems to or from ASCII format a breeze.

Manage Your Data Dictionaries in External Text Files. In the v5.2.2 release, a significant capability was added to ease the management of hierarchical data dictionaries.  The problem that is faced with medium to large systems is managing data dictionary consistency across multiple subsystems.  The core facility that was added was the #include directive in external data dictionary files.  This is documented in sections 1.2 and 1.3 of the v5.2.2 release notes.  The release notes also provide some guidance for effectively using the facility.  Here are some keys to effective data dictionary management:

  • Define each type in only one file, then include that file wherever needed.
  • Divide types into those required to USE a subsystem (parameter and I/O types) vs. those required internally, for implementation only.  The internal DDE file for the subsystem includes the external DDE file for the subsystem as well as the external DDE files for any subsytems who’s components it uses.
  • Put types used across the system in central files that are included everywhere they are needed.
  • Organize the type and constant definitions in the DDE files in a manner that aids in understanding them.  Use line comments (lines beginning with ‘#’) to document the sections of the file.
  • Put comments on each data dictionary entry in the file (surrounded by ‘*’) describing the use of the type and it’s units (where applicable.)  Start comments with a short mnemonic indicating the data dictionary it is defined in.  This makes it easy to find the definition when looking at the type declaration in Foresight.
  • When defining types, ONLY define them in the external files then import them where needed.  Do not define the types directly in Foresight using the Data Dictionary editor.

Currently, Foresight does not automatically recognize when a subsystem data dictionary is out of date with respect to the external source.  As a result, it is very important to manually re-import the data dictionary source for every affected subsystem after a change.  This is a deficiency which will be corrected in an upcoming Foresight release (I promise!)

The result of all of this is that importing the internal data dictionary file for a subsystem will import ALL types needed for that subsystem.  If each type is defined in only one place, consistency is preserved across the entire system model.

Manage Model Parameters in an Excel Workbook. Large models can have thousands of parameters.  Foresight’s ability to read configuration parameters from external files is helpful, but still cumbersome for very large sets.  We have had excellent success managing parameters in an Excel workbook which we locate in the model folder.  We usually dedicate a sheet to each reusable, or to a subsystem if the number of instances of reusables is small.  In a reusable sheet, we put the individual parameters in rows and instances of the reusable in columns.  Cells contain values for a parameter on a given instance.  Some simple VBA macros write the parameter values to appropriately formatted text files when the workbook is saved.

A further enhancement to this strategy adds an “ExperimentSetup” sheet to the workbook.  This sheet has a row for each parameter that is frequently changed or varied across simulations.  Each column represents a separate configuration that will be executed.  A simple macro executes the Foresight simulator in batch mode for each configuration.  (A new folder is created for each configuration containing parameter files and simulation output files.)  In this way, a complete series of simulations can be laid out and executed in batch mode.  This is very convenient when a number of parameters must be “swept” or sensitivity analysis is being performed.

In future posts, we’ll be sharing some examples with macros in place to aid those who aren’t conversant with VBA programming in Excel.

Click here for the post describing in detail how to accomplish this.

Leverage ACCESS and Excel for Data Analysis. Post-simulation data analysis and visualization is always a challenge.  The Foresight visualizer will only take you so far, and monitor files can be hard to parse.  We have taken to using the Foresight Minispec file I/O functions to writing our simulation data-of-interest directly to comma-delimited files (*.csv).  These can easily be imported into Excel or ACCESS for really powerful analysis.  Excel’s 16bit row limit makes it necessary to use ACCESS for larger jobs.  Getting proficient with query building and graphing in ACCESS can yield big dividends in creating reports that show just exactly what you need to communicate.

Go External! We’re referring to the External Function Call (EFCI) interface and Bridgeway.  I had a friend that used to say that “implementation makes a very good spec”, and it’s the truth.  It is often the case that a reference implementation for an algorithm or some other implementation is already available for important functionality in your model.  Or maybe you already have a model in another simulator.  Often it just does not make sense to model and validate these functions in Foresight when you could just connect them up.  Here are a few examples of things we’ve done with the EFCI and Bridgeway:

  • Connected voice recognition, voice synthesis and GPS navigation implementations to a voice-activated UI model for a truly interactive prototype of a telematics system.
  • Connected various reference algorithms for signal processing, random number generation, etc. for use within Foresight models.
  • Connected algorithm implementations for JPEG encoding to a Foresight control model.
  • Connected the Linux scheduler and DiffServ queuing discipline implementation (from the source distribution) for use in a Linux-based QOS performance model.
  • Implemented computationally intensive functions required by a model as external function calls in order to speed up the model.
  • Extended the Foresight Minispec language to provide “missing” functionality (such as converting strings to numbers and vice-versa, getting the length of a string, etc.).
  • Connected a MATLAB model of an algorithm for use in a system model.  (See the example in the whitepapers section of the Foresight web site.)
  • Connected a variety of other simulators to Foresight for co-simulation.

Both the EFCI and Bridgeway are amazingly easy to use once you get your feet wet, and they are very powerful.  Again, we’ll be providing examples as we go along here.

Use Alternatives to Bundle Flows. One use of the Alternative data type is to bundle flows that carry related information.  This is particularly useful in message-based systems where many different types of messages flow throughout the system.  Prior to v5.3.3, using Alternatives to bundle these together had usability and performance consequences.  The v5.3.3 release fixes these problems and makes it much easier to use Alternatives to help you organize your system.

In following posts, we’ll try to give more detail for each of these with examples and so-on.  So, keep tuning in, same bat-time, same bat-channel!  If you have an immediate need for further explanation of one or more of these, contact us directly and we’ll get it to you.

If you have some best practices to share, please take the time to add them to this post as comments!

Comments are closed.