nalgebra_numpy/
lib.rs

1//! This crate provides conversion between [`nalgebra`] and [`numpy`](https://numpy.org/).
2//! It is intended to be used when you want to share nalgebra matrices between Python and Rust code,
3//! for example with [`inline-python`](https://docs.rs/inline-python).
4//!
5//! # Conversion from numpy to nalgebra.
6//!
7//! It is possible to create either a view or a copy of a numpy array.
8//! You can use [`matrix_from_numpy`] to copy the data into a new matrix,
9//! or one of [`matrix_slice_from_numpy`] or [`matrix_slice_mut_from_numpy`] to create a view.
10//! If a numpy array is not compatible with the requested matrix type,
11//! an error is returned.
12//!
13//! Keep in mind though that the borrow checker can not enforce rules on data managed by a Python object.
14//! You could potentially keep an immutable view around in Rust, and then modify the data from Python.
15//! For this reason, creating any view -- even an immutable one -- is unsafe.
16//!
17//! # Conversion from nalgebra to numpy.
18//!
19//! A nalgebra matrix can also be converted to a numpy array, using [`matrix_to_numpy`].
20//! This function always creates a copy.
21//! Since all nalgebra arrays can be represented as a numpy array,
22//! this directly returns a [`pyo3::PyObject`] rather than a `Result`.
23//!
24//! # Examples.
25//!
26//! Copy a numpy array to a new fixed size matrix:
27//!
28//! ```
29//! use inline_python::{Context, python};
30//! use nalgebra_numpy::{matrix_from_numpy};
31//!
32//! # fn main() -> Result<(), nalgebra_numpy::Error> {
33//! let gil = pyo3::Python::acquire_gil();
34//! let context = Context::new_with_gil(gil.python());
35//! context.run(python! {
36//!     import numpy as np
37//!     matrix = np.array([
38//!         [1.0, 2.0, 3.0],
39//!         [4.0, 5.0, 6.0],
40//!         [7.0, 8.0, 9.0],
41//!     ])
42//! });
43//!
44//! let matrix = context.globals(gil.python()).get_item("matrix").unwrap();
45//! let matrix : nalgebra::Matrix3<f64> = matrix_from_numpy(gil.python(), matrix)?;
46//!
47//! assert_eq!(matrix, nalgebra::Matrix3::new(
48//!     1.0, 2.0, 3.0,
49//!     4.0, 5.0, 6.0,
50//!     7.0, 8.0, 9.0,
51//! ));
52//! # Ok(())
53//! # }
54//! ```
55//!
56//! Dynamic matrices are also supported:
57//!
58//! ```
59//! # use inline_python::{Context, python};
60//! # use nalgebra_numpy::{matrix_from_numpy};
61//! use nalgebra::DMatrix;
62//! # fn main() -> Result<(), nalgebra_numpy::Error> {
63//! # let gil = pyo3::Python::acquire_gil();
64//! # let context = Context::new_with_gil(gil.python());
65//! # context.run(python! {
66//! #     import numpy as np
67//! #     matrix = np.array([
68//! #         [1.0, 2.0, 3.0],
69//! #         [4.0, 5.0, 6.0],
70//! #         [7.0, 8.0, 9.0],
71//! #     ])
72//! # });
73//! #
74//! # let matrix = context.globals(gil.python()).get_item("matrix").unwrap();
75//!
76//! let matrix : DMatrix<f64> = matrix_from_numpy(gil.python(), matrix)?;
77//! assert_eq!(matrix, DMatrix::from_row_slice(3, 3, &[
78//!     1.0, 2.0, 3.0,
79//!     4.0, 5.0, 6.0,
80//!     7.0, 8.0, 9.0,
81//! ]));
82//! # Ok(())
83//! # }
84//! ```
85//!
86//! And so are partially dynamic matrices:
87//!
88//! ```
89//! # use inline_python::{Context, python};
90//! # use nalgebra_numpy::{matrix_from_numpy};
91//! use nalgebra::{MatrixMN, Dynamic, U3};
92//! # fn main() -> Result<(), nalgebra_numpy::Error> {
93//! # let gil = pyo3::Python::acquire_gil();
94//! # let context = Context::new_with_gil(gil.python());
95//! # context.run(python! {
96//! #     import numpy as np
97//! #     matrix = np.array([
98//! #         [1.0, 2.0, 3.0],
99//! #         [4.0, 5.0, 6.0],
100//! #         [7.0, 8.0, 9.0],
101//! #     ])
102//! # });
103//! # let matrix = context.globals(gil.python()).get_item("matrix").unwrap();
104//!
105//! let matrix : MatrixMN<f64, U3, Dynamic> = matrix_from_numpy(gil.python(), matrix)?;
106//! assert_eq!(matrix, MatrixMN::<f64, U3, Dynamic>::from_row_slice(&[
107//!     1.0, 2.0, 3.0,
108//!     4.0, 5.0, 6.0,
109//!     7.0, 8.0, 9.0,
110//! ]));
111//! # Ok(())
112//! # }
113//! ```
114//!
115//! A conversion to python object looks as follows:
116//! ```
117//! use nalgebra_numpy::matrix_to_numpy;
118//! use nalgebra::Matrix3;
119//! use inline_python::python;
120//!
121//! let gil = pyo3::Python::acquire_gil();
122//! let matrix = matrix_to_numpy(gil.python(), &Matrix3::<i32>::new(
123//!     0, 1, 2,
124//!     3, 4, 5,
125//!     6, 7, 8,
126//! ));
127//!
128//! python! {
129//!     from numpy import array_equal
130//!     assert array_equal('matrix, [
131//!         [0, 1, 2],
132//!         [3, 4, 5],
133//!         [6, 7, 8],
134//!     ])
135//! }
136//! ```
137
138mod from_numpy;
139mod to_numpy;
140
141pub use from_numpy::*;
142pub use to_numpy::*;
nalgebra_numpy/lib.rs

nalgebra_numpy/
lib.rs
