npy

README

npy

A Go library for reading and writing NumPy's .npy and .npz file formats with support for mixed types and Go generics.

Features

• Type-safe API using Go generics
• Support for all common NumPy data types (bool, int8/16/32/64, uint8/16/32/64, float32/64)
• Read/write single arrays (.npy files)
• Read/write multiple arrays (.npz files)
• Support for multi-dimensional arrays
• Support for both row-major (C order) and column-major (Fortran order) arrays

Installation

go get github.com/datumbrain/npy

Import

import "github.com/datumbrain/npy"

Usage Examples

Working with .npy Files

Creating and Writing a NumPy Array

package main

import (
    "fmt"
    "log"

    "github.com/datumbrain/npy"
)

func main() {
    // Create a 2x3 float64 matrix
    data := []float64{1.0, 2.0, 3.0, 4.0, 5.0, 6.0}
    shape := []int{2, 3}

    // Create a NumPy array
    arr := &npy.Array[float64]{
        Data:    data,
        Shape:   shape,
        DType:   npy.Float64,
        Fortran: false, // Use row-major (C) order
    }

    // Write to a .npy file
    err := npy.WriteFile("matrix.npy", arr)
    if err != nil {
        log.Fatalf("Failed to write array: %v", err)
    }

    fmt.Println("Array successfully written to matrix.npy")
}

Reading a NumPy Array

package main

import (
    "fmt"
    "log"

    "github.com/datumbrain/npy"
)

func main() {
    // Read a .npy file with float64 data
    arr, err := npy.ReadFile[float64]("matrix.npy")
    if err != nil {
        log.Fatalf("Failed to read array: %v", err)
    }

    // Print shape
    fmt.Printf("Array shape: %v\n", arr.Shape)

    // Access data
    fmt.Printf("Element at (0,0): %f\n", arr.Data[0])

    // Calculate index for position [1,2] in a 2x3 matrix
    // Index = row*width + col = 1*3 + 2 = 5
    fmt.Printf("Element at (1,2): %f\n", arr.Data[5])
}

Working with .npz Files

Creating and Writing Multiple Arrays

package main

import (
    "fmt"
    "log"

    "github.com/datumbrain/npy"
)

func main() {
    // Create first array (float64)
    arr1 := &npy.Array[float64]{
        Data:    []float64{1.0, 2.0, 3.0, 4.0},
        Shape:   []int{2, 2},
        DType:   npy.Float64,
        Fortran: false,
    }

    // Create second array (int32)
    arr2 := &npy.Array[int32]{
        Data:    []int32{5, 6, 7, 8, 9},
        Shape:   []int{5},
        DType:   npy.Int32,
        Fortran: false,
    }

    // Create NPZ file
    npzFile := npy.NewNPZFile()

    // Add arrays to NPZ file
    npy.Add(npzFile, "matrix", arr1)
    npy.Add(npzFile, "vector", arr2)

    // Write NPZ file
    err := npy.WriteNPZFile("data.npz", npzFile)
    if err != nil {
        log.Fatalf("Failed to write NPZ file: %v", err)
    }

    fmt.Println("NPZ file successfully written to data.npz")
}

Reading Multiple Arrays

package main

import (
    "fmt"
    "log"

    "github.com/datumbrain/npy"
)

func main() {
    // Read NPZ file
    npzFile, err := npy.ReadNPZFile("data.npz")
    if err != nil {
        log.Fatalf("Failed to read NPZ file: %v", err)
    }

    // List all arrays in the file
    fmt.Printf("Arrays in NPZ file: %v\n", npy.Keys(npzFile))

    // Get float64 array
    matrix, ok := npy.Get[float64](npzFile, "matrix")
    if !ok {
        log.Fatal("Matrix not found in NPZ file")
    }

    // Get int32 array
    vector, ok := npy.Get[int32](npzFile, "vector")
    if !ok {
        log.Fatal("Vector not found in NPZ file")
    }

    // Print data
    fmt.Printf("Matrix: %v\n", matrix.Data)
    fmt.Printf("Vector: %v\n", vector.Data)
}

Working with Different Types

The library supports all common NumPy data types:

// Create arrays with different types
boolArr := &npy.Array[bool]{
    Data:  []bool{true, false, true},
    Shape: []int{3},
    DType: npy.Bool,
}

int8Arr := &npy.Array[int8]{
    Data:  []int8{-1, 0, 1},
    Shape: []int{3},
    DType: npy.Int8,
}

uint16Arr := &npy.Array[uint16]{
    Data:  []uint16{100, 200, 300},
    Shape: []int{3},
    DType: npy.Uint16,
}

float32Arr := &npy.Array[float32]{
    Data:  []float32{1.1, 2.2, 3.3},
    Shape: []int{3},
    DType: npy.Float32,
}

Multi-dimensional Arrays

When working with multi-dimensional arrays, remember that NumPy arrays are stored in either:

• C order (row-major, default): last dimension varies fastest
• Fortran order (column-major): first dimension varies fastest

For example, a 2x3 array in C order would have elements in this sequence:

[0,0], [0,1], [0,2], [1,0], [1,1], [1,2]

When specifying multi-dimensional data, ensure your Go slice follows this ordering based on your Fortran flag.

API Reference

Types

• DType: String type representing NumPy data types

  • Constants: Bool, Int8, Int16, Int32, Int64, Uint8, Uint16, Uint32, Uint64, Float32, Float64

• Array[T]: Generic struct representing a NumPy array

  • Data []T: The array data
  • Shape []int: The dimensions of the array
  • DType DType: The data type
  • Fortran bool: If true, the array is in column-major (Fortran) order

• NPZFile: Struct representing a NumPy .npz file containing multiple arrays

Functions

For .npy Files

• ReadFile[T any](path string) (*Array[T], error): Read a NumPy array from a .npy file
• WriteFile[T any](path string, arr *Array[T]) error: Write a NumPy array to a .npy file
• Read[T any](r io.Reader) (*Array[T], error): Read a NumPy array from an io.Reader
• Write[T any](w io.Writer, arr *Array[T]) error: Write a NumPy array to an io.Writer

For .npz Files

• NewNPZFile() *NPZFile: Create a new empty NPZ file container
• Add[T any](npz *NPZFile, name string, arr *Array[T]): Add an array to an NPZ file
• Get[T any](npz *NPZFile, name string) (*Array[T], bool): Get an array from an NPZ file
• Keys(npz *NPZFile) []string: Get all array names in an NPZ file
• ReadNPZFile(path string) (*NPZFile, error): Read multiple NumPy arrays from a .npz file
• WriteNPZFile(path string, npz *NPZFile) error: Write multiple NumPy arrays to a .npz file

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Documentation

Index

• func Add[T any](npz *NPZFile, name string, arr *Array[T])
• func Keys(npz *NPZFile) []string
• func Write[T any](w io.Writer, arr *Array[T]) error
• func WriteFile[T any](path string, arr *Array[T]) error
• func WriteNPZFile(path string, npz *NPZFile) error
• type Array
  • func Get[T any](npz *NPZFile, name string) (*Array[T], bool)
  • func Read[T any](r io.Reader) (*Array[T], error)
  • func ReadFile[T any](path string) (*Array[T], error)
• type DType
• type NPZFile
  • func NewNPZFile() *NPZFile
  • func ReadNPZFile(path string) (*NPZFile, error)

Functions

func Add

func Add[T any](npz *NPZFile, name string, arr *Array[T])

Add adds an array to the NPZ file

func Keys

func Keys(npz *NPZFile) []string

Keys returns the names of all arrays in the NPZ file

func Write

func Write[T any](w io.Writer, arr *Array[T]) error

Write writes a NumPy array to an io.Writer

func WriteFile

func WriteFile[T any](path string, arr *Array[T]) error

WriteFile writes a NumPy array to a .npy file

func WriteNPZFile

func WriteNPZFile(path string, npz *NPZFile) error

WriteNPZFile writes multiple NumPy arrays to a .npz file

Types

type Array

type Array[T any] struct {
	Data    []T
	Shape   []int
	DType   DType
	Fortran bool // True if array is in Fortran order (column-major)
}

Array represents a NumPy array with type parameter for data

func Get

func Get[T any](npz *NPZFile, name string) (*Array[T], bool)

Get retrieves an array from the NPZ file

func Read

func Read[T any](r io.Reader) (*Array[T], error)

Read reads a NumPy array from an io.Reader

func ReadFile

func ReadFile[T any](path string) (*Array[T], error)

ReadFile reads a NumPy array from a .npy file with the specified type

type DType

type DType string

DType represents NumPy data types

const (
	Bool    DType = "bool"
	Int8    DType = "int8"
	Int16   DType = "int16"
	Int32   DType = "int32"
	Int64   DType = "int64"
	Uint8   DType = "uint8"
	Uint16  DType = "uint16"
	Uint32  DType = "uint32"
	Uint64  DType = "uint64"
	Float32 DType = "float32"
	Float64 DType = "float64"
)

NumPy data types

type NPZFile

type NPZFile struct {
	// contains filtered or unexported fields
}

NPZFile represents a NumPy .npz file containing multiple arrays

func NewNPZFile

func NewNPZFile() *NPZFile

NewNPZFile creates a new empty NPZ file

func ReadNPZFile

func ReadNPZFile(path string) (*NPZFile, error)

ReadNPZFile reads multiple NumPy arrays from a .npz file