MATLAB + Simulink and Octave Interface#

In order to use acados from Octave or MATLAB, you need to create the acados shared libraries using either the CMake or Make build system, as described on the installation page.

Getting started#

Check out the examples minimal_example_ocp.m and minimal_example_sim.m to get started with the MATLAB interface of acados. Note that acados currently supports both an old MATLAB interface (< v0.4.0) as well as the new one (>= v0.4.0). Unfortunately, not all MATLAB examples have been ported to the new interface yet. If you are new to acados please start with those examples that use the new interface already.

The examples require an installation of CasADi to generate the model functions. The getting_started example offers the option to attempt to automatically download the correct version in the recommended folder. Detailed instructions for a manual installation can be found in the last section of this page Setup CasADi.

The problem formulation is stated in this PDF.

Export environment variables#

In order to run the examples, some environment variables need to be exported. Instead of running the scripts below, you can modify an rc file, like .bashrc when launching MATLAB from bash, .matlab7rc.sh or startup.m to always have those environment variables defined when starting MATLAB.

Linux / macOS#

Navigate into the folder of the example you want to run and execute the following command:

source env.sh # Which can be found in the folder of one of the examples

If you want to run an acados example from another folder, you need to export the environment variable ACADOS_INSTALL_DIR properly. In the env.sh file it is assumed that ACADOS_INSTALL_DIR is two folders above the directory, in which the example is located.

Afterwards, launch MATLAB or Octave from the same shell.

If you want to run the examples in a different folder, please close the current shell and open a new one to repeat the procedure: this ensures the correct setting of the environment variables.

Windows#

Open MATLAB and navigate into <acados_root>/examples/acados_matlab_octave.
Run acados_env_variables_windows to export the environment variable ACADOS_INSTALL_DIR.
Navigate into <acados_root>/examples/acados_matlab_octave/getting_started and run one of the examples.

Interface structure#

The interface allows one to conveniently and compactly formulate an OCP (or IVP) and specify solver options. The nonlinear problem functions can be formulated using CasADi symbolics which are generated as C code with the required derivatives using automatic differentiation. The whole problem description is written to a json-file which is then used to render different templates, via the Tera renderer. These are the same templates as in the Python interface (see Python interface). In addition to a MEX wrapper it contains all the C code that is needed for embedded deployment. These templates can be found in <acados_root>/interfaces/acados_template/acados_template/c_templates_tera.

Options documentation#

For the template based part of the MATLAB interface, we refer to the docstring based documentation of the Python interface.

Simulink#

The templates mentioned above also contain templated S-functions and corresponding make functions for both the OCP solver and the acados integrator.

A basic Simulink example can be found in <acados_root>/examples/acados_python/getting_started/simulink_example.m

A more advanced Simulink example which showcases how to customize the inputs and outputs of the Simulink block corresponding to the solver can be found in <acados_root>/examples/acados_python/getting_started/simulink_example_advanced.m

Simulink input and output ports#

The Simulink input and output ports for an acados OCP solver can be configured using the AcadosOcpSimulinkOptions class. Please refer to the documentation there for a detailed description.

Developing extensions#

If you want a more advanced interaction with the acados solver via Simulink, feel free to edit the corresponding templates in <acados_root>/interfaces/acados_template/acados_template/c_templates_tera/matlab_templates to add more inputs or outputs.

S-function Mask#

Port labels are automatically baked into the Simulink block mask when the block is generated by make_sfun or make_sfun_sim. No manual copy-paste of mask commands is required.

SIM solver block: Port labels are always included in the mask.
OCP solver block: Port labels are included only when simulink_opts.show_port_info is set to 1 (default: 1). When disabled, the mask shows only the solver name.

To enable port labels for the OCP block, set the flag before generating the solver:

simulink_opts.show_port_info = 1;

The generated Simulink block (saved as <name>_ocp_solver_simulink_block.slx) will then display the name of each input and output port directly on the block icon, facilitating debugging.

Setup CasADi#

To create external function for your problem, we suggest to use CasADi from the folder <acados_root_folder>/external. Depending on the environment you want to use to generate CasADi functions from, proceed with the corresponding paragraph (MATLAB, Octave).

Any CasADi version between 3.4.0 and 3.6.7 should work. If you don’t have CasADi yet, you can install it as described below.

MATLAB#

Download and extract the CasADi binaries into <acados_root_folder>/external/casadi-matlab:

cd external
wget -q -nc --show-progress https://github.com/casadi/casadi/releases/download/3.4.0/casadi-linux-matlabR2014b-v3.4.0.tar.gz
mkdir -p casadi-matlab
tar -xf casadi-linux-matlabR2014b-v3.4.0.tar.gz -C casadi-matlab
cd ..

Octave version 6.2 or later#

Download and extract the CasADi binaries into <acados_root_folder>/external/casadi-octave:

cd external
wget -O casadi-linux-octave.zip https://github.com/casadi/casadi/releases/download/3.6.7/casadi-3.6.7-linux64-octave7.3.0.zip
mkdir -p casadi-octave
unzip casadi-linux-octave.zip -d ./casadi-octave;

MATLAB + Simulink and Octave Interface

Contents