parallel

https://www.rdocumentation.org/packages/parallel/versions/3.6.2
Admin
The parallel package provides support for parallel computation in R, including parallel processing...
Tokens:6,806
Snippets:52
Trust Score:9.8
Update:6 months ago
Show doc for...
Tokens:
Raw
### Detect CPU Cores Usage

Source: https://www.rdocumentation.org/packages/parallel/versions/3.6.2/topics/detectCores

Basic usage examples for detecting logical and physical CPU cores.

```R
detectCores(all.tests = FALSE, logical = TRUE)
```

```R
# NOT RUN {
detectCores()
detectCores(logical = FALSE)
# }
```

--------------------------------

### Example Usage of Parallel Functions

Source: https://www.rdocumentation.org/packages/parallel/versions/3.6.2/topics/clusterApply

Demonstrates how to use various parallel computing functions with R clusters, including setting up clusters, exporting data, and running parallel operations.

```APIDOC
## Example 1: Basic Cluster Operations

### Description
This example shows how to create a cluster, use `clusterApply` for simple operations, export a variable using `clusterExport`, and use `clusterCall`.

### Method
Not specified (demonstrates function calls)

### Endpoint
Not applicable

### Code
```R
# NOT RUN {
cl <- makeCluster(getOption("cl.cores", 2))

# Use clusterApply for simple operations
clusterApply(cl, 1:2, get("+"), 3)

# Export a variable to the cluster nodes
xx <- 1
clusterExport(cl, "xx")

# Use clusterCall to execute a function on all nodes with exported variable
clusterCall(cl, function(y) xx + y, 2)

# stopCluster(cl) # Uncomment to stop the cluster
# }
```

## Example 2: Using clusterMap

### Description
Demonstrates the use of `clusterMap` which is a multi-argument parallel apply function, similar to `mapply`.

### Method
Not specified (demonstrates function calls)

### Endpoint
Not applicable

### Code
```R
# NOT RUN {
# Assuming 'cl' is an existing cluster
# Use clusterMap like an mapply example
clusterMap(cl, function(x, y) seq_len(x) + y,
          c(a =  1, b = 2, c = 3), c(A = 10, B = 0, C = -10))

# stopCluster(cl) # Uncomment to stop the cluster
# }
```

## Example 3: Using parSapply

### Description
Shows a basic example of using `parSapply` for parallel sapply operations.

### Method
Not specified (demonstrates function calls)

### Endpoint
Not applicable

### Code
```R
# NOT RUN {
# Assuming 'cl' is an existing cluster
parSapply(cl, 1:20, get("+"), 3)

# stopCluster(cl) # Uncomment to stop the cluster
# }
```

## Example 4: Bootstrapping with clusterEvalQ

### Description
An example of performing a bootstrapping analysis in parallel using `clusterEvalQ` to set up the environment on each worker node.

### Method
Not specified (demonstrates function calls)

### Endpoint
Not applicable

### Code
```R
# NOT RUN {
cl <- makeCluster(getOption("cl.cores", 2))

# Set up each worker node with necessary functions and data
clusterEvalQ(cl, {
  library(boot)
  cd4.rg <- function(data, mle) MASS::mvrnorm(nrow(data), mle$m, mle$v)
  cd4.mle <- list(m = colMeans(cd4), v = var(cd4))
  NULL
})

# Run the bootstrapping in parallel
res <- clusterEvalQ(cl, boot(cd4, corr, R = 100,
                    sim = "parametric", ran.gen = cd4.rg, mle = cd4.mle))

# Combine results and compute confidence intervals
library(boot)
cd4.boot <- do.call(c, res)
boot.ci(cd4.boot,  type = c("norm", "basic", "perc"),
        conf = 0.9, h = atanh, hinv = tanh)

stopCluster(cl)
# }
```

## Example 5: Bootstrapping with parLapply and clusterSetRNGStream

### Description
Another bootstrapping example, this time using `parLapply` and `clusterSetRNGStream` for reproducible random number generation across nodes.

### Method
Not specified (demonstrates function calls)

### Endpoint
Not applicable

### Code
```R
# NOT RUN {
library(boot)

# Define the function to run on each cluster node
run1 <- function(...) {
   library(boot)
   cd4.rg <- function(data, mle) MASS::mvrnorm(nrow(data), mle$m, mle$v)
   cd4.mle <- list(m = colMeans(cd4), v = var(cd4))
   boot(cd4, corr, R = 500, sim = "parametric",
        ran.gen = cd4.rg, mle = cd4.mle)
}

# Create a cluster
cl <- makeCluster(mc <- getOption("cl.cores", 2))

# Set a seed for reproducible results
clusterSetRNGStream(cl, 123)

# Run the bootstrapping in parallel using parLapply
cd4.boot <- do.call(c, parLapply(cl, seq_len(mc), run1))

# Compute confidence intervals
boot.ci(cd4.boot,  type = c("norm", "basic", "perc"),
        conf = 0.9, h = atanh, hinv = tanh)

stopCluster(cl)
# }
```
```

--------------------------------

### Setting and Using L'Ecuyer-CMRG RNG

Source: https://www.rdocumentation.org/packages/parallel/versions/3.6.2/topics/RNGstreams

Demonstrates how to set the L'Ecuyer-CMRG random number generator, get the current seed, and then advance to the next stream or substream. This is useful for ensuring reproducible random number generation in parallel tasks.

```R
RNGkind("L'Ecuyer-CMRG")
set.seed(123)
(s <- .Random.seed)
## do some work involving random numbers.
nextRNGStream(s)
nextRNGSubStream(s)

```

--------------------------------

### Get Default Parallel Cluster

Source: https://www.rdocumentation.org/packages/parallel/versions/3.6.2/topics/makeCluster

getDefaultCluster retrieves the currently registered default cluster. Returns NULL if no default cluster is set.

```R
getDefaultCluster()
```

--------------------------------

### Parallel Cluster Operations and Bootstrapping

Source: https://www.rdocumentation.org/packages/parallel/versions/3.6.2/topics/clusterApply

Demonstrates cluster initialization, data export, parallel execution, and bootstrapping using parallel apply functions.

```R
# NOT RUN {
## Use option cl.cores to choose an appropriate cluster size.
cl <- makeCluster(getOption("cl.cores", 2))

clusterApply(cl, 1:2, get("+"), 3)
xx <- 1
clusterExport(cl, "xx")
clusterCall(cl, function(y) xx + y, 2)

## Use clusterMap like an mapply example
clusterMap(cl, function(x, y) seq_len(x) + y,
          c(a =  1, b = 2, c = 3), c(A = 10, B = 0, C = -10))


parSapply(cl, 1:20, get("+"), 3)

## A bootstrapping example, which can be done in many ways:
clusterEvalQ(cl, {
  ## set up each worker.  Could also use clusterExport()
  library(boot)
  cd4.rg <- function(data, mle) MASS::mvrnorm(nrow(data), mle$m, mle$v)
  cd4.mle <- list(m = colMeans(cd4), v = var(cd4))
  NULL
})
res <- clusterEvalQ(cl, boot(cd4, corr, R = 100,
                    sim = "parametric", ran.gen = cd4.rg, mle = cd4.mle))
library(boot)
cd4.boot <- do.call(c, res)
boot.ci(cd4.boot,  type = c("norm", "basic", "perc"),
        conf = 0.9, h = atanh, hinv = tanh)
stopCluster(cl)

## or
library(boot)
run1 <- function(...) {
   library(boot)
   cd4.rg <- function(data, mle) MASS::mvrnorm(nrow(data), mle$m, mle$v)
   cd4.mle <- list(m = colMeans(cd4), v = var(cd4))
   boot(cd4, corr, R = 500, sim = "parametric",
        ran.gen = cd4.rg, mle = cd4.mle)
}
cl <- makeCluster(mc <- getOption("cl.cores", 2))
## to make this reproducible
clusterSetRNGStream(cl, 123)
cd4.boot <- do.call(c, parLapply(cl, seq_len(mc), run1))
boot.ci(cd4.boot,  type = c("norm", "basic", "perc"),
        conf = 0.9, h = atanh, hinv = tanh)
stopCluster(cl)
# }
```

--------------------------------

### Create Parallel Socket Cluster

Source: https://www.rdocumentation.org/packages/parallel/versions/3.6.2/topics/makeCluster

Use makeCluster to create a parallel socket cluster. Specify the cluster type and any additional options for worker spawning.

```R
makeCluster(spec, type, ...)
```

--------------------------------

### detectCores Function

Source: https://www.rdocumentation.org/packages/parallel/versions/3.6.2/topics/detectCores

Detects the number of CPU cores on the current host system.

```APIDOC
## detectCores

### Description
Attempt to detect the number of CPU cores on the current host.

### Usage
detectCores(all.tests = FALSE, logical = TRUE)

### Parameters
#### Arguments
- **all.tests** (logical) - Optional - If true apply all known tests.
- **logical** (logical) - Optional - If possible, use the number of physical CPUs/cores (if FALSE) or logical CPUs (if TRUE). Currently this is honoured only on macOS, Solaris and Windows.

### Value
An integer, NA if the answer is unknown. The result is OS-dependent, typically counting logical CPUs by default.

### Request Example
detectCores(logical = FALSE)
```

--------------------------------

### Create Parallel Socket Cluster with Hostnames or Count

Source: https://www.rdocumentation.org/packages/parallel/versions/3.6.2/topics/makeCluster

makePSOCKcluster creates a socket cluster. Provide a character vector of hostnames or an integer for the number of local copies.

```R
makePSOCKcluster(names, ...)
```

--------------------------------

### Cluster Creation Functions

Source: https://www.rdocumentation.org/packages/parallel/versions/3.6.2/topics/makeCluster

Functions to create and manage parallel computing clusters.

```APIDOC
## makeCluster

### Description
Creates a cluster of one of the supported types. The default type, `"PSOCK"`, calls `makePSOCKcluster`. Type `"FORK"` calls `makeForkCluster`. Other types are passed to package `snow`.

### Method
`makeCluster(..., type = getOption("paralelltype"))`

### Parameters
* **type** (character) - The type of cluster to create. Defaults to the value of the `"paralelltype"` option.

## makePSOCKcluster

### Description
An enhanced version of `makeSOCKcluster` in package `snow`. It runs `Rscript` on the specified host(s) to set up a worker process which listens on a socket for expressions to evaluate, and returns the results (as serialized objects).

### Method
`makePSOCKcluster(cl, ...)`

### Parameters
* **cl** (cluster object) - A cluster object, typically created by `makeCluster`.
* **master** (character) - The host name of the master, as known to the workers. May need to be a numeric IP address on private subnets.
* **port** (integer) - The port number for the socket connection. Defaults to `R_PARALLEL_PORT` environment variable or a random port in `11000:11999`.
* **setup_timeout** (numeric) - Maximum seconds a worker attempts to connect to master before failing. Default is 2 minutes.
* **timeout** (numeric) - Timeout in seconds for zero communication between master and worker before failing. Default is 30 days.
* **outfile** (character) - Where to direct `stdout` and `stderr` from workers. `""` for no redirection, or a file path on the worker's host. Defaults to `/dev/null` (`nul:` on Windows).
* **homogeneous** (logical) - Whether all hosts have identical setups, allowing `Rscript` to be launched using the same path on each. If `FALSE`, `Rscript` must be in the default path on workers.
* **rscript** (character) - The path to `Rscript` on the workers, used if `homogeneous` is `TRUE`. Defaults to the full path on the master.
* **rscript_args** (character vector) - Additional arguments for `Rscript`, such as `--no-environ`.
* **renice** (numeric) - Niceness value to set for worker processes (e.g., `15` for low priority). OS-dependent.
* **rshcmd** (character) - Command to launch a process on another host. Defaults to `ssh`.
* **user** (character) - User name for communicating with another host.
* **manual** (logical) - If `TRUE`, workers need to be run manually.
* **methods** (logical) - If `TRUE` (default), workers load the `methods` package. Setting to `FALSE` saves startup CPU time.
* **useXDR** (logical) - If `TRUE` (default), serialization uses XDR. Setting to `FALSE` may speed up communication if all nodes are little-endian.

## makeForkCluster

### Description
Creates a socket cluster by forking (not available on Windows). It supports options `port`, `timeout`, and `outfile`, and always uses `useXDR = FALSE`. It is strongly discouraged to use the `"FORK"` cluster with GUI front-ends or multi-threaded libraries.

### Method
`makeForkCluster(cl, ...)`

### Parameters
* **cl** (cluster object) - A cluster object, typically created by `makeCluster`.
* **port** (integer) - The port number for the socket connection.
* **timeout** (numeric) - Timeout in seconds for zero communication between master and worker before failing.
* **outfile** (character) - Where to direct `stdout` and `stderr` from workers.
* **useXDR** (logical) - Always `FALSE` for `makeForkCluster`.

## stopCluster

### Description
Shuts down the workers of a cluster.

### Method
`stopCluster(cl)`

### Parameters
* **cl** (cluster object) - The cluster object to stop.

## setDefaultCluster

### Description
Registers a cluster as the default one for the current session. Using `setDefaultCluster(NULL)` removes the registered cluster.

### Method
`setDefaultCluster(cl)`

### Parameters
* **cl** (cluster object or NULL) - The cluster object to set as default, or `NULL` to remove the default cluster.
```

--------------------------------

### Divide tasks using splitIndices

Source: https://www.rdocumentation.org/packages/parallel/versions/3.6.2/topics/splitIndices

Partitions a sequence of 20 tasks into 3 separate lists for cluster distribution.

```R
# NOT RUN {
splitIndices(20, 3)
# }
```

--------------------------------

### Cluster Function Overview

Source: https://www.rdocumentation.org/packages/parallel/versions/3.6.2/topics/clusterApply

Provides descriptions for various functions used in parallel computing with R clusters.

```APIDOC
## clusterCall

### Description
Calls a function `fun` with identical arguments `...` on each cluster node.

### Method
Not specified (typically used within a cluster context)

### Endpoint
Not applicable

## clusterEvalQ

### Description
Evaluates a literal expression on each cluster node. It is a parallel version of `evalq`, and is a convenience function invoking `clusterCall`.

### Method
Not specified (typically used within a cluster context)

### Endpoint
Not applicable

## clusterApply

### Description
Calls `fun` on the first node with arguments `x[[1]]` and `...`, on the second node with `x[[2]]` and `...`, and so on, recycling nodes as needed.

### Method
Not specified (typically used within a cluster context)

### Endpoint
Not applicable

## clusterApplyLB

### Description
A load balancing version of `clusterApply`. Jobs are distributed dynamically to available nodes, which can improve utilization but may reduce reproducibility.

### Method
Not specified (typically used within a cluster context)

### Endpoint
Not applicable

## clusterMap

### Description
A multi-argument version of `clusterApply`, analogous to `mapply` and `Map`. Handles argument recycling and node recycling.

### Method
Not specified (typically used within a cluster context)

### Endpoint
Not applicable

## clusterExport

### Description
Assigns the values of variables from the master R process to the global environment of each cluster node.

### Method
Not specified (typically used within a cluster context)

### Endpoint
Not applicable

## clusterSplit

### Description
Splits a sequence into consecutive pieces for each cluster node, returning a list of pieces.

### Method
Not specified (typically used within a cluster context)

### Endpoint
Not applicable

## parLapply, parSapply, parApply

### Description
Parallel versions of `lapply`, `sapply`, and `apply`. They use `clusterApply` for static chunk allocation.

### Method
Not specified (typically used within a cluster context)

### Endpoint
Not applicable

## parLapplyLB, parSapplyLB

### Description
Load-balancing versions of `parLapply` and `parSapply`. They use `clusterApplyLB` for dynamic chunk allocation, suitable for tasks with variable execution times.

### Method
Not specified (typically used within a cluster context)

### Endpoint
Not applicable

## parRapply, parCapply

### Description
Parallel row and column `apply` functions for matrices. May be more efficient than `parApply` but offer less post-processing.

### Method
Not specified (typically used within a cluster context)

### Endpoint
Not applicable
```

--------------------------------

### Create Forked Parallel Cluster

Source: https://www.rdocumentation.org/packages/parallel/versions/3.6.2/topics/makeCluster

makeForkCluster creates a forked cluster. Specify the number of nodes to fork, defaulting to the value of the 'mc.cores' option.

```R
makeForkCluster(nnodes = getOption("mc.cores", 2L), ...)
```

--------------------------------

### Parallel Apply Functions

Source: https://www.rdocumentation.org/packages/parallel/versions/3.6.2/topics/clusterApply

Functions for parallelizing apply-style operations across cluster nodes.

```APIDOC
## parLapply, parSapply, parApply, parRapply, parCapply

### Description
Parallel versions of standard R apply functions for distributed computation.

### Parameters
- **cl** (cluster object) - Optional - The cluster object to use.
- **X** (vector/array) - Required - The data structure to process.
- **FUN** (function) - Required - The function to apply.
- **chunk.size** (numeric) - Optional - Number of invocations per chunk for scheduling.
```

--------------------------------

### Cluster Management Functions

Source: https://www.rdocumentation.org/packages/parallel/versions/3.6.2/topics/makeCluster

Functions for creating and managing parallel clusters in R.

```APIDOC
## makeCluster

### Description
Creates a set of copies of R running in parallel and communicating over sockets.

### Parameters
- **spec** (any) - Required - A specification appropriate to the type of cluster.
- **type** (string) - Required - One of the supported types.
- **...** (options) - Optional - Options to be passed to the function spawning the workers.

### Response
- **cluster** (object) - An object of class c("SOCKcluster", "cluster").

## makePSOCKcluster

### Description
Creates a parallel socket cluster.

### Parameters
- **names** (character vector or integer) - Required - Either a character vector of host names or a positive integer for the number of copies on localhost.
- **...** (options) - Optional - Options to be passed to the function spawning the workers.

## makeForkCluster

### Description
Creates a forked cluster.

### Parameters
- **nnodes** (integer) - Optional - The number of nodes to be forked (defaults to getOption("mc.cores", 2L)).

## stopCluster

### Description
Stops a cluster.

### Parameters
- **cl** (object) - Optional - An object of class "cluster".
```

--------------------------------

### Cluster Execution Functions

Source: https://www.rdocumentation.org/packages/parallel/versions/3.6.2/topics/clusterApply

Functions for executing code, exporting variables, and splitting data across cluster nodes.

```APIDOC
## clusterCall, clusterEvalQ, clusterExport, clusterSplit

### Description
Functions to manage cluster execution, export variables to nodes, and split data sequences.

### Parameters
- **cl** (cluster object) - Optional - The cluster object to use; defaults to registered cluster if NULL.
- **fun** (function/string) - Required - The function to execute.
- **expr** (expression) - Required - The expression to evaluate on nodes.
- **varlist** (character vector) - Required - Names of objects to export.
- **seq** (vector) - Required - The vector to split.
```

--------------------------------

### Parallel Cluster Operation Signatures

Source: https://www.rdocumentation.org/packages/parallel/versions/3.6.2/topics/clusterApply

Usage definitions for cluster-based parallel functions in the parallel package.

```R
clusterCall(cl = NULL, fun, ...)
clusterApply(cl = NULL, x, fun, ...)
clusterApplyLB(cl = NULL, x, fun, ...)
clusterEvalQ(cl = NULL, expr)
clusterExport(cl = NULL, varlist, envir = .GlobalEnv)
clusterMap(cl = NULL, fun, ..., MoreArgs = NULL, RECYCLE = TRUE,
           SIMPLIFY = FALSE, USE.NAMES = TRUE,
           .scheduling = c("static", "dynamic"))
clusterSplit(cl = NULL, seq)
parLapply(cl = NULL, X, fun, ..., chunk.size = NULL)
parSapply(cl = NULL, X, FUN, ..., simplify = TRUE,
          USE.NAMES = TRUE, chunk.size = NULL)
parApply(cl = NULL, X, MARGIN, FUN, ..., chunk.size = NULL)
parRapply(cl = NULL, x, FUN, ..., chunk.size = NULL)
parCapply(cl = NULL, x, FUN, ..., chunk.size = NULL)
parLapplyLB(cl = NULL, X, fun, ..., chunk.size = NULL)
parSapplyLB(cl = NULL, X, FUN, ..., simplify = TRUE,
          USE.NAMES = TRUE, chunk.size = NULL)
```

--------------------------------

### splitIndices Function

Source: https://www.rdocumentation.org/packages/parallel/versions/3.6.2/topics/splitIndices

Divides a range of tasks into lists for cluster distribution.

```APIDOC
## splitIndices

### Description
Divides up 1:nx into ncl lists of approximately equal size, as a way to allocate tasks to nodes in a cluster.

### Usage
splitIndices(nx, ncl)

### Arguments
- **nx** (integer) - Number of tasks.
- **ncl** (integer) - Number of cluster nodes.

### Value
A list of length ncl, each element being an integer vector.

### Request Example
splitIndices(20, 3)
```

--------------------------------

### Set Default Parallel Cluster

Source: https://www.rdocumentation.org/packages/parallel/versions/3.6.2/topics/makeCluster

setDefaultCluster registers a cluster as the default. This is useful for functions that automatically use the default cluster.

```R
setDefaultCluster(cl = NULL)
```

--------------------------------

### RNGstreams Management Functions

Source: https://www.rdocumentation.org/packages/parallel/versions/3.6.2/topics/RNGstreams

Functions for generating and managing pseudo-random number streams and substreams for parallel tasks.

```APIDOC
## nextRNGStream(seed)

### Description
Calculates the next stream of pseudo-random numbers based on the provided seed.

### Parameters
#### Request Body
- **seed** (integer vector) - Required - An integer vector of length 7 as given by .Random.seed when the "L'Ecuyer-CMRG" RNG is in use.

### Response
- **value** (integer vector) - A value which can be assigned to .Random.seed.

---

## nextRNGSubStream(seed)

### Description
Calculates the next substream of pseudo-random numbers based on the provided seed.

### Parameters
#### Request Body
- **seed** (integer vector) - Required - An integer vector of length 7 as given by .Random.seed when the "L'Ecuyer-CMRG" RNG is in use.

### Response
- **value** (integer vector) - A value which can be assigned to .Random.seed.

---

## clusterSetRNGStream(cl = NULL, iseed)

### Description
Selects the "L'Ecuyer-CMRG" RNG and distributes streams to the members of a cluster.

### Parameters
#### Request Body
- **cl** (cluster object) - Optional - A cluster from this package or package snow, or NULL for the registered cluster.
- **iseed** (integer) - Required - An integer to be supplied to set.seed, or NULL not to set reproducible seeds.

---

## mc.reset.stream()

### Description
Resets the random number stream to make runs from mcparallel(mc.set.seed = TRUE) reproducible.
```

--------------------------------

### RNG Stream Management Functions

Source: https://www.rdocumentation.org/packages/parallel/versions/3.6.2/topics/RNGstreams

These functions manage pseudo-random number streams for parallel computations. `nextRNGStream` and `nextRNGSubStream` advance the current stream, while `clusterSetRNGStream` distributes streams to cluster members.

```R
nextRNGStream(seed)
nextRNGSubStream(seed)
clusterSetRNGStream(cl = NULL, iseed)
mc.reset.stream()

```

--------------------------------

### Stop Parallel Cluster

Source: https://www.rdocumentation.org/packages/parallel/versions/3.6.2/topics/makeCluster

stopCluster terminates a specified cluster. If no cluster is provided, it stops the default cluster.

```R
stopCluster(cl = NULL)
```
Tokens:
Raw