cinaral / matlab_cpp_work_demo

A workflow suggestion for generating C++ code via MATLAB and integrating MATLAB in your C++ project.

MATLAB and C/C++ Combined Workflow Demonstration

What is this?

This is an example project about generating, verifying and integrating C/C++ code using MATLAB and CMake.

• MATLAB is a programming and numeric computing platform with powerful data analysis and graphics tools.
• C is a general-purpose, procedural programming language with little hardware abstraction. It is efficient, portable and commonly used in embedded systems.
• C++ is almost a superset of C. It is one of the highest-level programming languages that can still provide deterministic execution time.

Quick start

a) Prerequisites:

1. CMake
2. A C/C++ compiler, e.g. for Windows, MinGW-w64 from Msys2.
3. MATLAB

b) Creating a new project:

1. Set up your project directory as shown

   <Project Name>
   ├─📂docs
   ├─📂include
   ├─📂matlab
   ├─📂src
   ├─📂tests
   │ └─📂matlab
   │	└─ run_all_tests.m
   ├─ CMakeLists.txt
   └─ README.md
   

   File/Folder	Explanation
   /docs	Documentation files (.md, .docx, .txt...)
   /include	Header files (.h, .hpp, .hxx, ...)
   /matlab	MATLAB scripts, prototypes, derivations (.m, .slx, ...)
   /src	Source files (.c, .cpp, .cxx, ...)
   /tests	Test files (.c, .cpp, .cxx, ...)
   /tests/matlab	MATLAB test scripts (.m, ...)
   run_all_tests.m	MATLAB script to call all MATLAB test scripts
   CMakeLists.txt	Describes the build process, read by CMake
   README.md	Summary of the project

2. Start with your mathematical derivations and document them in /docs, e.g. derivation.ipynb.

3. Prototype your derivations in MATLAB in /matlab, e.g. filter_1st_order.m.

4. Write MATLAB test scripts for your prototypes in /tests/matlab to verify them.

5. Code your project based on the prototypes, this step may include C/C++ code generation from MATLAB code. Do whichever is appropriate and convenient. Problem parameters known at compile time should be written in a separate header file, e.g. Parameters.hpp.

6. Write your unit tests in /tests. These unit tests should be automated as much as possible, but for verification and debug purposes a human may need to look at some plots. For this task read/write data to disk, and plot the data using MATLAB. It is important to share the problem parameters with the MATLAB test scripts. This can be achieved by including a step in the build instructions to write them to simple MATLAB-readable files, e.g. ParametersToFile.cpp.

7. Update the MATLAB test scripts to incorporate the unit tests if desired, e.g. test_filter.m.

c) Building and verifying an existing project:

1. Configure the project using CMake.
2. Build the project and run CTest tests.
3. Run the MATLAB script run_all_tests.m.

For help, see the How to compile? section.

Main principles

1. Prototype in MATLAB
2. Code and implement in C/C++
3. Verify in MATLAB

Unit testing is highly encouraged. Here is a good introduction to unit testing. The tester may or may not be the original programmer or a programmer.

Workflow

   MATLAB
   ┌──────────────────────┐
   │ 1)                   │
   │ ┌─────────┐          │
   │ │Prototype│◄────┐    │
   │ └────┬────┘     │    │
   │      │       ┌──┴──┐ │
   │      │       │Debug│ │
   │      ▼       └──┬──┘ │   
   │  ┌───────┐      │    │
┌──┼─►│Verify ├──────┘    │
│  │  └───────┘           │
│  └──────────────────────┘
│                    
│  C/C++             
│  ┌──────────────────────┐
│  │    2)                │
│  │    ┌─────┐           │
│  │    │Write│◄────┐     │
│  │    └──┬──┘  ┌──┴──┐  │
│  │       │     │Debug│  │
│  │       ▼     └──┬──┘  │
│  │   ┌───────┐    │     │
├──┼───┤Compile│────┘     │
│  │   └───┬───┘          │
│  └───────┼──────────────┘
│          │
│  Embedded│system
│  ┌───────┼──────────────┐
│  │  3)   ▼              │
│  │  ┌──────────┐        │
└──┼──┤Experiment│        │
   │  └──────────┘        │
   └──────────────────────┘

The workflow is split into three environments,

1. MATLAB
2. C/C++: Editor/IDE and build tools
3. Embedded system: Microcontroller

These environments have different levels of flexibility and portability. The main objective of this workflow is to play the strengths of each environment. MATLAB is very powerful for prototyping algorithms and verifying data, and so all verification should take place in MATLAB.

Verification means different things during different stages of development (i) In the prototyping stage it means prototypes are compared against existing data and solutions (e.g. analytical solutions), and (ii) in the coding and implementation stage it means the results produced meet expectations. You should worry about ideas while sketching and worry about the technique when drawing.

Verifying results from C/C++ and the embedded system in MATLAB is not a substitute for unit testing in their respective environments. All three environments should have their own (automated) unit testing routines whenever possible, including MATLAB prototypes. The MATLAB prototype can guide unit testing in other environments.

How to compile?

These instructions are for using Visual Studio Code.

1. Install VS Code
2. Install the following extensions for VS Code:
   • C/C++
   • CMake Tools (You may follow these instructions)
3. Install CMake and add to path during installation.
4. For Windows, install Msys2. (You may follow these instructions) and add C:\msys64\mingw64\bin to path. Open an Msys2 terminal type, in pacman -Syu and pacman -S --needed base-devel mingw-w64-x86_64-toolchain. For other platforms, make sure gcc is installed.
5. Verify g++ installation by typing g++ --version in an Msys2 terminal. It should display the current version.
6. Open the project root folder in VS Code (where the top CMakeLists.txt lives). By default CMake Tools will configure the project for you, creating a build folder. You may build and run tests using the task bar on the bottom of your screen.
7. If CMake tools fails to find prefered generator, addd

"cmake.mingwSearchDirs": [
	"C:\\mingw-w64\\mingw64\\bin"
],
"cmake.generator": "MinGW Makefiles"

to your VS Code settings (or your absolute path to mingw64 bin directory).

You will need a C++ compiler to compile .cpp files. You can use VS Code with gcc for this task.

Extensions

Once the C/C++ code is verified, it can easily be integrated to any environments. For example, it can be wrapped in Python for easy installation and visualization, such as graphical user interfaces. This can potentially extend our verification capabilities by allowing easy communication between different devices over different protocols.

Potential gotcha's

• The prototype and the C/C++ implementation may diverge over time. If this happens, since the C/C++ implementation must be verified, this may necessitate updating the prototype or adding new MATLAB code for comparison purposes.
• MATLAB may not be available everywhere. Whenever possible the unit tests should work independently of the MATLAB testing scripts.

Acknowledgements

This work was supported by the National Science Foundation DCSD Grant (No. 2029181).