



  

osm 1.1 documentation

 [osm](index.html#document-index) 

 latest

 

* [Installation](index.html#document-installation)

	+ [Via pip](index.html#via-pip)

	+ [Clone repository](index.html#clone-repository)

* [Command Line Interface](index.html#document-cli)

	+ [Getting help](index.html#getting-help)

	+ [Build and run the simulation campaign](index.html#build-and-run-the-simulation-campaign)

	+ [Parsing simulation results](index.html#parsing-simulation-results)

	+ [Analyzing simulation results](index.html#analyzing-simulation-results)

* [osm](index.html#document-modules)

	+ [campaign module](index.html#document-campaign)

	+ [custom\_analyzer module](index.html#document-custom_analyzer)

	+ [merge module](index.html#document-merge)

[osm](index.html#document-index)

* [Docs](index.html#document-index) »

* osm 1.1 documentation

* [Edit on GitHub](https://github.com/Pbarbecho/osm/blob/master/doc/index.rst)

---

Automating large-scale simulations for OMNeT++[¶](#automating-large-scale-simulations-for-omnet "Permalink to this headline")

=============================================================================================================================

OSM allows to OMNeT++ users to quickly and easily execute large-scale network simulations. Three shell commands (including help context) are available:

```

# Build and lauch the simulation campaign

$osm launcher [OPTIONS] INIFILE MAKEFILE

# Summarize result files located in output folder

$osm parser [OPTIONS]

# Analyze summarized file

$osm analyzer [OPTIONS]

```

How to cite us[¶](#how-to-cite-us "Permalink to this headline")

---------------------------------------------------------------

If you use SMO for your OMNeT++ experiment analysis, we would appreciate a citation of our work:

16. 1. 2. Bautista, L. F. Urquiza-Aguiar, L. L. Cárdenas and M. A. Igartua, “Large-Scale Simulations Manager Tool for OMNeT++: Expediting Simulations and Post-Processing Analysis,” in IEEE Access, vol. 8, pp. 159291-159306, 2020, doi: 10.1109/ACCESS.2020.3020745.

Feature highlights[¶](#feature-highlights "Permalink to this headline")

-----------------------------------------------------------------------

* Supports Python >= 3.5;

* Fine grane control of the simulation campaign;

* Customizable/interactive plotting

* Runs parallelized simulations and post-processing for large number of files (common in large-scale simulations);

User’s guide[¶](#user-s-guide "Permalink to this headline")

-----------------------------------------------------------

### Installation[¶](#installation "Permalink to this headline")

First, we recommend to install a virtualenv:

```

$pip3 install pipenv

```

#### Via pip[¶](#via-pip "Permalink to this headline")

Then, OSM is developed using pipenv. It can be installed from the master branch:

```

pip3 install --user -U https://github.com/Pbarbecho/osm/archive/master.zip

```

This will install the osm package and its linked dependencies in your current python

library path. In case of a virtual environment is installed, the osm installation can be executed by calling pipenv osm –help.

#### Clone repository[¶](#clone-repository "Permalink to this headline")

As an stating point, cloning the osm project into a osm folder can be issued by executing the following command:

```

git clone https://github.com/Pbarbecho/osm.git osm

```

### Command Line Interface[¶](#command-line-interface "Permalink to this headline")

In order to easy use of OMNeT++ simulation manager (OSM), it includes a command line interface.

OSM cope with the typical tasks that includes the large-scale simulations workflow.

#### Getting help[¶](#getting-help "Permalink to this headline")

OSM cli comes with –help option. Each sub-commands are detailed below::

```

osm --help

Usage: osm [OPTIONS] COMMAND [ARGS]...

  CLI OSM Simulation manager. Execute large-scale OMNeT++ simulations.

Options:

  -v      verbose

  --help  Show this message and exit.

Commands:

  analyzer  Customized filtering and plotting.

  launcher  Build the simulation campaign.

  parser    Merge result files into one single output file (.npy, .mat,...

```

#### Build and run the simulation campaign[¶](#build-and-run-the-simulation-campaign "Permalink to this headline")

Simulation campaign can be run through the launcher sub-command. The same command is used to pass users configurations as detailed below.

Once the launcher sub-command is executed, information of the build simulation campaign is prompted and the uset choices

to execute simulations. To extend information of osm launcher command usage, the –help flag can be used:

```

$osm launcher --help

Usage: osm launcher [OPTIONS] INIFILE MAKEFILE

  Build and run the simulation campaign.

Options:

  --omnet-path PATH               OMNET++ installation directory.

  --output-dir PATH               Path to directory where results are saved.

  -n, --ned-files-dir TEXT        Path of NED files used in the model

                                  separated by ':' (e.g. .:../../src).

                                  Consider current directory is omnetpp.ini

                                  file.

  --max-processes INTEGER         The maximum number of parallel simulations.

                                  [ default available cpus are used ]

  -t, --sim-time INTEGER          Simulation time. Common for all scenarios in

                                  simulation campaign.  [default: 300]

  -r, --repetitions INTEGER       Number of repetitions.  [default: 1]

  -a, --analyze                   Analyze a group of files from a previous

                                  simulation campaign, looking for missing

                                  files.

  -add, --additional-files-path PATH

                                  Path to parameters studied file

                                  (variables.txt.csv) and structure file

                                  (structure.csv) files. [default: parents

                                  directory]

--help                            Show this message and exit.

```

Two arguments are required:

> 

> 1. INIFILE -> The location of the project configuration file (omnetpp.ini)

> 2. MAKEFILE -> Location of the executable file of the project.

> 

> 

> 

As an option:

> 

> * The location of the NED files required by the project should be passed. In case non path was pass, by default the current location (/) will be used.

> * In case of a custom recording of output files, the additional files directory (variables, and structure files) is required.

> * The OMNeT++ installation path, the output directory where simulation results will be save and the directory to additional files (structure and variables) in case of customized recording.

> 

> 

> 

Example of launcher entry:

```

osm -v launcher --max-processes 20 -t 500 -r 20 -n '.:../../src/veins/' -add ~/additionals/ --output-dir ~/results/  ~/veins/omnetpp.ini ~/veins/src/veins\_executable

```

Simulation campaign summary:

```

============================

Simulation campaign summary

============================

Scenarios to simulate [scenario]: ['Barcelona', 'Berlin', 'Tokio']

Iteration variables: 2 = [4, 3]

Repetitions per scenario: 20

Simulation time: 500s

Total Runs: 720

Build simulation campaign (\*Y/N):

```

#### Parsing simulation results[¶](#parsing-simulation-results "Permalink to this headline")

The sub-command parser, can be used to merge into a unique output file simulation campaign results. The –additional-files-path or –add

includes the path to ‘variables’ and ‘structure’ files.

> 

> * Variables file: Include the iteration variable with the set of values. The OMNeT++ syntax is used to declare iteration variables.:

> 

> 

> 

> ```

> \*.node[\*0].veinsmobility.accidentDuration = {0, 50, 300}s

> \*.node[\*].appl.beaconInterval = {1, 30, 60, 90}s

> 

> ```

> * Structure file: Include the structure (n-dimension) of results files. This file is pass in combination with the variable file to map columns with the corresponding parameter (Column name). Columns are listed separated wih a comma as follows:

> 

> 

> 

> ```

> Type,NodeID,tx/rx,recAddress,Speed,MsgId,Length,CH,Time

> 

> ```

> 

> 

> 

Results are exported to any of the supported output formats .npy, .mat, .csv for later process within MATLAB or within the OSM analyzer.

Further details of parser command usage can be listed with the –help flag:

```

$osm launcher --help

Usage: osm parser [OPTIONS]

  Merge result files into one single output file (.npy, .mat, .csv).

Options:

  --max-processes INTEGER         The maximum number of parallel simulations.

                                  By default available cpus are used.

  -i, --input-dir PATH            Directory containing simulations results.

  -o, --output-dir PATH           Path to directory where output file is

                                  saved.

  -O, --output-filename TEXT      Filename with supported extension .npy

                                  (Numpy), .mat (Matlab) or csv (Comma-

                                  separated values).

  -add, --additional-files-path PATH

                                  Path to iteration varibles and structure

                                  files. [default: parents directory]

  --help                          Show this message and exit.

```

In case of no input, output and max processes options are included with the parser command,

by default the installation path create the input folder we the simulation is launched. In the same manner, the output folder and file’s name (results.csv) are created we parser command is executed without options. By default de maximum number of processes is used.

The following command, will try to automatically parse result files into an output file with sim.csv format:

```

$osm parser --add ~/additionals/ --input-dir ~/results/ --output-dir ~/summary/sim.csv

```

#### Analyzing simulation results[¶](#analyzing-simulation-results "Permalink to this headline")

The analyzer command includes a customizable python script. Here, parsed results files can be filtered and sorted for plotting.

The plotting phase is simplified by using the common structure of results (pandas dataframes). An interactive plotting is available with the option -itp. It try to automatically open a web browser (default firefox) where columns can be easily drag and drop to generate custom plots. Extended information is available with the –help flag:

```

$osm analyzer --help

    Usage: osm analyzer [OPTIONS]

        Customized filtering and plotting.

    Options:

        -i, --input-cvs-file PATH       Input .csv file with merge results

        -o, --output-dir PATH           Path to directory where custom analyzed

                                        factors are saved.

        -plt, --interactive-pivot-table

                                        GUI in firefox to drag columns and plot

                                        resutls dataframe.

        --help                          Show this message and exit.

```

The output of the analyzer, includes figures and data used to generate plots:

```

Files generated:

    0) summary\_%PL\_df.png

    1) summary\_%PL\_df.csv

    2) summary\_speed.png

    3) summary\_speed.csv

```

![summary_speed.png](summary_speed.png)

Code Documentation[¶](#code-documentation "Permalink to this headline")

-----------------------------------------------------------------------

### osm[¶](#osm "Permalink to this headline")

#### campaign module[¶](#module-campaign "Permalink to this headline")

`campaign.``add_iteration_variables_to_scenarions_ini_file`(*temp\_ini\_file*, *iteration\_variables\_dictionary*)[[source]](_modules/campaign.html#add_iteration_variables_to_scenarions_ini_file)[¶](#campaign.add_iteration_variables_to_scenarions_ini_file "Permalink to this definition")

Scenarios with same iteration variables.txt

`campaign.``allocate_processors`(*df\_scenarios*, *Processors*)[[source]](_modules/campaign.html#allocate_processors)[¶](#campaign.allocate_processors "Permalink to this definition")

`campaign.``ask_for_scenarios_to_simulate`(*sim\_scenarios\_list*)[[source]](_modules/campaign.html#ask_for_scenarios_to_simulate)[¶](#campaign.ask_for_scenarios_to_simulate "Permalink to this definition")

> 

> Select scenarios to include in the simulation campaign

> 

> 

> 

> Args:

> sim\_scenarios\_list(list): List of scenarios found in .ini file specified as argument

> 

> 

@param sim\_scenarios\_list:

@return:

`campaign.``build_simulation_campaign`(*max\_processors*, *output\_dir*, *omnet\_path*, *sim\_time*, *repetitions*, *sim\_scenarios\_list*, *variables\_path*, *inifile*, *analyze*, *makefile*, *verbose*, *NED\_files\_dir*)[[source]](_modules/campaign.html#build_simulation_campaign)[¶](#campaign.build_simulation_campaign "Permalink to this definition")

> 

> Execute parallel simulations of simulation campaign elements. If there is not enough processors,

> a bath is used for queue simulations and distribute among processors.

> 

> 

> Args:

> 

> 

> 

@param max\_processors: (int) The max number of cpus to use. By default, all cpus are used.

@param output\_dir: (path) The space of structure.csv to export.

@param omnet\_path: (path) The OMNET++ installation path

@param sim\_time: (int) The simulation time. Common for all scenarios.

@param repetitions: (int) The number of runs for each iteration parameter.

@param sim\_scenarios: (list) List of selected scenarios to include in the campaign

@param inifile: (path) Path to .ini file of veins project.

@param analyze: (bool) If true execute simulation campaign. Otherwise analyze result files

@param makefile: (path) Path to executable veins project.

@return:

`campaign.``clear_memory`()[[source]](_modules/campaign.html#clear_memory)[¶](#campaign.clear_memory "Permalink to this definition")

Clean memory cache at the end of simulation execution

`campaign.``create_temp_ini_file`(*output\_results*, *repetitions*, *veins\_ini\_file\_name*, *iteration\_variables\_dictionary*)[[source]](_modules/campaign.html#create_temp_ini_file)[¶](#campaign.create_temp_ini_file "Permalink to this definition")

Instantiates a temp.ini file with simulation campaign configurations.

| Parameters: | * **output\_results** (*path*) – The space of structure.csv to export.

* **repetitions** (*int*) – The number of runs for each iteration parameter.

* **veins\_ini\_file\_name** (*path*) – Path to .ini file of veins project.

 |

`campaign.``execute_sim`(*veins\_exec\_project\_path*, *max\_processors*, *omnet\_path*, *scenario*, *batch*, *sim\_time*, *runs*, *temp\_ini\_name*, *verbose*, *NED\_files\_dir*)[[source]](_modules/campaign.html#execute_sim)[¶](#campaign.execute_sim "Permalink to this definition")

Execute scenario simulation using OMNET++ funcionality (opp\_run all OMNET++ simulation manual 11.20 Running Simulation Campaigns)

Args:

@param veins\_exec\_project\_path: (path) Path to executable veins project.

@param max\_processors: (int) The max number of cpus to use. By default, all cpus are used.

@param omnet\_path: (path) Path to the OMNET++ installation.

@param scenario: Scenario to simulate

@param batch: Batch of simulations

@param sim\_time: (int) The simulation time. Common for all scenarios.

@param runs: Bundle of runs (e.g. 0,1,2,3….)

@param temp\_ini\_name: (string) VEINs ini configuration file name

@return:

:param verbose:

`campaign.``folder_permissions`(*veins\_exec\_project\_path*)[[source]](_modules/campaign.html#folder_permissions)[¶](#campaign.folder_permissions "Permalink to this definition")

`campaign.``get_scenarios`(*veins\_ini\_file*)[[source]](_modules/campaign.html#get_scenarios)[¶](#campaign.get_scenarios "Permalink to this definition")

Try to read simulation scenarios in VEINs project .ini file

OMNET++ defines [Config ] as the structure.csv in ini file to declare an scenario.

This function return a list with [Config ] declarations found in ini file.

`campaign.``isNotBlank`(*myString*)[[source]](_modules/campaign.html#isNotBlank)[¶](#campaign.isNotBlank "Permalink to this definition")

Check if string is empty or null.

Args:

@param myString: (string) Any string

@return: (bool)

`campaign.``missing_files`(*total\_sims*, *output\_dir*)[[source]](_modules/campaign.html#missing_files)[¶](#campaign.missing_files "Permalink to this definition")

Check in results folder if there are missing files of simulation campaign

@param total\_sims: (int) Total number of runs = scenarios \* iter variable \* repetitions\_per\_scenario

@param output\_dir: (path) The space of structure.csv to export.

@return:

`campaign.``new_folder`(*new\_directory*)[[source]](_modules/campaign.html#new_folder)[¶](#campaign.new_folder "Permalink to this definition")

Create new folder and replace if it exists. Used to creates the results folder where results files are saved.

| Parameters: | **new\_directory** (*path*) – Path of the new folder |

`campaign.``parallel`(*max\_processors*, *omnet\_path*, *batch*, *sim\_time*, *runs\_bundle*, *temp\_ini\_name*, *sim\_scenarios\_list*, *makefile*, *verbose*, *NED\_files\_dir*)[[source]](_modules/campaign.html#parallel)[¶](#campaign.parallel "Permalink to this definition")

Execute parallel summary. If the number of cpus < # of summary a batch of runs is set

Args:

@param max\_processors: (int) The max number of cpus to use. By default, all cpus are used.

@param omnet\_path: (path) Path to the OMNET++ installation.

@param batch: (int) Number of simulations per cpu

@param sim\_time: (int) The simulation time. Common for all scenarios.

@param runs\_bundle: (int) Bundle of runs (e.g. 0,1,2,3..)

@param temp\_ini\_name: (string) VEINs ini configuration file name

@param iter\_var\_per\_scenario: (dict) Dictionary with scenarios as keys and iterations as values

@param makefile: (path) Path to executable veins project.

@return:

`campaign.``read_iteration_variables_from_file`(*scenarios\_to\_sim*, *iter\_parameters\_file\_path*)[[source]](_modules/campaign.html#read_iteration_variables_from_file)[¶](#campaign.read_iteration_variables_from_file "Permalink to this definition")

Get the number of iteration structure.csv (defined as specified in OMNET++ Simulation manual 10.4 Parameter Studies)

of each scenario (sim\_scenarios) defined in .ini file.

e.g. OMNET++ study parameter definition -> [\*](#id1).numHosts = ${1, 2, 5, 10..50 step 10}

Args:

sim\_scenarios (list): List of selected scenarios to include in the campaign

veins\_ini\_file\_path (path): Path to .ini file of veins project.

Return a dictionary with scenarios as dic keys and read\_iteration\_variables\_from\_file as values.

Values in read\_iteration\_variables\_from\_file dictionary are defined as follows:

scenario1: [parameters1, parameter2, … , # of read\_iteration\_variables\_from\_file]

scenario2: [parameters1, parameter2, … , # of read\_iteration\_variables\_from\_file]

`campaign.``run`(*output\_dir*, *max\_processors*, *omnet\_path*, *sim\_time*, *repetitions*, *analyze*, *iter\_path*, *inifile*, *makefile*, *verbose*, *NED\_files\_dir*)[[source]](_modules/campaign.html#run)[¶](#campaign.run "Permalink to this definition")

Return the results relative to the desired parameter space in the form of an xarray data structure.csv.

Args:

output\_dir: (path) The space of structure.csv to export.

max\_processors: (int) The max number of cpus to use. By default, all cpus are used.

omnet\_path: (path) Path to the OMNET++ installation.

By default the script try to find the installation path.

sim\_time: (int) The simulation time. Common for all scenarios.

repetitions: (int) The number of runs for each iteration parameter.

analyze: (bool) If true execute simulation campaign. Otherwise analyze result files

from a simulation campaign to find missing simulations.

inifile: (path) Path to .ini file of veins project.

makefile: (path) Path to executable veins project.

`campaign.``run_simulations`()[[source]](_modules/campaign.html#run_simulations)[¶](#campaign.run_simulations "Permalink to this definition")

`campaign.``scenario_runs_set`(*scenario\_iteration\_variables\_dictionary*, *repetitions*)[[source]](_modules/campaign.html#scenario_runs_set)[¶](#campaign.scenario_runs_set "Permalink to this definition")

Generate runs list per scenario in OMNET++ format (opp\_run all OMNET++ simulation manual 11.20 Running Simulation Campaigns)

for create batches e.g. -r 0,1,2,3.

| Parameters: | * **scenario\_iteration\_variables\_dictionary** (*dict*) – Dictionary with scenarios as keys and the number of iteration variables.txt as values

* **repetitions** (*int*) – The number of runs for each iteration parameter.

 |

`campaign.``sim_campaign_info`(*scenarios\_to\_sim*, *iteration\_variables\_dictionary*, *repetitions*, *simtime*, *total\_sims*)[[source]](_modules/campaign.html#sim_campaign_info)[¶](#campaign.sim_campaign_info "Permalink to this definition")

Print simulation campaign summary:

Args:

#### custom\_analyzer module[¶](#custom-analyzer-module "Permalink to this headline")

#### merge module[¶](#merge-module "Permalink to this headline")

Links[¶](#links "Permalink to this headline")

---------------------------------------------

> 

> Github: <https://github.com/Pbarbecho/osm>

