PyPI/MLRsearch/README.rst

   1 Multiple Loss Ratio Search library
   2 ==================================
   3
   4 Origins
   5 -------
   6
   7 This library was developed as a speedup for traditional binary search
   8 in CSIT_ (Continuous System and Integration Testing) project of fd.io_
   9 (Fast Data), one of LFN_ (Linux Foundation Networking) projects.
  10
  11 In order to make this code available in PyPI_ (Python Package Index),
  12 the setuputils stuff (later converted to pyproject.toml) has been added,
  13 but after some discussion, that directory_ ended up having
  14 only a symlink to the original place of tightly coupled CSIT code.
  15
  16 IETF documents
  17 --------------
  18
  19 The currently published `IETF draft`_ describes the logic of version 1.2.0,
  20 earlier library and draft versions do not match each other that well.
  21
  22 Usage
  23 -----
  24
  25 High level description
  26 ______________________
  27
  28 A complete application capable of testing performance using MLRsearch
  29 consists of three layers: Manager, Controller and Measurer.
  30 This library provides an implementation for the Controller only,
  31 including all the classes needed to define API between Controller
  32 and other two components.
  33
  34 Users are supposed to implement the whole Manager layer,
  35 and also implement the Measurer layer.
  36 The Measurer instance is injected as a parameter
  37 when the manager calls the controller instance.
  38
  39 The purpose of Measurer instance is to perform one trial measurement.
  40 Upon invocation of measure() method, the controller only specifies
  41 the intended duration and the intended load for the trial.
  42 The call is done using keyword arguments, so the signature has to be:
  43
  44 ..  code-block:: python3
  45
  46     def measure(self, intended_duration, intended_load):
  47
  48 Usually, the trial measurement process also needs other values,
  49 collectively caller a traffic profile. User (the manager instance)
  50 is responsible for initiating the measurer instance accordingly.
  51 Also, the manager is supposed to set up SUT, traffic generator,
  52 and any other component that can affect the result.
  53
  54 For specific input and output objects see the example below.
  55
  56 Example
  57 _______
  58
  59 This is a minimal example showing every configuration attribute.
  60 The measurer does not interact with any real SUT,
  61 it simulates a SUT that is able to forward exactly one million packets
  62 per second (unidirectional traffic only),
  63 not one packet more (fully deterministic).
  64 In these conditions, the conditional throughput for PDR
  65 happens to be accurate within one packet per second.
  66
  67 This is the screen capture of interactive python interpreter
  68 (wrapped so long lines are readable):
  69
  70 ..  code-block:: python3
  71
  72     >>> import dataclasses
  73     >>> from MLRsearch import (
  74     ...     AbstractMeasurer, Config, MeasurementResult,
  75     ...     MultipleLossRatioSearch, SearchGoal,
  76     ... )
  77     >>>
  78     >>> class Hard1MppsMeasurer(AbstractMeasurer):
  79     ...     def measure(self, intended_duration, intended_load):
  80     ...         sent = int(intended_duration * intended_load)
  81     ...         received = min(sent, int(intended_duration * 1e6))
  82     ...         return MeasurementResult(
  83     ...             intended_duration=intended_duration,
  84     ...             intended_load=intended_load,
  85     ...             offered_count=sent,
  86     ...             forwarding_count=received,
  87     ...         )
  88     ...
  89     >>> def print_dot(_):
  90     ...     print(".", end="")
  91     ...
  92     >>> ndr_goal = SearchGoal(
  93     ...     loss_ratio=0.0,
  94     ...     exceed_ratio=0.005,
  95     ...     relative_width=0.005,
  96     ...     initial_trial_duration=1.0,
  97     ...     final_trial_duration=1.0,
  98     ...     duration_sum=21.0,
  99     ...     preceding_targets=2,
 100     ...     expansion_coefficient=2,
 101     ... )
 102     >>> pdr_goal = dataclasses.replace(ndr_goal, loss_ratio=0.005)
 103     >>> config = Config(
 104     ...     goals=[ndr_goal, pdr_goal],
 105     ...     min_load=1e3,
 106     ...     max_load=1e9,
 107     ...     search_duration_max=1.0,
 108     ...     warmup_duration=None,
 109     ... )
 110     >>> controller = MultipleLossRatioSearch(config=config)
 111     >>> result = controller.search(measurer=Hard1MppsMeasurer(), debug=print_dot)
 112     ....................................................................................
 113     ....................................................................................
 114     ...................>>> print(result)
 115     {SearchGoal(loss_ratio=0.0, exceed_ratio=0.005, relative_width=0.005, initial_trial_
 116     duration=1.0, final_trial_duration=1.0, duration_sum=21.0, preceding_targets=2, expa
 117     nsion_coefficient=2, fail_fast=True): fl=997497.6029392382,s=(gl=21.0,bl=0.0,gs=0.0,
 118     bs=0.0), SearchGoal(loss_ratio=0.005, exceed_ratio=0.005, relative_width=0.005, init
 119     ial_trial_duration=1.0, final_trial_duration=1.0, duration_sum=21.0, preceding_targe
 120     ts=2, expansion_coefficient=2, fail_fast=True): fl=1002508.6747611101,s=(gl=21.0,bl=
 121     0.0,gs=0.0,bs=0.0)}
 122     >>> print(f"NDR conditional throughput: {float(result[ndr_goal].conditional_throughp
 123     ut)}")
 124     NDR conditional throughput: 997497.6029392382
 125     >>> print(f"PDR conditional throughput: {float(result[pdr_goal].conditional_throughp
 126     ut)}")
 127     PDR conditional throughput: 1000000.6730730429
 128     >>>
 129
 130 Change log
 131 ----------
 132
 133 1.2.1: Updated the readme document.
 134
 135 1.2.0: Changed the output structure to use Goal Result as described in draft-05.
 136
 137 1.1.0: Logic improvements, independent selectors, exceed ratio support,
 138 better width rounding, conditional throughput as output.
 139 Implementation relies more on dataclasses, code split into smaller files.
 140 API changed considerably, mainly to avoid long argument lists.
 141
 142 0.4.0: Considarable logic improvements, more than two target ratios supported.
 143 API is not backward compatible with previous versions.
 144
 145 0.3.0: Migrated to Python 3.6, small code quality improvements.
 146
 147 0.2.0: Optional parameter "doublings" has been added.
 148
 149 0.1.1: First officially released version.
 150
 151 .. _CSIT: https://wiki.fd.io/view/CSIT
 152 .. _fd.io: https://fd.io/
 153 .. _LFN: https://www.linuxfoundation.org/projects/networking/
 154 .. _PyPI: https://pypi.org/project/MLRsearch/
 155 .. _directory: https://gerrit.fd.io/r/gitweb?p=csit.git;a=tree;f=PyPI/MLRsearch
 156 .. _IETF draft: https://tools.ietf.org/html/draft-ietf-bmwg-mlrsearch-05