dummy-link

Xtensor

Julia bindings for xtensor

Readme

xtensor-julia

Travis Appveyor Documentation Status Join the Gitter Chat

Julia bindings for the xtensor C++ multi-dimensional array library.

  • xtensor is a C++ library for multi-dimensional arrays enabling numpy-style broadcasting and lazy computing.
  • xtensor-julia enables inplace use of julia arrays in C++ with all the benefits from xtensor

The Julia bindings for xtensor are based on the CxxWrap.jl C++ library.

Installation

Pkg.clone("https://github.com/QuantStack/Xtensor.jl", "Xtensor");
Pkg.build("Xtensor")

Usage

xtensor-julia offers two container types wrapping julia arrays inplace to provide an xtensor semantics

  • jltensor
  • jlarray.

Both containers enable the numpy-style APIs of xtensor (see the numpy to xtensor cheat sheet).

  • On the one hand, jlarray has a dynamic number of dimensions. It can be reshaped dynamically and the new shape is reflected on the Julia side.

  • On the other hand jltensor has a compile time number of dimensions, specified with a template parameter. Shapes of jltensor instances are stack allocated, making jltensor a significantly faster expression than jlarray.

Example 1: Use an algorithm of the C++ standard library with Julia array.

C++ code

#include                         // Standard library import for std::accumulate
#include                    // CxxWrap import to define Julia bindings
#include "xtensor-julia/jltensor.hpp"     // Import the jltensor container definition
#include "xtensor/xmath.hpp"              // xtensor import for the C++ universal functions

double sum_of_sines(xt::jltensor m)
{
    auto sines = xt::sin(m);  // sines does not actually hold values.
    return std::accumulate(sines.cbegin(), sines.cend(), 0.0);
}

JULIA_CPP_MODULE_BEGIN(registry)
    cxx_wrap::Module mod = registry.create_module("xtensor_julia_test");
    mod.method("sum_of_sines", sum_of_sines);
JULIA_CPP_MODULE_END

Julia Code

using xtensor_julia_test

arr = [[1.0 2.0]
       [3.0 4.0]]

s = sum_of_sines(arr)
s

Outputs

1.1350859243855171

Example 2: Create a numpy-style universal function from a C++ scalar function

C++ code

#include 
#include "xtensor-julia/jlvectorize.hpp"

double scalar_func(double i, double j)
{
    return std::sin(i) - std::cos(j);
}

JULIA_CPP_MODULE_BEGIN(registry)
    cxx_wrap::Module mod = registry.create_module("xtensor_julia_test");
    mod.method("vectorized_func", xt::jlvectorize(scalar_func));
JULIA_CPP_MODULE_END

Julia Code

using xtensor_julia_test

x = [[ 0.0  1.0  2.0  3.0  4.0]
     [ 5.0  6.0  7.0  8.0  9.0]
     [10.0 11.0 12.0 13.0 14.0]]
y = [1.0, 2.0, 3.0, 4.0, 5.0]
z = xt.vectorized_func(x, y)
z

Outputs

[[-0.540302  1.257618  1.89929   0.794764 -1.040465],
 [-1.499227  0.136731  1.646979  1.643002  0.128456],
 [-1.084323 -0.583843  0.45342   1.073811  0.706945]]

Building the HTML Documentation

xtensor-julia's documentation is built with three tools

While doxygen must be installed separately, you can install breathe by typing

pip install breathe

Breathe can also be installed with conda

conda install -c conda-forge breathe

Finally, build the documentation with

make html

from the docs subdirectory.

Running the C++ tests

From deps/build

cmake -D JlCxx_DIR=/path/to/.julia/v0.5/CxxWrap/deps/usr/share/cmake/JlCxx -D BUILD_TESTS=ON ..

Dependencies on xtensor and CxxWrap

xtensor-julia depends on the xtensor and CxxWrap libraries

xtensor-julia xtensor CxxWrap
master ^0.13.1 ^0.5.0
0.0.9 ^0.13.1 ^0.5.0
0.0.8 ^0.12.0 ^0.5.0
0.0.7 ^0.11.0 ^0.5.0
0.0.6 ^0.11.0 ^0.5.0

These dependencies are automatically resolved when using the Julia package manager.

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 file for details.

First Commit

03/31/2017

Last Touched

17 days ago

Commits

137 commits

Used By: