Component-Based Modeling Guidelines

When to Partition a Design

Partition a design when it becomes too complex for one person to know all of the details. Complexity increases with design size and team size, for example,

  • Design size and complexity:

    • Thousands of blocks

    • Hundreds of logical decisions

    • Hundreds of inputs and outputs

    • Hundreds of times larger industry examples in some cases

    • Multiple variant configurations of the same functionality

  • Team integration:

    • Multiple people working on the design

    • People located in different places

    • People from different companies

Partitioning your design into components helps you to work with large-scale designs. Partitioning a design into components gives modularity to help you reduce complexity, collaborate on development, test and reuse components, and to succeed with large-scale model-based design. Component-based modeling helps:

  • Enable efficient and robust system development.

    • Reduce overall design complexity by solving smaller problems.

    • Gain performance benefits that scale.

    • Reuse components across multiple projects.

  • Facilitate collaboration

    • Partition algorithms, physical models, and tests. Define architecture in terms of structural and functional partitioning of the design using defined interfaces.

    • Collaborate with teams across organizational boundaries on product development. Teams can elaborate individual components independently to do plant modeling, algorithm design, and developing of test harnesses.

    • Manage design with source control tools.

  • Improved iteration, elaboration, and verification workflows

    • Iterate faster via more efficient testing and reuse.

    • Eliminate retesting for unchanged components.

    • Reuse environment models and algorithm designs in different projects.

    • Create variants of designs.

    • Elaborate components independently through well-defined interfaces.

    • Manage design evolution with configuration management tools.

Component-based modeling requires:

  • Mechanisms for partitioning models and specifying interfaces

  • Tools and processes for managing data, models, and environment

Use the following techniques for component-based modeling.

When Not to Partition a Design

Componentization provides benefits for large-scale designs, but is not needed for small designs. Partitioning your design into components requires design work and can increase time taken to update diagrams. Use separate components only when your design is large enough to benefit from componentization.

To decide whether your design needs partitioning, see the recommendations in Guidelines for Component Size and Functionality.

Plan for Componentization in Model Design

After models grow large and complex over time, it is difficult to split them into components to allow multiple engineers to work on them in parallel. Splitting a Simulink® model into components is easier if the model is designed for componentization from the start. Designing for componentization in the first place can help you avoid these difficulties:

  • If a single engineer develops a model from the bottom up, adding blocks and grouping them into subsystems as the model complexity increases, it is hard to later split the model into components. The subsystems within the model are often “virtual” and nonatomic. When you convert these to atomic subsystems and then to model reference components, you can introduce unwanted algebraic loops that are hard to diagnose and solve.

  • Subsystems grown over time do not always represent the best way to partition the model. “Best” here might mean the most useful structure for reusable components in other models, or for generating code that integrates with legacy functionality, or for performing Hardware-in-the-Loop tests, etc.

  • If you try to expand to parallel development without componentizing models, it is difficult to share work in teams without time-consuming and error-prone merging of subsystems.

These problems are analogous to taking a large piece of code (C, Java, or MATLAB® code) and trying to break it down into a number of separate functions. Significant effort is required and can require extensive modifications to some parts of the code, if the code was not designed to be modular in the first place. The same is true for Simulink models.

Lack of componentization causes common failure modes when trying to place Simulink models into configuration management as they grow and you want more than one engineer to work on it in parallel. The best way to avoid these issues is to design for components from the start. You can use the following features of Simulink to design a model suitable for componentization.

If you already have a design that you want to divide into components, see Partition an Existing Design.

Guidelines for Component Size and Functionality

To set up your project for a team to work on, consider the following model architecture guidelines for components. Useful components:

  • Have well-defined interface I/O boundaries.

  • Perform a defined set of functions (actions), defined by requirements.

  • Form part of a larger system.

  • Have the “right” size:

    • Large enough to be reusable

    • Small enough to be tested

    • Only one engineer is likely to want to edit each model at a time

The right size can depend on team size. You can have larger components if only one person is working on each, but if you need to share components between several people, you probably need to divide the design into smaller logical pieces. This aids two goals: understanding the design, and reducing file contention and time spent on merging.

Recommendations:

  • In most cases, if you have fewer than 100 blocks, do not divide the design into components. Instead, use subsystems if you want to create a visual hierarchy. For example, the example model vdp is not large enough to benefit from componentization.

  • If you have 500–1000 blocks, consider creating a model reference to contain that component in a separate file. The cost of verification can reduce the size for components. For example, if you have a small component of 100 blocks with high testing costs and frequent changes, consider separating that component into a separate file to make verification easier.

Consider dividing the model based on:

  • Physical components (e.g., plant and controller, for code generation)

  • Algorithm logic

  • Reusability in other models

  • Testability, for example, for performing Hardware-in-the-Loop tests

  • Sample rate; consider grouping components that have the same sample rate

  • Simulation speed; using different solvers for components with different numerical properties can increase simulation speed

  • Accessibility to other teams or others on your team.

While you cannot always plan on model size, if you expect multiple people to work on the design, you can benefit from componentization techniques. Consider controlling configuration management using a project and partitioning the design using Model Reference so that the team can work on separate files concurrently.

Component SizeRecommended Componentization TechniquesNotes

Small <500 blocks

Create visual hierarchy using subsystems.Small designs do not benefit from dividing into separate files. However, larger teams that cause file contention or high cost of verification can make it worth partitioning smaller components into separate files instead of using subsystems.
Large >500 blocksSeparate components into separate files using Model Reference or Libraries.

For multiple engineers or teams working on a design, best practice is one file per component. To reduce file contention, aim for components in which only one engineer needs to edit each model at a time.

Small <500 blocks, but expected to grow over time

Use atomic subsystems for functional block grouping instead of virtual subsystems. Atomic subsystems are easier to migrate to separate file components later.

If possible, plan your components from the start to avoid migration pain.

If your design or team is large enough to benefit from separating components into separate files, this table summarizes when to apply each technique.

Component CharacteristicsTechniqueBenefitsCosts
Small, low-level utility functions, reused in many places in a design

Library model containing a single reusable atomic subsystem

  • Context-dependent: can adapt to various interfaces with different data types, sample time, and dimensions, in different contexts, without changing the design.

  • Can be reused in other models

  • Stored as a separate file, can apply version control, but each instance adapts to context of parent model, so generated code can differ in each instance.

  • To avoid context adaption, if you have an Embedded Coder® license, you can specify different function interfaces for a reusable library subsystem and generate code for the library. This technique makes the library and not the model the owner of the code. See Library-Based Code Generation for Reusable Library Subsystems (Embedded Coder).

  • Cannot use independently to simulate or generate code. Requires a parent model.

  • Context adaptation not desirable for big components in large-scale models where interfaces are managed and locked down to specific data type and dimension. In these cases, you might not want code generated for the library block to differ in each instance.

  • Requires link management to avoid problems with broken, disabled, or parameterized links. See Manage Components Using Libraries.

Groups of blocks for sharing among users

Library for grouping and storing Simulink blocks

Library palette of links to components

  • Libraries are useful for storing blocks to share among a number of users

  • To reduce file contention, use library palettes of links to individual components in separate files. Store each component in a model reference file or a single subsystem in a separate library.

  • Causes file contention if multiple components reside in a single library file. File contention is a problem only if blocks need frequent updates or multi-user access. Palettes can help.

  • Requires link management to avoid problems with broken, disabled, or parameterized links. See Manage Components Using Libraries.

Top-level components for large-scale models: >500 blocks

Large components: starting at ~ 500–5000 blocks for one or a few reusable instances, or smaller if many instances

Components at any level of model hierarchy where teams need to work independently

Model Referencing
  • Components are independent model files and part of a larger model. You can simulate and generate code in the component.

  • Independent of context—good for large-scale model components where interfaces are managed and locked down.

  • Stored as a separate file—can apply version control to a component independently of the models that use it.

  • Possible to use Accelerator mode generated code to reduce memory requirements when loading models and increase simulation speed, compared to subsystems or libraries. Useful for top-level component partitions.

Performance can reduce slightly when updating a model (update diagram) because each reference model is checked for changes to enable incremental builds. When components are large enough (>500 blocks), update diagram is faster in most cases.

See Partition a Design Using Model Reference.

Choose Components for Team-Based Development

To perform parallel development, you need component-based modeling. Best practice for successful team-based development is to partition the models within the project so that only one user works on each part at a time. Componentization enables you to avoid or minimize time-consuming merging. To set up your project for work by a team, consider the following model architecture guidelines.

This table compares subsystems, libraries, and model referencing for team-based development.

Modeling Development ProcessSubsystemsLibrariesModel Referencing

Team-based development

Not supported

For subsystems in a model, Simulink provides no direct interface with source control tools.

To create or change a subsystem, you need to open the parent model’s file. This can lead to file contention when multiple people want to work on multiple subsystems in a model.

Merging subsystems is slow and error prone, so best avoided as a workflow process. However, Simulink provides tools to help you merge subsystems. See Merge Simulink Models from the Comparison Report.

Supported, with limitations

You can place library files in source control for version control and configuration management. You can use the project to interact with source control.

You can maintain one truth, by propagating changes from a single library block to all blocks that link to that library.

To reduce file contention, use one subsystem per library.

You can link to the same library block from multiple models.

You can restrict write access to library components.

Well suited

You can place model reference files in source control for version control and configuration management. You can use the project to interact with source control.

You save a referenced model in a separate file from the model that references it. Using separate files helps to avoid file contention.

You can design, create, simulate, and test a referenced model independently from the model that references it.

Simulink does not limit access for changing a model reference.

Most large models use a combination of componentization techniques. No single approach is suitable for the wide range of users of Simulink. The following advice describes some typical processes to show what you can do with MathWorks® tools to perform team-based development.

One File Per Component for Parallel Development

To perform efficient parallel development, break a large model into a number of individual files, so that team members can work independently and you can place each file under revision control. Componentization enables you to avoid or minimize time-consuming merging. To set up your project for work by a team, consider the advice in Guidelines for Component Size and Functionality.

A key goal of component-based modeling is to allow parallel development, where different engineers can work on components of a larger system in parallel. You can achieve this if each component is a single file. You can then control and trace the changes in each component using project source control. See Configuration Management.

Partition an Existing Design

If you already have a design that you want to divide into components, first decide where to partition the model. Existing subsystems that grow over time are not always the best way to partition the model. Consider dividing the model based on the advice in Guidelines for Component Size and Functionality.

Agreeing on an interface is a useful first step in deciding how to break down the functionality of a large system into subcomponents. You can group signals and partition data. See Interface Design.

After you decide how to partition your design, Simulink tools can help you divide an existing model into components.

Simulink can help you partition models by converting subsystems to files. You can convert to files using Model Reference or Libraries. See Guidelines for Component Size and Functionality for suggestions on when to apply each technique.

Partition a Design Using Model Reference

Use Model Reference to divide the components into separate files so that the team can work on separate files concurrently. You can also reuse the models in other models. To partition a model using model reference, see Reference Existing Models or Convert Subsystems to Referenced Models.

Manage Components Using Libraries

  • Use Libraries containing a single subsystem to contain a component in a single file. Use libraries to store blocks you can reuse in models. The linked blocks inherit attributes from the surrounding models, such as data types and sample rate. Using this technique for componentization has the management overhead of library links, described below.

  • Use Libraries to reuse blocks in multiple models. Libraries work well for grouping and storing Simulink blocks to share. Best practice for libraries is to use them for storing blocks to share with multiple users, and blocks that are updated infrequently. As a rough guideline, it is appropriate to use a Simulink library if its contents are updated once every few months. If you update it more frequently, then the library is probably being used to perform configuration management. In this case, take care to avoid the common problems described in Library Link Management.

  • To make library blocks available for reuse while reducing file contention and applying revision control, use library palettes. A palette is a library containing links to other components. If each component is a single subsystem in a separate library, or a model reference file, you can achieve the one-file-per-component best practice for component-based modeling. You can use separate version control for each component, and you can also control the palette.

    When you drag a block from the library palette into your model, Simulink follows the link back to the file where the subsystem or model reference is implemented. The models that use the component contain a link to the component and not to the palette.

Library Link Management

Library links can introduce management overhead if you use them for configuration management. Take care to manage:

  • Disabled links — Can cause merge conflicts, and failure to update all instances of the same model component. In a hierarchy of links, you can accidentally disable all links without being aware of it, and only restore one link while leaving others disabled.

  • Broken links — Accidentally broken links are a hard problem to solve, because, by design, you cannot detect what the broken link linked to previously.

  • Parameterized link data — It can be useful to change the value of parameter data, such as the value of a gain within a gain block, without disabling the library link. This generates “link data” for that instance only. However for configuration management this can cause a problem, if you assume all instances are identical, as one now has different properties.

Simulink tools help you manage library links to avoid problems:

Caution

These link management tools can detect link problems but cannot prevent editing the wrong files. If this is a problem, then use Model Reference as the partitioning mechanism to avoid the risks associated with disabled, broken, and parameterized links.

Related Topics