2. Advanced Usage¶

build_visit comes with many options for features such as building a parallel version, overcoming issues with OpenGL, a rendering library used by VisIt to render images, and controlling precisely what libraries VisIt is built with.

2.1. Building a parallel version¶

One of powerful capabilities of VisIt is running in parallel on large parallel clusters. VisIt runs in parallel using a library called MPI, which stands for Message Passing Interface. There are a couple of ways in which you can build a parallel version of VisIt using MPI. If your system doesn’t already have MPI installed on it, which is typically the case with a desktop system or small cluster, then you can use MPICH, which is an open source implementation of MPI. The following example builds a parallel version using MPICH.

./build_visit3_0_1 --mpich

If your system already has MPI installed on it, which is typically the case with a large system at a computer center, you can set several environment variables that specify the location of the MPI libraries and header files. The following example uses a system installed MPI library.

 env PAR_COMPILER=/usr/packages/mvapich2/bin/mpicc \
     PAR_COMPILER_CXX=/usr/packages/mvapich2/bin/mpicxx \
     PAR_INCLUDE=-I/usr/packages/mvapich2/include \
     PAR_LIBS=-lmpl \
./build_visit3_0_1 --parallel

When running in parallel, the user will typically use scalable rendering for rendering images in parallel. VisIt does this through the use of the Mesa 3D graphics library. Because of this you will want to include Mesa 3D when building a parallel version. In the following example we have included building with the Mesa 3D library.

./build_visit3_0_1 --mpich --osmesa

2.2. Building with Mesa as the OpenGL implementation¶

Mesa 3D is also an implementation of OpenGL and it can be used in place of the system OpenGL when building VisIt. There are a couple of reasons you would want to use Mesa 3D instead of the system OpenGL. The first is when you don’t have a system OpenGL, which typically occurs when building in a container or on a virtual machine. The second is when your system implementation of OpenGL is too old to support VTK. In the following example we use Mesa 3D instead of the system OpenGL.

./build_visit3_0_1 --mesagl

2.3. The difference between `--mesagl` and `--osmesa`¶

When you specify --mesagl VTK will be built against Mesa 3D. When you specify --osmesa VTK is built against the system OpenGL and the Mesa 3D library is substituted at run time for OpenGL when running the parallel engine to enable scalable rendering. If you specify --mesagl then --osmesa is unnecessary and ignored if specified.

2.4. Building Server only¶

Sometimes a special version of VisIt is needed for a remote server, one that only processes data and does not include any GUI elements. VisIt can be built in this fashion (and the build will be sped up considerably) by adding the -server-comonents-only flag to build only the server and related programs. Then you can run client/server from a desktop system running the GUI locally, and connect to the remote server to process data.

env PAR_COMPILER=mpicc ./build_visit3_3_3 --server-components-only --mesa --icet

This will do a basic build, but will probably not include the IO libraries you need (unless you only need VTK). You can specify any needed libraries individually, e.g. --hdf5 --netcdf --conduit --mfem to add HDF5, NetCDF, Conduit and Mfem IO libraries.

2.5. Building VisIt with Pre-Installed (e.g. System) Libraries¶

On many systems, some libraries VisIt needs (e.g. Qt, VTK, Python OpenGL, HDF5, etc.) come pre-installed. Can a user just use those pre-installed libraries to build VisIt?

Please don’t! In all likelihood this will not work at all or, worse, it will only partially work and fail in subtle ways that are nearly impossible to diagnose. In the unlikely chance it appears to work upon reporting any issues our first question will be, how was VisIt configured/built? If VisIt is built in a way that is not consistent with how developers routinely build, run and test it, we will not be able to reproduce the issue, debug it, identify work-arounds or otherwise provide sufficient support.

Apart from the general issues of reproducibility and support, there are many reasons building VisIt with pre-installed libraries will likely not work. Below, we breifly summarize various compatability issues with trying to use pre-installed libraries.

Version CompatabilityPre-installed libraries are not the version VisIt requires: Often, users notice a newer version of a library VisIt needs is pre-installed on their system and expect VisIt will run better with this newer version. However, having a newer version of VTK, for example, pre-installed does not mean VisIt will build or run properly with that version. Major versions of VTK, for example, (e.g. 8.0 and 9.0) are not compatable. Incompatabilities sometimes exist even between minor versions of some libraries. Incorrect library versions may cause VisIt to either fail to build or fail to run properly.
Patch CompatabilityPre-installed libaries are missing patches VisIt requires: In some cases, the libraries VisIt needs are patched to work around various issues building or running VisIt. Such patches are almost certainly not in any pre-installed version of the library. Missing patches may cause VisIt to either fail to build or fail to run properly.
Configuration CompatabilityPre-installed libraries are not configured in a way VisIt requires: Libraries often have many build options which enable or disable certain features. The Qt library, for example, has hundreds of build options. Some build options VisIt may not care about. Other build options, however, VisIt may require to be enabled and still other options to be disabled. Incorrect library configuration may cause VisIt to either fail to build or fail to run properly.
Dependency CompatabilityPre-installed libraries are not built with dependencies VisIt requires: Libraries often have dependencies on still other libraries. For example, Qt and VTK can both depend on OpenGL. In some cases, however, VisIt may require a specific implementation of OpenGL called MesaGL. Incorrect dependencies may cause VisIt to either fail to build or fail to run properly. Such dependencies complicate things significantly because it means all of the aforementioned compatability issues apply, recursively, to any libraries a pre-installed library depends on.
Compiler (Run-Time) CompatabilityPre-installed libraries are not built with a compiler (run-time) VisIt requires: For some situations, building VisIt and its dependencies requires a specific compiler. The compiler (run-time) used for pre-installed libraries may not be compatable with the compiler (run-time) VisIt requires.

There are likely other subtle compatability issues that can arise which we have neglected to mention here. A fully featured build of VisIt can involve 35+ libraries, many of which may come pre-installed (Qt, VTK, Python, HDF5, netCDF, OpenGL, MPI to name a few) on any particular platform. Bottom line, the number of ways pre-installed libraries can be built such that they will cause VisIt to either fail to build or fail to run properly are almost boundless. For this reason, we discourage users from attempting to build VisIt using pre-installed libraries and warn users that in all likelihood we will not have sufficient resources to help address any resulting issues that may arise.

2.6. Building on a system without internet access¶

When you want to build visit on a system without internet access, you can use build_visit to download the third party libraries and source code to a system that has internet access and then move those files to your machine without access. The following example downloads the optional libraries, mpich and osmesa.

./build_visit3_0_1 --optional --mpich --osmesa --download-only

Unfortunately, due to the way the code that builds Python is implemented, some Python libraries will not be downloaded. Here is the list of commands to download those additional libraries.

wget http://portal.nersc.gov/project/visit/releases/3.0.1/third_party/Imaging-1.1.7.tar.gz
wget http://portal.nersc.gov/project/visit/releases/3.0.1/third_party/setuptools-28.0.0.tar.gz
wget http://portal.nersc.gov/project/visit/releases/3.0.1/third_party/Cython-0.25.2.tar.gz
wget http://portal.nersc.gov/project/visit/releases/3.0.1/third_party/numpy-1.14.1.zip
wget http://portal.nersc.gov/project/visit/releases/3.0.1/third_party/pyparsing-1.5.2.tar.gz
wget http://portal.nersc.gov/project/visit/releases/3.0.1/third_party/requests-2.5.1.tar.gz

It’s possible that the list could change and the above list becomes outdated. In this case you can run build_visit to just build Python and that will end up downloading all the files you need. The following command builds only Python.

./build_visit3_0_1 --no-thirdparty --no-visit --python

2.7. Different versions of `build_visit`¶

When you use a version of build_visit that has a version number in it, for example build_visit3_0_1 then it builds that tagged version of VisIt. If the version of build_visit was from the develop branch of VisIt, then it will grab the latest version of VisIt from the devlop branch. If the version of build_visit came from a release candidate branch, for example the v3.0 branch, then it will grab the latest version of VisIt from that branch.

2.8. Troubleshooting `build_visit` failures¶

When build_visit runs, it generates a log file with _log added to the name of the script. For example, if you are running build_visit3_0_1 then the log file will be named build_visit3_0_1_log. The error that caused the failure should be near the end of the log file. When build_visit finishes running, it will leave the directories that it used to build the packages intact. You can go into the directory of the package that failed and correct the issue and finish building and installing the package. You can then execute the build_visit command again to have it continue the build.

2.9. Why can’t I use the Qt, Python, VTK, Mesa/GL, etc. that came on my system?¶

As much as we might like to believe it, large, complex libraries like Qt, Python and VTK are rarely 100% compatible between newer or older versions. Furthermore, for large libraries like these, there are often many, many different installation options for a given platform. It is highly unlikely that a given installation of VTK for example, is not only of a version compatibile with a given release of VisIt but also configured and installed on your system in exactly the way VisIt needs it. In addition, VisIt gets developed and thoroughly tested on specific versions and configurations of various libraries meaning that when users encounter issues in other configurations, we are not always able to reproduce them. In some cases, VisIt developers have had to work-around a bug in a library or, worse, had to patch the actual library itself to address an issue that might be specific to just one platform. Together, these issues result in a situation where VisIt often must be compiled with precisely the libraries it is released on and rarely, if ever, can take advantage of an installation that came as part of the system VisIt is being built on. Lastly, it becomes almost impossible to duplicate and diagnose issues reported by users when users are running VisIt in configurations substantially different from that which is being developed and routinely tested.