| Title: | Quasi-Monte Carlo Sobol Sequence Generator |
|---|---|
| Description: | Provides a fast and efficient implementation of Sobol sequences for quasi-Monte Carlo methods. The Sobol sequence is a low-discrepancy sequence with the property that for all values of N, its subsequence x1, ..., xN has a low discrepancy. It can be used to generate quasi-random numbers for use in Monte Carlo integration and other simulation methods. This implementation is based on the algorithms described by Bratley and Fox (1988) <doi:10.1145/42288.214372> and uses direction numbers from Joe and Kuo (2008) <doi:10.1145/1358628.1358630>. The package includes both batch and incremental interfaces with support for arbitrary starting indices and reproducible sequences. It uses 'Rcpp' for efficient 'C++' integration. |
| Authors: | Angel Robles [aut, cre], Ilya M. Sobol [ctb] (Original Sobol sequence algorithm), Paul Bratley [ctb] (Algorithm implementation reference), Bennett L. Fox [ctb] (Algorithm implementation reference), Stephen Joe [ctb] (Direction numbers and primitive polynomials), Frances Y. Kuo [ctb] (Direction numbers and primitive polynomials) |
| Maintainer: | Angel Robles <[email protected]> |
| License: | GPL (>= 3) |
| Version: | 1.0.0 |
| Built: | 2026-05-18 21:16:54 UTC |
| Source: | https://github.com/cran/sobol |
Print Method for Sobol Generator
## S3 method for class 'sobol_generator' print(x, ...)## S3 method for class 'sobol_generator' print(x, ...)
x |
A sobol_generator object |
... |
Additional arguments passed to print |
Invisibly returns the input object (for chaining)
Print Summary of Sobol Generator
## S3 method for class 'summary.sobol_generator' print(x, ...)## S3 method for class 'summary.sobol_generator' print(x, ...)
x |
A summary.sobol_generator object |
... |
Additional arguments passed to print |
Invisibly returns the input object
Creates a Latin hypercube design based on the Sobol low-discrepancy sequence. This function provides an API-compatible alternative to the sobol_design function in the pomp-explore package for generating parameter designs.
sobol_design(lower = numeric(0), upper = numeric(0), nseq)sobol_design(lower = numeric(0), upper = numeric(0), nseq)
lower |
Named numeric vector giving the lower bounds of the parameter
ranges. Must have the same names as |
upper |
Named numeric vector giving the upper bounds of the parameter
ranges. Must have the same names as |
nseq |
Integer, the total number of parameter sets (points) to generate. |
This function generates a Sobol sequence in the unit hypercube [0,1]^d and then scales each dimension to the specified parameter ranges. The Sobol sequence is generated using the Joe-Kuo direction numbers with Property A enforcement, providing excellent low-discrepancy properties.
Following the recommendation of Joe & Kuo (2003) and the implementation in pomp-explore, this function skips the first k points of the Sobol sequence, where k is the largest power of 2 smaller than nseq. This improves the uniformity properties of the generated design.
The function is designed to be API-compatible with the sobol_design
function from the pomp-explore package, allowing for easy comparison and
drop-in replacement.
A data frame with nseq rows and one column for each parameter
named in lower and upper. Each column contains values scaled
to the specified range [lower, upper] for that parameter.
Bratley, P., & Fox, B. L. (1988). Algorithm 659: Implementing Sobol's quasirandom sequence generator. ACM Transactions on Mathematical Software, 14(1), 88-100.
Joe, S., & Kuo, F. Y. (2008). Constructing Sobol sequences with better two-dimensional projections. SIAM Journal on Scientific Computing, 30(5), 2635-2654.
sobol_points for batch generation without scaling,
sobol_generator for incremental generation
# Generate 100 parameter sets for two parameters design <- sobol_design( lower = c(a = 0, b = 100), upper = c(a = 1, b = 200), nseq = 100 ) head(design) # Plot the design plot(design$a, design$b, main = "Sobol Design") # High-dimensional example params <- paste0("param", 1:10) design_10d <- sobol_design( lower = setNames(rep(0, 10), params), upper = setNames(rep(1, 10), params), nseq = 1000 )# Generate 100 parameter sets for two parameters design <- sobol_design( lower = c(a = 0, b = 100), upper = c(a = 1, b = 200), nseq = 100 ) head(design) # Plot the design plot(design$a, design$b, main = "Sobol Design") # High-dimensional example params <- paste0("param", 1:10) design_10d <- sobol_design( lower = setNames(rep(0, 10), params), upper = setNames(rep(1, 10), params), nseq = 1000 )
Returns the number of dimensions configured for the generator.
sobol_dimensions(x, ...)sobol_dimensions(x, ...)
x |
A sobol_generator object created by |
... |
Additional arguments (currently unused) |
An integer representing the number of dimensions.
gen <- sobol_generator(dimensions = 5) dims <- sobol_dimensions(gen) print(dims) # 5gen <- sobol_generator(dimensions = 5) dims <- sobol_dimensions(gen) print(dims) # 5
Creates an S3 object that wraps an Rcpp Sobol sequence generator for incremental point generation. The generator maintains internal state and allows for efficient generation of quasi-random sequences.
sobol_generator(dimensions, skip = 0)sobol_generator(dimensions, skip = 0)
dimensions |
Integer, the number of dimensions for the Sobol sequence. Must be a positive integer. |
skip |
Numeric, the number of initial points to skip (default: 0). This allows starting the sequence from any index for reproducibility. |
An S3 object of class "sobol_generator" containing:
generator |
The underlying Rcpp reference class object |
dimensions |
Number of dimensions |
initial_skip |
Initial skip value used at construction |
# Create a 3-dimensional Sobol generator gen <- sobol_generator(dimensions = 3) # Generate a single point point <- sobol_next(gen) # Generate multiple points points <- sobol_next_n(gen, n = 100) # Skip to a specific index sobol_skip_to(gen, 1000) # Create a generator starting from index 50 gen2 <- sobol_generator(dimensions = 2, skip = 50)# Create a 3-dimensional Sobol generator gen <- sobol_generator(dimensions = 3) # Generate a single point point <- sobol_next(gen) # Generate multiple points points <- sobol_next_n(gen, n = 100) # Skip to a specific index sobol_skip_to(gen, 1000) # Create a generator starting from index 50 gen2 <- sobol_generator(dimensions = 2, skip = 50)
Returns the current index of the generator, which is the index of the next point that will be generated.
sobol_index(x, ...)sobol_index(x, ...)
x |
A sobol_generator object created by |
... |
Additional arguments (currently unused) |
A numeric value representing the current index (0-based).
gen <- sobol_generator(dimensions = 2) sobol_next(gen) sobol_next(gen) idx <- sobol_index(gen) print(idx) # 2gen <- sobol_generator(dimensions = 2) sobol_next(gen) sobol_next(gen) idx <- sobol_index(gen) print(idx) # 2
Generates a single point from the Sobol sequence and advances the internal state of the generator.
sobol_next(x, ...)sobol_next(x, ...)
x |
A sobol_generator object created by |
... |
Additional arguments (currently unused) |
A numeric vector of length equal to the number of dimensions, containing the next point in the Sobol sequence. Values are in [0, 1).
gen <- sobol_generator(dimensions = 3) point <- sobol_next(gen) print(point) # e.g., [0.5, 0.5, 0.5]gen <- sobol_generator(dimensions = 3) point <- sobol_next(gen) print(point) # e.g., [0.5, 0.5, 0.5]
Generates n consecutive points from the Sobol sequence and advances the internal state of the generator.
sobol_next_n(x, n, ...)sobol_next_n(x, n, ...)
x |
A sobol_generator object created by |
n |
Integer, the number of points to generate. Must be non-negative. |
... |
Additional arguments (currently unused) |
A numeric matrix with n rows and dimensions columns, where each row represents a point in the Sobol sequence. Values are in [0, 1). If n = 0, returns a 0 x dimensions matrix.
gen <- sobol_generator(dimensions = 2) points <- sobol_next_n(gen, n = 10) print(dim(points)) # [1] 10 2gen <- sobol_generator(dimensions = 2) points <- sobol_next_n(gen, n = 10) print(dim(points)) # [1] 10 2
Efficiently generates a matrix of Sobol sequence points. This is a
convenience function that does not maintain state between calls.
For incremental generation, use sobol_generator instead.
n |
Integer, the number of points to generate. Must be non-negative. |
dim |
Integer, the number of dimensions for each point. Must be a positive integer. |
skip |
Numeric, the number of initial points to skip (default: 0). This allows generating subsequences of the Sobol sequence. |
This function is implemented directly in C++ via Rcpp and is more
efficient than creating a generator and calling sobol_next_n
when you know in advance how many points you need.
The skip parameter allows you to start from any point in the sequence, which is useful for:
Reproducibility: generating the same subsequence across runs
Parallelization: different workers can generate non-overlapping segments
Continuation: extending a previous sequence without regenerating early points
A numeric matrix with n rows and dim columns, where each row represents a point in the Sobol sequence. Values are in [0, 1). If n = 0, returns a 0 x dim matrix.
sobol_generator for incremental generation with state
# Generate 1000 points in 5 dimensions points <- sobol_points(n = 1000, dim = 5) dim(points) # [1] 1000 5 # Skip the first 100 points points_skipped <- sobol_points(n = 100, dim = 2, skip = 100) # Empty result empty <- sobol_points(n = 0, dim = 3) dim(empty) # [1] 0 3# Generate 1000 points in 5 dimensions points <- sobol_points(n = 1000, dim = 5) dim(points) # [1] 1000 5 # Skip the first 100 points points_skipped <- sobol_points(n = 100, dim = 2, skip = 100) # Empty result empty <- sobol_points(n = 0, dim = 3) dim(empty) # [1] 0 3
Jumps the internal state of the generator to a specific index in the Sobol sequence. This allows for reproducible subsequences and parallel generation strategies.
sobol_skip_to(x, index, ...)sobol_skip_to(x, index, ...)
x |
A sobol_generator object created by |
index |
Numeric, the index to skip to. Must be a non-negative integer.
The next call to |
... |
Additional arguments (currently unused) |
Invisibly returns the sobol_generator object (for chaining). The primary purpose is the side effect of updating the internal state.
gen <- sobol_generator(dimensions = 2) sobol_skip_to(gen, 100) point <- sobol_next(gen) # This is the 100th point (0-indexed)gen <- sobol_generator(dimensions = 2) sobol_skip_to(gen, 100) point <- sobol_next(gen) # This is the 100th point (0-indexed)
Summary Method for Sobol Generator
## S3 method for class 'sobol_generator' summary(object, ...)## S3 method for class 'sobol_generator' summary(object, ...)
object |
A sobol_generator object |
... |
Additional arguments passed to summary |
A list with class "summary.sobol_generator" containing summary information