search

OFFIS-DAI / cosima

cosima integrated the communication simulator OMNeT++ into agent communication
https://cosima.offis.de/
GNU Lesser General Public License v2.1
2 stars 1 forks source link
co-simulation communication energy simulation

readme

cosima: Integration of the (communication) simulator OMNeT++ into agent communication

In this project we integrated the communication simulator OMNeT++ into a separate simulation to model communication between software agents in multi-agent systems. This enables the simulation of realistic communication technologies (such as 5G) and the analysis of dynamic communication characteristics in Smart Grid scenarios.

The project originates from the OFFIS e.V. Institute of Information Technology in Oldenburg and the University of Oldenburg. For further information on cosima see our website.

Originally, cosima was developed for integration into mosaik.

mosaik is a Smart Grid co-simulation framework developed by OFFIS e.V. in Oldenburg. For further information on mosaik see mosaik. OMNeT++ is a simulation framework for (communication) network simulation. For further information on OMNeT++ see OMNeT++.

In addition, cosima provides a direct coupling to the agent framework mango. This coupling can be used especially in scenarios in which the focus is on the high-performance simulation of agent behaviour under the influence of the underlying communication infrastructure.

This README contains the basic instructions on how to install cosima and how to run the simulation. We recommend reading the detailed documentation on ReadTheDocs.

Installation

To use the project, an installation of mosaik (at least version 3.0), OMNeT++ and protobuf are required.

If you use Ubuntu in version 20.04: You can use the Installation Shell Script via

chmod +x install-requirements.sh
sudo ./install-requirements.sh

for the installation tasks. Otherwise, follow the following instructions.

Installation of python packages

Use the package manager pip to install the requirements.txt file.

pip install -r requirements.txt

Installation and configuration of OMNeT++

In order to install OMNeT++ in version 5.6.2, go to their website and follow the instructions for your operating system. In case that you are using Ubuntu (which is recommended), you can also execute the following commands:

Go to home directory

cd ~

Create working directory and enter directory

mkdir -p omnetpp
cd omnetpp

Fetch OMNeT++ source (in version 5.6.2)

wget https://github.com/omnetpp/omnetpp/releases/download/omnetpp-5.6.2/omnetpp-5.6.2-src-linux.tgz
tar -xf omnetpp-5.6.2-src-linux.tgz

Export path

export PATH=$PATH:/usr/omnetpp/omnetpp-5.6.2/bin

Configure and compile

cd omnetpp-5.6.2
./configure PREFER_CLANG=yes
make

Installation and configuration of INET\ Install INET 4.2.2 from the OMNeT++ website OMNeT++ INET. The corresponding release can be found under this link.

Again, under Ubuntu you can navigate to your preferred working directory and execute the following commands:

wget https://github.com/inet-framework/inet/releases/download/v4.2.2/inet-4.2.2-src.tgz
tar -xzf inet-4.2.2-src.tgz
rm inet-4.2.2-src.tgz
mv inet4 inet
cd inet
make makefiles

For the paths defined in the project to work correctly, inet and SimuLTE (optional, see below) should be in the project. This means that the folder structure should look something like this:

cosima

If (for whatever reason) the projects are located in other places, the paths should be adjusted accordingly. Please adjust the ned-path = ../simulte/src;. in the cosima.ini file and your INET_INSTALLATION_PATH path in the general_config.

After your installation, open the OMNeT++ IDE via

omnetpp

In the IDE, you can import the OMNeT++ files of this project as an Existing Project under\ File->Import->General->Existing Projects\ into Workspace.\ Then choose the INET installation directory as a project reference under\ Project Properties -> Project References\ in this project.

Now build your project:\ Project->Build Project

(Optional) if you want to use LTE networks: Install SimuLTE 1.2.0 Install SimuLTE in the correct version and set the SimuLTE installation directory under\ Project Properties -> Project References\ in this project and re-build your project.

After installing all libraries check (and maybe adjust) the Makefile of the project. Under

Project Properties -> OMNeT++ -> MakeMake\ adjust the makemakefile of the source folder ("src:makemake")

You should get a MakeMake option like 

--deep -I"C:\Users\user\Omnet-Projekt\inet" --meta:recurse --meta:use-exported-include-paths --meta:export-library --meta:use-exported-libs --meta:feature-ldflags

Installation of protobuf

Install the protobuf compiler version 3.6.1 (on Ubuntu) via

sudo apt-get install libprotobuf-dev protobuf-compiler

The used protobuf message is already compiled. However, errors may occur with the compiled file as it is system and version dependent. Therefore, it is recommended to compile the files again. If you want to compile the .proto file or another one use

protoc cosima_core/messages/message.proto --cpp_out=. --python_out=.

The output are the classes message_pb2.py for python and message.pb.cc and message.pb.h for C++. Put the C++ files in the OMNeT++ messages folder.

mv -t cosima_omnetpp_project/messages/ cosima_core/messages/message.pb.cc cosima_core/messages/message.pb.h

Now the generated files can be used in python via

from message_pb2 import InfoMessage

and in C++ via

#include "message.pb.h"

If the generated files should be used, in cosima_omnetpp_project/messages/message_pb2.cc, the include path for the header-file needs to be changed from

#include "cosima_core/messages/message.pb.h"

to

#include "message.pb.h"

Now add the protobuf installation to your project in OMNeT++ under\ Project Properties -> OMNeT++ -> MakeMake -> Options -> Link -> more -> additional objects to link with\ add "-lprotobuf".

Optional: PyTests

To set up testing in python follow these steps:

For further information see info.

Optional: Google-Test and Google-Mock

The process of testing is performed with the unit-testing Framework Google Test with Google Mock. It is generally used to test different functionalities of the cosima project like the AgentApps, the MosaikScenarioManager or the Scheduler Module. Because the tests do not include the functionalities of the Networks itself, there is no need to execute them, when implementing a new Network. For this reason, the tests are excluded from being executed in OMNeT++ by default.

Installing Google Test

The following commands can be used to install the Google Test framework under a Linux distribution. Google Test must be installed, to run any of the tests but is not necessary to execute the project itself.

git clone https://github.com/google/googletest.git -b release-1.11.0
cd googletest
mkdir build
cd build
cmake ..
make
sudo make install

or

sudo apt-get install googletest 
cd /usr/src/googletest   
sudo cmake CMakeLists.tx
sudo make
sudo make install

Include the Tests and execute them

Executing the tests is possible by doing the following steps...

  1. Including the tests folder To perform Tests for the cosima project first you have to include them in the OMNeT++ Framework. To do so, right-click on the folder tests and then go to Resource Configuration -> Exclude from Build. In the newly opened window you now can uncheck the boxes for the configuration, that you want to perform the tests on. By default, both the configuration for the debug and release mode should be checked.

excluding of folders

  1. Update dependencies Next up we have to make sure, that the compiler uses the Google Test libraries, when executinmg the project. Under the Project Properties of our cosima_omnetpp_project, we have to click on OMNeT++ -> Makemake -> Options -> Link -> Additional objects to link with. Here you have to add the following dependencies (-lgmock -lgtest -lpthread). Now all that is left, is to rebuild the project and then executing it. The Tests should now be performed with the rest of the project.

updating dependencies

Run simulation

There exist different ways to run a simulation. In the scenario configuration file, it is possible to choose from 'ide', 'qtenv' and 'cmd' as start mode.

Now, in order to start a simulation, you have two options. You can either execute a scenario from the scenarios folder or run the run.py script with command line arguments.

Executing a scenario file

Choose a scenario from the scenarios folder and execute the main-method. Make sure, that the base directory is the cloned repository folder.

Executing a scenario by command line

The run.py script script provides a flexible way to run different simulation scenarios using command-line arguments. It allows you to specify various parameters to customize the behavior of the simulation. Below are the steps to execute the run.py script script and run different scenarios.

To execute the run.py script, use the following command structure:

python run.py [-h] [-s SCENARIO] [-c COMMUNICATION_SIMULATION] [-e END] [-n NETWORK] [-a AGENTS] [-l LOGGING_LEVEL]

Arguments

Example Usage

  1. Run the default scenario:

    python run.py

  2. Run a specific scenario with custom parameters:

    python run.py -s mango_cohda_scenario -c True -e 10000 -n LargeLTENetwork -a 5 -l debug

Note

If you do not specify a scenario using the -s option, the script will default to the communication_scenario. If you encounter any issues or errors, make sure you have provided valid values for the arguments.

Simulation results