diff options
Diffstat (limited to 'PyPI')
| -rw-r--r-- | PyPI/MLRsearch/MANIFEST.in | 6 | ||||
| -rw-r--r-- | PyPI/MLRsearch/README.rst | 144 | ||||
| -rw-r--r-- | PyPI/MLRsearch/hints_and_todos.txt | 7 | ||||
| -rw-r--r-- | PyPI/MLRsearch/pyproject.toml | 31 | ||||
| -rw-r--r-- | PyPI/MLRsearch/setup.cfg | 7 | ||||
| -rw-r--r-- | PyPI/MLRsearch/setup.py | 52 | ||||
| -rw-r--r-- | PyPI/jumpavg/MANIFEST.in | 6 | ||||
| -rw-r--r-- | PyPI/jumpavg/README.rst | 61 | ||||
| -rw-r--r-- | PyPI/jumpavg/hints_and_todos.txt | 7 | ||||
| -rw-r--r-- | PyPI/jumpavg/pyproject.toml | 28 | ||||
| -rw-r--r-- | PyPI/jumpavg/setup.cfg | 7 | ||||
| -rw-r--r-- | PyPI/jumpavg/setup.py | 62 |
12 files changed, 250 insertions, 168 deletions
diff --git a/PyPI/MLRsearch/MANIFEST.in b/PyPI/MLRsearch/MANIFEST.in deleted file mode 100644 index 58073271d1..0000000000 --- a/PyPI/MLRsearch/MANIFEST.in +++ /dev/null @@ -1,6 +0,0 @@ - -# Include the README -include README.rst - -# Include the license file -include LICENSE.txt diff --git a/PyPI/MLRsearch/README.rst b/PyPI/MLRsearch/README.rst index 8439fe71a1..bec1b7749e 100644 --- a/PyPI/MLRsearch/README.rst +++ b/PyPI/MLRsearch/README.rst @@ -9,13 +9,136 @@ in CSIT_ (Continuous System and Integration Testing) project of fd.io_ (Fast Data), one of LFN_ (Linux Foundation Networking) projects. In order to make this code available in PyPI_ (Python Package Index), -the setuputils stuff has been added, -but after some discussion, the export directory_ -is only a symlink to the original place of tightly coupled CSIT code. +the setuputils stuff (later converted to pyproject.toml) has been added, +but after some discussion, that directory_ ended up having +only a symlink to the original place of tightly coupled CSIT code. + +IETF documents +-------------- + +The currently published `IETF draft`_ describes the logic of version 1.2.0, +earlier library and draft versions do not match each other that well. + +Usage +----- + +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=21.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=21.0, preceding_targets=2, expa + nsion_coefficient=2, fail_fast=True): fl=997497.6029392382,s=(gl=21.0,bl=0.0,gs=0.0, + bs=0.0), SearchGoal(loss_ratio=0.005, exceed_ratio=0.005, relative_width=0.005, init + ial_trial_duration=1.0, final_trial_duration=1.0, duration_sum=21.0, preceding_targe + ts=2, expansion_coefficient=2, fail_fast=True): fl=1002508.6747611101,s=(gl=21.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 + >>> Change log ---------- +1.2.1: Updated the readme document. + +1.2.0: Changed the output structure to use Goal Result as described in draft-05. + +1.1.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. @@ -25,20 +148,9 @@ API is not backward compatible with previous versions. 0.1.1: First officially released version. -Usage ------ - -TODO. - -Operation logic ---------------- - -The latest published `IETF draft`_ describes logic of version 0.3, -version 0.4 logic will be descibed in next draft version. - .. _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 +.. _directory: https://gerrit.fd.io/r/gitweb?p=csit.git;a=tree;f=PyPI/MLRsearch +.. _IETF draft: https://tools.ietf.org/html/draft-ietf-bmwg-mlrsearch-05 diff --git a/PyPI/MLRsearch/hints_and_todos.txt b/PyPI/MLRsearch/hints_and_todos.txt new file mode 100644 index 0000000000..ea1f087303 --- /dev/null +++ b/PyPI/MLRsearch/hints_and_todos.txt @@ -0,0 +1,7 @@ +toml hint: https://flit.pypa.io/en/stable/pyproject_toml.html +rst hint: https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html +build hint: https://packaging.python.org/en/latest/tutorials/packaging-projects/ + +TODO: Include simulator and tests. +TODO: Test which Python versions is the code actually compatible with. +TODO: Create a separate webpage for MLRsearch library. diff --git a/PyPI/MLRsearch/pyproject.toml b/PyPI/MLRsearch/pyproject.toml new file mode 100644 index 0000000000..c9f705aa74 --- /dev/null +++ b/PyPI/MLRsearch/pyproject.toml @@ -0,0 +1,31 @@ +[project] +name = "MLRsearch" +version = "1.2.1" +description = "Library for extending and speeding up througput search." +license = { file = "LICENSE.txt" } +readme = { file = "README.rst", content-type = "text/x-rst" } +requires-python = "~=3.8" +classifiers = [ + "Development Status :: 3 - Alpha", + "Intended Audience :: Telecommunications Industry", + "License :: OSI Approved :: Apache Software License", + "Natural Language :: English", + "Operating System :: OS Independent", + "Programming Language :: Python :: 3.8", + "Topic :: System :: Networking", +] +keywords = [ + "binary search", "throughput", "networking", "RFC 2544", + "conditional throughput", +] +authors = [ + { name = "Cisco Systems Inc. and/or its affiliates", email = "csit-dev@lists.fd.io" }, +] +maintainers = [ + { name = "Vratko Polak", email = "vrpolak@cisco.com" }, + { name = "Tibor Frank", email = "tifrank@cisco.com" }, +] + +[project.urls] +"Bug Tracker" = "https://jira.fd.io/projects/CSIT/issues" +"Source" = "https://gerrit.fd.io/r/gitweb?p=csit.git;a=tree;f=PyPI/MLRsearch" diff --git a/PyPI/MLRsearch/setup.cfg b/PyPI/MLRsearch/setup.cfg deleted file mode 100644 index b4abd1bd30..0000000000 --- a/PyPI/MLRsearch/setup.cfg +++ /dev/null @@ -1,7 +0,0 @@ -[metadata] -# This includes the license file in the wheel. -license_file = LICENSE.txt - -[bdist_wheel] -# TODO: Make the code work both on Python 2 and 3. -universal=0 diff --git a/PyPI/MLRsearch/setup.py b/PyPI/MLRsearch/setup.py deleted file mode 100644 index c3369e6589..0000000000 --- a/PyPI/MLRsearch/setup.py +++ /dev/null @@ -1,52 +0,0 @@ -"""A setup module for setuptools. - -See: -https://packaging.python.org/en/latest/distributing.html - -TODO: Move as much as possible into setup.cfg -""" - -from setuptools import setup, find_packages -from os import path -from io import open - -here = path.abspath(path.dirname(__file__)) -with open(path.join(here, u"README.rst"), encoding=u"utf-8") as f: - long_description = f.read() - -setup( - name=u"MLRsearch", - version=u"0.4.0", # This is currently the only place listing the version. - description=u"Library for speeding up binary search using shorter measurements.", - long_description=long_description, - long_description_content_type=u"text/x-rst", - # TODO: Create a separate webpage for MLRsearch library. - url=u"https://gerrit.fd.io/r/gitweb?p=csit.git;a=tree;f=PyPI/MLRsearch;hb=refs/heads/master", - author=u"Cisco Systems Inc. and/or its affiliates", - author_email=u"csit-dev@lists.fd.io", - classifiers=[ - u"Development Status :: 3 - Alpha", - u"Intended Audience :: Science/Research", - u"Intended Audience :: Telecommunications Industry", - u"License :: OSI Approved :: Apache Software License", - u"Programming Language :: Python :: 3.6", - u"Topic :: System :: Networking" - ], - keywords=u"binary search throughput networking", - packages=find_packages(exclude=[]), - python_requires=u"~=3.6", - install_requires=[], - # TODO: Include simulator and tests. - extras_require={ - }, - package_data={ - }, - entry_points={ - u"console_scripts": [ - ], - }, - project_urls={ - u"Bug Reports": u"https://jira.fd.io/projects/CSIT/issues", - u"Source": u"https://gerrit.fd.io/r/gitweb?p=csit.git;a=tree;f=PyPI/MLRsearch;hb=refs/heads/master", - }, -) diff --git a/PyPI/jumpavg/MANIFEST.in b/PyPI/jumpavg/MANIFEST.in deleted file mode 100644 index 58073271d1..0000000000 --- a/PyPI/jumpavg/MANIFEST.in +++ /dev/null @@ -1,6 +0,0 @@ - -# Include the README -include README.rst - -# Include the license file -include LICENSE.txt diff --git a/PyPI/jumpavg/README.rst b/PyPI/jumpavg/README.rst index 3161988f69..b6b502c62b 100644 --- a/PyPI/jumpavg/README.rst +++ b/PyPI/jumpavg/README.rst @@ -4,34 +4,71 @@ Jumpavg library Origins ------- -This library was developed as anomaly detection logic -for PAL_ (Presentation and Analysis Layer) -of CSIT_ (Continuous System and Integration Testing) -project of fd.io_ (Fast Data), one of LFN_ -(Linux Foundation Networking) projects. +This library was developed as anomaly detection logic for "PAL" component +of CSIT_ (Continuous System and Integration Testing) project +of fd.io_ ("Fast Data"), one of LFN_ (Linux Foundation Networking) projects. +Currently still being primarily used in PAL's successor: CSIT-DASH_. In order to make this code available in PyPI_ (Python Package Index), -the setuputils stuff has been added, -and the code has been moved into a separate directory_, -in order to not intervere of otherwise tightly coupled CSIT code. +the setuputils stuff (later converted to pyproject.toml) has been added, +but after some discussion, that directory_ ended up having +only a symlink to the original place of tightly coupled CSIT code. Usage ----- -TODO. +High level description +______________________ + +The main method is "classify", which partitions the input sequence of values +into consecutive "groups", so that standard deviation of samples within a group +is small. + +The design decisions that went into the final algorithm are heavily influenced +by typical results seen in CSIT testing, so it is better to read about +the inner workings of the classification procedure in CSIT documentation, +especially the Minimum Description Length sub-chapter of `trend analysis`_. + +Example +_______ + +A very basic example, showing some inputs and the structure of output. +The output is a single line, here shown wrapped for readability. + +.. code-block:: python3 + + >>> from jumpavg import classify + >>> classify(values=[2.1, 3.1, 3.2], unit=0.1) + BitCountingGroupList(max_value=3.2, unit=0.1, group_list=[BitCountingGroup(run_list= + [2.1], max_value=3.2, unit=0.1, comment='normal', prev_avg=None, stats=AvgStdevStats + (size=1, avg=2.1, stdev=0.0), cached_bits=6.044394119358453), BitCountingGroup(run_l + ist=[3.1, 3.2], max_value=3.2, unit=0.1, comment='progression', prev_avg=2.1, stats= + AvgStdevStats(size=2, avg=3.1500000000000004, stdev=0.050000000000000044), cached_bi + ts=10.215241265313393)], bits_except_last=6.044394119358453) Change log ---------- -TODO: Move into separate file? +0.4.2: Should no longer divide by zero on empty inputs. + +0.4.1: Fixed bug of not penalizing large stdev enough (at all for size 2 stats). + +0.4.0: Added "unit" and "sbps" parameters so information content +is reasonable even if sample values are below one. + +0.3.0: Considerable speedup by avoiding unneeded copy. Dataclasses used. +Mostly API compatible, but repr looks different. + +0.2.0: API incompatible changes. Targeted to Python 3 now. 0.1.3: Changed stdev computation to avoid negative variance due to rounding errors. 0.1.2: First version published in PyPI. -.. _PAL: https://wiki.fd.io/view/CSIT/Design_Optimizations#Presentation_and_Analytics_Layer .. _CSIT: https://wiki.fd.io/view/CSIT +.. _CSIT-DASH: https://csit.fd.io +.. _directory: https://gerrit.fd.io/r/gitweb?p=csit.git;a=tree;f=PyPI/jumpavg .. _fd.io: https://fd.io/ .. _LFN: https://www.linuxfoundation.org/projects/networking/ .. _PyPI: https://pypi.org/ -.. _directory: https://gerrit.fd.io/r/gitweb?p=csit.git;a=tree;f=PyPI/jumpavg;hb=refs/heads/master +.. _trend analysis: https://csit.fd.io/cdocs/methodology/trending/analysis/#trend-analysis diff --git a/PyPI/jumpavg/hints_and_todos.txt b/PyPI/jumpavg/hints_and_todos.txt new file mode 100644 index 0000000000..e829efa921 --- /dev/null +++ b/PyPI/jumpavg/hints_and_todos.txt @@ -0,0 +1,7 @@ +toml hint: https://flit.pypa.io/en/stable/pyproject_toml.html +rst hint: https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html +build hint: https://packaging.python.org/en/latest/tutorials/packaging-projects/ + +TODO: Include simulator and tests. +TODO: Test which Python versions is the code actually compatible with. +TODO: Create a separate webpage for jumpavg library. diff --git a/PyPI/jumpavg/pyproject.toml b/PyPI/jumpavg/pyproject.toml new file mode 100644 index 0000000000..8aa906c4c3 --- /dev/null +++ b/PyPI/jumpavg/pyproject.toml @@ -0,0 +1,28 @@ +[project] +name = "jumpavg" +version = "0.4.2" +description = "Library for locating changes in time series by grouping results." +license = { file = "LICENSE.txt" } +readme = { file = "README.rst", content-type = "text/x-rst" } +requires-python = ">=3.8" +classifiers = [ + "Development Status :: 3 - Alpha", + "Intended Audience :: Science/Research", + "License :: OSI Approved :: Apache Software License", + "Natural Language :: English", + "Operating System :: OS Independent", + "Programming Language :: Python :: 3.8", + "Topic :: Scientific/Engineering :: Information Analysis", +] +keywords = ["progression", "regression", "anomaly detection", "statistics", "bits" ] +authors = [ + { name = "Cisco Systems Inc. and/or its affiliates", email = "csit-dev@lists.fd.io" }, +] +maintainers = [ + { name = "Vratko Polak", email = "vrpolak@cisco.com" }, + { name = "Tibor Frank", email = "tifrank@cisco.com" }, +] + +[project.urls] +"Bug Tracker" = "https://jira.fd.io/projects/CSIT/issues" +"Source" = "https://gerrit.fd.io/r/gitweb?p=csit.git;a=tree;f=PyPI/jumpavg" diff --git a/PyPI/jumpavg/setup.cfg b/PyPI/jumpavg/setup.cfg deleted file mode 100644 index b4abd1bd30..0000000000 --- a/PyPI/jumpavg/setup.cfg +++ /dev/null @@ -1,7 +0,0 @@ -[metadata] -# This includes the license file in the wheel. -license_file = LICENSE.txt - -[bdist_wheel] -# TODO: Make the code work both on Python 2 and 3. -universal=0 diff --git a/PyPI/jumpavg/setup.py b/PyPI/jumpavg/setup.py deleted file mode 100644 index 28ddfcf0b1..0000000000 --- a/PyPI/jumpavg/setup.py +++ /dev/null @@ -1,62 +0,0 @@ -#!/usr/bin/env python3 - -"""A setup module for setuptools. - -See: -https://packaging.python.org/en/latest/distributing.html -""" - -from setuptools import (setup, find_packages) -from os import path -from io import open - -here = path.abspath(path.dirname(__file__)) -with open(path.join(here, u"README.rst"), encoding=u"utf-8") as f: - long_description = f.read() - -setup( - name=u"jumpavg", - version=u"0.2.0", # This is currently the only place listing the version. - description=( - u"Library for locating changes in time series by grouping results." - ), - long_description=long_description, - long_description_content_type=u"text/x-rst", - # TODO: Create a separate webpage for jumpavg library. - url=( - u"https://gerrit.fd.io/r/gitweb?p=csit.git;a=tree;f=PyPI/jumpavg" - u";hb=refs/heads/master" - ), - author=u"Cisco Systems Inc. and/or its affiliates", - author_email=u"csit-dev@lists.fd.io", - classifiers=[ - u"Development Status :: 3 - Alpha", - u"Intended Audience :: Science/Research", - # Pick your license as you wish - u"License :: OSI Approved :: Apache Software License", - u"Natural Language :: English", - # TODO: Test which Python versions is the code compatible with. - u"Programming Language :: Python :: 2.7", - u"Topic :: Scientific/Engineering :: Information Analysis" - ], - keywords=u"progression regression anomaly detection statistics bits", - packages=find_packages(exclude=[]), - python_requires="~=3.6", - install_requires=[], - # TODO: Include simulator and tests. - extras_require={ - }, - package_data={ - }, - entry_points={ - u"console_scripts": [ - ], - }, - project_urls={ - u"Bug Reports": u"https://jira.fd.io/projects/CSIT/issues", - u"Source": ( - u"https://gerrit.fd.io/r/gitweb?p=csit.git;a=tree;f=PyPI/jumpavg" - u";hb=refs/heads/master" - ), - }, -) |