Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/PyO3/rust-numpy

PyO3-based Rust bindings of the NumPy C-API
https://github.com/PyO3/rust-numpy

ndarray numpy numpy-capi rust-bindings rust-ndarray rust-numpy

Last synced: 3 months ago
JSON representation

PyO3-based Rust bindings of the NumPy C-API

Awesome Lists containing this project

README 

        
rust-numpy

===========

[![Actions Status](https://github.com/PyO3/rust-numpy/workflows/CI/badge.svg)](https://github.com/PyO3/rust-numpy/actions)

[![Crate](https://img.shields.io/crates/v/numpy.svg)](https://crates.io/crates/numpy)

[![Minimum rustc 1.48](https://img.shields.io/badge/rustc-1.48+-blue.svg)](https://rust-lang.github.io/rfcs/2495-min-rust-version.html)

[![Documentation](https://docs.rs/numpy/badge.svg)](https://docs.rs/numpy)

[![codecov](https://codecov.io/gh/PyO3/rust-numpy/branch/main/graph/badge.svg)](https://codecov.io/gh/PyO3/rust-numpy)



Rust bindings for the NumPy C-API.



## API documentation

- [Latest release](https://docs.rs/numpy)

- [Current main](https://pyo3.github.io/rust-numpy)



## Requirements

- Rust >= 1.48.0

  - Basically, our MSRV follows the one of [PyO3](https://github.com/PyO3/pyo3)

- Python >= 3.7

  - Python 3.6 support was dropped from 0.16

- Some Rust libraries

  - [ndarray](https://github.com/rust-ndarray/ndarray) for Rust-side matrix library

  - [PyO3](https://github.com/PyO3/pyo3) for Python bindings

  - And more (see [Cargo.toml](Cargo.toml))

- [numpy](https://numpy.org/) installed in your Python environments (e.g., via `pip install numpy`)

  - We recommend `numpy >= 1.16.0`, though older versions may work



## Example



### Write a Python module in Rust



Please see the [simple](examples/simple) example for how to get started.



There are also examples using [ndarray-linalg](examples/linalg) and [rayon](examples/parallel).



```toml

[lib]

name = "rust_ext"

crate-type = ["cdylib"]



[dependencies]

pyo3 = { version = "0.21", features = ["extension-module"] }

numpy = "0.21"

```



```rust

use numpy::ndarray::{ArrayD, ArrayViewD, ArrayViewMutD};

use numpy::{IntoPyArray, PyArrayDyn, PyReadonlyArrayDyn, PyArrayMethods};

use pyo3::{pymodule, types::PyModule, PyResult, Python, Bound};



#[pymodule]

fn rust_ext<'py>(_py: Python<'py>, m: &Bound<'py, PyModule>) -> PyResult<()> {

    // example using immutable borrows producing a new array

    fn axpy(a: f64, x: ArrayViewD<'_, f64>, y: ArrayViewD<'_, f64>) -> ArrayD {

        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`

    #[pyfn(m)]

    #[pyo3(name = "axpy")]

    fn axpy_py<'py>(

        py: Python<'py>,

        a: f64,

        x: PyReadonlyArrayDyn<'py, f64>,

        y: PyReadonlyArrayDyn<'py, f64>,

    ) -> Bound<'py, PyArrayDyn> {

        let x = x.as_array();

        let y = y.as_array();

        let z = axpy(a, x, y);

        z.into_pyarray_bound(py)

    }



    // wrapper of `mult`

    #[pyfn(m)]

    #[pyo3(name = "mult")]

    fn mult_py<'py>(a: f64, x: &Bound<'py, PyArrayDyn>) {

        let x = unsafe { x.as_array_mut() };

        mult(a, x);

    }



    Ok(())

}

```



### Execute a Python program from Rust and get results



``` toml

[package]

name = "numpy-test"



[dependencies]

pyo3 = { version = "0.21", features = ["auto-initialize"] }

numpy = "0.21"

```



```rust

use numpy::{PyArray1, PyArrayMethods};

use pyo3::{types::{IntoPyDict, PyAnyMethods}, PyResult, Python};



fn main() -> PyResult<()> {

    Python::with_gil(|py| {

        let np = py.import_bound("numpy")?;

        let locals = [("np", np)].into_py_dict_bound(py);



        let pyarray = py

            .eval_bound("np.absolute(np.array([-1, -2, -3], dtype='int32'))", Some(&locals), None)?

            .downcast_into::>()?;



        let readonly = pyarray.readonly();

        let slice = readonly.as_slice()?;

        assert_eq!(slice, &[1, 2, 3]);



        Ok(())

    })

}

```



## Dependency on ndarray



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.13, < 0.16`. 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



```toml

numpy = "0.21"

ndarray = "0.13"

```



this will currently depend on both version `0.13.1` and `0.15.3` of `ndarray` by default

even though `0.13.1` is within the range `>= 0.13, < 0.16`. To fix this, you can run



```sh

cargo update --package ndarray:0.15.3 --precise 0.13.1

```



to achieve a single dependency on version `0.13.1` of `ndarray`.



## Contributing



We welcome [issues](https://github.com/PyO3/rust-numpy/issues)

and [pull requests](https://github.com/PyO3/rust-numpy/pulls).



PyO3's [Contributing.md](https://github.com/PyO3/pyo3/blob/main/Contributing.md)

is a nice guide for starting.



Also, we have a [Gitter](https://gitter.im/PyO3/Lobby) channel for communicating.