This page aims to be a manual to help developing in OpenBACH API.
For a detailed description of the helpers and the reference scenarios, we encourage you to read the introduction to OpenBACH-extra and OpenBACH API.
In order to keep a clean API, and ease first-time users understanding, here is some conventions proposed for developing reference scenarios.
If you want to have your scenarios included in OpenBACH, please follow them.
Following some of the principles in the Zen of Python, here are a few simple rules to keep in mind:
"""Module Docstring. Describe the steps an phylosophy of your scenario. """ imports # Constants SCENARIO_DESCRIPTION = """Description of what the scenario accomplishes - step by step - walkthrough - if need be """ SCENARIO_NAME = 'default_name_for_scenario' # Other constants # Custom types needed as parameters # utility functions def _utility_function(…): … # "main" scenario functions def scenario_component(…, scenario_name=SCENARIO_NAME): … return scenario def alternate_scenario_component(…, scenario_name=SCENARIO_NAME): … return scenario # exposed "whole" scenario def build(…, post_processing_entity=None, scenario_name=SCENARIO_NAME): scenario = … if post_processing_entity is not None: … return scenario
The layout used should be the usual Python layout made of, in this order, module docstring, imports, constant declarations, classes (mostly namedtuples and custom argument types), and functions.
SCENARIO_DESCRIPTIONat the top;
scenario_name=SCENARIO_NAMEparameter at the end;
scenario_builder.Scenario), it must be wrapped in its own function: this ease reusability and parameters discovery through the function signature.
Scenario.add_argument. The latter making it harder to know, for an unsuspecting user, what values are expected when using the scenario as a sub-scenario.
buildfunction should be considered the “official” finished scenario of the file: it uses other functions to create a complete scenario and optionally add post-processing capabilities. Usage may look like
import scenario_module_file; scenario_module_file.build(…).
buildfunction is encouraged to define a
scenario_name=SCENARIO_NAMEparameter that will be forwarded to other scenario functions called. Beware, though, that naming two scenario with the same name will have the latter one override the former one in the OpenBach database.
buildfunction is encouraged to use scenarios constructed by the other functions and add behaviour (such as post-processing) to those scenarios directly; restrict the use of sub-scenario to the minimum (to ease scheduling, for instance).
File names and default scenario names (the
SCENARIO_NAME constant) share the following four options:
type_of action: e.g.
traffic type: e.g.
main statistic evaluated: e.g.
network_delay(if you want to highlight a measurement or performance evaluations (e.g. delay, jitter, rate, etc.)
main statistic evaluated
Protocol_Layer is one of: service, transport, network, access or physical.
Order of arguments:
There are three ways to help the user to create and launch scenarios:
Some useful information on helpers and scenarios:
How to combine them?
Examples of scripts using the scenario builder are available in the section Reference Scenarios and its subsections.