Project End of Life
From a technical point of view, terminating an MBD project is quite easy: Archive your work and stop working on it. Instead, this article discusses how to shut down a project so that:
- It can be re-started later
- Elements from it can be re-used in other projects
These topics are important because, in my experience, most MBD projects will have components that need to be re-used on other projects, or might even need to be fully revived at a later date.
Whenever I’ve tried re-using simulation elements, nearly all the difficulties were because the engineers inheriting the work did not have a sufficient understanding of the earlier work*. While working on these projects, I noticed that all of the difficulties were examples of just a few issues:
- Execution environment,
- Documentation, and
- Context.
The issue of re-using a terminated project is magnified for a Distributed MBD project. The knowledge base behind the project is scattered across multiple organizations, making it dramatically more difficult to capture the information needed to revive the work.
Execution Environment
An MBD execution environment includes:
- Name, location, format, and content of data files,
- Names, location, and values of parameters,
- Layout of data structures,
- Name and location of libraries,
- Simulator configuration, and
- Simulator version.
The above list is only the most commonly encountered elements of the execution environment. Almost every project has its own peculiarities, so an exhaustive list is not possible.
When a Distributed MBD project is started from scratch, the execution environment evolves with the project. With each iteration of the simulation, a few elements of the environment are updated, such as creating a new data structure or adding a field to an existing data structure, adding a data file, tweaking the configuration, etc. This is manageable because the participating groups develop the execution environment in small increments with each iteration of the simulation.
On the other hand, reviving a Distributed MBD project can be extremely challenging without the proper tools. When pulling the mothballed project from archives, many elements of the project will be broken. You are guaranteed to encounter at least one of many problems, including:
- Scripts often rely on hard-coded file locations, which will probably no longer be valid.
- Archived search paths (such as Matlab’s search path or Matlab’s Java class path) will point to locations that are no longer valid.
- The system search path will be different.
- Huge data files might not have been included in the archive.
- The steps to run the simulation might be forgotten.
- Compiler options are not known.
Again, the above list is not complete. Each project will have its own peculiarities.
Many of the problems encountered in reviving a project or a component will have an obvious solution once they are encountered, so most of the effort to resuscitate a project will be something like:
This leaves a few intractable problems. (I suppose a revival effort could encounter no such problem, but I’ve never been so lucky.) The exact nature of these problems will vary widely, depending on factors such as the purpose of the original project and the personalities of the engineers who developed it.
As an example, consider this scenario:
a. A component needs a binary data file with a custom format,
b. The data file is missing,
c. The data file is written and read by a compiled library, and
d. The library source code is held by a group that is not participating in the new effort.
In these hard-nut cases, the solution might be to excise whatever part of the simulation is causing problems and re-build it from scratch.
Regardless of how these problems are resolved, they could have been avoided if the previous work had been handled properly at project termination.
Documentation
Most of the problems described above can be mitigated or eliminated by properly documenting the original project, and including the documentation in the archive. With appropriate documentation, the team rebuilding the project would know how to avoid most of the problems, and would know how to handle the remaining problems.
Ideally, the project details would be documented as they are included in the project, so that this documentation would evolve as the project progresses. However, this doesn’t always work:
- Some projects do not have a directive to maintain such documentation, so only the most conscientious engineers will have any documentation.
- Some projects require thorough documentation, but engineers typically don’t like to write documentation. Often the documentation is only enough to check off the "documentation" requirement, and is not sufficient to revive the project.
- At project termination, upper management typically will not worry about the downstream problems when terminating a project, so there will be no budget or time to spend on documentation during project shut-down.
If the documentation exists, it would ideally be step-by-step instructions on how to rebuild the original project from scratch. However, even this is not perfect:
- It is easy to overlook an arcane, but critical, part of the process when documenting it.
- Engineers, and natural language, can be imprecise when writing technical instructions.
- Performing all of the steps can be time consuming.
Documenting a Distributed MBD project is more challenging than documenting an MBD project within one group:
- The policies and procedures of the different groups might produce a mish-mash of documentation that does not hang together
- Project shutdown often means terminating subcontracts, so some groups might not have full enthusiasm when documenting their work.
- Some groups might use documentation as hostage. If they don’t document their work, they are more likely to be called back for more work if it is ever revived
Context
In understanding any technical issue, simply understanding the context of the problem is the majority of trying to solve the problem. This is true at a macro level and a micro level.
- If your team is building an attitude control system, knowing whether it is for a spacecraft, a drone, or a mobile gun tells them a lot about how the attitude control system will work.
- If an engineer is building a filter for a gyro, knowing the gyro’s noise characteristics and the format of the gyro output tells him or her a lot about how the filter should work.
- If your team is designing a new component for inclusion into your project, they will use knowledge about the other components in the system to refine the design details.
In addition, technical elements such as simulation components need an appropriate context:
- They need the proper execution environment, as described above, and
- Their interfaces must be connected to the appropriate components to provide the correct inputs and to send the outputs to the appropriate destination.
SystemBlend™
A Distributed MBD project developed in the SystemBlend™ environment will always be packaged in a way that can be readily revived.
In the file-based variant of SystemBlend™, the design database and the components are packaged into stand-alone files. To mothball a project in this variant, your team needs to gather the working directory for the SystemDesigner application, and the packaged components, and perhaps bundle them into a .zip file.
In the client/server variant of SystemBlend™, everything needed for the project, except for Simulink itself, is stored in the server:
When you mothball a project one of these ways (depending on the variant), the full execution environment and context are saved.
Execution Environment
Because SystemBlend™ carefully controls the execution environment for the simulation, a SystemBlend™ project always has its execution environment fully, completely, and precisely defined, even in a mothballed state. When reviving a project from its mothballed state, the only setup is to ensure an appropriate version of Simulink is installed on the machines running the ComponentGuide and IntegrationMaster desktop applications.
For the file-based variant of SystemBlend™, reviving a project consists of:
- Installing SystemBlend™, if needed,
- Ensuring Simulink is installed on the machines running ComponentGuide and IntegrationMaster,
- Copying the packaged component file to the machines running IntegrationMaster, and
- Reviving the working directory on the machine running SystemDesigner.
For the client/server variant of SystemBlend™, reviving a project consists of:
- Restoring the project to the server, if needed,
- Installing the SystemBlend™ desktop applications, if needed, and
- Installing Simulink on the machines running ComponentGuide and IntegrationMaster.
Once revived, SystemBlend™ will ensure that the components and simulation are ready to run with no further setup.
Documentation
A SystemBlend™ design is largely self-documenting, due to the graphical nature of the design capture in the SystemDesigner desktop application:
When a SystemBlend™ project is resurrected from its mothballed state, the full graphical state is also resurrected, providing ready documentation of the restarted project.
Context
SystemBlend™ always provides the context of a project, at the system level and at the component level, even for a revived project.
The graphical design of SystemBlend™ provides context to engineers to help understand the project. By exploring the design graphically, and engineer can quickly gain an understanding of the architecture and the interactions between the components.
SystemBlend™ always has the technical context of a project, at the system level and at the component level, even when reviving it from an archived state. This ensures the system will be ready to run once it has been revived, without further setup.
When terminating a SystemBlend™ project, archiving it so that it can be readily revived in the future is very straight-forward. This will capture the full project, so engineers can rapidly gain understanding of the project, and can have the simulation running again with minimal effort.
Other Articles in this Series:
- Part 1: Project Launch
- Part 2: Updating Components
- Part 3: Adding Components
- Part 4: Splitting Components
- Part 5: Replacing Components
- Part 6: Component Delivery
- Part 7: Imprecise ICDs
- Part 8: Misinterpreted ICDs
- Part 9: Naming Collisions
- Part 10: Simulation Parameters
- Part 11: Simulator Configuration
- Part 12: Location Independence
- Part 13: Shared Parameters
- Part 14: Data Capture
- Part 15: Architecture Updates
- Part 16: Deprecating Components
- Part 17: Project End-of-Life
Footnotes: