Star-Engine A framework for Monte-Carlo solvers

Download Star-Engine 0.12.0

The purpose of Star-Engine is to provide a development environment for engineers and researchers who wish to use the Monte-Carlo method in order to perform numerical simulations. The Monte-Carlo method is indeed the only numerical method suitable to solve high-dimensional integrals even if an highly complex 3D scene or many coupled phenomena have to be considered.

On paper, such complex situations are easily handled: physicists will essentially translate the integral they need to solve into a mathematical form that can be read as a Monte-Carlo algorithm. But then, developing the associated simulation code might be very difficult, if even possible, because mathematical expressions do not provide any clue on data management concerns, or on how to address the development environment constraints. One good example would be a common integral over a surface: while it could be quite easy to write this integral, coding a fast and accurate function that can be used for any given surface is no small feat.

Star-Engine provides such practical solutions: it can be seen as a bridge between a Monte-Carlo algorithm that exists only as a mathematical expression and the actual numerical simulation code that uses this algorithm in order to evaluate the solution.

Star-Engine is a collection of C libraries available for the x86-64 architecture on GNU/Linux as well as Microsoft Windows 7 and later. Refer to the Components menu for an overview of its main libraries.

Related projects

The following applications make use of Star-Engine to implement Monte-Carlo solvers for a wide range of purposes. Refer to the their associated documentation for more informations.

Install

Although we can install and use each of the components of the Star-Engine separately, the easiest way is to deploy them as they are packaged in a specific version of the Star-Engine which guarantees their reciprocal compatibility.

One way to install the Star-Engine is to download a pre-compiled version and check its integrity against its PGP signature before extracting it.

You can alternatively compile the Star-Engine directly from its sources. On GNU/Linux, first make sure that you have installed git, CMake 3.1 or higher and GNU Compiler Colection 4.8 or higher. Then, in a GNU/Bash shell, type the following commands:

~ $ git clone -b 0.12.0 \
  https://gitlab.com/meso-star/star-engine.git \
  Star-Engine-0.12.0
~ $ mkdir Star-Engine-0.12.0/build
~ $ cd Star-Engine-0.12.0/build
~/Star-Engine-0.12.0/build $ cmake ../cmake
~/Star-Engine-0.12.0/build $ make

These commands install the Star-Engine at the root of your home directory in the Star-Engine-0.12.0/local sub-directory. Visit the Star-Engine git repository for a complete description of the build process and available options.

Once installed, the directory in which the Star-Engine is deployed looks like a classic Unix file system hierarchy:

Quick start

Once the Star-Engine is deployed, you can develop C/C++ applications using its libraries. Consider a GNU/Linux environment and a project with a single source file named main.c that uses the Star-Engine's Star-SamPling library to generate random numbers. To build the project executable, you must first register the Star-Engine installation in the current shell by sourcing its "profile".

~ $ source <STAR_ENGINE_DIR>/etc/star-engine.profile

where <STAR_ENGINE_DIR> is the Star-Engine install directory. This script updates the environment variables of the current shell with the install information of the Star-Engine. The updated environment variables are: LD_LIBRARY_PATH, PATH, MANPATH, CPATH and LIBRARY_PATH. Once this is done, assuming that GNU Compiler Collection is installed on the system, one can compile the program with a common invocation of gcc.

~ $ gcc main.c -lssp

where ssp is the name of the Star-SamPling library in the <STAR_ENGINE_DIR>/lib directory.

Note that this procedure is only practical for simple projects. For more advanced software one should rely on a build system like GNU Make or CMake (see below).

CMake build system

Star-Engine comes with CMake packages that provide programmers using the CMake build system with a seamless integration of the Star-Engine libraries in their software. In order to use these packages, add the Star-Engine install directory to the CMake search paths at the CMake configuration step. Then use the CMake package mechanism to use the required Star-Engine libraries.

For instance, consider a project relying on the Star-3D and the Star-SamPling libraries of the Star-Engine, with a single source file main.c and a CMakeLists.txt file defined as follow:

project(my_project C)

# Use CMake packages to check and add project dependencies
find_package(Star3D REQUIRED)
find_package(StarSP REQUIRED)
include_directories(${Star3D_INCLUDE_DIR} ${StarSP_INCLUDE_DIR})

# Define the program to build
add_executable(my_program main.c)

# Link the program against the Star-Engine libraries on which it depends
target_link_libraries(my_program StarSP Star3D)

One can generate the CMake project with the following command:

cmake -G<CMAKE_GENERATOR> -DCMAKE_PREFIX_PATH=<STAR_ENGINE_DIR> <MY_PROJECT_DIR>

where <CMAKE_GENERATOR> is the build system to use (for instance "Unix Makefiles"), <STAR_ENGINE_DIR> is the Star-Engine install location and <MY_PROJECT_DIR> is the directory where the aforementioned CMakeLists.txt file is stored.