README.md

ρμ - Java library of Randomization enHancements and Other Math Utilities

Copyright (C) 2017-2024 Vincent A. Cicirello.

Website: https://rho-mu.cicirello.org/

API documentation: https://rho-mu.cicirello.org/api/

Publications About the Library
Packages and Releases
Build Status
JaCoCo Test Coverage
Security
DOI
Other Information
Support

How to Cite

If you use this library in your research, please cite the following paper:

Cicirello, V. A., (2022). ρμ: A Java library of randomization enhancements and other math utilities. Journal of Open Source Software, 7(76), 4663, https://doi.org/10.21105/joss.04663.

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. 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 which are 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.

Some of the randomization enhancements include:

• 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 ρμ library is a dependency of some of our other projects, including JavaPermutationTools and Chips-n-Salsa.

Table of Contents

The rest of this README is organized as follows:

• UML Class Diagram: A UML class diagram of the library
• Java Requirements: Minimum supported Java version information
• Versioning Scheme: Explanation of the library's version numbers
• Building the Library (with Maven)
• Examples: Information on example library usage
• Java Modules: Information for those whose projects use Java modules
• Importing from Package Repositories
  • Importing the Library from Maven Central
  • Importing the Library from GitHub Packages
• Downloading Jar Files: Information on where you can download pre-compiled jars
• License: Licensing information
• Contribute: Information for those who wish to contribute

UML Class Diagram

This class diagram summarizes the public classes of ρμ in relation to Java 17's hierarchy of RandomGenerator interfaces. Note that for brevity in the diagram, methods are omitted. Each class and interface in the diagram is a clickable link to the javadoc page that documents it either within the documentation of ρμ for the classes of the ρμ library, or within the Java 17 API documentation for Java's RandomGenerator interfaces.

classDiagram
  class Statistics
  class MatrixOps
  class JacobiDiagonalization
  class MathFunctions
  class RandomGenerator
  <<interface>> RandomGenerator
  class StreamableGenerator
  <<interface>> StreamableGenerator
  RandomGenerator <|-- StreamableGenerator
  class SplittableGenerator
  <<interface>> SplittableGenerator
  StreamableGenerator <|-- SplittableGenerator
  class JumpableGenerator
  <<interface>> JumpableGenerator
  StreamableGenerator <|-- JumpableGenerator
  class LeapableGenerator
  <<interface>> LeapableGenerator
  JumpableGenerator <|-- LeapableGenerator
  class ArbitrarilyJumpableGenerator
  <<interface>> ArbitrarilyJumpableGenerator
  LeapableGenerator <|-- ArbitrarilyJumpableGenerator
  class EnhancedRandomGenerator
  EnhancedRandomGenerator : -RandomGenerator generator
  RandomGenerator <|.. EnhancedRandomGenerator
  class RandomVariates
  class IndexPair
  class RandomSampler
  class RandomIndexer
  class Shuffler
  class IndexTriple
  RandomIndexer <.. EnhancedRandomGenerator
  RandomIndexer <.. RandomSampler
  RandomSampler <.. RandomIndexer
  RandomSampler <.. EnhancedRandomGenerator
  RandomIndexer <.. Shuffler
  Shuffler <.. EnhancedRandomGenerator
  RandomVariates <.. EnhancedRandomGenerator
  RandomVariates <.. RandomSampler
  IndexPair <.. EnhancedRandomGenerator
  IndexPair <.. RandomIndexer
  IndexTriple <.. RandomIndexer
  IndexTriple <.. EnhancedRandomGenerator
  class EnhancedStreamableGenerator
  EnhancedStreamableGenerator : -StreamableGenerator generator
  EnhancedRandomGenerator <|-- EnhancedStreamableGenerator
  StreamableGenerator <|.. EnhancedStreamableGenerator
  class EnhancedSplittableGenerator
  EnhancedSplittableGenerator : -SplittableGenerator generator
  EnhancedStreamableGenerator <|-- EnhancedSplittableGenerator
  SplittableGenerator <|.. EnhancedSplittableGenerator
  class EnhancedJumpableGenerator
  EnhancedJumpableGenerator : -JumpableGenerator generator
  EnhancedStreamableGenerator <|-- EnhancedJumpableGenerator
  JumpableGenerator <|.. EnhancedJumpableGenerator
  class EnhancedLeapableGenerator
  EnhancedLeapableGenerator : -LeapableGenerator generator
  EnhancedJumpableGenerator <|-- EnhancedLeapableGenerator
  LeapableGenerator <|.. EnhancedLeapableGenerator
  class EnhancedArbitrarilyJumpableGenerator
  EnhancedArbitrarilyJumpableGenerator : -ArbitrarilyJumpableGenerator generator
  EnhancedLeapableGenerator <|-- EnhancedArbitrarilyJumpableGenerator
  ArbitrarilyJumpableGenerator <|.. EnhancedArbitrarilyJumpableGenerator
  link RandomIndexer "https://rho-mu.cicirello.org/api/org.cicirello.rho_mu/org/cicirello/math/rand/RandomIndexer.html"
  link RandomVariates "https://rho-mu.cicirello.org/api/org.cicirello.rho_mu/org/cicirello/math/rand/RandomVariates.html"
  link RandomSampler "https://rho-mu.cicirello.org/api/org.cicirello.rho_mu/org/cicirello/math/rand/RandomSampler.html"
  link EnhancedRandomGenerator "https://rho-mu.cicirello.org/api/org.cicirello.rho_mu/org/cicirello/math/rand/EnhancedRandomGenerator.html"
  link EnhancedStreamableGenerator "https://rho-mu.cicirello.org/api/org.cicirello.rho_mu/org/cicirello/math/rand/EnhancedStreamableGenerator.html"
  link EnhancedSplittableGenerator "https://rho-mu.cicirello.org/api/org.cicirello.rho_mu/org/cicirello/math/rand/EnhancedSplittableGenerator.html"
  link EnhancedJumpableGenerator "https://rho-mu.cicirello.org/api/org.cicirello.rho_mu/org/cicirello/math/rand/EnhancedJumpableGenerator.html"
  link EnhancedLeapableGenerator "https://rho-mu.cicirello.org/api/org.cicirello.rho_mu/org/cicirello/math/rand/EnhancedLeapableGenerator.html"
  link EnhancedArbitrarilyJumpableGenerator "https://rho-mu.cicirello.org/api/org.cicirello.rho_mu/org/cicirello/math/rand/EnhancedArbitrarilyJumpableGenerator.html"
  link RandomGenerator "https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/util/random/RandomGenerator.html"
  link StreamableGenerator "https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/util/random/RandomGenerator.StreamableGenerator.html"
  link SplittableGenerator "https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/util/random/RandomGenerator.SplittableGenerator.html"
  link JumpableGenerator "https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/util/random/RandomGenerator.JumpableGenerator.html"
  link LeapableGenerator "https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/util/random/RandomGenerator.LeapableGenerator.html"
  link ArbitrarilyJumpableGenerator "https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/util/random/RandomGenerator.ArbitrarilyJumpableGenerator.html"
  link MathFunctions "https://rho-mu.cicirello.org/api/org.cicirello.rho_mu/org/cicirello/math/MathFunctions.html"
  link Statistics "https://rho-mu.cicirello.org/api/org.cicirello.rho_mu/org/cicirello/math/stats/Statistics.html"
  link MatrixOps "https://rho-mu.cicirello.org/api/org.cicirello.rho_mu/org/cicirello/math/la/MatrixOps.html"
  link JacobiDiagonalization "https://rho-mu.cicirello.org/api/org.cicirello.rho_mu/org/cicirello/math/la/JacobiDiagonalization.html"
  link IndexPair "https://rho-mu.cicirello.org/api/org.cicirello.rho_mu/org/cicirello/math/rand/IndexPair.html"
  link IndexTriple "https://rho-mu.cicirello.org/api/org.cicirello.rho_mu/org/cicirello/math/rand/IndexTriple.html"
  link Shuffler "https://rho-mu.cicirello.org/api/org.cicirello.rho_mu/org/cicirello/math/rand/Shuffler.html"

Loading

Java Requirements

We currently support Java 17+. Our development process utilizes OpenJDK 17, and all jar files released via Maven Central, GitHub Packages, and GitHub Releases are built with a Java 17 target. See the following table for a mapping between library version and minimum supported Java version.

version	Java requirements
2.w.x to 4.y.z	Java 17+
1.x.y	Java 11+

Versioning Scheme

ρμ 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.

Building the Library (with Maven)

The ρμ library is built using Maven. The root of the repository contains a Maven pom.xml. To build the library, execute mvn package at the root of the repository, which will compile all classes, run all tests, run javadoc, and generate jar files of the library, the sources, and the javadocs. The file names make this distinction explicit. All build outputs will then be found in the directory target.

To include generation of a code coverage report during the build, execute mvn package -Pcoverage at the root of the repository to enable a Maven profile that executes JaCoCo during the test phase.

To run all static analysis tools (i.e., SpotBugs, Find Security Bugs, refactor-first), execute mvn package -Panalysis to enable a Maven profile that executes the various static analysis tools that we are using. The SpotBugs html report will be found in the target directory, or you can use the SpotBugs GUI with: mvn spotbugs:gui -Panalysis. The refactor-first report will be found in the target/site directory.

To run all of the above: mvn package -P "analysis,coverage".

Examples

The examples directory contains source code of a few example programs demonstrating how to use various features of the library. The source code of the examples is commented with explanations where appropriate.

Some of our other projects make extensive use of this library. You may consult the source code of JavaPermutationTools and/or Chips-n-Salsa for additional real code examples. For example Chips-n-Salsa is a library of parallel and adaptive stochastic local search algorithms, and as such requires extensive use of random number generation.

Java Modules

This library 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;
}

Importing from Package Repositories

Prebuilt artifacts are regularly published to Maven Central and GitHub Packages. In most cases, you'll want to use Maven Central. Releases are published to GitHub Packages mainly as a fall-back in the unlikely scenario that Maven Central is unavailable.

Importing the Library from Maven Central

Add this to the dependencies section of your pom.xml, replacing the version number with the version that you want to use.

<dependency>
  <groupId>org.cicirello</groupId>
  <artifactId>rho-mu</artifactId>
  <version>4.0.0</version>
</dependency>

Importing the Library from GitHub Packages

If you'd prefer to import from GitHub Packages, rather than Maven Central, then: (1) add the dependency as indicated in previous section above, and (2) add the following to the repositories section of your pom.xml:

<repository>
  <id>github</id>
  <name>GitHub cicirello Apache Maven Packages</name>
  <url>https://maven.pkg.github.com/cicirello/rho-mu</url>
</repository>

Note that GitHub Packages requires authenticating to GitHub. Thus, it is likely less convenient than importing from Maven Central. We mainly provide this option as a backup source of artifacts.

Downloading Jar Files

If you don't use a dependency manager that supports importing from Maven Central, or if you simply prefer to download manually, prebuilt jars are also attached to each GitHub Release. However, be sure to also download required versions of dependencies. You should really be using a dependency manager to ensure that you get this right.

License

The ρμ library is licensed under the GNU General Public License 3.0.

Contribute

If you would like to contribute to ρμ in any way, such as reporting bugs, suggesting new functionality, or code contributions such as bug fixes or implementations of new functionality, then start by reading the contribution guidelines. This project has adopted the Contributor Covenant Code of Conduct.