A Lightweight, Modern C++ library for reading & writing NumPy files

Version 2.197 (Release Notes ↗)

SyNumpy ↗ is a lightweight, Open-source C++17 library with comprehensive support for .npy and .npz NumPy files, developed by PixLab. It enables seamless integration of Python’s data structures into C++ applications, facilitating efficient reading, writing, and manipulation of multidimensional arrays. Designed for flexibility, SyNumpy ↗ ensures high performance and easy compatibility across platforms.

• Features
• Getting Started
• C++17 API Reference Guide

Features

SyNumpy ↗ provides robust tools for handling .npy and .npz files, including array loading and saving, append mode for extending data dimensions, and precise endian checks for system compatibility. Its core component, NpyArray, stores array shapes, data, and metadata efficiently in memory. Optional .npz support enables zip-based archiving for compact storage, ensuring flexibility and ease of use across various projects.

• NpyArray: A container that stores the loaded array’s shape, word size, fortran order, and data in memory.

• Load & Save:
  • syNumpy::loadNpy(...) reads from a file.
  • syNumpy::loadNpyBuffer(...) reads from a raw memory buffer.
  • syNumpy::saveNpy(...) writes or appends data.

• Append Mode: Save with mode = "a" to extend the first dimension of an existing file (if shapes match).

• Endian Checks: Warn if the file is big-endian while the system is little-endian (or vice versa). No auto-swapping.

• Optional NPZ: -DSYNUMPY_ENABLE_NPZ=1 enables zip-based .npz archiving (requires zlib). Minimal example included.

Getting Started

To use syNumpy in your C++17 project, start by including the syNumpy.hpp header file. Ensure that you compile your project with the -std=c++17 flag. Additionally, for .npz archiving, you can optionally define SYNUMPY

• Include syNumpy.hpp in your C++17 project.
• Compile with -std=c++17.
• Optional: Define SYNUMPY_ENABLE_NPZ=1 for .npz archiving.

Minimal Example

#include "syNumpy.hpp"
#include <iostream>

int main() {
    // 1) Save a float array
    {
        std::vector<float> data = {1.0f, 2.0f, 3.0f};
        syNumpy::saveNpy("floats.npy", data); // overwrites if file exists
    }

    // 2) Load it back
    {
        syNumpy::NpyArray arr = syNumpy::loadNpy("floats.npy");
        std::vector<float> loaded = arr.asVector<float>();
        std::cout << "Loaded " << loaded.size() << " floats: ";
        for (auto f : loaded) std::cout << f << " ";
        std::cout << "\n";
    }

#if SYNUMPY_ENABLE_NPZ
    // 3 Create a .npz archive with multiple arrays
    {
        syNumpy::NpzArchive zip;
        std::vector<int> arr1 = {10, 20, 30};
        std::vector<double> arr2 = {3.14, 2.71};
        zip.addArray("ints", arr1);
        zip.addArray("doubles", arr2);
        zip.save("arrays.npz");
    }
#endif
    return 0;
}

C++17 API REFERENCE GUIDE

This is the C++ interface for SyNumpy. Documentation is being updated until the libraries reach a stable release. Developers integrating SyNumpy into their C++ codebase should periodically check this page for updated documentation of the exported C++ API once stable.