Building ParaView 5.8.1 and Shoreline Plug-ins on viz003

You've probably noticed by now that the version of ParaView most used by the group is v5.4.1, which you obtain by "soft adding" into your viz003 environment. While being able to do most of all the post-processing tasks required, this version of ParaView is getting to be relatively old. A previous PhD student, Dr. Corey Wetterer-Nelson, created a novel ParaView plug-in package named Shoreline, which permits insitu modification of a finite element mesh in ParaView, while a PHASTA simulation is on-going. The only caveat is that these plug-ins require Paraview 5.8.1 or newer in order to be built and function properly. The vast majority of the instructions to build Paraview provided on Kitware's "building paraview" wiki page do not apply to our viz003 system due to required user permissions, compiler versions, storage location of several dependencies, etc... thus the need for this wiki page.

This page will walk you through the steps required to successfully build Paraview 5.8.1 and the Shoreline plug-ins, as well as all their dependencies on viz003:

Obtaining and Building Paraview

First, let's obtain a fresh copy of Paraview's git repository:

git clone https://github.com/Kitware/ParaView.git

Place this repository in a location that makes sense to you. For example, I cloned it in the directory ~/GitHub-Builds/Paraview-Builds/test_v5.8.1

Next, while in the top level of your newly cloned Paraview directory, checkout the version 5.8.1 branch:

git checkout v5.8.1

Once v5.8.1 is checked out, we need to update all of it's submodules (while still in the top level directory):

git submodule update --init --recursive

Now that you have cloned and updated the repository for Paraview v5.8.1, you are ready to begin building it. First, make and enter a fresh (does not contain any files or sub directories) build directory in the same folder where you cloned the repository (you will need to cd .. out of the cloned repository):

mkdir build_paraview
cd build_paraview

Now, set your environment so that you can use the software needed to build ParaView:

soft add +cmake-3.16.0
soft add +gcc-8.2.0  
soft add +openmpi-gnu-1.10.6-gnu49-thread

Note: You can also use gcc 9.2.0 or 10.2.0 

The only tricky thing about building ParaView on the viz nodes is that it depends on a newer version of Qt, which cannot be directly soft added to your environment like the other software found when running the command softenv. However, a newer version of Qt (5.11.0) does exist on the viz nodes, you just need to manually point to it. To do so, run these two commands:

export PATH="/usr/local/qt/5.11.0/bin:$PATH"
export LD_LIBRARY_PATH="/usr/local/qt/5.11.0/lib:$LD_LIBRARY_PATH"

Now, you are ready for cmake to do the heavy lifting for you. While in your build directory, point the ccmake command to where the source files for paraview are located. In our case:

CC=gcc CXX=g++ FC=gfortran ccmake ../ParaView/

Once you have the GUI open, hit "c" to configure. It will take a few moments for cmake to configure the files. Eventually, you will get to an interface where you can toggle build options. If you are building a vanilla version of Paraview 5.8.1, none of these build options need to be changed right now.

Else, if you are building 5.8.1 to make use of the Shoreline Plug-ins, you need to ensure that these compiler flags are set to the following before you generate:

CMAKE_BUILD_TYPE = Release
Paraview_Build_Edition = Canonical
Paraview_Build_Shared_Libs = ON
Paraview_Use_Python = ON
Paraview_Use_MPI = ON
Paraview_Use_VTKM = ON
Paraview_Use_Qt = ON

The remainder of the available flags will automatically be set by cmake and can be left as they are.

Continue the configuring process by hitting "c" until the generate option "g" appears (Make sure the compiler flags are set as above if you are building for the Shoreline Plug-ins). Hit "g" to generate. This will finish configuring the make files and exit the cmake GUI. You are now ready to build ParaView!

Building ParaView can take anywhere from 15 minutes to two hours, depending on how many other people are using the viz nodes. You can run top to see how many other processes are currently running. If others in the group are running large jobs, you may want to change to the other viz node, or just wait until later when the resources are more free. In any case, to build Paraview run:

make -jn

where n is the number of processors you want to use (n=8, for example). If you want to build as fast as possible, you can use all the processors by omitting the "n" altogether, but be sure that nobody else is running important jobs if you do.

To run ParaView, you need to enter vglrun and then the full path to the Paraview executable. For example, based on our previous directory structures, my command would look like:

vglrun /users/conrad54418/GitHub-Builds/Paraview-Builds/test_v5.8.1/build_paraview/bin/paraview

You should now be able to use ParaView 5.8.1!

Note: When you build ParaView from scratch on the viz nodes, you may get a weird error about "QXcbShmImage"; as far as we can tell, these errors do not affect the performance, they are just an annoyance. We have reached out to the ParaView dev team and they told us to just put the error window in the bottom left corner and make it as small as possible.. it is what it is!

If you are building Paraview to use the Shoreline Plug-ins, you will need to follow the next steps below to get the Plug-in's up and running. Otherwise, enjoy using a much newer version of Paraview than what can currently be soft added.

Obtaining and Building libIGL

The next step to building the Shoreline Plug-ins is to obtain and build libIGL, a math algorithm library used by Shoreline to create the desired geometry manipulations. To obtain libIG, clone their repository to a location that makes sense to you:

git clone https://github.com/libigl/libigl.git 

Next, just like we did for paraview, create and enter a fresh build directory in the same parent folder where you cloned the repository (you will need to cd .. out of the cloned repository before making this new directory):

mkdir build_libIGL
cd build_libIGL

Next, make sure that you have gcc 8.2.0 or newer soft-added to your environment (It should already be added from when we built Paraview, but double check to make sure):

gcc --version  

Cmake likes to default to the old 4.9 version of gcc even if we have soft-added the newer version, so we need to force it to use the soft-added version by running CC=gcc CXX=g++ FC=gfortran in front of our cmake or ccmake command. Te easiest way to generate the build files for libIGL is to run the following cmake command and not open the cmake GUI:

CC=gcc CXX=g++ FC=gfortran cmake -DLIBIGL_WITH_COMISO=OFF -DLIBIGL_WITH_EMBREE=OFF -DBUILD_SHARED_LIBS=ON -DBUILD_TESTING=OFF -DLIBIGL_WITH_OPENGL=OFF -DLIBIGL_WITH_OPENGL_GLFW=OFF -DLIBIGL_BUILD_TESTS=OFF -DLIBIGL_BUILD_TUTORIALS=OFF ../libigl

where the ../libigl portion needs to be the path from your build folder to the cloned libIGL repo.

Once the above command reaches completion, you can now build libIGL by running make -jn where n is the number of nodes your want to use to build, as explained in the Paraview section above. This should only take a few minutes if you run it on 8 nodes.

libIGL is simply a header library, and there is no GUI or executable for us to run. Shoreline simply links to the library to make use of the algorithms.

Obtaining and Building Eigen

The next step to building the Shoreline Plug-ins is to obtain and build Eigen, a C++ math algorithm library which is used by libIGL. Once Eigen is built, you will need to point the Shoreline cmake files to the Eigen cmake files (more on that later). To obtain Eigen, clone their repository to a location that makes sense to you:

git clone https://gitlab.com/libeigen/eigen.git

Now that you have cloned Eigen, you are ready to begin building it. First, make and enter a fresh build directory in the same folder where you cloned the repository (you will need to cd .. out of the cloned repository):

mkdir build_paraview
cd build_paraview

Now, generate the build files like we have done previously for Paraview:

ccmake ../eigen

Keep hitting 'c' until you have the option to generate. Do not worry about the CUDA_SDK_ROOT_DIR-NOTFOUND messages, we do not want to use CUDA. Once you can generate hit 'g' and wait for it to complete the make file generation process. Next, simply build Eigen by running:

make -j8

Eigen should successfully build within a few minutes.

Obtaining and Building Shoreline Plug-ins

Shoreline is a suite of Paraview Plug-ins to enable in-situ interactive geometry modification of simulation domains. You can see Shoreline's public git repo here: Shoreline.

Before trying to build Shoreline plug-ins, make sure you have successfully completed the previous modules of this wiki page. First, let's obtain a fresh copy of Shoreline's git repository and place it in a location that makes sense to you:

git clone https://github.com/SimNautilus/shoreline.git

scale Direction, scaleNormal, translateFeature

Currently the CmakeList.txt files for each plug-in have some lines of code which point to a generic file path for libIGL include files. In order for the plug-ins to compile, we need to modify these paths to point the compiler to the libIGL files which we have just built.

We will use the scaleDirection plug-in as an example, but know that scaleNormal, and translateFeature will require the same modification. To make the modification, enter the shoreline directory you just cloned and change directory to:

cd /ParaViewPlugins/scaleDirection/Plugin/Filters

Next, open the CMakeLists.txt file to make the modification:

vi CMakeLists.txt 

We need to modify the path in the following line of code:

vtk_module_include(scaleDirectionFilters PRIVATE "/Users/corey/Git/libigl/include/")

to the path where our version of the include directory of libIGL lives. For example, mine looks like this:

vtk_module_include(scaleDirectionFilters PRIVATE "/users/conrad54418/GitHub-Builds/libigl-Builds/libigl/include")

Save the file and exit, :wq

Now go back to the .../shoreline/ParaViewPlugins/scaleDirection/ directory and create and enter a fresh build directory:

mkdir build
cd build

now run the following command:

CC=gcc CXX=g++ FC=gfortran ccmake ..

Hit 'c' to configure. Once it finishes this first configure iteration, the Paraview_DIR field will either not be pointing to anything, or be pointed to the wrong version of ParaView. We need to change this Paraview_DIR to the path where we built ParavView 5.8.1. For example, mine looks like:

/users/conrad54418/GitHub-Builds/Paraview-Builds/v5.8.1/build_paraview/

Once you have changed the path, hit 'c' again. This time, you will need to enter the path to the libIGL build folder in the LIBIGL_DIR field. Mine looks like:

/users/conrad54418/GitHub-Builds/libigl-Builds/build_libigl/

Hit 'c' a few more times until you have the option to hit 'g' to generate the build files. Once it's done generating run make. It should only take about 2 minutes to build.

You can repeat this process for both the scaleNormal and translateFeature plug-ins.

Using Shoreline Plug-ins

To use the Shoreline plug-ins, we need to activate them within ParaView.

First, vglrun the Paraview executable for the v5.8.1 w/ Shoreline build. Once ParaView 5.8.1 is run, you can open the following model file to test the plug-ins and make sure they are working properly:

/users/jeffhadley/serverSentMesh.vtp

To learn how to load the plug-in's and view a brief example of how to use scaleDirection, you can watch this video. scaleDirection is explained a bit more in depth in the next video.

Note: to load the plug-ins you will need to find the location of the .so files inside of each plug-in's build directory. The paths from the build directories are the same for scaleNormal, scaleDirection, and translateFeature, however the paths for the other plug-ins will different slightly in sub-directory nomenclature, so you can grep -rni '.so' * from the top level of the plugin to see where the .so file is located. REMINDER: if there are 2 .so files, take the .so that does not contain 'lib' in it's name.

To learn how to use scaleNormal and scaleDirection you can watch this video.

To learn how to use translateFeature you can watch this video.