Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/cicirello/rho-mu
ρμ - a Java library of Randomization enHancements and Other Math Utilities
https://github.com/cicirello/rho-mu
binomial cauchy gaussian pseudorandom random-numbers randomization randomizer
Last synced: about 2 months ago
JSON representation
ρμ - a Java library of Randomization enHancements and Other Math Utilities
- Host: GitHub
- URL: https://github.com/cicirello/rho-mu
- Owner: cicirello
- License: gpl-3.0
- Created: 2021-09-20T18:38:01.000Z (over 3 years ago)
- Default Branch: main
- Last Pushed: 2024-10-22T00:17:38.000Z (2 months ago)
- Last Synced: 2024-10-22T21:29:48.420Z (2 months ago)
- Topics: binomial, cauchy, gaussian, pseudorandom, random-numbers, randomization, randomizer
- Language: Java
- Homepage: https://rho-mu.cicirello.org
- Size: 2.25 MB
- Stars: 4
- Watchers: 3
- Forks: 3
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
- Citation: CITATION.cff
Awesome Lists containing this project
README
# ρμ - Java library of Randomization enHancements and Other Math Utilities
Copyright (C) 2017-2024 [Vincent A. Cicirello](https://www.cicirello.org/).
Website: https://rho-mu.cicirello.org/
API documentation: https://rho-mu.cicirello.org/api/
| __Publications About the Library__ | [](https://doi.org/10.21105/joss.04663) |
| :--- | :--- |
| __Packages and Releases__ | [](https://central.sonatype.com/artifact/org.cicirello/rho-mu/) [](https://github.com/cicirello/rho-mu/releases) |
| __Build Status__ | [](https://github.com/cicirello/rho-mu/actions/workflows/build.yml) [](https://rho-mu.cicirello.org/api/) [](https://github.com/cicirello/rho-mu/actions/workflows/codeql-analysis.yml) |
| __JaCoCo Test Coverage__ | [](https://github.com/cicirello/rho-mu/actions/workflows/build.yml) [](https://github.com/cicirello/rho-mu/actions/workflows/build.yml) |
| __Security__ | [](https://snyk.io/vuln/maven%3Aorg.cicirello%3Arho-mu) [](https://snyk.io/test/github/cicirello/rho-mu) |
| __DOI__ | [](https://zenodo.org/badge/latestdoi/408560166) |
| __Other Information__ | [](https://github.com/cicirello/rho-mu/blob/main/LICENSE) [](https://google.github.io/styleguide/javaguide.html) |
| __Support__ | [](https://github.com/sponsors/cicirello) [](https://liberapay.com/cicirello) [](https://ko-fi.com/cicirello) |
## 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](https://github.com/cicirello/JavaPermutationTools)
and [Chips-n-Salsa](https://github.com/cicirello/Chips-n-Salsa).
### Table of Contents
The rest of this README is organized as follows:
* [UML Class Diagram](#uml-class-diagram): A UML class diagram of the library
* [Java Requirements](#java-requirements): Minimum supported Java version information
* [Versioning Scheme](#versioning-scheme): Explanation of the library's version numbers
* [Building the Library (with Maven)](#building-the-library-with-maven)
* [Examples](#examples): Information on example library usage
* [Java Modules](#java-modules): Information for those whose projects use Java modules
* [Importing from Package Repositories](#importing-from-package-repositories)
* [Importing the Library from Maven Central](#importing-the-library-from-maven-central)
* [Importing the Library from GitHub Packages](#importing-the-library-from-gitHub-packages)
* [Downloading Jar Files](#downloading-jar-files): Information on where you can download pre-compiled jars
* [License](#license): Licensing information
* [Contribute](#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 ρμ](https://rho-mu.cicirello.org/api/)
for the classes of the ρμ library, or within the Java 17 API documentation for Java's `RandomGenerator` interfaces.
```mermaid
classDiagram
class Statistics
class MatrixOps
class JacobiDiagonalization
class MathFunctions
class RandomGenerator
<> RandomGenerator
class StreamableGenerator
<> StreamableGenerator
RandomGenerator <|-- StreamableGenerator
class SplittableGenerator
<> SplittableGenerator
StreamableGenerator <|-- SplittableGenerator
class JumpableGenerator
<> JumpableGenerator
StreamableGenerator <|-- JumpableGenerator
class LeapableGenerator
<> LeapableGenerator
JumpableGenerator <|-- LeapableGenerator
class ArbitrarilyJumpableGenerator
<> 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"
```
## 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](https://semver.org/) 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](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](https://github.com/cicirello/JavaPermutationTools)
and/or [Chips-n-Salsa](https://github.com/cicirello/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`:
```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.
```XML
org.cicirello
rho-mu
4.0.0
```
### 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:
```XML
github
GitHub cicirello Apache Maven Packages
https://maven.pkg.github.com/cicirello/rho-mu
```
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](https://github.com/cicirello/rho-mu/releases). 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](https://www.gnu.org/licenses/gpl-3.0.en.html).
## 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](https://github.com/cicirello/.github/blob/main/CONTRIBUTING.md).
This project has adopted
the [Contributor Covenant Code of Conduct](https://github.com/cicirello/.github/blob/main/CODE_OF_CONDUCT.md).