Metadata-Version: 2.1
Name: pyxtensor
Version: 0.0.4
Summary: pybind11 details for xtensor.
Home-page: https://github.com/tdegeus/pyxtensor
Author: Tom de Geus
Author-email: tom@geus.me
License: MIT
Keywords: C++,C++11,C++14,Python bindings,pybind11,xtensor
Platform: UNKNOWN
Requires-Dist: pybind11 (>=2.2.0)

# 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", &timesTwo);
}
```

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/*
    ```




