Add proper readme

Author: SylvainCorlay

README.md

@@ -1,22 +1,138 @@
-# Requirement
+# xtensor-python
 
- - pybind11 master (not 1.8.1)
- - xtensor 0.1.0
+Python bindings for the [xtensor](https://github.com/QuantStack/xtensor) C++ multi-dimensional array library.
 
-# Installation
+ - `xtensor` is a C++ library for multi-dimensional arrays enabling numpy-style broadcasting and lazy computing.
+ - `xtensor-python` enables inplace use of numpy arrays with all the benefits from `xtensor`
 
- - build and install conda recipe
+     - C++ universal function and broadcasting 
+     - STL - compliant APIs.
 
-# Dev installation
+The Python bindings for `xtensor` are based on the [pybind11](https://github.com/pybind/pybind11/) C++ library, which enables seemless interoperability between C++ and Python.
 
- - symlink `include\xtensor-python` to `$SYS_PREFIX\include\xtensor-python`
+## Usage
 
-# Testing
+### Example 1: Use an algorithm of the C++ library on a numpy array inplace.
 
-  Testing `xtensor-python` requires `nosetests`
+**C++ code**
+
+```cpp
+#include <numeric>                        // Standard library import for std::accumulate
+#include "pybind11/pybind11.h"            // Pybind11 import to define Python bindings
+#include "xtensor/xmath.hpp"              // xtensor import for the C++ universal functions
+#include "xtensor-python/pyarray.hpp"     // Numpy bindings
+
+double sum_of_sines(xt::pyarray<double> &m)
+{
+    auto sines = xt::sin(m);  // sines does not actually hold any value, which are only computed upon access
+    return std::accumulate(sines.begin(), sines.end(), 0.0);
+}
+
+PYBIND11_PLUGIN(xtensor_python_test)
+{
+    pybind11::module m("xtensor_python_test", "Test module for xtensor python bindings");
+
+    m.def("sum_of_sines", sum_of_sines, "Computes the sum of the sines of the values of the input array");
+
+    return m.ptr();
+}
+```
+
+**Python Code**
+
+```python
+import numpy as np
+import xtensor_python_test as xt
+
+a = np.arange(15).reshape(3, 5)
+s = xt.sum_of_sines(v)
+s
+```
+
+**Outputs**
+
+```
+1.2853996391883833
+``` 
+
+### Example 2: Create a universal function from a C++ scalar function
+
+**C++ code**
+
+```cpp
+#include "pybind11/pybind11.h"
+#include "xtensor-python/pyvectorize.hpp"
+#include <numeric>
+#include <cmath>
+
+namespace py = pybind11;
+
+double scalar_func(double i, double j)
+{
+    return std::sin(i) - std::cos(j);
+}
+
+PYBIND11_PLUGIN(xtensor_python_test)
+{
+    py::module m("xtensor_python_test", "Test module for xtensor python bindings");
+
+    m.def("vectorized_func", xt::pyvectorize(scalar_func), "");
+
+    return m.ptr();
+}
+```
+
+**Python Code**
+
+```python
+import numpy as np
+import xtensor_python_test as xt
+
+x = np.arange(15).reshape(3, 5)
+y = [1, 2, 3]
+z = xt.vectorized_func(x, y)
+z
+```
+
+**Outputs**
+
+```
+[[-1.      ,  0.301169,  1.325444,  1.131113, -0.103159],
+ [-1.958924, -0.819718,  1.073133,  1.979351,  1.065762],
+ [-1.544021, -1.540293, -0.120426,  1.41016 ,  1.644251]]
+``` 
+
+## Installation
+
+We provide a package for the conda package manager.
+
+```bash
+conda install -c conda-forge xtensor-python
+```
+
+This will pull the dependencies to xtensor-python, that is `pybind11` and `xtensor`.
+
+## Project cookiecutter
+
+A template for a project making use of `xtensor-python` is available in the form of a cookie cutter [here](https://github.com/QuantStack/xtensor-cookiecutter).
+
+This project is meant to help library authors get started with the xtensor python bindings.
+
+It produces a project following the best practices for the packaging and distribution of Python extensions based on `xtensor-python`, including a `setup.py` file and a conda recipe.
+
+## Building and Running the Tests
+
+Testing `xtensor-python` requires `nosetests`
 
   ``` bash
   nosetests .
   ```
 
-  To pick up changes in `xtensor-python` while rebuilding, delete the `build/` directory. 
+To pick up changes in `xtensor-python` while rebuilding, delete the `build/` directory. 
+
+## License
+
+We use a shared copyright model that enables all contributors to maintain the
+copyright on their contributions.
+
+This software is licensed under the BSD-3-Clause license. See the [LICENSE](LICENSE) file for details.

test/main.cpp

@@ -1,32 +1,50 @@
-#include <pybind11/pybind11.h>
+#include "pybind11/pybind11.h"
+#include "xtensor/xmath.hpp"
 #include "xtensor/xarray.hpp"
 #include "xtensor-python/pyarray.hpp"
 #include "xtensor-python/pyvectorize.hpp"
 #include <iostream>
+#include <numeric>
 
 namespace py = pybind11;
 
-int add(int i, int j) {
-    return i + j;
-}
+// Examples
 
-double test0(xt::pyarray<double> &m)
+double example1(xt::pyarray<double> &m)
 {
     return m(0);
 }
 
-xt::pyarray<double> test1(xt::pyarray<double> &m)
+xt::pyarray<double> example2(xt::pyarray<double> &m)
 {
     return m + 2;
 }
 
+// Readme Examples
+
+double readme_example1(xt::pyarray<double> &m)
+{
+    auto sines = xt::sin(m);
+    return std::accumulate(sines.begin(), sines.end(), 0.0);
+}
+
+// Vectorize Examples
+
+int add(int i, int j)
+{
+    return i + j;
+}
+
 PYBIND11_PLUGIN(xtensor_python_test)
 {
     py::module m("xtensor_python_test", "Test module for xtensor python bindings");
 
-    m.def("test0", test0, "");
-    m.def("test1", test1, "");
-    m.def("vec_add", xt::pyvectorize(add), "");
+    m.def("example1", example1, "");
+    m.def("example2", example2, "");
+
+    m.def("readme_example1", readme_example1, "");
+
+    m.def("vectorize_example1", xt::pyvectorize(add), "");
 
     return m.ptr();
 }

test/test_pyarray.py

@@ -15,19 +15,23 @@
 
 class ExampleTest(TestCase):
 
-    def test_example0(self):
-        self.assertEqual(4, xt.test0([4, 5, 6]))
-
     def test_example1(self):
+        self.assertEqual(4, xt.example1([4, 5, 6]))
+
+    def test_example2(self):
         x = np.array([[0., 1.], [2., 3.]])
         res = np.array([[2., 3.], [4., 5.]])
-        y = xt.test1(x)
+        y = xt.example2(x)
         np.testing.assert_allclose(y, res, 1e-12)
 
     def test_vectorize(self):
         x1 = np.array([[0, 1], [2, 3]])
         x2 = np.array([0, 1])
         res = np.array([[0, 2], [2, 4]])
-        y = xt.vec_add(x1, x2)
+        y = xt.vectorize_example1(x1, x2)
         np.testing.assert_array_equal(y, res)
 
+    def test_readme_example1(self):
+        v = np.arange(15).reshape(3, 5)
+        y = xt.readme_example1(v)
+        np.testing.assert_allclose(y, 1.2853996391883833, 1e-12)