Distributed MBD Projects, Part 12: Location Independence

This is the next in a series of posts MBD projects that are distributed across multiple managerial domains.

Location Independence

This article is part of a series, but it is also closely related to my earlier post on Component Reuse.

When developing components for inclusion in another group’s simulation, the components must be developed with complete location independence. For this article, I’ll define location independence as “The ability to operate a component in any location”. This includes:

Operating on a computer other than the computer on which the component was developed.
Operating in another company.
Operating from any subdirectory on the host machine.
Operating on any OS supported by the simulation tools.
No dependence on a particular configuration of the host computer.

Resource Location

The most common location independence error is hard-coded file system paths to resources, which are basically any files that a component needs in order to operate. The nature and type of these files are as varied as the engineers that create the components, but most of them fall into one or more of these categories:

Models,
Initialization scripts,
Libraries,
Data files, and
Configuration files.

A fully qualified path such as C:\Users\IsadorraJarr\MotorModel will almost certainly fail when moved to another computer, because the indicated path probably won’t exist there.

Relative path names don’t necessarily work either, because it could reference a resource that is not included in the delivered component. For example, consider an engineer, Tad Pohl, who is developing a satellite attitude control model for delivery to another company, and he is using this directory structure:

Suppose Tad’s got an awesome utility, myIngeniousScript.sh, located in the Utilities directory that he uses in all of his models. In this case, his attitude control model will reference the ../../Utilities/myIngeniousScript.sh script. If Tad delivers only the AttitudeControl directory, the reference will be broken.

Tad could also deliver his Utilities directory with instructions to include it in the search path, but this is a bad idea for reasons that I discuss below under Packaging a Component.

The best approach to addressing this issue is to:

Contain the component completely within one directory and its subdirectories,
Use only relative paths, and
Make sure the relative paths do not reference any files outside of the component’s directory structure.

Operating System Dependencies

Ideally, a delivered component will not have any dependencies on a host operating system. The simplest ones to manage are:

File path separators (“/” vs “\“). In most situations, a component can use “/” for file path separators because Windows is tolerant of this separator. For situations in which this doesn’t work, most programming environments provide an easy way to discover it (“filesep” in Matlab).
Search path separators (“;” vs “:“). Most simulation components will not be building search paths, but for those that do, most programming environments readily provide it (“pathsep” in Matlab).
Line separators (“\r\n” vs “\n“). This is usually not a problem because most I/O frameworks provide a mechanism to read a file line-by-line that is tolerant of differing line endings, such as the ubiquitous variants of C’s scanf(...) function or Matlab’s fgetl(...) function.

As the above descriptions show, resolving a single operating system dependency is rather easy. However, discovering all such dependencies can be tricky. The best approach is to consistently use the techniques described above when building simulation components.

Another OS dependency is the language used in supporting scripts. Components built for re-use should avoid using OS-specific scripts such as Bourne shell scripts or batch files. This is usually not a problem for simulations because most simulation engines provide their own proprietary OS-independent scripting capability, such as Matlab’s .m files.

Instead of building components that are independent of any OS, your team can decide to standardize on a particular OS. I was on a team that did this on a Distributed MBD project, and it worked out okay. We were providing Independent Verification and Validation (IV&V) of a sensor’s flight software. The flight software itself made many Linux-specific calls and was dependent on Linux shell scripts, so we had no choice but to standardize on Linux. This didn’t cause any significant problems on the project, but most of what we produced could not be used on other OSs.

Host Configuration

A component that is location independent should not rely on any particular configuration of the host computer. Examples include:

Location-independent components should not expect any environment variable to be set (other than those automatically set by the OS). For example, a component might require a DATA_FILES environment variable to be set to point to the directory containing the component’s data files. Unless that environment variable is properly set on the host computer, this technique will not work. Environment variables that point to a location on disk can be replaced with relative path names as described above. Environment variables that specify values for a component can be replaced with configuration facilities in the simulation environment.
Components should not require that any third-party software be pre-installed on the host computer, except perhaps the simulation tools. Ideally, any supporting software should be included with the component, and should not require any installation procedure.

Packaging a Component

Although not a location independence issue, packaging a component is a closely related issue. On more than one Distributed MBD project, I received components with instruction such as:

Set an environment variable to a certain value,
Install third-party software before running the simulation, or
Add a set of utilities to the Matlab path.

These techniques can work, and can even allow a component to run in a new environment, but too often it requires a Vulcan mind-meld with the components. I strongly recommend that this not be allowed on your project:

When integrating components from different groups, there are many opportunities for errors. The setup procedures should not add to it.
Any one of the above instructions by itself might not be too onerous, but managing these issues across an entire project is problematic. My experience indicates that these types of setups are a source of frequent and recurring errors, simply because there are so many ways it can go wrong.
As the project evolves over time, so will these setup instructions. Managing these changes, and understanding when to apply them, is very error prone. Error messages resulting from these issues often don’t provide any indication about what’s wrong and how to resolve it. Often, the resolution involves another round of delivery from the offending component.
Managing these setup instructions across multiple components from different organizations can be a significant juggling act for the team that is integrating the simulation.
When moving the simulation to a new machine, getting the correct setup for all of the components is time consuming and error-prone.
Anybody needing simulation results must wait while diagnosing and repairing these issues.
Most simulations evolve spirally, and these delays slow down the feedback that is critical for spiral development.

My experience strongly suggests that each and every component be completely self-contained. Distributed MBD projects that push any problems downstream to the integration phase progress much more slowly, because diagnosing a problem across multiple organizations is inherently slow and frustrating.

SystemBlend™

SystemBlend™ works entirely within the simulation engine, so it inherits its location independence from the simulation engine. Currently, SystemBlend™ only supports the Matlab/Simulink engine, so SystemBlend™ is location-independent*.

Because SystemBlend™ operates within Simulink, there is no opportunity for a component to run an OS-specific script prior to integration. This addresses the issue of OS-specific scripts, but it does limit what a component can do for setup. This is not a problem for ordinary Simulink development because a typical component uses the Matlab environment for setup.

A developer might want to re-use a component from a different project, where the component requires OS-specific scripts. Although I have never encountered this in my career, it is a possibility. The workflow in SystemBlend™ requires that this be resolved by the component developer, instead of pushing the issue downstream to the integration phase.

Other Articles in this Series:

Footnotes:

* The SystemBlend™ software itself has been carefully designed, implemented, and tested for location-independence.

Note: This post has been updated with links to other posts in the series