MATLAB
®
MAT-File Format
R2020a
How to Contact MathWorks
Latest news:
www.mathworks.com
Sales and services:
www.mathworks.com/sales_and_services
User community:
www.mathworks.com/matlabcentral
Technical support:
www.mathworks.com/support/contact_us
Phone: 508-647-7000
The MathWorks, Inc.
1 Apple Hill Drive
Natick, MA 01760-2098
MAT-File Format
© COPYRIGHT 1999–2020 by The MathWorks, Inc.
The software described in this document is furnished under a license agreement. The software may be used or copied
only under the terms of the license agreement. No part of this manual may be photocopied or reproduced in any form
without prior written consent from The MathWorks, Inc.
FEDERAL ACQUISITION: This provision applies to all acquisitions of the Program and Documentation by, for, or through
the federal government of the United States. By accepting delivery of the Program or Documentation, the government
hereby agrees that this software or documentation qualies as commercial computer software or commercial computer
software documentation as such terms are used or dened in FAR 12.212, DFARS Part 227.72, and DFARS 252.227-7014.
Accordingly, the terms and conditions of this Agreement and only those rights specied in this Agreement, shall pertain
to and govern the use, modication, reproduction, release, performance, display, and disclosure of the Program and
Documentation by the federal government (or other entity acquiring for or through the federal government) and shall
supersede any conicting contractual terms or conditions. If this License fails to meet the government's needs or is
inconsistent in any respect with federal procurement law, the government agrees to return the Program and
Documentation, unused, to The MathWorks, Inc.
Trademarks
MATLAB and Simulink are registered trademarks of The MathWorks, Inc. See
www.mathworks.com/trademarks for a list of additional trademarks. Other product or brand names may be
trademarks or registered trademarks of their respective holders.
Patents
MathWorks products are protected by one or more U.S. patents. Please see www.mathworks.com/patents for
more information.
Revision History
June 1999 Online only New for MATLAB
®
5.3 (Release 11)
November 2000 PDF only Revised for MATLAB
®
6.0 (Release 12)
June 2001 PDF only Revised for MATLAB
®
6.1 (Release 12.1)
July 2002 PDF only Revised for MATLAB
®
6.5 (Release 13)
January 2003 PDF only Revised for MATLAB
®
6.5.1 (Release 13 SP1)
June 2004 PDF only Revised for MATLAB
®
7.0 (Release 14)
October 2004 PDF only Revised for MATLAB
®
7.0.1 (Release 14SP1)
September 2005 PDF only Minor revision for MATLAB
®
7.1 (Release 14SP3)
September 2007 PDF only Rereleased for Version 7.5 (Release 2007b)
March 2008 PDF only Revised for Version 7.6 (Release 2008a)
October 2008 PDF only Rereleased for Version 7.7 (Release 2008b)
March 2009 PDF only Rereleased for Version 7.8 (Release 2009a)
September 2009 PDF only Rereleased for Version 7.9 (Release 2009b)
March 2010 PDF only Rereleased for Version 7.10 (Release 2010a)
September 2010 PDF only Rereleased for Version 7.11 (Release 2010b)
April 2011 PDF only Rereleased for Version 7.12 (Release 2011a)
September 2011 PDF only Rereleased for Version 7.13 (Release 2011b)
March 2012 PDF only Rereleased for Version 7.14 (Release 2012a)
September 2012 PDF only Rereleased for Version 8.0 (Release 2012b)
March 2013 PDF only Rereleased for Version 8.1 (Release 2013a)
September 2013 PDF only Rereleased for Version 8.2 (Release 2013b)
March 2014 PDF only Rereleased for Version 8.3 (Release 2014a)
October 2014 PDF only Minor revision for Version 8.4 (Release 2014b)
March 2015 PDF only Rereleased for Version 8.5 (Release 2015a)
September 2015 PDF only Rereleased for Version 8.6 (Release 2015b)
March 2016 PDF only Rereleased for Version 9.0 (Release 2016a)
September 2016 PDF only Rereleased for Version 9.1 (Release 2016b)
March 2017 PDF only Rereleased for Version 9.2 (Release 2017a)
September 2017 PDF only Rereleased for Version 9.3 (Release 2017b)
March 2018 PDF only Rereleased for Version 9.4 (Release 2018a)
September 2018 PDF only Rereleased for Version 9.5 (Release 2018b)
March 2019 PDF only Rereleased for Version 9.6 (Release 2019a)
September 2019 PDF only Rereleased for Version 9.7 (Release 2019b)
March 2020 PDF only Rereleased for Version 9.8 (Release 2020a)
MAT-File Format
1
Introduction .................................................. 1-2
MAT-File Formats ........................................... 1-2
Level 5 MAT-File Format ........................................ 1-3
MAT-File Header Format ...................................... 1-3
Data Element Format ........................................ 1-4
Data Compression .......................................... 1-6
Level 5 MATLAB Array Data Element Formats ...................... 1-8
Numeric Array and Character Array Data Element Formats ........... 1-8
Sparse Array Data Element Format ............................. 1-12
Cell Array Data Element Format ............................... 1-15
Structure MAT-File Data Element Format ........................ 1-16
MATLAB Object MAT-File Data Element Format ................... 1-18
Level 4 MAT-File Format ....................................... 1-21
v
Contents
MAT-File Format
“Introduction” on page 1-2 Describes Level 5 and Level 4 MAT-les and how
to access them.
“Level 5 MAT-File Format” on page 1-3 Describes the internal format of MAT-les that
are compatible with MATLAB Versions 5 and up.
“Level 5 MATLAB Array Data Element Formats”
on page 1-8
Shows how to use the Array data type to
represent all types of MATLAB arrays.
“Level 4 MAT-File Format” on page 1-21 Describes the internal format of MAT-les that
are compatible with MATLAB Versions 4 and
earlier.
1
Introduction
This document describes the internal format of MATLAB Level 4 and Level 5 MAT-les. Level 4 MAT-
les are compatible with versions of MATLAB up to Version 4. Level 5 MAT-les are compatible with
MATLAB Versions 5 and up. You can read and write Level 4 MAT-les with the later versions of
MATLAB, but when writing a MAT-le under these circumstances, you need to specify a switch in the
save or matOpen command line to tell MATLAB that the MAT-le is at Level 4.
A MAT-le stores data in binary (not human-readable) form. In MATLAB, you create MAT-les using
the save function, which writes the arrays currently in memory to a le as a continuous byte stream.
By convention, this le has the lename extension .mat; thus the name MAT-le. The load function
reads the arrays from a MAT-le into the MATLAB workspace.
Most MATLAB users do not need to know the internal format of a MAT-le. Even users who must read
and write MAT-les from C and Fortran programs do not need to know the MAT-le format if they use
the MAT-le interface. This interface shields users from dependence on the details of the MAT-le
format.
Note See "Importing and Exporting Data" in the MATLAB External Interfaces documentation for
information on the MAT-le interface. See "C [or Fortran] MAT-File Functions" in the MATLAB
External Interfaces Reference documentation for information on the functions available with this
interface.
However, if you need to read or write MAT-les on a system that does not support the MAT-le
interface, you must write your own read and write routines. The MAT-le interface is only available
for platforms on which MATLAB is supported. This document provides the details about the MAT-le
format you will need to read and write MAT-les on these systems.
Note Whenever possible, MathWorks strongly advises you to use the MAT-le interface functions to
read and write MAT-les. Any code you write that depends on the MAT-le format may need to be
rewritten when the format changes in future releases.
This document describes MAT-les from a big-endian perspective. The associated gures also reect
MAT-les written by a big-endian system. In MAT-les written by a little-endian system, the order of
bytes within each instance of a MAT-le data type is reversed.
MAT-File Formats
This document describes both Level 5 and Level 4 MAT-le formats. The Level 5 MAT-le format
supports all the array types supported in MATLAB Versions 5 and up, including multidimensional
numeric arrays, character arrays, sparse arrays, cell arrays, structures, and objects. “Level 5 MAT-
File Format” on page 1-3 describes this format.
The Level 4 MAT-le format is a simpler format, but it only supports two-dimensional matrices and
character strings. “Level 4 MAT-File Format” on page 1-21 describes this format.
1
MAT-File Format
1-2
Level 5 MAT-File Format
Level 5 MAT-les are made up of a 128-byte header followed by one or more data elements. Each data
element is composed of an 8-byte tag followed by the data in the element. The tag species the
number of bytes in the data element and how these bytes should be interpreted; that is, should the
bytes be read as 16-bit values, 32-bit values, oating-point values or some other data type.
By using tags, the Level 5 MAT-le format provides quick access to individual data elements within a
MAT-le. You can move through a MAT-le by nding a tag, and then skipping ahead the specied
number of bytes until the next tag.
“Figure 1-1, MATLAB Level 5 MAT-File Format” on page 1-3 graphically illustrates this MAT-le
format. The sections that follow provide more details about these MAT-le elements:
• “MAT-File Header Format” on page 1-3
• “Data Element Format” on page 1-4
• “Data Compression” on page 1-6
Figure 1-1, MATLAB Level 5 MAT-File Format
MAT-File Header Format
Level 5 MAT-les begin with a 128-byte header made up of a 124-byte text eld and two, 16-bit ag
elds.
This section covers the following topics:
• “Header Text Field” on page 1-3
• “Header Subsystem Data Oset Field” on page 1-4
• “Header Flag Fields” on page 1-4
Header Text Field
The rst 116 bytes of the header can contain text data in human-readable form. This text typically
provides information that describes how the MAT-le was created. For example, MAT-les created by
MATLAB include the following information in their headers:
• Level of the MAT-le (value equals 1 for Level 5)
• Platform on which the le was created
• Date and time the le was created
You can view the text in a MAT-le header using the cat command on UNIX
®
systems, or the type
command on a PC. The output displays the text in this part of the header. (The display of the header is
followed by unreadable characters representing the binary data in the le.)
cat my_matfile.mat
MATLAB 5.0 MAT-file, Platform: SOL2, Created on: Thu Nov 13
10:10:27 1997
Level 5 MAT-File Format
1-3
Note When creating a MAT-le, you must write data in the rst 4 bytes of this header. MATLAB uses
these bytes to determine if a MAT-le uses a Level 5 format or a Level 4 format. If any of these bytes
contains a zero, MATLAB will incorrectly assume the le is a Level 4 MAT-le.
Header Subsystem Data Oset Field
Bytes 117 through 124 of the header contain an oset to subsystem-specic data in the MAT-le. All
zeros or all spaces in this eld indicate that there is no subsystem-specic data stored in the le.
Header Flag Fields
The last 4 bytes in the header are divided into two, 16-bit ag elds (int16).
Field Value
Version When creating a MAT-le, set this eld to 0x0100.
Endian Indicator Contains the two characters, M and I, written to the MAT-le in this order, as a
16-bit value. If, when read from the MAT-le as a 16-bit value, the characters
appear in reversed order (IM rather than MI), it indicates that the program
reading the MAT-le must perform byte-swapping to interpret the data in the
MAT-le correctly.
Note Programs that create MAT-les always write data in their native machine format. Programs
that read MAT-les are responsible for byte-swapping.
Data Element Format
Each data element begins with an 8-byte tag followed immediately by the data in the element.
“Figure 1-2, MAT-File Data Element Format” on page 1-4 shows this format. (MATLAB also
supports a compressed data element format. See “Small Data Element Format” on page 1-6 for
more information.)
Figure 1-2, MAT-File Data Element Format
This section covers the following topics:
• “The Tag Field” on page 1-4
• “The Data Field” on page 1-6
• “Small Data Element Format” on page 1-6
• “Example Data Element” on page 1-6
The Tag Field
The 8-byte data element tag is composed of two, 32-bit elds:
• Data Type
• Number of Bytes
1
MAT-File Format
1-4
Data Type
The Data Type eld species how the data in the element should be interpreted, that is, its size and
format. The MAT-le format supports many data types including signed and unsigned, 8-bit, 16-bit,
32-bit, and 64-bit data types, a special data type that represents MATLAB arrays, Unicode
®
encoded
character data, and data stored in compressed format. The Table 1-1, MAT-File Data Types table lists
all these data types with the values used to specify them. The table also includes symbols that are
used to represent these data types in the examples in this document.
Table 1-1, MAT-File Data Types
Value Symbol MAT-File Data Type
1 miINT8 8 bit, signed
2 miUINT8 8 bit, unsigned
3 miINT16 16-bit, signed
4 miUINT16 16-bit, unsigned
5 miINT32 32-bit, signed
6 miUINT32 32-bit, unsigned
7 miSINGLE IEEE
®
754 single format
8 -- Reserved
9 miDOUBLE IEEE 754 double format
10 -- Reserved
11 -- Reserved
12 miINT64 64-bit, signed
13 miUINT64 64-bit, unsigned
14 miMATRIX MATLAB array
15 miCOMPRESSED Compressed Data
16 miUTF8 Unicode UTF-8 Encoded Character Data
17 miUTF16 Unicode UTF-16 Encoded Character Data
18 miUTF32 Unicode UTF-32 Encoded Character Data
The UTF-16 and UTF-32 encodings are in the byte order specied by the Endian Indicator (See
“Header Flag Fields” on page 1-4). UTF-8 is byte order neutral.
For character data that is not Unicode encoded, the Data Type part of the Tag eld should be set to
miUINT16.
For more information about the miMATRIX data type, see “Level 5 MATLAB Array Data Element
Formats” on page 1-8.
Number of Bytes
The Number of Bytes eld is a 32-bit value that species the number of bytes of data in the element.
This value does not include the 8 bytes of the data element's tag.
If Data Type is miCOMPRESSED, then the Number of Bytes eld contains the compressed MATLAB
array size in bytes. (See “Data Compression” on page 1-6.)
Level 5 MAT-File Format
1-5
The Data Field
The data immediately follows the tag. All data that is uncompressed must be aligned on 64-bit
boundaries. When writing a MAT-le, if the amount of data in a data element falls short of a 64-bit
boundary, you must add bytes of padding to make sure the tag of the next data element falls on a 64-
bit boundary. Likewise, when reading data from a MAT-le, be sure to account for these padding
bytes.
Note For data elements representing MATLAB arrays, (type miMATRIX), the value of the Number of
Bytes eld includes padding bytes in the total. For all other MAT-le data types, the value of the
Number of Bytes eld does not include padding bytes.
Small Data Element Format
If a data element takes up only 1 to 4 bytes, MATLAB saves storage space by storing the data in an 8-
byte format. In this format, the Data Type and Number of Bytes elds are stored as 16-bit values,
freeing 4 bytes in the tag in which to store the data. Figure 4 illustrates this format.
Figure 1-3, Small Data Element Format
Note When reading a MAT-le, you can tell if you are processing a small data element by comparing
the value of the rst 2 bytes of the tag with the value zero (0). If these 2 bytes are not zero, the tag
uses the small data element format. When writing to a MAT-le, use of the small data element format
is optional.
Example Data Element
“Figure 1-4, Example MAT-File Data Element” on page 1-6 illustrates a data element representing
an array of six 32-bit, unsigned integers: 1, 2, 3, 4, 5, 6. In the gure, the Data Type eld contains the
value from Table 1-1, MAT-File Data Types that species unsigned, 32-bit integers (miUINT32). The
Number of Bytes eld in the data element tag contains the number of data values multiplied by the
number of bytes used to represent each value. Note that this value does not include the 8 bytes in the
data element tag.
Figure 1-4, Example MAT-File Data Element
Data Compression
MATLAB compresses the data it saves to a MAT-le using buered in-memory zlib compression. It
compresses MATLAB variables transparently as they are written out to disk. This technique uses less
memory than systems that compress an entire variable at once before writing it out to disk. Also, no
temporary les are required to read or write compressed data.
1
MAT-File Format
1-6
Because it compresses each variable individually, MATLAB can read a compressed MAT-le like any
other MAT-le. No code changes are required at either the C or M level to read a compressed MAT-
le.
MATLAB compresses data for MAT-les (le I/O) only, not for sequential streams. The reason for this
is that the size of the compressed variable is known only after it is compressed, but it must be written
in the tag at the beginning of the variable. In a le it is possible to seek back and write the size, while
in a stream this cannot be done.
MAT-les containing compressed variables are nonplatform specic like any MAT-le, and such a le
saved on any MATLAB supported platform can be loaded on any other supported platform.
To decompress the contents of a compressed variable in a MAT-le, you can use the uncompress
function from the freeware zlib-1.1.4 library available at, http://www.gzip.org/zlib/. Once a
MATLAB array has been decompressed, you can ignore the miCOMPRESSED tag and process the data
normally, as if it had not been compressed.
Storing Compressed Data
MATLAB stores compressed data in zlib-compressed MATLAB arrays. Each compressed variable is
stored complete with its tags and data eld in the same format as uncompressed variables, as
described in “Data Element Format” on page 1-4. The dierence is that the entire variable is
compressed into a data buer, and this buer is preceded by an 8-byte tag named miCOMPRESSED.
The tag contains the length of the compressed buer.
Each variable in a MAT-le has a 56-byte header. Even if the data is stored in the header itself, as can
be the case for variables containing 1 to 4 bytes of data, no variable in a MAT-le can be less than 56
bytes. Thus, regardless of how random the data in a variable may be, it is unlikely (but not
impossible) that a compressed variable will take more space than its uncompressed counterpart. This
is because the 56-byte header always compresses to a smaller size. Note that compression works best
on nonrandom data. The more random the data, the less it will compress.
Level 5 MAT-File Format
1-7
Level 5 MATLAB Array Data Element Formats
The MAT-le data type miMATRIX (14) is used to represent all types of MATLAB arrays, including:
• Numeric arrays
• Character arrays
• Sparse arrays
• Cell arrays
• Structures
• Objects
The miMATRIX data type is a compound data type. MAT-le data elements of this type are composed
of multiple subelements. The subelements can be of any other MAT-le data type, including other
miMATRIX data types.
“Figure 1-5, MATLAB Array Data Element with Subelements” on page 1-8 shows a miMATRIX data
element composed of three subelements. Note how each subelement is a data element with its own
tag. The value of the Number of Bytes eld (96 in the gure) in the data element tag includes all the
subelements.
Figure 1-5, MATLAB Array Data Element with Subelements
Each miMATRIX data element representing the dierent types of MATLAB arrays each has a specic
set of subelements. Some of these subelements are common to all MATLAB arrays. Others
subelements are unique to a particular type of array. The following sections detail the subelements
for each MATLAB array type.
Numeric Array and Character Array Data Element Formats
A MAT-le data element representing a MATLAB numeric array or character array is composed of
four subelements and one optional subelement. Table 1-2, Numeric and Character Array Subelements
with Tag Data lists the subelements in the order in which they appear in the data element. The table
also includes the values of the Data Type and Number of Bytes elds you would use in the tag of each
subelement. For an example, see “Examples of Numeric Array Data Elements” on page 1-11.
1 MAT-File Format
1-8
Table 1-2, Numeric and Character Array Subelements with Tag Data
Subelement Data Type Number of Bytes
Array Flags miUINT32 2 * sizeOfDataType (8 bytes)
Dimensions Array miINT32 numberOfDimensions * sizeOfDataType
(To learn how to determine the number of
dimensions, see “Dimensions Array Subelement” on
page 1-10.)
Array Name miINT8 numberOfCharacters * sizeOfDataType
Real part (pr) Any of the numeric data
types.
numberOfValues * sizeOfDataType
Imaginary part (pi)
(Optional)
Any of the numeric data
types.
numberOfvalues * sizeOfDataType
Array Flags Subelement
This subelement identies the MATLAB array type (class) represented by the data element and
provides other information about the array. The Array Flags subelement is common to all array types.
“Figure 1-6, Array Flags Format” on page 1-9 illustrates the format of the Array Flags subelement.
(For sparse matrices, bytes 5 through 8 are used to store the maximum number of nonzero elements
in the matrix. See “Sparse Array Data Element Format” on page 1-12 for more information.)
Figure 1-6, Array Flags Format
Flags
This eld contains three, single-bit ags that indicate whether the numeric data is complex, global, or
logical. If the complex bit is set, the data element includes an imaginary part (pi). If the global bit is
set, MATLAB loads the data element as a global variable in the base workspace. If the logical bit is
set, it indicates the array is used for logical indexing.
Class
This eld contains a value that identies the MATLAB array type (class) represented by the data
element. Table 1-3, MATLAB Array Types (Classes) lists the MATLAB array types with the values you
use to specify them. The table also includes symbols that are used to represent the MATLAB array
type in the examples in this document.
Note The value of the Class eld identies the MATLAB data type. The value of the Data Type eld in
the data element tag identies the data type used to store the data in the MAT-le. The MAT-le data
types are listed in Table 1-1, MAT-File Data Types. The value of the Class and the Data Type elds do
not need to be the same; for more information, see “Automatic Compression of Numeric Data” on
page 1-11.
Level 5 MATLAB Array Data Element Formats
1-9
Table 1-3, MATLAB Array Types (Classes)
MATLAB Array Type (Class) Value Symbol
Cell array 1 mxCELL_CLASS
Structure 2 mxSTRUCT_CLASS
Object 3 mxOBJECT_CLASS
Character array 4 mxCHAR_CLASS
Sparse array 5 mxSPARSE_CLASS (Use of this
symbol is not recommended. Sparse
array is no longer classied
MATLAB class. To indicate the
sparse array type, use the numeric
value 5.)
Double precision array 6 mxDOUBLE_CLASS
Single precision array 7 mxSINGLE_CLASS
8-bit, signed integer 8 mxINT8_CLASS
8-bit, unsigned integer 9 mxUINT8_CLASS
16-bit, signed integer 10 mxINT16_CLASS
16-bit, unsigned integer 11 mxUINT16_CLASS
32-bit, signed integer 12 mxINT32_CLASS
32-bit, unsigned integer 13 mxUINT32_CLASS
64-bit, signed integer 14 mxINT64_CLASS
64-bit, unsigned integer 15 mxUINT64_CLASS
For numeric arrays, Class can contain any of the numeric array types: mxDOUBLE_CLASS,
mxSINGLE_CLASS, mxINT8_CLASS, mxUINT8_CLASS, mxINT16_CLASS, mxUINT16_CLASS,
mxINT32_CLASS, or mxUINT32_CLASS.
For character arrays, Class contains mxCHAR_CLASS.
Dimensions Array Subelement
This subelement species the size of each dimension of an n-dimensional array in an n-sized array of
32-bit values (miINT32). All numeric arrays have at least two dimensions. The Dimensions Array
subelement is common to all MATLAB array types.
For example, if a data element represents a 2-by-3-by-2 MATLAB array, the Dimensions Array
subelement would contain three values: 2, 3, and 2.
Note To calculate the number of dimensions in an array, divide the value stored in the Number of
Bytes eld in the Dimensions Array subelement tag by 4, the number of bytes in the data type
(miINT32) used in the subelement.
Array Name Subelement
This subelement species the name assigned to the array, as an array of signed, 8-bit values
(miINT8). This subelement is common to all array types.
1
MAT-File Format
1-10
Real Part (pr) Subelement
This subelement contains the numeric data in the MATLAB array. If the array contains complex
numbers (the complex bit in the Array Flags is set), this is the real part of the number.
The data type of the values can be any of the numeric data types listed in Table 1-1, MAT-File Data
Types.
For character data that is not Unicode encoded, the Data Type part of the Tag eld should be set to
miUINT16.
Imaginary Part (pi) Subelement
This subelement contains the imaginary part of the numeric data in the MATLAB array. This
subelement is only present if one or more of the numeric values in the MATLAB array is a complex
number (if the complex bit is set in Array Flags). The data type of the values can be any of the
numeric data types listed in Table 1-1, MAT-File Data Types.
Note When reading a MAT-le, check the value of the Data Type eld in the tag of Real Part and
Imaginary Part subelements to identify the data type used to store data. Also note that MATLAB reads
and writes these values in column-major order.
Automatic Compression of Numeric Data
MATLAB stores the numeric data in an array in double-precision format. When MATLAB writes a
numeric (or sparse) array to a MAT-le, ˋˋˋˋit uses the smallest one of miINT32, miUINT16,
miINT16, or miUINT8 to store the data, both the real and imaginary parts.
For example, if MATLAB determines that the data stored in double-precision format can actually be
stored in an 8-bit format, it will use an miUINT8 to store it in a MAT-le. Note, however, that if any of
the numeric values in the array requires a 64-bit representation, MATLAB stores all of the data in a
64-bit data type. See “Compressed Data Element” on page 1-12 for an example.
When you create a MAT-le, compressing data is optional.
Note When MATLAB uses a smaller data type to store data in a MAT-le, the value of the Class eld
in the Array Flags subelement identies the original MATLAB data type.
Examples of Numeric Array Data Elements
This section uses examples to illustrate both the compressed and uncompressed numeric array data
element formats.
Uncompressed Data Element
“Figure 1-7, Example Numeric Array MAT-File Data Element” on page 1-12 shows how this 2-by-2
numeric array, my_array, is represented in a MAT-le.
my_array = [ 1.1+1.1i 2 ; 3 4 ]
my_array =
Level 5 MATLAB Array Data Element Formats
1-11
1.1000 + 1.1000i 2.0000
3.0000 4.0000
In the gure, note:
• The data element includes ve subelements. Because one of the numeric values in the array is a
complex number, the complex bit ag in the Array Flags subelement is set and the Imaginary Part
(pi) subelement is included.
• The value of the Number of Bytes eld in the data element tag includes all the subelements, but
not the 8 bytes of the tag itself.
Figure 1-7, Example Numeric Array MAT-File Data Element
Compressed Data Element
“Figure 1-8, Example Numeric Array MAT-le Data Element (Compressed)” on page 1-12 shows how
the three-dimensional numeric array in this example, arr, is represented in a MAT-le when
compression is used to conserve storage space.
A = [ 1 2 3 ; 4 5 6 ];
B = [ 7 8 9 ; 10 11 12];
arr = cat(3,A,B)
arr(:,:,1) =
1 2 3
4 5 6
arr(:,:,2) =
7 8 9
10 11 12
In the gure, note:
• The Array Name subelement uses the compressed data element format.
• The numeric data in the array, stored in double-precision format in MATLAB, is stored as 8-bit,
unsigned values in the pr subelement. The Class eld in the Array Flags subelement identies the
original MATLAB data type.
Figure 1-8, Example Numeric Array MAT-le Data Element (Compressed)
Sparse Array Data Element Format
A MAT-le data element representing a MATLAB sparse array is composed of six subelements and one
optional subelement. Table 1-4, Sparse Array Subelements with Tag Data lists the subelements in the
order in which they appear in the data element. The table lists the values of the Data Type and
Number of Bytes elds of the tag for each subelement.
1
MAT-File Format
1-12
Table 1-4, Sparse Array Subelements with Tag Data
Subelement Data Type Number of Bytes
Array Flags miUINT32 2 * sizeOfDataType (8 bytes)
Dimensions Array miINT32 numberOfDimensions * sizeOfDataType
where numberOfdimensions can be 0, 1 or 2.
Array Name miINT8 numberOfcharacters * sizeOfDataType
Row Index (ir) miINT32 nzmax * sizeOfDataType
(The nzmax value is stored in Array Flags.)
Column Index (jc) miINT32 (N+1) * sizeof(int32)
where N is the second element of the Dimensions
array subelement.
Real part (pr) Any numeric data
type
numberOfNonzeroValues * sizeOfDataType
Imaginary part (pi)
(Optional)
Any numeric data
type
numberOfNonzeroValues * sizeOfDataType
Array Flags Subelement
This subelement identies the MATLAB array type (class) represented by the data element and
provides other information about the array. The Array Flags subelement is common to all array types.
“Figure 1-9, Array Flags Format for Sparse Arrays” on page 1-13 shows the Array Flags format. For
sparse arrays, this value also contains the maximum number of nonzero elements in the array
(nzmax).
Figure 1-9, Array Flags Format for Sparse Arrays
Flag
For more information, see “Flags” on page 1-9.
Class
This eld contains a value that identies the MATLAB data type represented by the data element. For
sparse arrays, Class contains the value 5. See “Class” on page 1-9 for more information.
Dimensions Array Subelement
This subelement species the size of each dimension of the array. This subelement is common to all
array types. For more information, see “Dimensions Array Subelement” on page 1-10.
Note that MATLAB only supports two-dimensional sparse arrays.
Array Name Subelement
This subelement species the name assigned to the array. This subelement is common to all array
types. For more information, see “Array Name Subelement” on page 1-10.
Level 5 MATLAB Array Data Element Formats
1-13
Row Index for Nonzero Values (ir) Subelement
This subelement species the row indices of the nonzero elements in the real part (pr) of the matrix
data and the imaginary part (pi) of the matrix data, if present. This subelement is a series of 32-bit
(miINT32) values.
Column Index for Nonzero Values (jc) Subelement
This subelement contains column index information as a series of 32-bit (miINT32) values. For more
information about what this subelement contains, see the MATLAB Application Program Interface
Guide.
Real Part (pr) Subelement
This subelement contains the numeric data in the MATLAB array. If the array contains complex
numbers (the complex bit in the Array Flags is set), this is the real part of the number.
Because MATLAB uses data compression to save storage space, the data type of the values can be
any of the numeric data types listed in Table 1-1, MAT-File Data Types. For more information, see
“Automatic Compression of Numeric Data” on page 1-11.
Imaginary Part (pi) Subelement
This subelement contains the imaginary data in the array, if one or more of the numeric values in the
MATLAB array is a complex number (if the complex bit is set in Array Flags).
Because MATLAB uses data compression to save storage space, the data type of the values can be
any of the numeric data types listed in Table 1-1, MAT-File Data Types. For more information, see
“Automatic Compression of Numeric Data” on page 1-11.
Note You must check the value of the Data Type eld in the tag of Real Part and Imaginary Part
subelements to identify the type of the data. Also note that MATLAB reads and writes these values in
column-major order.
Example Sparse Array
“Figure 1-10, Example Sparse Array MAT-le Data Element” on page 1-15 illustrates the MAT-le
data element format of this 3-by-3 sparse matrix:
a = [ 1 2 3 ];
S = sparse(a,a,a+.5)
S =
(1,1) 1.5000
(2,2) 2.5000
(3,3) 3.5000
In the gure, note:
• The data element contains six subelements.
• The value of the Number of Bytes eld in the data element tag includes all the subelements, but
not the 8 bytes of the tag itself.
1
MAT-File Format
1-14
• Bytes 5 through 8 of the Array Flags subelement contain the maximum number of nonzero
elements (nzmax) in the sparse array.
• The Array Name subelement uses the compressed data element format.
Figure 1-10, Example Sparse Array MAT-le Data Element
Note *The array ags portion of “Figure 1-10, Example Sparse Array MAT-le Data Element” on page
1-15 uses the symbol mxSPARSE_CLASS to indicate the array type. MATLAB no longer classies
sparse arrays as classes. Therefore, when programming, the use of the symbol mxSPARSE_CLASS is
not supported. Instead, use the value 5 to denote the array type as sparse. See “Class” on page 1-9
for more information.
Cell Array Data Element Format
A MAT-le data element representing a MATLAB cell array is composed of four subelements. Table
1-5, Cell Array Subelements with Tag Data lists the subelements in the order in which they appear in
the data element. The table lists the values of the Data Type and Number of Bytes elds of the tag for
each subelement.
Table 1-5, Cell Array Subelements with Tag Data
Subelement Data Type Number of Bytes
Array Flags miUINT32 2 * sizeOfDataType (8 bytes)
Dimensions Array miINT32 numberOfDimensions * sizeOfDataType
Array Name miINT8 numberOfcharacters * sizeOfDataType
Cells Each cell is written in place as an miMATRIX element.
Array Flags Subelement
This subelement identies the MATLAB array type (class) represented by the data element and
provides other information about the array. “Figure 1-11, Array Flags Format” on page 1-15 shows
the Array Flags format. The Array Flags subelement is common to all array types.
Figure 1-11, Array Flags Format
Flags
See “Flags” on page 1-9 for more information.
Class
This eld contains a value that identies the MATLAB data type represented by the data element. For
cell arrays, Class contains the value 1 (mxCELL_CLASS). For more information, see “Class” on page 1-
9.
Level 5 MATLAB Array Data Element Formats
1-15
Dimensions Array Subelement
This subelement species the size of each dimension of the array. This subelement is common to all
array types. For more information, see “Dimensions Array Subelement” on page 1-10.
Array Name Subelement
This subelement species the name assigned to the array. This subelement is common to all array
types. For more information, see “Array Name Subelement” on page 1-10.
Cells Subelement
This subelement contains the value stored in a cell. These values are MATLAB arrays, represented
using the miMATRIX format specic to the array type: numeric array, sparse array, structure, object
or other cell array. See the appropriate section in this document for details about the MAT-le
representation of a each of these array types. Cells are written in column-major order.
Example Cell Array
“Figure 1-12, Example Cell Array Data Element” on page 1-16 illustrates the MAT-le data element
format of this cell array:
A = [ 1 2 3 ; 4 5 6 ]
A =
1 2 3
4 5 6
B = [ 7 8 9 ; 10 11 12 ]
B =
7 8 9
10 11 12
C = { A, B }
C =
[2x3 double] [2x3 double]
In the gure, note:
• The data element contains ve subelements, the three common subelements; Array Flags,
Dimensions and Array Name; and two cell subelements.
• The value of the Number of Bytes eld in the data element tag includes all the subelements, but
not the 8 bytes of the tag itself.
• Each cell subelement is an miMATRIX type. In the example, each cell contains a numeric array. For
more information about the format of these elements, see “Numeric Array and Character Array
Data Element Formats” on page 1-8.
Figure 1-12, Example Cell Array Data Element
Structure MAT-File Data Element Format
A MAT-le data element representing a MATLAB structure is composed of six subelements. Table 1-6,
Structure Subelements with Tag Data lists the subelements in the order in which they appear in the
1
MAT-File Format
1-16
data element. The table lists the values of the Data Type and Number of Bytes elds of the tag for
each subelement.
Table 1-6, Structure Subelements with Tag Data
Subelements Data Type Number of Bytes
Array Flags miUINT32 2*sizeOfDataType (8 bytes)
Dimensions Array miINT32 numberOfDimensions * sizeOfDataType
Array Name miINT8 numberOfCharacters * sizeOfDataType
Field Name Length miINT32 sizeOfDataType (4 bytes)
Field Names miINT8 numberOfFields * FieldNameLength
Fields Each eld is written in place as an array. Fields are written in column order.
Array Flags Subelement
This subelement identies the MATLAB array type (class) represented by the data element and
provides other information about the array. “Figure 1-13, Array Flags Format” on page 1-17 shows
the Array Flags format. The Array Flags subelement is common to all array types.
Figure 1-13, Array Flags Format
Flags
See “Flags” on page 1-9 for more information.
Class
This eld contains a value that identies the MATLAB data type represented by the data element. For
structures, Class contains the value 2 (mxSTRUCT_CLASS). For more information, see “Class” on page
1-9.
Dimensions Array Subelement
This subelements Species the size of each dimension of the array. This subelement is common to all
array types. For more information, see “Dimensions Array Subelement” on page 1-10.
Array Name Subelement
This subelement species the name assigned to the structure. This subelement is common to all array
types. For more information, see “Array Name Subelement” on page 1-10.
Field Name Length Subelement
This subelement species the maximum length of a Field Name. MATLAB sets this limit to 32 (31
characters and a NULL terminator). In a MAT-le created by MATLAB, this subelement always uses
the compressed data element format.
Level 5 MATLAB Array Data Element Formats
1-17
Field Names Subelement
This subelement species the name of each eld in the structure as a series of 8-bit (miINT8)
character arrays. The value of the Field Name Length subelement determines the length of each eld
name array (32 bytes). Field names must be NULL-terminated.
Fields Subelement
This subelement contains the value stored in a eld. These values are MATLAB arrays, represented
using the miMATRIX format specic to the array type: numeric array, sparse array, cell, object or
other structure. See the appropriate section of this document for details about the MAT-le format of
each of these array type. MATLAB reads and writes these elds in column-major order.
Example
“Figure 1-14, Example Structure MAT-File Data Element” on page 1-18 illustrates the MAT-le data
element format for this MATLAB structure:
X.w = [1];
X.y = [2];
X.z = [3];
X
X =
w: 1
y: 2
z: 3
In the gure, note:
• The data element contains eight subelements: the three common subelements (Array Flags,
Dimensions and Array Name) and ve structure-specic subelements (Field Name Length, Field
Names, and three Field subelements).
• The value of the Number of Bytes eld in the data element tag includes all the subelements, but
not the 8 bytes of the tag itself.
• The Field Names subelement allocates 32 bytes of storage for each eld name. A NULL terminator
indicates the end of each eld name.
• Each Field subelement is an miMATRIX data type. In the example, each eld contains a numeric
array. For more information about the format of these elements, see “Numeric Array and
Character Array Data Element Formats” on page 1-8.
• Each of the numeric arrays contain zero-length Array Name subelements. The Field Names
subelement contains the names of the numeric arrays.
Figure 1-14, Example Structure MAT-File Data Element
MATLAB Object MAT-File Data Element Format
A MAT-le data element representing a MATLAB object is composed of seven subelements. Table 1-7,
MATLAB Object Subelements with Tag Data lists the subelements in the order in which they appear
in the data element. An object data element has the same subelements as a structure with the
1
MAT-File Format
1-18
addition of the Class Name subelement. The table lists the values of the Data Type and Number of
Bytes elds of the tag for each subelement.
Table 1-7, MATLAB Object Subelements with Tag Data
Subelement Data Type Number of Bytes
Array Flags miUINT32 2 * sizeOfDataType (8 bytes)
Dimensions Array miINT32 numberOfDimensions * sizeOfDataType
Array Name miINT8 numberOfCharacters * sizeOfDataType
Class Name miINT8 numberOfCharacters * sizeOfDataType
Field Name Length miINT32 sizeOfDataType (4 bytes)
Field Names miINT8 numberOfFields * FieldNameLength
Fields Each eld is written in place as an array.
Array Flags Subelement
This subelement identies the MATLAB array type (class) represented by the data element and
provides other information about the array. “Figure 1-15, Array Flags Format” on page 1-19 shows
the Array Flags format. The Array Flags subelement is common to all array types.
Figure 1-15, Array Flags Format
Flags
See “Flags” on page 1-9 for more information.
Class
This eld contains a value that identies the MATLAB data type represented by the data element. For
objects, the Class byte has the value 3 (mxOBJECT_CLASS). For more information, see “Class” on
page 1-9.
Dimensions Array Subelement
This subelement species the size of each dimension of the array. This subelement is common to all
array types. For more information, see “Dimensions Array Subelement” on page 1-10.
Array Name Subelement
This subelement species the name assigned to the array. This subelement is common to all array
types. For more information, see “Array Name Subelement” on page 1-10.
Class Name Subelement
This subelement species the name assigned to the object class. This subelement is an array of 8-bit
characters (miINT8).
Field Name Length Subelement
This subelement species the maximum length of a Field Name. See “Field Name Length
Subelement” on page 1-17 for more information.
Level 5 MATLAB Array Data Element Formats
1-19
Field Names Subelement
This subelement species the name of each eld in the structure. See “Field Names Subelement” on
page 1-18 for more information.
Fields Subelement
This subelement contains the value stored in a eld. See “Fields Subelement” on page 1-18 for more
information.
Example
“Figure 1-16, Example Object MAT-le Data Element” on page 1-20 illustrates how the MATLAB
object in this example is represented in a MAT-le.
X = inline(`t^2');
The gure only shows the rst four subelements of the object. For an example that shows the
remaining subelements, see “Example” on page 1-18.
In the gure, note:
• The Array Flag Class byte is set to mxOBJECT_CLASS.
• The data element includes the Class Name subelement.
Figure 1-16, Example Object MAT-le Data Element
1 MAT-File Format
1-20
Level 4 MAT-File Format
Note This section is taken from the MATLAB V4.2 External Interface Guide, which is no longer
available in printed form.
This section presents the internal structure of Level 4 MAT-les. This information is provided to
enable users to read and write MAT-les on machines for which the MAT-le access routine library is
not available. It is not needed when using the MAT-le subroutine library to read and write MAT-les,
and we strongly advise that you do use the External Interface Library if it is available for all of the
machines that you are working with.
A MAT-le may contain one or more matrices. The matrices are written sequentially on disk, with the
bytes forming a continuous stream. Each matrix starts with a xed-length 20-byte header that
contains information describing certain attributes of the Matrix. The 20-byte header consists of ve
long (4-byte) integers:
Level 4 MAT-File Format
1-21
Table 1-8, Level 4 MAT-File Matrix Header Format
Field Description
type The type ag contains an integer whose decimal digits encode storage information. If the
integer is represented as MOPT where M is the thousands digit, O 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 le. Use this
table to determine the number to use for your machine:
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-oat
3 VAX G-oat
4 Cray
O is always 0 (zero) and is reserved for future use.
P indicates which format the data is stored in according to the following table:
0 double-precision (64-bit) oating-point numbers
1 single-precision (32-bit) oating-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
oating-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, requiring fewer bytes per
element.
Element range Bytes per element
[0:255] 1
[0:65535] 2
[-32767:32767] 2
[-2^31+1:2^31-1] 4
other 8
T indicates the matrix type according to the following table:
0 Numeric (Full) matrix
1 Text matrix
2 Sparse matrix
Note that the elements of a text matrix are stored as oating-point numbers between 0 and
255 representing ASCII-encoded characters.
mrows The row dimension contains an integer with the number of rows in the matrix.
ncols The column dimension contains an integer with the number of columns in the matrix.
1 MAT-File Format
1-22
Field Description
imagf The imaginary ag is an integer whose value is either 0 or 1. If 1, then the matrix has an
imaginary part. If 0, there is only real data.
namlen The name length contains an integer with 1 plus the length of the matrix name.
Immediately following the xed length header is the data whose length is dependent on the variables
in the xed length header:
Table 1-9, Level 4 MAT-File Matrix Data Format
Field Description
name The matrix name consists of namlen ASCII bytes, the last one of which must
be a null character ('\0').
real Real part of the matrix consists of mrows * ncols numbers in the format
specied by the P element of the type ag. The data is stored column-wise
such that the second column follows the rst column, etc.
imag Imaginary part of the matrix, if any. If the imaginary ag imagf is nonzero,
the imaginary part of a matrix is placed here. It is stored in the same manner
as the real data.
This structure is repeated for each matrix stored in the le.
The following C language code demonstrates how to write a single matrix to disk in Level 1.0 MAT-le
format.
#include <stdio.h>
main() {
typedef struct {
long type;
long mrows;
long ncols;
long imagf;
long namelen;
} Fmatrix;
char *pname;
double *pr;
double *pi;
Fmatrix x;
int mn;
FILE *fp;
double real_data = 1.0;
double imag_data = 2.0;
fp = fopen("mymatfile.mat", "wb");
if (fp != NULL) {
pname = "x";
x.type = 1000;
x.mrows = 1;
x.ncols = 1;
x.imagf = 1;
x.namelen = 2;
Level 4 MAT-File Format
1-23
pr = &real_data;
pi = &imag_data;
fwrite(&x, sizeof(Fmatrix), 1, fp);
fwrite(pname, sizeof(char), x.namelen, fp);
mn = x.mrows *x.ncols;
fwrite(pr, sizeof(double), mn, fp);
if(x.imagf)
fwrite(pi, sizeof(double), mn, fp);
}
else
printf("File could not be opened.\n");
fclose(fp);
}
Again, we strongly advise against using this approach, and recommend that you instead use the MAT-
le access routines provided in the External Interface Library. You will need to write your own C code
as shown above only if you do not have the MAT-le access routines for the particular platform on
which you need to read and write MAT-les.
1 MAT-File Format
1-24
