https://github.com/cicirello/zigguratgaussian
Fast Gaussian distributed pseudorandom number generation in Java via the Ziggurat algorithm
https://github.com/cicirello/zigguratgaussian
gaussian gaussian-distribution java normal normal-distribution ziggurat ziggurat-algorithm
Last synced: 11 months ago
JSON representation
Fast Gaussian distributed pseudorandom number generation in Java via the Ziggurat algorithm
- Host: GitHub
- URL: https://github.com/cicirello/zigguratgaussian
- Owner: cicirello
- License: gpl-3.0
- Created: 2019-08-09T19:12:30.000Z (almost 7 years ago)
- Default Branch: master
- Last Pushed: 2025-06-17T22:47:19.000Z (12 months ago)
- Last Synced: 2025-06-17T23:32:19.564Z (12 months ago)
- Topics: gaussian, gaussian-distribution, java, normal, normal-distribution, ziggurat, ziggurat-algorithm
- Language: Java
- Homepage:
- Size: 516 KB
- Stars: 7
- Watchers: 2
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
- Citation: CITATION.cff
- Zenodo: .zenodo.json
Awesome Lists containing this project
README
# Ziggurat Gaussian
[
](#ziggurat-gaussian)
Copyright (C) 2015, 2017-2024 [Vincent A. Cicirello](https://www.cicirello.org/).
| __Packages and Releases__ | [](https://central.sonatype.com/artifact/org.cicirello/ziggurat/) [](https://github.com/cicirello/ZigguratGaussian/releases) |
| :--- | :--- |
| __Build Status__ | [](https://github.com/cicirello/ZigguratGaussian/actions/workflows/build.yml) [](https://github.com/cicirello/ZigguratGaussian/actions/workflows/codeql-analysis.yml) |
| __JaCoCo Test Coverage__ | [](https://github.com/cicirello/ZigguratGaussian/actions/workflows/build.yml) [](https://github.com/cicirello/ZigguratGaussian/actions/workflows/build.yml) |
| __Security__ | [](https://snyk.io/vuln/maven%3Aorg.cicirello%3Aziggurat) [](https://snyk.io/test/github/cicirello/ZigguratGaussian) |
| __DOI__ | [](https://zenodo.org/badge/latestdoi/201526811) |
| __Other Information__ | [](https://github.com/cicirello/ZigguratGaussian/blob/master/LICENSE) [](https://google.github.io/styleguide/javaguide.html) |
| __Support__ | [](https://github.com/sponsors/cicirello) [](https://liberapay.com/cicirello) [](https://ko-fi.com/cicirello) |
## Fast Gaussian distributed pseudorandom number generation in Java via the Ziggurat algorithm
This repository contains a Java implementation of the Ziggurat
algorithm for generating Gaussian distributed pseudorandom numbers.
The Ziggurat algorithm is significantly faster than the more commonly encountered
Polar method, and has some other desirable statistical properties.
The ZigguratGaussian class is a Java port of the GNU Scientific
Library's C implementation (Voss, 2005) of the Ziggurat method.
In porting to Java, we have made several optimizations, the details of
which can be found in the source code comments, which highlights any
differences between this Java implementation and the
C implementation on which it is based.
This Java implementation originated as part of an effort to speed
up the runtime of a parallel genetic algorithm (PGA). The PGA in
question evolved its control parameters (i.e., crossover and mutation rates,
etc) using Gaussian mutation. The only Gaussian implementation within the
Java API is the polar method (nextGaussian method of the Random and
ThreadLocalRandom classes, however the polar method is quite slow
relative to other newer available alternatives, such as the Ziggurat method.
## When to Use This Library
The following table summarizes when this library will speed up Gaussian random
number generation relative to Java's builtin functionality:
| Java Version | Significantly Faster For |
| --- | --- |
| Java 11 ≤ version < Java 17 | `Random`, `SecureRandom`, `SplittableRandom`,`ThreadLocalRandom` |
| Java version ≥ Java 17 | `Random`, `SecureRandom`, `ThreadLocalRandom` |
Source code and data of experiments with Java 17 can be found in
the [experiment](experiment) directory. The following paper discusses
experiments using the library with Java 17. In Java 17, several enhancements
to random number generation were introduced, including several new random number
geenrators a RandomGenerator interface, and a modified ziggurat for the new random
number generators as well as for `SplittableRandom`. The other legacy generators
still use the slow polar method, however. This report explores how and where our
ziggurat library is still relevant in Java 17.
> Vincent A. Cicirello. 2024. [Fast Gaussian Distributed Pseudorandom Number Generation in Java via the Ziggurat Algorithm](https://reports.cicirello.org/24/009/). arXiv:[2405.19493](https://arxiv.org/abs/2405.19493), May 2024. doi:[10.48550/arXiv.2405.19493](https://doi.org/10.48550/arXiv.2405.19493). [[PDF]](https://reports.cicirello.org/24/009/ALG-24-009.pdf)
You can find some additional experimental data comparing the performance of a sequential
genetic algorithm (GA) using this implementation of the Ziggurat method for
Gaussian mutation vs using the more common polar method, as well as experimental data
for the same comparison but with a PGA, in the following paper:
> V. A. Cicirello. [Impact of Random Number Generation on Parallel Genetic Algorithms](https://www.cicirello.org/publications/cicirello2018flairs.html). *Proceedings of the Thirty-First International Florida Artificial Intelligence Research Society Conference*, pages 2-7. AAAI Press, May 2018. [[PDF]](https://www.cicirello.org/publications/cicirello-flairs2018.pdf).
## Background on the Algorithm Itself
See the following articles for detailed description of the Ziggurat algorithm itself, as well as
additional experimental data:
* G. Marsaglia and W. W. Tsang. [The ziggurat method for generating random variables](http://www.jstatsoft.org/v05/i08/). *Journal of Statistical Software*. 5(1):1–7, 2000.
* P. H. W. Leong, G. Zhang, D. Lee, W. Luk, and J. Villasenor. [A Comment on the Implementation of the Ziggurat Method](https://www.jstatsoft.org/article/view/v012i07). *Journal of Statistical Software*. 12(7):1–4, 2005.
* J. Voss. [The Ziggurat Method for Generating Gaussian Random Numbers](http://www.seehuhn.de/pages/ziggurat). GSL: GNU Scientific Library. 2005.
## See [ρμ](https://github.com/cicirello/rho-mu) for Expanded Functionality
The entirety of this library has been absorbed
by [ρμ, a Java library of Randomization enHancements and Other Math Utilities](https://github.com/cicirello/rho-mu), which
includes additional enhanced random number generation, among other related functionality. However, [ρμ](https://rho-mu.cicirello.org/)
requires Java 17+, whereas this Ziggurat implementation supports Java 11+.
## Versioning Scheme
The library 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.
## Java 11+
The jars of the library, distributed via Maven Central, GitHub Packages,
and GitHub Releases, are built with OpenJDK 17 but for a target of Java 11.
## 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 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
ziggurat
1.0.5
```
### Importing 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/ZigguratGaussian
```
Note that GitHub Packages requires authenticating to GitHub.
### 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/ZigguratGaussian/releases).
## Build with Maven
If you want to build from the source, then execute `mvn package` at the root
of the repository. The library should build with Java 11+.
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"`.
## License
The example programs in this repository are licensed under
the [GNU General Public License 3.0](https://www.gnu.org/licenses/gpl-3.0.en.html).