{"id":40776702,"url":"https://github.com/nessan/xoshiro","last_synced_at":"2026-01-21T19:11:50.394Z","repository":{"id":252809241,"uuid":"841526792","full_name":"nessan/xoshiro","owner":"nessan","description":"C++ header-only library for the full family of Xoshiro/Xoroshiro random number generators","archived":false,"fork":false,"pushed_at":"2025-08-28T15:51:27.000Z","size":1477,"stargazers_count":19,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-08-28T22:45:35.474Z","etag":null,"topics":["parallel-computing","random-number-generators","transition-matrix","xoshiro","xoshiro256"],"latest_commit_sha":null,"homepage":"https://nessan.github.io/xoshiro","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nessan.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2024-08-12T15:26:45.000Z","updated_at":"2025-08-26T10:22:23.000Z","dependencies_parsed_at":"2025-01-08T11:20:18.482Z","dependency_job_id":"73e3212a-0f4b-4828-a884-41c61315691f","html_url":"https://github.com/nessan/xoshiro","commit_stats":null,"previous_names":["nessan/xoshiro"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/nessan/xoshiro","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nessan%2Fxoshiro","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nessan%2Fxoshiro/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nessan%2Fxoshiro/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nessan%2Fxoshiro/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nessan","download_url":"https://codeload.github.com/nessan/xoshiro/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nessan%2Fxoshiro/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28640509,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-21T18:04:35.752Z","status":"ssl_error","status_checked_at":"2026-01-21T18:03:55.054Z","response_time":86,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":["parallel-computing","random-number-generators","transition-matrix","xoshiro","xoshiro256"],"created_at":"2026-01-21T19:11:48.564Z","updated_at":"2026-01-21T19:11:50.386Z","avatar_url":"https://github.com/nessan.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"# README\n\nDavid Blackman and Sebastiano Vigna introduced the [xoshiro/xoroshiro][] class of pseudorandom number generators, which are very efficient and, though they have relatively small states, display excellent statistical properties. The mathematical details are to be found in their [paper][].\n\n`xoshiro.h` is a single header file, `C++` implementation of the _complete_ family of [xoshiro/xoroshiro][] pseudorandom uniform number generators.\n\nThe generators satisfy `C++`'s [`std::uniform_random_bit_generator`][] concept and can drive any distribution defined in the standard library.\n\nWe also provide efficient jump-ahead methods for *arbitrary* jump sizes, making these generators particularly suitable for parallel processing applications. They are excellent replacements for the \"standard\" _Mersenne Twister_ generator.\n\nWhile the implementation is very general, there are simple type aliases for specific preferred instantiations that are known to work well in most situations.\n\n## Example\n\nHere is a simple example of using the _default xoshiro_ generator, `xso::rng`, to sample a normal distribution from the standard library.\n\nWe have copied the sample code from [`std::normal_distribution`][] webpage and used `xso::rng` as a drop-in replacement for [`std::mersenne_twister_engine`][].\n\n```cpp\n#include \u003cxoshiro.h\u003e\n#include \u003crandom\u003e\n#include \u003cmap\u003e\n#include \u003ciomanip\u003e\n\nint main()\n{\n    xso::rng gen;\n\n    // lambda: draws a sample from a normal distribution and rounds it to an integer.\n    std::normal_distribution d{5.0, 2.0};\n    auto random_int = [\u0026d, \u0026gen] { return int(std::round(dist(gen))); };\n\n    // Run many trials and create a histogram of the results in integer buckets.\n    std::map\u003cint, int\u003e hist{};\n    for (int n = 0; n != 25'000; ++n) ++hist[random_int()];\n\n    // Print that histogram.\n    for (auto [bucket, count] : hist) {\n        auto n = static_cast\u003cstd::size_t\u003e(count / 100);\n        std::cout \u003c\u003c std::setw(2) \u003c\u003c bucket \u003c\u003c ' ' \u003c\u003c std::string(n, '*') \u003c\u003c '\\n';\n    }\n}\n```\n\nEverything is in the single `xoshiro.h` header file. The classes, functions etc., are all in the `xso` namespace. `xso::rng` is a type alias for `xso::rng64` which produces 64-bit outputs from a specific _xoshiro_ generator with 256 bits of state.\n\nHere is the output from one run of the program:\n\n```sh\n-3\n-2\n-1\n 0 **\n 1 *******\n 2 ****************\n 3 *****************************\n 4 ********************************************\n 5 ************************************************\n 6 ********************************************\n 7 *****************************\n 8 ****************\n 9 *******\n10 **\n11\n12\n14\n```\n\n## Installation\n\nThis library is header-only, so there is nothing to compile \u0026 link—drop the `xoshiro.h` file somewhere convenient, and you are good to go.\n\nAlternatively, if you are using `CMake`, you can use the standard `FetchContent` module by adding a few lines to your project's `CMakeLists.txt` file:\n\n```cmake\ninclude(FetchContent)\nFetchContent_Declare(xoshiro URL https://github.com/nessan/bit/releases/download/current/xoshiro.zip)\nFetchContent_MakeAvailable(xoshiro)\n```\n\nThis command downloads and unpacks an archive of the current version of `xoshiro` to your project's build folder. You can then add a dependency on `xoshiro::xoshiro`, a `CMake` alias for `xoshiro`. `FetchContent` will automatically ensure the build system knows where to find the downloaded header files and any needed compiler flags.\n\nUsed like this, `FetchContent` will only download a minimal library version without any redundant test code, sample programs, documentation files, etc.\n\n## Implementation\n\n`C` versions of the generators are available on the author's [website][xoshiro/xoroshiro].\nWrapping those routines so they conform to the [`std::uniform_random_bit_generator`][] concept is a trivial exercise.\n\nHowever, our implementation in `xoshiro.h` is distinguished in several other ways:\n\n### Generality\n\nUsing `xoshiro.h`, you can create _any_ member of the _xoshiro/xoroshiro_ family.\n\nWe have `State` classes that are templatised across the number of state bits and the parameters (labelled `A`, `B`, and `C` in the literature) that determine how the state is advanced from step to step.\n\n`Scrambler` classes are templatised across the other parameters (labelled `R`, `S`, and `T` in the literature) that determine how the higher dimensional state is scrambled/reduced to single 3-bit or 64-bit output words.\n\nThis means you can instantiate _any_ generator in the _xoshiro/xoroshiro_ family.\n\n### No Compromise on Speed\n\nFor the reasonable optimisation levels you are likely to employ in any numerical code, the C++ versions perform identically to the simpler-looking `C` versions linked above.\n\n### Simplicity\n\nWhile you can instantiate _any_ generator in the _xoshiro/xoroshiro_ family, we also recognise that only a limited number of those generators have been vetted for suitability as being \"good\".\n\nTherefore, we provide some _type aliases_ for the recommended default generators you should use in most cases.\n\n### Arbitrary Jumps\n\nWe provide methods to advance a generator by _arbitrary_ and potentially vast numbers of steps. This contrasts with the `C` versions, which only define a limited number of jump possibilities.\n\nHuge jumps are used to _partition_ a single random number stream into non-overlapping sub-streams. In parallel processing applications, the sub-streams drive independent jobs running on different compute cores.\n\n### Sampling Methods\n\nThe `C++` standard library follows a typical design pattern for the facilities in its [`\u003crandom\u003e`][] header. It maintains a strict separation between the classes that produce random bits and others that use those bits.\n\nUniform random bit generators produce streams of _uniformly_ distributed output words (usually 32-bit or 64-bit unsigned integers). Other classes and functions shape those core streams to simulate a desired distribution over some field of interest (for example, to generate variates from a uniform distribution of reals in the range 0 to 1).\n\nThe idea is reasonable enough. You can swap out the uniform random bit generator for a better one and continue to use the other functions without change.\n\nHowever, this interface is quite complicated for the end user—particularly for a user who has no idea or interest in how all the generator/distribution machinery works.\nPerhaps you google \"`c++ random number generator`\" and get advice to use the [`std::mersenne_twister_engine`][] class. However, that produces those unsigned output words that are useless by themselves. To simulate something as simple as a die roll, you must feed the thing into some other class and use that to get the required effect.\n\nFor this reason, we enrich our _xoshiro/xoroshiro_ classes with some utility methods that interface directly with the various distribution classes in the standard [`\u003crandom\u003e`][] header.\nThat dice roll becomes something as simple as:\n\n```cpp\nxso::rng gen;\nstd::cout \u003c\u003c \"Six-sided dice roll: \" \u003c\u003c gen.roll() \u003c\u003c '\\n';\n```\n\nSimilarly, you can ask one of our generators to flip a coin or shuffle the elements in a container.\n\nPerhaps most importantly, the generators directly support the idea of _sampling_.\nThis includes pulling samples from a range, container, or an arbitrary distribution.\n\nHere are some examples:\n\n```cpp\nstd::cout \u003c\u003c gen.sample(1, 10)   \u003c\u003c '\\n';   // \u003c1\u003e\nstd::cout \u003c\u003c gen.sample(1., 10.) \u003c\u003c '\\n';   // \u003c2\u003e\n\nstd::normal_distribution nd{70., 15.};\nstd::cout \u003c\u003c gen.sample(nd);                // \u003c3\u003e\n\nstd::array\u003cdouble, 10\u003e v;\ngen.sample(nd, v.begin(), v.word_count());  // \u003c4\u003e\n\nstd::array\u003cdouble, 5\u003e u;\ngen.sample(v, u.begin(), u.word_count());   // \u003c5\u003e\n\nge.shuffle(u);                              // \u003c6\u003e\n```\n\n1. Prints a random integer from $[1,10]$,  where each integer is equally likely to occur.\n2. Prints a random real from a uniform distribution over $[1,10)$\n3. Prints a random variate from a normal distribution with a mean of 70 and a standard deviation of 15.\n4. Fills an array `v` with ten random variates from that same distribution.\n5. Fills an array `u` with five elements drawn from `v` without replacement.\n6. Shuffles the elements of `u`.\n\n### Extra Analysis\n\nExtra non-member functions for generator analysis are defined if the [`bit`][] library is available.\n\n`bit` is a `C++` library for doing linear algebra over [GF(2)][] the simplest field of two elements $\\{0,1\\}$, where the usual arithmetic operations are performed mod 2.\nThe `bit` library is header only and is easily incorporated into any application.\n\nIf it is available, then `xoshiro.h` defines some extra functions that let you access the generator's _transition matrix_ and use/analyse it in various ways.\n\n## Documentation\n\nYou can read the project's documentation [here](https://nessan.github.io/xoshiro/). \\\nThe documentation site was generated using [Quarto](https://quarto.org).\n\n### Contact\n\nYou can contact me by email [here](mailto:nzznfitz+gh@icloud.com).\n\n### Copyright and License\n\nCopyright (c) 2022-present Nessan Fitzmaurice. \\\nYou can use this software under the [MIT license](https://opensource.org/license/mit).\n\n\u003c!-- Reference Links --\u003e\n\n[xoshiro/xoroshiro]: https://prng.di.unimi.it\n[paper]: https://vigna.di.unimi.it/ftp/papers/ScrambledLinear.pdf\n[`std::uniform_random_bit_generator`]: https://en.cppreference.com/w/cpp/numeric/random/uniform_random_bit_generator\n[`std::normal_distribution`]: https://en.cppreference.com/w/cpp/numeric/random/normal_distribution\n[`\u003crandom\u003e`]: https://en.cppreference.com/w/cpp/header/random\n[`std::mersenne_twister_engine`]: https://en.cppreference.com/w/cpp/numeric/random/mersenne_twister_engine\n[`bit`]: https://nessan.github.io/bit\n[GF(2)]: https://en.wikipedia.org/wiki/GF(2)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnessan%2Fxoshiro","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnessan%2Fxoshiro","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnessan%2Fxoshiro/lists"}