Home   :   Model Compiler Walkthrough

Model Compiler Walkthrough

Follow us on

Twitter

Discuss us on

LinkedIn

Watch us on

YouTube

Email us at

UltraDark

mike@ultradark.com

Get our code at

GitHub

Installing Matrix

You can install the free Matrix Model Compiler from Downloads. Be sure to read all the notes about the download before continuing as it introduces the folders and files that are created when Matrix is installed and points out other important information, such as how to easily uninstall Matrix from your system.

How to Use the Download

There are two ways of using the created files installed. The first is in read-only mode. If you don’t wish to use the Model Compiler to generate C code then you can simply browse the Matrix model files plus the generated C code files as all the generated products and compiled files are included in the install.

The second, which is far more rewarding involves actively running the Model Compiler and compiling the generated C code. The resulting executables can be run under the Simulator using command files.

A further step is to update a model by editing the corresponding System.matrix file and seeing what effect this has on the generated C code and its output when run. A number of models are supplied that can be used as a starting point.

What to Do Next

Having installed Matrix, follow the build process to see how it all works:

• Examine a Matrix Model

• Run the Model Compiler

• Start Visual Studio

• Examine the Generated Code

• Execute the Code and Examine Output

Examine a Matrix Model

Find the "Analysis Design Matrix" menu on the Windows Start Button and select the model you wish to see. The appearance of this menu depends on which version of Windows you have. Windows 10 does not allow sub-menus in the Start Menu but all other versions of Windows do.

The first time this is attempted Windows will claim not to know about this file type so just choose any text editing application. You can try this by opening the Banking Application model by selecting the "Model - Banking Application" option as shown below:

Alternatively, you can find the Matrix model by opening the file directly. To look at the Banking Application model, start Windows Explorer and navigate to the folder:

C:\Matrix\Models\Banking_Application\$Main

Open the System.matrix file in any text editor. You may need to open the file from inside the editor. If all else fails, see this model's code here.

Run the Model Compiler

To run the Model Compiler on the models supplied simply select the "Generate All Code" menu option.

This will open a Command Prompt window and run the Model Compiler on all five of the models using the System.matrix files as input. After this is complete scroll back the window to see the output from the Model Compiler. Press any key to close the Command Prompt window. This C code is written to the Generated folder and can be examined later.

Alternatively, navigate to the Command folder:

C:\Matrix\Command

Double click on the AllMatrixCompile.bat file. 

Individual models can be compiled by using the "Analysis Design Matrix" menu and opening the sub-menu called "Compile Models" as shown below (except Windows 10):

The C code produced by the Learning Edition has been especially developed to assist developers to detect model errors at run-time by including extra checks. It should be noted that the code generated is not suitable for production work.

Start Visual Studio

Having installed Visual Studio, select the "Compile Generated Code" option. This will start Visual Studio which will list the projects corresponding to all five models. From here you can find all the C source files that were generated when the Model Compiler was run.

Alternatively, navigate to the folder:

C:\Matrix\Build

Double click on the Build.sln file.

Examine the Generated Code

Using Visual Studio it's a simple matter to open the C header files in the Header Files filter and C procedure file in the Source Files filter. Just double click to open a C file. You can also see the System.matrix and Scenario.mcx files by opening the Resources Files filter.

Execute the Code and Examine Output

To compile and run the Banking Application C code from within Visual Studio simply press Function Key 5 (F5) on your keyboard or click on the Start Debugging icon on the Toolbar.

A Command Prompt window will now appear and display output from running the model. When done click on the Stop Debugging icon or press Shift+F5. Visual Studio may hide the Command Prompt window.

Alternatively, the Banking Application's output can be seen here.

To run another model, right click on the model's project name in the Solution Explorer window and select the "Set as StartUp Project" menu option then press F5 as before.

Individual models can be executed without Visual Studio by using the "Analysis Design Matrix" menu and opening the sub-menu called "Execute Models" as shown below:

It should be noted that Visual Studio is required if you want to compile C source code that has been generated from your own models.

Editing Matrix Model Files

Any text editor can be used to edit a Matrix model file which is always called System.matrix. We recommend the TextPad editor and we can provide a TextPad syntax colouring file that highlights Matrix statement names, symbols and also improves code readability.

Matrix Example Models

The supplied models and their expected outputs come fully documented and include model diagrams:

Hello World - The standard Hello World! demo that every language must have.

Ping Pong - A model that demonstrates generating and listening for events.

Zig Zag - A model that demonstrates the asynchronous creation and deletion of objects.

Banking Application - This model is taken from the book Object Lifecycles: Modeling the World in States by Sally Shlaer and Stephen J. Mellor.

Passenger Elevator - A larger model that describes a workable elevator (lift) system that employs a simplistic allocation algorithm. An assigner entity is used to resolve any possible contention for elevators.

Windows WiX Installer - A model that generates an application's WiX installation source file in XML format. The file is processed by the WiX toolset to produce an installable MSI file for the Windows platform. This model is used to generate the installer for the Model Compiler download.

Gothic Hotel Controller - This model is based on a state machine design of an amusing but fantastical security system described by Martin Fowler in a discussion of Domain Specific Languages. The subsequent example model, Gothic Hotel is based on entities abstracted from the problem space.

Gothic Hotel - This example presents how the Gothic Hotel securty system should be analysed using entities abstracted from the problem space. The previous example model, Gothic Hotel Controller followed the original article by implementing a state machine based solution.

Petrol Station - A model that documents an experiment to convert an existing MASL model to the Matrix language. MASL is expected to become the main modeling langage for the Executable UML BrigdgePoint tool.