ρμ
Overview
ρμ is a Java library of Randomization enHancements and Other Math Utilities (rho mu). It includes implementations of various algorithms for efficiently randomly sampling combinations of 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, Binomial, etc. Additionally, it includes implementations of other math functions that are either needed by the randomization utilities, or which are needed by some of our other projects.
All of the initial functionality of ρμ originated in some of our other libraries, including JavaPermutationTools and Chips-n-Salsa. However, we found ourselves beginning to add one or the other of those libraries as dependencies in some other projects strictly for the randomization utilities, which is certainly less than ideal. Therefore, we have extracted ρμ from those libraries.
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 nested subinterfaces). Specifically, ρμ now provides a class EnhancedRandomGenerator that wraps an instance 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.
- 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; and is licensed under the GNU General Public License Version 3 (GPLv3). The API documentation is found on this site. The library is regularly published to Maven Central, from which it is easily imported into software projects using Maven and other commonly used build tools.
The ρμ library originated as part of the research of Vincent A. Cicirello.
How to Cite
If you use the ρμ library in your research, please cite the following article which introduces the library:
- Vincent A. Cicirello. ρμ: A Java library of randomization enhancements and other math utilities. Journal of Open Source Software, 7(76), 4663, August 2022. [PDF] [BIB] [DOI]
Importing from Maven Central
To import ρμ from the Maven Central repository (if your build tool is Maven), add the following to the dependencies section of your “pom.xml” (for other build tools, see your build tool's documentation for the equivalent):
<dependency>
<groupId>org.cicirello</groupId>
<artifactId>rho-mu</artifactId>
<version>x.y.z</version>
</dependency>
Just replace x.y.z
with your desired version of the library.
Java Modules
ρμ provides a Java module, org.cicirello.rho_mu. To use in your project, add the following to your module-info.java:
module your.module.name.here {
requires org.cicirello.rho_mu;
}
Semantic Versioning
ρμ uses Semantic Versioning with version numbers of the form: MAJOR.MINOR.PATCH, where differences in MAJOR correspond to incompatible API changes, differences in MINOR correspond to introduction of backwards compatible new functionality, and PATCH corresponds to backwards compatible bug fixes.
Development Process
To maintain a high quality library, our development process utilizes the following:- Test Coverage: We require unit tests for all functionality. We generate JaCoCo test coverage reports on all push and pull-request events to the source code repository. Although we don't have a strict minimum coverage for acceptance, coverage is quite often at or near 100%. Current coverage is reported in the readme of the GitHub repository (updated automatically).
- Regression Testing: All new and existing tests are executed as part of all pull requests, and all must pass for acceptance.
- Static Analysis: We use multiple static analysis tools to scan for potential vulnerabilities, error prone code, and other potential code improvements. At the present time, this includes running:
Dependent Libraries
The following libraries depend upon ρμ
Related Publications
The following is a list of publications that either influenced the design of the ρμ library, introduced algorithms included within ρμ, or are otherwise directly related in some substantial way.
- Vincent A. Cicirello. On the Average Runtime of an Open Source Binomial Random Variate Generation Algorithm. Technical Report ALG-24-007, Cicirello.org, March 2024. [PDF] [BIB] [arXiv] [CODE]
- Vincent A. Cicirello. An Analysis of an Open Source Binomial Random Variate Generation Algorithm. Engineering Proceedings, 56(1), Article 86, October 2023. doi:10.3390/ASEC2023-15349. [PDF] [BIB] [DOI] [CODE]
- Vincent A. Cicirello. Cycle Mutation: Evolving Permutations via Cycle Induction. Applied Sciences, 12(11), Article 5506, June 2022. doi:10.3390/app12115506. [PDF] [BIB] [DOI] [arXiv]
- Vincent A. Cicirello. Chips-n-Salsa: A Java Library of Customizable, Hybridizable, Iterative, Parallel, Stochastic, and Self-Adaptive Local Search Algorithms. Journal of Open Source Software, 5(52), 2448, August 2020. [PDF] [BIB] [DOI]
- Vincent A. Cicirello. JavaPermutationTools: A Java Library of Permutation Distance Metrics. Journal of Open Source Software, 3(31), 950, November 2018. [PDF] [BIB] [DOI]
- Vincent A. Cicirello. Impact of Random Number Generation on Parallel Genetic Algorithms. In Proceedings of the Thirty-First International Florida Artificial Intelligence Research Society Conference, pages 2-7. AAAI Press, May 2018. [PDF] [BIB] [PUB]