Format and purpose of YAML files

YAML files are used to configure the simulated experiment in a human-readable format that can be automatized if needed.

In a nutshell, omnetpypy uses YAML files to specify the following information:

  • What modules are going to be used in the simulation.

  • How modules are interconnected to form the network.

  • What parameters characterize the experiment.

Except for the main configuration file, all the other YAML files should be placed in the same directory, whose path is specified in the main configuration file itself.

To design a simulation, you can just follow these steps:

  1. Create a yaml file, named as you want, that contains the global experiment configuration. Example:

    repetitions: 35 # number of independent runs
num_rngs: 50 # number of independent random number generators for each run
time_unit: "us" # time unit for the simulation, in this case microseconds
simulate_until: 1000000
yaml_directory: "./"  # directory where all other yaml files are located, relative to this file
output_dir: "./out" # directory where the simulation output will be stored, relative to this file
engine: "simpy" # simulation engine to use, only simpy is supported for now
num_processes: 8 # number of parallel Python processes

metrics: # metrics to collect
  - name: "queuing_time"
    collect: ["vector", "mean"] # we want the whole vector of samples and the mean
    type: "number"

global_params: # global parameters that can be accessed by any entity in the simulation
  num_servers: 2
  num_clients: 5

    See the configuration file format page for details.

  2. Determine the simple modules that will be part of the simulation. If you need custom behavior, you can create a custom simple module by subclassing SimpleModule.

  3. Create a yaml file called simple.yaml that lists all the simple module classes that will be part of the simulation. They are dynamically loaded by the simulation engine. Example:

    simple:
    - name: ClientModule
      package: my_package
    - name: ServerModule
      package: another_package

    See the “simple.yaml” format page for details.

  4. (optional) Create a yaml file called channels.yaml that lists all the custom channel classes that will be part of the simulation. They are dynamically loaded by the simulation engine.

    See the “channels.yaml” format page for details.

  5. (optional) Determine the compound modules that will be part of the simulation. You define compound modules in another yaml file called compound.yaml. Example:

    compound:
    - name: ClientServerModule
      submodules:
          - type: "ClientModule"
            name: "client_1"
            parameters: # class parameters that will be passed to the constructor
                num_requests: 100
                send_rate: 10
          - type: "ClientModule"
            name: "client_2"
            parameters: # class parameters that will be passed to the constructor
                num_requests: 150
                send_rate: 8
          - type: "ServerModule"
            name: "server"
            parameters:
                service_rate: 20
      connections:
          - source: "client_1.lan" # port with format module_name.port_name
            target: "server.lan0"
            channel: "default" # use the default channel, otherwise specify the channel name
            parameters:
              delay: 10
          - source: "client_2.lan" # port with format module_name.port_name
            target: "server.lan1"
            channel: "default" # use the default channel, otherwise specify the channel name
            parameters:
              delay: 20

    See the “compound.yaml” format page for details.

  6. Create yet another yaml file (it’s the last one, we promise!) called network.yaml that describes the network to simulate. In practice, the network is the top-level compound module. Example:

    network:
    - name: MyNetwork
      submodules:
          - type: "ClientServerModule"
            name: "client_server"

    See the “network.yaml” format page for details.

  7. Run the simulation by instantiating an Experiment object and calling its run_experiments method. Example:

    from omnetpypy.simulation import Experiment

experiment = Experiment(config_file="./config.yaml")
experiment.run_simulations()

For reference, here are all the documentation pages that describe the format of each YAML file: