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 (partial support)
• Cell arrays (partial support)

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	⚠️ Partial	✅
Structures	⚠️ Partial	⚠️ Partial
Cell arrays	⚠️ Partial	⚠️ Partial
Sparse matrices	❌	⚠️ Limited
Compression	❌	❌
Function handles	❌	❌
Objects	❌	❌

Writer Support (v0.2.0)

Feature	v5 (v5-v7.2)	v7.3+ (HDF5)
Numeric arrays	✅	✅
Complex numbers	✅	✅
Character arrays	⚠️ Partial	✅
Multi-dimensional	✅	✅
Both endianness	✅ MI/IM	N/A
Structures	❌ Future	❌ Future
Cell arrays	❌ Future	❌ Future
Compression	❌ Future	❌ Future

Known Limitations (v0.2.0-beta)

Writer Limitations

• No compression support yet
• No structures/cell arrays writing yet
• Character arrays (partial support for v5 Writer)

Reader Limitations

• Limited support for structures and cell arrays
• No compression support

What Works Well ✅

• ✅ v5 Writer COMPLETE - All numeric types, complex numbers, multi-dimensional arrays ✨ NEW in v0.2.0-beta
• ✅ v7.3 Writer COMPLETE - Full HDF5-based writing
• ✅ Parser bugs FIXED - Multi-dimensional arrays, multiple variables ✨ FIXED in v0.2.0-beta
• ✅ 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 an early-stage beta project and we'd love your help.

Before contributing:

1. Read CONTRIBUTING.md - Git workflow and development guidelines
2. Check open issues
3. 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:

• Implement v5 writer (TASK-011)
• Fix reader bugs (multi-dimensional arrays, multiple variables)
• Test MATLAB/Octave compatibility
• Improve test coverage (target: 80%+)

---

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	✅ 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: Beta - Read and Write support for both v5 and v7.3 formats! Version: v0.2.0-beta Last Updated: 2025-11-06

Ready for: Testing, feedback, and real-world usage Not ready for: Production use (API may change)

---

Built with ❤️ by the SciGoLib community