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.

✨ 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)

go get github.com/scigolib/matlab

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)
		}
	}
}

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)
	}
}

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)
	}
}

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

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

• ✅ 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.

• 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

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

# 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

# Run all tests
make test

# Run with coverage
make test-coverage

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

# Run linter
make lint

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)

Contributions are welcome! This is a stable 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:

• 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%)

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

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

• 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

• 📖 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