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.
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.
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.
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)|
|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.
- 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|
An integer specifying the number of rows in the matrix.
An integer specifying the number of columns in the matrix.
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.
An integer specifying the length in bytes plus one (null terminated) of the matrix name.
A null-terminated string of namlen ASCII bytes.
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 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.
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.
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.
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.
If a variable does not have an associated description, the line is filled with blanks.
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,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.
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.
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.