Installation¶

CMake¶

The simplest method to install the library and build the examples is to use CMake. For the default install, we suggest the following. First, extract the source

tar -zxvf yee_crbc_lib.tar.gz


We suggest building the library in a separate directory. For this example we will call the directory ‘build’. Then, we simply have to invoke CMake.

mkdir build
cd build
cmake ../yee_crbc_lib
make
make install


This will install the library and build the examples.

The library uses some functionality of C++11. For most modern compilers, we have found that it is not necessary to include any special compiler flags to use these features (e.g. Intel 15+, GNU 4.8+). However, some compilers do require we specifically tell it to use C++11. At this time it appears that CMake only identifies these flags correctly for the GNU compilers, so it may be necessary to tell CMake to include the appropriate flag. For example:

cmake ../yee_crbc_lib -DCMAKE_CXX_FLAGS:STRING=-std=c++11


The correct flag varies by compiler. Also note that if your compiler uses the GNU STL implementation, it is necessary that the GNU library version be >=4.8.

Options¶

There are additional options that can be enabled.

Shared Library¶

To build the shared version of the library use the command

-DBUILD_SHARED="ON"


Install Path¶

The default install places the library file in /usr/local/lib and places the header files in /usr/local/include/yeecrbc, although this behavior can vary from system to system. The install can be changed to place the library in /usr/lib and the headers in /usr/include/yeecrbc, for example, by adding the following CMake option.

-DCMAKE_INSTALL_PREFIX:PATH=/usr


Example Locations¶

By default the examples are built in the build directory, so they can be found in <path>/build/examples. They can be built at another location by setting the example_dir variable. From the command line you can change by adding the option

-Dexample_dir:STRING="<path to install examples>"


Index and Data Types¶

The defaults are to use the int type for indexing and the double type for the field data type and coefficient data type. In the C interfaces, the indexing type can be changed to the long int or long long data type by adding the following command line options to the CMake invocation

-DINDEX_TYPE:STRING="long int"


or

-DINDEX_TYPE:STRING="long long"


Similarly, the data type we use for a majority of the computations can be changed from the default type of double to float by adding the following

-DUSE_CRBC_SCALAR_FLOAT="ON"


and the coefficient data type can be changed from double to float with

-DUSE_CRBC_COEF_FLOAT="ON"


Note that the underlying C++ code and interfaces is templated on the index and data types, so these commands only affect the C interfaces.

Save and Restart¶

The library includes the optional ability to save the state of the boundary updater and restart from a previously saved state. This functionality requires the use of the HDF5 library. To enable this function from the command line add the following to the CMake invocation

-DUSE_HDF5_RESTARTS=ON


-DUSE_OPENMP=ON


Debugging¶

To build in Debug mode, add

-DCMAKE_BUILD_TYPE=Debug


Some additionaly error checking and messages can be enabled with the option

-DENABLE_EXTRA_DEBUG="ON"


Note that builds with these options enabled significantly degrades performance.

In order to link with Cmake, a CMakeLists.txt file should include

find_package(yeecrbc REQUIRED)


Depending on the install location Cmake may or may not be able to locate the libraries configuration file. If it is not found, the variable yeecrbc_DIR needs to be set to the install location. Using the default install settings this can be done with the following CMake command

-Dyeecrbc_DIR=/usr/local/lib


Alternatively, this can be set in the CMakeLists.txt file by adding

set(yeecrbc_DIR "/usr/local/lib")


To link to the library, add -lyeecrbc to the compile string. If the library was not installed in a standard path, it is necessary to provide the path to the library and the header files. For example, using the typical default install settings

-L/usr/local/lib -lyeecrbc -I/usr/local/include/yeecrbc


Since the majority of the library is written in C++, -lstdc++ is often needed to compile.

If the HDF5 restart capability is enabled, the HDF library also needs to be included in the linking. Typically, this is done with -lhdf5. If the threading is enabled, the appropriate OpenMP compiler flag needs to be included. For the GNU compilers, the flag is -fopenmp; for Intel compilers, the flag is -openmp; and for Portland Group compilers, the flag is -mp.

export LD_LIBRARY_PATH=\$LD_LIBRARY_PATH:/usr/local/lib