Installation

Installing this package is not a trivial task due to its heavy dependencies. ParPyDTK2 has the following installation requirements:

  1. C++11 compiler
  2. MPI
  3. MOAB
  4. DTK2 and Trilinos
  5. Python >= 3.5
  6. mpi4py
  7. NumPy
  8. setuptools

And both MOAB and DTK2 have their own dependencies.

In addition, to build the documentation, the following packages are needed:

  1. Sphinx
  2. Doxygen
  3. breathe
  4. numpydoc

The good news is you can install these easily through pip.

Install MOAB

The MOAB official README has a very clear description of the installation process. Here we take an excerpt of our MOAB Docker image building script:

$ git clone --depth=1 https://bitbucket.org/fathomteam/moab.git
$ cd moab
$ autoreconf -fi
$ ./configure \
    --prefix=/usr/local \
    --with-mpi \
    CC=mpicc \
    CXX=mpicxx \
    FC=mpif90 \
    F77=mpif77 \
    --enable-optimize \
    --enable-shared=yes \
    --with-blas=-lopenblas \
    --with-lapack=-lopenblas \
    --with-scotch=/usr/lib \
    --with-metis=/usr/lib/x86_64-linux-gnu \
    --with-eigen3=/usr/include/eigen3 \
    --with-x \
    --with-cgns \
    --with-netcdf \
    --with-hdf5=/usr/lib/hdf5-openmpi \
    --with-hdf5-ldflags="-L/usr/lib/hdf5-openmpi/lib" \
    --enable-ahf=yes \
    --enable-tools=yes
$ make && sudo make install

Notice that this is for system installation. Install to your preferred locations if you don’t have the root access. Also, turn off those optional packages if you don’t have them, only MPI and HDF5 are necessary.

Warning

You must build it into a shared object!

Note

If you use Ubuntu >= 17.10, all those optional packages are likely to be available through apt.

Install DTK2

DTK2 is shipped as a sub-module of Trilinos, so building Trilinos is needed. For people who are not familiar with Trilinos, this can be tricky. Therefore, an excerpt of our DTK2 Docker image building script might be helpful:

$ export TRILINOS_VERSION=12-12-1
$ git clone --depth 1 --branch trilinos-release-${TRILINOS_VERSION}
$ cd Trilinos
$ git clone --depth 1 --branch dtk-2.0 \
    https://github.com/unifem/DataTransferKit.git
$ mkdir build && cd build
$ cmake \
    -DCMAKE_INSTALL_PREFIX:PATH=/usr/local \
    -DCMAKE_BUILD_TYPE:STRING=RELEASE \
    -DCMAKE_VERBOSE_MAKEFILE:BOOL=OFF \
    -DCMAKE_SHARED_LIBS:BOOL=ON \
    -DTPL_ENABLE_MPI:BOOL=ON \
    -DTPL_ENABLE_Boost:BOOL=ON \
    -DBoost_INCLUDE_DIRS:PATH=/usr/include/boost \
    -DTPL_ENABLE_Libmesh:BOOL=OFF \
    -DTPL_ENABLE_MOAB:BOOL=ON \
    -DMOAB_INCLUDE_DIRS=$MOAB_ROOT/include \
    -DMOAB_LIBRARY_DIRS=$MOAB_ROOT/lib \
    -DTPL_ENABLE_Netcdf:BOOL=ON \
    -DTPL_ENABLE_BinUtils:BOOL=OFF \
    -DTrilinos_ENABLE_ALL_OPTIONAL_PACKAGES:BOOL=OFF \
    -DTrilinos_ENABLE_ALL_PACKAGES=OFF \
    -DTrilinos_EXTRA_REPOSITORIES="DataTransferKit" \
    -DTrilinos_ENABLE_EXPLICIT_INSTANTIATION:BOOL=ON \
    -DTrilinos_ASSERT_MISSING_PACKAGES:BOOL=OFF \
    -DTrilinos_ENABLE_TESTS:BOOL=OFF \
    -DTrilinos_ENABLE_EXAMPLES:BOOL=OFF \
    -DTrilinos_ENABLE_CXX11:BOOL=ON \
    -DTrilinos_ENABLE_Tpetra:BOOL=ON \
    -DTpetra_INST_INT_UNSIGNED_LONG:BOOL=ON \
    -DTPL_ENABLE_BLAS:BOOL=ON \
    -DTPL_BLAS_LIBRARIES=/usr/lib/x86_64-linux-gnu/libopenblas.so \
    -DTPL_ENABLE_LAPACK:BOOL=ON \
    -DTPL_LAPACK_LIBRARIES=/usr/lib/x86_64-linux-gnu/libopenblas.so \
    -DTPL_ENABLE_Eigen:BOOL=ON \
    -DTPL_Eigen_INCLUDE_DIRS=/usr/include/eigen3 \
    -DTrilinos_ENABLE_DataTransferKit=ON \
    -DDataTransferKit_ENABLE_DBC=ON \
    -DDataTransferKit_ENABLE_TESTS=ON \
    -DDataTransferKit_ENABLE_EXAMPLES=OFF \
    -DDataTransferKit_ENABLE_ClangFormat=OFF \
    -DTPL_ENABLE_BoostLib:BOOL=OFF \
    -DBUILD_SHARED_LIBS:BOOL=ON
$ make && sudo make install

Again, this assumes root access, adjust this based on your situation. DTK2 needs to stay in the root directory of Trilinos and be turned on through switches DTrilinos_EXTRA_REPOSITORIES and DTrilinos_ENABLE_DataTransferKit. The environment var MOAB_ROOT is the place where you install MOAB.

Note

We recommend that install DTK2 from my personal forked repo since we may add/modify the source codes to make DTK2 more advanced.

Install ParPyDTK2

Once you have the dependencies setup, installing ParPyDTK2 can be very easy. The easiest way is through PyPI:

$ sudo pip3 install parpydtk2

However, this assumes that ParPyDTK2 can find MOAB and DTK2 on the system. With different specifications of install command, ParPyDTK2 can automatically add different paths to search for MOAB and DTK2.

$ pip3 install parpydtk2 --user

will assume MOAB and DTK2 can be found in USER_BASE/{include,lib}.

$ pip3 install parpydtk2 --prefix=...

will allow ParPyDTK2 to search MOAB and DTK2 under the prefix directory.

The preferred way is to define the environment variables PARPYDTK2_MOAB_ROOT and PARPYDTK2_DTK_ROOT before you do pip install. For instance,

$ export PARPYDTK2_MOAB_ROOT=/path/to/moab/root
$ export PARPYDTK2_DTK_ROOT=/path/to/dtk/root
$ pip3 install parpydtk2 --user

Warning

We don’t mark mpi4py as installation dependency, so you need to install it manually before you install ParPyDTK2. pip3 install mpi4py is just fine.

Of course, you can install from source, which can be obtained here. Just make sure you have all Python dependencies installed.

$ git clone -b parallel https://github.com/chiao45/parpydtk2.git
$ cd parpydtk2
$ python3 setup.py install --user

Using our Docker container

You can try the package through our pre-built Docker container. Two driver scripts are provided in order to easily use the container:

  1. parpydtk2_desktop.py
  2. parpydtk2_jupyter.py

The former will launch a desktop environment through VNC, while the latter will run the container as a Jupyter server.