Wolfram Language Home Page »

File Formats—Simulation Result Files

System Modeler uses a number of different file formats. For a complete list, see the System Modeler File Formats page.

Simulation Result Files

Simulation result files (.mat) are generated during simulations. The files are read by Simulation Center, but may also be accessed from within the Wolfram Language to extract specific values or datasets.

At the end of each simulation, the results of the simulation are stored in a level-4 MAT-file according to this specification. This binary file has a structure that can be interpreted as a sequence of matrices: Aclass, name, description, dataInfo, data_1, ..., data_n.

There are two different ways in which the matrices may be stored.

• binNormal: matrix is stored as a non-transposed binary matrix.

• binTrans: matrix is stored as a transposed binary matrix.

The first matrix, Aclass, is always stored in the binNormal format by System Modeler. The format of the rest of the matrices is given by the Aclass matrix; see Aclass documentation.

There are four informative matrices, followed by one or more data matrices containing the values for each simulation variable. Every matrix has a header with a specific structure that is described in detail in this chapter.

The content of the MAT-file is a set of matrices, where each matrix is preceded by a header.

Headers

Each matrix is preceded by a header with six entries. The first five entries contain information about what data is stored and how, while the sixth entry is the name of the matrix.

type

An integer with storage information. If the integer is represented as M0PT, where M is the thousands digit, 0 is the hundreds digit, P is the tens digit, and T is the ones digit, then:

• M indicates the numeric format of binary numbers on the machine that wrote the file. It is possible to use the table below to determine the number to use for your machine. This should be the same for all the headers in the MAT-file.

	0	IEEE Little Endian (PC, 386, 486, DEC Risc)
	1	IEEE Big Endian (Macintosh SPARC, Apollo, SGI, HP 9000/300, other Motorola systems)
	2	VAX D-float
	3	VAX G-float
	4	Cray

• 0 is always 0 (zero) and is reserved for future use.

• P specifies the format of the data according to the table below.

	0	double-precision (64-bit) floating-point numbers
	1	single-precision (32-bit) floating-point numbers
	2	32-bit signed integers
	3	16-bit signed integers
	4	16-bit unsigned integers
	5	8-bit unsigned integers

The precision used by the save command depends on the size and type of each matrix. Matrices with any noninteger entries and matrices with 10,000 or fewer elements are saved in floating-point formats requiring 8 bytes per real element. Matrices with all integer entries and more than 10,000 elements are saved in the following formats (see table below), requiring fewer bytes per element.

	[0:255]	1
	[0:65535]	2
	[-32767:32767]	2
	[-2^31+1:2^32-1]	4
	other	8

• T indicates the matrix type according to the table below. Note that the elements of a text matrix are stored as floating-point numbers between 0 and 255 representing ASCII-encoded characters.

	0	numeric (full) matrix
	1	text matrix
	2	sparse matrix

mrows

An integer specifying the number of rows in the matrix.

ncols

An integer specifying the number of columns in the matrix.

imagf

An integer specifying whether the matrix has an imaginary part. If set to 0, there is only real data; if set to 1, the matrix has an imaginary part.

namlen

An integer specifying the length in bytes plus one (null terminated) of the matrix name.

name

A null-terminated string of namlen ASCII bytes.

Informative Matrices

The matrices Aclass, name, and description are of type char, while the dataInfo matrix is of type int32_t. Each of the matrices contains information about the simulation and the variables.

Aclass

Aclass is a matrix with a (4,*) size; the number of columns depends on the lengths of the strings they contain. The information you get from this matrix is the format of the file (file format version and storage format) as well as the model name.

Below is a simplified and schematic representation of the matrix Aclass.

--------------------------------------
Atrajectory
1.1
GettingStarted.MultiDomain.DCMotor
binTrans
--------------------------------------

The first line is always the mandatory string Atrajectory. The second line is the version of the file format. The third line is the full name of the simulated model. The fourth and last line determine the format of the matrices that follow.

The version can be 1.1 or 1.2. If the version is 1.2, there is a fifth line added at the end, describing how the time vector is stored in data matrices. If the fifth line is timeDiff, the first time point contains the simulation start time, and each entry after that contains the time increment since the point before it. If the fifth line is time, each time entry is the time value stored normally.

name

The name matrix contains the names of the variables in the file, including states, variables, parameters, constants, and so on. The ^th row contains the name of the ^th variable. The global length of a row depends on the maximal length of all the strings.

Below is a simplified and schematic representation of the name matrix.

--------------------------------------
Time
inductor1.i
inertial.phi
...
...
--------------------------------------

description

This third matrix contains description texts for all variables. This corresponds to the strings you may add when defining a variable in Modelica. If nVars is the total number of variables, the matrix description is an (nVars,*)-sized matrix.

Below is a simplified and schematic representation of the description matrix.

--------------------------------------
Time
Current flowing from pin p to n [A]
Absolute rotation angle of component
...
...
--------------------------------------

If a variable does not have an associated description, the line is filled with blanks.

dataInfo

This fourth matrix dataInfo is an (nVars,4)-sized matrix of type int32_t, where nVars is the total number of variables. The matrix contains information on how and where each variable is stored in the data matrices. The ^th row describes the ^th variable.

Here is the correspondence between column values and their meaning:

• dataInfo(n,1) = j means that the n ^th variable data is stored in matrix data_j.

• dataInfo(n,2) = k means that the n ^th variable data is stored in column abs(k) of matrix data_j, with sign(k) used as the sign.

• dataInfo(n,3) = 0 is reserved for future use; always 0.

• dataInfo(n,4) = -1 is reserved for future use; always -1.

Note that dataInfo(1,1) = 0 means that column number dataInfo(1,2) is the abscissa data names name(1,*) of all data matrices. This is usually Time. This special rule is necessary, since otherwise the abscissa name has to be repeated in the matrix name, and the names in it would no longer be unique.

With one-based indexing, the structure of the matrix can be schematically given by the following example:

--------------------------------------
0 1 0 -1
1 2 0 -1
1 3 0 -1
2 2 0 -1
...
...
--------------------------------------

where

• name(1,*) is abscissa data stored in data_*(*, 1)

• name(2,*) is stored in data_1(*, 2)

• name(3,*) is stored in data_1(*, 3)

• name(4,*) is stored in data_2(*, 2)

and so forth until the nVars row of data. Immediately following is the data matrix, containing the value of each variable at each time step.

Data Matrices

There can be several matrices for a simulation, and each of them has a specific name data_<index>, where <index> is the index of the matrix. Data matrices are always of type double. The information concerning these matrices is extracted from the previous matrix, dataInfo, as is the location of the values of interest.