pybind11 details for xtensor.
Project description
# pyxtensor
<!-- MarkdownTOC -->
- [Introduction](#introduction)
- [Usage](#usage)
- [Compile project using `setup.py`](#compile-project-using-setuppy)
- [Develop](#develop)
<!-- /MarkdownTOC -->
## Introduction
This library provides details for [pybind11](https://github.com/pybind/pybind11) such that an interface to NumPy arrays is automatically provided when including a function that takes any of the [xtensor](https://github.com/QuantStack/xtensor) classes as (return) argument(s).
> The behaviour is distinctly different from [xtensor-python](https://github.com/QuantStack/xtensor-python). The latter 'maps' NumPy arrays to a so-called `xt::pyarray` giving direct memory access to it. In contrast, [pyxtensor](https://github.com/tdegeus/pyxtensor) copies the NumPy object to a `xt::array` or `xt::tensor` and vice versa. This results in a simpler usage in which a C++ library can be exposed without any wrapper functions, however, with the disadvantage of using copies (that cost time, and that disallow in-place modifications).
## Usage
Consider the following example:
```cpp
#include <xtensor/xarray.hpp>
#include <pyxtensor/pyxtensor.hpp>
xt::xarray<double> timesTwo(const xt::xarray<double>& a)
{
return 2. * a;
}
namespace py = pybind11;
PYBIND11_MODULE(example, m)
{
m.def("timesTwo", ×Two);
}
```
As observed the [pybind11](https://github.com/pybind/pybind11) wrapper immediately acts on the [xtensor](https://github.com/QuantStack/xtensor) objects. See [pybind11_examples](https://github.com/tdegeus/pybind11_examples) for compilation strategies.
## Compile project using `setup.py`
In addition a Python module is provided to aid compilation using a `setup.py`. Both headers and the Python module can be installed using
```bash
pip install pyxtensor
```
Using the [pyxtensor](https://github.com/tdegeus/pyxtensor) Python module the `setup.py` of a [pybind11](https://github.com/pybind/pybind11) project can be as follows
```python
from setuptools import setup, Extension
import sys, re
import setuptools
import pybind11
import pyxtensor
ext_modules = [
Extension(
'ModuleName',
['path/to/pybind11/interface.cpp'],
include_dirs=[
pybind11 .get_include(False),
pybind11 .get_include(True ),
pyxtensor.get_include(False),
pyxtensor.get_include(True ),
pyxtensor.find_xtensor(),
pyxtensor.find_xtl(),
pyxtensor.find_eigen(),
],
language='c++'
),
]
setup(
name = 'ModuleName',
description = 'Short description',
long_description = 'Long description',
version = 'v0.1.2',
license = 'MIT',
author = 'Tom de Geus',
author_email = '...',
url = 'https://github.com/...',
ext_modules = ext_modules,
install_requires = ['pybind11>=2.2.0','pyxtensor>=0.0.1'],
cmdclass = {'build_ext': pyxtensor.BuildExt},
zip_safe = False,
)
```
Compilation can then proceed using
```bash
python setup.py build
python setup.py install
```
## Develop
1. Update the version number as follows in `include/pyxtensor/pyxtensor.hpp``.
2. Upload the changes to GitHub and create a new release there (with the correct version number).
3. Upload the package to PyPi:
```bash
python setup.py bdist_wheel --universal
twine upload dist/*
```
<!-- MarkdownTOC -->
- [Introduction](#introduction)
- [Usage](#usage)
- [Compile project using `setup.py`](#compile-project-using-setuppy)
- [Develop](#develop)
<!-- /MarkdownTOC -->
## Introduction
This library provides details for [pybind11](https://github.com/pybind/pybind11) such that an interface to NumPy arrays is automatically provided when including a function that takes any of the [xtensor](https://github.com/QuantStack/xtensor) classes as (return) argument(s).
> The behaviour is distinctly different from [xtensor-python](https://github.com/QuantStack/xtensor-python). The latter 'maps' NumPy arrays to a so-called `xt::pyarray` giving direct memory access to it. In contrast, [pyxtensor](https://github.com/tdegeus/pyxtensor) copies the NumPy object to a `xt::array` or `xt::tensor` and vice versa. This results in a simpler usage in which a C++ library can be exposed without any wrapper functions, however, with the disadvantage of using copies (that cost time, and that disallow in-place modifications).
## Usage
Consider the following example:
```cpp
#include <xtensor/xarray.hpp>
#include <pyxtensor/pyxtensor.hpp>
xt::xarray<double> timesTwo(const xt::xarray<double>& a)
{
return 2. * a;
}
namespace py = pybind11;
PYBIND11_MODULE(example, m)
{
m.def("timesTwo", ×Two);
}
```
As observed the [pybind11](https://github.com/pybind/pybind11) wrapper immediately acts on the [xtensor](https://github.com/QuantStack/xtensor) objects. See [pybind11_examples](https://github.com/tdegeus/pybind11_examples) for compilation strategies.
## Compile project using `setup.py`
In addition a Python module is provided to aid compilation using a `setup.py`. Both headers and the Python module can be installed using
```bash
pip install pyxtensor
```
Using the [pyxtensor](https://github.com/tdegeus/pyxtensor) Python module the `setup.py` of a [pybind11](https://github.com/pybind/pybind11) project can be as follows
```python
from setuptools import setup, Extension
import sys, re
import setuptools
import pybind11
import pyxtensor
ext_modules = [
Extension(
'ModuleName',
['path/to/pybind11/interface.cpp'],
include_dirs=[
pybind11 .get_include(False),
pybind11 .get_include(True ),
pyxtensor.get_include(False),
pyxtensor.get_include(True ),
pyxtensor.find_xtensor(),
pyxtensor.find_xtl(),
pyxtensor.find_eigen(),
],
language='c++'
),
]
setup(
name = 'ModuleName',
description = 'Short description',
long_description = 'Long description',
version = 'v0.1.2',
license = 'MIT',
author = 'Tom de Geus',
author_email = '...',
url = 'https://github.com/...',
ext_modules = ext_modules,
install_requires = ['pybind11>=2.2.0','pyxtensor>=0.0.1'],
cmdclass = {'build_ext': pyxtensor.BuildExt},
zip_safe = False,
)
```
Compilation can then proceed using
```bash
python setup.py build
python setup.py install
```
## Develop
1. Update the version number as follows in `include/pyxtensor/pyxtensor.hpp``.
2. Upload the changes to GitHub and create a new release there (with the correct version number).
3. Upload the package to PyPi:
```bash
python setup.py bdist_wheel --universal
twine upload dist/*
```
Project details
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distributions
No source distribution files available for this release.See tutorial on generating distribution archives.
Built Distribution
Close
Hashes for pyxtensor-0.0.4-py2.py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | e34e7cdc0d6c105d7f5f7b02057bc580b670862ec47826714ec070926bebe429 |
|
MD5 | f4fa1fe854d3a0bb304683e33adc3045 |
|
BLAKE2b-256 | b9b735e77dcc41ac47eec817f2b462e62676537f7317cbcf3d03c9ca6e47afd6 |