rust-numpy开发者指南：从零构建高性能Python扩展

富茉钰Ida

388人浏览 · 2026-03-04 00:19:43

富茉钰Ida · 2026-03-04 00:19:43 发布

rust-numpy开发者指南：从零构建高性能Python扩展

【免费下载链接】rust-numpy PyO3-based Rust bindings of the NumPy C-API 项目地址: https://gitcode.com/gh_mirrors/ru/rust-numpy

rust-numpy是一个基于PyO3的NumPy C-API Rust绑定库，它允许开发者使用Rust语言创建高性能的Python扩展。本文将为你提供一个全面的指南，帮助你从零开始使用rust-numpy构建强大的Python扩展。

为什么选择rust-numpy？

rust-numpy结合了Rust的性能优势和NumPy的科学计算能力，为开发者提供了一个创建高性能Python扩展的理想工具。通过使用rust-numpy，你可以：

利用Rust的内存安全和高性能特性
直接访问NumPy的C-API，避免Python的性能瓶颈
创建类型安全的数值计算函数
轻松处理大型数组和复杂的数学运算

环境准备

在开始使用rust-numpy之前，你需要确保系统中安装了以下依赖：

Rust编译器（推荐使用rustup安装）
Python 3.6或更高版本
NumPy库
PyO3依赖

你可以通过以下命令克隆rust-numpy仓库：

git clone https://gitcode.com/gh_mirrors/ru/rust-numpy

基本概念

PyArray：Rust中的NumPy数组

在rust-numpy中，PyArray是核心数据结构，它表示一个NumPy数组。PyArray<T, D>是一个泛型类型，其中T是元素类型，D是维度。例如，PyArray<f64, 2>表示一个二维的双精度浮点数数组。

rust-numpy提供了多种创建PyArray的方法，如：

PyArray::new：创建一个新的未初始化数组
PyArray::from_iter：从迭代器创建数组
PyArray::from_slice：从Rust切片创建数组

类型转换

rust-numpy提供了灵活的类型转换机制，允许你在Rust类型和NumPy类型之间进行转换。Element trait定义了Rust类型与NumPy dtype之间的映射关系。

快速开始：创建你的第一个扩展

1. 创建新项目

首先，创建一个新的Rust项目，并添加必要的依赖到Cargo.toml：

[package]
name = "my_numpy_extension"
version = "0.1.0"
edition = "2021"

[dependencies]
pyo3 = { version = "0.19", features = ["extension-module"] }
numpy = { path = "../rust-numpy" }

2. 编写基本函数

在src/lib.rs中，我们可以编写一个简单的函数来计算数组的平方：

use numpy::ndarray::{ArrayViewD, ArrayD};
use numpy::{IntoPyArray, PyArrayDyn};
use pyo3::prelude::*;

#[pyfunction]
fn square_array(a: &PyArrayDyn<f64>) -> PyResult<Py<PyArrayDyn<f64>>> {
    let a = a.as_array();
    let result = a.mapv(|x| x * x);
    Ok(result.into_pyarray(py).into())
}

#[pymodule]
fn my_numpy_extension(_py: Python, m: &PyModule) -> PyResult<()> {
    m.add_function(wrap_pyfunction!(square_array, m)?)?;
    Ok(())
}

3. 构建和测试

使用maturin或setuptools-rust构建你的扩展：

maturin develop

然后在Python中测试：

import my_numpy_extension
import numpy as np

arr = np.array([1.0, 2.0, 3.0])
result = my_numpy_extension.square_array(arr)
print(result)  # 输出 [1. 4. 9.]

高级特性

数组操作

rust-numpy提供了丰富的数组操作方法，如转置、重塑和轴操作。例如，你可以使用permute和transpose方法改变数组的轴顺序：

let arr = PyArray::from_slice(py, &[[1, 2], [3, 4]]);
let transposed = arr.transpose()?;  // 转置数组

类型安全

rust-numpy通过类型系统确保数组操作的安全性。例如，PyReadonlyArray确保数组在使用期间不会被修改，而PyArrayDescr提供了对数组数据类型的安全访问。

错误处理

rust-numpy定义了多种错误类型，如维度不匹配、类型转换失败等。你可以使用这些错误类型来处理各种异常情况：

// 维度不匹配错误
pub(crate) const DIMENSIONALITY_MISMATCH_ERR: &str = "inconsistent dimensionalities: The dimensionality expected by `PyArray` does not match that given by NumPy.";