Package: random-test-tool
Random Test Tool (RTT)Random Test Tool(also referedRTT) is a Python script designed fortesting the randomnessof sequences ofintegersorbits. RTT serves the purpose ofevaluating random number generators.This project was primarily motivated by the following objectives:Evaluate series of integers: RTT allows the assessment of series of integers generated by programs based on generators or directly by generators.Facilitate random outputs controls during security audits: RTT provides a structured set of instructions and assessment outputs to enhance the interpretation of statistical results obtained during security audits.Simplify manipulation of test inputs, tests themselves and test outputs: The tool offers an easy-to-use Python implementation, enabling users to manipulate test inputs, outputs, and tests effortlessly.InstallationCompatibilityRandom Test Toolruns in Python 3!It has minimal dependencies, all of which can be installed with the following commands below.Install through package managerAvailable here:https://pypi.org/project/random-test-tool/pipinstallrandom-test-toolInstall through repositorygitclonehttps://github.com/xmco/random-test-toolcdrandom-test-tool
pipinstall-rrequirements.txtUsageRunning Random Test ToolRandom Test Toolcan be executed using the following commands:pythonrandom_test_tool.py-i<file_path>
pythonrandom_test_tool.py-d<dir_path>For example:pythonrandom_test_tool.py-irandom_generator_samples/python_random_integer/20230816-105301_RANDOM_NUMBERS.txtRandom Test Toolsupports three input formats (within20230816-105301_RANDOM_NUMBERS.txt):"bitstring" series, i.e., a sequence of 0s and 1s:01010111010011001...list of integersstarting at 0 or 1 separated by commas, spaces, semicolons or line breaks:25
12
1
4"bytestring" series, a sequence of bytesRandom Test Toolis capable of testingmultiple files in a row:pythonrandom_test_tool.py-itest_file_1.txttest_file_2.txtAdditionally, it can testall files within a directory:pythonrandom_test_tool.py-dtest_filesOutputsBy default,Random Test Toolreturns resultsin the terminal.You can use the-ooption to specifya return fileorgenerate graphs.Other optionsFor a comprehensive understanding of available options, use the following command:pythonrandom_test_tool.py-hScripttestingtherandomnessofaserieofintegersbitsviastatisticalstatistical_tests.

optionalarguments:-h,--helpshowthishelpmessageandexit-iINPUT_FILES[INPUT_FILES...],--input_filesINPUT_FILES[INPUT_FILES...]Listoffilestotest.-dINPUT_DIR,--input_dirINPUT_DIRInputdirectory,statistical_testswillbelaunchedoneachfile.-o{terminal,file,graph,all},--output{terminal,file,graph,all}Outputreportoptions.-j{1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23,24,25,26,27,28,29,30,31},--n_cores{1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23,24,25,26,27,28,29,30,31}Numberofprocessesused,1bydefault,maximum31-t[STATISTICAL_TESTS...],--test[STATISTICAL_TESTS...]Specifieswhichstatistical_teststolaunch.Bydefaultallstatistical_testsarelaunched.-dt{int,bits,bytes},--data_type{int,bits,bytes}Usedtoselectdatatypeofsample,bydefaultinteger(int)-s{\n,,,,;},--separator{\n,,,,;}Separatorusedforintegerfiles.-ll{ALL,DEBUG,INFO,WARN,ERROR,FATAL,OFF,TRACE},--log_level{ALL,DEBUG,INFO,WARN,ERROR,FATAL,OFF,TRACE}Loglevel(default:INFO).Interpretation of the generated resultsThe tests in this tool calculate ap-value.Thep-valuerepresents the probability of obtaining a distribution at least as extreme as that observed.We compare thisp-valueto athreshold(0.01). If thep-valueis lower than this threshold, it implies that the probability of the observed behavior occurring by chance1 - 0.01(99%).For this example (p-value<0.01), a perfectly random sample is expected to fail this test only1%of the time.To account for this behavior, therecommended use of Random Test Toolis:Run it on multiple samplesfrom the same source;consider a test to failif it fails on a sufficient number of samplescompared to the expected number (1% of samples in the example).For example, if we run the tests on100samples and thebinary ranktest fails12times, as12%>1%(threshold of 0.01), we can consider that the source fails the test in question.Conversely, if there are only2failures out of100, the test would be considered a success.Comparison withDieharder,NIST Test SuiteandTestU01The primary motivation for implementing thisRandom Test Toolwas to provide to the community a toolhighly user friendly,easy to manipulate, capable of deliveringclear and explicit results data, requiring minimal configuration.While there are, of course,other tools that implement statistical tests:Diehard(mainly inCandFortranlanguages)NIST Statistical Test Suite(mainly inClanguage)TestU01(mainly inClanguage)Implemented statistical tests comparisonThe table belowlists the implemented statistical tests by Tool.Statistical testDiehardNIST Test SuiteDiharderTestU01Random Test ToolMonobit (Chi2)XXXXXXXXXXFrequency in blockXXXXXXXXRun TestXXXXXXXXXXLongest run of OnesXXXXXXBinary RankXXXXXXXXXXDFTXXXXXXXXNon-overlapping template matchingXXXXXXXXOverlapping template matchingXXXXXXXXMaurer testXXXXXXXXLempel-ZivXXXXXXLinear ComplexityXXXXXXXXSerialXXXXXXXXApproximate entropyXXXXXXCumulative SumsXXXXXXRandom excursionsXXXXXXXXBirthday SpacingXXXXXX5-PermutationXXXXXXOPSO/OQSOXXXXXXDNAXXXXXXParking LotXXXXXXMinimum DistanceXXXXXX3-D SpheresXXXXXXCrapsXXXXXXSqueezeXXXXXXOther "Crush Tests"  (multiple tests)XXOther "BigCrush" tests (multiple tests)XXIt is important to note thatTestU01implements three test batteries:SmallCrush,Crush, andBigCrush. Due to the substantial number of tests within these batteries, not all of them are listed in the above table.From a purely statistical perspective,TestU01is currentlythe most comprehensive test suite available.Usage comparisonThe table below provides a comparison of the previously discussed tools, focusing oncriteriaandfeatureschosen byauditors(from an audit perspective rather than a statistical one).The aim of this comparison is tohelp one user to identify the most relevant tool to pickbased on theusers' needs.ThemeControlDiharderNIST Test SuiteTestU01Random Test ToolEase of installationVia native operating system package managerXXOOO"Via non-native package managerOOOXX (pip)"Via distributed executableOOOO"Via code compilationXXXXXXXX"Simple configuration (no/few non-standard installation tasks)XXXXOXXSharing / TransparencyOpen-source toolXXXXXXXXDocumentationQuality of installation documentationXXOXXX"Quality of "quick start" / "out-of-the-box" usage documentationXOOXX"Documentation usability quality (ease of search and presentation of topics)XOXX"Quality of mathematical documentation (precise description of statistical tests)XXXXOEase of useOverall ease of use / intuitivenessXXXXXX"Automatable (e.g., no interactivity required)XXOXXXXInputs/OutputsInputs: ASCII binaryXXXXXXX"Inputs: Raw binary (files)XXXXXXX"Inputs: Floating numbers [0; 1]OOXXO"Inputs: Integers / Range of integersOOOXX"Outputs: Results within the terminalXXXXXXXX"Outputs: Structured outputsXXXXXXX"Outputs: Interpreted statistical resultsXXOXXXX"Outputs: Measurement and numerical results returnedXXXXXXXRelevance of statistical testsCompleteness of tests algorithms and precision of the configurationXXXXXTable captionColorQualificationONonexistent / Difficult to identify / ComplexXPartially addressedXXComplete / AdequatePlease note that the provided qualification representsa subjective perspectivebased onfew hours of usage/researchfor each tool, within the context ofrandom-related technical audits.It's important to highlight that no performance comparison was conducted between the toolsContribute to this project!Feedback, contributions and ideas are very Welcome !Need some feature or encountering a bug?Please open anissueand describe the encountered bug and or share any awesome ideas you may have related to theRandom Test Toolproject.Steps for submitting codeForkthe current repository.Write your feature. Please follow-up thePEP 8 coding style.Send a GitHub Pull Request on the develop branch. Contributions will be merged after a code review. Branches will be moved to main when required.High level TodolistImplement, enhance and complete unit-tests (based on the standard)Implement an export feature including results and figures (HTML and/or Markdown)Integrate additional statistical tests (starting with NIST)Related workFrench blog postsDes dés aux données : de l'importance des nombres aléatoires (partie 1/2)Des dés aux données : de l'importance des nombres aléatoires (partie 2/2)English blog postsWe intend to translate both of the above blog posts into English in the near future once our English blog is available .