Module org.cicirello.rho_mu

module org.cicirello.rho_mu

ρμ - A Java library of randomization enhancements and other math utilities.

Copyright © 2017-2024 Vincent A. Cicirello.

DOI:10.21105/joss.04663 Maven Central GitHub release (latest by date) GitHub Repository GNU General Public License Version 3 (GPLv3)

How to Cite

If you use the ρμ library in your research, please cite the following article which introduces the library:

Support ρμ

GitHub Sponsors Liberapay Ko-Fi

About the ρμ Library

The ρμ library is a library of Randomization enHancements and Other Math Utilities. It includes implementations of various algorithms for randomly sampling indexes into arrays and other sequential structures, randomly sampling pairs and triples of unique indexes, randomly sampling k indexes, etc. It also includes efficient implementations of random number generation from distributions other than uniform, such as Gaussian, Cauchy, etc. Additionally, it includes implementations of other math functions that are either needed by the randomization utilities, or needed by some of our other projects.

Much of the core randomization enhancements is in a pair of utility classes: RandomIndexer and RandomVariates. Beginning with v2.0.0, the ρμ library was revised to utilize Java 17's hierarchy of random number generator interfaces (i.e., RandomGenerator and its subinterfaces). Specifically, ρμ now provides a class EnhancedRandomGenerator that wraps an instance of RandomGenerator while also implementing RandomGenerator, enabling adding the enhanced randomization features to any of Java 17's many random number generators, while also serving as a drop-in replacement. Additionally, ρμ provides a hierarchy of such wrapper classes, corresponding to Java 17's hierarchy of random number generator interfaces.

The randomization enhancements includes:

  • Faster generation of random int values subject to a bound or bound and origin.
  • Faster generation of random int values within an IntStream subject to a bound and origin.
  • Faster generation of Gaussian distributed random doubles for Java's legacy random number generators.
  • Additional distributions available beyond what is supported by the Java API's RandomGenerator classes, such as Binomial and Cauchy random vaiables.
  • Ultrafast, but biased, nextBiasedInt methods that sacrifices uniformity for speed by excluding the rejection sampling necessary to ensure uniformity, as well as a biasedInts methods for generating streams of such integers.
  • Methods for generating random pairs of integers without replacement, and random triples of integers without replacement.
  • Methods for generating random samples of k integers without replacement from a range of integers.
  • Methods to generate streams of numbers from distributions other than uniform, such as streams of random numbers from binomial distributions, Cauchy distributions, exponential distributions, and Gaussian distributions.
  • Methods to generate streams of pairs of distinct integers, and streams of triples of distinct integers.
  • Methods for shuffling the elements of arrays and Lists.

The source code repository is hosted on GitHub. The source code is licensed under the GNU General Public License Version 3 (GPLv3). For more information see the ρμ website.

UML Class Diagram

The following UML class diagram shows the structure of the ρμ library. Classes and interfaces shown in blue are classes within the ρμ library, and are clickable links to the page documenting the class. Classes and interfaces shown in gray are in the Java API, and are also clickable links to the relevant page within the Java API documentation. For brevity in the diagram, methods are omitted, and most attributes are omitted, aside from the attributes corresponding to the wrapped random number generator instances.

UML diagram