/*
 * This file is part of the StarPU Handbook.
 * Copyright (C) 2009--2011  Universit@'e de Bordeaux 1
 * Copyright (C) 2010, 2011, 2012, 2013, 2014  Centre National de la Recherche Scientifique
 * Copyright (C) 2011, 2012 Institut National de Recherche en Informatique et Automatique
 * See the file version.doxy for copying conditions.
 */

/*! \page SimGridSupport SimGrid Support

StarPU can use Simgrid in order to simulate execution on an arbitrary
platform.

\section Preparing your application for simulation.

There are a few technical details which need to be handled for an application to
be simulated through Simgrid.

If the application uses <c>gettimeofday</c> to make its
performance measurements, the real time will be used, which will be bogus. To
get the simulated time, it has to use starpu_timing_now() which returns the
virtual timestamp in us.

For some technical reason, the application's .c file which contains main() has
to be recompiled with starpu.h, which in the simgrid case will #define main()
into starpu_main(), and it is libstarpu which will provide the real main() and
call the application's main().

\section Calibration Calibration

The idea is to first compile StarPU normally, and run the application,
so as to automatically benchmark the bus and the codelets.

\verbatim
$ ./configure && make
$ STARPU_SCHED=dmda ./examples/matvecmult/matvecmult
[starpu][_starpu_load_history_based_model] Warning: model matvecmult
   is not calibrated, forcing calibration for this run. Use the
   STARPU_CALIBRATE environment variable to control this.
$ ...
$ STARPU_SCHED=dmda ./examples/matvecmult/matvecmult
TEST PASSED
\endverbatim

Note that we force to use the scheduler <c>dmda</c> to generate
performance models for the application. The application may need to be
run several times before the model is calibrated.

\section Simulation Simulation

Then, recompile StarPU, passing \ref enable-simgrid "--enable-simgrid"
to <c>./configure</c>, and re-run the application:

\verbatim
$ ./configure --enable-simgrid && make
$ STARPU_SCHED=dmda ./examples/matvecmult/matvecmult
TEST FAILED !!!
\endverbatim

It is normal that the test fails: since the computation are not actually done
(that is the whole point of simgrid), the result is wrong, of course.

If the performance model is not calibrated enough, the following error
message will be displayed

\verbatim
$ STARPU_SCHED=dmda ./examples/matvecmult/matvecmult
[starpu][_starpu_load_history_based_model] Warning: model matvecmult
    is not calibrated, forcing calibration for this run. Use the
    STARPU_CALIBRATE environment variable to control this.
[starpu][_starpu_simgrid_execute_job][assert failure] Codelet
    matvecmult does not have a perfmodel, or is not calibrated enough
\endverbatim

The number of devices can be chosen as usual with \ref STARPU_NCPU,
\ref STARPU_NCUDA, and \ref STARPU_NOPENCL.  For now, only the number of
cpus can be arbitrarily chosen. The number of CUDA and OpenCL devices have to be
lower than the real number on the current machine.

The amount of simulated GPU memory is for now unbound by default, but
it can be chosen by hand through the \ref STARPU_LIMIT_CUDA_MEM,
\ref STARPU_LIMIT_CUDA_devid_MEM, \ref STARPU_LIMIT_OPENCL_MEM, and
\ref STARPU_LIMIT_OPENCL_devid_MEM environment variables.

The Simgrid default stack size is small; to increase it use the
parameter <c>--cfg=contexts/stack_size</c>, for example:

\verbatim
$ ./example --cfg=contexts/stack_size:8192
TEST FAILED !!!
\endverbatim

\section SimulationOnAnotherMachine Simulation On Another Machine

The simgrid support even permits to perform simulations on another machine, your
desktop, typically. To achieve this, one still needs to perform the Calibration
step on the actual machine to be simulated, then copy them to your desktop
machine (the <c>$STARPU_HOME/.starpu</c> directory). One can then perform the
Simulation step on the desktop machine, by setting the environment
variable \ref STARPU_HOSTNAME to the name of the actual machine, to
make StarPU use the performance models of the simulated machine even
on the desktop machine.

If the desktop machine does not have CUDA or OpenCL, StarPU is still able to
use simgrid to simulate execution with CUDA/OpenCL devices, but the application
source code will probably disable the CUDA and OpenCL codelets in thatcd sc
case. Since during simgrid execution, the functions of the codelet are actually
not called, one can use dummy functions such as the following to still permit
CUDA or OpenCL execution:

\snippet simgrid.c To be included. You should update doxygen if you see this text.


*/