Small doc updates/reorg (#25)

* [feat] add comptime chcek for float and int values

* [fix,feat] update bernoulli

* [docs] draft of new readme

* [docs] update new readme

* [fix,test] bug fixes and tests added

* [fix,test] new beta implementation w/ tests

* [fix,test] bug fixes and tests added; binomial

* [feat] added cauchy distribution

* [test] updating ci action

* [fix] updating build script

* [fix,test] tests and bug fixes for chi squared

* [test] tests for dirichlet

* [fix,test] tests and new lnPdf for exponential

* [feat,test] new gamma implementation and tests

* [fix,test] fix pmf and tests for geometric

* [fix,test] sumToOne form utils and tests for multinomial

* [fix] switch rng to rand

* [test] adding tests to negative binomial

* [docs] correcting negative binomial header docs

* [docs,test] negative binomial docs fix; tests for normal distr

* [fix,test] fix bugs in poisson sampling and adding tests

* [test] add tests for uniform and discrete uniform

* [fix,feat] bug fixes and new functions

* [feat] add sumToOne check

* [feat] weighted sampling

* [fix,feat] add new distributions to main file

* [fix] mark multivariate normal as unstable

* [feat,draft] RandomEnvironment struct for high-level API

* [misc] scripts for builds/tests

* [feat,draft] adding examples

* [docs,draft] draft of new docs

* [docs,draft] updating readme

* [fix] bug fixes for chi squared, poisson, REnv

* [fix] removing docs build from script

* [docs] adding index files for docs

* [fix] correcting pdf/lnPdf

* [test] adding tests; new dirichlet and multinomial apis

* [test] building examples as part of ci

* [test] add zig latest tests in ci; pdf/pmf to distr files

* [fix] bug in math.pow for generic float types

* [fix] generic pdf and lnPdf fixies for beta distr

* [fix] removing support for f16

* [docs] updating docs to be built from module docstrings

* [docs] build docs for pull requests

* [fix] update example build.zig for 0.13

* [fix] update scripts for 0.13 and new .zig-cache

* [fix] binomial pmf update

* [fix] normal distr pdf/lnPdf corrections

* [test] add pdf tests to RandomEnvironment

* [test] updating ci and gitignore for 0.13

* [docs] restructing docs

README.md

@@ -11,60 +11,11 @@ The instructions below will get you started with integrating `zprob` into your p
 introducing some basic use cases. For more detailed information on the different APIs that `zprob`
 implements, please refer to the [docs site](https://github.com/pblischak/zprob).
 
-## Installation
-
-> **Note:**
-> The current version of `zprob` was developed and tested using v0.13.0 of Zig and is still a work in progress.
-> Using a version of Zig other than 0.13.0 may lead to the code not compiling.
-
-To include `zprob` in your Zig project, you can add it to your `build.zig.zon` file in the
-dependencies section:
-
-```zon
-.{
-    .name = "my_project",
-    .version = "0.1.0",
-    .paths = .{
-        "build.zig",
-        "build.zig.zon",
-        "README.md",
-        "LICENSE",
-        "src",
-    },
-    .dependencies = .{
-        .zprob = {
-            .url = "https://github.com/pblischak/zprob/archive/refs/tags/v0.2.0.tar.gz",
-            .hash = "12200e840921f2199753be06fa57616ae9458bb467c5fde233a851b5556bca539ed0",
-        }
-    },
-}
-```
-
-Then, in the `build.zig` file, add the following lines within the `build` function to include
-`zprob` as a module:
-
-```zig
-pub fn build(b: *std.Build) void {
-    // exe setup...
-
-    const zprob_dep = b.dependency("zprob", .{
-            .target = target,
-            .optimize = optimize,
-    });
-
-    const zprob_module = zprob_dep.module("zprob");
-    exe.root_module.addImport("zprob", zprob_module);
-
-    // additional build steps...
-}
-```
-
-Check out the build files in the [examples/](https://github.com/pblischak/zprob/tree/main/examples)
-folder for some demos of complete sample code projects.
-
 ## Getting Started
 
-Below we show a brief "Hello, World!" program that introduces the `RandomEnvironment` struct, which
+### `RandomEnvironment` API
+
+Below we show a small example program that introduces the `RandomEnvironment` struct, which
 provides a high-level interface for sampling from distributions and calculating probabilities. It
 automatically generates and stores everything needed to begin generating random numbers
 (seed + random generator), and follows the standard Zig convention of initialization with an
@@ -101,6 +52,41 @@ pub fn main() !void {
 }
 ```
 
+To initialize a `RandomEnvironment` with a particular seed, use the `initWithSeed` method:
+
+```zig
+var env = RandomEnvironment.initWithSeed(1234567890, allocator);
+env.deinit();
+```
+
+### Distributions API
+
+While the easiest way to get started using `zprob` is with the `RandomEnvironment` struct,
+for users wanting more fine-grained control over the construction and usage of different probability
+distributions, `zprob` provides a lower level "Distributions API".
+
+```zig
+const std = @import("std");
+const zprob = @import("zprob");
+const Random = std.Random;
+
+pub fn main() !void {
+    // Set up random generator.
+    var prng = Random.DefaultGenerator;
+    var rand = prng.random();
+
+    var beta = zprob.Beta(f64).init(&rand);
+    var binomial = zprob.Binomial(u8, f64).init(&rand);
+
+    var b1: f64 = undefined;
+    var b2: u8 = undefined;
+    for 0..100 |_| {
+        b1 = beta.sample(1.0, 5.0);
+        b2 = binomial.sample(20, b1);
+    }
+}
+```
+
 ## Example Projects
 
 As mentioned briefly above, there are several projects in the
@@ -117,12 +103,6 @@ usage of `zprob` for different applications:
   with different frequencies, are given different stats based on their type, and are placed randomly
   on the level map.
 
-## Low-Level Distributions API
-
-While the easiest way to get started using `zprob` is with the `RandomEnvironment` struct,
-for users wanting more fine-grained control over the construction and usage of different probability
-distributions, `zprob` provides a lower-level "Distributions API".
-
 ## Available Distributions
 
 **Discrete Probability Distributions**
@@ -146,6 +126,59 @@ distributions, `zprob` provides a lower-level "Distributions API".
 [Normal](https://en.wikipedia.org/wiki/Normal_distribution) ::
 [Uniform](https://en.wikipedia.org/wiki/Continuous_uniform_distribution)
 
+## Installation
+
+> [!NOTE]
+> The current version of `zprob` was developed and tested using v0.13.0 of Zig and is still a work in progress.
+> Using a version of Zig other than 0.13.0 may lead to the code not compiling.
+
+To include `zprob` in your Zig project, you can add it to your `build.zig.zon` file in the
+dependencies section:
+
+```zon
+.{
+    .name = "my_project",
+    .version = "0.1.0",
+    .paths = .{
+        "build.zig",
+        "build.zig.zon",
+        "README.md",
+        "LICENSE",
+        "src",
+    },
+    .dependencies = .{
+        // This will link to tagged v0.2.0 release.
+        // Change the url and hash to link to a specific commit.
+        .zprob = {
+            .url = "",
+            .hash = "",
+        }
+    },
+}
+```
+
+Then, in the `build.zig` file, add the following lines within the `build` function to include
+`zprob` as a module:
+
+```zig
+pub fn build(b: *std.Build) void {
+    // exe setup...
+
+    const zprob_dep = b.dependency("zprob", .{
+            .target = target,
+            .optimize = optimize,
+    });
+
+    const zprob_module = zprob_dep.module("zprob");
+    exe.root_module.addImport("zprob", zprob_module);
+
+    // additional build steps...
+}
+```
+
+Check out the build files in the [examples/](https://github.com/pblischak/zprob/tree/main/examples)
+folder for some demos of complete sample code projects.
+
 ## Issues
 
 If you run into any problems while using `zprob`, please consider filing an issue describing the

build.zig.zon

@@ -1,6 +1,6 @@
 .{
     .name = "zprob",
-    .version = "0.2.0",
+    .version = "0.2.1",
     .paths = .{
         "build.zig",
         "build.zig.zon",

src/RandomEnvironment.zig

@@ -62,6 +62,7 @@ gamma: Gamma(f64),
 normal: Normal(f64),
 uniform: Uniform(f64),
 
+/// Initialize a new `RandomEnvironment` struct with an `Allocator`.
 pub fn init(allocator: Allocator) !Self {
     var seed: u64 = undefined;
     try std.posix.getrandom(std.mem.asBytes(&seed));
@@ -93,6 +94,7 @@ pub fn init(allocator: Allocator) !Self {
     };
 }
 
+/// Initialize a new `RandomEnvironment` struct with a specific seed and an `Allocator`.
 pub fn initWithSeed(seed: u64, allocator: Allocator) !Self {
     const rng_state = try allocator.create(RngState);
     rng_state.*.prng = std.rand.DefaultPrng.init(seed);

src/bernoulli.zig

@@ -1,13 +1,11 @@
-//! Bernoulli distribution
-//!
-//! [https://en.wikipedia.org/wiki/Bernoulli_distribution](https://en.wikipedia.org/wiki/Bernoulli_distribution)
-
 const std = @import("std");
 const Allocator = std.mem.Allocator;
 const Random = std.Random;
 const utils = @import("utils.zig");
 
 /// Bernoulli distribution with parameter `p`.
+///
+/// [https://en.wikipedia.org/wiki/Bernoulli_distribution](https://en.wikipedia.org/wiki/Bernoulli_distribution)
 pub fn Bernoulli(comptime I: type, comptime F: type) type {
     _ = utils.ensureIntegerType(I);
     _ = utils.ensureFloatType(F);

src/beta.zig

@@ -1,7 +1,3 @@
-//! Beta distribution
-//!
-//! [https://en.wikipedia.org/wiki/Beta_distribution](https://en.wikipedia.org/wiki/Beta_distribution)
-
 const std = @import("std");
 const math = std.math;
 const Allocator = std.mem.Allocator;
@@ -12,6 +8,8 @@ const utils = @import("utils.zig");
 const Gamma = @import("gamma.zig").Gamma;
 
 /// Beta distribution with parameters `alpha` > 0 and `beta` > 0.
+///
+/// [https://en.wikipedia.org/wiki/Beta_distribution](https://en.wikipedia.org/wiki/Beta_distribution)
 pub fn Beta(comptime F: type) type {
     _ = utils.ensureFloatType(F);
 

src/binomial.zig

@@ -1,7 +1,3 @@
-//! Binomial distribution
-//!
-//! [https://en.wikipedia.org/wiki/Binomial_distribution](https://en.wikipedia.org/wiki/Binomial_distribution)
-
 const std = @import("std");
 const math = std.math;
 const Allocator = std.mem.Allocator;
@@ -11,6 +7,8 @@ const spec_fn = @import("special_functions.zig");
 const utils = @import("utils.zig");
 
 /// Binomial distribution with parameters `p` and `n`.
+///
+/// [https://en.wikipedia.org/wiki/Binomial_distribution](https://en.wikipedia.org/wiki/Binomial_distribution)
 pub fn Binomial(comptime I: type, comptime F: type) type {
     _ = utils.ensureIntegerType(I);
     _ = utils.ensureFloatType(F);

src/cauchy.zig

@@ -1,7 +1,3 @@
-//! Cauchy distribution
-//!
-//! [https://en.wikipedia.org/wiki/Cauchy_distribution](https://en.wikipedia.org/wiki/Cauchy_distribution)
-
 const std = @import("std");
 const math = std.math;
 const Allocator = std.mem.Allocator;
@@ -10,6 +6,8 @@ const Random = std.Random;
 const utils = @import("utils.zig");
 
 /// Cauchy distribution with median parameter `x0` and scale parameter `gamma`.
+///
+/// [https://en.wikipedia.org/wiki/Cauchy_distribution](https://en.wikipedia.org/wiki/Cauchy_distribution)
 pub fn Cauchy(comptime F: type) type {
     _ = utils.ensureFloatType(F);
 

src/chi_squared.zig

@@ -1,7 +1,3 @@
-//! Chi-squared distribution
-//!
-//! [https://en.wikipedia.org/wiki/Chi-squared_distribution](https://en.wikipedia.org/wiki/Chi-squared_distribution)
-
 const std = @import("std");
 const math = std.math;
 const Allocator = std.mem.Allocator;
@@ -12,6 +8,8 @@ const spec_fn = @import("special_functions.zig");
 const utils = @import("utils.zig");
 
 /// Chi-squared distribution with degrees of freedom `k`.
+///
+/// [https://en.wikipedia.org/wiki/Chi-squared_distribution](https://en.wikipedia.org/wiki/Chi-squared_distribution)
 pub fn ChiSquared(comptime I: type, comptime F: type) type {
     _ = utils.ensureIntegerType(I);
     _ = utils.ensureFloatType(F);

src/dirichlet.zig

@@ -1,7 +1,3 @@
-//! Dirichlet distribution
-//!
-//! [https://en.wikipedia.org/wiki/Dirichlet_distribution](https://en.wikipedia.org/wiki/Dirichlet_distribution)
-
 const std = @import("std");
 const math = std.math;
 const Allocator = std.mem.Allocator;
@@ -12,6 +8,8 @@ const spec_fn = @import("special_functions.zig");
 const utils = @import("utils.zig");
 
 /// Dirichlet distribution with parameter `alpha_vec`.
+///
+/// [https://en.wikipedia.org/wiki/Dirichlet_distribution](https://en.wikipedia.org/wiki/Dirichlet_distribution)
 pub fn Dirichlet(comptime F: type) type {
     _ = utils.ensureFloatType(F);
 

src/exponential.zig

@@ -1,7 +1,3 @@
-//! Exponential distribution
-//!
-//! [https://en.wikipedia.org/wiki/Exponential_distribution](https://en.wikipedia.org/wiki/Exponential_distribution)
-
 const std = @import("std");
 const math = std.math;
 const Allocator = std.mem.Allocator;
@@ -10,6 +6,8 @@ const Random = std.Random;
 const utils = @import("utils.zig");
 
 /// Exponential distribution with parameter `lambda`.
+///
+/// [https://en.wikipedia.org/wiki/Exponential_distribution](https://en.wikipedia.org/wiki/Exponential_distribution)
 pub fn Exponential(comptime F: type) type {
     _ = utils.ensureFloatType(F);
 

src/gamma.zig

@@ -1,7 +1,3 @@
-//! Gamma distribution
-//!
-//! [https://en.wikipedia.org/wiki/Gamma_distribution](https://en.wikipedia.org/wiki/Gamma_distribution)
-
 const std = @import("std");
 const math = std.math;
 const Allocator = std.mem.Allocator;
@@ -11,6 +7,8 @@ const spec_fn = @import("special_functions.zig");
 const utils = @import("utils.zig");
 
 /// Gamma distribution with parameters `shape` and `scale` (`1 / rate`).
+///
+/// [https://en.wikipedia.org/wiki/Gamma_distribution](https://en.wikipedia.org/wiki/Gamma_distribution)
 pub fn Gamma(comptime F: type) type {
     _ = utils.ensureFloatType(F);
 

src/geometric.zig

@@ -1,18 +1,14 @@
-//! Geometric distribution
-//!
-//! [https://en.wikipedia.org/wiki/Geometric_distribution](https://en.wikipedia.org/wiki/Geometric_distribution)
-//!
-
 const std = @import("std");
 const math = std.math;
 const Allocator = std.mem.Allocator;
 const Random = std.Random;
 
 const utils = @import("utils.zig");
 
-/// Geometric distribution with parameter `p`.
+/// Geometric distribution with parameter `p`. Records the number of trials needed to get the
+///  first success.
 ///
-/// Records the number of trials needed to get the first success.
+/// [https://en.wikipedia.org/wiki/Geometric_distribution](https://en.wikipedia.org/wiki/Geometric_distribution)
 pub fn Geometric(comptime I: type, comptime F: type) type {
     _ = utils.ensureIntegerType(I);
     _ = utils.ensureFloatType(F);

src/multinomial.zig

@@ -1,7 +1,3 @@
-//! Multinomial distribution
-//!
-//! [https://en.wikipedia.org/wiki/Multinomial_distribution](https://en.wikipedia.org/wiki/Multinomial_distribution)
-
 const std = @import("std");
 const math = std.math;
 const Allocator = std.mem.Allocator;
@@ -13,6 +9,8 @@ const utils = @import("utils.zig");
 
 /// Multinomial distribution with parameters `n` (number of totol observations)
 /// and `p_vec` (probability of observing each category).
+///
+/// [https://en.wikipedia.org/wiki/Multinomial_distribution](https://en.wikipedia.org/wiki/Multinomial_distribution)
 pub fn Multinomial(comptime I: type, comptime F: type) type {
     _ = utils.ensureIntegerType(I);
     _ = utils.ensureFloatType(F);