Improve the quality of the codebase

.clang-format

@@ -1,4 +1,4 @@
-# SPDX-FileCopyrightText: 2008-2023 HPDCS Group <rootsim@googlegroups.com>
+# SPDX-FileCopyrightText: 2008-2026 HPCS Group <rootsim@googlegroups.com>
 # SPDX-License-Identifier: CC0-1.0
 BasedOnStyle: LLVM
 Language: Cpp

.editorconfig

@@ -1,4 +1,4 @@
-# SPDX-FileCopyrightText: 2008-2023 HPDCS Group <rootsim@googlegroups.com>
+# SPDX-FileCopyrightText: 2008-2026 HPCS Group <rootsim@googlegroups.com>
 # SPDX-License-Identifier: CC0-1.0
 
 root = true

.github/workflows/build_and_test.yml

@@ -17,14 +17,14 @@ jobs:
             compiler: gcc
         include:
           - os: macos-latest
-            compiler: gcc-11
+            compiler: gcc-14
             type: Debug
           - os: macos-latest
-            compiler: gcc-11
+            compiler: gcc-14
             type: Release
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v3
+        uses: actions/checkout@v6
       - name: Initialize Environment
         uses: ROOT-Sim/ci-actions/init@v1.2
       - name: Build & Test

.github/workflows/reuse_check.yml

@@ -7,7 +7,7 @@ jobs:
   reuse_check:
     runs-on: ubuntu-latest
     steps:
-      - name: Checkpout repository
-        uses: actions/checkout@v3
+      - name: Checkout repository
+        uses: actions/checkout@v6
       - name: REUSE check
-        uses: ROOT-Sim/ci-actions/reuse-check@v1.2
+        uses: ROOT-Sim/ci-actions/reuse-check@v1.4

.gitignore

@@ -1,4 +1,4 @@
-# SPDX-FileCopyrightText: 2008-2023 HPDCS Group <rootsim@googlegroups.com>
+# SPDX-FileCopyrightText: 2008-2026 HPCS Group <rootsim@googlegroups.com>
 # SPDX-License-Identifier: CC0-1.0
 
 # Prerequisites

CMakeLists.txt

@@ -1,4 +1,4 @@
-# SPDX-FileCopyrightText: 2008-2023 HPDCS Group <rootsim@googlegroups.com>
+# SPDX-FileCopyrightText: 2008-2026 HPCS Group <rootsim@googlegroups.com>
 # SPDX-License-Identifier: GPL-3.0-only
 
 cmake_minimum_required(VERSION 3.12)

README.md

@@ -0,0 +1,48 @@
+# ROOT-Sim Random Number Generators Library
+
+[![Continuous Integration](https://github.com/ROOT-Sim/random-number-generators/actions/workflows/build_and_test.yml/badge.svg)](https://github.com/ROOT-Sim/random-number-generators/actions/workflows/build_and_test.yml)
+[![GitHub issues](https://img.shields.io/github/issues/ROOT-Sim/random-number-generators)](https://github.com/ROOT-Sim/random-number-generators/issues)
+[![REUSE status](https://api.reuse.software/badge/github.com/ROOT-Sim/random-number-generators)](https://api.reuse.software/info/github.com/ROOT-Sim/random-number-generators)
+
+*Brought to you by the [High Performance Computing & Simulation (HPCS)](https://hpcs.ing.uniroma2.it/) Research Group*
+
+----------------------------------------------------------------------------------------
+
+## Overview
+
+The ROOT-Sim Random Number Generators (RNG) Library provides a collection of Piece-Wise Deterministic Random Number Generators designed for use in simulation models. It serves as a core component for the [ROOT-Sim](https://github.com/ROOT-Sim/cROOT-Sim) framework, delivering robust, high-performance, and reproducible random streams for Logical Processes.
+
+## Features
+
+This library supports multiple common statistical distributions and relies on a fast underlying Pseudo-Random Number Generator (PRNG), such as Xoroshiro, to ensure performance and statistical quality.
+
+Available distributions and utilities include:
+
+*   **Uniform Distributions:** Standard continuous random numbers and discrete 64-bit unsigned integers.
+*   **Normal Distributions:** Standard normally distributed random values.
+*   **Exponential Distributions:** Exponentially distributed random numbers for inter-arrival times.
+*   **Gamma Distributions:** Support for the Gamma distribution shape parameters.
+*   **Poisson Distributions:** Discrete probability distributions for event occurrences.
+*   **Zipf Distributions:** Skewed distributions often used to model popularity or access patterns.
+*   **Range Selections:** Uniform and non-uniform selections across defined minimum and maximum bounds.
+
+## Integration
+
+To utilize the random number generation facilities in your model, include the main header:
+
+```c
+#include <ROOT-Sim/random.h>
+```
+
+This project relies on CMake and requires a C11-compliant compiler. To build and link the library, follow the standard CMake build process:
+
+```bash
+mkdir build
+cd build
+cmake ..
+make
+```
+
+## License
+
+This project is licensed under the GPL-3.0-only license, with some components utilizing the CC0-1.0 license. See the `LICENSES` directory or the REUSE configuration for more precise details regarding file-level licensing.

REUSE.toml

@@ -0,0 +1,46 @@
+version = 1
+SPDX-PackageName = "ROOT-Sim"
+SPDX-PackageSupplier = "HPCS Group <rootsim@googlegroups.com>"
+SPDX-PackageDownloadLocation = "https://github.com/ROOT-Sim/topology"
+
+[[annotations]]
+path = "docs/**"
+precedence = "aggregate"
+SPDX-FileCopyrightText = "2008-2026 HPCS Group <rootsim@googlegroups.com>"
+SPDX-License-Identifier = "CC0-1.0"
+
+[[annotations]]
+path = "docs/img/**"
+precedence = "aggregate"
+SPDX-FileCopyrightText = "2008-2026 HPCS Group <rootsim@googlegroups.com>"
+SPDX-License-Identifier = "CC-BY-SA-4.0"
+
+[[annotations]]
+path = ".github/**"
+precedence = "aggregate"
+SPDX-FileCopyrightText = "2008-2026 HPCS Group <rootsim@googlegroups.com>"
+SPDX-License-Identifier = "CC0-1.0"
+
+[[annotations]]
+path = "AUTHORS"
+precedence = "aggregate"
+SPDX-FileCopyrightText = "2008-2026 HPCS Group <rootsim@googlegroups.com>"
+SPDX-License-Identifier = "CC0-1.0"
+
+[[annotations]]
+path = "ChangeLog"
+precedence = "aggregate"
+SPDX-FileCopyrightText = "2008-2026 HPCS Group <rootsim@googlegroups.com>"
+SPDX-License-Identifier = "CC0-1.0"
+
+[[annotations]]
+path = "CODEOWNERS"
+precedence = "aggregate"
+SPDX-FileCopyrightText = "2008-2026 HPCS Group <rootsim@googlegroups.com>"
+SPDX-License-Identifier = "CC0-1.0"
+
+[[annotations]]
+path = "README.md"
+precedence = "aggregate"
+SPDX-FileCopyrightText = "2008-2026 HPCS Group <rootsim@googlegroups.com>"
+SPDX-License-Identifier = "GPL-3.0-only"

src/CMakeLists.txt

@@ -1,12 +1,12 @@
-# SPDX-FileCopyrightText: 2008-2023 HPDCS Group <rootsim@googlegroups.com>
+# SPDX-FileCopyrightText: 2008-2026 HPCS Group <rootsim@googlegroups.com>
 # SPDX-License-Identifier: GPL-3.0-only
 
 if(WIN32)
     set(EXTRA_LIBS ${EXTRA_LIBS} winmm)
 endif()
 
 add_library(rsrng STATIC random.c xxtea.c)
-target_include_directories(rsrng PRIVATE . ./include)
+target_include_directories(rsrng PRIVATE . PUBLIC ./include)
 target_link_libraries(rsrng ${EXTRA_LIBS})
 
 install(DIRECTORY include/ DESTINATION include)

src/include/ROOT-Sim/random.h

@@ -5,7 +5,7 @@
 *
 * Piece-Wise Deterministic Random Number Generators.
 *
-* SPDX-FileCopyrightText: 2008-2023 HPDCS Group <rootsim@googlegroups.com>
+* SPDX-FileCopyrightText: 2008-2026 HPCS Group <rootsim@googlegroups.com>
 * SPDX-License-Identifier: GPL-3.0-only
 */
 #pragma once

src/random.c

@@ -5,7 +5,7 @@
  *
  * Piece-Wise Deterministic Random Number Generators.
  *
- * SPDX-FileCopyrightText: 2008-2023 HPDCS Group <rootsim@googlegroups.com>
+ * SPDX-FileCopyrightText: 2008-2026 HPCS Group <rootsim@googlegroups.com>
  * SPDX-License-Identifier: GPL-3.0-only
  */
 #include <ROOT-Sim/random.h>
@@ -30,10 +30,10 @@ struct timeval {
 #endif /* _TIMEVAL_DEFINED */
 
 int gettimeofday(struct timeval* tp, void* tzp) {
-	DWORD t;
-	t = timeGetTime();
+	(void)tzp;
+	DWORD t = GetTickCount();
 	tp->tv_sec = t / 1000;
-	tp->tv_usec = t % 1000;
+	tp->tv_usec = (t % 1000) * 1000;
 	return 0;
 }
 #elif defined(__unix__) || defined(__unix) || (defined(__APPLE__) && defined(__MACH__))

src/xoroshiro.h

@@ -1,12 +1,14 @@
 /**
- * @file lsrc/xoroshiro.h
+ * @file src/xoroshiro.h
  *
  * @brief Xoroshiro RNG support functions
  *
  * Xoroshiro RNG support functions.
  *
  * SPDX-FileCopyrightText: 2008-2021 D. Blackman and S. Vigna <vigna@acm.org>
  * SPDX-License-Identifier: CC0-1.0
+ * SPDX-FileCopyrightText: 2008-2026 HPCS Group <rootsim@googlegroups.com>
+ * SPDX-License-Identifier: GPL-3.0-only
  */
 #pragma once
 

src/xxtea.c

@@ -6,7 +6,7 @@
  * An implementation of the XXTEA block cipher
  * (code based on "Correction to xtea" by David J. Wheeler and Roger M. Needham)
  *
- * SPDX-FileCopyrightText: 2008-2023 HPDCS Group <rootsim@googlegroups.com>
+ * SPDX-FileCopyrightText: 2008-2026 HPCS Group <rootsim@googlegroups.com>
  * SPDX-License-Identifier: GPL-3.0-only
  */
 #include "xxtea.h"

src/xxtea.h

@@ -5,7 +5,7 @@
  *
  * An implementation of the XXTEA block cipher
  *
- * SPDX-FileCopyrightText: 2008-2023 HPDCS Group <rootsim@googlegroups.com>
+ * SPDX-FileCopyrightText: 2008-2026 HPCS Group <rootsim@googlegroups.com>
  * SPDX-License-Identifier: GPL-3.0-only
  */
 #pragma once

test/CMakeLists.txt

@@ -1,4 +1,4 @@
-# SPDX-FileCopyrightText: 2008-2023 HPDCS Group <rootsim@googlegroups.com>
+# SPDX-FileCopyrightText: 2008-2026 HPCS Group <rootsim@googlegroups.com>
 # SPDX-License-Identifier: GPL-3.0-only
 
 # Retrieve and make available the testing framework
@@ -17,6 +17,3 @@ test_program_link_libraries(numerical rsrng)
 test_program(xxtea xxtea.c)
 test_program_link_libraries(xxtea rsrng)
 
-# TODO: The following is garbage and will be removed soon
-target_include_directories(test_numerical PRIVATE ${CMAKE_SOURCE_DIR}/src/include)
-target_include_directories(test_xxtea PRIVATE ${CMAKE_SOURCE_DIR}/src/include)

test/init.c

@@ -3,7 +3,7 @@
  *
  * @brief Test: initialization of the RNG library
  *
- * SPDX-FileCopyrightText: 2008-2023 HPDCS Group <rootsim@googlegroups.com>
+ * SPDX-FileCopyrightText: 2008-2026 HPCS Group <rootsim@googlegroups.com>
  * SPDX-License-Identifier: GPL-3.0-only
  */
 #include <stdint.h>

test/numerical.c

@@ -3,7 +3,7 @@
  *
  * @brief Test: rollbackable RNG
  *
- * SPDX-FileCopyrightText: 2008-2023 HPDCS Group <rootsim@googlegroups.com>
+ * SPDX-FileCopyrightText: 2008-2026 HPCS Group <rootsim@googlegroups.com>
  * SPDX-License-Identifier: GPL-3.0-only
  */
 #include <test.h>
@@ -120,13 +120,37 @@ static int random_range_test(_unused void *_)
 
 	return passed;
 }
+static int ks_aggregation_test(_unused void *_)
+{
+	int runs = 10000;
+	int failures = 0;
+	for(int i = 0; i < runs; i++) {
+		if(kolmogorov(1000, Random) != 0) {
+			failures++;
+		}
+	}
+
+	/* 
+	 * The KS threshold in kolmogorov() corresponds to alpha = 0.02.
+	 * Over 10,000 independent runs, the expected number of failures is 10000 * 0.02 = 200.
+	 * The standard deviation is sqrt(10000 * 0.02 * 0.98) = 14.
+	 * We accept failures within +/- 4 standard deviations: [144, 256].
+	 * Probability of false positive is practically 0 (< 0.00006).
+	 */
+	test_assert(failures >= 144 && failures <= 256);
+
+	return 0;
+}
 
+extern uint64_t master_seed;
 
 int main(void)
 {
+	master_seed = 42;
 	initialize_stream(0, &ctx);
 
 	test("Kolmogorov-Smirnov test on Random(&ctx)", aux_ks_test, NULL);
+	test("Kolmogorov-Smirnov aggregated rejection rate test", ks_aggregation_test, NULL);
 	test("Functional test on RandomRange()", random_range_test, NULL);
 	test("Functional test on RandomRangeNonUniform()", random_range_non_uniform_test, NULL);
 }

test/random.h

@@ -3,7 +3,7 @@
  *
  * @brief Test: rollbackable RNG
  *
- * SPDX-FileCopyrightText: 2008-2023 HPDCS Group <rootsim@googlegroups.com>
+ * SPDX-FileCopyrightText: 2008-2026 HPCS Group <rootsim@googlegroups.com>
  * SPDX-License-Identifier: GPL-3.0-only
  */
 #pragma once

test/xxtea.c

@@ -3,7 +3,7 @@
  *
  * @brief Test: XXTEA cipher
  *
- * SPDX-FileCopyrightText: 2008-2023 HPDCS Group <rootsim@googlegroups.com>
+ * SPDX-FileCopyrightText: 2008-2026 HPCS Group <rootsim@googlegroups.com>
  * SPDX-License-Identifier: GPL-3.0-only
  */
 #include <test.h>