5 tips for more readable Simulink models

With this post, I will share some of the methods I have used over the years to make my Simulink models more readable.

Resize subsystems and reorder ports

Resizing subsystems is a common suggestion to making diagrams more readable.  A step beyond that is to reorder the ports so that the connections between multiple subsystems are more readable.

With this Before/After example, I have done three things

  1. Resized the source and destination blocks
  2. Changed the port order on the source block
  3. Offset the two destination blocks

MATLAB functions for equations

When I am entering in an equation into Simulink, I ask myself 2 questions

  1. Is there a built-in function for this equation (e.g., Integrators, Transfer Functions, table lookups)?  Use the built-in function
  2. Is the equation more than 3 operations long?  Use a MATLAB function.

In text form, the Pythagorean theorem is quickly recognized and understood.  When written out as a Simulink equation it takes slightly longer to understand.

Note: I do have a caveat, if the mathematical operations are series of gains, for instance when converting from one unit to another, then keeping the calculations in Simulink is fine.

Use of  Virtual busses for conditionally executed subsystems

Merging data from conditionally executed subsystems requires the use of the Merge block.  When the subsystems have multiple output ports routing the data quickly becomes cumbersome.  This can be addressed by creating a virtual bus to pack and then unpack the signals.

virtBus

Note: Using a virtual bus will allow Simulink/Embedded Coder to optimize the memory placement of the signals.  If a structure is desired, then a bus object should be defined and used.

The rule of 40, 5 and 2

When I create a Simulink subsystem, I aim to have a limited number of active blocks in the subsystem (40).  A limited number of used inputs (5) and a limited number of calculated outputs (2).

  1. Active blocks:  Any block that performs an operation.  This count does not include inports, outports, mux, demux, bus…
    1. Why: When the total number of blocks goes above 40 the ability to understand what is going on in the subsystem decreases.
  2. Used inputs: Bus signals can enter the subsystem, and only one signal off of the bus may be used.  A “used signal” is one that is actively used as part of the subsystems calculations.
    1. Why: The number of used inputs is a good metric for how “focused” the subsystem is in addressing a specific issue.
  3. The number of outputs: directly relates to the first two metrics, e.g.h, how focused the subsystem is on a specific issue.

Notes: Subsystems that are integration subsystems (see this Model Architecture post) can and should break this rule.)

Stay out of the deep end, beware of breadth

As a general rule of thumb, I recommend that models have a “depth” of 3.  Navigation up and down the hierarchy quickly can lose a reviewer.  Likewise, for given model, I recommend between 30 and 60 subsystems in total.

Image result for pool deep end

This recommendation holds for a single model.  For integration models, each “child” model should be treated as a single unit.

Final thoughts

These are just a few of the recommendations that I have hit upon in the past 18 years.  I would be curious to hear your thoughts and recommendations.

3 thoughts on “5 tips for more readable Simulink models

  1. Hi Mickael,

    What would be your advice regarding the use of From/Goto tags ?
    Same question for visualisation blocks (scopes, spectrum analyzer, …).
    Do you have best practices for Area and Annotations ?
    Thank you,
    Pierre

    Like

    1. Pierre

      For Goto/From tags I follow the MAAB style guideline rules
      1.) na_0011: Scope of Goto and From Blocks
      2.) jc_0171: Maintaining signal flow when using Goto and From blocks

      With respect to viewing signals. I try not too put too many scopes into my model, I find this link
      https://www.mathworks.com/help/simulink/ug/viewing-output-trajectories.html
      useful for deciding what to do with data logging.

      With respect to Areas, I haven’t seen a unified best practice emerge yet so I am still thinking about that one.

      On annotations, I prefer to use a requirement document to an annotation unless it is a “Work in Progress” note, e.g. something to remind myself what I was doing when I come back to the model.

      Like

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s