From e049493d2819d46768a7b48685d67f4afa339203 Mon Sep 17 00:00:00 2001
From: copilot-swe-agent[bot]
Date: Fri, 20 Feb 2026 06:47:00 +0000
Subject: Add comprehensive README documentation for the C implementation

Co-authored-by: 8e8m <248551607+8e8m@users.noreply.github.com>
---
 source/README.md | 95 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 95 insertions(+)
 create mode 100644 source/README.md

(limited to 'source')

diff --git a/source/README.md b/source/README.md
new file mode 100644
index 0000000..c1f8d7f
--- /dev/null
+++ b/source/README.md
@@ -0,0 +1,95 @@
+# PhotonSpinRandom C Implementation
+
+This directory contains a C implementation of the PhotonSpinRandom generator, originally written in C# by Will Stafford Parsons and distributed in the [unity-helpers](https://github.com/wallstop/unity-helpers) repository.
+
+## Files
+
+- **photon_spin_random.h** - Header file with type definitions and function declarations
+- **photon_spin_random.c** - Implementation of the PhotonSpin32 random number generator
+- **Makefile** - Build configuration for easy compilation
+- **donut.c** - ASCII art donut (not a source file, QA artifact)
+
+## About PhotonSpinRandom
+
+PhotonSpin32 is a 20-word ring-buffer random number generator inspired by SHISHUA, designed for high throughput and large period (~2^512). It excels at:
+
+- Generating large streams of high-quality random numbers
+- Heavy simulation workloads requiring excellent distribution
+- Deterministic state capture and restoration
+
+**Not suitable for**: Cryptographic or security-sensitive applications.
+
+## Building
+
+### Using Make
+
+```bash
+make        # Build the test program
+make test   # Build and run tests
+make clean  # Clean build artifacts
+```
+
+### Using @BAKE
+
+The source file includes a `@BAKE` statement for use with the [bake](https://github.com/8e8m/bake) build tool:
+
+```bash
+# The @BAKE command is embedded in photon_spin_random.c:
+# @BAKE cc -O2 -Wall -Wextra -std=c99 -o photon_spin_random photon_spin_random.c -lm @STOP
+```
+
+To use it with bake, simply run bake in this directory.
+
+### Manual Compilation
+
+```bash
+# For testing with built-in test harness:
+cc -O2 -Wall -Wextra -std=c99 -DPHOTON_SPIN_TEST_MAIN -o photon_spin_random photon_spin_random.c -lm
+
+# As a library (without test main):
+cc -O2 -Wall -Wextra -std=c99 -c photon_spin_random.c
+```
+
+## Usage Example
+
+```c
+#include "photon_spin_random.h"
+
+int main(void) {
+    photon_spin_random_t rng;
+    
+    // Initialize with a seed
+    photon_spin_init(&rng, 42);
+    
+    // Generate random numbers
+    uint32_t rand_uint = photon_spin_next_uint(&rng);
+    float rand_float = photon_spin_next_float(&rng);  // [0, 1)
+    double rand_double = photon_spin_next_double(&rng);  // [0, 1)
+    int32_t rand_range = photon_spin_next_int_range(&rng, 0, 100);  // [0, 100)
+    
+    return 0;
+}
+```
+
+## API Reference
+
+### Initialization Functions
+
+- `photon_spin_init(rng, seed)` - Initialize with a single 32-bit seed
+- `photon_spin_init_scalars(rng, seed_a, seed_b, seed_c)` - Initialize with three 32-bit seeds
+- `photon_spin_init_ulongs(rng, seed0, seed1)` - Initialize with two 64-bit seeds
+
+### Generation Functions
+
+- `photon_spin_next_uint(rng)` - Generate next 32-bit unsigned integer
+- `photon_spin_next_float(rng)` - Generate next float in [0, 1)
+- `photon_spin_next_double(rng)` - Generate next double in [0, 1)
+- `photon_spin_next_int_range(rng, min, max)` - Generate integer in [min, max)
+
+## License
+
+MIT License - Copyright (c) 2025 wallstop
+
+Original C# implementation from: https://github.com/wallstop/unity-helpers
+
+Converted to C for the librandom project.
-- 
cgit v1.2.3