5.5 ConfigStore

Feedback requested: This is an experimental feature of ns-3. It is found in src/contrib and not in the main tree. If you like this feature and would like to provide feedback on it, please email us.

Values for ns-3 attributes can be stored in an ASCII or XML text file and loaded into a future simulation. This feature is known as the ns-3 ConfigStore. The ConfigStore code is in src/contrib/. It is not yet main-tree code, because we are seeking some user feedback and experience with this.

We can explore this system by using an example. Copy the csma-bridge.cc file to the scratch directory:

  cp examples/csma-bridge.cc scratch/
  ./waf

Let’s edit it to add the ConfigStore feature. First, add an include statement to include the contrib module, and then add these lines:

#include "contrib-module.h"
...
int main (...)
{
  // setup topology

  // Invoke just before entering Simulator::Run ()
  ConfigStore config;
  config.ConfigureDefaults ();
  config.ConfigureAttributes ();

  Simulator::Run ();

There are three attributes that govern the behavior of the ConfigStore: "Mode", "Filename", and "FileFormat". The Mode (default "None") configures whether ns-3 should load configuration from a previously saved file (specify "Mode=Load") or save it to a file (specify "Mode=Save"). The Filename (default "") is where the ConfigStore should store its output data. The FileFormat (default "RawText") governs whether the ConfigStore format is Xml or RawText format.

So, using the above modified program, try executing the following waf command and

./waf --command-template="%s --ns3::ConfigStore::Filename=csma-bridge-config.xml
--ns3::ConfigStore::Mode=Save --ns3::ConfigStore::FileFormat=Xml" --run scratch/csma-bridge

After running, you can open the csma-bridge-config.xml file and it will display the configuration that was applied to your simulation; e.g.

<?xml version="1.0" encoding="UTF-8"?>
<ns3>
 <default name="ns3::V4Ping::Remote" value="102.102.102.102"/>
 <default name="ns3::MsduStandardAggregator::MaxAmsduSize" value="7935"/>
 <default name="ns3::EdcaTxopN::MinCw" value="31"/>
 <default name="ns3::EdcaTxopN::MaxCw" value="1023"/>
 <default name="ns3::EdcaTxopN::Aifsn" value="3"/>
 <default name="ns3::QstaWifiMac::ProbeRequestTimeout" value="50000000ns"/>
 <default name="ns3::QstaWifiMac::AssocRequestTimeout" value="500000000ns"/>
 <default name="ns3::QstaWifiMac::MaxMissedBeacons" value="10"/>
 <default name="ns3::QstaWifiMac::ActiveProbing" value="false"/>
...

This file can be archived with your simulation script and output data.

While it is possible to generate a sample config file and lightly edit it to change a couple of values, there are cases where this process will not work because the same value on the same object can appear multiple times in the same automatically-generated configuration file under different configuration paths.

As such, the best way to use this class is to use it to generate an initial configuration file, extract from that configuration file only the strictly necessary elements, and move these minimal elements to a new configuration file which can then safely be edited and loaded in a subsequent simulation run.

When the ConfigStore object is instantiated, its attributes Filename, Mode, and FileFormat must be set, either via command-line or via program statements.

As a more complicated example, let’s assume that we want to read in a configuration of defaults from an input file named "input-defaults.xml", and write out the resulting attributes to a separate file called "output-attributes.xml". (Note– to get this input xml file to begin with, it is sometimes helpful to run the program to generate an output xml file first, then hand-edit that file and re-input it for the next simulation run).

#include "contrib-module.h"
...
int main (...)
{

  Config::SetDefault ("ns3::ConfigStore::Filename", StringValue ("input-defaults.xml"));
  Config::SetDefault ("ns3::ConfigStore::Mode", StringValue ("Load"));
  Config::SetDefault ("ns3::ConfigStore::FileFormat", StringValue ("Xml"));
  ConfigStore inputConfig;
  inputConfig.ConfigureDefaults ();
  
  //
  // Allow the user to override any of the defaults and the above Bind() at
  // run-time, via command-line arguments
  //
  CommandLine cmd;
  cmd.Parse (argc, argv);

  // setup topology
  ...

  // Invoke just before entering Simulator::Run ()
  Config::SetDefault ("ns3::ConfigStore::Filename", StringValue ("output-attributes.xml"));
  Config::SetDefault ("ns3::ConfigStore::Mode", StringValue ("Save"));
  ConfigStore outputConfig;
  outputConfig.ConfigureAttributes ();
  Simulator::Run ();

5.5.1 GTK-based ConfigStore

There is a GTK-based front end for the ConfigStore. This allows users to use a GUI to access and change variables. Screenshots of this feature are available in the ns-3 Overview presentation.

To use this feature, one must install libgtk and libgtk-dev; an example Ubuntu installation command is:

sudo apt-get install libgtk2.0-0 libgtk2.0-dev

To check whether it is configured or not, check the output of the ./waf configure step:

---- Summary of optional NS-3 features:
Threading Primitives          : enabled
Real Time Simulator           : enabled
GtkConfigStore                : not enabled (library 'gtk+-2.0 >= 2.12' not found)

In the above example, it was not enabled, so it cannot be used until a suitable version is installed and ./waf configure; ./waf is rerun.

Usage is almost the same as the non-GTK-based version, but there are no ConfigStore attributes involved:

  // Invoke just before entering Simulator::Run ()
  GtkConfigStore config;
  config.ConfigureDefaults ();
  config.ConfigureAttributes ();

Now, when you run the script, a GUI should pop up, allowing you to open menus of attributes on different nodes/objects, and then launch the simulation execution when you are done.

5.5.2 Future work

There are a couple of possible improvements:

• save a unique version number with date and time at start of file
• save rng initial seed somewhere.
• make each RandomVariable serialize its own initial seed and re-read it later
• add the default values

This document was generated on August 20, 2010 using texi2html 1.82.