Advanced Topics

Advanced Topics

The previous section introduced many features of Shawn like different transmission models, distance estimation, and the generation of topologies. Nevertheless, there is more functionality available offered by Shawn.

Random Variables

Shawn provides Random Variable for using randomness in applications. By default, there are two different types of probability distribution available: Normal Distribution and Uniform Distribution, but other distributions can be easily added.

The simulation task create_uniform creates a uniform distribution. It takes the arguments lower and upper for defining the range. Whether the given boundaries are included, can be set by lower_incl and upper_incl, respectively. If not given, the task creates a random variable that ranges from 0.0 to 1.0, inclusive 0.0, but exclusive 1.0. Thus,

  create_uniform name=standard_uniform

creates such a variable from. As another example,

  create_uniform name=next_uni \
    lower=-1.8 upper=1.8 \
    lower_incl=false upper_incl=true

creates a uniform distribution in the interval (-1.8,1.8].

The other provided possibility is to create a normal distribution with the task create_normal. It takes the arguments stddev for standard deviation, variance, and mean for the base. The appropriate standard values are 1.0, 1.0, and 0.0, respectively. Hence,

  create_normal name=normal_ex1 mean=1.0 stddev=0.1
  create_normal name=normal_ex2 mean=0.0 variance=0.04

are potential calls for creating normal distributions.

Distance Estimation with Random Variables

Previously the distance estimations perfect estimate and absolute error have been used. The former always returns the correct distance without any error. The latter adds a uniformly distributed value to the returned distance as an error. But there is also the possibility to combine distance estimation errors with own random variables.

The simulation task create_randomized_distance_estimate has been implemented for such cases. Besides the parameters name for unique identification and offset for adding a fixed value on each estimation, it awaits the parameter multiplier. The multiplier is the unique name of an existing random variable. Each time a distance is requested, the real value is multiplied with this random variable. Additionally, the parameter chop_low defines a lower limit of the resulting distance. If lower than the limit, it is either set to the limit directly, or recalculated. The latter happens when resample_chopped is set to true.

For example, a distance estimation with a maximal error of 10 %, and all distances greater than zero can be created as follows.

  create_uniform name=uniform_multiplier lower=.9 upper=1.1
  create_randomized_distance_estimate name=uniform_dist \
    multiplier=uniform_multiplier \
    chop_low=0 resample_chopped=false

First, the uniform distribution variable is created with values from 0.9 to 1.1. Whenever a distance is returned, it is first multiplied with this variable.

Alternatively, a similar result but with a normal distribution can be achieved as follows.

  create_normal name=normal_multiplier mean=1 stddev=0.1
  create_randomized_distance_estimate name=normal_dist \
    multiplier=normal_multiplier \
    chop_low=0 resample_chopped=false

Loading and Saving Worlds

It is already known that simulations can be rerun by setting the seed with the aid of the simulation task random_seed. But doing so just leads to a complete repetition of the previous simulation. If one wants to run multiple simulations on the same scenario with different results, setting the seed is not an option.

Therefore it is possible to load scenarios from, and store them into XML files. This can be done with the simulation tasks load_world and save_world, respectively. Append the following line to the configuration file that loads smiley.xml and populates nodes in lattice style (should be the last available one):

  save_world file=test-world-saving.xml

The generated file should begin with the following lines (at least similar ones):

  <scenario>
  <snapshot id="19">
      <node id="v0_W3DGUB-C">
          <location x="0" y="0" z="0" />
      </node>
      <node id="v1_W3DGUB-C">
          <location x="2" y="0" z="0" />
      </node>
      <node id="v2_W3DGUB-C">
          <location x="4" y="0" z="0" />
      </node>
      [...]
  </snapshot>
  </scenario>

The snapshot id is generally set to the current simulation round. In the consequence that the previous simulation set to a maximal iteration value of 20, the value in the XML file is 19 (counting started at 0). The naming of the id can also be changed via the parameter snapshot. There are the magics %r which is default and is replaced by the current simulation round, %n which represents a counter that increases with every save in the actual simulation, and %u for a uuid that is unique for the current run. For example, writing

  save_world file=test-world-saving.xml snapshot=myid:%r_%n_%u

leads to

  [...]
  <snapshot id="myid:19_0_KMEGUB-A">
  [...]

in the XML file. Finally, the generated file is completely rewritten on each run. This can be controlled by the parameter append which is set to false by default. Setting to true allows multiple snapshots per file.

The other way around, each saved snapshot can again be loaded by load_world that requires a filename via file, and can also get an optional name for the snapshot, which is especially useful when multiple snapshots are stored in a file.