Installation

This page presents how to install Batsim and some of its tools. We recommend Using Nix, but you may prefer Using Batsim from a Docker container, Using Batsim with Singularity or just Building it yourself.

Using Nix

Batsim and its ecosystem are packaged in the kapack repository. These packages use the Nix package manager. We recommend to use Nix as its purity property allows to fully define all the software dependencies of our tools — as well as the versions of each software. This property is great to produce controlled software environments, as showcased in Doing a reproducible experiment.

If you already have a working Nix installation, you can skip Installing Nix and directly go for Using Batsim from a well-defined Nix environment or Installing Batsim in your system via Nix.

Note

Most package have at least two versions in kapack, named PACKAGE and PACKAGE-master. PACKAGE stands for the latest release of the package, while the -master version is the latest unstable commit from the main git branch.

Note

Nix commands check if the requested packages — and ALL their dependencies — are already available in your system. If this is not the case, all the required packages will be built, which may take a lot of time. To speed the process up you can enable the use of Batsim’s binary cache, so that Nix will download our binaries instead of rebuilding them.

# Install cachix (using Nix).
# (up-to-date instructions are there: https://cachix.org/)
nix-env -iA cachix -f https://cachix.org/api/v1/install

# Configure cachix: tell Nix to use batsim.cachix.org as a binary cache.
cachix use batsim

Installing Nix

Note

This is unlikely but the procedure to install Nix may be outdated. Please refer to Nix installation documentation for up-to-date installation material.

Installing Nix is pretty straightforward.

curl -L https://nixos.org/nix/install | sh

Follow the instructions displayed at the end of the script. You usually need to source a file to access the Nix commands.

Warning

On some distributions like Debian 10, kernel user namespaces are disabled. They should be enabled to make sure Nix works properly. Enable them with the following command:

sudo echo 1 > /proc/sys/kernel/unprivileged_userns_clone

Using Batsim from a well-defined Nix environment

Defining a software environment from which your simulations run is quite straightforward with Nix. This is the recommended way to use Batsim.

For example, the following file defines an en environment from which you can execute batsim and a scheduler implementation. It uses the last release of our tools.

tuto-env.nix

let
  kapack = import
    ( fetchTarball "https://github.com/oar-team/nur-kapack/archive/master.tar.gz") {};
in

kapack.pkgs.mkShell rec {
  name = "tuto-env";
  buildInputs = [
    kapack.batsim # simulator
    kapack.batsched # scheduler
    kapack.batexpe # experiment management tools
    kapack.pkgs.curl # used to retrieve batsim workloads/platforms
  ];
}

After downloading an environment file on your machine’s filesystem, you can enter the environment thanks to nix-shell — for example nix-shell ./env.nix if you downloaded tuto-env.nix into you current working directory as env.nix. The strength of this approach is that you can easily tune which version you want to use for each tool. For example, the next environment uses the latest commit of the master branch of the same tools.

tuto-env-master.nix

let
  kapack = import
    ( fetchTarball "https://github.com/oar-team/nur-kapack/archive/master.tar.gz") {};
in

kapack.pkgs.mkShell rec {
  name = "tuto-env-master";
  buildInputs = [
    kapack.batsim-master # simulator
    kapack.batsched-master # scheduler
    kapack.batexpe-master # experiment management tools
    kapack.pkgs.curl # used to retrieve batsim workloads/platforms
  ];
}

And here is a more advanced example where you can specify the git repository and commit to use for every tool. This can be used as a base to start an experiment using Batsim, as you will probably need to implement new algorithms/features in a scheduler, Batsim or both. You may also be interested in reading Doing a reproducible experiment for good practice advices.

tuto-env-pinned.nix

let
  kapack = import
    ( fetchTarball "https://github.com/oar-team/nur-kapack/archive/master.tar.gz") {};
in

let my-packages = rec {
  # define your own batsim version from batsim-4.2.0
  # (you can select another base, such as batsim-310 for batsim-3.1.0)
  my-batsim = kapack.batsim-420.overrideAttrs(old: rec {
    # define where to the source code of your own batsim version.
    # here, use a given commit on the official batsim git repository on framagit,
    # but you can of course use your own commit/fork instead.
    version = "194c926d4c9c9c83340ef9d5ba17ad47e8b3b67e";
    src = kapack.pkgs.fetchgit rec {
      url = "https://framagit.org/batsim/batsim.git";
      rev = version;
      sha256 = "sha256-RsjvPhuJL6S804/BZGpzl9qkCujWJxWK0isD4osekMI=";
    };
  });

  # define your own version of a scheduler, here from batsched-1.4.0
  my-batsched = kapack.batsched-140.overrideAttrs(old: rec {
    # (you can also your own commit/fork of batsched here)
    version = "b020e48b89a675ae681eb5bcead01035405b571e";
    src = kapack.pkgs.fetchgit rec {
      url = "https://framagit.org/batsim/batsched.git";
      rev = version;
      sha256 = "sha256-AJejS+A1t5F5lY3GKDwnr9W3d7NOL5Hq+ET4IuYXvbY=";
    };
  });

  # can also be done on the pybatsim scheduler, here from pybatsim-3.2.0
  # (note that overridePythonAttrs is needed instead of overrideAttrs)
  my-pybatsim = kapack.pybatsim-320.overridePythonAttrs(old: rec {
    # (you can also your own commit/fork of pybatsim here)
    version = "fa6600eccd4e5ffbebfc7ecba05b64cf84c5e9d3";
    src = kapack.pkgs.fetchgit rec {
      url = "https://gitlab.inria.fr/batsim/pybatsim.git";
      rev = version;
      sha256 = "sha256-3lCjxyYvCH6q3YwQOJp24l+DpRudOIE2BTN40zWGKFs=";
    };
  });

  shell = kapack.pkgs.mkShell rec {
    name = "tuto-env";
    buildInputs = [
      my-batsim
      my-batsched
      my-pybatsim
      kapack.batexpe
      kapack.pkgs.curl
    ];
  };
};
in
  my-packages.shell

Installing Batsim in your system via Nix

This can be done with nix-env --install.

# Install the Batsim simulator.
nix-env -f https://github.com/oar-team/nur-kapack/archive/master.tar.gz -iA batsim

# Other packages from the Batsim ecosystem can also be installed this way.
# For example schedulers.
nix-env -f https://github.com/oar-team/nur-kapack/archive/master.tar.gz -iA batsched
nix-env -f https://github.com/oar-team/nur-kapack/archive/master.tar.gz -iA pybatsim

# Or interactive visualization tools.
nix-env -f https://github.com/oar-team/nur-kapack/archive/master.tar.gz -iA evalys

# Or experiment management tools...
nix-env -f https://github.com/oar-team/nur-kapack/archive/master.tar.gz -iA batexpe

Using Batsim from a Docker container

Batsim and all its runtime dependencies are packaged in the oarteam/batsim Docker container, which allows to run batsim without any installation on a Linux host — assuming that Docker is installed.

docker run \
    --net host \
    -u $(id -u):$(id -g) \
    -v $PWD:/data \
    oarteam/batsim:latest \
    -p /data/platf.xml -w /data/wload.json

Here is a quick explanation on the various parameters.

--net host enables the use of the host network to communicate with the scheduler.
-u $(id -u):$(id -g) enables the generation of output files with your own user permission.
-v $PWD:/data shares your local directory so batsim can find input files and write output files.
oarteam/batsim:latest is the image to run. latest is built from master branch’s last commit.
-p /data/platf.xml -w /data/wload.json are batsim arguments (see Command-line Interface).

Using Batsim with Singularity

The oarteam/batsim docker containers can directly be executed by Singularity.

singularity exec \
    docker://oarteam/batsim:latest \
    batsim -p /data/platf.xml -w /data/wload.json

Building it yourself

Batsim can be built with the Meson (+ Ninja) build system. You can also use CMake if you prefer but please note that our cmake support is deprecated.

Warning

You first need to install all Batsim dependencies for the following lines to work.

Decent clang/gcc (real C++17 support).
Decent boost.
Recent SimGrid.
ZeroMQ.
Redox (our fork has pkg-config support) and its dependencies (hiredis, libev).
RapidJSON.
Pugixml.
Docopt.cpp.

Make sure you install versions of these packages with pkg-config support! The two build systems we use rely on pkg-config to find dependencies.

The dependency list above may be outdated! Please refer to Batsim packages definition in kapack for up-to-date information — in case of doubt, Contact us.

# Configure the project ; use 'build' as build directory
meson build # --prefix=/desired/installation/prefix

# Actually build batsim
ninja -C build

# Install batsim
meson install -C build