From 4d30a294717f32bc58d259481db9363cf6b8298d Mon Sep 17 00:00:00 2001 From: David Widmann Date: Wed, 12 Jun 2024 02:27:27 +0200 Subject: [PATCH 1/2] Start sequence at zero --- .gitignore | 1 + Project.toml | 2 +- README.md | 21 +++++++++++++------ sobol1024.png | Bin 30809 -> 28274 bytes src/Sobol.jl | 53 ++++++++++++++++++++++++++--------------------- test/runtests.jl | 17 +++++++++------ 6 files changed, 57 insertions(+), 37 deletions(-) create mode 100644 .gitignore diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..2251642 --- /dev/null +++ b/.gitignore @@ -0,0 +1 @@ +Manifest.toml \ No newline at end of file diff --git a/Project.toml b/Project.toml index dc2faec..cef11b8 100644 --- a/Project.toml +++ b/Project.toml @@ -1,6 +1,6 @@ name = "Sobol" uuid = "ed01d8cd-4d21-5b2a-85b4-cc3bdc58bad4" -version = "1.5.0" +version = "2.0.0" [deps] DelimitedFiles = "8bb1440f-4735-579b-a4ab-409b98df4dab" diff --git a/README.md b/README.md index fe9c3da..b488bb3 100644 --- a/README.md +++ b/README.md @@ -96,10 +96,9 @@ where `lb` and `ub` are arrays (or other iterables) of length `N`, giving the lower and upper bounds of the hypercube, respectively. For example, `SobolSeq([-1,0,0],[1,3,2])` generates points in the box [-1,1]×[0,3]×[0,2]. (Although the generated points are `Float64` by default, in general the precision is determined by that of `lb` and `ub`.) -If you know in advance the number `n` of points that you plan to -generate, some authors suggest that better uniformity can be attained -by first skipping the initial portion of the LDS. In particular, -we skip 2ᵐ−1 for the largest `m` where `2ᵐ-1 ≤ n` (see [Joe and Kuo, 2003][joe03] for a similar suggestion). This +If you know in advance the number `n` of points that you plan to generate, +some authors suggest that skipping the initial portion of the LDS. +In particular, we skip 2ᵐ points for the largest `m` where `2ᵐ ≤ n` (see [Joe and Kuo, 2003][joe03] for a similar suggestion). This facility is provided by: ```julia skip(s, n) @@ -111,8 +110,15 @@ Skipping exactly `n` elements is also possible: skip(s, n, exact=true) ``` +Note, however, that generally it is not recommended to skip (arbitrary) +number of points since this can ruin the digital net property and lead +to worse convergence (as illustrated in [Owen, 2021](https://arxiv.org/abs/2008.08051) for the +common proactice of dropping the initial point). + `skip` returns `s`, so you can simply do `s = skip(SobolSeq(N))` or similar. +Note, however, that generally it is not recommended to skip arbitrary + ## Example Here is a simple example, generating 1024 points in two dimensions and @@ -123,9 +129,12 @@ the [0,1]×[0,1] unit square! using Sobol using PyPlot s = SobolSeq(2) -p = reduce(hcat, next!(s) for i = 1:1024)' +p = Matrix{Float64}(undef, 2, 1024) +for x in eachcol(p) + next!(s, x) +end subplot(111, aspect="equal") -plot(p[:,1], p[:,2], "r.") +plot(p[1, :], p[2, :], "r.") ``` ![plot of 1024 points of a 2d Sobol sequence](sobol1024.png "1024 points of a 2d Sobol sequence") diff --git a/sobol1024.png b/sobol1024.png index ba253a19245d051c0a5b70b846c6c2a791850607..1a58c37906825c1774c8271e75fd02c74c80b1a3 100644 GIT binary patch literal 28274 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 bXdC;jC8f(R3@-IUEpqLOwp#h+JHh`CakB)m literal 30809 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 ZIrGjqGj<|= c - @inbounds sx[i] = sx[i] ⊻ (sm[i,c+1] << (b-c)) - @inbounds x[i] = ldexp(Float64(sx[i]), ((~b) % Int32)) - else - @inbounds sx[i] = (sx[i] << (c-b)) ⊻ sm[i,c+1] - @inbounds sb[i] = c - @inbounds x[i] = ldexp(Float64(sx[i]), ((~c) % Int32)) + + if iszero(s.n) + # Initial point + fill!(x, 0.0) + else + # Subsequent points + c = UInt32(trailing_zeros(s.n)) + sb = s.b + sx = s.x + sm = s.m + for i=1:ndims(s) + @inbounds b = sb[i] + # note: ldexp on Float64(sx[i]) is exact, independent of precision of x[i] + if b >= c + @inbounds sx[i] = sx[i] ⊻ (sm[i,c+1] << (b-c)) + @inbounds x[i] = ldexp(Float64(sx[i]), ((~b) % Int32)) + else + @inbounds sx[i] = (sx[i] << (c-b)) ⊻ sm[i,c+1] + @inbounds sb[i] = c + @inbounds x[i] = ldexp(Float64(sx[i]), ((~c) % Int32)) + end end end + + s.n += one(s.n) + return x end next!(s::SobolSeq) = next!(s, Array{Float64,1}(undef, ndims(s))) # if we know in advance how many points (n) we want to compute, then -# adopt a suggestion similar to the Joe and Kuo paper, which in turn -# is taken from Acworth et al (1998), of skipping a number of -# points one less than the largest power of 2 smaller than n+1. +# we can adopt a suggestion similar to Joe and Kuo (2003), which in turn +# is taken from Acworth et al (1998), of skipping a number of initial +# points. The number of points is the largest power of 2 smaller than n+1. # if exactly n points are to be skipped, use the keyword exact=true. -# (Ackworth and Joe and Kuo seem to suggest skipping exactly -# a power of 2, but skipping 1 less seems to produce much better -# results: issue #21.) # -# skip!(s, n) skips 2^m - 1 such that 2^m < n ≤ 2^(m+1) +# skip!(s, n) skips 2^m such that 2^m ≤ n < 2^(m+1) # skip!(s, n, exact=true) skips m = n function skip!(s::SobolSeq, n::Integer, x; exact=false) @@ -91,7 +96,7 @@ function skip!(s::SobolSeq, n::Integer, x; exact=false) n == 0 && return s throw(ArgumentError("$n is not non-negative")) end - nskip = exact ? n : (1 << floor(Int,log2(n+1)) - 1) + nskip = exact ? n : prevpow(2, n) for unused=1:nskip; next!(s,x); end return s end diff --git a/test/runtests.jl b/test/runtests.jl index 1555d98..8deff24 100644 --- a/test/runtests.jl +++ b/test/runtests.jl @@ -21,8 +21,8 @@ using Sobol, Test for line in eachline(exp_results_file) values = [parse(Float64, item) for item in split(line)] if length(values) > 0 - @test x == values next!(s, x) + @test x == values end end end @@ -32,7 +32,7 @@ end using Base.Iterators: take @testset "iterators" begin # issue #8 - @test [x[1] for x in collect(take(Sobol.SobolSeq(1),5))] == [0.5,0.75,0.25,0.375,0.875] + @test [x[1] for x in collect(take(Sobol.SobolSeq(1),5))] == [0.0,0.5,0.75,0.25,0.375] end @testset "scaled" begin @@ -44,8 +44,13 @@ end @test s isa ScaledSobolSeq{3,Int} @test eltype(s) == Vector{Float64} @test eltype(SobolSeq(Float32.(lb),Float32.(ub))) == Vector{Float32} - @test first(s) == [0,1.5,1] - @test first(SobolSeq((x for x in lb), (x for x in ub))) == [0,1.5,1] + @test next!(s) == [-1,0,0] + @test next!(s) == [0,1.5,1] + + s = SobolSeq((x for x in lb), (x for x in ub)) + @test next!(s) == [-1,0,0] + @test next!(s) == [0,1.5,1] + @test SobolSeq(N,lb,ub) isa ScaledSobolSeq{3,Int} @test_throws BoundsError SobolSeq(2,lb,ub) end @@ -71,10 +76,10 @@ end p = map(_->next!(s), 1:16) sort!(map(x -> sum((x .≥ 0.5) .* (2 .^ (0:3))), p)) == 0:15 - for n in (7,8) + for n in (7,8,9) s = skip(SobolSeq(2), n) p = [next!(s) for _ = 1:n] - s2 = skip(SobolSeq(2), 7, exact=true) + s2 = skip(SobolSeq(2), n == 7 ? 4 : 8, exact=true) p2 = [next!(s2) for _ = 1:n] @test p == p2 end From a584c10935d1ccf6644dc1f5943bcf070bd803a5 Mon Sep 17 00:00:00 2001 From: David Widmann Date: Tue, 8 Apr 2025 18:49:15 +0200 Subject: [PATCH 2/2] Apply suggestions from code review Co-authored-by: Jerry Ling --- README.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/README.md b/README.md index b488bb3..a848feb 100644 --- a/README.md +++ b/README.md @@ -113,11 +113,10 @@ skip(s, n, exact=true) Note, however, that generally it is not recommended to skip (arbitrary) number of points since this can ruin the digital net property and lead to worse convergence (as illustrated in [Owen, 2021](https://arxiv.org/abs/2008.08051) for the -common proactice of dropping the initial point). +common practice of dropping the initial point). `skip` returns `s`, so you can simply do `s = skip(SobolSeq(N))` or similar. -Note, however, that generally it is not recommended to skip arbitrary ## Example