-
Notifications
You must be signed in to change notification settings - Fork 117
/
Copy pathREADME.md
157 lines (121 loc) · 4.84 KB
/
README.md
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
rust-numpy
===========
[](https://github.com/PyO3/rust-numpy/actions)
[](https://crates.io/crates/numpy)
[](https://rust-lang.github.io/rfcs/2495-min-rust-version.html)
[](https://docs.rs/numpy)
[](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.63.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.22", 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<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`
#[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<f64>> {
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<f64>>) {
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.22", 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::<PyArray1<i32>>()?;
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.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
```sh
cargo update --package ndarray:0.16.1 --precise 0.15.6
```
to achieve a single dependency on version `0.15.6` 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.