{"id":34072972,"url":"https://github.com/probsys/optimal-approximate-sampling","last_synced_at":"2025-12-14T08:31:59.225Z","repository":{"id":54082946,"uuid":"220839454","full_name":"probsys/optimal-approximate-sampling","owner":"probsys","description":"Optimal approximate sampling from discrete probability distributions","archived":false,"fork":false,"pushed_at":"2021-03-09T16:28:24.000Z","size":66,"stargazers_count":18,"open_issues_count":0,"forks_count":0,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-10-19T12:58:42.560Z","etag":null,"topics":["optimization","popl","python-library","random-numbers","random-sampling","sampler"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/probsys.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2019-11-10T19:27:13.000Z","updated_at":"2025-07-19T19:06:37.000Z","dependencies_parsed_at":"2022-08-13T06:31:40.270Z","dependency_job_id":null,"html_url":"https://github.com/probsys/optimal-approximate-sampling","commit_stats":null,"previous_names":["probcomp/optimal-approximate-sampling"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/probsys/optimal-approximate-sampling","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/probsys%2Foptimal-approximate-sampling","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/probsys%2Foptimal-approximate-sampling/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/probsys%2Foptimal-approximate-sampling/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/probsys%2Foptimal-approximate-sampling/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/probsys","download_url":"https://codeload.github.com/probsys/optimal-approximate-sampling/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/probsys%2Foptimal-approximate-sampling/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":27723272,"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","status":"online","status_checked_at":"2025-12-14T02:00:11.348Z","response_time":56,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["optimization","popl","python-library","random-numbers","random-sampling","sampler"],"created_at":"2025-12-14T08:31:58.512Z","updated_at":"2025-12-14T08:31:59.211Z","avatar_url":"https://github.com/probsys.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Optimal Approximate Sampling From Discrete Probability Distributions\n\nThis repository contains a prototype implementation of the optimal\nsampling algorithms from:\n\n\u003e Feras A. Saad, Cameron E. Freer, Martin C. Rinard, and Vikash K. Mansinghka.\n[Optimal Approximate Sampling From Discrete Probability\nDistributions](https://doi.org/10.1145/3371104).\n_Proc. ACM Program. Lang._ 4, POPL, Article 36 (January 2020), 33 pages.\n\n## Installing\n\nThe Python 3 library can be installed via pip:\n\n    pip install optas\n\nThe C code for the main sampler is in the `c/` directory and the\nPython 3 libraries are in the `src/` directory.\n\nOnly Python 3 is required to build and use the software from source.\n\n    $ git clone https://github.com/probcomp/optimal-approximate-sampling\n    $ cd optimal-approximate-sampling\n    $ python setup.py install\n\nTo build the C sampler\n\n    $ cd c \u0026\u0026 make all\n\n## Usage\n\nPlease refer to the examples in the [examples](./examples) directory.\nGiven a fixed target distribution and error measure:\n\n1. [./examples/sampling.py](./examples/sampling.py) shows an example of how\n   to find an optimal distribution and sample from it, given a\n   user-specified precision.\n\n2. [./examples/maxerror.py](./examples/maxerror.py) shows an example of how\n   to find an optimal distribution that uses the least possible precision\n   and obtains an error that is less than a user-specified maximum\n   allowable error.\n\nThese examples can be run directly as follows:\n\n    $ ./pythenv.sh python examples/sampling.py\n    $ ./pythenv.sh python examples/maxerror.py\n\n## Tests\n\nTo test the Python library and run a crash test in C (requires\n[pytest](https://docs.pytest.org/en/latest/) and\n[scipy](https://scipy.org/)):\n\n    $ ./check.sh\n\n## Experiments\n\nThe code for experiments in the POPL publication is available in a tarball\non the ACM Digital Library. Please refer to the online supplementary\nmaterial at https://doi.org/10.1145/3371104.\n\n## Citing\n\nPlease use the following BibTeX to cite this work.\n\n    @article{saad2020sampling,\n    title          = {Optimal approximate sampling from discrete probability distributions},\n    author         = {Saad, Feras A. and Freer, Cameron E. and Rinard, Martin C. and Mansinghka, Vikash K.},\n    journal        = {Proc. ACM Program. Lang.},\n    volume         = 4,\n    number         = {POPL},\n    month          = jan,\n    year           = 2020,\n    pages          = {36:1--36:31},\n    numpages       = 31,\n    publisher      = {ACM},\n    doi            = {10.1145/3371104},\n    abstract       = {This paper addresses a fundamental problem in random variate generation: given access to a random source that emits a stream of independent fair bits, what is the most accurate and entropy-efficient algorithm for sampling from a discrete probability distribution $(p_1, \\dots, p_n)$, where the output distribution $(\\hat{p}_1, \\dots, \\hat{p}_n)$ of the sampling algorithm can be specified with a given level of bit precision? We present a theoretical framework for formulating this problem and provide new techniques for finding sampling algorithms that are optimal both statistically (in the sense of sampling accuracy) and information-theoretically (in the sense of entropy consumption). We leverage these results to build a system that, for a broad family of measures of statistical accuracy, delivers a sampling algorithm whose expected entropy usage is minimal among those that induce the same distribution (i.e., is ``entropy-optimal'') and whose output distribution $(\\hat{p}_1, \\dots, \\hat{p}_n)$ is a closest approximation to the target distribution $(p_1, \\dots, p_n)$ among all entropy-optimal sampling algorithms that operate within the specified precision budget. This optimal approximate sampler is also a closer approximation than any (possibly entropy-suboptimal) sampler that consumes a bounded amount of entropy with the specified precision, a class which includes floating-point implementations of inversion sampling and related methods found in many standard software libraries. We evaluate the accuracy, entropy consumption, precision requirements, and wall-clock runtime of our optimal approximate sampling algorithms on a broad set of probability distributions, demonstrating the ways that they are superior to existing approximate samplers and establishing that they often consume significantly fewer resources than are needed by exact samplers.},\n    }\n\n## Related Repositories\n\nFor a near-optimal exact dice rolling algorithm see\nhttps://github.com/probcomp/fast-loaded-dice-roller.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fprobsys%2Foptimal-approximate-sampling","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fprobsys%2Foptimal-approximate-sampling","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fprobsys%2Foptimal-approximate-sampling/lists"}