From 614c2c3f073b9528342b6059d1e515a66a2394a4 Mon Sep 17 00:00:00 2001 From: Chris Rackauckas Date: Mon, 6 Jun 2022 12:15:11 -0400 Subject: [PATCH] add real docs --- .github/workflows/Documentation.yml | 25 ++++++++ Project.toml | 1 + README.md | 9 ++- docs/.gitignore | 2 + docs/Project.toml | 6 ++ docs/make.jl | 19 ++++++ docs/pages.jl | 6 ++ docs/src/index.md | 97 +++++++++++++++++++++++++++++ docs/src/pois_rand.md | 5 ++ src/PoissonRandom.jl | 20 ++++++ test/REQUIRE | 1 - 11 files changed, 189 insertions(+), 2 deletions(-) create mode 100644 .github/workflows/Documentation.yml create mode 100644 docs/.gitignore create mode 100644 docs/Project.toml create mode 100644 docs/make.jl create mode 100644 docs/pages.jl create mode 100644 docs/src/index.md create mode 100644 docs/src/pois_rand.md delete mode 100644 test/REQUIRE diff --git a/.github/workflows/Documentation.yml b/.github/workflows/Documentation.yml new file mode 100644 index 0000000..3f6eb3c --- /dev/null +++ b/.github/workflows/Documentation.yml @@ -0,0 +1,25 @@ +name: Documentation + +on: + push: + branches: + - master + - 'release-' + tags: '*' + pull_request: + +jobs: + build: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v2 + - uses: julia-actions/setup-julia@latest + with: + version: '1' + - name: Install dependencies + run: julia --project=docs/ -e 'using Pkg; Pkg.develop(PackageSpec(path=pwd())); Pkg.instantiate()' + - name: Build and deploy + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} # For authentication with GitHub Actions token + DOCUMENTER_KEY: ${{ secrets.DOCUMENTER_KEY }} # For authentication with SSH deploy key + run: julia --project=docs/ docs/make.jl diff --git a/Project.toml b/Project.toml index a2739d8..886b5c1 100644 --- a/Project.toml +++ b/Project.toml @@ -1,5 +1,6 @@ name = "PoissonRandom" uuid = "e409e4f3-bfea-5376-8464-e040bb5c01ab" +version = "0.4.1" [deps] Random = "9a3f8284-a2c9-5f02-9a11-845980a1fd5c" diff --git a/README.md b/README.md index db36eb9..1b5722b 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,14 @@ -# PoissonRandom +# PoissonRandom.jl: Fast Poisson Random Numbers [![Build Status](https://github.com/SciML/PoissonRandom.jl/workflows/CI/badge.svg)](https://github.com/SciML/PoissonRandom.jl/actions?query=workflow%3ACI) +## Tutorials and Documentation + +For information on using the package, +[see the stable documentation](https://poissonrandom.sciml.ai/stable/). Use the +[in-development documentation](https://poissonrandom.sciml.ai/dev/) for the version of +the documentation, which contains the unreleased features. + ## Usage ```julia diff --git a/docs/.gitignore b/docs/.gitignore new file mode 100644 index 0000000..a303fff --- /dev/null +++ b/docs/.gitignore @@ -0,0 +1,2 @@ +build/ +site/ diff --git a/docs/Project.toml b/docs/Project.toml new file mode 100644 index 0000000..ebeb450 --- /dev/null +++ b/docs/Project.toml @@ -0,0 +1,6 @@ +[deps] +PoissonRandom = "e409e4f3-bfea-5376-8464-e040bb5c01ab" +Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4" + +[compat] +Documenter = "0.27" diff --git a/docs/make.jl b/docs/make.jl new file mode 100644 index 0000000..7f42f6f --- /dev/null +++ b/docs/make.jl @@ -0,0 +1,19 @@ +using Documenter, PoissonRandom + +include("pages.jl") + +makedocs( + sitename="PoissonRandom.jl", + authors="Chris Rackauckas", + modules=[PoissonRandom], + clean=true,doctest=false, + format = Documenter.HTML(analytics = "UA-90474609-3", + assets = ["assets/favicon.ico"], + canonical="https://poissonrandom.sciml.ai/stable/"), + pages=pages +) + +deploydocs( + repo = "github.com/SciML/PoissonRandom.jl.git"; + push_preview = true +) diff --git a/docs/pages.jl b/docs/pages.jl new file mode 100644 index 0000000..e1e30f6 --- /dev/null +++ b/docs/pages.jl @@ -0,0 +1,6 @@ +# Put in a separate page so it can be used by SciMLDocs.jl + +pages=[ + "Home" => "index.md", + "pois_rand.md", +] \ No newline at end of file diff --git a/docs/src/index.md b/docs/src/index.md new file mode 100644 index 0000000..3c034e8 --- /dev/null +++ b/docs/src/index.md @@ -0,0 +1,97 @@ +# PoissonRandom.jl: Fast Poisson Random Numbers + +PoissonRandom.jl is a component of the SciML ecosystem which allows +for fast generation of Poisson random numbers. + +## Installation + +To install ParameterizedFunctions.jl, use the Julia package manager: + +```julia +using Pkg +Pkg.add("PoissonRandom") +``` + +## Usage + +```julia +# Simple Poisson random +pois_rand(λ) + +# Using another RNG +using RandomNumbers +rng = Xorshifts.Xoroshiro128Plus() +pois_rand(rng,λ) +``` + +## Implementation + +It mixes two methods. A simple count method and a method from a normal approximation. +See [this blog post for details](https://www.johndcook.com/blog/2010/06/14/generating-poisson-random-values/). + +## Benchmark + +```julia +using RandomNumbers, Distributions, BenchmarkTools, StaticArrays, + RecursiveArrayTools, Plots, PoissonRandom +labels = ["count_rand","ad_rand","pois_rand","Distributions.jl"] +rng = Xorshifts.Xoroshiro128Plus() + +function n_count(rng,λ,n) + tmp = 0 + for i in 1:n + tmp += PoissonRandom.count_rand(rng,λ) + end +end + +function n_pois(rng,λ,n) + tmp = 0 + for i in 1:n + tmp += pois_rand(rng,λ) + end +end + +function n_ad(rng,λ,n) + tmp = 0 + for i in 1:n + tmp += PoissonRandom.ad_rand(rng,λ) + end +end + +function n_dist(λ,n) + tmp = 0 + for i in 1:n + tmp += rand(Poisson(λ)) + end +end + +function time_λ(rng,λ,n) + t1 = @elapsed n_count(rng,λ,n) + t2 = @elapsed n_ad(rng,λ,n) + t3 = @elapsed n_pois(rng,λ,n) + t4 = @elapsed n_dist(λ,n) + @SArray [t1,t2,t3,t4] +end + +# Compile +time_λ(rng,5,5000000) +# Run with a bunch of λ +times = VectorOfArray([time_λ(rng,n,5000000) for n in 1:20])' +plot(times,labels = labels, lw = 3) +``` + +![benchmark result](https://user-images.githubusercontent.com/1814174/40387004-1e377776-5dc0-11e8-88a2-2d9cb12db984.png) + +So this package ends up about 30% or so faster than Distributions.jl (the method +at the far edge is λ-independent so that goes on forever). + +## Contributing + +- Please refer to the + [SciML ColPrac: Contributor's Guide on Collaborative Practices for Community Packages](https://github.com/SciML/ColPrac/blob/master/README.md) + for guidance on PRs, issues, and other matters relating to contributing to SciML. +- There are a few community forums: + - the #diffeq-bridged channel in the [Julia Slack](https://julialang.org/slack/) + - [JuliaDiffEq](https://gitter.im/JuliaDiffEq/Lobby) on Gitter + - on the [Julia Discourse forums](https://discourse.julialang.org) + - see also [SciML Community page](https://sciml.ai/community/) diff --git a/docs/src/pois_rand.md b/docs/src/pois_rand.md new file mode 100644 index 0000000..fb2f463 --- /dev/null +++ b/docs/src/pois_rand.md @@ -0,0 +1,5 @@ +# Poisson Random API + +```@docs +pois_rand +``` \ No newline at end of file diff --git a/src/PoissonRandom.jl b/src/PoissonRandom.jl index d296060..61bccc5 100644 --- a/src/PoissonRandom.jl +++ b/src/PoissonRandom.jl @@ -141,6 +141,26 @@ function procf(λ, K::Int, s::Float64) return px,py,fx,fy end +""" +```julia +pois_rand(λ) +pois_rand(rng::AbstractRNG, λ) +``` + +Generates Poisson(λ) distributed random numbers using a fast polyalgorithm. + +## Examples + +```julia +# Simple Poisson random +pois_rand(λ) + +# Using another RNG +using RandomNumbers +rng = Xorshifts.Xoroshiro128Plus() +pois_rand(rng,λ) +``` +""" pois_rand(λ) = pois_rand(Random.GLOBAL_RNG, λ) pois_rand(rng::AbstractRNG, λ) = λ < 6 ? count_rand(rng, λ) : ad_rand(rng, λ) diff --git a/test/REQUIRE b/test/REQUIRE deleted file mode 100644 index 484f501..0000000 --- a/test/REQUIRE +++ /dev/null @@ -1 +0,0 @@ -Distributions