SEACAS [Documentation] [Wiki]
- Get the sources
- Build instructions
- Configure, Build, and Install SEACAS
- Parallel Build
- Testing
- Exodus
- Trilinos
- SPACK
- Docker
- CMake Example Usage
- Requred Software: Mac
- License
- Contact information
- NOTE: The old imake-based build has been removed.
git clone https://github.com/sandialabs/seacas.gitThis will create a directory that will be referred to as seacas in the instructions that follow. You can rename this directory to any other name you desire. Set an environment variable pointing to this location by doing:
cd seacas && export ACCESS=`pwd`There are a few externally developed third-party libraries (TPL) that
are required (or optional) to build SEACAS: HDF5, NetCDF, CGNS, MatIO,
Kokkos, and (if MPI set) PnetCDF libraries. You can build the
libraries using the install-tpl.sh script, or you can install them
manually as detailed in
TPL-Manual-Install.md.
- The script requires bash and wget, which you may need to install.
- To use the script, simply type
bash ./install-tpl.sh. - The default behavior can be modified via a few environment variables:
| Variable | Values | Default | Description |
|---|---|---|---|
| INSTALL_PATH | path to install | pwd | Root of install path; default is current location |
| COMPILER | clang, gnu, intel, ibm nvidia | gnu | What compiler should be used for non-parallel build. Must have C++-17 capability. |
| MPI | YES, NO | NO | If YES, then build parallel capability |
| FORCE | YES, NO | NO | Force downloading and building even if lib is already installed. |
| BUILD | YES, NO | YES | Should TPLs be built and installed. |
| DOWNLOAD | YES, NO | YES | Should TPLs be downloaded. |
| USE_PROXY | YES, NO | NO | Sandia specific -- use proxy when downloading tar files |
| DEBUG | YES, NO | NO | Build debug executable; default is optimized |
| SHARED | YES, NO | YES | Build shared libraries if YES, archive (.a) if NO |
| CRAY | YES, NO | YES | Is this a Cray system (special parallel options) |
| NEEDS_ZLIB | YES, NO | NO | If system does not have zlib installed, download and install it (HDF5 compression). |
| USE_ZLIB_NG | YES, NO | NO | Should the improved zlib-ng library be used to provide ZLIB capability |
| NEEDS_SZIP | YES, NO | NO | If system does not have szip installed, download and install it (HDF5 compression). |
| USE_64BIT_INT | YES, NO | NO | In CGNS, enable 64-bit integers |
| CGNS | YES, NO | YES | Should CGNS TPL be built. |
| MATIO | YES, NO | YES | Should matio TPL be built. |
| METIS | YES, NO | NO | Should metis TPL be built (parallel decomposition). |
| PARMETIS | YES, NO | NO | Should parmetis TPL be built (parallel decomposition). |
| ADIOS2 | YES, NO | NO | Should adios2 TPL be built. |
| CATALYST2 | YES, NO | NO | Should catalyst 2 TPL be built. |
| KOKKOS | YES, NO | NO | Should Kokkos TPL be built. |
| GNU_PARALLEL | YES, NO | YES | Should GNU parallel script be built. |
| FMT | YES, NO | YES | Should Lib::FMT TPL be built. |
| CATCH2 | YES, NO | YES | Should Catch2 be built (used for testing). |
| H5VERSION | V114, V110 | V114 | Use HDF5-1.14.X or HDF5-1.10.X |
| H5CPP | YES, NO | NO | Should the HDF5 C++ library be built/installed |
| BB | YES, NO | NO | Enable Burst Buffer support in PnetCDF |
| JOBS | {count} | 2 | Number of "jobs" used for simultaneous compiles |
| SUDO | "" or sudo | "" | If need to be superuser to install |
- NOTE: The
DOWNLOADandBUILDoptions can be used to download all TPL source; move to a system with no outside internet access and then build/install the TPLs. - The arguments can either be set in the environment as:
export COMPILER=gnu, or passed on the script invocation line:COMPILER=gnu ./install-tpl.sh
At this time, you should have all external TPL libraries built and
installed into ${ACCESS}/lib and ${ACCESS}/include. You are now ready
to configure the SEACAS CMake build.
cd $ACCESSmkdir buildcd build- edit the
${ACCESS}/cmake-configfile and adjust compilers and other settings as needed. - enter the command
../cmake-configand cmake should configure everything for the build. make && make install- If everything works, your applications should be in
${ACCESS}/bin - To install in a different location, do
INSTALL_PATH={path_to_install} ../cmake-config - The default behavior can be modified via a few environment variables:
| Variable | Values | Default | Description |
|---|---|---|---|
| INSTALL_PATH | path to install | pwd | Root of install path; default is current location |
| BUILDDIR | {dir} | pwd/build |
Directory to do config and build |
| COMPILER | clang, gnu, intel, ibm | gnu | What compiler should be used for non-parallel build |
| SHARED | YES, NO | YES | Build and use shared libraries is YES |
| APPLICATIONS | YES, NO | YES | Should all SEACAS applications be built (see cmake-config) |
| LEGACY | YES, NO | YES | Should the legacy SEACAS applications be built (see cmake-config) |
| FORTRAN | YES, NO | YES | Should fortran libraries and applications be built (see cmake-config) |
| ZOLTAN | YES, NO | YES | Should zoltan library and nem_slice be built |
| BUILD_TYPE | debug, release | release | what type of build |
| MODERN | YES, NO | NO | Use "modern" CMake configuration files for netCDF and HDF5 |
| DEBUG | -none- | If specified, then do a debug build. Can't be used with BUILD_TYPE |
|
| HAVE_X11 | YES, NO | YES | Does the system have X11 libraries and include files; used for blot, fastq |
| THREADSAFE | YES, NO | NO | Compile a thread-safe IOSS and Exodus library |
| USE_SRUN | YES, NO | NO | If MPI enabled, then use srun instead of mpiexec to run parallel tests |
| DOXYGEN | YES, NO | NO | Run doxygen on several packages during build to generate documentation |
| OMIT_DEPRECATED | YES, NO | NO | Should the deprecated code be omitted; NO will enable deprecated code |
| EXTRA_WARNINGS | YES, NO | NO | Build with extra warnings enabled; see list in cmake-config |
| SANITIZER | many | NO | If not NO, build using specified sanitizer; see list in cmake-config |
| GENERATOR | many | "Unix Makefiles" | what generator should CMake use; see cmake doc |
- The arguments can either be set in the environment as:
export COMPILER=gnu, or passed on the script invocation line:COMPILER=gnu ./install-tpl.sh
For some areas of use, a parallel version of SEACAS is required. This will build a "parallel-aware" version of the exodus library and a parallel version of the Ioss library.
The only modification to the serial build described above is to make
sure that the mpicc parallel C compiler is in your path and to add the
MPI=YES argument to the install-tpl.sh script invocation when
building the TPLs. For example:
MPI=YES ./install-tpl.shThis will download all requested libraries and build them with parallel capability enabled (if applicable). You can then continue with the steps outlined in the previous section.
There are a few unit tests for zoltan, exodus, ioss, and aprepro that can be run via make test or ctest if you configured with -D Seacas_ENABLE_TESTS=YES.
There is also a system-level test that just verifies that the applications can read and write exodus files correctly. This test runs off of the installed applications. To run do:
make installcd ../SEACAS-Testmake clean; make
This will run through several of the SEACAS applications creating a mesh (exodus file) and then performing various manipulations on the mesh. If the test runs successfully, there is some hope that everything has built and is running correctly.
If you only want the exodus library, then follow most of the above instructions with the following exceptions:
- Clone entire source tree as above. (There used to be a zip file, but difficult to keep up-to-date)
- You only need the netcdf and optionally hdf5 libraries
- Use the
cmake-exodusfile instead ofcmake-config. - This will build, by default, a shared exodus library and also install the exodus.py and exomerge.py Python interfaces.
Although SEACAS is included in Trilinos
(https://github.com/trilinos/Trilinos), it is also possible to use the
SEACAS code from this repository to override the possibly older SEACAS
code in Trilinos. The steps are to directly pull SEACAS from github
under Trilinos and then build SEACAS under Trilinos with that version
using SEACAS_SOURCE_DIR_OVERRIDE. Here is how you do it:
cd Trilinos/
git clone https://github.com/sandialabs/seacas.git
cd BUILD/
cmake -DSEACAS_SOURCE_DIR_OVERRIDE:STRING=seacas/packages/seacas -DTrilinos_ENABLE_SEACAS [other options] ..The SPACK package manager (https://spack.io/) can be used to install SEACAS and all dependent third-party libraries. SEACAS is a supported package in SPACK as of December 2018.
git clone https://github.com/spack/spack.git
. spack/share/spack/setup-env.sh
spack install seacas~mpi # Serial build (most common)An Ubuntu-based Docker image, with SEACAS built and installed, is available on Docker Hub.
docker pull mrbuche/seacasSEACAS is located in /seacas when running the container. There is also a similar image available on Docker Hub with only Exodus built and installed.
docker pull mrbuche/exodusA simple example of using the SEACAS Exodus library in your external project. Here is the CMakeLists.txt file:
project(ExodusCMakeExample VERSION 1.0 LANGUAGES C Fortran)
cmake_minimum_required(VERSION 3.1...3.26)
#### C ####
find_package(SEACASExodus CONFIG)
add_executable(ExodusWriteC ExodusWrite.c)
target_link_libraries(ExodusWriteC PRIVATE SEACASExodus::all_libs)
#### FORTRAN #####
IF ("${CMAKE_Fortran_COMPILER_ID}" MATCHES "GNU")
SET(CMAKE_Fortran_FLAGS "${CMAKE_Fortran_FLAGS} -fcray-pointer -fdefault-real-8 -fdefault-integer-8 -fno-range-check")
ELSEIF ("${CMAKE_Fortran_COMPILER_ID}" MATCHES "XL")
SET(CMAKE_Fortran_FLAGS "${CMAKE_Fortran_FLAGS} -qintsize=8 -qrealsize=8")
ELSEIF ("${CMAKE_Fortran_COMPILER_ID}" MATCHES "Cray")
SET(CMAKE_Fortran_FLAGS "${CMAKE_Fortran_FLAGS} -sdefault64")
ELSE()
SET(CMAKE_Fortran_FLAGS "${CMAKE_Fortran_FLAGS} -r8 -i8")
ENDIF()
find_package(SEACASExodus_for CONFIG)
add_executable(ExodusReadFor ExodusRead.f)
target_link_libraries(ExodusReadFor PRIVATE SEACASExodus_for::all_libs)A similar CMakeLists.txt file for using the IOSS library would be something like:
cmake_minimum_required(VERSION 3.1...3.26)
project(IossCMakeExample VERSION 1.0 LANGUAGES CXX)
#### C++ IOSS ####
find_package(SEACASIoss CONFIG)
add_executable(IossExample IossExample.C)
target_link_libraries(IossExample PRIVATE SEACASIoss::all_libs)The cmake-use-example directory contains Exodus example files in the
exodus subdirectory and Ioss example files in the ioss subdirectory.
These provide short examples of how to build and link a program with the
Exodus and/or Ioss libraries.
To use this, copy the contents of the directory to your own filespace and modify the contents as needed.
To configure and build, you would do something like:
mkdir build; cd build
CMAKE_PREFIX_PATH={path_to_root_of_seacas_install} cmake ..
makeAnd you would then get an executable (ExodusWriteC and
ExodusReadFor for Exodus, IossExample for Ioss) compiled and linked
against the Exodus and/or Ioss libraries.
The SEACAS system requires that there be some libraries and applications already existing on the chosen system prior to building SEACAS and its required Third-Party Liberaries.
These include:
-
The
gitapplication is used to access the SEACAS and TPL git repositories -
CMake is used to generate the build system.
-
C, C++, and (optionally) Fortran compilers. The C compiler must support the C11 standard and C++ must support C+++17. GNU, Clang, Intel, Cray, compilers are supported and tested regularly.
-
For parallel capability, an MPI library is needed. We have used openmpi, mpich, mvapich, intel, and cray MPI libraries. It is recommended to use as current an MPI library as possible.
-
Automake is used to configure some of the TPL builds
-
wget is needed to download some of the TPL library source code.
-
python is required to use the
exodus.pyandexomerge.pyPython interfaces to Exodus databases. Python3 is recommended. -
To use the
blotandfastqapplications, an X11 development environment is needed. -
Flex and Bison are optional if you are developing new capabilities in aprepro.
-
M4 is needed to build the netCDF library.
On a mac system, I use the brew system which provides all of the
applications listed above. The X11 system I use is XQuartz. The
Mac also requires Xcode
On an ubuntu system, the following is used to set up the basic packages needed to compile SEACAS:
apt install -y libaec-dev zlib1g-dev automake autoconf \
libcurl4-openssl-dev libjpeg-dev wget curl bzip2 m4 flex bison cmake \
libzip-dev openmpi-bin libopenmpi-dev \On windows, I have used the following packages for MINGW64:
git mingw-w64-x86_64-toolchain make mingw-w64-x86_64-hdf5 \
mingw-w64-x86_64-cgns mingw-w64-x86_64-netcdf mingw-w64-x86_64-zlib \
mingw-w64-x86_64-gcc-fortran mingw-w64-x86_64-gcc-libgfortran \
mingw-w64-x86_64-cmake mingw-w64-x86_64-fmtThere is also a Visual Studio build performed at each commit to the
SEACAS git repository. See the file .appveyor.yml for more details.
SEACAS is licensed under the Modified BSD License. See the LICENSE file for details.
The following externally-developed software routines are used in some of the SEACAS applications and are under a separate license:
| Routine | Where Used | License |
|---|---|---|
| getline | packages/seacas/libraries/aprepro_lib/apr_getline_int.c |
MIT |
| getline | packages/seacas/libraries/suplib_c/getline.c |
BSD |
| GetLongOpt | packages/seacas/libraries/suplib_cpp/GetLongOpt.C |
public domain |
| adler hash | packages/seacas/libraries/suplib_c/adler.c |
zlib |
| MurmurHash | packages/seacas/libraries/ioss/src/Ioss_FaceGenerator.C |
public domain |
| json include file | packages/seacas/libraries/ioss/src/visualization/ |
MIT |
| Tessil Hash | packages/seacas/libraries/ioss/src/hash |
MIT |
| pdqsort | packages/seacas/libraries/ioss/src |
Zlib License |
Greg Sjaardema (gsjaardema@gmail.com, gdsjaar@sandia.gov)