Merge pull request #1 from Provisdom/kwill/docs

add docs

Author: kennyjwilli

bin/kaocha

@@ -0,0 +1,3 @@
+#!/usr/bin/env bash
+
+clojure -M:test:test-clj-runner "$@"

deps.edn

@@ -4,16 +4,15 @@
                                              :sha     "401e177f3a4d806dffe54379f07ad0a02632eb9a"}
            provisdom/utility-belt           {:git/url "https://github.com/Provisdom/utility-belt.git"
                                              :sha     "a85f733d736727c458a6cd7909f8de482883b9fe"}}
- :aliases {:dev         {:extra-paths ["siderail"]}
+ :aliases {:dev             {:extra-paths ["siderail"]}
            :local           {:override-deps {provisdom/math         {:local/root "../math"}
                                              provisdom/utility-belt {:local/root "../utility-belt"}}}
-           :test        {:extra-paths ["test" "siderail"]
-                         :extra-deps  {com.cognitect/transcriptor {:mvn/version "0.1.5"}
-                                       criterium/criterium        {:mvn/version "0.4.6"}
-                                       orchestra/orchestra        {:mvn/version "2021.01.01-1"}
-                                       org.clojure/test.check     {:mvn/version "1.1.1"}
-                                       provisdom/test             {:git/url "https://github.com/Provisdom/test.git"
-                                                                   :sha     "f62afc093223dff1830a0142bd076ab89cbdef6c"}}}
-           :test-runner {:extra-deps {lambdaisland/kaocha           {:mvn/version "1.91.1392"}
-                                      lambdaisland/kaocha-junit-xml {:mvn/version "1.17.101"}}
-                         :main-opts  ["-m" "kaocha.runner"]}}}
+           :test            {:extra-paths ["test" "siderail"]
+                             :extra-deps  {criterium/criterium        {:mvn/version "0.4.6"}
+                                           orchestra/orchestra        {:mvn/version "2021.01.01-1"}
+                                           org.clojure/test.check     {:mvn/version "1.1.1"}
+                                           provisdom/test             {:git/url "https://github.com/Provisdom/test.git"
+                                                                       :sha     "f62afc093223dff1830a0142bd076ab89cbdef6c"}}}
+           :test-clj-runner {:extra-deps {lambdaisland/kaocha           {:mvn/version "1.91.1392"}
+                                          lambdaisland/kaocha-junit-xml {:mvn/version "1.17.101"}}
+                             :main-opts  ["-m" "kaocha.runner"]}}}

src/data_readers.clj

@@ -0,0 +1,2 @@
+{apache-math/vector provisdom.apache-math.apache-vector/apache-vector
+ apache-math/matrix provisdom.apache-math.apache-matrix/->apache-matrix}

src/provisdom/apache_math/alternative_random.clj

@@ -1,4 +1,14 @@
 (ns provisdom.apache-math.alternative-random
+  "Alternative random number generators from Apache Commons Math.
+  
+  Provides specialized random number generators beyond basic uniform random:
+  - Quasi-random sequences with better coverage (Sobol sequences)
+  - Cryptographically secure random numbers (ISAAC)
+  - Fast, high-quality pseudorandom numbers (Mersenne Twister)
+  
+  Example usage:
+    (def quasi-seq (quasi-rnd-vector-lazy 2))
+    (take 3 quasi-seq) ;=> [[0.0 0.0] [0.5 0.5] [0.75 0.25]]"
   (:require
     [clojure.spec.alpha :as s]
     [clojure.spec.gen.alpha :as gen]
@@ -27,9 +37,20 @@
 
 ;;;APACHE RANDOM NUMBER GENERATORS
 (defn quasi-rng
-  "Creates an Apache RNG with better coverage but more predictable through a
-  lazy sequence of vectors of size `dimensions`. Because of predictability, can
-  be better for a single use simulation."
+  "Creates a Sobol quasi-random number generator for improved uniform coverage.
+  
+  Quasi-random sequences provide better distribution coverage than pseudorandom
+  sequences, making them ideal for Monte Carlo simulations and numerical integration.
+  However, they are more predictable and should not be used for cryptographic purposes.
+  
+  Parameters:
+    dimensions - number of dimensions for each generated vector (1-1000)
+  
+  Returns Apache Commons SobolSequenceGenerator instance.
+  
+  Example:
+    (def qrng (quasi-rng 2))
+    (.nextVector qrng) ;=> [0.0 0.0]"
   [dimensions]
   (SobolSequenceGenerator. ^long dimensions))
 
@@ -38,9 +59,20 @@
   :ret ::apache-rng)
 
 (defn quasi-rnd-vector-lazy
-  "Better coverage but more predictable through a lazy sequence of vectors of
-  size `dimensions`. Because of predictability, can be better for a single use
-  simulation."
+  "Returns lazy sequence of quasi-random vectors with improved coverage.
+  
+  Generates an infinite lazy sequence of vectors using Sobol quasi-random sequences.
+  Each vector contains `dimensions` numbers in [0,1). Provides better uniform
+  coverage than pseudorandom sequences, making it superior for Monte Carlo methods.
+  
+  Parameters:
+    dimensions - size of each vector (1-1000)
+  
+  Returns lazy sequence of vectors with quasi-random numbers.
+  
+  Example:
+    (take 3 (quasi-rnd-vector-lazy 2))
+    ;=> [[0.0 0.0] [0.5 0.5] [0.75 0.25]]"
   [dimensions]
   (let [qr (quasi-rng dimensions)]
     (repeatedly #(vec (.nextVector ^SobolSequenceGenerator qr)))))
@@ -50,8 +82,20 @@
   :ret (s/every ::rnd-vector))
 
 (defn secure-rng
-  "Creates an Apache RNG that is less predictable but slower RNG than Mersenne
-  Twister."
+  "Creates cryptographically secure random number generator using ISAAC algorithm.
+  
+  ISAAC (Indirection, Shift, Accumulate, Add, and Count) provides cryptographically
+  secure random numbers suitable for security applications. Slower than Mersenne
+  Twister but much less predictable.
+  
+  Parameters:
+    seed - long integer seed for reproducible sequences
+  
+  Returns Apache Commons ISAACRandom instance.
+  
+  Example:
+    (def secure-gen (secure-rng 12345))
+    (.nextDouble secure-gen) ;=> 0.26673862796330083"
   [seed]
   (ISAACRandom. ^long seed))
 
@@ -60,7 +104,20 @@
   :ret ::apache-rng)
 
 (defn secure-rnd-lazy
-  "A less predictable but slower rnd-lazy than Mersenne Twister."
+  "Returns lazy sequence of cryptographically secure random numbers.
+  
+  Generates an infinite lazy sequence of random doubles in [0,1) using the ISAAC
+  algorithm. Provides cryptographic security but at the cost of performance.
+  Each call creates a new generator instance.
+  
+  Parameters:
+    seed - long integer seed for reproducible sequences
+  
+  Returns lazy sequence of secure random doubles.
+  
+  Example:
+    (take 5 (secure-rnd-lazy 42))
+    ;=> (0.123... 0.456... 0.789...)"
   [seed]
   (repeatedly #(.nextDouble ^ISAACRandom (secure-rng seed))))
 
@@ -69,7 +126,20 @@
   :ret ::rnd-lazy)
 
 (defn mersenne-rng
-  "Creates an Apache RNG using `seed`."
+  "Creates Mersenne Twister random number generator.
+  
+  Mersenne Twister is a fast, high-quality pseudorandom number generator with
+  excellent statistical properties and a very long period (2^19937-1). Suitable
+  for most simulation work but not cryptographically secure.
+  
+  Parameters:
+    seed - long integer seed for reproducible sequences
+  
+  Returns Apache Commons MersenneTwister instance.
+  
+  Example:
+    (def mt-gen (mersenne-rng 12345))
+    (.nextDouble mt-gen) ;=> 0.8335762378570932"
   [seed]
   (MersenneTwister. ^long seed))
 
@@ -78,7 +148,20 @@
   :ret ::apache-rng)
 
 (defn mersenne-rnd-lazy
-  "Returns rnd-lazy using `seed`."
+  "Returns lazy sequence of high-quality pseudorandom numbers.
+  
+  Generates an infinite lazy sequence of random doubles in [0,1) using the
+  Mersenne Twister algorithm. Provides excellent statistical properties and
+  performance for most simulation needs. Each call creates a new generator instance.
+  
+  Parameters:
+    seed - long integer seed for reproducible sequences
+  
+  Returns lazy sequence of pseudorandom doubles.
+  
+  Example:
+    (take 5 (mersenne-rnd-lazy 42))
+    ;=> (0.833... 0.150... 0.271...)"
   [seed]
   (repeatedly #(.nextDouble ^MersenneTwister (mersenne-rng seed))))