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

[kolkov]

We're thrilled to announce that MATLAB File Reader/Writer has reached its first stable release - v0.2.0! 🚀

After 2 months of rigorous testing since v0.2.0-beta, we're confident in marking this release as production-ready. This is a major milestone for the project and the Go scientific computing ecosystem.

---

🎯 What Makes v0.2.0 Special?

From Beta to Stable

This is our first stable release, transitioning from beta to production-ready status:

• ✅ 2 months of battle-testing since v0.2.0-beta
• ✅ Zero regressions - all features work perfectly
• ✅ HDF5 v0.13.1 stable - upgraded from beta dependency
• ✅ Production-ready quality - 78.5% test coverage, 0 linter errors
• ✅ Comprehensive security policy - SECURITY.md added

Why This Matters

MATLAB File Reader/Writer is now the first pure Go library with complete bidirectional MATLAB file I/O support for both v5 (legacy) and v7.3 (HDF5) formats!

No more cgo required for v5 files. No more MATLAB installation needed. Just pure Go.

---

🚀 What Can You Do With v0.2.0?

Read MATLAB Files (Any Version)

import "github.com/scigolib/matlab"

file, _ := os.Open("data.mat")
matFile, _ := matlab.Open(file) // Auto-detects v5 or v7.3

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

Write MATLAB Files (Both Formats)

// v5 format (legacy, compatible with MATLAB R14-R2006b)
writer, _ := matlab.Create("output.mat", matlab.Version5)
writer.WriteVariable(&matlab.Variable{
    Name:       "mydata",
    Dimensions: []int{3, 4},
    Data:       []float64{1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12},
})
writer.Close()

// v7.3 format (HDF5-based, modern MATLAB)
writer73, _ := matlab.Create("output_v73.mat", matlab.Version73)
// ... same API

Handle Complex Numbers

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

writer.WriteVariable(&matlab.Variable{
    Name:      "signal",
    Data:      complexData,
    IsComplex: true,
})

---

📊 By The Numbers

Quality Metrics

• 100% passing tests on all platforms (Linux, macOS, Windows)
• 78.5% code coverage (main package)
• 0 linter errors (34+ linters including security checks)
• 0 data races detected
• 565 lines of production v5 writer code
• 434 lines of comprehensive security documentation

What's Supported

✅ All numeric types: double, single, int8/16/32/64, uint8/16/32/64
✅ Complex numbers: Real + imaginary parts (proper MATLAB format)
✅ Multi-dimensional arrays: 1D, 2D, 3D, N-D
✅ Both endianness: MI (little-endian), IM (big-endian) for v5
✅ Multiple variables: Read/write multiple variables per file
✅ Round-trip verified: Write → Read → Verify working perfectly
✅ Cross-platform: Windows, Linux, macOS (including ARM)

---

🔒 Security First

This release includes a comprehensive SECURITY.md policy that covers:

• Binary format parsing vulnerabilities and mitigations
• Integer overflow protection
• Resource exhaustion prevention
• Compression bomb safeguards (when compression is added)
• Best practices for handling untrusted MATLAB files
• Responsible disclosure process

We take security seriously. All binary parsing is bounds-checked, validated, and tested.

---

🎓 Real-World Use Cases

Scientific Computing

// Process experimental data from MATLAB
data := readMATLABExperiment("results.mat")
analysis := performGoAnalysis(data)
writeMATLABReport("report.mat", analysis)

Data Migration

// Convert legacy MATLAB data to modern format
v5File, _ := matlab.Open(oldFile)
v73Writer, _ := matlab.Create("modern.mat", matlab.Version73)
for _, variable := range v5File.Variables() {
    v73Writer.WriteVariable(variable)
}

CI/CD Integration

// Automated testing with MATLAB reference data
func TestAlgorithm(t *testing.T) {
    reference := loadMATLABReference("test_data.mat")
    result := myAlgorithm(input)
    assert.Equal(t, reference, result)
}

Cross-Platform Tools

// Build Go tools that work with MATLAB files
// No MATLAB installation required!
cmd := cobra.Command{
    Use: "mat-convert",
    Run: func(cmd *cobra.Command, args []string) {
        // Convert MATLAB files anywhere
    },
}

---

📈 Performance Characteristics

Memory Efficient

• Streaming I/O for large files
• Zero-copy operations where possible
• Lazy loading of variable data

Fast Parsing

• v5 parser: Custom state machine (no reflection)
• v7.3 parser: Thin wrapper around optimized HDF5 library
• Format detection: Single signature check

Production-Ready

• No panics - all errors returned properly
• Thread-safe - concurrent reads supported
• Resource cleanup - proper Close() semantics

---

🛣️ What's Next?

v0.3.0 (Planned in 2-3 Weeks)

Functional Options Pattern:

// More flexible API with options
writer, _ := matlab.Create("output.mat",
    matlab.WithVersion(matlab.Version5),
    matlab.WithEndianness(matlab.BigEndian),
    matlab.WithDescription("My awesome data"),
)

Context Support:

// Cancellable operations
ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
defer cancel()

matFile, err := matlab.OpenWithContext(ctx, file)

v1.0.0 (Target: Mid-2026)

• API stability guarantee (semver 2.0)
• Compression support (v5 GZIP, v7.3 filters)
• Structures and cell arrays (read/write)
• Sparse matrices (full support)
• Long-term support (LTS)

See our ROADMAP for details.

---

📦 Installation & Upgrade

New Users

go get github.com/scigolib/matlab@v0.2.0

Upgrading from v0.2.0-beta

go get -u github.com/scigolib/matlab@v0.2.0

No code changes required - fully backward compatible!

Upgrading from v0.1.x

Check the CHANGELOG for breaking changes (if any).

---

🙏 Thank You!

This release wouldn't be possible without:

• HDF5 Go Library team - for the excellent v0.13.1 stable release
• Early adopters - for testing and feedback on beta versions
• Contributors - for bug reports and suggestions
• SciGoLib community - for supporting scientific computing in Go

Special thanks to everyone who tested v0.2.0-beta and provided valuable feedback!

---

📚 Resources

• GitHub Release: https://github.com/scigolib/matlab/releases/tag/v0.2.0
• Documentation: https://pkg.go.dev/github.com/scigolib/matlab@v0.2.0
• CHANGELOG: https://github.com/scigolib/matlab/blob/main/CHANGELOG.md
• ROADMAP: https://github.com/scigolib/matlab/blob/main/ROADMAP.md
• SECURITY: https://github.com/scigolib/matlab/blob/main/SECURITY.md
• Contributing Guide: https://github.com/scigolib/matlab/blob/main/CONTRIBUTING.md

---

💬 Join The Conversation

We'd love to hear from you!

• 🐛 Found a bug? Open an issue
• 💡 Have an idea? Start a discussion
• 🤝 Want to contribute? See CONTRIBUTING.md
• ⭐ Like the project? Give us a star on GitHub!

---

🎯 Call to Action

Try It Out!

# Quick start
mkdir matlab-test && cd matlab-test
go mod init example
go get github.com/scigolib/matlab@v0.2.0

# Create a simple program
cat > main.go << 'EOF'
package main

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

func main() {
    // Create a simple MATLAB file
    writer, _ := matlab.Create("hello.mat", matlab.Version5)
    defer writer.Close()

    writer.WriteVariable(&matlab.Variable{
        Name:       "message",
        Dimensions: []int{1, 5},
        Data:       []float64{72, 101, 108, 108, 111}, // "Hello"
    })

    fmt.Println("Created hello.mat with Go!")
}
EOF

go run main.go

Share Your Experience

We'd love to hear how you're using MATLAB File Reader/Writer!

• What problems are you solving?
• What features would you like to see?
• Any success stories to share?

Comment below or start a new discussion! 💬

---

🌟 Star History

If you find this project useful, please consider starring it on GitHub! ⭐

Your support helps us:

• Gain visibility in the Go community
• Attract more contributors
• Justify continued development
• Show appreciation for the work

⭐ Star us on GitHub →

---

🎉 Celebrating The Milestone

v0.2.0 stable is a major milestone:

• 🥇 First stable release - Production-ready quality
• 🚀 Complete feature set - Both read and write for v5 & v7.3
• 🔒 Security-focused - Comprehensive security documentation
• 📈 High quality - 100% passing tests, 0 linter errors
• 🌍 Cross-platform - Works everywhere Go works

Thank you for being part of this journey!

We're excited to see what you'll build with MATLAB File Reader/Writer. 🎊

---

Built with ❤️ by the SciGoLib community

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