Hybrid Equations Toolbox

Toolbox for simulating hybrid systems and plotting hybrid arcs in MATLAB and Simulink.
7.4K Downloads
Updated 15 Oct 2022

Hybrid Equations Toolbox

View Hybrid Equations Toolbox on File Exchange

The Hybrid Equation (HyEQ) Toolbox provides MATLAB and Simulink libraries for the simulation of hybrid dynamical systems. The Toolbox supports definitions of hybrid systems with inputs, allowing for the creation of interconnected hybrid systems in modular configurations. The hybrid arcs output by simulations can be transformed and plotted with a suite of tools that allow easy customization. Detailed documentation and numerous examples are provided in the MATLAB Help browser or at hyeq.github.io.

Requirements

Installing v3.0 of the HyEQ Toolbox requires MATLAB R2014b or newer.

This toolbox officially supports the following combinations of operating system and MATLAB/Simulink version:

  • Windows: R2014b-R2022b
  • Mac (MATLAB only): R2014b-R2022b
  • Mac (MATLAB+Simulink): R2016a-R2022b
  • Linux: R2021a-R2022b

MATLAB versions R2014b through R2015b are not compatible with recent versions of macOS, such as macOS Monterey. See MATLAB and Simulink's system requirements to find a compatible OS/software version pair.

When the Toolbox was tested on Linux in MATLAB R2014b, Simulink caused the automated test runner to crash. Manual testing indicates that the HyEQ MATLAB library might work, but use at your own risk. For a MATLAB version tested with Linux, use R2021a or later (earlier versions than 2021a may work but were not tested).

How to Install the HyEQ Toolbox version 3.0

Before installing version 3.0 of the HyEQ Toolbox, it is necessary to manually uninstall any installed earlier versions (v2.04 or earlier). Subsequently, it is not necessary to manually uninstall the HyEQ Toolbox (v3.0 or later) before updating to a newer version.

Uninstalling HyEQ Toolbox Version 2.04.

The process for uninstalling v2.04 is as follows (earlier versions are similar).

  1. Open Matlab.
  2. Navigate to the HyEQ Toolbox folder. The toolbox folder can be located by running which('HyEQsolver') in the MATLAB command window (note that HyEQsolver is in a subdirectory of the HyEQ Toolbox folder).
    • On Windows, the HyEQ Toolbox folder path is typically C:\Program Files\Matlab\toolbox\HyEQ_Toolbox_v204.
    • On Macintosh, the HyEQ Toolbox folder path is typically ~/matlab/HyEQ_Toolbox_v204.
  3. While in the HyEQ Toolbox folder, run the uninstallation script tbclean in the MATLAB command window. This script deletes all the files in the HyEQ Toolbox folder!
  4. Restart Matlab.
  5. Check that the HyEQ Toolbox is uninstalled by running which('HyEQsolver'). The output should be 'HyEQsolver' not found.

Installing v3.0 via the Add-On Explorer (MATLAB R2017b and later)

On MATLAB R2017b and later, the HyEQ Toolbox can be installed through the MATLAB Add-on Explorer.

  1. Open MATLAB
  2. Select the “Home” tab at the top of the window.
  3. Click the “Add-Ons” button to open the Add-On explorer.
  4. Search for “Hybrid Equations Toolbox” and select the entry by Ricardo Sanfelice.
  5. Click the “Add” button to open a drop-down menu and select “Add to MATLAB”.
  6. A license agreement will open. Click “I Accept” to start the installation.
  7. When the installation is complete, a “Getting Started” guide will open in MATLAB with instructions for next steps.

If the above steps do not work because the Add-On Explorer is unavailable, then you can install the toolbox using the steps described below for installing without the Add-On Explorer.

Installing v3.0 Without the Add-On Explorer (MATLAB R2014b through R2017a)

The MATLAB Add-on Manager is not supported on versions of MATLAB before MATLAB R2017b, so for these versions the HyEQ Toolbox must be installed by the following process.

  1. Open the Hybrid Equations Toolbox page on the MATLAB Central File Exchange.
  2. Click “Download” and select “Toolbox” from the drop-down menu.
  3. Select any convenient location to save the .mltbx file.
  4. Open the .mltbx file in MATLAB.
  5. A dialog box will prompt you to install the toolbox. Click “Install.”
  6. To finish setting up the toolbox, run hybrid.configureToolbox in the MATLAB command window. This command
    1. checks that only one version of the toolbox is installed,
    2. upgrades the Simulink library and example model files to the current MATLAB version (this prevents warnings that they were last saved on an old version of Simulink), and
    3. opens a prompt to run automated tests (there will be several skipped tests for functionality that is not tested on older versions of MATLAB).
  7. You may delete the .mltbx file at this point.

Help Using the Toolbox

To access the HyEQ Toolbox documentation, open MATLAB Help (F1) and navigate to Supplemental Software>Hybrid Equations Toolbox. The documentation is also available online at hyeq.github.io.

To ask for help, report a problem, or request a feature, please submit an issue on GitHub.

Troubleshooting

Problem: When I call HybridSystem.solve(), after installing v3.0, the following error appears: “Error using HyEQsolver. Too many input arguments.

Cause: A previous version of the toolbox is still installed.

Solution: Uninstall the previous hybrid toolbox version by following the steps above.


Problem: Opening a Simulink example model produces the following error:

File '<path to toolbox>\Examples\+hybrid\+examples\+<example package>\<model name>.slx' cannot be loaded because it is
shadowed by another file of the same name higher on the MATLAB path.  For more information see "Avoiding Problems with Shadowed Files" in the Simulink documentation.

The file that is higher on the MATLAB path is: <path to another file>.

Solution: Either rename the example file name or rename the file that is shadowing it (or remove it from the MATLAB Path). After renaming the example file to <new model name>, you can open the model to by running hybrid.examples.<example package>.<new model name> or by navigating to it in the file browser. Links to open the example from the MATLAB Help browser will no longer work.


Problem: A Simulink model produces the following error message:

An error occurred while running the simulation and the simulation was terminated
Simulink cannot solve the algebraic loop containing '<model name>/Integrator System/ICx' at time 0.0 using the TrustRegion-based algorithm due to one of the following reasons: the model is ill-defined i.e., the system equations do not have a solution; or the nonlinear equation solver failed to converge due to numerical issues.

Cause: The Simulink model contains an algebraic loop (a closed signal loop that contains only direct feedthrough blocks) that is preventing Simulink from propagating the dynamics of the system.

Solution: For one of the HyEQ blocks in the loop, use the “x-” output instead of the “x” output to pass the output to the next block in the loop. This introduces a one time-step delay to the output signal in order to break the algebraic loop.

Credits

Version 2.04

Version 2.04 of the Hybrid Equations Toolbox was developed by Ricardo G. Sanfelice, David A. Copp, and Pablo Nanez.

Version 3.0

Version 3.0 of the HyEQ Toolbox was developed by Paul Wintz.

See Credits and Acknowledgments in the HyEQ Toolbox documentation for further acknowledgments.

See Also

Cite As

Ricardo Sanfelice (2024). Hybrid Equations Toolbox (https://github.com/pnanez/HyEQ_Toolbox/releases/tag/3.0.0.76), GitHub. Retrieved .

Sanfelice, Ricardo, et al. “A Toolbox for Simulation of Hybrid Systems in Matlab/Simulink.” Proceedings of the 16th International Conference on Hybrid Systems: Computation and Control - HSCC ’13, ACM Press, 2013, doi:10.1145/2461328.2461346.

View more styles
MATLAB Release Compatibility
Created with R2021b
Compatible with R2014b and later releases
Platform Compatibility
Windows macOS Linux
Categories
Find more on Simulink in Help Center and MATLAB Answers
Acknowledgements

Inspired: LibHybrid for System Identification Toolbox

Community Treasure Hunt

Find the treasures in MATLAB Central and discover how the community can help you!

Start Hunting!

Examples/+hybrid/+examples

Examples/+hybrid/+examples/+analog_to_digital_converter

Examples/+hybrid/+examples/+behavior_in_C_intersection_D

Examples/+hybrid/+examples/+bouncing_ball

Examples/+hybrid/+examples/+bouncing_ball_with_adc

Examples/+hybrid/+examples/+bouncing_ball_with_input

Examples/+hybrid/+examples/+coupled_subsystems

Examples/+hybrid/+examples/+finite_state_machine

Examples/+hybrid/+examples/+fireflies

Examples/+hybrid/+examples/+mobile_robot

Examples/+hybrid/+examples/+network_estimation

Examples/+hybrid/+examples/+vehicle_on_constrained_path

Examples/+hybrid/+examples/+zero_order_hold

Examples/+hybrid/+examples/+zoh_feedback_control

doc

doc/src

doc/src/Matlab2tex

matlab

matlab/+hybrid

matlab/+hybrid/+internal

matlab/+hybrid/+internal/+experimental

matlab/+hybrid/+subsystems

matlab/+hybrid/+tests

matlab/+hybrid/+tests/+internal

matlab/+hybrid/+tests/+slow_dev_only

matlab/+hybrid/+tests/+slow_essential

matlab/@function_handle

matlab/legacyPlottingFunctions

simulink

Version Published Release Notes
3.0.0.76

See release notes for this release on GitHub: https://github.com/pnanez/HyEQ_Toolbox/releases/tag/3.0.0.76

2.4.0.0

A new version of the simulator is available!
The main new features are:
1) Compatibility issues with matlab 2014-2016 are now solved
2) Instructions file updated
3) New examples and html files
4) Now is possible to solve DAE equations as a flow maps
A new version of the simulator is available!
The main new features are:
1) Compatibility issues with matlab 2014-2016 are now solved
2) Instructions file updated
3) New examples and html files
4) Now is possible to solve DAE equations as flow maps

2.3.0.0

Change log:
-new zero events in lite version
-new help files
-smaller insttallation file
-new CPS blocks
-new plotting functions, now compatible with pre and post 2014a plot behaviour
-update of the simulink library
-CPS examples

1.4.0.0

Instruction file for installation were updated.
Install problems in iMac's OS X 10.9.5 are solved.

1.3.0.0

1)Added two new plotting functions plotHarcColor and plotHarcColor3D
2)All functions have now the standard head (H1) help line
3)Functions plotC and plotD were removed
4)New help environment for all functions were created (with examples inclued)

1.2.0.0

Help files and instructions updated.

1.0.0.0

To view or report issues in this GitHub add-on, visit the GitHub Repository.
To view or report issues in this GitHub add-on, visit the GitHub Repository.