Binsparse Python Reference Implementation

This library is a reference implementation of the Binsparse Binary Sparse Format Specification written using Python.

Binsparse is a cross-platform, embeddable format for storing sparse matrices and tensors. This library implements Binsparse bindings for NumPy NPZ, HDF5, and Zarr containers, with conversion interfaces for NumPy, SciPy, PyTorch, and PyData/Sparse.

Python Binsparse Interface

The primary interface consists of load_binsparse and save_binsparse. These functions select a container from the path extension (.npz, .h5/.hdf5, or .zarr) and read or write a BinsparseTensor:

from binsparse import load_binsparse, save_binsparse

tensor = load_binsparse("input.h5")
save_binsparse(tensor, "output.npz")

Parsed tensors expose their logical shape, number_of_stored_values, optional fill value, and the arrays that define their storage format. Concrete tensor classes represent the predefined Binsparse formats, including dense vectors and matrices, compressed sparse rows and columns, doubly compressed matrices, and coordinate formats. CustomTensor and the level classes (DenseLevel, SparseLevel, and ElementLevel) represent arbitrary level-based format descriptors.

For applications that already manage their own storage objects, the lower-level BinsparseContainer interface separates tensor parsing and serialization from the physical container. Adapters are provided for NPZ mappings, HDF5 files, Zarr groups, and in-memory descriptors and buffers. Use BinsparseTensor.parse(container) to read through an adapter and tensor.serialize(container) to write through one.

The alias option controls whether predefined format names such as CSR are preserved or expanded to custom level descriptors. The copy option allows a caller to request a copy, permit whichever representation is required, or require a zero-copy operation when the source and destination support it.

binsparse.conversions exports the following conversion functions:

• NumPy: from_numpy and to_numpy
• SciPy: from_scipy and to_scipy
• PyTorch: from_torch and to_torch
• PyData/Sparse: from_sparse and to_sparse

NumPy support is included by default; the other adapters require their corresponding optional dependency.

SciPy, PyData/Sparse, and PyTorch COO imports sort indices and sum duplicate entries before constructing a Binsparse tensor, without modifying the source. copy=False requires canonical (sorted, duplicate-free) input; PyTorch COO tensors must be coalesced first. PyTorch CSR/CSC imports rely on PyTorch's sorted, unique index invariants.

Source

The source code for binsparse is available on GitHub at https://github.com/Binsparse/binsparse-reference-python

Installation

binsparse is available on PyPi, and can be installed with pip:

pip install binsparse