Rust bindings for the NumPy C-API.
- Rust >= 1.74.0
- Basically, our MSRV follows the one of PyO3
- Python >= 3.7
- Python 3.6 support was dropped from 0.16
- Some Rust libraries
- ndarray for Rust-side matrix library
- PyO3 for Python bindings
- And more (see Cargo.toml)
- numpy installed in your Python environments (e.g., via
pip install numpy)- We recommend
numpy >= 1.16.0, though older versions may work
- We recommend
Please see the simple example for how to get started.
There are also examples using ndarray-linalg and rayon.
[lib] name = "rust_ext" crate-type = ["cdylib"] [dependencies] pyo3 = { version = "0.27" } numpy = "0.27"
#[pyo3::pymodule] mod rust_ext { use numpy::ndarray::{ArrayD, ArrayViewD, ArrayViewMutD}; use numpy::{IntoPyArray, PyArrayDyn, PyReadonlyArrayDyn, PyArrayMethods}; use pyo3::{pyfunction, PyResult, Python, Bound}; // example using immutable borrows producing a new array fn axpy(a: f64, x: ArrayViewD<'_, f64>, y: ArrayViewD<'_, f64>) -> ArrayD<f64> { a * &x + &y } // example using a mutable borrow to modify an array in-place fn mult(a: f64, mut x: ArrayViewMutD<'_, f64>) { x *= a; } // wrapper of `axpy` #[pyfunction(name = "axpy")] fn axpy_py<'py>( py: Python<'py>, a: f64, x: PyReadonlyArrayDyn<'py, f64>, y: PyReadonlyArrayDyn<'py, f64>, ) -> Bound<'py, PyArrayDyn<f64>> { let x = x.as_array(); let y = y.as_array(); let z = axpy(a, x, y); z.into_pyarray(py) } // wrapper of `mult` #[pyfunction(name = "mult")] fn mult_py<'py>(a: f64, x: &Bound<'py, PyArrayDyn<f64>>) { let x = unsafe { x.as_array_mut() }; mult(a, x); } }
[package] name = "numpy-test" [dependencies] pyo3 = { version = "0.27", features = ["auto-initialize"] } numpy = "0.27"
use numpy::{PyArray1, PyArrayMethods}; use pyo3::{types::{IntoPyDict, PyAnyMethods}, PyResult, Python, ffi::c_str}; fn main() -> PyResult<()> { Python::attach(|py| { let np = py.import("numpy")?; let locals = [("np", np)].into_py_dict(py)?; let pyarray = py .eval(c_str!("np.absolute(np.array([-1, -2, -3], dtype='int32'))"), Some(&locals), None)? .cast_into::<PyArray1<i32>>()?; let readonly = pyarray.readonly(); let slice = readonly.as_slice()?; assert_eq!(slice, &[1, 2, 3]); Ok(()) }) }
This crate uses types from ndarray in its public API. ndarray is re-exported
in the crate root so that you do not need to specify it as a direct dependency.
Furthermore, this crate is compatible with multiple versions of ndarray and therefore depends
on a range of semver-incompatible versions, currently >= 0.15, < 0.17. Cargo does not
automatically choose a single version of ndarray by itself if you depend directly or indirectly
on anything but that exact range. It can therefore be necessary to manually unify these dependencies.
For example, if you specify the following dependencies
numpy = "0.27" ndarray = "0.15"
this will currently depend on both version 0.15.6 and 0.16.1 of ndarray by default
even though 0.15.6 is within the range >= 0.15, <= 0.17. To fix this, you can run
cargo update --package ndarray:0.16.1 --precise 0.15.6
to achieve a single dependency on version 0.15.6 of ndarray.
We welcome issues and pull requests.
PyO3's Contributing.md is a nice guide for starting.
Also, we have a Gitter channel for communicating.