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 using 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

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 (multi-user installation).

sh <(curl --proto '=https' --tlsv1.2 -L https://nixos.org/nix/install) --daemon

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

Installing Batsim in your system via Nix

This can be done with the following command:

nix profile add git+https://framagit.org/batsim/batsim\?ref=main#batsim

Note

The packaging of Batsim and its ecosystem now uses the experimental flakes features of Nix. If flakes are not enabled on your profile you will need to run the following command:

nix --extra-experimental-features 'nix-command flakes' profile add git+https://framagit.org/batsim/batsim\?ref=main#batsim

Other packages from the Batsim ecosystem can be installed with similar commands for pybatsim:

nix --extra-experimental-features 'nix-command flakes' profile add git+https://gitlab.inria.fr/batsim/pybatsim?dir=pybatsim-core#pybatsim

Or the interactive visualization tools evalys:

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

Note

If you prefer to work with a temporary environment you can replace the profile add part of the following commands by shell. This will drop you into a shell with the required package in your PATH.

Using Batsim from a well-defined Nix environment

Todo

This part is out of date since the major changes made in Batsim for the version 5. With the introduction of flakes for the packaging of Batsim and its ecosystem, the following nix environment files must be updated to primarily use flakes instead of kapack.

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 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
  ];
}

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
  ];
}

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.0.0
  # (you can select another base, such as batsim-310 for batsim-3.1.0)
  my-batsim = kapack.batsim-400.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 = "c79d95851cd8f80089b7218a2cf85f4b26ebde5f";
    src = kapack.pkgs.fetchgit rec {
      url = "https://framagit.org/batsim/batsim.git";
      rev = version;
      sha256 = "0lr3vawdbmajisgvbj5cjqw0wfy9y990yhl20kplarambx40nplp";
    };
  });

  # 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 = "1dmx2zk25y24z3m92bsfndvvgmdg4wy2iildjmwr3drmw15s75q0";
    };
  });

  # 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 = "0nr8hqsx6y1k0lv82f4x3fjq6pz2fsd3h44cvnm7w21g4v3s6l6y";
    };
  });

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

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.

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 (at least v4.0).
batprotocol-cpp.
ZeroMQ.
Intervalset.
RapidJSON.
CLI11.

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 the dependencies in meson.build 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