icarus package

Subpackages

• icarus.execution package
  • Submodules
  • icarus.execution.collectors module
  • icarus.execution.engine module
  • icarus.execution.network module
  • Module contents
• icarus.models package
  • Subpackages
    • icarus.models.cache package
      • Submodules
      • icarus.models.cache.policies module
      • icarus.models.cache.systems module
      • Module contents
    • icarus.models.strategy package
      • Submodules
      • icarus.models.strategy.base module
      • icarus.models.strategy.hashrouting module
      • icarus.models.strategy.offpath module
      • icarus.models.strategy.onpath module
      • Module contents
  • Module contents
• icarus.results package
  • Submodules
  • icarus.results.plot module
  • icarus.results.readwrite module
  • icarus.results.visualize module
  • Module contents
• icarus.scenarios package
  • Submodules
  • icarus.scenarios.algorithms module
  • icarus.scenarios.cacheplacement module
  • icarus.scenarios.contentplacement module
  • icarus.scenarios.topology module
  • icarus.scenarios.workload module
  • Module contents
• icarus.tools package
  • Submodules
  • icarus.tools.cacheperf module
  • icarus.tools.stats module
  • icarus.tools.traces module
  • Module contents

Submodules

icarus.main module

Run the Icarus simulator.

This script automatically adds Icarus source folder to the PYTHONPATH and then executes the simulator according to the settings specified in the provided configuration file.

Usage:

icarus run -r RESULTS [-c CONFIG_OVERRIDE] [-v] config icarus results print [–json] RESULTS icarus results merge -o OUTPUT INPUT_1 … INPUT_N

icarus.orchestration module

Orchestrate the execution of all experiments.

The orchestrator is responsible for scheduling experiments specified in the user-provided settings.

class Orchestrator(settings, summary_freq=4)

Bases: object

Orchestrator.

It is responsible for orchestrating the execution of all experiments and aggregate results.

Methods

error_callback(msg)	Callback method called in case of error in Python > 3.2
experiment_callback(args)	Callback method called by run_scenario
run()	Run the orchestrator.
stop()	Stop the execution of the orchestrator

error_callback(msg)

Callback method called in case of error in Python > 3.2

Parameters:

msg : string

Error message

experiment_callback(args)

Callback method called by run_scenario

Parameters:

args : tuple

Tuple of arguments

run()

Run the orchestrator.

This call is blocking, whether multiple processes are used or not. This methods returns only after all experiments are executed.

stop()

Stop the execution of the orchestrator

run_scenario(settings, params, curr_exp, n_exp)

Run a single scenario experiment

Parameters:

settings : Settings

The simulator settings

params : Tree

experiment parameters tree

curr_exp : int

sequence number of the experiment

n_exp : int

Number of scheduled experiments

Returns:

results : 3-tuple

A (params, results, duration) 3-tuple. The first element is a dictionary which stores all the attributes of the experiment. The second element is a dictionary which stores the results. The third element is an integer expressing the wall-clock duration of the experiment (in seconds)

icarus.registry module

Registry keeping track of all registered pluggable components

register_cache_placement(name)

Decorator that register a class or a function to a register.

Parameters:

name : str

The name assigned to the class or function to store in the register

register_cache_policy(name)

Decorator that register a class or a function to a register.

Parameters:

name : str

The name assigned to the class or function to store in the register

register_content_placement(name)

Decorator that register a class or a function to a register.

Parameters:

name : str

The name assigned to the class or function to store in the register

register_data_collector(name)

Decorator that register a class or a function to a register.

Parameters:

name : str

The name assigned to the class or function to store in the register

register_decorator(register)

Returns a decorator that register a class or function to a specified register

Parameters:

register : dict

The register to which the class or function is register

Returns:

decorator : func

The decorator

register_results_reader(name)

Decorator that register a class or a function to a register.

Parameters:

name : str

The name assigned to the class or function to store in the register

register_results_writer(name)

Decorator that register a class or a function to a register.

Parameters:

name : str

The name assigned to the class or function to store in the register

register_strategy(name)

Decorator that register a class or a function to a register.

Parameters:

name : str

The name assigned to the class or function to store in the register

register_topology_factory(name)

Decorator that register a class or a function to a register.

Parameters:

name : str

The name assigned to the class or function to store in the register

register_workload(name)

Decorator that register a class or a function to a register.

Parameters:

name : str

The name assigned to the class or function to store in the register

icarus.release module

This module contains all the information related to the current release of the library including descriptions, version number, authors and contact information.

icarus.runner module

Launches a simulation campaign and save results.

run(config_file, output, config_override)

Run function. It starts the simulator. experiments

Parameters:

config : str

Path of the configuration file

output : str

The file name where results will be saved

config_override : dict, optional

Configuration parameters overriding parameters in the file

handler(settings, orch, output, signum=None, frame=None)

Signal handler

This function is called when the simulator receive SIGTERM, SIGHUP, SIGKILL or SIGQUIT from the OS.

Its function is simply to write on a file the partial results.

Parameters:

settings : Settings

The simulator settings

orch : Orchestrator

The instance of the orchestrator

output : str

The output file

icarus.util module

Utility functions

class Settings

Bases: object

Object storing all settings

Attributes:

frozen

Return whether the object is frozen or not.

Methods

freeze()	Freeze the objects.
get(name)	Return value of settings with given name
read_from(path[, freeze])	Initialize settings by reading from a file
set(name, value)	Sets a given value for a settings with given name

freeze()

Freeze the objects. No settings can be added or modified any more

frozen

Return whether the object is frozen or not.

get(name)

Return value of settings with given name

Parameters:

name : str

Name of the setting

Returns:

value : any hashable type

The value of the setting

read_from(path, freeze=False)

Initialize settings by reading from a file

Parameters:

path : str

The path of the file from which settings are read

freeze : bool, optional

If True, freezes object so that settings cannot be changed

set(name, value)

Sets a given value for a settings with given name

Parameters:

name : str

Name of the setting

value : any hashable type

The value of the setting

class AnyValue

Bases: object

Pseudo-value that returns True when compared to any other object.

This object can be used for example to store parameters in resultsets.

One concrete usage example is the following: let’s assume that a user runs an experiment using various strategies under different values of a specific parameter and that the user knows that one strategy does not depend on that parameters while others do. If a user wants to plot the sensitivity of all these strategies against this parameter, he would want the strategy insensitive to that parameter to be selected from the resultset when filtering it against any value of that parameter. This can be achieved by setting AnyValue() to this parameter in the result related to that strategy.

class SequenceNumber(initval=1)

Bases: object

This class models an increasing sequence number.

It is used to assign a sequence number for an experiment in a thread-safe manner.

Methods

assign()	Assigns a new sequence number.
current()	Return the latest sequence number assigned

assign()

Assigns a new sequence number.

Returns:

seq : int

The sequence number

current()

Return the latest sequence number assigned

Returns:

seq : int

The latest assigned sequence number

config_logging(log_level='INFO')

Configure logging level

Parameters:

log_level : int

The granularity of logging

inheritdoc(cls)

Decorator that inherits docstring from the overridden method of the superclass.

Parameters:

cls : Class

The superclass from which the method docstring is inherit

Notes

This decorator requires to specify the superclass the contains the method (with the same name of the method to which this decorator is applied) whose docstring is to be replicated. It is possible to implement more complex decorators which identify the superclass automatically. There are examples available in the Web (e.g., http://code.activestate.com/recipes/576862/), however, the increased complexity leads to issues of interactions with other decorators. This implementation is simple, easy to understand and works well with Icarus code.

timestr(sec, with_seconds=True)

Get a time interval in seconds and returns it formatted in a string.

The returned string includes days, hours, minutes and seconds as appropriate.

Parameters:

sec : float

The time interval

with_seconds : bool

If True the time string includes seconds, otherwise only minutes

Returns:

timestr : str

A string expressing the time in days, hours, minutes and seconds

iround(x)

Round float to closest integer

This code was taken from here: http://www.daniweb.com/software-development/python/threads/299459/round-to-nearest-integer

Parameters:

x : float

The number to round

Returns:

xr : int

The rounded number

step_cdf(x, y)

Convert an empirical CDF in set of points representing steps.

Normally this is conversion is done for plotting purposes.

Parameters:

x : array

The x values of the CDF

y : array

The y values of the CDF

Returns:

x : array

The x values of the CDF

y : array

The y values of the CDF

class Tree(data=None, **attr)

Bases: collections.defaultdict

Tree data structure

This class models a tree data structure that is mainly used to store experiment parameters and results in a hierarchical form that makes it easier to search and filter data in them.

Attributes:

default_factory

Factory for default value called by __missing__().

empty

Return True if the tree is empty, False otherwise

Methods

clear()
copy()
dict([str_keys])	Convert the tree in nested dictionaries
fromkeys(S[,v])	v defaults to None.
get(k[,d])
getval(path)	Get the value at a specific path, None if not there
has_key(k)
items()
iteritems()
iterkeys()
itervalues()
keys()
match(condition)	Check if the tree matches a given condition.
paths()	Return a dictionary mapping all paths to final (non-tree) values and the values.
pop(k[,d])	If key is not found, d is returned if given, otherwise KeyError is raised
popitem()	2-tuple; but raise KeyError if D is empty.
setdefault(k[,d])
setval(path, val)	Set a value at a specific path
update(e)	Update tree from e, similarly to dict.update
values()
viewitems()
viewkeys()
viewvalues()

dict(str_keys=False)

Convert the tree in nested dictionaries

Parameters:

str_key : bool, optional

Convert keys to string. This is useful for example to dump a dict into a JSON object that requires keys to be strings

Returns:

d : dict

A nested dict representation of the tree

empty

Return True if the tree is empty, False otherwise

getval(path)

Get the value at a specific path, None if not there

Parameters:

path : iterable

Path to the desired value

Returns:

val : any type

The value at the given path

match(condition)

Check if the tree matches a given condition.

The condition is another tree. This method iterates to all the values of the condition and verify that all values of the condition tree are present in this tree and have the same value.

Note that the operation is not symmetric i.e. self.match(condition) != condition.match(self). In fact, this method return True if this tree has values not present in the condition tree while it would return False if the condition has values not present in this tree.

Parameters:

condition : Tree

The condition to check

Returns:

match : bool

True if the tree matches the condition, False otherwise.

paths()

Return a dictionary mapping all paths to final (non-tree) values and the values.

Returns:

paths : dict

Path-value mapping

setval(path, val)

Set a value at a specific path

Parameters:

path : iterable

Path to the value

val : any type

The value to set at the given path

update(e)

Update tree from e, similarly to dict.update

Parameters:

e : Tree

The tree to update from

can_import(statement)

Try executing an import statement and return True if succeeds or False otherwise

Parameters:

statement : string

The import statement

Returns:

can_import : bool

True if can import, False otherwise

path_links(path)

Convert a path expressed as list of nodes into a path expressed as a list of edges.

Parameters:

path : list

List of nodes

Returns:

path : list

List of edges

multicast_tree(shortest_paths, source, destinations)

Return a multicast tree expressed as a set of edges, without any ordering

Parameters:

shortest_paths : dict of dicts

Return all pairs shortest paths

source : any hashable object

The source node of the multicast tree

destinations : iterable

All destinations of the multicast tree

apportionment(n, fracs)

Allocate items to buckets according to a given proportion.

This function uses the Largest remainder method with the Hare quota.

Parameters:

n : int

Number of items to allocate to buckets

fracs : list of float

Proportion of items to allocate to each bucket

Module contents