|
librsb
1.3
|
A sparse matrix library implementing the `Recursive Sparse Blocks' (RSB) matrix storage.
This is the documentation for the application programming interface (API) of the `librsb' library.
In order to use librsb, there is no need for the user to know the RSB layout and algorithms: this documentation should be sufficient.
librsb is dual-interfaced; it supports: a native (`RSB') interface (with identifiers prefixed by `rsb_' or `RSB_'), and a (mostly complete) Sparse BLAS interface, as a wrapper around the RSB interface.
Many computationally intensive operations are implemented with thread parallelism, by using OpenMP.
Thread parallelism can be turned off at configure time, if desired, or controlled at execution time.
Many of the computational kernels source code files (mostly internals) were automatically generated.
This user documentation concerns the end user API only.
This library was born as research software.
Over the years it has been stabilized and its test suite expanded considerably.
There are projects making available librsb in Octave, Python or Julia; you might want to check them out as well.
For a first approach, see the Example programs and code documentation section, or the quick start examples section on this page.
Information about the supported matrix types and matrix operations resides in the rsb_types.h file.
A C/C++ user can use the native API of RSB by including the rsb.h header.
The same interface is available in Fortran via the ISO C Binding interface, specified in rsb.F90.
An experimental C++ API is available in (optional) rsb.hpp.
The C header file for The Sparse BLAS interface to librsb (blas_sparse.h, rsb_blas_sparse.F90) is blas_sparse.h (notice there is no native C++ equivalent).
Contents of the README file :
librsb README file
================================================================================
librsb - Recursive Sparse Blocks Matrix computations library
--------------------------------------------------------------------------------
A library for sparse matrix computations featuring the Recursive Sparse Blocks
(RSB) matrix format, geared towards cache efficient and multi-threaded
(that is, shared memory parallel) operations on large sparse matrices.
It provides the most common operations necessary to iterative solvers, like
matrix-vector and matrix-matrix multiplication, triangular solution, scaling of
rows/columns, diagonal extraction / setting, blocks extraction, computation of
norm, formats conversion.
The RSB format is especially well suited for symmetric and transposed
multiplication variants.
Much of the source code is machine-generated; the supported numerical types can
be chosen by the user at build time.
This library is dual-interfaced: it can be used via the native (`RSB`)
interface (with function identifiers prefixed by `rsb_` or `RSB_`), and a
Sparse BLAS one (function identifiers prefixed by `BLAS_`).
The `RSB` interface can be used from C/C++ (`rsb.h` header) or via modern
Fortran ISO-C-BINDING (`rsb` module in `rsb.F90`).
New in version 1.3 is the C++-only API in `rsb.hpp` (`Rsb`-prefixed classes).
The Sparse BLAS interface is usable from C/C++ via the `blas_sparse.h` header,
and from Fortran via the `blas_sparse` module.
--------------------------------------------------------------------------------
This (README) is the first document you should read about librsb.
It contains basic instructions to configure, build, install, and use librsb.
The reference documentation for programming with librsb is contained in the
`./doc/` source package subdirectory and when installed, placed in the
appropriate system directories as both Unix man pages (`./doc/man/`) and HTML
(`./doc/html/`).
If you have used a previous release version of librsb, see the `NEWS` file
for a succinct list of user-relevant changes.
INTRODUCTION
--------------------------------------------------------------------------------
librsb is a library for sparse matrix algebra computations.
It is stand-alone: it does not require any other library to build or work.
It is shared memory parallel, using constructs from the OpenMP standard.
It is focused on high performance SpMV and SpMM operations.
A part of the library code is automatically generated from templates and
macros, on the basis of the numerical types a user wishes to have supported.
The configure script provides many build time options, especially with respect
to debug and additional verbosity (see `configure --help`).
Defaults should be fine for most users, though.
- INTRODUCTION
- MAIN ASPECTS,FEATURES
- QUICK INSTALL AND TESTING EXAMPLE
- LIBRARY CONFIGURATION, GENERATION, BUILD
- INSTALLATION, USAGE
- EXECUTION AND ENVIRONMENT VARIABLES
- DOCUMENTATION, EXAMPLES AND PROGRAMMING GUIDELINES
- CONFIGURE, BUILD AND BENCHMARK EXAMPLE
- COMPATIBILITY
- FAQ
- POSSIBLE FUTURE ENHANCEMENTS
- ABOUT THE INTERNALS
- BUGS
- CONTACTS
- CREDITS
- LICENSE
MAIN ASPECTS,FEATURES
--------------------------------------------------------------------------------
* conceived for efficient multithreaded SpMV/SpMM
* thread level (shared memory) parallelism by using OpenMP
* threads/structure auto-tuning feature for additional performance
* support for multiple numerical data types which can be turned
on/off individually (e.g.:`double`, `float`, `int`, `char`, `float complex`,
`double complex`) at configure time
* a Sparse BLAS interface for matrix assembly, computation, destruction
* code generators for the inner CSR, COO computational kernels
* based on a recursive memory layout of submatrices
* enough functionality to implement the most common iterative methods
* basic input sanitizing (index types overflow checks, etc)
* parallel matrix assembly and conversion routines
* auxiliary functions for matrix I/O (using the "Matrix Market" format:
real, integer, complex and pattern are supported)
* implemented as a building block for solvers like e.g. PSBLAS, MaPHyS++
* dual implementation of inner kernels: with "full-" and "half-word" indices
* basic (unoptimized) sparse matrices multiplication and summation
* interactive usage possible by using the `sparsersb` plugin for GNU Octave
or the PyRSB Python package
* complete with examples and a test suite
* see the `NEWS` text file for a detailed list of changes in each release
QUICK INSTALL AND TESTING EXAMPLE
--------------------------------------------------------------------------------
# unpack the archives or get them from the repositories
./autogen.sh # only necessary if configure file does not exist
./configure --prefix=$HOME/local/librsb/ # with installation destination
# see also ./configure --help for many other options
# librsb has been configured
make help # provide information
make # build the library and test programs
# librsb has been built
make qtests # perform brief sanity tests
make qqtests # the same, but with less output
make tests # perform extended sanity tests
ls examples/*.c # editable C examples; build them with 'make'
ls examples/*.cpp # editable C++ examples; build them with 'make'
ls examples/*.F90 # editable Fortran examples; build them with 'make'
make install # install to $HOME/local/librsb/
make itests # perform post-installation tests on examples
# librsb has been installed and can be used
# for instance, try using one of the librsb examples as a base:
mkdir -p ~/rsb-test/ && cp examples/hello.c ~/rsb-test/myrsb.c
# adapt hello.c to your needs and recompile:
cd ~/rsb-test/
export PATH=$PATH:$HOME/local/librsb/bin/
gcc `librsb-config --I_opts`. -c myrsb.c
gcc -o myrsb myrsb.o `librsb-config --static --ldflags --extra_libs`
./myrsb # run your program
LIBRARY CONFIGURATION, GENERATION, BUILD
--------------------------------------------------------------------------------
A good portion of this library is C code generated via M4 macros.
Certain generation options (notably, supported numerical types) can be set via
the `./configure` script.
The M4 preprocessor executable can be specified explicitly to `./configure`
with the `M4` environment variable or via the `--with-m4` option.
After invoking `./configure` and before running `make` it is possible to invoke
`make cleanall` to make sure that auto-generated code is deleted first.
The `configure` script attempts at detecting the system cache memory hierarchy
parameters and prints them out.
If detection fails, you can pass them via the `--with-memhinfo=...` option.
For instance, declaring having 3 MB of L3, 256 kB of L2, and 32 kB of L1:
`./configure --with-memhinfo="L3:12/64/3072K,L2:8/64/256K,L1:8/64/32K" `
These values need not be exact: also approximate can help achieving better
performance.
You can override the configure-time default at run time: see API documentation.
Read a few sections further for a description of the memory hierarchy info
string format.
If you want to enable Fortran examples, be sure of running `./configure` with
the `--enable-fortran-examples` option. You can specify the desired Fortran
compiler and compilation flags via the `FC` and `FCFLAGS` variables.
Set the `CPPFLAGS` variable at configure time to provide additional compilation
flags; e.g. `configure` to detect necessary headers in non-standard location.
Similarly, the `LDFLAGS` variable can be set to contain link time options; so
you can use it to specify libraries to be linked to librsb examples.
Invoke `./configure --help` for details of other relevant environment
variables.
The `./configure` script will emit information about the current build options.
If all went fine, you can invoke `make` to build the library and the examples.
To check for library consistency, run:
make qtests # takes a short time, spots most problems
or
make tests # takes longer, qtests is usually enough
If these tests terminate with an error code, it may be that it has been caused
by a bug in librsb, so please report it (see BUGS).
These tests also check error reporting capabilities, so don't be scared by
error messages appearing in the running output.
INSTALLATION, USAGE
--------------------------------------------------------------------------------
Once built, the library can be installed with e.g.:
sudo make install # 'sudo' may be needed for system-wide locations
This installs header files, binary library files, documentation, examples,
and the `librsb-config` program.
Then, application C programs should include the `rsb.h` header file with
`#include <rsb.h>`
C++ programs can use that as well, or `#include <rsb.hpp>`.
Path to the librsb headers and extra options can be obtained via
`librsb-config --I_opts`.
To link to the librsb library and its dependencies one can use the output of
`librsb-config --static --ldflags --extra_libs`.
Users of `pkg-config` can manually copy the `librsb.pc` file to the appropriate
directory to use `pkg-config` in a way similar to `librsb-config`.
EXECUTION AND ENVIRONMENT VARIABLES
--------------------------------------------------------------------------------
By default, librsb reads the environment variable
`RSB_USER_SET_MEM_HIERARCHY_INFO`, which allows to override settings of memory
hierarchy set at configure-time or detected at runtime.
Its value is specified as n concatenated strings of the form:
L<l>:<a_l>/<b_l>/<c_l>
These strings are separated by a comma (","), and each of them is made
up from substrings where:
<n> is the cache memories hierarchy height, from 1 upwards.
<l> is the cache level, from 1 upwards.
<a_l> is the cache associativity
<b_l> is the cache block size (cache line length)
<c_l> is the cache capacity (size)
The `<a_l>`, `<b_l>`, `<c_l>` substrings consist of an integer number with an
optional multiplier character among {K,M,G} (to specify respectively 2^10,
2^20 or 2^30).
Any value is permitted, a long as it is positive. Higher level cache
capacities are required to be larger than lower level ones.
Please note that currently, only the cache capacity value is being used.
Example strings and usage in the BASH shell:
RSB_USER_SET_MEM_HIERARCHY_INFO="L2:4/64/512K,L1:8/64/32K" <your program>
RSB_USER_SET_MEM_HIERARCHY_INFO="L1:8/128/2M" <your program>
Experimenting with this environment variable can help tuning performance.
Setting this environment variable may be also needed if automatic detection
fails (e.g. very recent systems).
A default value for this memory hierarchy info string can be set at configure
time by using the `--with-memhinfo` configure option.
If you don't know values for these parameters, you can run the
`./scripts/linux-sys-cache.sh`
script to try to get a guess on a Linux system.
On other systems, please consult the available documentation.
E.g.: On Mac OS 10.6 it was possible to get this information by invoking
`sysctl -a | grep cache`.
You can control the active threads count with OpenMP variable
`OMP_NUM_THREADS`, but also override it via `RSB_NUM_THREADS`.
DOCUMENTATION, EXAMPLES AND PROGRAMMING GUIDELINES
--------------------------------------------------------------------------------
The latest API documentation is reachable from http://librsb.sourceforge.net/ .
The `<rsb.h>` header file specifies the C API of librsb.
Header `<rsb.hpp>` provides two C++ classes for librsb and most of the
functionality of `<rsb.h>`.
The complete API documentation is generated by the `doxygen` tool in the `doc`
directory in both HTML and man formats, and gets installed with `make install`.
The librsb man pages can be listed with `apropos rsb` or `man -k rsb`.
If you wish not to use doxygen (or don't have it) you can skip documentation
generation by adding the `DOXYGEN=false` argument to `./configure`.
The `examples` directory has a number of working example programs.
The library declares symbols prefixed by `rsb_`.
To avoid name clashes, you should avoid declaring identifiers prefixed that way
in programs using librsb.
If `configure` has been invoked with the `--enable-sparse-blas-interface`, then
the corresponding `BLAS_`- and `blas_`- prefixed symbols will also be built.
CONFIGURE, BUILD AND BENCHMARK EXAMPLE
--------------------------------------------------------------------------------
The performance-critical parts of librsb are written in C and C++.
Compilation flags for C and C++ are specified by the CFLAGS and CXXFLAGS
variables
Fortran flags can be set by FCFLAGS, but are of minor importance.
A sensible setup can be:
./configure CC=gcc CFLAGS='-Ofast' CXX=g++ CXXFLAGS='-Ofast -std=c++17' FC=gfortran --prefix=/opt/librsb
You should be able to specify other combination of compilers, like icx+icpx+ifc
or icc+icpc+ifort. If you have luck, even mix compilers from different suites.
If you wish to build the librsb benchmark program with the MKL library (say,
for performance comparison purposes), you can use one of the following three
recipes as a base.
With gcc, 64 bit (and a few more options you may want to adapt):
export MKLROOT=/opt/intel/mkl
./configure \
CC=gcc CFLAGS='-Ofast' \
CXX=g++ CXXFLAGS='-Ofast -std=c++17' \
FC=gfortran \
--with-mkl="-static -L${MKLROOT}/lib/intel64 \
-Wl,--start-group,-lmkl_intel_lp64,-lmkl_gnu_thread,-lmkl_core,--end-group \
-fopenmp -lpthread" \
--with-memhinfo=L2:4/64/512K,L1:8/64/24K \
--with-mkl-include=/opt/intel/mkl/include/
With icc, 64 bit)
export MKLROOT=/opt/intel/mkl
./configure \
CC=icc CFLAGS='-Ofast' \
CXX=icpc CXXFLAGS='-Ofast -std=c++17' \
FC=ifort \
--with-mkl="-static -L${MKLROOT}/lib/intel64 -openmp -lpthread \
-Wl,--start-group,-lmkl_intel_lp64,-lmkl_intel_thread,-lmkl_core,--end-group" \
--with-memhinfo=L2:4/64/512K,L1:8/64/24K \
--with-mkl-include=/opt/intel/mkl/include/
or 32 bit:
./configure \
CC=gcc CFLAGS='-Ofast'
CXX=g++ CXXFLAGS='-Ofast -std=c++17' \
FC=gfortran \
--with-memhinfo=L2:4/64/512K,L1:8/64/24K \
--with-mkl="-static -L/opt/intel/mkl/lib/ia32/ -lmkl_solver \
-Wl,--start-group,-lmkl_intel,-lmkl_gnu_thread,-lmkl_core,--end-group \
-fopenmp -lpthread" \
--with-mkl-include=/opt/intel/mkl/include/
Once you chose your configure options, you want to build.
make cleanall # (optional) delete generated sources
make # build library, documentation, tests, examples
make qtests # optional
make install # optional
make itests # optional
If you modified configure options impacting code generation, may want to run
`make cleanall`, which deletes stale sources and ensures sources re-generation
before the 'make'.
To speed up 'make', consider using the parallelism option, e.g.:
make -j 3 # use 3 build threads
After the build, say you want to benchmark the library for SpMV/SpMM.
You have a Matrix Market file representing a matrix, `A.mtx`,
you want to use 1 and 4 cores, and type Z (double complex).
With SpMV, and SpMM with 2 right hand sides laid in C order.
Then running:
./rsbench -oa -Ob --bench -f A.mtx -qH -R -n1,4 -T z --verbose --nrhs 1,2 --by-rows
will output performance and timing results in a tabular form.
If not specifying a type (argument to the `-T` option), all will be used.
If configured in at build time, choices may be `-T D` (where `D` is the BLAS
prefix for `double`), `-T Z` (`Z` stands for `double complex`) and so on.
You can also pass `-T :` to specify all of the configured types.
For more options and configuration information, invoke:
./rsbench -oa -Ob --help
./rsbench --help
./rsbench --version
./rsbench -I
./rsbench -C
An example Matrix Market matrix file contents:
%%MatrixMarket matrix coordinate pattern general
% This is a comment.
% See other examples in the distributed *.mtx files.
2 2 3
1 1
2 1
2 2
COMPATIBILITY
--------------------------------------------------------------------------------
This library was developed mostly on Debian Linux and using only free software.
This library has been built and tested on Unix machines.
Microsoft Windows users can try building librsb under the Cygwin environment.
(Ancient comment kept for the nostalgic reader)
Some tricks may have to be used on IBM AIX. For instance, adding the
`--without-xdr` or the `--without-zlib` switch to `./configure`.
Your mileage may vary.
AIX's `make` program may give problems; use the GNU version `gmake` instead;
the same shall be done with the M4 interpreter.
FAQ
--------------------------------------------------------------------------------
Q: **Can you provide me good configure defaults for an optimized build ?**
A: Default `./configure` options are appropriate for an optimized build.
A good starting point for `gcc` is `./configure CC=gcc CFLAGS='-O3'`.
However, if you need complex arithmetic and are using GCC, I'd advise using
-Ofast. On many versions of GCC I observed sub-optimal complex arithmetic
performance with `-O3`, regardless use of e.g. `-mtune=native`.
For more, consult your compiler documentation (e.g. `man gcc`, `man icx`,
`man icc`),
and learn about the best flags for your specific platform.
Striping your executable (`make install-strip` for librsb's `rsbench`) may
help.
Q: **I am a beginner and I wish librsb to be very verbose when I invoke
library interface functions incorrectly.
Can you provide me good configure defaults for such a "debug" build ?**
A: Yes: via the `./scripts/configure_for_debug.sh` script.
Q: **I have problems linking, seems like some Fortran library is missing.
What should I do?**
A: Did you try `./configure --enable-fortran-linker` ?
Q: **I have machine X, compiler Y, compiling flags Z; is SpMV performance P
with matrix M good ?**
A: In general, hard to tell. You can `make hinfo.log` and send to me (see
CONTACTS) the `hinfo.log` file and your matrix in Matrix Market format
(well, please don't send matrices by email but rather upload them
somewhere on the web and send an URL to them).
The `hinfo.log` file will contain useful compile and machine information.
Then I *may* get an idea about the performance you should get with that
matrix on that computer.
Q: **What is the Sparse BLAS ?**
A: It's a programming interface specification:
* [sparseblas_2001]:
BLAS Technical Forum Standard, Chapter 3, Sparse BLAS.
http://www.netlib.org/blas/blast-forum/chapter3.pdf
* [dhp_2002]:
An Overview of the Sparse Basic Linear Algebra Subprograms:
The New Standard from the BLAS Technical Forum.
IAIN S. DUFF, CERFACS and Rutherford Appleton Laboratory.
MICHAEL A. HEROUX, Sandia National Laboratories.
ROLDAN POZO, National Institute of Standards and Technology.
* [dv_2002]:
Algorithm 818:
A Reference Model Implementation of the Sparse BLAS in Fortran 95.
IAIN S. DUFF, CERFACS, France and Atlas Centre, RAL, England.
CHRISTOF VÖMEL, CERFACS, France.
Q: **Is there an easy way to profile librsb usage in my application ?**
A: Yes: build with `--enable-librsb-stats` and extract time elapsed in librsb
via e.g.:`rsb_lib_get_opt(RSB_IO_WANT_LIBRSB_ETIME,&etime);`.
Q: **Why another sparse matrix library ?**
A: This library is the fruit of the author's PhD work, focused on researching
improved multi threaded and cache friendly matrix storage schemes for e.g.
PSBLAS.
Q: **What are the key features of this library when compared to other ones ?**
A: Recursive storage, a code generator, parallel BLAS operations
(including matrix assembly, matrix-matrix multiplication, transposed
matrix-vector multiply), a rich test suite, a Sparse BLAS
interface and a free software licensing.
Q: **How do I detect librsb from my package's `configure` script ?**
A: Please check out `examples/configure.ac` and `examples/makefile.am`:
Q: **How is correctness checked in the librsb test suite ?**
A: In different ways, often configuration dependent.
Check out the `qtests` and `tests` targets in the Makefile.
Q: **Why did you originally write the library in C and not in C++ ?**
A: C is pretty easy to interface with C++ and Fortran.
Using a debugger in C++ can be a headache.
Also C's `restrict` keyword.
Q: **Why did you use C and not Fortran ?**
A: This library is slightly system-oriented, and system calls interfacing is
much easier in C. Also C's pointer arithmetic was desirable.
Q: **Is there a quick and easy way to perform an artificial performance
test with huge matrices without having to program ?**
A: Express your matrix in a Matrix Market format as the `A.mtx` file and
use it as e.g.:**
./rsbench -oa -Ob --bench -f A.mtx --verbose --nrhs 1,4 --by-rows
Q: **I've found a bug! What should I do ?**
A: First please make sure it is really a bug:
read the documentation, check, double check.
Then you can write a description of the problem, with a minimal program
source code and data to replicate it.
Then you can jump to the CONTACTS details section.
Q: **Is it possible to build matrices of, say, `long double` or
`long double complex` or `int` or `short int` ?**
A: Yes. Invoke the configure script accordingly, e.g.:
`--enable-matrix-types="long double"` or
`--enable-matrix-types="double,long double,double complex"`
If this breaks code compilation, feel free to contact the author
(see the CONTACTS section).
Note that some combinations may break `make qtests` or other test recipes.
Q: **Is there a way to compare the performance of this library to some other
high performance libraries ?**
A: If you build `rsbench` with support for the Intel MKL library, then you
can do performance comparisons with e.g.:
`# ./rsbench -oa -Ob -qH -R --gen-diag 100 --compare-competitors --verbose`
or use the following script:
`# bench/dense.sh ' '`
Or even better, check out the `--write-performance-record` feature.
For details see the output of:
`# rsbench -oa -Ob --help`
Q: **Is there a non-threaded (serial) version of librsb ?**
A: Yes: you can configure the library to work serially (with no OpenMP).
See `./configure --help`.
Q: **Is this library thread-safe ?**
A: Probably yes: no static buffers are being used, and reentrant C standard
library functions are invoked.
Q: **Does the librsb library run on GPUs?**
A: Not yet.
Q: **I built and compiled the code without enabling any BLAS type (S,D,C,Z),
and both `make qtests` and `make tests` ran successfully outside the
`./examples` directory, but `make tests` breaks within `./examples`
directory.**
A: Well, the tests passed because the examples testing was simply skipped.
The example programs need at least one of these types to work.
Q: **At build time I get many "unused variable" warnings. Why ?**
A: librsb accommodates many code generation and build time configuration
options. Some combinations may turn off compilation of certain parts of the
code, leading some variables to be unused.
Q: **Are there papers to read about the RSB format and algorithms ?**
A: Yes, the following:
* Michele Martone, Simone Bacchio.
Portable performance on multi-threaded Sparse BLAS operations with PyRSB
Proceedings of SciPy 2021 (Scientific Python Conference).
https://doi.org/10.25080/majora-1b6fd038-00e
* Michele Martone.
Efficient Multithreaded Untransposed, Transposed or Symmetric Sparse
Matrix-Vector Multiplication with the Recursive Sparse Blocks Format.
Parallel Computing 40(7): 251-270 (2014).
http://dx.doi.org/10.1016/j.parco.2014.03.008
* Michele Martone.
Cache and Energy Efficiency of Sparse Matrix-Vector Multiplication for
Different BLAS Numerical Types with the RSB Format.
Proceedings of the ParCo 2013 conference, September 2013, Munich, Germany.
PARCO 2013: 193-202.
http://dx.doi.org/10.3233/978-1-61499-381-0-193
* Michele Martone, Marcin Paprzycki, Salvatore Filippone.
An Improved Sparse Matrix-Vector Multiply Based on Recursive Sparse Blocks
Layout.
LSSC 2011: 606-613.
http://dx.doi.org/10.1007/978-3-642-29843-1_69
* Michele Martone, Salvatore Filippone, Salvatore Tucci, Marcin Paprzycki,
Maria Ganzha.
Utilizing Recursive Storage in Sparse Matrix-Vector.
Multiplication - Preliminary Considerations. CATA 2010: 300-305
* Michele Martone, Salvatore Filippone, Marcin Paprzycki, Salvatore Tucci.
Assembling Recursively Stored Sparse Matrices. IMCSIT 2010: 317-325.
http://www.proceedings2010.imcsit.org/pliks/205.pdf
* Michele Martone, Salvatore Filippone, Pawel Gepner, Marcin Paprzycki,
Salvatore Tucci.
Use of Hybrid Recursive CSR/COO Data Structures in Sparse Matrices-Vector
Multiplication.
IMCSIT 2010: 327-335.
http://dx.doi.org/10.1109/SYNASC.2010.72
* Michele Martone, Salvatore Filippone, Marcin Paprzycki, Salvatore Tucci.
On BLAS Operations with Recursively Stored Sparse Matrices.
SYNASC 2010: 49-56.
http://dx.doi.org/10.1109/SYNASC.2010.72
* Michele Martone, Salvatore Filippone, Marcin Paprzycki, Salvatore Tucci.
On the Usage of 16 Bit Indices in Recursively Stored Sparse Matrices.
SYNASC 2010: 57-64.
http://dx.doi.org/10.1109/SYNASC.2010.77
Q: **I have M4-related problems on IBM SP5/SP6 (my M4 preprocessor tries to
regenerate code but it fails). What should I do ?**
A: A fix is to use a GNU M4 implementation
e.g.: `M4=/opt/freeware/bin/m4 ./configure ...`
e.g.: `M4=gm4 ./configure ...`
or execute:
`touch *.h ; touch *.c ; make`
Or `./configure; make` the library on a different machine, then build
a sources archive with `make dist`, and use it on the original machine.
And BTW, consider donating them machines to a computer museum, like
https://museo.freaknet.org/
POSSIBLE FUTURE ENHANCEMENTS
--------------------------------------------------------------------------------
* auxiliary functions for numerical vectors
* CSC,BCSR,BCSC and other block-level formats
* performance prediction/estimation facilities (experimental)
* types of the blocks, nonzeroes, and coordinates indices can be user specified
* automatic matrix blocking selection (for BCSR/BCSC)
* an arbitrary subset of block size kernels can be specified to be generated
* recursive storage variants of blocked formats (non uniform blocking)
* more auto-tuning and prediction control
ABOUT THE INTERNALS
--------------------------------------------------------------------------------
The following good practices are being followed during development of librsb:
- only symbols beginning with `rsb_` or `blas_` or `BLAS_` are being exported
- internal functions are usually prefixed by `rsb__`
- no library internal function is expected to call any API function
BUGS
--------------------------------------------------------------------------------
If you encounter any bug (e.g.: mismatch of library/program behaviour and
documentation, please let me know about it by sending me (see CONTACTS) all
relevant information (code snippet, originating data/matrix, `config.log` ), in
such a way that I can replicate the bug behaviour on my machines.
If the bug occurred when using rsb interfaced to some proprietary library,
please make sure the bug is in librsb.
It may be of great help to you to build the library with the debug compile
options on (e.g.: `CFLAGS='-O0 -ggdb'`), and with appropriate library verbosity
levels, e.g. (`--enable-internals-error-verbosity=1` and
`--enable-interface-error-verbosity=1` options to configure) to better
understand the program behaviour before sending a report.
Make sure you have the latest version of the library when reporting a bug.
CONTACTS
--------------------------------------------------------------------------------
You are welcome to contact the librsb author:
Michele Martone `<michelemartone AT users DOT sourceforge DOT net>`
Please specify "librsb" in the "Subject:" line of your emails.
More information and downloads on http://sourceforge.net/projects/librsb
Mailing list: https://lists.sourceforge.net/lists/listinfo/librsb-users
CREDITS (in alphabetical order)
--------------------------------------------------------------------------------
For librsb-1.3:
* Matthieu A. Simonin for testing, discussion and suggestions.
* Rafael Laboissiere for continued help in aspects of build, documentation,
testing and distribution.
For librsb-1.2:
* Marco Atzeri provided testing, patches to build librsb under cygwin over
nearly each release, and spotted a few bugs.
* Fabio Cassini spotted an unintended conversion via sparsersb and +.
* John Donoghue spotted a rendering corner case bug.
* Sebastian Koenig spotted a computational bug in -rc6.
* Rafael Laboissiere helped a lot improving the documentation and the build
system.
* Mu-Chu Lee provided a patch to fix sorting code crashing with > 10^9 nnz.
* Constanza Manassero spotted an inconsistency in the usmm/ussm interface.
* Markus Muetzel helped debugging rsb_mtx_rndr().
* Dmitri Sergatskov spotted a double free in rsb_mtx_rndr() and convinced about
the necessity of sanitizing memory usage.
For librsb-1.1:
* Gilles Gouaillardet provided a patch for OpenMP-encapsulated I/O.
* Marco Restelli provided with testing and detailed comments and suggestions.
For librsb-1.0:
* Francis Casson helped with testing and documentation reviewing during
the first release.
* Nitya Hariharan helped revising early versions of the documentation.
ACKNOWLEDGEMENTS
--------------------------------------------------------------------------------
In 2019-2021, librsb has been developed under the PRACE-6IP-WP8 (GRANT
AGREEMENT NUMBER 823767 -- PRACE-6IP) EU project LyNcs (partners:
Computation-based Science and Technology Research Centre (CaSToRC) of The
Cyprus Institute and Inria).
LICENSE
--------------------------------------------------------------------------------
This software is distributed under the terms of the Lesser GNU Public License
version 3 (LGPLv3) or later.
See the COPYING file for a copy of the LGPLv3.
librsb is free software.
To support it, consider writing to the author and acknowledging use of librsb
in your publications.
All that would be very appreciated.
--------------------------------------------------------------------------------
For a quick startup, consider the following three example programs.
The first, using the RSB interface (for native C++, please see the optional rsblib/examples/example.cpp):
The second, using the Sparse BLAS interface:
For more, see the Example programs and code section.
1.8.13