feat(MLRsearch): MLRsearch v7

Replaces MLRv2, suitable for "big bang" upgrade across CSIT.
PyPI metadata updated only partially (full edits will come separately).
Pylint wants less complexity, but the differences are only minor.

+ Use the same (new CSIT) defaults everywhere, also in Python library.
+ Update also PLRsearch to use the new result class.
+ Make upper bound optional in UTI.
+ Fix ASTF approximate duration detection.
+ Do not keep approximated_receive_rate (for MRR) in result structure.

Change-Id: I03406f32d5c93f56b527cb3f93791b61955dfd74
Signed-off-by: Vratko Polak <vrpolak@cisco.com>

1 files changed, 114 insertions, 4 deletions

diff --git a/PyPI/MLRsearch/README.rst b/PyPI/MLRsearch/README.rst
index 8439fe71a1..92c2afe484 100644
--- a/PyPI/MLRsearch/README.rst
+++ b/PyPI/MLRsearch/README.rst
@@ -16,6 +16,11 @@ is only a symlink to the original place of tightly coupled CSIT code.
 Change log
 ----------
 
+1.0.0: Logic improvements, independent selectors, exceed ratio support,
+better width rounding, conditional throughput as output.
+Implementation relies more on dataclasses, code split into smaller files.
+API changed considerably, mainly to avoid long argument lists.
+
 0.4.0: Considarable logic improvements, more than two target ratios supported.
 API is not backward compatible with previous versions.
 
@@ -28,17 +33,122 @@ API is not backward compatible with previous versions.
 Usage
 -----
 
-TODO.
+High level description
+______________________
+
+A complete application capable of testing performance using MLRsearch
+consists of three layers: Manager, Controller and Measurer.
+This library provides an implementation for the Controller only,
+including all the classes needed to define API between Controller
+and other two components.
+
+Users are supposed to implement the whole Manager layer,
+and also implement the Measurer layer.
+The Measurer instance is injected as a parameter
+when the manager calls the controller instance.
+
+The purpose of Measurer instance is to perform one trial measurement.
+Upon invocation of measure() method, the controller only specifies
+the intended duration and the intended load for the trial.
+The call is done using keyword arguments, so the signature has to be:
+
+..  code-block:: python3
+
+    def measure(self, intended_duration, intended_load):
+
+Usually, the trial measurement process also needs other values,
+collectively caller a traffic profile. User (the manager instance)
+is responsible for initiating the measurer instance accordingly.
+Also, the manager is supposed to set up SUT, traffic generator,
+and any other component that can affect the result.
+
+For specific input and output objects see the example below.
+
+Example
+_______
+
+This is a minimal example showing every configuration attribute.
+The measurer does not interact with any real SUT,
+it simulates a SUT that is able to forward exactly one million packets
+per second (unidirectional traffic only),
+not one packet more (fully deterministic).
+In these conditions, the conditional throughput for PDR
+happens to be accurate within one packet per second.
+
+This is the screen capture of interactive python interpreter
+(wrapped so long lines are readable):
+
+..  code-block:: python3
+
+    >>> import dataclasses
+    >>> from MLRsearch import (
+    ...     AbstractMeasurer, Config, MeasurementResult,
+    ...     MultipleLossRatioSearch, SearchGoal,
+    ... )
+    >>>
+    >>> class Hard1MppsMeasurer(AbstractMeasurer):
+    ...     def measure(self, intended_duration, intended_load):
+    ...         sent = int(intended_duration * intended_load)
+    ...         received = min(sent, int(intended_duration * 1e6))
+    ...         return MeasurementResult(
+    ...             intended_duration=intended_duration,
+    ...             intended_load=intended_load,
+    ...             offered_count=sent,
+    ...             forwarding_count=received,
+    ...         )
+    ...
+    >>> def print_dot(_):
+    ...     print(".", end="")
+    ...
+    >>> ndr_goal = SearchGoal(
+    ...     loss_ratio=0.0,
+    ...     exceed_ratio=0.005,
+    ...     relative_width=0.005,
+    ...     initial_trial_duration=1.0,
+    ...     final_trial_duration=1.0,
+    ...     duration_sum=61.0,
+    ...     preceding_targets=2,
+    ...     expansion_coefficient=2,
+    ... )
+    >>> pdr_goal = dataclasses.replace(ndr_goal, loss_ratio=0.005)
+    >>> config = Config(
+    ...     goals=[ndr_goal, pdr_goal],
+    ...     min_load=1e3,
+    ...     max_load=1e9,
+    ...     search_duration_max=1.0,
+    ...     warmup_duration=None,
+    ... )
+    >>> controller = MultipleLossRatioSearch(config=config)
+    >>> result = controller.search(measurer=Hard1MppsMeasurer(), debug=print_dot)
+    ....................................................................................
+    ....................................................................................
+    ....................................................................................
+    ....................................................................................
+    ....................................................................................
+    ....................................................................................
+    ...>>> print(result)
+    {SearchGoal(loss_ratio=0.0, exceed_ratio=0.005, relative_width=0.005, initial_trial_
+    duration=1.0, final_trial_duration=1.0, duration_sum=61.0, preceding_targets=2, expa
+    nsion_coefficient=2): fl=997497.6029392382,s=(gl=61.0,bl=0.0,gs=0.0,bs=0.0), SearchG
+    oal(loss_ratio=0.005, exceed_ratio=0.005, relative_width=0.005, initial_trial_durati
+    on=1.0, final_trial_duration=1.0, duration_sum=61.0, preceding_targets=2, expansion_
+    coefficient=2): fl=1002508.6747611101,s=(gl=61.0,bl=0.0,gs=0.0,bs=0.0)}
+    >>> print(f"NDR conditional throughput: {float(result[ndr_goal].conditional_throughp
+    ut)}")
+    NDR conditional throughput: 997497.6029392382
+    >>> print(f"PDR conditional throughput: {float(result[pdr_goal].conditional_throughp
+    ut)}")
+    PDR conditional throughput: 1000000.6730730429
 
 Operation logic
 ---------------
 
-The latest published `IETF draft`_ describes logic of version 0.3,
-version 0.4 logic will be descibed in next draft version.
+The currently published `IETF draft`_ describes the logic of version 0.4,
+the logic of version 1.0 will be descibed better in the next draft version (-05).
 
 .. _CSIT: https://wiki.fd.io/view/CSIT
 .. _fd.io: https://fd.io/
 .. _LFN: https://www.linuxfoundation.org/projects/networking/
 .. _PyPI: https://pypi.org/project/MLRsearch/
 .. _directory: https://gerrit.fd.io/r/gitweb?p=csit.git;a=tree;f=PyPI/MLRsearch;hb=refs/heads/master
-.. _IETF draft: https://tools.ietf.org/html/draft-ietf-bmwg-mlrsearch-00
+.. _IETF draft: https://tools.ietf.org/html/draft-ietf-bmwg-mlrsearch-04