MATLAB File Reader/Writer for Go

Pure Go implementation for reading AND writing MATLAB .mat files - No CGo required

A modern, pure Go library for reading and writing MATLAB .mat files without CGo dependencies. Part of the SciGoLib scientific computing ecosystem.

Features

✨ Read & Write Support

📖 Read MATLAB v5-v7.2 files (traditional format)
📖 Read MATLAB v7.3+ files (HDF5 format)
✍️ Write MATLAB v7.3+ files (HDF5 format)
✍️ Write MATLAB v5-v7.2 files (traditional format) - NEW in v0.2.0!

🎯 Key Capabilities

Simple, intuitive API
Zero external C dependencies
Type-safe data access
Comprehensive error handling
Round-trip verified (write → read → verify)

📊 Data Types

All numeric types (double, single, int8-64, uint8-64)
Complex numbers
Multi-dimensional arrays
Character arrays
Structures
Cell arrays
Sparse matrices
Compressed data (reading)

Installation

go get github.com/scigolib/matlab

Quick Start

Reading MAT-Files

package main

import (
	"fmt"
	"log"
	"os"

	"github.com/scigolib/matlab"
)

func main() {
	// Open MAT-file
	file, err := os.Open("data.mat")
	if err != nil {
		log.Fatal(err)
	}
	defer file.Close()

	// Parse MAT-file (auto-detects v5 or v7.3)
	mat, err := matlab.Open(file)
	if err != nil {
		log.Fatal(err)
	}

	// Access variables
	for _, v := range mat.Variables {
		fmt.Printf("%s: %s %v\n", v.Name, v.DataType, v.Dimensions)

		// Access data based on type
		if data, ok := v.Data.([]float64); ok {
			fmt.Println("Data:", data)
		}
	}
}

Writing MAT-Files

v7.3 Format (HDF5-based)

package main

import (
	"log"

	"github.com/scigolib/matlab"
	"github.com/scigolib/matlab/types"
)

func main() {
	// Create new MAT-file (v7.3 format)
	writer, err := matlab.Create("output.mat", matlab.Version73)
	if err != nil {
		log.Fatal(err)
	}
	defer writer.Close()

	// Write a variable
	err = writer.WriteVariable(&types.Variable{
		Name:       "mydata",
		Dimensions: []int{3, 2},
		DataType:   types.Double,
		Data:       []float64{1.0, 2.0, 3.0, 4.0, 5.0, 6.0},
	})
	if err != nil {
		log.Fatal(err)
	}

	// Write complex numbers
	err = writer.WriteVariable(&types.Variable{
		Name:       "z",
		Dimensions: []int{2},
		DataType:   types.Double,
		IsComplex:  true,
		Data: &types.NumericArray{
			Real: []float64{1.0, 2.0},
			Imag: []float64{3.0, 4.0},
		},
	})
	if err != nil {
		log.Fatal(err)
	}
}

v5 Format (Traditional Binary) - NEW in v0.2.0!

package main

import (
	"log"

	"github.com/scigolib/matlab"
	"github.com/scigolib/matlab/types"
)

func main() {
	// Create new MAT-file (v5 format - legacy compatible)
	writer, err := matlab.Create("output_v5.mat", matlab.Version5)
	if err != nil {
		log.Fatal(err)
	}
	defer writer.Close()

	// Write a simple array
	err = writer.WriteVariable(&types.Variable{
		Name:       "A",
		Dimensions: []int{3},
		DataType:   types.Double,
		Data:       []float64{1.0, 2.0, 3.0},
	})
	if err != nil {
		log.Fatal(err)
	}

	// Write a matrix (multi-dimensional)
	err = writer.WriteVariable(&types.Variable{
		Name:       "B",
		Dimensions: []int{2, 3},
		DataType:   types.Double,
		Data:       []float64{1, 2, 3, 4, 5, 6},
	})
	if err != nil {
		log.Fatal(err)
	}

	// Write complex numbers
	err = writer.WriteVariable(&types.Variable{
		Name:       "C",
		Dimensions: []int{2},
		DataType:   types.Double,
		IsComplex:  true,
		Data: &types.NumericArray{
			Real: []float64{1.0, 2.0},
			Imag: []float64{3.0, 4.0},
		},
	})
	if err != nil {
		log.Fatal(err)
	}
}

Supported Features

Reader Support

Feature	v5 (v5-v7.2)	v7.3+ (HDF5)
Numeric arrays	✅	✅
Complex numbers	✅	✅
Character arrays	✅	✅
Multi-dimensional	✅	✅
Structures	✅	✅
Cell arrays	✅	✅
Sparse matrices	✅	✅
Compression	✅	✅
Function handles	❌ Out of scope	❌ Out of scope
Objects	❌ Out of scope	❌ Out of scope

Writer Support

Feature	v5 (v5-v7.2)	v7.3+ (HDF5)
Numeric arrays	✅	✅
Complex numbers	✅	✅
Character arrays	✅	✅
Multi-dimensional	✅	✅
Both endianness	✅ MI/IM	N/A
Structures	📅 v0.5.0+	📅 v0.5.0+
Cell arrays	📅 v0.5.0+	📅 v0.5.0+
Compression	📅 v0.5.0+	📅 v0.5.0+

Known Limitations

Writer Limitations

No compression support (planned for v0.5.0+)
No structures/cell arrays writing (planned for v0.5.0+)

Reader Limitations

Function handles not supported (MATLAB-specific, cannot be serialized)
Objects not supported (language-specific)

What Works Well ✅

✅ v5 Writer COMPLETE - All numeric types, complex numbers, multi-dimensional arrays
✅ v7.3 Writer COMPLETE - Full HDF5-based writing
✅ Parser bugs FIXED - Multi-dimensional arrays, multiple variables
✅ All numeric types (double, single, int8-64, uint8-64)
✅ Multi-dimensional arrays (read & write)
✅ Complex numbers (proper MATLAB format for both v5 and v7.3)
✅ Round-trip verified (v5 write → read, v7.3 write → read)
✅ Cross-platform (Windows, Linux, macOS)
✅ Both endianness (MI/IM for v5)

See CHANGELOG.md for detailed limitations and planned fixes.

Documentation

Getting Started - Basic usage examples
API Reference - Full API documentation
Architecture - Internal architecture and design decisions
CHANGELOG.md - Version history and changes
ROADMAP.md - Future plans and development timeline

Development

Requirements

Go 1.25 or later
HDF5 library (for v7.3+ support): github.com/scigolib/hdf5 develop branch (commit 36994ac)
No external C dependencies

Building

# Clone repositories (side-by-side)
cd D:\projects\scigolibs
git clone https://github.com/scigolib/hdf5.git
git clone https://github.com/scigolib/matlab.git

# Build MATLAB library
cd matlab
make build

# Run tests
make test

# Run linter
make lint

# Generate test data
go run scripts/generate-testdata/main.go

# Verify round-trip
go run scripts/verify-roundtrip/main.go

Testing

# Run all tests
make test

# Run with coverage
make test-coverage

# Run specific tests
go test ./internal/v73 -v

# Run linter
make lint

Test Data

The project includes test data in testdata/:

testdata/generated/ - Files created by our writer (8 files)
testdata/scipy/ - Reference files from SciPy project (3 files)

Contributing

Contributions are welcome! This is a stable project and we'd love your help.

Before contributing:

Read CONTRIBUTING.md - Git workflow and development guidelines
Check open issues
Review the architecture in .claude/CLAUDE.md

Ways to contribute:

🐛 Report bugs
💡 Suggest features
📝 Improve documentation
🔧 Submit pull requests
⭐ Star the project
🧪 Test with real MATLAB files and report compatibility

Priority Areas:

Test MATLAB/Octave compatibility with real-world files
Add compression support for v5/v7.3 writers
Implement structures and cell arrays writing
Improve test coverage (current: 92.8%)

Comparison with Other Libraries

Feature	This Library	go-hdf5/*	matlab-go
Pure Go	✅ Yes	❌ CGo required	✅ Yes
v5-v7.2 Read	✅ Yes	❌ Limited	⚠️ Partial
v7.3+ Read	✅ Yes	❌ No	❌ No
Write Support	✅ v5 + v7.3 Yes	❌ No	❌ No
Complex Numbers	✅ Yes	⚠️ Limited	❌ No
Maintained	✅ Active	❌ Inactive	❌ Inactive
Cross-platform	✅ Yes	⚠️ Platform-specific	✅ Yes

Related Projects

HDF5 Go Library - Pure Go HDF5 implementation (used for v7.3+ support)
Part of SciGoLib - Scientific computing libraries for Go

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

The MathWorks for the MATLAB file format specification
The HDF Group for HDF5 format specification
scigolib/hdf5 for HDF5 support
SciPy project for reference test data
All contributors to this project

Support

📖 Documentation - See .claude/CLAUDE.md for architecture details
🐛 Issue Tracker
💬 Discussions - GitHub Discussions (coming soon)
📧 Contact - Via GitHub Issues

Status: ✅ STABLE - Production-ready read and write support for both v5 and v7.3 formats! Last Updated: 2026-03-30

Ready for: Production use, testing, feedback, and real-world usage Stable API: Minor API changes may occur in 0.x versions, major stability expected

Built with ❤️ by the SciGoLib community

📚 matlab - Awesome Go Library for Science and Data Analysis

Detailed Description of matlab