Prerequisites

ECOGEN must be compiled with C++. It also requires a functional system implementation of MPI library (not provided in this package). Depending on your operating system, you can follow the instructions below to set a full open-source installation.

Installing prerequisites on Ubuntu system

ECOGEN requires two mandatory components to be installed on your Ubuntu system: A C++ compiler and an effective implementation of MPI.

Installing C++ compiler

Nothing is easier than installing C and C++ compiler on Ubuntu. In your terminal, just enter the following commands:

sudo apt-get update
sudo apt-get upgrade
sudo apt-get install gcc
sudo apt-get install g++
sudo apt-get install build-essential
sudo apt-get install make

More information on the Ubuntu doc page https://doc.ubuntu-fr.org/gcc.

Installing openMPI

The simpliest way to install openMPI on Ubuntu is with the apt package manager:

sudo apt-get install libopenmpi-dev

Download

The last ECOGEN version 6.0 can be downloaded from GitHub. The source files are available at the following address: https://github.com/code-mphi/ECOGEN/releases.

The package includes:

  • ECOGEN/src/ folder including C++ source files.

  • ECOGEN/libMeshes/ folder including examples of unstructured meshes in .geo format (Gmsh files version 2). See section Generating Meshes for details.

  • ECOGEN/libEOS/ folder including some possible parameters for the equation-of-states in XML files. See section Materials for details.

  • ECOGEN/libTests folder including:

    • ECOGEN/libTests/referenceTestCases/ folder organized as a test-case library according to the flow model (Euler-equation ECOGEN solver, pressure-velocity-equilibrium model (previously named Kapila’s model) and velocity-equilibrium model for multiphase-flow ECOGEN solver, homogeneous-Euler-equation ECOGEN solver, etc.). A detailed list of available test cases is proposed in section Test cases.

    • 4 quick-manual XML files to create a new flow computation with ECOGEN.

  • ECOGEN.xml: Main entry file to select running cases.

  • Makefile: For compilation in Unix environment. This file may require some adaptation to the user’s environment.

  • LICENSE, COPYRIGHT and AUTHORS: Information files about authors and licensing.

  • README.md: Information file.

  • ECOGEN_V1.0_documentation.pdf: The full documentation for ECOGEN.

Compilation on bash using the provided Makefile

Compilation

Use the Makefile (can be adapted if necessary) to compile ECOGEN sources directly on bash (XX is the number of cores required for compilation):

make -j XX

It builds the ECOGEN application at root of the worktree. By default ECOGEN is built in release mode (-O3 -DNDEBUG compiler flags).

Predefined compilation modes

Other compilation modes are proposed in predefined Makefile targets:

  • debug mode for -O0 -g flags,

  • coverage mode for -O3 –coverage flags,

  • profile mode for -O3 -pg flags.

For example, to build ECOGEN with debug informations:

make -j XX debug

Adding compilation flags

If needed, compilation flags and linker flags can be overloaded using, respectively, CXXFLAGS and LDFLAGS variables. For example, to build ECOGEN with AddressSanitizer (a memory error detector):

CXXFLAGS=-fsanitize=address LDFLAGS=-fsanitize=address make -j XX

Compiling ECOGEN library

If one needs to use ECOGEN as a library, the provided Makefile also defines the libECOGEN.so target that produces a shared library of ECOGEN. To build it:

make -j XX libECOGEN.so

By default, the ECOGEN application built by calling make without providing an explicit target doesn’t use the ecogen library. The ECOGEN application that calls the libECOGEN.so library can be built by calling the exe_using_lib target:

make -j XX exe_using_lib

Clean build files

The clean target (make clean command) cleans temporary build files. The distclean target (make distclean) cleans all files created by the makefile (including ECOGEN and libECOGEN.so files).

Compilation using CMake tool

Alternatively, more advanced users can choose to use CMake to build the project.

Warning

To avoid any confusion, do not mix compilation using the provided Makefile and compilation using CMake in the same worktree.

Prerequisite

Install CMake using your usual package manager. For example on Ubuntu:

apt install -y cmake

Compilation

  1. Configuration step

    Generate the build files in the build_dir directory:

cmake -S . -B build_dir

  1. Compilation step

    Build the project (XX is the number of cores required for compilation).

cmake --build build_dir -j XX

The ECOGEN shared library (libECOGEN.so) and the ECOGEN executable (ECOGEN) are created inside the build_dir directory.

A static library can be built instead of the shared one by setting the BUILD_SHARED_LIBS CMake variable to OFF (cmake -DBUILD_SHARED_LIBS=OFF …).

By default, the ECOGEN application doesn’t use the ecogen library. The ECOGEN_EXE_USE_LIB cmake variable can be set to ON to build an ECOGEN application that calls the ecogen library:

cmake -S . -B build_dir -D ECOGEN_EXE_USE_LIB=ON
cmake --build build_dir -j XX

Predefined compilation modes

CMake proposes predefined compilation modes through the setting of the CMAKE_BUILD_TYPE variable. Please refer to the official documentation for more details. Typical values are Debug (-g compiler flag) at development step and Release (-O3 -DNDEBUG compiler flags) at production step:

cmake -S . -B build_dir -D CMAKE_BUILD_TYPE=Release

Enabling HDF5 I/Os

If needed, user can configure and build ECOGEN with HDF5 I/Os capabilities using the CMake build mode previously described.

Prerequisite

Install parallel HDF5, either from source (see HDF5 documentation), or using a package manager.

For example, to install parallel HDF5 on Ubuntu with OpenMPI MPI library:

apt install -y libhdf5-openmpi-dev

CMake configuration

If parallel HDF5 is installed on your system, CMake should detect it and enable HDF5 I/Os automatically at configuration step. You can force CMake trigger an error if HDF5 is missing by enabling explicitly HDF5 support:

cmake -S . -B build_dir -DENABLE_HDF5=ON

You can then build your project as usually (see cmake compilation step)

Executing ECOGEN

Executing ECOGEN is really easy on bash (XX is the number of cores required for execution):

mpirun -np XX <path-to-ecogen-binary>/ECOGEN

So, if ECOGEN has been built using provided makefile:

mpirun -np XX ./ECOGEN

If it has been built in build_dir directory using CMake:

mpirun -np XX ./build_dir/ECOGEN

ECOGEN may used colorized outputs using ANSI color escape sequences. To avoid garbage outputs in terminals that doesn’t support ANSI colors, you can set the NO_COLOR environment variable to 1 to disable output colorization:

NO_COLOR=1 mpirun -np XX <path-to-ecogen-binary>/ECOGEN

Testing

Once ECOGEN has been successfully compiled, the best way to test ECOGEN’s installation is to run successively the two simple following commands:

  • if you built the project using the provided Makefile:

    ./ECOGEN
mpirun -np 2 ECOGEN

  • if you built it using CMake:

    ./build_dir/ECOGEN
mpirun -np 2 ./build_dir/ECOGEN

These will run the default test case included in the package two times:

  • Once in sequential (single core).

  • Once in parallel using 2 cores.

These should print information in the terminal on the running default test case. If no error message appears, then your installation should be OK and you should be able to use ECOGEN for your own applications.

ECOGEN is including a given number of simple prebuild test cases. Each test can be used as a basis for a new one. Visit the tutorial section Tutorials for more information.