MATIO

MATLAB MAT file I/O library

Status

Table of Contents

1. Introduction

• 1.1 Contact
• 1.2 Acknowledgements
• 1.3 Contributing
• 1.4 Questions and Reporting Bugs

2. Building

• 2.1 Dependencies
  • 2.1.1 zlib
  • 2.1.2 HDF5
• 2.2 Building matio
  • 2.2.1 Quick Build Guide
  • 2.2.2 Configure Options
  • 2.2.3 CMake build system
  • 2.2.4 Visual Studio
  • 2.2.5 Testsuite
• 2.3 Platforms

3. License

1.0 Introduction

Matio is an open-source C library for reading and writing binary MATLAB MAT files. This library is designed for use by programs/libraries that do not have access or do not want to rely on MATLAB's shared libraries.

1.1 Contact

You can contact the maintainer through email at t-beu@users.sourceforge.net.

1.2 Acknowledgements

The following people/organizations have helped in the development of matio through patches, bug reports, and/or testing:

• Don Zimmer
• Greg Sjaardema
• Jacco van Beek
• John Filo
• LTX Simulation
• Maarten Bent
• Modelica Association
• Nelson
• Nils Jannasch
• OpenMEEG
• Scilab
• Sébastien Villemot
• SGI in support of Interactive Supercomputing, Inc.
• Steven Leibman

1.3 Contributing

If you are interested in collaborations, contact the maintainer via email (see section 1.1).

1.4 Questions and Reporting Bugs

Questions can be asked using the forums on the sourceforge site hosting matio.

Bugs, enhancements, etc. should be submitted using one of the trackers on the sourceforge page.

2.0 Building

This section describes how to build matio. Section 2.1 describes the dependencies, section 2.2 how to build/test matio, and section 2.3 documents the platforms matio has been tested on.

2.1 Dependencies

Matio has two optional dependencies. These are not required for the software to work, but without them some files may be unreadable. Zlib is required to read/write level 5 MAT files that use compression. HDF5 is required to work with newer MAT files that use the HDF5-format files.

2.1.1 zlib

To support compressed MAT files, zlib version ≥ 1.2.3 is required. The zlib software can be downloaded from http://zlib.net/.

2.1.2 HDF5

Support for MAT file version 7.3 requires the HDF5 library of version ≥ 1.8.x. This library can be downloaded from https://github.com/HDFGroup/hdf5/releases. Neither deprecated HDF5 1.6.x API functions nor HDF5 higher-level functions are called.

• Building matio with HDF5 1.8.x requires configuration of HDF5 with default API v18.
• Building matio with HDF5 1.10.x requires configuration of HDF5 with either default API v110 or with deprecated API v18.
• Building matio with HDF5 1.12.x requires configuration of HDF5 with either default API v112, or with deprecated APIs v110 or v18.
• Building matio with HDF5 1.14.x requires configuration of HDF5 with either default API v114, or with deprecated APIs v112, v110 or v18.
• Building matio with HDF5 2.0.0 requires configuration of HDF5 with either default API v200, or with deprecated APIs v114, v112, v110 or v18.

For Ubuntu, sudo apt install libhdf5-dev should work fine.

2.2 Building matio

2.2.1 Quick Build Guide

The primary method for building the software is with GNU autotools using configure followed by make. After building, the testsuite can be executed to test the software using make check. The software can be installed using make install. For example,

git clone git://git.code.sf.net/p/matio/matio
cd matio
git submodule update --init  # for datasets used in unit tests
./autogen.sh
./configure
make
make check
make install

If any of the tests in the testsuite fail, you should report the failure using the tracker (see section 1.4). You should attach the generated testsuite.log file to the bug report.

2.2.2 Configure Options

The configure script used to build the software takes a number of options. This section describes the key options.

• --enable-mat73=yes This flag enables the support for version 7.3 MAT files. The option only makes sense if built with HDF5 as support for version 7.3 files. It will be disabled if HDF5 is not available.
• --enable-extended-sparse=yes This option enables extended sparse matrix data types not supported in MATLAB. MATLAB only supports double-precision sparse data. With this flag, matio will read sparse data with other types (i.e. single-precision and integer types).
• --with-matlab=DIR This option specifies the directory (DIR) with the 'matlab' program. With this option, the testsuite will check that the MAT files written by matio can be read into MATLAB. Without this, the test will only check that matio can read the file written and if successful the test will be skipped. If matio can not read the file, the test will fail.
• --with-zlib=DIR This option specifies the prefix where zlib is installed (see section 2.1.1 for information about zlib).
• --with-hdf5=DIR This option specifies the prefix where the HDF5 software is installed (see section 2.1.2 for information about HDF5).
• --with-default-file-ver=version This option sets the default MAT file version (4,5,7.3) that will be used when writing. The default file version is used by the Mat_Create macro and the Mat_CreateVer function when MAT_FT_DEFAULT is used for the version argument.
• --with-libdir-suffix=suffix This option specifies a suffix to apply to library directories when installing and looking for dependent libraries (i.e. HDF5 and zlib). For example, some multi-arch Linux distributions install 64-bit libraries into lib64 and 32-bit libraries into lib.

2.2.3 CMake build system

The CMake build system is supported as an alternative build system, which usually consists of three steps for configuration, build and installation. By default, the CMake project is also configured for testing with CTest. For example,

git clone git://git.code.sf.net/p/matio/matio
cd matio
git submodule update --init  # for datasets used in unit tests
cmake .
cmake --build .
ctest --test-dir .
cmake --install .

The following matio specific options for building with CMake are available.

• MATIO_DEFAULT_FILE_VERSION:STRING=5 This option sets the default MAT file version (4,5,7.3) that will be used when writing.
• MATIO_EXTENDED_SPARSE:BOOL=ON This option enables extended sparse matrix data types not supported in MATLAB.
• MATIO_MAT73:BOOL=ON This flag enables the support for version 7.3 MAT files.
• MATIO_PIC:BOOL=ON This option enables position-independent code (PIC), i.e., compilation with the -fPIC flag. It is ignored for Visual Studio builds.
• MATIO_SHARED:BOOL=ON This option builds the matio library as shared object (i.e., a dynamic link library on Windows).
• MATIO_WITH_HDF5:BOOL=ON This option enables CMake to check for availability of the HDF5 library (see section 2.1.2 for information about HDF5).
• MATIO_WITH_ZLIB:BOOL=ON This option enables CMake to check for availability of the zlib library (see section 2.1.1 for information about zlib).
• MATIO_BUILD_TESTING:BOOL=ON This option enables the matio testsuite for CTest.
• MATIO_ENABLE_CPPCHECK:BOOL=OFF This