QRNG client library (scientific edition)

v1.1.1.

Client library for the quantum random number API at qrng.av.it.pt, implemented in parallel across four languages: Python, Julia, MATLAB, and C/C++. All five implementations (C and C++ share one core) expose the same construction options, the same methods, and the same observable behavior -- differing only in each language's own idiom for expressing them.

This is the scientific/statistical edition: it returns raw quantum entropy exactly as served, with no cryptographic post-processing (no DRBG, no conditioning). It's intended for simulation, sampling, and other scientific/statistical use -- do not use it to generate cryptographic keys, nonces, tokens, or other security-sensitive material. A separate cryptographically-secure edition (NIST SP 800-90A/C conformant-by-design DRBG output) will be published shortly.

Directory structure

python/qrng.py            Python implementation
python/qrng_validate.py   its validation/conformance test suite

julia/qrng.jl              Julia implementation
julia/qrng_validate.jl     its validation/conformance test suite

matlab/qrng.m               MATLAB implementation
matlab/qrng_validate.m      its validation/conformance test suite

c/qrng.h, c/qrng.c          shared C11 core (libcurl + cJSON + GMP)
c/qrng.hpp                  C++17/20 RAII wrapper over the same core (header-only)
c/qrng_validate.c           C validation/conformance test suite
c/qrng_validate.cpp         C++ validation/conformance test suite
c/CMakeLists.txt            builds the core + both validate suites
c/README.md                 C/C++-specific build & usage instructions
c/build/                    prebuilt validate-suite binaries + the reusable qrng_core library
c/etc/                      TLS certificate bundle used by c/build/'s binaries (keep alongside build/)
c/install/                  clean include/ + lib/ (+ bin/) tree for use in your own project

Each implementation file carries its own full API reference at the top (a module docstring in Python, a doc-comment block in Julia, MATLAB help text, and a header comment in qrng.h/qrng.hpp) -- read that for the complete parameter list, return-value shapes, and worked examples. This file only covers what's common across all of them.

Each qrng_validate.* file is a validation/conformance test suite for its own implementation -- it checks the client's own correctness (construction, buffer/refill logic, rendering, error handling) against the real API. It is not a usage demo and not a statistical randomness/entropy-quality test suite.

Common contract

Every language's client follows the same rules:

• Construction never fails loudly. An invalid configuration (bad base, negative bits, etc.) does not raise/throw -- it simply makes every subsequent call return a param-style error status.
• Every method returns (value, status). status is empty/None/ nothing/QRNG_OK on success. On failure it carries a code (one of param, network, http, parse, list_empty, buffer_too_small) and a human-readable message. Nothing is ever thrown, raised, or crashes across the API boundary because of a bad response or a bad argument.
• Same construction options, same names, same defaults, across all five implementations: generator, source, bits, base, nbuff, timeout, wait, max_wait_seconds, allow_oversized, always_array, default_base/default_size/default_fmt, the advanced wire_base/force_wire_base/nbatch, and the optional vmin/vmax construction-time domain restriction (confines every draw to [vmin,vmax], auto-sizing bits from vmax when not given explicitly; random source only).
• Same three read methods: draw formatted values (next/qrng_next), draw the server's raw digit strings (nextStr/qrng_next_str), and pre-fill the entropy buffer ahead of time (fill/qrng_fill). next supports fmt="int"|"str"|"vec"|"float" -- "float" renders a uniform double in [0,1), unavailable with source="prime".
• Bit-exact output. For the same inputs, every implementation slices and renders the identical bits in the identical MSB-first order, with real (never padded) leading zeros. Python is the reference implementation; the other four are verified bit-for-bit against it.
• An internal entropy buffer, refilled from the server as needed, so repeated calls don't each cost a network round-trip.

Where a language's own idiom requires a different return container (e.g. C's tagged union + is_scalar flag vs. Python's bare value/list distinction, or MATLAB's numeric/string/cell arrays), that's a deliberate, documented per-language difference in representation, not in the underlying values or semantics.

Quick start

# Python
from qrng import qrng
q = qrng(bits=32, base=10)
value, status = q.next()

# Julia
using .QRNGClient
q = qrng(bits=32, base=10)
value, status = next(q)

% MATLAB
q = qrng(bits=32, base=10);
[value, status] = q.next();

/* C */
qrng_config_t cfg = qrng_config_default();
cfg.bits = 32; cfg.base = 10;
qrng_t *q; qrng_status_t st;
qrng_init(&cfg, &q, &st);
qrng_value_t val;
qrng_next(q, 1, 0, 0, QRNG_FMT_DEFAULT, &val, &st);

// C++
qrng::qrng q({.bits = 32, .base = 10});
auto [value, status] = q.next();

Running the validation suites

Each suite runs an offline (mocked, deterministic, no network) pass by default, plus a live pass against the real API unless told to skip it:

• Python: py -3 qrng_validate.py (or --offline)
• Julia: julia qrng_validate.jl (or --offline)
• MATLAB: matlab -batch "qrng_validate" (or qrng_validate(true) for live)
• C/C++: ./qrng_validate_c / ./qrng_validate_cpp (or --offline) -- see c/README.md for building from source, or "C/C++: prebuilt binaries" below to run the ones already built.

C/C++: prebuilt binaries and using the library elsewhere

c/build/ contains a ready-to-run Release build (qrng_validate_c.exe, qrng_validate_cpp.exe) with every required runtime DLL alongside it, plus c/etc/ next to it holding the TLS certificate bundle those executables need for live HTTPS calls -- no MSYS2/vcpkg environment, PATH changes, or extra setup needed to run them as-is. Keep c/build/ and c/etc/ together if you move or copy this project.

To use the client library in your own C/C++ project, you don't need to recompile anything -- c/install/ is a ready-made

include/qrng.h, qrng.hpp
lib/libqrng_core.a
bin/  (Windows runtime DLLs + the TLS CA bundle)

tree, produced from this same build via cmake --install. Point your compiler at install/include/install/lib and link -lqrng_core -lcurl -lcjson -lgmp (C) or just #include "qrng.hpp" and link -lgmpxx -lgmp (C++, header-only). Full details, exact commands, and the Windows runtime-DLL/CA-bundle notes are in c/README.md.

TLS trust

Live HTTPS calls rely on standard TLS certificate verification in every language (always on, never disabled) as the sole trust anchor. There is no certificate/key pinning in any language: qrng.av.it.pt serves a Let's Encrypt certificate, which rotates its key on every renewal, so certificate verification -- not a fixed pin -- is the right and only trust mechanism here.

License

This project's own code is licensed under the BSD 2-Clause License -- see LICENSE. The .dll files bundled under c/build/ and c/install/bin/ (curl, cJSON, GMP, OpenSSL, zlib, and their own dependencies) are prebuilt third-party binaries, each covered by its own upstream license, not this project's -- see THIRD_PARTY_LICENSES.md for the full list of bundled libraries, their versions/licenses, and the dynamic-linking compliance notes (including the LGPL/GPL-with-runtime-exception ones).