Skip to content

v0.2.0 - Stable Release

Choose a tag to compare

View all tags
@kolkov kolkov released this 21 Nov 18:12
· 9 commits to main since this release
v0.2.0
c3b4e84

🎉 MATLAB File Reader/Writer v0.2.0 - Stable Release

We're excited to announce v0.2.0 - the first stable release! 🚀

After 2 months of battle-testing since v0.2.0-beta, we're confident in marking this release as production-ready. This release upgrades to stable HDF5 dependency and maintains all the powerful features from the beta.

✨ What's New in v0.2.0 Stable

🎯 Stable Release

  • STABLE: Graduated from beta to stable version
  • HDF5 v0.13.1: Upgraded from v0.11.5-beta to stable HDF5 dependency
  • Production-Ready: 2 months of testing, zero regressions
  • Backward Compatible: Full compatibility with v0.2.0-beta
  • SECURITY.md: Comprehensive security policy added

📊 Quality Metrics

  • ✅ Tests: 100% passing (all platforms: Linux, macOS, Windows)
  • ✅ Coverage: 78.5% (main), 51.8% (v5), 48.8% (v73)
  • ✅ Linter: 0 errors, 0 warnings (34+ linters)
  • ✅ Race Detector: 0 data races detected
  • ✅ CI/CD: All platforms GREEN

🚀 Complete Feature Set

v5 Format (MATLAB v5-v7.2) - Legacy Binary Format

Reader:

  • ✅ All numeric types (double, single, int8-64, uint8-64)
  • ✅ Complex numbers (real + imaginary parts)
  • ✅ Multi-dimensional arrays (1D, 2D, 3D, N-D)
  • ✅ Both endianness (MI little-endian, IM big-endian)
  • ✅ Multiple variables per file
  • ✅ Fixed: Critical parser bugs (tag format detection, dimensions)

Writer:

  • ✅ All numeric types with proper encoding
  • ✅ Complex numbers (proper v5 format)
  • ✅ Multi-dimensional arrays
  • ✅ Both endianness support
  • ✅ Proper 8-byte alignment and padding
  • ✅ 565 lines of production-quality code

v7.3 Format (MATLAB v7.3+) - HDF5-Based Format

Reader:

  • ✅ HDF5 signature detection
  • ✅ All numeric datasets
  • ✅ Complex numbers (proper MATLAB group structure)
  • ✅ MATLAB_class attributes
  • ✅ Multi-dimensional datasets

Writer:

  • ✅ HDF5 file creation
  • ✅ All numeric types with MATLAB_class attributes
  • ✅ Complex numbers (nested datasets with /real, /imag)
  • ✅ Multi-dimensional arrays
  • ✅ Full MATLAB/Octave compatibility

Cross-Platform Support

  • ✅ Windows (x86, x64)
  • ✅ Linux (x86, x64, ARM)
  • ✅ macOS (Intel, Apple Silicon)
  • ✅ Pure Go (no CGo required for v5)

📖 Installation

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

🔧 Quick Start

Reading MATLAB Files

package main

import (
    "fmt"
    "os"
    "github.com/scigolib/matlab"
)

func main() {
    // Open any MATLAB file (v5 or v7.3 - auto-detected)
    file, _ := os.Open("data.mat")
    defer file.Close()

    matFile, err := matlab.Open(file)
    if err != nil {
        panic(err)
    }

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

Writing MATLAB Files

package main

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

func main() {
    // Create v5 file
    writer, _ := matlab.Create("output.mat", matlab.Version5)
    defer writer.Close()

    // Write a matrix
    writer.WriteVariable(&matlab.Variable{
        Name:       "mymatrix",
        Dimensions: []int{2, 3},
        DataType:   matlab.Double,
        Data:       []float64{1.0, 2.0, 3.0, 4.0, 5.0, 6.0},
    })

    // Or create v7.3 file (HDF5-based)
    writer73, _ := matlab.Create("output_v73.mat", matlab.Version73)
    defer writer73.Close()

    writer73.WriteVariable(&matlab.Variable{
        Name:       "data",
        Dimensions: []int{100},
        DataType:   matlab.Double,
        Data:       make([]float64, 100),
    })
}

Complex Numbers

// Write complex array
complexData := &types.NumericArray{
    Real: []float64{1.0, 2.0, 3.0},
    Imag: []float64{4.0, 5.0, 6.0},
}

writer.WriteVariable(&matlab.Variable{
    Name:       "complex_data",
    Dimensions: []int{3},
    DataType:   matlab.Double,
    Data:       complexData,
    IsComplex:  true,
})

🔒 Security

This release includes a comprehensive SECURITY.md policy covering:

  • Supported versions and security updates
  • Vulnerability reporting process
  • Binary format parsing security considerations
  • Best practices for handling untrusted MATLAB files
  • Known security considerations and mitigations

See SECURITY.md for details.

📋 What Changed from v0.2.0-beta

Changed

  • HDF5 Dependency: Upgraded from v0.11.5-beta to v0.13.1 (stable)
  • Status: Marked as stable and production-ready
  • Documentation: Updated README, ROADMAP, CHANGELOG

Added

  • SECURITY.md: Comprehensive security policy and best practices

Quality

  • Zero Regressions: All tests passing, no breaking changes
  • Backward Compatible: Drop-in replacement for v0.2.0-beta
  • Production Tested: 2 months of real-world usage

📚 Documentation

🎯 Use Cases

This library is perfect for:

  • Scientific Computing: Read/write MATLAB data in Go applications
  • Data Migration: Convert between MATLAB and other formats
  • Interoperability: Exchange data between MATLAB and Go systems
  • Testing: Generate test data for MATLAB/Octave
  • CI/CD: Automate MATLAB file processing in pipelines
  • Cross-Platform: Process MATLAB files without MATLAB installation

⚠️ Known Limitations

Not Yet Implemented (Planned for Future Versions)

  • Compression support (v5 GZIP, v7.3 filters)
  • Structures (read/write)
  • Cell arrays (read/write)
  • Sparse matrices (full support)
  • Function handles (not planned - MATLAB-specific)

What Works Well ✅

  • All numeric types (integers, floats)
  • Multi-dimensional arrays (any dimensions)
  • Complex numbers (proper format)
  • Round-trip verified (write → read → verify)
  • Cross-platform (Windows, Linux, macOS)

See CHANGELOG.md for complete details.

🚦 Migration from Beta

If you're using v0.2.0-beta:

# Simply update to v0.2.0
go get -u github.com/scigolib/[email protected]

No code changes required - API is fully backward compatible!

🙏 Acknowledgments

This release is made possible by:

  • HDF5 Go Library (v0.13.1) - for v7.3 format support
  • SciGoLib Community - for testing and feedback
  • MATLAB/MathWorks - for file format documentation
  • All contributors - for making this library better

🔮 What's Next?

v0.3.0 (planned in 2-3 weeks):

  • Functional Options Pattern for flexible API
  • Context support for cancellable operations
  • Additional examples and documentation

v1.0.0 (target: mid-2026):

  • API stability guarantee
  • Comprehensive feature completeness
  • Long-term support (LTS)

See ROADMAP.md for details.

📞 Support

⭐ Star Us!

If you find this library useful, please consider:

  • ⭐ Starring the repository
  • 📢 Sharing with colleagues
  • 🐛 Reporting bugs
  • 💡 Suggesting features
  • 🤝 Contributing code

Thank you for using MATLAB File Reader/Writer! 🎉

Built with ❤️ by the SciGoLib community

Full Changelog: v0.1.1-beta...v0.2.0

Assets 2
Loading