new layout for documentation / libxerus.org

doc/advanced.md

-# Notes for Advanced Users
-
-## Multi-Threading
-
-Please note, that `xerus` is only thread-safe up to 1024 threads at the time of this writing. This number is due to the internal handling of indices. To ensure that indices can 
-be compared and identified uniquely, they store a unique id of which the first 10 bits are reserved to denote the number of the current thread. With more than 1024 threads (when these
-10 bits overflow) it can thus lead to collisions and indices that were shared between threads and were meant to be seperate suddenly evaluate to be equal to all algorithms.
-
-

doc/new/.gitignore

+_site
+

doc/new/_config.yml

+# Jekyll configuration
+
+name: Xerus Documentation
+description: Documentation for the xerus library.
+
+# baseurl will often be '', but for a project page on gh-pages, it needs to
+# be the project name.
+# *** IMPORTANT: If your local "jekyll serve" throws errors change this to '' or
+#     run it like so: jekyll serve --baseurl=''
+baseurl: ''
+
+permalink: /:title
+# paginate: 3
+
+highlighter: rouge
+# highlighter: coderay
+markdown: kramdown
+# gems: ['jekyll-paginate']
+
+# exclude: ['README.md', 'LICENSE']

doc/new/_posts/2000-10-20-debugging.md

+---
+layout: post
+title: "Debugging"
+date: 2000-10-20 16:25:06 +0000
+topic: "Advanced Usage"
+section: "Documentation"
+---
+
+
+# Debugging
+
+`xerus` comes with a number of functionalities to simplify debugging. The purpose of this page is to explain the most important ones.
+
+## LOG
+
+The library uses a macro of the form `XERUS_LOG(level, msg)` to print messages to `cout`. It allows to use arbitrary log levels without any need to declare them beforehand
+and to use typical piping syntax for the messages.
+~~~.cpp
+XERUS_LOG(als_warning, "The ALS encountered a mishap " << variable_1 << " <= " << variable_2);
+~~~
+The following warning levels are predefined: `fatal`, `critical`, `error`, `warning`, `info`, `debug`. The default config file `config.mk.default` defines the preprocessor
+variable `XERUS_LOG_INFO` which causes all but the `debug` level to be printed. Per default any other log-level is printed. This can be turned off by including 
+`XERUS_SET_LOGGING(level, xerus::err::NO_LOGGING)` inside a commonly included header.
+
+The `fatal` loglevel is special in that it will not just print the message but also throw an exception including the message itself and a callstack in the `.what()` string.
+
+With the additional option `LOGGING += -D XERUS_LOG_BUFFER` in the `config.mk` file, any not printed log message will be stored in a circular buffer and will be dumped to a file
+in the `errors/` subfolder (if it exists) on any `error`, `critical` or `fatal` log message. 
+
+
+## REQUIRE
+
+The `XERUS_REQUIRE(condition, additional_msg)` macro replaces assertions in the `xerus` library. It uses above `XERUS_LOG` functionality and can thus use piping style messages just as the `XERUS_LOG`
+macro. It is equivalent to the following definition
+~~~.cpp
+XERUS_REQUIRE(condition, additional_msg) = if (!(condition)) { XERUS_LOG(fatal, additional_msg); }
+~~~
+There is a large number of such checks in the library. All of them can be turned off by defining `DEBUG += -D XERUS_DISABLE_RUNTIME_CHECKS` in the `config.mk` file.
+
+
+## UNIT_TEST
+
+Compiling with `make test` creates an executable that includes all functions defined within `xerus::UnitTest` objects.
+~~~.cpp
+static xerus::misc::UnitTest objectName("Group", "Name", [](){
+    // source code of the test
+    // likely includes (several) tests of the form TEST(condition);
+    TEST(true);
+});
+~~~
+This will only include the 
+unit tests in the library but can easily be extended should you wish to use it for your own executable. The created executable can be launched manually to perform individual
+tests (eg. `./XerusTest TTTensor:summation`) or reperform all of them (`./XerusTest all`).
+
+With the additional `config.mk` option `DEBUG += -D XERUS_TEST_COVERAGE`, the executable will track which `XERUS_REQUIRE` and `XERUS_REQUIRE_TEST` macros were executed during the run to advice 
+about function that need additional testing.
+
+
+## Callstacks and XERUS_THROW
+
+Unless `XERUS_NO_FANCY_CALLSTACK = TRUE` was declared in the `config.mk` file, the function `xerus::misc::get_call_stack()` will return a formatted string of the full stack trace including function name,
+source file and line numbers. This stack will in particular be included in the exceptions thrown by `XERUS_LOG(fatal, ...)` and `XERUS_REQUIRE(...)` macros to simplify the detection of errors.
+
+The information of this callstack is only available if the application was compiled with the `-g` flag and the linking requires the `binutils` packages `-lbfd -lz -ldl -liberty`.
+
+The exceptions used by `xerus` have the additional capability to accept piped information that will be included in the `.what()` string. To include a callstack it is thus possible to 
+simply write
+~~~.cpp
+XERUS_THROW(xerus::misc::generic_error() << "callstack:\n" << xerus::misc::get_call_stack());
+~~~
+The used macro will additionally include the source file and line as well as the function name in which the exception was thrown.
+

doc/new/_posts/2000-10-25-optimization.md

+---
+layout: post
+title: "Optimization"
+date: 2000-10-25 16:25:06 +0000
+topic: "Advanced Usage"
+section: "Documentation"
+---
+
+
+# Optimizations
+
+If you are like us, you want to get the fastest possible version of your numerical code to run as many samples as possible and
+solve the largest systems possible. To this end there are a number of possible optimizations already provided for you by the 
+`xerus` library. The following list expands on the most relevant of them in roughly the order of effectiveness.
+
+## Disabling Runtime Checks
+The library contains many runtime checks for out-of-bounds access, other invalid inputs (like illegal contractions), consistency
+and even to check the correct behaviour of internal structures. Depending on the complexity your code and the time spent inside
+`xerus` (and not one of the libraries it uses) you can expect a large performance gain by disabling these checks in the `config.mk`
+file during compilation of xerus.
+
+It is not advisable to do this while developing, as it will be much more difficult to detect errors in your calls to `xerus`
+functions, but once you have established, that your code works as expected you might want to try replacing the `libxerus.so` object
+used by your project with one compiled with the `-D XERUS_DISABLE_RUNTIME_CHECKS` flag.
+
+## Use c++ instead of Python
+The interface between the languages python and c++ makes it necessary to perform operations for the sole purpose of compatibility
+between the otherwise incompatible languages. Often this includes copies of vectors of integers (whenever dimensions are specified
+or queried) and sometimes even deep copies of whole tensors (`.from_ndarray()` and `.to_ndarray()`). The only way to get rid of
+this overhead is to write your appliation in c++ instead of python. Most instructions that `xerus` offers for python look very
+similar in c++, so a transition might be simpler than you think. Simply check out the rest of the tutorials to compare the code
+snippets.
+
+## Compiling Xerus with High Optimizations
+Per default the library already compiles with high optimization settings (corresponding basically to `-O3`) as there is rarely
+any reason to use lower settings for numerical code. If you want to spend a significant amount of cpu hours in numerical code
+using the `xerus` library though, it might be worthwile to go even further.
+
+The most significant change in runtime speed gains due to compiler settings at this point will come from link-time optimizations
+(for `c++`projects using `xerus`).
+To make use of them you will need a sufficiently recent versions of the `g++` compiler and `ar` archiver. After compiling the
+`libxerus.so` object with the `USE_LTO = TRUE` flag you can then enable `-flto` in your own compilation process. The optimizations
+that will be used then extending more than a single compilation unit and might thus use significant system resources during 
+compilation.
+
+If link-time optimization is not an option (or not sufficient) it is also possible to replace the high optimizations flag in your
+`config.mk` file with the `DANGEROUS_OPTIMIZATION = TRUE` flag. This will enable non-IEEE-conform optimizations that should
+typically only change floating point results in the least significant bit but might lead to undefined behaviour in case a `NaN`
+or overflow is encountered during runtime. (It is rumored that there is an even higher optimization setting available for `xerus`
+for those who know how to find it and want to get even the last 1% of speedup...)
+
+
+## Avoiding Indexed Expressions
+The comfort of being able to write Einstein-notation-like equations in the source code of the form `A(i,k) = B(i,j)*C(j,k);` 
+comes with the price of a certain overhead during runtime. It is in the low single-digit percent range for typical applications
+but can become significant when very small tensors are being used and the time for the actual contraction thus becomes negligible.
+
+In such cases it can be useful to replace such equations (especially ones that are as simple as above) with the explicit statement 
+of contractions and reshuffels. For above equation that would simply be
+~~~.cpp
+contract(A, B, false, C, false, 1);
+~~~
+i.e. read as: contract two tensors and store the result in A, left hand side B, not transposed, right hand side C, not transposed, contract a single mode.
+
+If it is necessary to reshuffle a tensor to be able to contract it in such a way, e.g. `A(i,j,k) = B(i,k,j)`, this can be done
+with the `reshuffle` function.
+~~~.cpp
+reshuffle(A, B, {0,2,1});
+~~~
+
+It is our opinion that code written with these functions instead of indexed espressions are often much harder to understand
+and the speedup is typically small... but just in case you really want to, you now have the option to use them.
+

doc/new/_posts/2000-11-28-indices.md

+---
+layout: post
+title: "Indices and Equations"
+date: 2000-11-28 16:25:06 +0000
+topic: "Basic Usage"
+section: "Documentation"
+---
+
+
+# Indices and Equations
+
+## Blockwise Construction of Tensors
+

doc/new/_posts/2000-12-15-nomenclature.md

+---
+layout: post
+title: "Nomenclature"
+date: 2000-12-15 16:25:06 +0000
+topic: "Introduction"
+section: "Documentation"
+---
+
+
+# Nomenclature
+
+Tensor (Network) methods were developed independently in several different fields. As such there is a large variety of different
+names for the same concepts and at times even several concepts for the same name, depending on the context.
+
+To avoid confusion we want to explain the terms as they are used throughout this library. Unfortunately we are not aware of any 
+introductory publication using our exact notation and nomenclature, but everybody familiar with the notation from Numerical Analysis
+will be familiar with most definitions. We saw it necessary to expand these terms though to have precise names for every aspect.
+
+Tensor, degree, dimension, mode, index, multi-index, position, span, slate, entry, (element - unused??), contraction, shuffling, 
+TensorNetwork, Node, external link
+TTTensor, TTOperator, rounding, core, cannonical form, component
+

doc/new/_posts/2000-12-20-building_xerus.md

+---
+layout: post
+title: "Building Xerus"
+date: 2000-12-20 16:25:06 +0000
+topic: "Introduction"
+section: "Documentation"
+---
+
+
+# Building Xerus
+
+## Obtaining Xerus
+
+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
+~~~
+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`. 
+Make sure that all these are installed on your system before proceeding.
+
+E.g. to install all dependencies on a fedora system execute
+~~~
+dnf install gcc-c++ openblas-devel suitesparse-devel lapack-devel binutils-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`
+~~~
+cp config.mk.default config.mk
+nano config.mk
+~~~
+
+## Making Sure Everything Works as Intended
+The sources include a number of unit tests that ensure that everything works as intended. To perform them simply input
+~~~
+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
+~~~
+|
+|                       total summary 132 of 132 passed
+-------------------------------------------------------------------------------
+|
+|                       Total time elapsed: 10848.406 ms
+-------------------------------------------------------------------------------
+~~~
+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 
+can in our [issuetracker](https://git.hemio.de/xerus/xerus/issues) or write us an [email](mailto:contact@libxerus.org).
+
+
+## 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 you want to install `xerus` on your system to the path given in `config.mk` simply 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.
+
+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`).
+
+You can test this by trying to compile the tutorial file (in this example without the installed `xerus` library)
+~~~
+g++ -std=c++11 tutorials/fulltensor.cpp libxerus.a -llapacke -llapack -lcblas -lblas -lcxsparse -lbfd -liberty -lz -ldl
+~~~
+

doc/new/css/syntax.css

+/* This css file is the colorful.css theme from https://github.com/iwootten/jekyll-syntax */
+
+.highlight .hll { background-color: #ffffcc }
+.highlight  { background: #ffffff; }
+.highlight .c { color: #888888 } /* Comment */
+.highlight .err { color: #FF0000; background-color: #FFAAAA } /* Error */
+.highlight .k { color: #008800; font-weight: bold } /* Keyword */
+.highlight .o { color: #333333 } /* Operator */
+.highlight .cm { color: #888888 } /* Comment.Multiline */
+.highlight .cp { color: #557799 } /* Comment.Preproc */
+.highlight .c1 { color: #888888 } /* Comment.Single */
+.highlight .cs { color: #cc0000; font-weight: bold } /* Comment.Special */
+.highlight .gd { color: #A00000 } /* Generic.Deleted */
+.highlight .ge { font-style: italic } /* Generic.Emph */
+.highlight .gr { color: #FF0000 } /* Generic.Error */
+.highlight .gh { color: #000080; font-weight: bold } /* Generic.Heading */
+.highlight .gi { color: #00A000 } /* Generic.Inserted */
+.highlight .go { color: #888888 } /* Generic.Output */
+.highlight .gp { color: #c65d09; font-weight: bold } /* Generic.Prompt */
+.highlight .gs { font-weight: bold } /* Generic.Strong */
+.highlight .gu { color: #800080; font-weight: bold } /* Generic.Subheading */
+.highlight .gt { color: #0044DD } /* Generic.Traceback */
+.highlight .kc { color: #008800; font-weight: bold } /* Keyword.Constant */
+.highlight .kd { color: #008800; font-weight: bold } /* Keyword.Declaration */
+.highlight .kn { color: #008800; font-weight: bold } /* Keyword.Namespace */
+.highlight .kp { color: #003388; font-weight: bold } /* Keyword.Pseudo */
+.highlight .kr { color: #008800; font-weight: bold } /* Keyword.Reserved */
+.highlight .kt { color: #333399; font-weight: bold } /* Keyword.Type */
+.highlight .m { color: #6600EE; font-weight: bold } /* Literal.Number */
+.highlight .s { background-color: #fff0f0 } /* Literal.String */
+.highlight .na { color: #0000CC } /* Name.Attribute */
+.highlight .nb { color: #007020 } /* Name.Builtin */
+.highlight .nc { color: #BB0066; font-weight: bold } /* Name.Class */
+.highlight .no { color: #003366; font-weight: bold } /* Name.Constant */
+.highlight .nd { color: #555555; font-weight: bold } /* Name.Decorator */
+.highlight .ni { color: #880000; font-weight: bold } /* Name.Entity */
+.highlight .ne { color: #FF0000; font-weight: bold } /* Name.Exception */
+.highlight .nf { color: #0066BB; font-weight: bold } /* Name.Function */
+.highlight .nl { color: #997700; font-weight: bold } /* Name.Label */
+.highlight .nn { color: #0e84b5; font-weight: bold } /* Name.Namespace */
+.highlight .nt { color: #007700 } /* Name.Tag */
+.highlight .nv { color: #996633 } /* Name.Variable */
+.highlight .ow { color: #000000; font-weight: bold } /* Operator.Word */
+.highlight .w { color: #bbbbbb } /* Text.Whitespace */
+.highlight .mf { color: #6600EE; font-weight: bold } /* Literal.Number.Float */
+.highlight .mh { color: #005588; font-weight: bold } /* Literal.Number.Hex */
+.highlight .mi { color: #0000DD; font-weight: bold } /* Literal.Number.Integer */
+.highlight .mo { color: #4400EE; font-weight: bold } /* Literal.Number.Oct */
+.highlight .sb { background-color: #fff0f0 } /* Literal.String.Backtick */
+.highlight .sc { color: #0044DD } /* Literal.String.Char */
+.highlight .sd { color: #DD4422 } /* Literal.String.Doc */
+.highlight .s2 { background-color: #fff0f0 } /* Literal.String.Double */
+.highlight .se { color: #666666; font-weight: bold; background-color: #fff0f0 } /* Literal.String.Escape */
+.highlight .sh { background-color: #fff0f0 } /* Literal.String.Heredoc */
+.highlight .si { background-color: #eeeeee } /* Literal.String.Interpol */
+.highlight .sx { color: #DD2200; background-color: #fff0f0 } /* Literal.String.Other */
+.highlight .sr { color: #000000; background-color: #fff0ff } /* Literal.String.Regex */
+.highlight .s1 { background-color: #fff0f0 } /* Literal.String.Single */
+.highlight .ss { color: #AA6600 } /* Literal.String.Symbol */
+.highlight .bp { color: #007020 } /* Name.Builtin.Pseudo */
+.highlight .vc { color: #336699 } /* Name.Variable.Class */
+.highlight .vg { color: #dd7700; font-weight: bold } /* Name.Variable.Global */
+.highlight .vi { color: #3333BB } /* Name.Variable.Instance */
+.highlight .il { color: #0000DD; font-weight: bold } /* Literal.Number.Integer.Long */

doc/new/css/theme.css

+body {
+    padding-top: 60px;
+    padding-bottom: 60px;
+}
+
+.copyright {
+    color: #ffffff;
+}
+
+.footer {
+    text-align: center;
+}
+
+.footer a {
+    color: #ee4444;
+}
+
+.sidebar h1 {
+    color: #ee4444;
+    font-size: 1.3em;
+}
+
+.sidebar a {
+    color: #428bca;
+}
+
+.sidebar li {
+    margin-top: .7em;
+    line-height: 1em;
+}
+
+.sidebar a:hover {
+    color: #3071a9;
+}
+
+.container-left {
+    margin: 0;
+}
+
+.well h1 {
+    color: #ee4444;
+    font-size: 1.3em;
+}
+
+.author {
+    color: #ee4444;
+}
+
+.author a {
+    color: #ee4444;
+}

doc/new/documentation.md

+---
+layout: post
+section: "Documentation"
+---
+
+# xerus - a general purpose tensor library    {#mainpage}
+
+## Introduction
+
+The `xerus` library is a general purpose library for numerical calculations with higher order tensors, Tensor-Train Decompositions / Matrix Product States and general Tensor Networks.
+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.
+* 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.
+* Direct integration of the `blas` and `lapack`, as high performance linear algebra backends.
+* 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.
+* [Tensor Class](@ref md_tensor) - an introduction into the most important functions relating to the `xerus::Tensor` class.
+* [TT Tensors](_t_t-_tensors_01_07_m_p_s_08-example.html) - using the MPS or Tensor-Train decomposition.
+* [Optimization](@ref md_optimization) - some hints how to achieve the fastest possible numerical code using `xerus`.
+* [Debugging](@ref md_tut_debugging) - using `xerus`'s capabilities to debug your own application.
+
+## Issues
+
+Should you have any problems with the library do not hesitate to contact us at [contact[at]libxerus.org](mailto:contact[at]libxerus.org) or describe your problem in the [issuetracker](https://git.hemio.de/xerus/xerus/issues).
+
+
+## Licence and Attribution
+
+The `xerus` library is published under the AGPL v3.0. With proper attribution you are thus allowed to freely use and modify the source code but if you distribute your software including the `xerus`
+library (or you provide a service based on this library) you have to provide the full source code under a compatible licence. For more information see the [AGPL](http://www.gnu.org/licenses/agpl-3.0.html).
+
+If this library proved useful in your scientific research we would be grateful for any contributions to the source code and citations. As there is no related article yet, a corresponding bibtex 
+entry might look as follows
+~~~
+@Misc{xerus,
+	author = {Huber, Benjamin and Wolf, Sebastian},
+	title = {Xerus - A General Purpose Tensor Library},
+	howpublished = {\url{https://libxerus.org/}},
+	year = {2014--2017}
+}
+~~~