NpyCpp

C++ API used for read/write *.npy/*.npz files


Project maintained by pmontalb Hosted on GitHub Pages — Theme by mattgraham

CI Coverage codecov

Npy++

A modern C++20 library for reading and writing NumPy .npy and .npz files, originally forked from rogersce/cnpy (see original README).

Implemented Functionalities

Known Limitations

Building & Testing

Linux (GCC / Clang)

Dependencies: CMake 3.28+, Ninja, zlib (zlib1g-dev), and GoogleTest (libgtest-dev, top-level builds only).

cmake -S . --preset=gcc-release
cmake --build --preset=gcc-release
ctest --preset=gcc-release --output-on-failure

Windows (MSVC + vcpkg)

Dependencies: Visual Studio / MSVC (C++20), CMake 3.28+, Ninja, and vcpkg (zlib, gtest with the x64-windows-static-md triplet to match the /MD runtime). Run from an x64 Native Tools Developer Command Prompt:

vcpkg install zlib:x64-windows-static-md gtest:x64-windows-static-md
cmake -S . --preset=msvc-release -DCMAKE_TOOLCHAIN_FILE=<vcpkg-root>\scripts\buildsystems\vcpkg.cmake -DVCPKG_TARGET_TRIPLET=x64-windows-static-md
cmake --build --preset=msvc-release
ctest --preset=msvc-release --output-on-failure

See cmake/README.md for all available compiler (gcc-*, clang-*, msvc-*, etc.), sanitizer, LTO, PGO, coverage, and CUDA presets.

Sample Usage

Basic .npy and .npz Serialization

#include <Npy++.h>

#include <cassert>
#include <cstddef>
#include <vector>

int main()
{
    const std::vector<std::size_t> shape { 4, 4, 8 };
    const std::vector<double> vec(128, 0.01);

    // Serialize using stdio (FILE*)
    npypp::Save("arr1.npy", vec, shape, "w");

    // Deserialize using memory mapping
    const auto useMemoryMapping = true;
    const auto loadedData = npypp::LoadFull<double>("arr1.npy", useMemoryMapping);

    assert(loadedData.shape == shape);
    assert(loadedData.data == vec);

    // Compressed archives (.npz)
    npypp::SaveCompressed("arr1.npz", "arr1", vec, shape, "w");
    const auto loadedCompressedData = npypp::LoadCompressedFull<double>("arr1.npz", "arr1");

    assert(loadedCompressedData.shape == shape);
    assert(loadedCompressedData.data == vec);
}

Zero-Copy / Read-Write Memory Mapping

#include <Npy++.h>

#include <cassert>
#include <cstddef>
#include <functional>
#include <numeric>
#include <vector>

int main()
{
    const std::vector<std::size_t> shape { 4, 4, 8 };
    const std::vector<double> vec(128, 0.01);

    const auto nElements = std::accumulate(shape.begin(), shape.end(), std::size_t{ 1 }, std::multiplies<std::size_t>());
    const auto npyHeader = npypp::detail::GetNpyHeader<double>(shape);
    const auto fileSizeBytes = npyHeader.size() + nElements * sizeof(double);

    // Open the file with read/write memory mapping (size must be known upfront)
    mm::MemoryMappedFile<mm::CacheHint::SequentialScan, mm::MapMode::ReadAndWrite> mmf("arr1_mmap.npy", fileSizeBytes);
    assert(mmf.IsValid());
    npypp::Save(mmf, vec, shape);

    // Rewind mapped cursor before reading back
    mmf.Rewind();

    // Zero-copy std::span view directly into the mapped .npy buffer
    std::vector<std::size_t> loadedShape;
    const auto spanView = npypp::LoadSpan<double>(mmf, &loadedShape);

    assert(loadedShape == shape);
    assert(spanView.size() == vec.size());
    for (std::size_t i = 0; i < vec.size(); ++i)
        assert(vec[i] == spanView[i]);
}