Overview

MyraMath can be built natively on Linux using the supplied Makefile. Some slight modification of the Makefile is to be expected, in particular you must supply the directives to link in LAPACK and the BLAS. Some test programs are provided to help you debug this step, once they are building you may continue on to build the rest of the library. MyraMath ships with a large number of tests, you can build and run them with a supplied test-runner to verify the library is behaving as expected. The Makefile also contains phony targets for producing the doxygen documentation and API tutorials. These materials may prove useful when you are developing your own new projects that use MyraMath.

Below are links to the sections of this page:

Modifying the Makefile for your platform

The supplied GNU Makefile is included for building on Linux platforms or on Windows machines running Cygwin (though bear in mind that a native Windows build will probably perform better than Cygwin). It will require some small modifications for your platform. In particular:

The CC variable should be set to the desired compiler. Both GNU Compiler Collection and clang are suitable.
The CPPFLAGS and LDFLAGS should (i) enable C++11 (ii) enable OpenMP (iii) establish the name mangling convention for LAPACK and the BLAS (more on this on a moment)
The LDFLAGS should also be populated with all the linker settings needed to find LAPACK and the BLAS.

Among these, linking LAPACK/BLAS and name mangling are the non-obvious steps. Basically, LDFLAGS needs to point to the .a's or .so's that implement LAPACK and the BLAS for your platform. On Cygwin, the reference LAPACK and BLAS implementation are implemented within /lib/liblapack.a and /lib/libblas.a, respectively. Alternatively, you can use MyraKL, a partial LAPACK/BLAS implementation that is open-source and can be built natively on Linux or Cygwin.

In addition to populating LDFLAGS, you also need to pick the correct name-mangling scheme via a #define within CPPFLAGS. For MyraKL, -DMYRAMATH_MANGLE_BLAS0 and -DMYRAMATH_MANGLE_LAPACK0 is suitable. This will mangle all LAPACK/BLAS symbols to lowercase and add a leading myra_, yielding symbols like myra_sgemm() for example. Other LAPACK/BLAS implementations might have their own mangling schemes, try using nm to examine the symbols in your LAPACK/BLAS library, then consult linktest/mangle_lapack.h to find a matching variant of -DMYRAMATH_MANGLE_BLASx and -DMYRAMATH_MANGLE_LAPACKx.

To help you debug these steps, there are two special targets:

make link_blas.out: a small test program that requires the BLAS
make link_lapack.out: a small test program that requires LAPACK

They don't depend upon anything else in the library, so you can quickly iterate/debug these linking and mangling settings.

Building the library

Once link_blas.out and link_lapack.out are built and are producing correct answers, build libmyramath.so and the accompanying testers via:

make lib -j12
make tests -j12
make profiles -j12
make tutorials -j12

Environment settings

MyraMath is internally multithreaded so you should use a singlethreaded LAPACK/BLAS layer to avoid oversubscription. Consult the documentation of your LAPACK/BLAS install to find out how to configure it to use just one thread. Some LAPACK/BLAS providers (like MKL) provide environment variables to control threading (like MKL_NUM_THREADS), while other providers (like ACML) move this choice to link-time by providing different .a's for parallel/serial implementations. Note that MyraKL is a sequential library, so it works fine out of the box. In either case, there are also a few environment variables that should be set to configure MyraMath's threading behavior. You can invoke these commands from a terminal session, or add them once and for all in your .bashrc equivalent:

export MYRAMATH_NUM_THREADS= number of physical [not hyperthreaded] cores

Running tests

MyraMath ships with a collection of regression tests that can help end users to verify/debug a new build. The unit tests (and tutorial programs, etc) are all based on the MyraTest framework/test-runner. Try running myramath_tests.out -help to get started, or browse the MyraTest tutorial for more information.

You probably don't need to run all of the tests, but a few interesting selections are given below:

myramath_tests.out -run -add=[dense]: tests with the [dense] tag verify correctness of the BLAS/LAPACK install.
myramath_tests.out -run -add=maxthreads: verifies that MYRAMATH_NUM_THREADS reports multiple threads.
myramath_tests.out -run -add=pgemm_speedup: evaluates thread-parallel efficiency for pgemm(), matrix multiplication.
myramath_tests.out -run -add=rcholesky2*: verifies sparse solver functionality on small 2D problems.
myramath_profile.out -run -add=rcholesky3_factor: evaluates sparse solver thread-parallel efficiency on user-sized 3D problems

Once this collection of tests is passing you can be reasonably confident that MyraMath is correctly built and ready for use. There are many additional tests (thread-parallel BLAS3 tests tagged [pdense], tests for the other types of sparse solvers tagged [multifrontal], etc) to browse if you need to verify something specific. In addition to checking correctness, these tests are also meant to serve as "living documentation" of how to use the library.

Building documentation

Documentation for MyraMath can be scraped directly from the commented source code using Doxygen:

make doxygen

This also builds and runs all the unit tests, capturing their output. The documentation is rooted from doc/html/index.html, so open that local file in your web browser to get started.

Creating new projects of your own

This tutorial concludes by writing a small example program that uses MyraMath. In a new folder of your choosing, create a file example.cpp with the following contents:

#include <myramath/dense/Matrix.h>
#include <myramath/dense/inverse.h>
#include <myramath/dense/gemm.h>
#include <myramath/dense/threshold.h>
#include <iostream>
using namespace myra;
int main()
  {
  auto A = Matrix<double>::random(3,3);
  auto Z = inverse(A);
  std::cout << A << std::endl;
  std::cout << Z << std::endl;
  std::cout << threshold(Z*A,1.0e-12) << std::endl;
  return 0;
  }

To compile example.cpp, you must:

Indicate the include directory for MyraMath, using g++ you'd say -I/path/to/myramath_source
Indicate the linking directory for MyraMath, using g++ you'd say -L/path/to/myramath_source
Append a link directive for libmyramath.so, using g++ you'd say -lmyramath
Append a link directive for OpenMP, using g++ you'd say -fopenmp
Append any special MyraMath defines. For g++ I'd suggest -DMYRAMATH_ENABLE_OMP and -DMYRAMATH_ENABLE_CPP11

MyraMath is directly under my home directory (/home/Ryan/myramath_source), so I'd compile example.cpp by saying:

g++ -std=c++0x example.cpp -o example.out -I/home/Ryan/myramath_source -L/home/Ryan/myramath_source -lmyramath -fopenmp -DMYRAMATH_ENABLE_OMP -DMYRAMATH_ENABLE_CPP11

To run example.out, you must:

Append the path containing "libmyramath.so" to your LD_LIBRARY_PATH. For example, export LD_LIBRARY_PATH=/home/Ryan/myramath_source:$LD_LIBRARY_PATH.
Append the path containing your BLAS/LAPACK install to your LD_LIBRARY_PATH. For example, export LD_LIBRARY_PATH=/home/Ryan/myrakl_source:$LD_LIBRARY_PATH.
These might be worth adding to your .bashrc if you use MyraMath a lot.

The expected output of example.cpp is something like:

size 3 by 3 matrix of double: 
[ 0.380002 0.10957 -0.585236 ]
[ 0.0108368 -0.243142 0.252524 ]
[ 0.182981 -0.484536 -0.319746 ]
size 3 by 3 matrix of double: 
[ 3.41954 5.44463 -1.95887 ]
[ 0.848852 -0.246375 -1.74825 ]
[ 0.670571 3.48915 -1.59923 ]
size 3 by 3 matrix of double: 
[ 1 0 0 ]
[ 0 1 0 ]
[ 0 0 1 ]

At this point, you've covered all the build steps required to integrate MyraMath into new or existing projects. Now would be a good time to take a guided tour through the API Tutorials. You can copy/paste the source code from any of the tutorial .cpp files into this project you just created, and test things out for yourself.

Appendix: Out-of-source builds

The supplied makefile can be modified slightly for an out-of-source build using the VPATH feature of GNU make. For an out-of-source build, copy the Makefile into a separate build folder, then update the MYRAMATH_HOME variable within it to point back to the project root. This is useful when you want to simultaneously maintain multiple builds of MyraMath with different compiler settings (e.g. debug vs release).

You can of course use the Makefile as-is for an in-source build, just leave MYRAMATH_HOME=. and invoke make as usual.

Please note that the Doxygen documentation can only be built in-source. All documentation products are dumped into doc/html (and subfolders).

Go back to Building and Dependencies