Package org.loudouncodes.randkit

package org.loudouncodes.randkit
RandKit — lightweight random variate generation for Java 17+.

What this package is

A small, opinionated library for sampling from probability distributions, built directly on the JDK java.util.random.RandomGenerator API. It aims to be deterministic by seed, bias-free for integer ranges, and easy to use in simulations and teaching.

Key concepts

  • Distributions: Continuous and discrete types expose a small, consistent surface (sample, pdf/pmf, cdf, quantile, mean, variance) via ContinuousDistribution and DiscreteDistribution.
  • Support metadata: Distributions describe their mathematical domain using DistributionSupport so callers can reason about bounds, open/closed endpoints, and discrete vs. continuous values.
  • Samplers: For “just draw values” scenarios, the tiny functional interfaces DoubleSampler and IntSampler provide minimal plugs.
  • RNG utilities: Randoms centralizes the default generator choice and seeded construction.

Seeding & determinism

All distributions accept a RandomGenerator. Overloads are provided for a sensible default RNG and for deterministic, seeded construction. Given the same algorithm, seed, and parameters, sequences are repeatable.

Threading

Distribution instances are not synchronized. Prefer one instance per thread, or supply a RandomGenerator that you split per thread. Avoid sharing a single instance across threads unless you provide external synchronization.

Integer sampling (no modulo bias)

Integer-valued generators use unbiased methods (e.g., bounded nextLong or rejection sampling) for ranges that are not powers of two.

What’s included (v1 snapshot)

Quick start


 import java.util.random.RandomGenerator;
 import org.loudouncodes.randkit.continuous.UniformDouble;
 import org.loudouncodes.randkit.discrete.UniformInt;
 import org.loudouncodes.randkit.util.Randoms;

 // Continuous uniform on [0,1), default RNG
 double x = new UniformDouble(0.0, 1.0).sample();

 // Discrete uniform on {1,2,3,4,5,6}, deterministic by seed
 int face = new UniformInt(1234L, 1, 6).sample();

 // Bring your own generator
 RandomGenerator rng = Randoms.seeded(42L);
 double y = new UniformDouble(rng, -2.0, 3.0).sample();

Validation & errors

Constructors validate parameters eagerly and throw IllegalArgumentException for invalid inputs (e.g., a < b for uniform, probabilities in [0,1], positive scale).

Subpackages

  • org.loudouncodes.randkit.api — public interfaces and support metadata.
  • org.loudouncodes.randkit.continuous — continuous distributions.
  • org.loudouncodes.randkit.discrete — discrete distributions.
  • org.loudouncodes.randkit.util — RNG utilities and general helpers.
Since:
0.1.0