cnpy：NumPy文件格式读写的C 17库

≥≥软件X 21（2023）101324原始软件出版物cnpy++：用于读写.npy/.npz文件马克西米利安·赖宁豪斯Institut für Astroteilchenphysik，Karlsruher Institut für Technologie（KIT），Postfach 3640，76021 Karlsruhe，Germanyar t i cl e i nf o文章历史记录：2022年12月2日收到2023年1月16日收到修订版，2023年关键词：NumPy文件数据格式C++迭代器序列化a b st ra ctcnpy++是一个易于使用的C++17库，用于读取和写入NumPy文件格式（.npy和.npz文件）的数据，提供比其他实现更多的功能。除了编写标准的数据数组之外，它还支持编写通过C++迭代器公开的数据，允许序列化不驻留在连续内存中的数据结构。此外，提供了对结构化数组的支持，这有助于方便地读取和写入具有标记列的表格数据©2023作者由爱思唯尔公司出版这是CC BY许可下的开放获取文章（http://creativecommons.org/licenses/by/4.0/）中找到。代码元数据当前代码版本v2.1.1用于此代码版本的代码/存储库的永久链接https://github.com/ElsevierSoftwareX/SOFTX-D-22-00404Reproducible Capsule的永久链接不适用法律代码许可证MIT许可证使用git的代码版本控制系统使用C++17、C、cmake的软件代码语言、工具和服务编译要求、操作环境依赖性libzip≥v1.7.3（可选）;（boost≥v1.78）或（boost≥v1.74和（Microsoft如果可用，链接到开发人员文档/手册GSL v3.1.0或gsl-lite v0.40.0））;在Linux和Android上测试，存储库文件README.md支持电子邮件，如有疑问，请联系maximilian. kit.edu1. 动机和意义NumPy是Python中最广泛使用的科学计算库之一，是构建在其上的整个软件生态系统的基础[1，2]。除了处理和操作（多维）数据数组（主要是数值）的大量函数外，该库还定义了一个文件格式来存储这些数据在磁盘上，在下文中称为NPY文件（建议的文件扩展名是.npy）。NPY文件格式是一种独立于平台的二进制格式，在参考文献[3]中进行了标准化。在Python中，可以通过numpy.save（）和numpy.load（）函数轻松处理NPY文件。最重要的是，许多这样的文件可以组合在一个（可选压缩）zip文件中，以将相关数据存储在单个文件（NPZ文件）中。该格式的简单性和易用性使其成为共享数据的合适选择在本文中，我介绍了cnpy++，一个C++17库，用于从/向NPY和NPZ文件读写数据中的常见工作流电子邮件地址：maximilian. kit.edu。https://doi.org/10.1016/j.softx.2023.101324当代科学计算是利用以诸如C++的编译语言编写的代码来创建数据（例如，模拟的输出）以实现高性能，并且利用诸如Python的脚本语言来进一步分析和可视化这些数据。cnpy++有助于减少C++和Python之间交换数据的负担。它被设计为与现有的C++代码很好地集成cnpy++开始时是cnpy项目的一个分支[4]，似乎不再维护。整个代码库进行了彻底的改革，现代化，并实现了原始代码所缺乏的新功能，使cnpy++成为目前在C++中处理NPY/NPZ文件的最通用的解决方案。2. 软件描述2.1. 软件构架cnpy++是一个C++17库，由头部分和编译部分（共享或静态库）。头部分不仅包含2352-7110/©2023作者。由爱思唯尔公司出版这是CC BY许可下的开放获取文章（http://creativecommons.org/licenses/by/4.0/）。可在ScienceDirect上获得目录列表SoftwareX期刊主页：www.elsevier.com/locate/softx马克西米利安·赖宁豪斯软件X 21（2023）1013242≥编译库，但也有函数和类模板，不能预编译。由于cnpy++被设计为序列化来自泛型源的数据（见下文），它依赖于C++迭代器来访问数据，这需要相应的函数接受任何满足迭代器概念的类型。此外，cnpy++依赖于模板元编程技术来实现一些更高级的功能。cnpy++ 大 量 使 用 了 几 个boost 库 ， 特 别 是 boost ： ：endian、boost：：filesystem、boost：：iostreams、boost：：iterator和boost：：stlinterfaces，使boost成为一个强制依赖项。此外，cnpy++有libzip作为可选的依赖项，用于读取和写入zip存档，允许使用任何压缩方法。如果没有libzip，所有处理NPZ文件的功能都不可用。使用的构建系统是CMake，cnpy++也可以很容易地集成到使用CMake的其他项目中。2.2. 软件功能cnpy++的用户API由许多函数组成，用于将在下文中，给出了API的最重要部分的描述。它们都属于cnpypp命名空间。2.2.1. 将数据写入.npy要将数据写入NPY文件，提供了模板函数npy_save（）的几个重载templatenameTforrwardIterator>voidcnpypp：：npy_save（std：：stringconstfnme，TForwardIteratttra t tt ra t trat tr atttd：：string_viewmode=“w“）这个最基本的重载将数据从一对迭代器（first，last）写入路径为fname的文件。在最简单的情况下，迭代器类型可以是指向连续内存的指针（例如，floatconst*等），但也可以是满足for-ward迭代器概念的任何类型（例如，STL1容器的许多迭代器，如std：：vector，std：：list等）。迭代器的值类型必须是基本整数、浮点类型、std：：complex或bool。mode参数可以是“w”或“a”。使用“w”，可能存在的文件被覆盖。如果文件已经存在，则使用“a”附加数据生成的NPY文件将包含一个一维数组。templatteypenametupleIterator>voidcnpypp：：npy_save（std：：stringconst&fname，std：：vecttd：：string_view>constlabels，TTupleIteratfirst，cnpypp：：spannsize_tconst >constshape，std：：string_viewmode=“w“，MemoryOrderMemory_order=MemoryOrder：：C）cnpy++还支持编写表格数据，NumPy命名中的结构化数组。这里的要求是TTupleIterator的值类型是一个std：：tuple，其元素是基本类型或引用，例如std：：tuple或std：：tuple。根据labels参数对各个列进行标记，该参数需要包含与tuple的元素一样多的标签字符串。cnpy++负责在写入之前打包元组元素，即元素之间的任何填充都将被删除。此重载可用于序列化内存中以数组结构和结构数组布局存在的数据，如下面的示例所 注意cnpy++不支持嵌套结构数组。2.2.2. 将数据写入.npz使用npz_save（）函数将数据写入NPZ存档。与npy_save（）相比，它们有两个文件名参数，第一个引用整个NPZ存档，第二个引用存档中的NPY文件。其余参数的含义与对应的npy_save（）相同，除了mode参数指示是否应将另一个数组添加到归档中或覆盖整个NPZ文件。目前不支持将数据复制到NPZ归档中的现有阵列。2.2.3. 从.npy和.npzcnpypp：：NpyArraycnpypp：：npy_load（std：：stringconstfname，boolmemory_mapped=false）通过npy_load（）读取NPY文件需要文件名作为参数。如果文件是内存映射的，则可选的布尔参数可以设置为true如果没有，它的数据内容将被复制到内存中。内存映射允许读取太大而无法放入内存的文件，仅受可用地址空间的限制，这对当前的64位架构没有任何实际限制。cnpypp：：NpyArraycnpypp：：npz_load（std：：stringconst&fname，std：：stringconstarrname）此重载允许写入多维数据，其每个维度的元素数由shape参数2给出。写入的元素总数是这些元素的乘积。memory_order参数可以采用MemoryOrder：：C或MemoryOrder：：Fortran的值，指示迭代它们的顺序。1 标准模板库。2 类型cnpypp：：span< T>是实现的别名。用户可以在Microsoft的Guidelines Support Library [ 6 ]、Moene的gsl-lite [ 7 ]、recent（1. 78）boost的版本，或者使用C++20标准编译时的STL实现。从NPZ存档读取还需要从存档中提取数组的名称。记忆映射阅读 未对NPZ存档实现。这些函数的返回值是一个NpyArray对象，它包含内存中的数据（在内存映射的情况下是虚拟内存）及其元数据。cnpypp：：NpyArray：：shape->std：：vectorsize_t>cnpypp：：NpyArray：： mmory_order->cnpypp：：moryOrdercnpypp：：NpyArray：：word_sizes->std：：vectorsize_t>cnpypp：：NpyArray：：labels->std：：vectorst d：：string>这些成员变量包含数组的元数据：形状，内存顺序，单词大小和标签。如果文件不包含结构化数组，则NpyArray：：labels是一个空向量，NpyArray：：word_sizes包含单个元素。tempenameT>T*cnpyp：：NpyArray：：end（）;tempename nameT>T*cnpyp：：NpyArray：：end（）;在输入时输入类型TC>voidcnpypp：：npy_save（std：：stringconstfnme，TConstInttteratart，cnpypp：：spansize_tconst >shape，std：：strin g_viewmode=“w“，MemoryOrderMemory_order=MemoryOrder：：C）马克西米利安·赖宁豪斯软件X 21（2023）1013243templatcnpypp：：subrangecnpypp：：tuple_iteratd：：tuple >>cnpypp：：NpyArray：：tuple_range（）清单1： 将1D数据从std：：list写入NPY文件清单2：将2D数组写入NPZ归档12345#includecstdint>#includelist >#includeconstl{10，11，12，13};7/ /这是一个 很好的选 择。 npz/matrix“98cnpypp：：npz_save（“archive. npz“，“matrix“，mat10//保存到“list.npy“[0][0]，{2，3}）;11cnpypp：：npy_save（“list.npy“，l. begin（），l.end（））9};121314//appendatafromrversedlistcnpypp：：npy_save（“list.npy“，l. rbegin（），l.rend（）、“a“）;清单3：写入和读取结构化数组15}1#includecstdint>2#includeiostrem>3#includetuple >4#includevector>可以通过模板函数NpyArray来存储数据：：begin T>（）和NpyArray：：end T>（）。用户负责在编译时通过模板参数选择正确的类型。这些函数对于非结构化阵列是最有用的。为了方便地遍历结构化数据，可以使用可变成员函数模板NpyArray ： ：tuple_range（ ）， 并将元组元素类型作为模板参数。在运行时，检查提供的模板参数的字节大小是否与文件的元数据匹配，如果不匹配，则抛出NpyArray：：tuple_range（）返回一个类range的对象，它本身提供了begin（）和end（）迭代器，在解引用时返回引用的元组。templatecnpypp：：subrange>cnpypp：：NpyArray：：column_range（std：：string_viewlabel）如果只对结构化数组的一列感兴趣，可以使用成员函数模板NpyArray：：column_range（）返回一个仅在相应元素上迭代的范围，即具有步幅。该列已选定通过它的标签。template参数设置迭代器的值类型。3. 说明性实例现在让我们考虑几个示例应用。清单1展示了如何使用npy_save（）函数通过迭代器接口保存std：：整数列表中的首先，将列表元素写入list.npy。然后，再次打开文件，以倒序追加列表元素。清单2是处理2D数据和NPZ归档的示例使用npz_save（）将2 × 3矩阵保存到文件archive.npz中。结构化数组的处理如清单3所示。在这里，我们使用zip迭代器（使用range-v3库的实现[8]）从两个独立的向量xVec和yVec创建一个元组序列，大小相同。注意，ranges：：views：：zip的返回值，一个&<&这些元组保存到文件structured.npy中，带有标签"x"和"y“的两列数据随后，数据被读回内存。第23行f。展示了如何使用NpyArray：：tuple_range（）结合基于范围的for 循 环 中 的 结 构 化 绑 定 来 在 第 30 F 行 中 ， NpyArray ： ：column_range（）用于仅遍历4. 影响cnpy++是一个相当轻量级的库，很容易通过cmake构建系统集成到其他项目中。再加上其易用性，它可以成为更复杂解决方案的可行替代方案[10]如HDF5 [9]或ROOT [10]。虽然HDF 5基本上是5678910111213141516#includeconstxVec{4，5，6};std：：vectorconstyVec{2. 二二三三点三，4.44};//zipthemtogetheritottleviazipieratorocstzipiew=ranges：：views：：zip（xVec，yVec）;cnpypp：：npy_save（“结构化.npy“，{“x“，“y“}，zipview. begin（），{zipview. }）;1718//reeadbackintoreeadData19cnpypp：：NpyArrayconstreadData=20cnpypp：：npy_load（“结构化.npy“）;2122//遍历元组2324对于（autoconst&[x，y]：readData. public intfindDuplicate（）{（“x“））{

下载后可阅读完整内容，剩余1页未读，立即下载