1. The Command-Line Interface
2. Required argument
3. Specifying a certain scenario
   1. Examples
4. Altering simulation parameters
   1. Examples
   2. Example: Analyzing resource growth functions
5. Specifying output behaviour
   1. Output path for CSV logging
   2. Verbosity
6. Running multiple experiments at once
   1. Batch and range
   2. Total amount of experiments
   3. Multi-threading
   4. Examples
7. Specifying real-time plotting behaviour
8. Default Values of Arguments

The Command-Line Interface

Interaction with the model is done through the file sim.py that’s located in the root directory. At any time, a discription of the CLI can be found by using python sim.py --help.

nemo@p-sea$ py sim.py --help

usage: sim.py [-h] [-n scenario] [-p item [item ...]] [-b int]
              [-r item [item ...]] [-j int] [-o path] [-P [bool]]
              [-v [int]] [-f [bool]]
              {run,save,list}

positional arguments:
  {run,save,list}       run: run a simulation; save: save the previous
                        simulation; list: list all saved simulations

optional arguments:
  -h, --help            show this help message and exit
  -n scenario, --name scenario
                        the name of the scenario to load or to save
  -p item [item ...], --param item [item ...]
                        add parameters to override its value, e.g.
                        resource:start_amount=600
  -b int, --batch int   the amount of times the same experiment should be run
                        (defaults to 1)
  -r item [item ...], --range item [item ...]
                        add parameters to run the simulation with a range of
                        values, e.g. resource:start_amount=300,601,100
  -j int, --jobs int    the amount of parallel processes in range or batch
                        mode
  -o path, --out path   the output path for CSV logging
  -P [bool], --plot [bool]
                        whether to show a real-time plot
  -v [int], --verbose [int]
                        whether to enter verbose mode [0..2]
  -f [bool], --fullscreen [bool]
                        whether to show the plot in fullscreen

Required argument

The only required argument is a positional argument. Possible options are run, save and list.

• Specifying run will run a simulation with default parameters, real-time plotting and book-keeping in the CLI.

  $ py sim.py run
  

• Specifying save will save the parameters of the previously ran experiment as a scenario. The scenario will be saved with a default name.

  $ py sim.py save
  

• Specifying list will list the names of all saved scenarios.

  $ py sim.py list
  

Specifying a certain scenario

 -n    [name_of_scenario]
--name [name_of_scenario] 

With the name argument, it’s possible to specify a certain scenario name.

• If the program is operating in run-mode, the name argument can be used to spedify the name of a scenario to load.
• If the program is operating in save-mode, the name argument can be used to specify the name of the to be saved scenario.
• If the program is operating in list-mode, the name argument is ignored.

Examples

• Load a scenario called semi_stable, and run this simulation:

  $ py sim.py run --name semi_stable
  

• Save the previously ran simulation as a scenario named interesting_results

  $ py sim.py save --name interesting_results
  

It isn’t possible to overwrite already saved scenarios. Scenarios can be manually deleted by deleting a the scenario directory in ./scenarios/.

Altering simulation parameters

 -p       [parameter_address]=[value]
--params  [parameter_address]=[value]

With the param argument, it’s possible to override the default values of different parameters. The parameter address [parameter_address] follows the parameter syntax found in Parameters. The new parameter value [value] can be an integer, a float or a string. It is possible to override multiple paramers at once. Note that the param argument is only used in run-mode.

Examples

For an overview of all parameters available in this model, refer to Parameters.

• Change the initial agent count from 100 (default) to 10:

  $ py sim.py run --param agent:count=10
  

• Change the resource growth function¹ from logarithmic (default) to nroot:

  $ py sim.py run --param resource:growth_function=nroot
  

• Change both the initial agent count and the resource growth function:

  $ py sim.py run --param agent:count=10 resource:growth_function=nroot
  

• Change the initial agents’ SVO distribution to a bimodal normal distribution with \(\mu_1=0.2\), \(\sigma_1=0.125\), \(\mu_2=0.95\), and \(\sigma_2=0.01\):

  $ py sim.py run --param \
  >   svo_dist:d1:m=0.2 \
  >   svo_dist:d1:s=0.125 \
  >   svo_dist:d2:m=0.95 \
  >   svo_dist:d2:s=0.01
  

Example: Analyzing resource growth functions

• Analyze the behaviour of the resource growth functions for 100 epochs without interference of any agents:

  $ py sim.py run --param \
  >   resource:growth_function=exponential \
  >   agent:count=0 \
  >   simulation:max_epoch=100
  

• Compare two different base root values for the nroot growth function:

  $ py sim.py run \
  >   --param \
  >       resource:growth_function=nroot \
  >       agent:count=0 \
  >       simulation:max_epoch=100 \
  >       resource:growth_function:nroot:n=2
  

  $ py sim.py run \
  >   --param \
  >       resource:growth_function=nroot \
  >       agent:count=0 \
  >       simulation:max_epoch=100 \
  >       resource:growth_function:nroot:n=15
  

Specifying output behaviour

 -o   [path]
--out [path]

 -v       [?mode]
--verbose [?mode]

This model has multiple ways of showing the condition of the simulation each epoch. Real-time plotting is used to make a simulation more insightful to the human eye, however when running a lot of experiments or closely monitoring the behaviour of each agent, these plots might not be sufficient. This is where the CSV logging and verbosity modes come into play.

Output path for CSV logging

The out argument can be used to specify the output path for the CSV file. Note that CSV logging will only be enabled when this argument is specified (unless running a batch or range of experiments). It is possible to specify either a relative path (relative to ‘sim.py’) or an absolute path.

For example, to enable CSV logging and have the CSV output path be results/out.csv, use:

$ py sim.py run --out results/out.csv

Verbosity

The verbose argument specifies the level of verbosity of the model. Three modes are available:

For examples of the exact output of the different verbosity modes, refer to Output. So for example, to use verbosity mode 1, use:

$ py sim.py run --verbose 1 

Running multiple experiments at once

 -b     [amount]
--batch [amount]

 -r     [parameter_address]=[from],[to],[increment]
--range [parameter_address]=[from],[to],[increment]

 -j    [number_of_jobs]
--jobs [number_of_jobs]

Batch and range

With the batch argument, it’s possible to specify the mount of times a single experiment should be run. As our model is highly stochastic, this functionality can be used to determine more accurately the impact that a certain parameter has on system outcomes.

The batch and range functionality can’t be saved as a scenario. If you attempt to save a previously ran batch or range scenario, it will only save the general parameters as listed in Parameters.

With the range argument, it’s possible to specify a range of values that a specific parameter will iterate over. The list of values is obtained by repeatedly adding [increment] to the value of [from] (inclusive), until the value of [to] (exclusive) is reached. For example, if 0,5,1 is given, the resulting set of values will be \(\{0,1,2,3,4\}\). It is possible to specify ranges for multiple parameters at once.

When using a range and/or batch, CSV logging is enabled by default. If the out argument isn’t specified, it will default to ./out.csv.

Total amount of experiments

Suppose \(P\) is the set of all parameters that are specified through the range argument. Say that, for each specified parameter \(p\in P\), the set of values that \(p\) will range over is called \(V_p\). Finally, suppose that the batch amount is set as \(b\). The total amount of experiments is then equal to \(b\cdot\prod_{p\in P}V_p\).

Keep in mind that the total number of experiments can increase very fast!

Multi-threading

If the total amount of experiments is very high, depending on your CPU, it might be beneficial to enable multi-threading mode. This is done through the jobs argument. This argument specifies the amount of threads that will be used in parallel. The default value of jobs is 1, i.e. the model runs in single-threaded mode by default. To enable multi-threading mode, set the jobs argument to a value higher than 1.

In multi-threading mode, each experiment will be saved to a separate file due to memory concerns and multi-threaded file access limitations. This means that the out argument should contain the path to a directory instead of a file. If the out argument isn’t specified and the simulation runs multi-threaded, it will default to the directory ./out/.

Examples

For an overview of all parameters available in this model, refer to Parameters.

• Run the default experiment 10 times:

  $ py sim.py run --batch 10
  

• Range over the agents’ consumption factor with values ranging from 1 to and including 5:

  $ py sim.py run --range agent:consumption_factor=1,6,1
  

• Run the same experiment as above but repeat it 5 times, and save it to nice_experiment.csv:

  $ py sim.py run \
  >   --range agent:consumption_factor=1,6,1 \
  >   --out nice_experiment.csv \
  >   --batch 5 
  

  This results in a total of 25 experiments.

• Use a bimodal starting SVO distribution where both standard deviations are equal and fixed. We range over both means, where \(\mu_1\) explores [0..0.5] in three steps and \(\mu_2\) explores [0.5..1] in three steps. We also repeat each experiment 12 times. Save to quite_large.csv.

  $ py sim.py run \
  >   --param \
  >       svo_dist:d1:m=0 \
  >       svo_dist:d1:s=0.125 \
  >       svo_dist:d2:m=0 \
  >       svo_dist:d2:s=0.125 \
  >   --range \
  >       svo_dist:d1:m=0,0.5,0.17 \
  >       svo_dist:d2:m=0.5,1,0.16 \
  >   --out quite_large.csv \
  >   --batch 12
  

  We first use --param to create the parameter entries for both means and standard deviations. This is because svo_dist is empty by default. Therefore, we first have to generate both modes of the multi-modal distribution before we can range over any of them. For more information about the svo_dist parameter, refer to Parameters.

  This results in a total of 108 experiments.

• Now we also want to range over both standard deviations. This results in quite a high number of experiments, so we use multi-threading to speed up the process.

  $ py sim.py run \
  >   --param \
  >       svo_dist:d1:m=0 \
  >       svo_dist:d1:s=0.125 \
  >       svo_dist:d2:m=0 \
  >       svo_dist:d2:s=0.125 \
  >   --range \
  >       svo_dist:d1:m=0,0.5,0.17 \
  >       svo_dist:d1:s=0.01,0.32,0.1 \
  >       svo_dist:d2:m=0.5,1,0.16 \
  >       svo_dist:d2:s=0.01,0.32,0.1 \
  >   --out very_big \
  >   --batch 12 \
  >   --jobs 8 
  

  Note that we specify a directory for the out argument, instead of a file.

  This results in a total of 1728 experiments, divided over 8 parallel threads.

Specifying real-time plotting behaviour

 -P     [?boolean]
--plot  [?boolean]

 -f
--fullscreen

--resize

By default, the real-time plotting window will pop up in a small window. Also, depending on the mode of the simulation, real-time plotting might be enabled or disabled by default.

The plot argument can be used to override whether to enable the real-time plotting functionality.

• To forcefully enable the real-time plotting:

  $ py sim.py run --plot true
  

• To forcefully disable the real-time plotting:

  $ py sim.py run --plot false
  

The fullscreen argument can be used to make the real-time plotting window show up in full screen. To enable this, simply add the --fullscreen or -f argument.

The resize argument can be used in a similar way as the fullscreen argument. Specifying this argument will cause the plot to start in a different mode allowing the plot to be resized without it resetting the current plot.

Setting this option however will cause a significant base slow-down of the plot, and cause the plot to become gradually slower over the epochs too!

Default Values of Arguments

If left unspecified, some arguments have different defaults based on the current running mode. This is mainly influenced by whether the model is running a batch or range of experiments, and whether this is done in a multi-threaded environment. In the table below,

Default values of plot, verbose and out arguments depending on values of batch/range and jobs arguments.

Note that both the verbose and plot arguments are ignored if the model is running in multi-threaded mode. This means that, even when you override the verbose or plot arguments, it will not matter. This is because the multi-threading has a custom output, and showing multiple plotting windows is not feasible in a multi-threaded environment.