You can get the source-code of the `xerus` library via [git](https://git.hemio.de/xerus/xerus/tree/master) or as an [archiv](https://git.hemio.de/xerus/xerus/repository/archive.tar.gz?ref=master).
For example to clone the repository with the latest stable version under linux simply type
~~~
~~~ bash
git clone https://git.hemio.de/xerus/xerus.git
~~~
## Dependencies and Configuration
`Xerus` depends on several well established libraries, usually pre-installed or available through the standard package managers. In particular `lapacke`, `CXSparse`, `binutils`
and their dependencies. Also note that at at least version 4.8 of the `GCC` is required, as this is the first version to offer support for all `C++11` functionality used in `xerus`.
`Xerus` depends on several well established libraries, usually pre-installed or available through the standard package managers. In particular `lapacke`, `CXSparse`, `binutils`, `boost`
and their dependencies. Also note that at least version 4.8 of the `GCC` is required, as this is the first version to offer support for all `C++11` functionality used in `xerus`.
Make sure that all these are installed on your system before proceeding.
E.g. to install all dependencies on a fedora system execute
To build the python bindings you will furthermore need the python development headers, `numpy` as well as `boost-python` or
`boost-python3` depending on the python version you wish to use. E.g. for a fedora system and if you want to use python 2 simply execute
~~~ bash
dnf install python2-numpy python-devel
~~~
After downloading the source it is necessary to set a number of options that are somewhat individual to your system and needs. All following build steps assume that these
options are set in the `config.mk` file. Reasonable default values can be found in the `config.mk.default` file.
In particular the optimization level is interesting and the paths or standard flags for the required libraries need to be set. This way the `xerus` library can be compiled with any
`blas` compatible library for the matrix operations. For more details see the description in the `config.mk.default`
~~~
`blas` compatible library for the matrix operations. For more details see the description in the `config.mk.default` file
~~~ bash
cp config.mk.default config.mk
nano config.mk
~~~
## Making Sure Everything Works as Intended
## Ensure Everything Works as Intended
The sources include a number of unit tests that ensure that everything works as intended. To perform them simply input
~~~
~~~ bash
make test-j4
~~~
(where `-j4` allows make to use up to 4 threads for the compilation). If all options were set correctly in the `config.mk` it should compile a test executable and launch it.
The output of this executable should then list a number of passed tests and end with
The output of this executable should then list a number of passed tests and end with something similar to
Note in particular, that all tests were passed. Should this not be the case please file a bug report with as many details as you
...
...
@@ -58,29 +64,34 @@ can in our [issuetracker](https://git.hemio.de/xerus/xerus/issues) or write us a
## Building the Library
If all tests were passed you can build the library simply by calling make
~~~
make all -j4
~~~
this creates the shared library object `libxerus.so` as well as the static library object `libxerus.a`.
If all tests were passed you can build the library simply by calling `make shared` or `make static` depending on whether you want
to build shared or static library objects. To build all shared objects as well as the python bindings use `make python`. After
the compilation you should have a `build/` directory with a `libxerus_misc.a/.so` (suffix depending on build type), a `libxerus.a/.so`
and the `xerus.so` for python in case you also built the python bindings.
If you want to install `xerus` on your system to the path given in `config.mk` simply call (as root if necessary)
~~~
make install
~~~
You can use these objects directly by setting your environment variables accordingly or you can install the library to a path
already included in these variables. To do so simply set the path in `config.mk` and call (as root if necessary) `make install`.
## Compiling your own Applications Using Xerus
If `xerus` is properly installed on your system, compiling your own applications using `xerus` is as simple as using any other library. Just include `-lxerus` in your linker call and make sure to use
`-std=c++11` or `-std=c++14` in all compilation units that include `xerus.h` and everything should work.
`-std=c++11` or `-std=c++14` in all compilation units that include `xerus.h` and everything should work fine.
If you want to use the static version of `xerus` you also have to include all libraries `xerus` depends on in your linker call. In particular these are lapacke (`-llapacke`),
lapack (`-llapack`), blas (`-lblas` or `-lopenblas` or similar), suitesparse (`-lumfpack -lspqr`), binutils (`-lbfd`). On some old system one has to manually include the dependencys of binutils (`-liberty -lz -ldl`).
lapack (`-llapack`), blas (`-lblas` or `-lopenblas` or similar), suitesparse (`-lcholmod -lspqr`) and binutils (`-lbfd`). On some old system one has to manually include the dependencys of binutils (`-liberty -lz -ldl`).
You can test this by trying to compile the tutorial file (in this example without the installed `xerus` library)
You can test this by trying to compile one of the examples (here without the installed `xerus` library)
# xerus - a general purpose tensor library {#mainpage}
# Xerus
## Introduction
...
...
@@ -10,7 +12,8 @@ The `xerus` library is a general purpose library for numerical calculations with
The focus of development was the simple usability and adaptibility to any setting that requires higher order tensors or decompositions thereof.
The key features include:
* Modern code and concepts incorporating many features of the new `C++11` standard.
* Modern code and concepts incorporating many features of the `C++11` standard.
* Full python bindings with very similar syntax for easy transitions from and to c++.
* Calculation with tensors of arbitrary orders using an intuitive Einstein-like notation `A(i,j) = B(i,k,l) * C(k,j,l);`.
* Full implementation of the Tensor-Train decompositions (MPS) with all neccessary capabilities (including Algorithms like ALS, ADF and CG).
* Lazy evaluation of multiple tensor contractions featuring heuristics to find the most effective contraction order.
...
...
@@ -18,13 +21,11 @@ The key features include:
* Fast sparse tensor calculation by usage of the `suiteSparse` sparse matrix capabilities.
* Capabilites to handle arbitrary Tensor Networks.
## Version History
We released our first stable version 1.0 in May 2015 and are currently at version 2.2.1. It can be obtained via [git](https://git.hemio.de/xerus/xerus) or as an archived download via the same link.
The current development version is also available in the same git repository (branch 'development') and it might include more features than the latest stable release, but be adviced that these development versions are particularly bad documented and might change drastically from one day to the next.
## Getting Started
There are a number of tutorials to get you started using the `xerus` library.
*[Building xerus](@ref md_building_xerus) - instruction on how to build the library iteself and your first own program using it.
*[Quick-Start guide](_quick-_start-example.html) - a short introduction into the basic `xerus` functionality.
