Commit e6c2e40a authored by Fuchsi*'s avatar Fuchsi*

bringing the debugging tutorial up to date

parent 83e14fc2
Pipeline #704 failed with stages
in 4 minutes and 48 seconds
......@@ -2,12 +2,13 @@
Potentially breaking changes are marked with an exclamation point '!' at the begin of their description.
* 2016-??-?? v3.0.0
* 2017-??-?? v3.0.0
* Python wrapper now stable.
* ! REQUIRE macro now logs as error instead of fatal error.
* ! All macros and preprocessor defines now use the XERUS_ prefix. The config.mk file changed accordingly.
* ! TT::find_largest_entry and TT::dyadic_product left the TT scope.
* ! Tensor::modify_diag_elements renamed to Tensor::modify_diagonal_entries for naming consistency.
* Added a highly optimized minimal version of the ALS algorithm as xALS.
* Some minor bugfixes.
* 2016-06-23 v2.4.0
......@@ -26,7 +27,7 @@ Potentially breaking changes are marked with an exclamation point '!' at the beg
* Bug fix in the handling of fixed indices in TensorNetworks.
* Several static member function now warn if their return type is not used.
* Initial support for compilation with the intel ICC.
* 2016-03-11 v2.2.1
* Added support for 32bit systems.
......
......@@ -44,7 +44,7 @@ The output of this executable should then list a number of passed tests and end
-------------------------------------------------------------------------------
~~~
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).
can in our [issuetracker](https://git.hemio.de/xerus/xerus/issues) or write us an [email](mailto:contact@libxerus.org).
## Building the Library
......
......@@ -44,6 +44,6 @@ entry might look as follows
author = {Huber, Benjamin and Wolf, Sebastian},
title = {Xerus - A General Purpose Tensor Library},
howpublished = {\url{https://libxerus.org/}},
year = {2014--2016}
year = {2014--2017}
}
~~~
......@@ -4,52 +4,60 @@
## LOG
The library uses a macro of the form `LOG(level, msg)` to print messages to `cout`. It allows to use arbitrary log levels without any need to declare them beforehand
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
LOG(als_warning, "The ALS encountered a mishap " << variable_1 << " <= " << variable_2);
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 `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
`SET_LOGGING(als_warning, err::NO_LOGGING)` inside a commonly included header (like `include/xerus/tensorLogger.h`).
variable `XERUS_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 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
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 `REQUIRE(condition, additional_msg)` macro replaces assertions in the `xerus` library. It uses above `LOG` functionality and can thus use piping style messages just as the `LOG`
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
REQUIRE(condition, additional_msg) = if (!(condition)) { LOG(fatal, additional_msg); }
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 DISABLE_RUNTIME_CHECKS_` in the `config.mk` file.
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 with the `UNIT_TEST(group_name, test_name, source_code...)` macro. This will only include the
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 TEST_COVERAGE_`, the executable will track which `REQUIRE` and `REQUIRE_TEST` macros were executed during the run to advice
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 `NO_FANCY_CALLSTACK = TRUE` was declared in the `config.mk` file, the function `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 `LOG(fatal, ...)` and `REQUIRE(...)` macros to simplify the detection of errors.
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::generic_error() << "callstack:\n" << xerus::get_call_stack());
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.
......@@ -123,7 +123,7 @@ namespace xerus {
}
// Sweep Right -> Left
// Sweep Left -> Right
for(size_t corePosition = 0; corePosition < d; ++corePosition) {
Tensor op, rhs;
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment