Diagrams are not Models

A common misconception often held by new CertSAFE users is that a diagram by itself is a model of a system. In CertSAFE, a .cxdiag file does not give you enough information to form a model of a system’s behavior. For one, the diagram may reference other unit types and data types, and the files for all of these referenced resources (and any resources they reference, transitively) are needed to provide an accurate simulation.

Another point is that a diagram may be intended to represent only a subsystem or reusable component rather than a top-level system. CertSAFE does not distinguish these cases in the software. Setting a diagram or stitch as your current root means that you are treating that definition as the top level that you are interested in—a system unto its own, regardless of whether it was written with the intention to be thought of as a subsystem of a larger whole.

Most important, though, is the distinction between definitions and instantiated roots. Even if you have all of the files referenced directly or indirectly from the definitions you are interested in, you do not have a simulatable model until you choose a root and CertSAFE builds an instance hierarchy from that definition and all of its children. This is visible in many aspects of CertSAFE’s design, starting with the definition/instance mode distinction.

A diagram or stitch definition only has references to other definitions. These definitions can in turn have references to still other definitions, and a definition can have multiple other definitions that reference it. Instances, on the other hand, form a hierarchy with a clear parent/child relationship and root. There is no such thing as a singular “parent diagram” or “parent stitch” of a unit type definition—multiple different parents can have references to a unit type.


The image above shows a graphical representation of a simple project. Each box represents a unit type definition. For example, “V”, “W”, “X”, “Y”, and “Z” might be the names of diagram files in the project. Each arrow indicates a child reference. The start of an arrow indicates the definition containing the reference, the end of an arrow indicates the definition being referenced, and the label indicates the child name as it would be entered in the CertSAFE GUI. Notice how multiple definitions can have a unit of type Z as a child, and a single definition can contain multiple units of type Z.

Suppose in the project shown above you were to select W as your root in the CertSAFE interface. CertSAFE will automatically construct an instance tree from the definitions in the project like this:


This is the same structure that can be navigated using the Instance view and breadcrumbs bar in the CertSAFE GUI, just laid out in a two-dimensional format. As with instance paths in CertSAFE, the hollow square symbol indicates the instance root, and the right-pointing arrow symbol is a path separator indicating that the right-hand side is a child of the left-hand side. A colon means that the type of the object on the left is the type on the right. So, all together, the notation “□ ▶ Child 2 ▶ Child 1 : Z” can be read as “the unit named ‘Child 1’, which is in the unit named ‘Child 2’, which is in the current root, is of type Z.”

Because there are multiple references to the definition Z reachable from the selected root, the instance hierarchy contains multiple units of type Z. When viewing the diagram Z in instance mode in CertSAFE, the drop-down on the right-hand side of the breadcrumbs bar will list all three instances and let you switch between them.