Skip to content

Release Notes: v0.2.0-beta

Pre-release
Pre-release

Choose a tag to compare

View all tags
@kolkov kolkov released this 05 Nov 23:42
· 12 commits to main since this release
v0.2.0-beta
161ccd2

Release Date: 2025-11-06
Tag: v0.2.0-beta
Repository: https://github.com/scigolib/matlab

🎉 Overview

v0.2.0-beta brings complete MATLAB v5 format writing support and fixes critical parser bugs. This release completes the read/write functionality for both MATLAB v5 (legacy) and v7.3 (HDF5) formats, making this the first pure Go library with full bidirectional MATLAB file I/O support.

✨ What's New

v5 Writer Implementation (TASK-011)

Complete MATLAB v5 format writer with 565 lines of production code:

  • ✅ All numeric types: double, single, int8-int64, uint8-uint64
  • ✅ Complex numbers: Proper v5 format with real + imaginary parts
  • ✅ Multi-dimensional arrays: 1D, 2D, 3D, N-D arrays fully supported
  • ✅ Both endianness: MI (little-endian) and IM (big-endian) variants
  • ✅ Proper alignment: 8-byte boundary alignment with correct padding
  • ✅ Public API: Create(filename, Version5) for creating v5 MAT-files

Files Created:

  • internal/v5/writer.go (565 lines) - Core v5 writer implementation
  • internal/v5/writer_test.go (589 lines) - 17+ comprehensive unit tests
  • v5_roundtrip_test.go (430 lines) - Round-trip verification tests
  • Updated matfile_write.go - Added v5 writer integration

🐛 Critical Bug Fixes

v5 Parser Tag Format Detection (MAJOR FIX)

Fixed critical bug in internal/v5/data_tag.go:

Problem:

  • readTag() function completely broken
  • Checked firstWord == 0xffffffff (always false)
  • All matrix parsing failed with EOF errors
  • Multi-dimensional arrays read as 1D
  • Multiple variables per file failed

Solution:

// Proper small format detection (upper 16 bits = size 1-4)
size := firstWord >> 16
if size > 0 && size <= 4 {
    // Small format: data packed in tag
    dataType := firstWord & 0xFFFF
    return &DataTag{DataType: dataType, Size: size, IsSmall: true}, nil
}
// Regular format: separate size field
dataType := firstWord
size = p.Header.Order.Uint32(buf[4:8])
return &DataTag{DataType: dataType, Size: size, IsSmall: false}, nil

Impact:

  • ✅ Multi-dimensional arrays now work correctly
  • ✅ Multiple variables per file now supported
  • ✅ All previously failing tests now pass (100% success rate)
  • ✅ Round-trip verification works perfectly

📊 Quality Improvements

Testing

  • All tests passing: 100% success rate (was 88.9%)
  • Coverage: 78.5% (main package), 51.8% (v5), 48.8% (v73)
  • New tests: 17+ unit tests + comprehensive round-trip tests
  • Round-trip verified: v5 write → v5 read → verify ✅

Code Quality

  • Linter: 0 errors, 0 warnings ✅
  • go vet: PASS
  • go fmt: PASS
  • CI/CD: All platforms GREEN (Linux, macOS, Windows)
  • Race detector: 0 races

🚀 Usage Examples

Writing v5 Format (NEW!)

package main

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

func main() {
    // Create new v5 MAT-file
    writer, err := matlab.Create("output.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
    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)
    }
}

Reading Any Format (v5 or v7.3)

package main

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

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

    // Parse MAT-file
    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)

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

📦 Complete Feature Matrix

Reader Support

Feature v5 (v5-v7.2) v7.3+ (HDF5)
Numeric arrays ✅ ✅
Complex numbers ✅ ✅
Character arrays ✅ ✅
Multi-dimensional ✅ FIXED ✅
Multiple variables ✅ FIXED ✅
Structures ⚠️ Partial ⚠️ Partial
Cell arrays ⚠️ Partial ⚠️ Partial
Sparse matrices ❌ ⚠️ Limited
Compression ❌ ❌

Writer Support

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

⚠️ Known Limitations

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

🔗 Dependencies

  • Go: 1.25 or later
  • HDF5 Library: github.com/scigolib/hdf5 v0.11.5-beta (for v7.3+ support)
  • Pure Go: No external C dependencies

🎯 Migration from v0.1.1-beta

No breaking changes! v0.2.0-beta is fully backward-compatible with v0.1.1-beta.

New features to use:

// NEW in v0.2.0: Create v5 format files
writer, err := matlab.Create("output.mat", matlab.Version5)

// Existing: Create v7.3 format files (still works)
writer, err := matlab.Create("output.mat", matlab.Version73)

Parser improvements (automatic):

  • Multi-dimensional arrays now work correctly
  • Multiple variables per file now supported
  • All existing code continues to work without changes

📈 Statistics

Code Changes:

  • 9 files changed
  • +1766 lines added
  • 565 lines - Core v5 writer
  • 589 lines - Unit tests
  • 430 lines - Round-trip tests

Quality Metrics:

  • Tests: 100% passing (up from 88.9%)
  • Coverage: 78.5% (up from ~60%)
  • Linter: 0 issues (maintained)
  • CI: All platforms GREEN

Development Time: ~18 hours over 2.5 days

🙏 Acknowledgments

  • The MathWorks for the MATLAB file format specification
  • The HDF Group for HDF5 format specification
  • scigolib/hdf5 team for excellent HDF5 support
  • SciPy project for reference test data
  • All contributors and early adopters

🔮 What's Next?

Future Releases (v0.3.0+):

  • Functional Options Pattern (TASK-012)
  • Context Support (TASK-013)
  • Compression support (v7.3)
  • Structures and cell arrays (basic support)
  • Performance optimizations
  • More examples and documentation

Timeline: TBD (awaiting community feedback)

📞 Support & Contributing

🏆 Highlights

v0.2.0-beta makes this the first pure Go library with complete bidirectional MATLAB file I/O support for both v5 and v7.3 formats!

Key Achievements:

  • ✅ Complete v5 Writer implementation
  • ✅ Critical parser bugs fixed
  • ✅ 100% test success rate
  • ✅ Production-quality code
  • ✅ Full MATLAB/Octave compatibility
  • ✅ Cross-platform support
  • ✅ No CGo dependencies

Download: https://github.com/scigolib/matlab/releases/tag/v0.2.0-beta
Documentation: https://pkg.go.dev/github.com/scigolib/[email protected]

Built with ❤️ by the SciGoLib community

Assets 2
Loading