Create a new directory control, in the following assumed to be at /home/simpy/control/, create a Gemfile with the following content:

source 'https://rubygems.org'
gem 'SimControl'

and run bundle to install the dependencies.

Next, run bundle exec simcontrol init to create the basic directory structure:

├── Controlfile
├── Gemfile
├── Gemfile.lock
├── results
└── scenarios

The Controlfile describes both the hosts on which the simulation will run, as well as general information about the simulation program. The default Controlfile is given below

hosts do
  #A host with name "hostname"
  use "hostname"

  #Another host, with 3 cores to be used for simulation
  use "another-hostname", cores: 3
end

#currently only a python environment is implemented
simulation PythonEnvironment, "/home/simpy/simulation/simulation.py",
  #use a virtualenv, not the global python
  virtualenv: "/home/simpy/simpy-env",
  #do not use the default system python but pypy
  interpreter: "pypy"

In order to create your first simulation scenario, run

bundle exec simcontrol scenario myScenario

which creates a results subfolder named myScenario as well as a scenario description file myScenario.rb in the scenarios folder, resulting in the following overall project structure:

.
├── Controlfile
├── Gemfile
├── Gemfile.lock
├── results
│   └── myScenario
└── scenarios
    └── myScenario.rb

The default scenario description in myScenario.rb has the following content:

repetitions 10
numberOfServers = (1..100).step(10)

numberOfServers.each do |currentNumberOfServers|
  simulate numberOfServers: currentNumberOfServers,
    duration: 1.day + 1.hour,
    transientPhaseDuration: 1.hour
end

This describes 10 scenarios, each with 10 repetitions are described. A system with a varying number of server components is simulated for a duration of 25 hours, the first hour is exempt from statistic collection to account for the transient phase.

Next, we consider the execution of the simulation on one of the hosts specified in the Controlfile by running bundle exec simulate myScenario. First, all scenarios, i.e. calls to simulate, are enumerated. Then, they are assigned to the hosts specified via the host call, were each host is considered multiple times if multiple cores are specified. In our example, the 3 of the 10 scenarios will be assigned to hostname and the first core of another-hostname, while 2 scenarios will be assigned the remaining cores of another-hostname. Then, simcontrol obtains the local hostname and the assigned scenarios and one scenario group is started per core. The command to simulate a scenario is obtained as follows:

The class and options hash passed to the simulation method in Controlfile are used to construct a PythonEnvironment instance, which is able to start the simulation environment. Note, that the simulation method merges the options hash with computed options, e.g. the path to the scenarios results directory and the seed to use for the stimulation. The full set of parameters used to invoke the simulation are obtained from the parameters of the simulate method in myScenario.rb, were each of the (hash) options passed to the simulation as unix-style long parameters (i.e. foo: 4 is converted to --foo 4) and the first parameter is passed as a command.

In our example this results in the following simulation scenarios. Note, that in our example each of the scenarios is executed with varying parameter values for SEED (seed generation is discussed later).