{"id":15765365,"url":"https://github.com/cicirello/rho-mu","last_synced_at":"2025-04-21T03:32:05.681Z","repository":{"id":37527099,"uuid":"408560166","full_name":"cicirello/rho-mu","owner":"cicirello","description":"ρμ - a Java library of Randomization enHancements and Other Math Utilities","archived":false,"fork":false,"pushed_at":"2025-04-12T00:25:15.000Z","size":2394,"stargazers_count":5,"open_issues_count":0,"forks_count":4,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-04-14T15:00:39.309Z","etag":null,"topics":["binomial","cauchy","gaussian","pseudorandom","random-numbers","randomization","randomizer"],"latest_commit_sha":null,"homepage":"https://rho-mu.cicirello.org","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cicirello.png","metadata":{"funding":{"github":"cicirello","patreon":null,"open_collective":null,"ko_fi":"cicirello","tidelift":null,"community_bridge":null,"liberapay":"cicirello","issuehunt":null,"otechie":null,"custom":null},"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":"CITATION.cff","codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":".zenodo.json"}},"created_at":"2021-09-20T18:38:01.000Z","updated_at":"2025-04-12T00:25:13.000Z","dependencies_parsed_at":"2024-04-23T23:25:20.311Z","dependency_job_id":"27a31cf2-1cc4-4f72-83ff-72b7e70b583a","html_url":"https://github.com/cicirello/rho-mu","commit_stats":null,"previous_names":[],"tags_count":24,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cicirello%2Frho-mu","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cicirello%2Frho-mu/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cicirello%2Frho-mu/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cicirello%2Frho-mu/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cicirello","download_url":"https://codeload.github.com/cicirello/rho-mu/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249991065,"owners_count":21357196,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["binomial","cauchy","gaussian","pseudorandom","random-numbers","randomization","randomizer"],"created_at":"2024-10-04T12:41:20.401Z","updated_at":"2025-04-21T03:32:05.272Z","avatar_url":"https://github.com/cicirello.png","language":"Java","funding_links":["https://github.com/sponsors/cicirello","https://ko-fi.com/cicirello","https://liberapay.com/cicirello"],"categories":["数学库"],"sub_categories":["语音合成"],"readme":"# \u0026rho;\u0026mu; - Java library of Randomization enHancements and Other Math Utilities\n\n\u003cimg src=\"https://rho-mu.cicirello.org/images/rho-mu.png\" width=\"640\" alt=\"\u0026rho;\u0026mu; - Java library of Randomization enHancements and Other Math Utilities\"\u003e\n\nCopyright (C) 2017-2024 [Vincent A. Cicirello](https://www.cicirello.org/).\n\nWebsite: https://rho-mu.cicirello.org/\n\nAPI documentation: https://rho-mu.cicirello.org/api/\n\n| __Publications About the Library__ | [![DOI](https://joss.theoj.org/papers/10.21105/joss.04663/status.svg)](https://doi.org/10.21105/joss.04663) |\n| :--- | :--- |\n| __Packages and Releases__ | [![Maven Central](https://img.shields.io/maven-central/v/org.cicirello/rho-mu.svg?label=Maven%20Central\u0026logo=apachemaven)](https://central.sonatype.com/artifact/org.cicirello/rho-mu/) [![GitHub release (latest by date)](https://img.shields.io/github/v/release/cicirello/rho-mu?logo=GitHub)](https://github.com/cicirello/rho-mu/releases) |\n| __Build Status__ | [![build](https://github.com/cicirello/rho-mu/workflows/build/badge.svg)](https://github.com/cicirello/rho-mu/actions/workflows/build.yml) [![docs](https://github.com/cicirello/rho-mu/workflows/docs/badge.svg)](https://rho-mu.cicirello.org/api/) [![CodeQL](https://github.com/cicirello/rho-mu/actions/workflows/codeql-analysis.yml/badge.svg)](https://github.com/cicirello/rho-mu/actions/workflows/codeql-analysis.yml) |\n| __JaCoCo Test Coverage__ | [![coverage](https://raw.githubusercontent.com/cicirello/rho-mu/badges/jacoco.svg)](https://github.com/cicirello/rho-mu/actions/workflows/build.yml) [![branches coverage](https://github.com/cicirello/rho-mu/blob/badges/branches.svg)](https://github.com/cicirello/rho-mu/actions/workflows/build.yml) |\n| __Security__ | [![Snyk security score](https://snyk-widget.herokuapp.com/badge/mvn/org.cicirello/rho-mu/badge.svg)](https://snyk.io/vuln/maven%3Aorg.cicirello%3Arho-mu) [![Snyk Known Vulnerabilities](https://snyk.io/test/github/cicirello/rho-mu/badge.svg)](https://snyk.io/test/github/cicirello/rho-mu) |\n| __DOI__ | [![DOI](https://zenodo.org/badge/408560166.svg)](https://zenodo.org/badge/latestdoi/408560166) | \n| __Other Information__ | [![GitHub](https://img.shields.io/github/license/cicirello/rho-mu)](https://github.com/cicirello/rho-mu/blob/main/LICENSE) [![style](https://img.shields.io/badge/style-Google%20Java%20Style-informational)](https://google.github.io/styleguide/javaguide.html) | \n| __Support__ | [![GitHub Sponsors](https://img.shields.io/badge/sponsor-30363D?logo=GitHub-Sponsors\u0026logoColor=#EA4AAA)](https://github.com/sponsors/cicirello) [![Liberapay](https://img.shields.io/badge/Liberapay-F6C915?logo=liberapay\u0026logoColor=black)](https://liberapay.com/cicirello) [![Ko-Fi](https://img.shields.io/badge/Ko--fi-F16061?logo=ko-fi\u0026logoColor=white)](https://ko-fi.com/cicirello) |\n\n## How to Cite\n\nIf you use this library in your research, please cite the following paper:\n\n\u003e 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.\n\n## Overview\n\n\u0026rho;\u0026mu; is a Java library of Randomization enHancements and Other Math Utilities\n(rho mu). It includes implementations of various algorithms for efficiently \nrandomly sampling combinations of indexes into arrays and other sequential\nstructures. It also includes efficient implementations of random number generation from\ndistributions other than uniform, such as Gaussian, Cauchy, etc. Additionally, it \nincludes implementations of other math functions that are either needed by the randomization \nutilities, or which are needed by some of our other projects.\n\nMuch of the core randomization enhancements is in a pair of utility classes: `RandomIndexer` and\n`RandomVariates`. Beginning with v2.0.0, the \u0026rho;\u0026mu; library was revised to utilize Java 17's\nhierarchy of random number generator interfaces (i.e., `RandomGenerator` and its subinterfaces).\nSpecifically, \u0026rho;\u0026mu; now provides a class `EnhancedRandomGenerator` that wraps an instance\nof `RandomGenerator` while also implementing `RandomGenerator`, enabling adding the enhanced\nrandomization features to any of Java 17's many random number generators, while also serving\nas a drop-in replacement. Additionally, \u0026rho;\u0026mu; provides a hierarchy of such wrapper classes,\ncorresponding to Java 17's hierarchy of random number generator interfaces.\n\nSome of the randomization enhancements include:\n* Faster generation of random int values subject to a bound or bound and origin.\n* Faster generation of random int values within an IntStream subject to a bound and origin.\n* Faster generation of Gaussian distributed random doubles.\n* Additional distributions available beyond what is supported by the Java API's `RandomGenerator` classes, \n  such as Binomial and Cauchy random vaiables.\n* Ultrafast, but biased, `nextBiasedInt` methods that sacrifices uniformity for speed by excluding the \n  rejection sampling necessary to ensure uniformity, as well as a `biasedInts` methods for generating streams \n  of such integers.\n* Methods for generating random pairs of integers without replacement, and random triples of integers without replacement.\n* Methods for generating random samples of k integers without replacement from a range of integers.\n* Methods to generate streams of numbers from distributions other than uniform, such as streams of random numbers \n  from binomial distributions, Cauchy distributions, exponential distributions, and Gaussian distributions.\n* Methods to generate streams of pairs of distinct integers, and streams of triples of distinct integers.\n* Methods for shuffling the elements of arrays and Lists.\n\nThe \u0026rho;\u0026mu; library is a dependency of some of our other projects, \nincluding [JavaPermutationTools](https://github.com/cicirello/JavaPermutationTools)\nand [Chips-n-Salsa](https://github.com/cicirello/Chips-n-Salsa).\n\n### Table of Contents\n\nThe rest of this README is organized as follows:\n* [UML Class Diagram](#uml-class-diagram): A UML class diagram of the library\n* [Java Requirements](#java-requirements): Minimum supported Java version information\n* [Versioning Scheme](#versioning-scheme): Explanation of the library's version numbers\n* [Building the Library (with Maven)](#building-the-library-with-maven)\n* [Examples](#examples): Information on example library usage\n* [Java Modules](#java-modules): Information for those whose projects use Java modules\n* [Importing from Package Repositories](#importing-from-package-repositories)\n  * [Importing the Library from Maven Central](#importing-the-library-from-maven-central)\n  * [Importing the Library from GitHub Packages](#importing-the-library-from-gitHub-packages)\n* [Downloading Jar Files](#downloading-jar-files): Information on where you can download pre-compiled jars\n* [License](#license): Licensing information\n* [Contribute](#contribute): Information for those who wish to contribute\n\n## UML Class Diagram\n\nThis class diagram summarizes the public classes of \u0026rho;\u0026mu; in relation to Java 17's\nhierarchy of `RandomGenerator` interfaces. Note that for brevity in the diagram, methods are \nomitted. Each class and interface in the diagram is a clickable link to the javadoc page \nthat documents it either within the [documentation of \u0026rho;\u0026mu;](https://rho-mu.cicirello.org/api/) \nfor the classes of the \u0026rho;\u0026mu; library, or within the Java 17 API documentation for Java's `RandomGenerator` interfaces.\n\n```mermaid\nclassDiagram\n  class Statistics\n  class MatrixOps\n  class JacobiDiagonalization\n  class MathFunctions\n  class RandomGenerator\n  \u003c\u003cinterface\u003e\u003e RandomGenerator\n  class StreamableGenerator\n  \u003c\u003cinterface\u003e\u003e StreamableGenerator\n  RandomGenerator \u003c|-- StreamableGenerator\n  class SplittableGenerator\n  \u003c\u003cinterface\u003e\u003e SplittableGenerator\n  StreamableGenerator \u003c|-- SplittableGenerator\n  class JumpableGenerator\n  \u003c\u003cinterface\u003e\u003e JumpableGenerator\n  StreamableGenerator \u003c|-- JumpableGenerator\n  class LeapableGenerator\n  \u003c\u003cinterface\u003e\u003e LeapableGenerator\n  JumpableGenerator \u003c|-- LeapableGenerator\n  class ArbitrarilyJumpableGenerator\n  \u003c\u003cinterface\u003e\u003e ArbitrarilyJumpableGenerator\n  LeapableGenerator \u003c|-- ArbitrarilyJumpableGenerator\n  class EnhancedRandomGenerator\n  EnhancedRandomGenerator : -RandomGenerator generator\n  RandomGenerator \u003c|.. EnhancedRandomGenerator\n  class RandomVariates\n  class IndexPair\n  class RandomSampler\n  class RandomIndexer\n  class Shuffler\n  class IndexTriple\n  RandomIndexer \u003c.. EnhancedRandomGenerator\n  RandomIndexer \u003c.. RandomSampler\n  RandomSampler \u003c.. RandomIndexer\n  RandomSampler \u003c.. EnhancedRandomGenerator\n  RandomIndexer \u003c.. Shuffler\n  Shuffler \u003c.. EnhancedRandomGenerator\n  RandomVariates \u003c.. EnhancedRandomGenerator\n  RandomVariates \u003c.. RandomSampler\n  IndexPair \u003c.. EnhancedRandomGenerator\n  IndexPair \u003c.. RandomIndexer\n  IndexTriple \u003c.. RandomIndexer\n  IndexTriple \u003c.. EnhancedRandomGenerator\n  class EnhancedStreamableGenerator\n  EnhancedStreamableGenerator : -StreamableGenerator generator\n  EnhancedRandomGenerator \u003c|-- EnhancedStreamableGenerator\n  StreamableGenerator \u003c|.. EnhancedStreamableGenerator\n  class EnhancedSplittableGenerator\n  EnhancedSplittableGenerator : -SplittableGenerator generator\n  EnhancedStreamableGenerator \u003c|-- EnhancedSplittableGenerator\n  SplittableGenerator \u003c|.. EnhancedSplittableGenerator\n  class EnhancedJumpableGenerator\n  EnhancedJumpableGenerator : -JumpableGenerator generator\n  EnhancedStreamableGenerator \u003c|-- EnhancedJumpableGenerator\n  JumpableGenerator \u003c|.. EnhancedJumpableGenerator\n  class EnhancedLeapableGenerator\n  EnhancedLeapableGenerator : -LeapableGenerator generator\n  EnhancedJumpableGenerator \u003c|-- EnhancedLeapableGenerator\n  LeapableGenerator \u003c|.. EnhancedLeapableGenerator\n  class EnhancedArbitrarilyJumpableGenerator\n  EnhancedArbitrarilyJumpableGenerator : -ArbitrarilyJumpableGenerator generator\n  EnhancedLeapableGenerator \u003c|-- EnhancedArbitrarilyJumpableGenerator\n  ArbitrarilyJumpableGenerator \u003c|.. EnhancedArbitrarilyJumpableGenerator\n  link RandomIndexer \"https://rho-mu.cicirello.org/api/org.cicirello.rho_mu/org/cicirello/math/rand/RandomIndexer.html\"\n  link RandomVariates \"https://rho-mu.cicirello.org/api/org.cicirello.rho_mu/org/cicirello/math/rand/RandomVariates.html\"\n  link RandomSampler \"https://rho-mu.cicirello.org/api/org.cicirello.rho_mu/org/cicirello/math/rand/RandomSampler.html\"\n  link EnhancedRandomGenerator \"https://rho-mu.cicirello.org/api/org.cicirello.rho_mu/org/cicirello/math/rand/EnhancedRandomGenerator.html\"\n  link EnhancedStreamableGenerator \"https://rho-mu.cicirello.org/api/org.cicirello.rho_mu/org/cicirello/math/rand/EnhancedStreamableGenerator.html\"\n  link EnhancedSplittableGenerator \"https://rho-mu.cicirello.org/api/org.cicirello.rho_mu/org/cicirello/math/rand/EnhancedSplittableGenerator.html\"\n  link EnhancedJumpableGenerator \"https://rho-mu.cicirello.org/api/org.cicirello.rho_mu/org/cicirello/math/rand/EnhancedJumpableGenerator.html\"\n  link EnhancedLeapableGenerator \"https://rho-mu.cicirello.org/api/org.cicirello.rho_mu/org/cicirello/math/rand/EnhancedLeapableGenerator.html\"\n  link EnhancedArbitrarilyJumpableGenerator \"https://rho-mu.cicirello.org/api/org.cicirello.rho_mu/org/cicirello/math/rand/EnhancedArbitrarilyJumpableGenerator.html\"\n  link RandomGenerator \"https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/util/random/RandomGenerator.html\"\n  link StreamableGenerator \"https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/util/random/RandomGenerator.StreamableGenerator.html\"\n  link SplittableGenerator \"https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/util/random/RandomGenerator.SplittableGenerator.html\"\n  link JumpableGenerator \"https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/util/random/RandomGenerator.JumpableGenerator.html\"\n  link LeapableGenerator \"https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/util/random/RandomGenerator.LeapableGenerator.html\"\n  link ArbitrarilyJumpableGenerator \"https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/util/random/RandomGenerator.ArbitrarilyJumpableGenerator.html\"\n  link MathFunctions \"https://rho-mu.cicirello.org/api/org.cicirello.rho_mu/org/cicirello/math/MathFunctions.html\"\n  link Statistics \"https://rho-mu.cicirello.org/api/org.cicirello.rho_mu/org/cicirello/math/stats/Statistics.html\"\n  link MatrixOps \"https://rho-mu.cicirello.org/api/org.cicirello.rho_mu/org/cicirello/math/la/MatrixOps.html\"\n  link JacobiDiagonalization \"https://rho-mu.cicirello.org/api/org.cicirello.rho_mu/org/cicirello/math/la/JacobiDiagonalization.html\"\n  link IndexPair \"https://rho-mu.cicirello.org/api/org.cicirello.rho_mu/org/cicirello/math/rand/IndexPair.html\"\n  link IndexTriple \"https://rho-mu.cicirello.org/api/org.cicirello.rho_mu/org/cicirello/math/rand/IndexTriple.html\"\n  link Shuffler \"https://rho-mu.cicirello.org/api/org.cicirello.rho_mu/org/cicirello/math/rand/Shuffler.html\"\n```\n\n## Java Requirements\n\nWe currently support Java 17+. Our development process utilizes OpenJDK 17, and all\njar files released via Maven Central, GitHub Packages, and GitHub Releases are built\nwith a Java 17 target.  See the following table for a mapping between library version\nand minimum supported Java version.\n\n| version | Java requirements |\n| --- | --- |\n| 2.w.x to 4.y.z | Java 17+ |\n| 1.x.y | Java 11+ |\n\n## Versioning Scheme\n\n\u0026rho;\u0026mu; uses [Semantic Versioning](https://semver.org/) with \nversion numbers of the form: MAJOR.MINOR.PATCH, where differences \nin MAJOR correspond to incompatible API changes, differences in MINOR \ncorrespond to introduction of backwards compatible new functionality, \nand PATCH corresponds to backwards compatible bug fixes. \n\n## Building the Library (with Maven)\n\nThe \u0026rho;\u0026mu; library is built using Maven. The root of the\nrepository contains a Maven `pom.xml`.  To build the library, \nexecute `mvn package` at the root of the repository, which\nwill compile all classes, run all tests, run javadoc, and generate \njar files of the library, the sources, and the javadocs. The file names\nmake this distinction explicit.  All build outputs will then\nbe found in the directory `target`.\n\nTo include generation of a code coverage report during the build,\nexecute `mvn package -Pcoverage` at the root of the repository to \nenable a Maven profile that executes JaCoCo during the test phase.\n\nTo run all static analysis tools (i.e., SpotBugs, Find Security Bugs,\nrefactor-first), execute `mvn package -Panalysis` to enable a Maven \nprofile that executes the various static analysis tools that we are \nusing. The SpotBugs html report will be found in the `target` directory, \nor you can use the SpotBugs GUI with: `mvn spotbugs:gui -Panalysis`. The \nrefactor-first report will be found in the `target/site` directory.\n\nTo run all of the above: `mvn package -P \"analysis,coverage\"`.\n\n## Examples\n\nThe [examples](examples) directory contains source code of a few example\nprograms demonstrating how to use various features of the library. The source\ncode of the examples is commented with explanations where appropriate.\n\nSome of our other projects make extensive use of this library. You may\nconsult the source code of [JavaPermutationTools](https://github.com/cicirello/JavaPermutationTools)\nand/or [Chips-n-Salsa](https://github.com/cicirello/Chips-n-Salsa) for additional\nreal code examples. For example Chips-n-Salsa is a library of parallel and adaptive\nstochastic local search algorithms, and as such requires extensive use of\nrandom number generation.\n\n## Java Modules\n\nThis library provides a Java module, `org.cicirello.rho_mu`. To use in your project,\nadd the following to your `module-info.java`:\n\n```Java\nmodule your.module.name.here {\n\trequires org.cicirello.rho_mu;\n}\n```\n\n## Importing from Package Repositories\n\nPrebuilt artifacts are regularly published to Maven Central and GitHub Packages. In \nmost cases, you'll want to use Maven Central. Releases are published to GitHub Packages \nmainly as a fall-back in the unlikely scenario that Maven Central is unavailable.\n\n### Importing the Library from Maven Central\n\nAdd this to the dependencies section of your pom.xml, replacing \nthe version number with the version that you want to use.\n\n```XML\n\u003cdependency\u003e\n  \u003cgroupId\u003eorg.cicirello\u003c/groupId\u003e\n  \u003cartifactId\u003erho-mu\u003c/artifactId\u003e\n  \u003cversion\u003e4.0.0\u003c/version\u003e\n\u003c/dependency\u003e\n```\n\n### Importing the Library from GitHub Packages\n\nIf you'd prefer to import from GitHub Packages, rather than Maven Central, \nthen: (1) add the dependency as indicated in previous section above, and (2) add \nthe following to the repositories section of your pom.xml:\n\n```XML\n\u003crepository\u003e\n  \u003cid\u003egithub\u003c/id\u003e\n  \u003cname\u003eGitHub cicirello Apache Maven Packages\u003c/name\u003e\n  \u003curl\u003ehttps://maven.pkg.github.com/cicirello/rho-mu\u003c/url\u003e\n\u003c/repository\u003e\n```\n\nNote that GitHub Packages requires authenticating to GitHub. Thus, it is likely less convenient\nthan importing from Maven Central. We mainly provide this option as a backup source of artifacts.\n\n## Downloading Jar Files\n\nIf you don't use a dependency manager that supports importing from Maven Central,\nor if you simply prefer to download manually, prebuilt jars are also attached to \neach [GitHub Release](https://github.com/cicirello/rho-mu/releases). However, be\nsure to also download required versions of dependencies. You should really be using\na dependency manager to ensure that you get this right.\n\n## License\n\nThe \u0026rho;\u0026mu; library is licensed under the [GNU General Public License 3.0](https://www.gnu.org/licenses/gpl-3.0.en.html).\n\n## Contribute\n\nIf you would like to contribute to \u0026rho;\u0026mu; in any way, such \nas reporting bugs, suggesting new functionality, or code contributions \nsuch as bug fixes or implementations of new functionality, then start \nby reading the [contribution guidelines](https://github.com/cicirello/.github/blob/main/CONTRIBUTING.md).\nThis project has adopted \nthe [Contributor Covenant Code of Conduct](https://github.com/cicirello/.github/blob/main/CODE_OF_CONDUCT.md).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcicirello%2Frho-mu","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcicirello%2Frho-mu","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcicirello%2Frho-mu/lists"}