comboGroupsIterator: comboGroups Iterator

In RcppAlgos: High Performance Tools for Combinatorics and Computational Mathematics

comboGroups Iterator

Description

• Returns an iterator for iterating over partitions of a vector into groups.

• Supports random access via the [[ method.

• GMP support allows for exploration of cases where the number of comboGroups is large.

• Use the next methods to obtain results in lexicographical order.

Usage

comboGroupsIter(v, numGroups = NULL, grpSizes = NULL,
                retType = "matrix", Parallel = FALSE,
                nThreads = NULL)

Arguments

v	Source vector. If v is a positive integer, it will be converted to the sequence 1:v. If v is a negative integer, it will be converted to the sequence v:-1. All atomic types are supported (See is.atomic).
numGroups	An Integer. The number of groups that the vector will be partitioned into. The default is NULL. If provided and grpSize is NULL, it must divide the length of v (if v is a vector) or v (if v is a scalar).
grpSizes	A vector of whole numbers representing the size of each group. The default is NULL. If provided, the sum of the elements must total the length of v (if v is a vector) or v (if v is a scalar).
retType	A string, "3Darray" or "matrix", that determines the shape of the output. The default is "matrix". Note, "3Darray" can only be used when the size of each group is uniform. When the size of each group varies, the return output will always be a matrix.
Parallel	Logical value indicating whether results should be generated in parallel using n - 1 threads, where n is the maximum number of threads. The default is FALSE. If nThreads is not NULL, it will be given preference (e.g. if user has 8 threads with Parallel = TRUE and nThreads = 4, only 4 threads will be spawned). If your system is single-threaded, the arguments Parallel and nThreads are ignored.
nThreads	Specific number of threads to be used. The default is NULL. See Parallel.

Details

Once you initialize a new iterator, the following methods are available:

nextIter

Retrieve the next lexicographical result

nextNIter

Pass an integer n to retrieve the next n lexicographical results

nextRemaining

Retrieve all remaining lexicographical results

currIter

Returns the current iteration

startOver

Resets the iterator

sourceVector

View the source vector

summary

Returns a list of summary information about the iterator

front

Retrieve the first lexicographical result

back

Retrieve the last lexicographical result

[[

Random access method. Pass a single value or a vector of valid indices. If a single value is passed, the internal index of the iterator will be updated, however if a vector is passed the internal state will not change. GMP support allows for flexible indexing.

Value

• If nextIter is called, a named vector is returned if retType = "matrix". If retType = "3Darray", a named matrix is returned.

• Otherwise a named matrix is returned when retType = "matrix" and a named 3D array is returned when retType = "3Darray".

Note

• If nThreads is utilized, it will only take effect if the number of elements requested is greater than some threshold (determined internally). E.g:

  serial   <- comboGroupsIter(50, 10)
  multi    <- comboGroupsIter(50, 10, nThreads = 4)
  fetch1e6 <- multi@nextNIter(1e6)  ## much faster than serial@nextNIter(1e6)
  fetch1e3 <- multi@nextNIter(1e3)  ## only one thread used... same as serial@nextNIter(1e3)
  
  library(microbenchmark)
  microbenchmark(multi@nextNIter(1e6), serial@nextNIter(1e6), times = 20)
  microbenchmark(multi@nextNIter(1e3), serial@nextNIter(1e3), times = 20)

• The maximum number of comboGroups that can be generated at one time is 2^{31} - 1.

Author(s)

Joseph Wood

See Also

comboGroups

Examples

a = comboGroupsIter(12, 3)
a@nextIter()
a@nextNIter(3)
a@front()
all_remaining = a@nextRemaining()
dim(all_remaining)
a@summary()
a@back()
a[[5]]
a@summary()
a[[c(1, 17, 3)]]
a@summary()

RcppAlgos documentation built on May 29, 2024, noon