Package {sobol}

sobol: 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.

Author(s)

Maintainer: Angel Robles a.l.robles.fernandez@gmail.com

Other contributors:

• Ilya M. Sobol (Original Sobol sequence algorithm) [contributor]

• Paul Bratley (Algorithm implementation reference) [contributor]

• Bennett L. Fox (Algorithm implementation reference) [contributor]

• Stephen Joe (Direction numbers and primitive polynomials) [contributor]

• Frances Y. Kuo (Direction numbers and primitive polynomials) [contributor]

See Also

Useful links:

• https://alrobles.github.io/sobol/

• Report bugs at https://github.com/alrobles/sobol/issues

Print Method for Sobol Generator

Description

Print Method for Sobol Generator

Usage

## S3 method for class 'sobol_generator'
print(x, ...)

Arguments

Value

Invisibly returns the input object (for chaining)

Print Summary of Sobol Generator

Description

Print Summary of Sobol Generator

Usage

## S3 method for class 'summary.sobol_generator'
print(x, ...)

Arguments

Value

Invisibly returns the input object

Generate a Sobol Design for Parameter Exploration

Description

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.

Usage

sobol_design(lower = numeric(0), upper = numeric(0), nseq)

Arguments

Details

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.

Value

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.

References

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.

See Also

sobol_points for batch generation without scaling, sobol_generator for incremental generation

Examples

# 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
)

Get Number of Dimensions of a Sobol Generator

Description

Returns the number of dimensions configured for the generator.

Usage

sobol_dimensions(x, ...)

Arguments

Value

An integer representing the number of dimensions.

Examples

gen <- sobol_generator(dimensions = 5)
dims <- sobol_dimensions(gen)
print(dims) # 5

Create a Sobol Sequence Generator

Description

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.

Usage

sobol_generator(dimensions, skip = 0)

Arguments

Value

An S3 object of class "sobol_generator" containing:

Examples

# 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)

Get Current Index of a Sobol Generator

Description

Returns the current index of the generator, which is the index of the next point that will be generated.

Usage

sobol_index(x, ...)

Arguments

Value

A numeric value representing the current index (0-based).

Examples

gen <- sobol_generator(dimensions = 2)
sobol_next(gen)
sobol_next(gen)
idx <- sobol_index(gen)
print(idx) # 2

Generate the Next Point from a Sobol Generator

Description

Generates a single point from the Sobol sequence and advances the internal state of the generator.

Usage

sobol_next(x, ...)

Arguments

Value

A numeric vector of length equal to the number of dimensions, containing the next point in the Sobol sequence. Values are in [0, 1).

Examples

gen <- sobol_generator(dimensions = 3)
point <- sobol_next(gen)
print(point) # e.g., [0.5, 0.5, 0.5]

Generate Multiple Points from a Sobol Generator

Description

Generates n consecutive points from the Sobol sequence and advances the internal state of the generator.

Usage

sobol_next_n(x, n, ...)

Arguments

Value

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.

Examples

gen <- sobol_generator(dimensions = 2)
points <- sobol_next_n(gen, n = 10)
print(dim(points)) # [1] 10  2

Generate a Batch of Sobol Points

Description

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.

Arguments

Details

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

Value

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.

See Also

sobol_generator for incremental generation with state

Examples

# 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

Skip to a Specific Index in a Sobol Generator

Description

Jumps the internal state of the generator to a specific index in the Sobol sequence. This allows for reproducible subsequences and parallel generation strategies.

Usage

sobol_skip_to(x, index, ...)

Arguments

Value

Invisibly returns the sobol_generator object (for chaining). The primary purpose is the side effect of updating the internal state.

Examples

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

Description

Summary Method for Sobol Generator

Usage

## S3 method for class 'sobol_generator'
summary(object, ...)

Arguments

Value

A list with class "summary.sobol_generator" containing summary information