Organizing your models

Packages are the principal mechanism for organizing models. In fact, a model is just a kind of package in the underlying SysML metamodel. Different models used for different purposes are likely to be organized in different ways. This recipe focuses on systems’ engineering models to specifically support requirements capture, use case and requirements analysis, architectural trade studies, architectural design, and the hand-off of relevant Systems Model data to the subsystem teams. In this recipe, we create not only the systems model but also the federation of models used in systems engineering. Federations, in this context, are sets of interconnected models with well-defined usage patterns defined.

Purpose

Organizing well is surprisingly important. The reasons why include:

• Grouping information to facilitate access and use
• Supporting concurrent model use by different team members performing different tasks
• Serving as the basis for configuration management
• Allowing for relevant portions of models to be effectively reused
• Supporting team collaboration on common model elements
• Allowing for the independent building, simulation, and verification of model aspects

Inputs and preconditions

The product vision and purpose are the primary input for the systems engineering model. The hand-off model is created after the architecture is stable for the iteration and is the primary input for the subsequent Shared Model and Subsystem Models.

Outputs and postconditions

The outputs are the shells of the Systems, Shared, and Subsystem Models, a federation of models for downstream engineering The Systems Model is populated with the system requirements, if they exist. The Shared Model is initially populated with (references to) the system requirements, (logical) system interfaces and (logical) data schema from the Systems Model. A separate Subsystem Model is created for each subsystem and is initially populated with a reference to its subsystem requirements from the Systems Model, and the physical interfaces and data schema from the Shared Model.

How to do it

Figure 1.37 is the workflow for creating and organizing the Systems Model. In the end you’ll have logical places for the MBSE work, and your team will be able to work more or less independently on their portions of the effort:

Figure 1.37: Organizing the systems engineering model

Review product vision, scope, and intent

Every product has a vision that includes its scope and intent. Similarly, every model you create has a scope, purpose, and level of precision. A model’s scope determines what goes into the model and what is outside of it. A common early failure of modeling happens when you don’t have a well-defined purpose for a model.

The purpose of the model is important because it determines the perspective of the model. George Box is famously attributed to the quote “All models are wrong, but some are useful.” What I believe this means is that every model is an abstraction of reality. A model fundamental represents information useful to the purpose of the model and ignores system properties that are not useful. The purpose of the model, therefore, determines what and how aspects of the product and its context will be represented.

The level of precision of the model is something often overlooked but is also important. It is too often that you will see requirements such as:

The aircraft will adjust the rudder control surface to ±30 degrees.

That’s fine as far as it goes, but what does it mean to achieve a value of +15 degrees? Are 14.5 degrees close enough? How about 14.9? 14.999? How quickly will the position of the rudder be adjusted? If it took a minute, would that be OK? Maybe 1.0 seconds? 100ms? The degree to which you care about how close is “close enough” is the precision of the model, and different needs have different levels of required precision. This is sometimes known as “model fidelity.” The bottom line is to know what you are modeling, why you are modeling it, and how close to reality you must come to achieve the desired value from your model. In this case, the model is of the requirements, their analyses, supporting analyses leading to additional requirements, and the architecture structure.

Create a new model

In whatever tool you use, create a blank, empty model.

Add the canonical system model structure

This is the key step for this recipe. The author has consulted for decades to literally hundreds of systems engineering projects, and the Subsystem Model organization shown in Figure 1.38 has emerged as a great starting point. You may well make modifications, but this structure is so common that I call it the system canonical organization.

It serves the purpose of MBSE well:

Figure 1.38: Systems model canonical structure

The main categories in Figure 1.38 are packages that will hold the modeled elements and data. The main packages are:

Model Overview Package – this package holds the model overview diagram, model summary information, and a glossary, if present.

Capabilities Package – holds all capability-related information, including requirements, use cases, and functional analyses.

Requirements Package – holds the requirements, either directly (most common) or as remote resources in the Jazz environment.

Use Case Package – holds the system use cases and use case diagrams.

Note that while this organization is labeled canonical, it is common to have minor variants on the structure.

Functional Analysis Package – holds the use case analyses, one (nested) package per use case analyzed. An example “template” package is shown with a typical structure for the analysis of a single use case.

Architecture Package – holds all design-related information for the Systems Model.

Architectural Analysis Package – hold architectural analyses, such as trade studies, usually in one nested package per analysis.

Architectural Design Package – holds the architectural design, the system and subsystem blocks, and their relations. Later in the process, it will hold the subsystem specifications, one (nested) package per subsystem.

Interfaces Package – holds the logical system and subsystem interfaces as well as the logical data schema for data and flows passed via those interfaces. Logical interfaces are discussed in more detail in Chapter 2, System Specification: Functional, Safety, and Security Analysis.

Add systems requirements, if they exist

It is not uncommon that you’re handed an initial set of system requirements. If so, they can be imported or referenced. If they are added later, this is where they go.

Modify the model structure for special needs, if required

You may identify special tasks or model information that you need to account for, so it’s OK to add additional packages as needed.

Add a model overview diagram

I like every model to contain a Model Overview Diagram. This diagram is placed in the Model Overview package and serves as a brief introduction to the model’s purpose, content, and organization. It commonly has hyperlinks to tables and diagrams of particular interest. The lower left-hand corner of Figure 1.39 has a comment with hyperlinks to important diagrams and tables located throughout the model.

This aids model understanding and navigation, especially in large and complex models:

Figure 1.39: Example model overview diagram

After systems engineering work completes and the time comes to handoff to downstream engineering, more models must be created. In this case, the input is the Systems Model and the output is the Shared Model and a set of Subsystem Models. The Shared Model contains information common to more than one subsystem – specifically the physical system and subsystem interfaces and the corresponding physical data schema used by those interfaces. The details of elaborating those models are dealt with in some detail in Chapter 4, Handoff to Downstream Engineering, but their initial construction is shown in Figure 1.40:

Figure 1.40: Organizing the shared and subsystem models

Create the Shared Model

This task creates an empty shared model. This model will hold the information shared by more than one subsystem; that is, each subsystem model will have a reference to these common interfaces and data definitions and elements.

Apply the canonical shared model structure

Apply the canonical shared model structure

The purpose of the shared model is twofold. First, using the logical interfaces and data schema as a starting point, derive the physical interfaces and data schema, a topic of Chapter 4, Handoff to Downstream Engineering. Secondly, the Shared Model serves as a common repository for information shared by multiple subsystems.

The organization shown in Figure 1.41 does that:

Figure 1.41: Shared model canonical structure

The Requirements and Interfaces packages in Figure 1.41 reference the Systems Model packages of the same name. In this way, those elements are visible to support the work in the Shared Model. The Physical Interfaces package holds the physical interfaces and data schema to be used by the subsystems. The Common Elements package holds elements used in other places in the model or in multiple subsystems. The Common Stereotypes profile holds stereotypes either used in the Physical Interfaces package or created for multiple subsystems to use.

Add a reference to the system requirements

As shown above, the Requirements package of the systems model is referenced so that they are available to view but also so that the physical interfaces and data schema can trace to them, to provide a full traceability record.

Add references to the logical interfaces and data schema

The logical interfaces and related logical data schema specify the logical properties of those elements without specifying physical implementation details. The Creating the Logical data schema recipe from Chapter 2, System Specification: Functional, Safety, and Security Analysis, goes into the creation of those elements. By referencing these elements in the Shared Model, the engineer has visibility to them but can also create trace links from the physical interfaces and data schema to them.

Add model overview diagram

As in the systems model organization, every model should have a Model Overview diagram to serve as a table of contents and introduction to the model:

Figure 1.42: Example shared model overview diagram

Create the subsystem model

Commonly, each subsystem has its own interdisciplinary team, so the creation of a Subsystem Model per subsystem provides each team with a modeling workspace for their efforts.

Apply the canonical subsystem model organization

Figure 1.43 shows the canonical organization of a Subsystem Model. Remember, that each subsystem team has their own, with the same basic organization:

Figure 1.43: Subsystem model canonical structure

The Common Stereotypes and Physical Interfaces packages are referenced from the Shared Model, while the Requirements package is referenced from the Systems Model.

We would like to think that the requirements and use cases being handed down to the subsystem team are perfect; however, we would be wrong. First, there may be additional elaboration work necessary at the subsystem level to understand those subsystem requirements. Further, discipline-specific requirements must be derived from the subsystem requirement so that the electronics, mechanical, and software engineers clearly understand what they need to do. That work is held in the Subsystem Spec Package. If we create additional, more detailed use cases, they will be analyzed in the Functional Analysis Package in the same way that the system use cases are analyzed in the Systems Model.

The Deployment Architecture Package is where the identification of the facets and the allocation of responsibilities to the engineering disciplines takes place. To be clear, this package does not detail the internal structure of the facets; the electronics architecture, for example, is not depicted in this package, but the electronics facet as a black box entity is. Further, the interfaces between the electronics, software, and mechanical facets are detailed here as well.

Lastly, the SW Design Package is where the design and implementation of the software will be done. It is expected that the software will continue to work in the model but that the other facets will not. Alternatively, the software engineers can create their own separate model that references the subsystem model. For electronics and mechanical design, we expect that they will use their own separate tools and this model will serve only as a specification of what needs to be done in those facets. It is possible that the electronics design could be done here, using SysML or UML and then generating SystemC, for example, but that is fairly rare. SysML and UML are poorly suited to capture mechanical designs, as they don’t have any underlying metamodel for representing or visualizing geometry.

Copy the subsystem specification

The Subsystem Package is copied (rather than referenced) from the Systems Model. This model holds the subsystem details such as subsystem functions and use cases. Of course, the name of this package in Figure 1.43 is misleading; if the name of the subsystem was Avionics Subsystem, then the name of this package would be Avionics Subsystem Package or something similar.

In a practical sense, I prefer to copy the subsystem package from the Systems Model, because that isolates the Subsystem Model from subsequent changes to that package in the Systems Model that may take place in later iterations. The subsystem team may then explicitly re-import that changed Subsystem Model at times of its own choosing. If the subsystem package is added by reference, then whenever the systems team modifies it, the changes are reflected in the referencing Subsystem Model. This can also be handled by other means, such as referencing versions of the system model in the configuration management set, but I find this conceptually easier. However, if you prefer to have a reference rather than a copy, that’s an acceptable variation point in the recipe.

Add a reference to the subsystem requirements

The Requirements package in the Systems Model also holds the derived subsystem requirements (see Chapter 2, System Specification: Functional, Safety, and Security Analysis). Thus, referencing the Requirements package from the system model allows easy access to those requirements.

Add a reference to the physical interfaces and data schema

Logical interfaces serve the needs of systems engineering well, for the most part. However, since the subsystem team is developing the physical subsystem, they need to know the actual bit-level details of how to communicate with the actors and other subsystems, so they must reference the physical interfaces from the Shared Model.

Add model overview diagram

As before, each model should have a Model Overview diagram to serve as a table of contents and introduction to the model.

How it works

At the highest level, there is a federated set of models defined here. The Systems Model holds the engineering data for the entire set, and this information is almost exclusively at the logical level of abstraction. This means that the important logical properties of the data are represented – such as the extent and precision of the data – but their physical properties are not. Thus, we might represent an element such as a Radar Track in the Systems Model as having a value property of range with an extent of 10 meters to 300 kilometers and a precision of ± 2 meters. Those are logical properties. But the physical schema might represent the value as a scaled integer with 100* the value for transmission over the 1553 avionics bus. Thus, a range of 123 kilometers would be transmitted as an integer value of 12,300. This representation is a part of the physical data schema that realizes the logical properties.

Beyond the Systems Model, the Shared Model provides a common repository for information shared by multiple subsystems. During the systems engineering work, this is limited to the physical interfaces and associated physical data schema. Later in downstream engineering, other shared subsystem design elements might be shared, but that is beyond our scope of concern.

Lastly, each subsystem has its own Subsystem Model. This is a model used by the interdisciplinary subsystem team. For all team members, this model serves as a specification of the system and the related engineering facets. Remember that a facet is defined to be the contribution to a design specific to a single engineering discipline, such as software, electronics, or mechanical design. Software work is expected to continue in the model but the other disciplines will likely design their own specific tools.

Example

Figure 1.44 shows the initial organization of the Pegasus System Model, with Architecture 0 already added (see recipe Architecture 0). I’ve filled in a few other details, such as adding references to diagrams to illustrate how they might be shown here:

Figure 1.44: Pegasus system model – overview diagram

The shared model and subsystem model are not created early in the MBSE process but rather late, after the Pegasus architecture work is completed for the current iteration and the work developing the hand-off to downstream engineering is underway. We will discuss their creation in Chapter 4, Handoff to Downstream Engineering.