Simulation Setup

In this section, we discuss the basic setup of a simulation run in PeerfactSim.KOM within the Simonstrator Platform. We discuss the XML-based configuration files and the execution of a simulation via the GUIRunner application window. The batched execution of multiple runs with different parameter variations is discussed on the following page.

You need to clone at least the Simrunner-project and build it in your local development environment to follow this part of the documentation. The Simrunner automatically fetches PeerfactSim.KOM and the Simonstrator API via Maven.

Configuration Files

As already shown in the quick-start guide, the GuiRunner offers a graphical interface that enables us to execute XML-based configuration files. These configuration files consist of two basic building block: the configuration of individual hosts (i.e., their active host components) and the configuration of the scenario (i.e., churn, mobility, …). The syntax is fairly simple, however, the configuration files can grow significantly in complexity if they are designed such that they enable automated execution of a multitude of configurations and scenarios, as later discussed for the batched execution of simulations. For now, we focus on the main parts of a configuration file and explain some of the pitfalls and best practices.

Host Builder

This section is still under construction. Consider taking a look at Section 5.1 of the original PeerfactSim.KOM documentation. Although partially outdated, it details most concepts of the configuration files.

Variables

Variables are defined as key-value pairs within a <Default> tag:

<Default>
    <Variable name="SEED" value="10" />
    <Variable name="DELAY" value="100ms" />
    <Variable name="BANDWIDTH" value="10Mbits" />
</Default>

As shown in the example, variable values may utilize unit symbols for time (ms, s, m, h) and bandwidth (kbits, Mbits). To access the value of a variable as input to a setter for any component, simply prefix it with a $, as shown here for the $SEED variable:

<SimulatorCore class="de.tud.kom.p2psim.impl.simengine.Simulator"
    static="getInstance" seed="$SEED" />

In some instances, you might want to concatenate variables (e.g., containing different string values). In this case, you need to use ${}:

<Monitor class="de.tud.kom.p2psim.impl.common.DefaultMonitor"
    experimentDescription="Eval with seed: ${SEED}" />

The first definition of a variable is used (i.e., the values of a variable cannot be overwritten). This is important in the context of batched execution.

Conditionals

Relying on variables, you can structure your configuration files using <IfEqualStr> and <IfNotEqualStr> for conditional blocks. The following example includes a configuration block if the provided variable $ENABLE_DAO is set to the value true (internally, string comparison is utilized!):

<IfEqualStr arg0="$ENABLE_DAO" arg1="true">
    <Analyzer class="de.tudarmstadt.maki.simonstrator.peerfact.application.pubsub.eval.PubSubResultPersistingCustomMeasurement" />
</IfEqualStr>

Includes

It is generally a good idea to structure configurations into different files that are then included and configured. Relying on the fact that the first definition of a variable is used and values are not overwritten, this enables you to specify default values within each included configuration fragment. Have a look at the existing configuration files in config/pubsub/bypass for an example of such a structure. This is especially handy if you want to rely on batched execution of simulations.

To include another XML configuration fragment, you need to add the XInclude specification to your topmost configuration file; afterwards, other configuration files can simply be included using the <xi:include> tag:

<?xml version='1.0' encoding='utf-8'?>
<Configuration xmlns:xi="http://www.w3.org/2001/XInclude">
    <!-- All your toplevel variable definitions -->
    <xi:include href="inc_network.xml" parse="xml" />
    <xi:include href="inc_metrics.xml" parse="xml" />
</Configuration>

Updated: