ρμ

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 extracted ρμ from those libraries, and we have since continued development of ρμ independently of those other projects.

Much of the core randomization enhancements is in three utility classes: RandomIndexer, RandomVariates, and RandomSampler. 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, ρμ 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, as illustrated in the interactive UML diagram further down the page.

Features: The randomization enhancements includes:

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.

How to Cite

https://doi.org/10.21105/joss.04663

The ρμ library originated as part of the research of Vincent A. Cicirello. If you use the ρμ library in your research, please cite the following article which introduces the library:

Dependencies

ρμ has minimal dependencies, and include:

Dependent Libraries

The following libraries depend upon ρμ

Importing from Maven Central

Latest release on 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;
}

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. This UML diagram is scrollable horizontally for viewing on mobile devices.

UML diagram

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:

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.