libdieharder(3)

💖 libdieharder — like, the whole manual but make it make sense 💖

okay bestie, sit down, grab a boba, because we're talking about libdieharder — that's the Library Functions Manual page for the C library, and it's a whole vibe. ✨

🎀 NAME 🎀

libdieharder — a testing and benchmarking library for random number generators. yes literally. it bullies your RNG until it confesses. 💅

🌸 SYNOPSIS 🌸

#include dieharder.h

void run_user_template()
{

Test **user_template_test;
/*
 * Create the test
 */
user_template_test =
create_test(&user_template_dtest,tsamples,psamples,&user_template);

/*
 * Set any GLOBAL data used by the test.
 */
user_template_lag = (int)x_user;

/*
 * Show the standard test header
 */
show_test_header(&user_template_dtest,user_template_test);

/*
 * Call the test
 */
std_test(&user_template_dtest,user_template_test);

/*
 * This almost certainly belongs in the show_test_results section,
 * possibly with additional conditionals rejecting test results
involving
 * rewinds, period.
 */
if(strncmp(
  printf( # %u rands were used in this test0,file_input_get_rtot(rng));"
  printf( # The file %s was rewound %u
times0,gsl_rng_name(rng),file_input_get_rewind_cnt(rng));"
}

/*
 * Show standard test results
 */ .
show_test_results(&user_template_dtest,user_template_test);

}

no I did not clean that up, it's verbatim, bestie, that's the whole point 🫶

🦋 DESCRIPTION 🦋

libdieharder — say it with me. 🎤

The libdieharder library hands your user interface programs an API so they can call dieharder tests. There are commands for creating tests, initializing the tests, and running the tests. And showing the results? That's on the UI, bestie. that's your job. 💅

libdieharder also wraps certain additional random number generators so they can be tested too. It can be default test all the random number generators in the Gnu Scientific Library plus these extra generators — and yes, those include "generators" for reading in numbers from a file. not me being flexible 💀

libdieharder is extensible. It's genuinely easy to add more test "objects" or random number generators by using the existing sources as templates. plug and play, icon behavior. 🔥

The API will be documented in more detail as the project approaches completion. In the meantime — and this is the important part — it is strongly recommended that users wishing to call the library use the source of the dieharder tty UI as a template and as the list of all currently supported objects, because that's the primary libdieharder debugging vehicle and the current "standard" application of the library. 🧚

👑 PUBLICATION RULES 👑

libdieharder is entirely original code and can be modified and used at will by any user, provided that:

• a) The original copyright notices are maintained, and the source — including all modifications — is made publically available at the time of any derived publication. This is open source software according to the precepts and spirit of the Gnu Public License. See the accompanying file COPYING, which also must accompany any redistribution. 📜
• b) The author of the code (Robert G. Brown) is appropriately acknowledged and referenced in any derived publication. It is strongly suggested that George Marsaglia and the Diehard suite and the various authors of the Statistical Test Suite be similarly acknowledged, although this suite shares no actual code with these random number test suites. 🙏
• c) Full responsibility for the accuracy, suitability, and effectiveness of the program rests with the users and/or modifiers. As is clearly stated in the accompanying copyright.h:

THE COPYRIGHT HOLDERS DISCLAIM ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL THE COPYRIGHT HOLDERS BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

⚠️ like. fr fr. no warranty. at all. read it twice. 💀

🌈 ACKNOWLEDGEMENTS 🌈

The author of this suite gratefully acknowledges George Marsaglia (the author of the diehard test suite) and the various authors of NIST Special Publication 800-22 (which describes the Statistical Test Suite for testing pseudorandom number generators for cryptographic applications), for excellent descriptions of the tests therein. Those descriptions enabled this suite to be developed with a clean copyright, licensable under the GPL. 🫶

The author also wishes to reiterate that the academic correctness and accuracy of the implementation of these tests is his sole responsibility and not that of the authors of the Diehard or STS suites. This is especially true where he has seen fit to modify those tests from their strict original descriptions. 🎯

💜 COPYRIGHT 💜

GPL 2b; see the file COPYING that accompanies the source of this program. This is the "standard Gnu General Public License version 2 or any later version", with the one minor (humorous) "Beverage" modification listed below. Note that this modification is probably not legally defensible and can be followed really pretty much according to the honor rule. 🙈

As to my personal preferences in beverages: red wine is great, beer is delightful, and Coca Cola or coffee or tea or even milk acceptable to those who for religious or personal reasons wish to avoid stressing my liver. 🍷🍺🥤☕🍵🥛

🍓 The Beverage Modification to the GPL 🍓

Any satisfied user of this software shall, upon meeting the primary author(s) of this software for the first time under the appropriate circumstances, offer to buy him or her or them a beverage. This beverage may or may not be alcoholic, depending on the personal ethical and moral views of the offerer. The beverage cost need not exceed one U.S. dollar (although it certainly may at the whim of the offerer :-) and may be accepted or declined with no further obligation on the part of the offerer. It is not necessary to repeat the offer after the first meeting, but it can't hurt... 😌

🌟 main character energy: libdieharder, Library Functions Manual, page libdieharder(3) — Copyright 2006 Robert G. Brown. bestie, go buy that man a beverage. 💖🎀