============================================== The Augmented Block Cimmino Distributed Solver ============================================== **Note:** Check for more details. Tested plateforms ----------------- Working ======= * Linux x86_64 with GNU 4.7 and 4.8 compilers,``MKL``, ``ACML``, reference blas and lapack. Not Working =========== * Fujitsu FX with Fujitsu compilers: - ``PaToH`` is not compatible (users have to request a compatible version from the authors) - Our Logging library is not compatible with Fujitsu compilers, should work with GNU compilers. * Microsoft Windows: - ``MUMPS`` does not support Windows (there is an unofficial guide to compile it under Windows, but we do not provide any pre-compiled library for it) - ``PaToH`` is not compatible (users have to request a compatible version from the authors) You can disable ``PaToH`` by running cmake with the option ``-DPATOH=OFF``. Not Tested ========== * Mac OSX was not tested but should be fully compatible. Obtaining the source code ------------------------- The ABCD Solver depends on a few external libraries: ``MUMPS``, ``Sparselib++ (custom)``, ``PaToH``, ``lapack`` and ``Boost::MPI`` version 1.50 or higher. * A patched version of ``MUMPS`` is distributed with our solver in the ``lib/mumps/`` directory. Only the headers and a compiled version (``Linux x86_64``, other version will be available uppon request) is distributed. When ``MUMPS 5.0`` is released, it should be used instead. * ``Sparselib++ (custom)``: a modified version of ``SparseLib++`` to suits our needs, is also distributed with our solver in the ``lib/sparselib`` directory. The library is compiled same as MUMPS, but you still can recompile it by running ``make all`` in ``lib/sparselib`` directory. * ``PaToH``: Can be downloaded from the webpage of `Ümit V. Çatalyürek <>`_ (URL available in the following script). The file ``libpatoh.a`` has to be copied into the ``lib/`` directory and the header `patho.h` has to be copied into the ``include`` directory. * ``BLAS`` and ``LAPACK`` are both mandatory. We provide configurations to build the solver using ``ACML`` and ``MKL``. * ``BLACS`` and ``ScaLAPACK`` are required by ``MUMPS``, therefore they are needed when you link your software with the solver. We explicitly require them so that we can build the examples. * ``Boost::MPI`` requires ``MPI`` and so does ``MUMPS``. You can install it either from source or through your distribution repositories. The solver was tested with versions 1.47, 1.49 and 1.54. However, we recommend to use versions higher than 1.50. The installation can be done by typing the following commands in your terminal .. code-block:: bash # download the latest stable version # it will create a directory named abcd git clone # download the appropriate version of patoh from # # copy libpatoh.a to the lib/ directory # copy patoh.h to the include/ directory Now that everything is ready, we can compile the solver. To do so, we need a configuration file from the ```` directory, suppose we are going to use the ``ACML`` library that provides ``BLAS`` and ``LAPACK``. .. code-block:: bash # get the appropriate configuration file cp ./ To use ``MKL`` instead, copy the file ````: .. code-block:: bash # get the appropriate configuration file cp ./ You can use the `Intel® Math Kernel Library Link Line Advisor <>`_ to customize the configuration. Edit the file ```` so that it reflects your configuration (path to libraries, file names, path to MPI, etc). Building the library -------------------- The build process is done using ``cmake``: .. code-block:: bash # create a building directory mkdir build # run cmake cd build cmake .. # if everything went correctly you can run make make # the files will be in directory lib/ ls lib # gives libabcd.a If cmake does not finish correctly, here are some possible reasons: * ``mpic++`` is either not installed or there is an issue with ``mpi`` libraries, check also that you gave the right path in your ```` file. * ``Boost`` is either not installed, or the version is too old. Check that ``Boost::MPI`` is installed. * The path to some libraries is not well defined in ````. Running ABCD ------------ You can run the solver without having to write a code (as we do in the next section). After building the library, a binary is created called ``abcd_run``, it uses a configuration file that you will find in the directory ``test/src/`` that you need to copy to your build directory. .. code-block:: bash cd build cp ../ . # to try ABCD on a provided small test matrix, without having to write any code, # abcd_run looks by default for the file in the current directory mpirun -np 16 ./abcd_run You can also give the executable the path to your configuration file: .. code-block:: bash mpirun -np 16 ./abcd_run /path/to/configuration_file The configuration file incorporates comments with details about all possible options and how to use them. Building an example (to call ABCD from C++ or C) ------------------------------------------------- Once the library is built, you can compile the given examples (either C++ or C): .. code-block:: bash # the C++ example called `example.cpp` and the # C example called `example.c` are in the examples directory cd examples # create a directory where to build your examples mkdir build_example cd build_example # tell cmake where the abcd solver is located # the current version supposes that the library was built within # the directory ``build`` in a release mode # if you get an error while running cmake, check that you gave the # absolute path to the abcd solver directory cmake .. -DABCD=/absolute/path/to/abcd/ make # if everything went correctly, try to run the C++ example mpirun -np 16 ./example # or if you want to run the C example: mpirun -np 16 ./example_c Issue tracker ------------- If you find any bug, didn't understand a step in the documentation, or if you have a feature request, submit your issue on our `Issue Tracker <>`_ by giving: - reproducible steps - a source code, or a snippet where you call the solver - a matrix file if possible.