View source for 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:
 <code>git clone https://github.com/Kitware/ParaView.git</code>

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

Next, while in the top level of your newly cloned Paraview directory, checkout the version 5.8.1 branch:
 <code>git checkout v5.8.1</code>

Once v5.8.1 is checked out, we need to update all of it's submodules (while still in the top level directory): 
 <code>git submodule update --init --recursive</code>

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 <code>cd ..</code> 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 <code>softenv</code>. 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 <code>ccmake</code> 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 <code>top</code> 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 <code>vglrun</code> 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 <code>CC=gcc CXX=g++ FC=gfortran</code> 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 <code>../libigl</code> 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 <code>make -jn</code> 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 <code>cd ..</code> 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 <code>CUDA_SDK_ROOT_DIR-NOTFOUND</code> 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 CGAL ==

Some of the Shoreline plug-ins will require CGAL, which is a Headers-Only math library. You can access the CGAL github page [https://github.com/CGAL/cgal here] to learn more. 

Since it is a headers only library, there will be no <code>make</code> build step. You just need to clone the repo:

 git clone https://github.com/CGAL/cgal

Then, create a <code>build</code> directory somewhere that makes sense for you and enter into it. 

 mkdir build
 cd build

Next, run the following command, replacing the <code>../path/to/source</code> portion to the path from your build folder to the directory where you cloned the CGAL repo: 

  CC=gcc CXX=g++ FC=gfortran ccmake ../path/to/source

Hit 'c' and follow the instructions once it's done configuring. You will probably need to set the CMAKE_BUILD_TYPE to 'Release'. Once you have done this and have the option to generate, hit 'g'. This will create all of the files required, and CGAL has been "built".

== Obtaining and Building Boost ==

Some of the Shoreline plug-ins will require Boost, a compilation of C++ libraries. You can access the Boost webpage [https://www.boost.org/here] to learn more. To obtain boost, we need to download a <code>.tar</code> file from their website. You can access the download links [https://www.boost.org/users/history/version_1_76_0.html here]. We obtained the <code>.tar.bz2</code> version for our builds.

Once the <code>.tar</code> file is downloaded, you will need to extract the actual Boost folder and place it somewhere that makes sense for you to access it in order to build Boost. The name of the Boost source directory should be similar to this naming convention: 

 boost_1_76_0

Next, create a build directory for Boost somewhere that makes sense for you. Once it's built, 'cd' into the build folder and obtain and copy the full path to this directory, we will refer to this as ".../full/path/to/build/directory". Now, 'cd' into the source <code>boost_1_76_0</code> directory and run the <code>boostrap.sh</code> shell script:

 ./boostrap.sh --prefix='.../full/path/to/build/directory'

This will create an executable called <code>b2</code>. You will need to run this executable and give it the option of where your build directory is located: 

 ./b2 install --prefix='.../full/path/to/build/directory'

Once this command completes the Boost libraries will be built in your Boost build folder.

== Obtaining and Building Shoreline ParaView 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: [https://github.com/SimNautilus/shoreline 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

There are currently two branches of Shoreline, the main branch, and the viz003 branch. The viz003 branch contains modifications to the original code to permit an easier installation on viz003. it is highly recommended that you checkout the viz003 branch if you are building on viz003.

 git checkout viz003

=== scaleDirection, 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 in previous steps. 

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 <code>CMakeLists.txt</code> 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/jeffhadley/Builds/src/libigl/include/")
to the path where our version of the include directory of the libIGL source directory 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, <code>:wq</code> 

Now go back to the <code>.../shoreline/ParaViewPlugins/scaleDirection/</code> 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 <code>Paraview_DIR</code> field will either not be pointing to anything, or will be pointed to the incorrect version of ParaView. We need to change this <code>Paraview_DIR</code> 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 <code>make</code>. It should only take about 2 minutes to build. 

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

=== createHarmonicSkeleton, interactiveSkeleton ===

Before trying to build createHarmonicSkeleton and interactiveSkeleton it is very important that you have successfully completed all of the previous modules in this wiki; these plug-ins have dependencies on all of the different software packages we had to obtain and build. It is also very important that you have the viz003 branch of Shoreline checked out, as this branch is modified to work with viz003 by only needing to change the paths for external dependencies. 

interactiveSkeleton requires that a skeleton be created on our work piece in order to be used, so lets build the createHarmonicSkeleton plug-in first. 

Just as the other plug-ins we've built previously, the paths to certain dependencies will need to be changed to match the paths on your version of the build. The easiest way to find all the path's that require to be modified is by running the following in the top level directory for the plug-in:

 grep -rni 'jeff' *

Make note of all of the instances that grep returns: the file name, line number, and path to the file. Systematically work through all of the lines of code which need to be modified and change them to your equivalent paths. Note that there are many more paths that require to be modified in these plug-ins compared to the ones we've previously built.

The next step is to create a cache folder where the temporary deformation files will be written to and read in by the skeleton plug-ins. Change directory to the top level of the Shoreline directory, and create the cache folder and cd into it, then print the working directory and copy it to the clipboard (we will need this full path in a bit):

 mkdir cache
 cd cache
 pwd

Now change directory to the top level of the createHarmonicSkeleton plugin, and create and enter a new build directory:

 mkdir build
 cd build

Run the following command to launch the Cmake GUI and force it to use the soft-added environment:

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

Hit 'c' to do the initial configure. Once it's done there will be an empty field called CACHE_PATH_OPTION, you will paste the full cache directory path we copied previously into this field. For example, mine looks like: 

 /users/jeffhadley/Builds/src/shoreline/cache

The compiler will also ask you to provide the paths to the paraview make files, libIGL make files, etc (Same idea as the previous plug-ins). You will also need to toggle to advance mode and provide <code>Boost_DIR</code>, the full path to the <code>Boost-config.cmake</code> file, which should be located in the following generic path from the boost build folder: <code>path/to/build-Boost/lib/cmake/Boost-1.76.0</code>. You will also need to provide the <code>Boost_INCLUDE_DIR</code>, which should follow roughly: <code>path/to/build-Boost/include</code>. Provide the paths as necessary and continue hitting 'c' until you have the option to generate, then hit 'g'. you can now build by running:

 make -j8  

This build should take about 5 minutes at most.

Once it's done, you can repeat all of these steps but with 'interactiveSkeleton' instead of 'createHarmonicSkeleton' to build the interactiveSkeleton plugin.

== Loading and Using Shoreline Plug-ins ==

=== Loading Plug-ins ===

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

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

 /users/jeffhadley/serverSentMesh.vtp

Next, we need to load the plug-ins into ParaView. To learn how to load the plug-in's and view a brief example of how to use '''scaleDirection''', you can watch this [https://fluid.colorado.edu/tutorials/tutorialVideos/ParaviewShorelinePlugins_part1.mp4 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 <code>.so</code> files inside of each plug-in's build directory. The paths from the top level build directories are the same for scaleNormal, scaleDirection, and translateFeature, however the paths for the other plug-ins will differ slightly in sub-directory nomenclatures, so you can <code>grep -rni '.so' *</code> from the top level of each plugin's build directory to see the full path to where the <code>.so</code> file is located. '''REMINDER:''' if there are 2 <code>.so</code> files, take the <code>.so</code> that does not contain 'lib' in it's name.

=== Using Shoreline Plug-ins ===

To learn how to use '''scaleNormal''' and '''scaleDirection''' you can watch this [https://fluid.colorado.edu/tutorials/tutorialVideos/scaleNormal_scaleDirection.mp4 video].

To learn how to use '''translateFeature''' you can watch this [https://fluid.colorado.edu/tutorials/tutorialVideos/translateFeature_mp3audio.mp4 video].

To learn how to use the '''createHarmonicSkeleton''' and the '''interactiveSkeleton''' filters you can watch this [https://fluid.colorado.edu/tutorials/tutorialVideos/skeletonManipulation.mp4 video].

== Building Shoreline Client-Server Manager ==

 *** SECTION UNDER CONSTRUCTION ***

Assuming you have already cloned the Shoreline repository in the Obtaining Shoreline step, you can also build the Client-Server Manager, an Application Programming Interface (API)  which permits in-situ flow visualization after deforming the working model using Shoreline plug-ins.

The first step in building the ClientServerManager is to ensure your environment is properly set-up. You can find the required soft adds in the <code>softSetup.sh</code> file. Make sure to soft add these versions of the external dependencies. You must also run the two export commands for PETSC as cmake is not capable of finding the listed directories when you pass them in using <code>-DPETSC_DIR= ....</code>. 

pass in SCOREC-core
pass in Paraview 5.8.1
git checkout SSE-catalyst-5.8.1 in phasta-next directory
pass in source directory of Phasta-next


Shoreline Client Server Manager tutorial video: [https://fluid.colorado.edu/tutorials/tutorialVideos/ShorelineClientServerTutorial.mp4 Watch me!]