Electromagnetic Template Library (EMTL)
Loading...
Searching...
No Matches
Unix installation

Building

Dependecies

  • CMake >= 3.13
  • C++14 compatibale compiler wich also suppors OpenMP

Optional:

  • libfftw3
  • MPI
  • Python3 for python modules
  • swig for python modules
  • Doxygen for documentation

Building emtl and ivutils in the same project

Basic build

The easiest way to build emtl is to build it together with ivutils. Put emtl and ivutils in directories on the same level and name the later "ivutils".

With all dependecies installed run the following commands in emtl directory:

mkdir build && cd build
cmake -DDEVELOPMENT=ON
cmake --build .

After the build completes you can run provided examples in the test directory. Option -DDEVELOPMENT=ON tells cmake to absorb ivutils into a emtl project.

Portable installations

If the portable installation is required you should also provide an install prefix -DCMAKE_INSTALL_PREFIX=~/emtl/. The following command will install all needed files into a prefix:

cmake --install .

Configuration options

You can use configuration options to fine-tune the build:

  • -DDEVELOPMENT=ON forces cmake to search for ivutils sources at ../ivutils (and hipercone sources at ../hipercone if hipercone is enabled). Paths are given relative to emtl's main CMakeLists. Default value is OFF.
  • -DSINGLE_PRECISION=OFF sets the default floating type to double instead of float. Default value is ON.
  • -DBUILD_STATIC=ON enables static libraries. Default value is OFF for Linux and ON for Windows.
  • -DBUILD_SHARED=ON enables shared libraries. Default value is ON for Windows and OFF for Linux. At least one of library types should be enabled. On Linux it is possible to build both
  • -DDOCUMENTATION=ON builds documentation. The main page path is doc/emtl/<LANGUAGE>/html/index.html. Available languages are English and Russian, however English documentation has better coverage. Default value is OFF.
  • -DPYTHON=ON builds python modules. Default value is ON.
  • -DMPI_PARALLEL=ON enables mpi support for the library. Default value is OFF
  • -DUSE_HIPERCONE=ON use proprietary module with faster solvers. To indicate the module location use --Dhipercone_ROOT=<PATH_TO_MODULE_DIR> (and disable DEVELOPMENT) or place sources in the directory hipercone on the same level with ivutils.
  • -DFORCE_STATIC=ON fores executables and libraries to be completely static. It requires all dependencies to have static libraries too. The main purpose of this option is to build completely static executables which can be easily launched on different systems. Incompatible with BUILD_SHARED. Default value is OFF.

Additional variables can be found through CMake. Run the following command from emtl directory to print a list of all available variables, including the ones explained above:

cmake -B build -L

Building a package

To facilitate the installation emtl may be build into deb or rpm packages. Building packages requires packaging tools not listed among dependencies. To build the package you can run one of the commands

cpack -G DEB
cpack -G RPM

Building emtl and ivutils separately

You can build emtl and ivutils as separate projects. If doing so make sure that you set the same values for SINGLE_PRECISION and MPI_PARALLEL options. For separate build DEVELOPMENT option in emtl should be set to OFF.

First build and install ivutils:

cd ivutils
mkdir build && cd build
cmake -DCMAKE_INSTALL_PREFIX=~/emtl/
cmake --build .
cmake --install .

Then build emtl:

cd newfdtd
mkdir build && cd build
cmake -DCMAKE_INSTALL_PREFIX=~/emtl/ -Divuitls_ROOT=~/emtl
cmake --build .
cmake --install .

When the projects are installed in the same prefix they also form a relocatable installation. However if the prefixes are different project use absolute paths to address each other thus the installation won't be relocatable anymore. You can force the use of relative paths in case of different prefixes with -DFORCE_RELATIVE_PATHS=ON option for emtl. Keep in mind that in this case cross-references in documentations will be broken in the build directory. They will work correctly after installation.

Testing the build

Testing the executables

To test the build you can run one of the provided codes. They are placed in bin subdirectory on installation. Each code create output in current working directory, hence it is recommended to start it from an empty one:

mkdir test_mie && cd test_mie
<PATH_TO_INSTALL_PREFIX>/bin/test_mie

If everything goes right and the calculation starts you'll see these lines:

...
Estimated calculation time for 3200 steps is 0:00:31
Performing 32 time steps
Performing 32 time steps
...

Testing Python module

To test the python module it's enough to load emtl module:

python -m "emtl"

Python module works as long as this command finishes without an error.

Testing custom experiment build

To test building you need an example code file, like test_dipole.cpp here:

# include "uiextexp.h"

    int main(int argc,char **argv){
      emInit(argc,argv);
      uiPyExperiment task;
      task.SetInternalSpace(Vector_3(-32, -32, -32), Vector_3(32, 32, 32));
      task.SetFirstUpdatedField(1);
      task.SetBC(BC_PER, BC_PER, BC_PER);
      task.SetResolution(1);
      task.AddPointDipole(Vector_3(0,0,0),Vector_3(0,0,1),0,1,true);
      task.SetSignal(new Berenger(1,25,5,125));
      task.BuildDimensions();
      task.AddDetectorSet("fc",Vector_3(),Vector_3(),iVector_3(1));
      task.Calculate(64);
      task.Analyze();
      return 0;
    }

And you also should create corresponding CMakeLists.txt:

cmake_minimum_required(VERSION 3.13 FATAL_ERROR)
project(test_dipole)

find_package(emtl REQUIRED COMPONENTS lib dev)
add_executable(${PROJECT_NAME} ${PROJECT_NAME}.cpp)
target_link_libraries(${PROJECT_NAME} emtl::emtl)

In the directory containing both you can build this test with:

mkdir build && cd build
    cmake -Demtl_ROOT=<PATH TO EMTL INSTALL PREFIX> ../
    cmake --build .

An successful build will produce the test_dipole executable. You can omit the emtl_ROOT if emtl is installed to the standard paths.