The library is available for Linux, Mac and Windows operating systems. In all cases, in order to use the library, one needs some building tools for c/c++ to be installed:
the CMake Build chain (cmake) available for all systems at http://www.cmake.org/.
a GCC compiler1 (c++, ...)
The folders are organized as follows.
Folder lib contains the pre-compiled library libhj.a. This library includes the implemented numerical methods (classes HJB, HJB_SL and HJB_FD), all data management methods (grids, options, ...).
The header files containing the class declarations are in the folder include/.
The master c++ file is main.cpp and is in the folder src/. The folder src/ main contain also the file HJB_user.cpp with some included trajectory reconstruction procedures (to allow the user to add some personal implementation of trajectory reconstruction methods: see the src/*.h files).
These folders should not be renamed.
Folders data, OUTPUT, VALUE: The user has to create a new model file as a C-header file, named like data_mymodel.h, that contains the definition of the drift, distributed-cost, the hamiltonian function (if known analytically), the initial conditions, the boundary conditions, the obstacle function (if any) and all the parameters that describe the model to be solved.
When the data file data_mymodel.h is created, the user should include its name in the file data/data_simulation.h as follows:
#include ”data_mymodel.h”
(The data file data_simulation.h is then included in main.cpp by an include command in the same way, so that the main file is not touched.)
Some basic knowledge of C programming syntax is necessary to describe a new problem to be solved by the HJB solver.
For the user’s convenience several models of data files are already available in the folder data. In particular:
data_basicmodel.h: shows the main functions that have to be defined. It gives some basic options for the computation and for plotting results;
data_advancedmodel.h: similar model implemented by an other approximation method for the Hamiltonian function.
(In this case, these two files themselves include an other data file : data_default.h with more specific parameter definitions.)
The file data_simulation.h should not be removed or renamed (this data file is included in src/main.cpp).
The solver’s executable needs two folders: OUTPUT/ and VALUE/ where the outputs of the simulation will be stored. (If these folders are removed or renamed, the program will not be able to save outputs propertly and will signal an error.)
The ROC-HJ-Editor may be available in the folder ROC-HJ-Editor. This application is designed to assist with the process of editing the template for a new data file. The application shows main possible options and helps the user to define a new data file adapted to the problem to be solved. When creating a new template model using the ROC-HJ-Editor, two files are generated: data_user_mymodel.h which contains the parameters and functions that the user has to define; data_default_mymodel.h which contains predefined parameters that the user does not need to handle (but that are mandatory for running the program). Further detailed instructions on how to construct a header file and how to compile the program are presented in the User’s Manual for ROC-HJ solver.
Once the data file is defined and declared in the file data_simulation.h (see above), the project can be compiled and executed. The compilation/execution process is composed of several steps:
Building the Makefile: cmake . (do not forget the "dot")
Compilation: make (source files *.cpp are in the directory src/)
Options: make clean (cleaning some executable files, some *.o files), make cleanall.
Eventually, before compilation, use ./clean to first erase all unecessary files (can be done before the cmake . command.)
./cleandat will erase all output data files such as OUTPUT/*.dat, OUTPUT/*.txt files, but not the executables. Eventually, before compilation, use ./clean to first erase all unecessary files
Sequential execution mode Execution (basic):
./exe
Execution (with options)
./exe -nn NN -nc NC
Options :
option -nn NN: number of mesh points per dimension
option -nc NC: number of controlsuitable for the equation to be solved.s per command’s dimension.
OpenMP execution mode Some options run with OpenMP. Execution:
./exe -nt nbth
where nbth is the number of threads (typically try nbth=2 or nbth=4).
Parallel code (Parallel MPI version only): contact the ROC-HJ developpers for more info.
Execution:
mpirun -n MPI_PROCS ./exe -nn NN -nc NC -nt OMP_THREADS -nd MPI_GRID_DIM
where
MPI_PROCS: number of MPI processors (default is 1)
NN: number of mesh points per dimension
NC: number of controls per command’s dimension
OMP_THREADS: number of OpenMP threads (default 1)
MPI_GRID_DIM: dimension of the MPI mesh grid decomposition (2 or 3) (default 2).
Example 1 : mpirun -n 2 ./exe -nn 200 will execute the program with 2 MPI processors and 200 mesh points per dimension.
Example 2 : mpirun -n 64 ./exe -nn 500 -nc 10 -nt 4 -nd 2 will execute the program with MPI_PROCS=64 MPI processors, NN=500 points per direction, NC=10 controls per command’s dimension, OMP_THREADS=4 OpenMP threads, and MPI_GRID_DIM=2, the dimension of the MPI mesh grid decomposition.
Example 3 : mpirun -n 1 ./exe -nn 500 -nc 10 -nt 4.
The OpenMP parallelization is working for Semi Lagrangian and Finite Difference methods. When using only this method, one can indicate only one process for the mpirun command (for instance mpirun -n 1 ./exe -nt 4 for using 4 openMP threads) or, equivalently, use ./exe -nt 4
Different version of the package exist corresponding to different OS:
Linux 64 bits : rochj-2.5.7-1jun2022-linux64.zip
Mac OS X : rochj-2.5.7-1jun2022-mac64.zip
Windows : contact us directly.
The distributed software ROC-HJ contains:
a pre-compiled library lib/libhj.a (with the set of its header files )
The main source file src/main.cpp
A set of "model-description" files
data/data_simulation.h
data/data_xxx.h
…
ROC-HJ-Editor (depending of the ROC-HJ version) a code generator with an integrated editor that can help the user to create new data files.
Some visualization tools for Matlab/Octave users (OUTPUT/output_view.m and related files).