sim.scenario module

This module contains BaseScenario which is an abstract base class providing specification to create a scenario. It contains no implementation. It should be extended to a subclass to describe the actual scenario.

sim.scenario.BaseScenario class is designed to be extended where the extended subclass instance should act as a container to carry entities for the simulation.

The subclass should use it to describe how each entity appears in the world. Reimplement sim.scenario.BaseScenario.on_create() method to build a scenario in the world.

Note

  • Created by: CH Foh (2021)

class sim.scenario.BaseScenario(simworld)

Bases: abc.ABC

This is an abstract base class providing specification to create a scenario. It contains no implementation. It should be extended to a subclass to describe the actual scenario.

See example1.py to learn how to create a scenario using this abstract class.

Show example1.py source code
'''This is a simple example to show how a simulation can be created within 50 lines.'''

from sim import World, BaseScenario, ScreenXY as XY
from node import BaseNode, NodeType, Stationary, StaticPath
from comm import Transceiver, DiscModel

class MyBS(BaseNode):
    '''MyBS: This is a base station design.'''
    def __init__(self, simworld, id, loc, freq, channel):
        super().__init__(simworld, id, node_type=NodeType.BaseStation(self))
        self.set_transceiver(Transceiver(self,freq, channel))
        self.set_mobility(Stationary(loc))

class MyVehicle(BaseNode):
    '''MyVehicle: This is a vehicle design.'''
    def __init__(self, simworld, id, start_loc, path, freq, channel):
        super().__init__(simworld, id, node_type=NodeType.Vehicle(self))
        self.set_transceiver(Transceiver(self,freq, channel))
        self.set_mobility(StaticPath(start_loc,path))

class MyScenario(BaseScenario):
    '''This is MyScenario. It reimplements on_create() and on_event().'''

    ## this will be called at the start
    def on_create(self, simworld) -> bool: 
        self.set_name("A simulation in less than 50 lines")
        omni = DiscModel(radius=100)
        self.my_bs = MyBS(simworld, "BS", XY(160,100), freq=2.4, channel=omni)
        self.my_vehicle = MyVehicle(simworld, id="Vehicle", freq=2.4, channel=omni,
                                    start_loc=XY(10,130), path=[(60,XY(350,130))])
        return True

    ## this will be called repeatedly
    def on_event(self, sim_time, event_obj): 
        self.my_bs.clear_drawing()
        self.my_vehicle.clear_drawing()
        beacon_message = self.my_bs.get("transceiver").create_signal()
        for (node,signal) in self.my_bs.get("transceiver").broadcast(beacon_message):
            if node is self.my_vehicle:
                self.my_bs.draw_circle(100)
                self.my_vehicle.draw_line(self.my_bs)

if __name__ == "__main__":
    sim = World()
    sim.config(sim_stop=5.0, sim_step=0.1, sim_speed=1.0, 
               display_option=True, 
               scenario=MyScenario(sim))
    sim.run()

Methods

add_button(id, label)

Add a button to the user defined space on the simulation window.

add_drawable(drawable)

Use this method to add a persistent drawable on the scenario background.

change_sim_stop_time(new_time)

Change the simulation stop time to a new stop time.

get_setting(setting_str)

Get the simulation setting.

has_map()

Check whether this scenario has a valid street map object.

on_create()

This is an event listener which will be called when the scenario object is being created.

on_event(sim_time, event_obj)

This is an event listener which will be called when an event occurs.

remove_drawable(drawable)

Use this method to remove a persistent drawable from the scenario background.

set_background(bitmap[, x, y, zoom])

Set a background bitmap image for this scenario.

set_name(name)

Set a name for this scenario to show on the window.

sim__get_control()

Get the user defined contols.

use_map(map[, x, y, zoom])

Set a street map info object for this scenario to describe the map.
__init__(simworld)

This is the constructor.

Parameters
simworldsim.simulation.World
It is the container where this scenario will be put to run.
abstract on_create() → bool

This is an event listener which will be called when the scenario object is being created. The subclass should extend this method to create the simulation world.

Note

When creating variables for the subclass, DO NOT use variable names beginning with two underscores. This might clash with the variable used internally in the base class.

Returns
bool

True if the scenario is created successfully, False otherwise. Returning False will cause the simulation to throw a runtime error.

abstract on_event(sim_time, event_obj)

This is an event listener which will be called when an event occurs.

The simulation periodically calls this method to allow user to perform any user simulation for every time step of mobility. In other words, the simulation continuously progresses a simulation time step, freezes the time and calls this method.

A subclass must extend this method to perform any necessary user simulation on the simulation world.

Parameters
sim_timefloat

The simulation time that the event happens.

event_objectsim.event.Event

The event object describing what has happened. The user should check the type of the event object and handle the event accordingly.

add_button(id, label)

Add a button to the user defined space on the simulation window. This method should only be called within on_create() event. After the event, calling to this method will have no effect.

Parameters
idint

The id of the button. When this button is clicked, an event will be triggered and user simulation will be called to pass the button clicked event carrying this id.

label :

The text to show on the button.

sim__get_control()

Get the user defined contols.

Note

User simulation should not use this method. It is used for the simulation engine to retrieve user defined controls after the scenario setup.

set_background(bitmap, x=0, y=0, zoom=1.0)

Set a background bitmap image for this scenario. The background image will be placed on the window at (x,y) position. That is, the left-top position of the image is placed at (x,y) position of the window. This method should be used when the scenario is not using a map. If the scenario uses a map, the associated map image will be used as the background, and there is no need to provide another background image.

The input is an instance of wx.Bitmap. To load a bitmap from a file, simply use wx.Bitmap(file_name).

Parameters
bitmapwx.Bitmap

The bitmap to use for the scenario.

x,yinteger, default is (0,0)

The position to show the bitmap on the window. The position (x,y) will be the left-top position of the image.

zoomfloat, default is 1.0 which is original scale

The zoom scale of the image to view.

set_name(name: str)

Set a name for this scenario to show on the window.

Parameters
namestr

The name for this scenario.

change_sim_stop_time(new_time)

Change the simulation stop time to a new stop time. The input must be a future simulation time, otherwise the new setting will not apply.

Parameters
new_timefloat

The new simulation stop time, which must be a future simulation time.

get_setting(setting_str: str)

Get the simulation setting. This method throws a warning if setting_str is unrecognized.

The following is a list of available settings to get:

  • “name”: the scenario name.

  • “sim step”: the simulation mobility time step.

  • “sim speed”: the current simulation speed.

  • “stop time”: the stop time of the simulation.

  • “background”: the background image assigned to this scenario. A tuple (wx.Bitmap, int, int) is returned specifying the bitmap used and its (x,y) screen position on the viewing window.

  • “simworld”: the instance of sim.sulation.World which hosts this scenario.

  • “map”: the map object encapsulating the map information. None if no street map is assigned to this scenario.

  • “drawables”: a list of drawable instances added to the scenario.

Returns
any

The method returns the requested setting, or None if the input requested setting string is not recognized.

use_map(map, x=0, y=0, zoom=1.0)

Set a street map info object for this scenario to describe the map.

The input map is an object of map.mapinfo.MapInfo. The object contains graph information describing a map and user defined pins. The object also contains the image of the map. Once used, the scenario will apply the map image as the background of the simulation.

Note

The map object must be ready for use. This method will assume the map object is ready. It will access to the map information without further check, and throw errors when accessing a non-ready map. Check for map readiness before using this method to avoid run-time error.

Parameters
mapmap.mapinfo.MapInfo

The object encapsulating the map information.

x,yinteger, default is (0,0)

The map image position to show on the window. The position (x,y) on the map will be shifted to the left-top position of the window.

zoomfloat, default is 1.0 which is original scale

The zoom scale of the map to view.

has_map() → bool

Check whether this scenario has a valid street map object.

add_drawable(drawable)

Use this method to add a persistent drawable on the scenario background.

Parameters
drawablesim.drawable.Drawable

The drawable instance to put on the background.

remove_drawable(drawable)

Use this method to remove a persistent drawable from the scenario background.

Parameters
drawablesim.drawable.Drawable

The drawable instance to be removed. If the drawable instance is not earlier added, nothing will happen.