Skip to content

🎉 MATLAB File Reader/Writer v0.1.0-beta - First Public Release

Pre-release
Pre-release

Choose a tag to compare

View all tags
@kolkov kolkov released this 02 Nov 20:41
· 23 commits to main since this release
v0.1.0-beta
c31eed6

Pure Go library for reading and writing MATLAB .mat files
Part of the SciGoLib ecosystem - scientific computing libraries for Go

🚀 What's New

Reader Support

  • ✅ Format auto-detection - v5 (MATLAB v5-v7.2) and v7.3+ (HDF5)
  • ✅ Public API: Open(io.Reader) - parse MATLAB files
  • ✅ Type system: Variable, DataType, NumericArray
  • ✅ Numeric types: double, single, int8-64, uint8-64
  • ✅ Complex numbers and multi-dimensional arrays
  • ✅ Partial support: structures, cell arrays

Writer Support ✨ NEW!

  • ✅ v7.3 Writer complete (HDF5-based)
  • ✅ Public API: Create(), WriteVariable(), Close()
  • ✅ All numeric types supported
  • ✅ Multi-dimensional arrays
  • ✅ Complex numbers (with workaround - see limitations)
  • ✅ Round-trip verified: write → read → ✅ PASSED

Infrastructure

  • ✅ CI/CD: GitHub Actions (Linux, macOS, Windows) - ALL GREEN
  • ✅ Code quality: golangci-lint with 34+ linters, 0 issues
  • ✅ Tests: 27 tests, 24 passing (88.9%)
  • ✅ Documentation: README, CONTRIBUTING, ROADMAP, API docs

📦 Installation

go get github.com/scigolib/[email protected]

🔧 Quick Start

Reading MATLAB Files

package main

import (
    "fmt"
    "os"

    "github.com/scigolib/matlab"
)

func main() {
    file, _ := os.Open("data.mat")
    defer file.Close()

    matFile, _ := matlab.Open(file)

    for _, variable := range matFile.Variables {
        fmt.Printf("Variable: %s, Type: %s, Dimensions: %v\n",
            variable.Name, variable.DataType, variable.Dimensions)
    }
}

Writing MATLAB Files

package main

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

func main() {
    writer, _ := matlab.Create("output.mat", matlab.Version73)
    defer writer.Close()

    variable := &types.Variable{
        Name:       "mydata",
        DataType:   types.Double,
        Dimensions: []int{3, 2},
        Data:       []float64{1.0, 2.0, 3.0, 4.0, 5.0, 6.0},
    }

    writer.WriteVariable(variable)
}

⚠️ Known Limitations (Beta Release)

Reader Limitations

  • ⚠️ 3 tests skipped due to bugs with multi-dimensional arrays and multiple variables
  • ⚠️ Structures/cell arrays: partial support only

Writer Limitations

  • ❌ v5 Writer not implemented - only v7.3 format supported (TASK-011 planned)
  • ⚠️ Complex numbers workaround: Uses flat structure (varname_real/varname_imag) instead of standard MATLAB groups
    • Reason: HDF5 library limitations (nested datasets, group attributes not supported)
    • Impact: Files readable by this library, may not be fully compatible with MATLAB/Octave
    • Fix: Will be resolved when HDF5 library v0.11.5-beta releases (1-2 weeks)
  • ❌ No compression support yet
  • ❌ No structures/cell arrays writing yet

What Works ✅

  • ✅ All numeric types (double, single, int8-64, uint8-64)
  • ✅ Multi-dimensional arrays
  • ✅ Complex numbers (with workaround format)
  • ✅ Round-trip write → read verified
  • ✅ Production-quality code (0 linter issues)

📚 Documentation

🔮 What's Next

v0.2.0 (3-4 weeks)

  • ⭐ v5 Writer implementation (TASK-011)
  • ⭐ Fix reader bugs (multi-dim arrays, multiple variables)
  • ⭐ Improve complex number format (when HDF5 v0.11.5-beta releases)

v0.3.0+ (Future)

  • Functional Options Pattern (flexible API)
  • Context Support (cancellable operations)
  • Compression support
  • Full structures/cell arrays support

v1.0.0 (2026)

  • Production stable release
  • API freeze and long-term support
  • Community feedback incorporated

🤝 Contributing

We welcome contributions! Please read CONTRIBUTING.md for guidelines.

Priority areas:

  • Test coverage improvements
  • Bug fixes for reader issues
  • v5 writer implementation
  • Documentation improvements

📞 Support

🙏 Dependencies

📝 License

MIT License - See LICENSE file for details

Full Changelog: https://github.com/scigolib/matlab/blob/main/CHANGELOG.md

🤖 Released with production-quality standards: 0 linter issues, CI all green, comprehensive testing

Assets 2
Loading