# Documentation

### This is machine translation

Translated by
Mouseover text to see original. Click the button below to return to the English version of the page.

## Establish Arrays on a GPU

### Transfer Arrays Between Workspace and GPU

#### Send Arrays to the GPU

A `gpuArray` in MATLAB® represents an array that is stored on the GPU. Use the `gpuArray` function to transfer an array from MATLAB to the GPU:

```N = 6; M = magic(N); G = gpuArray(M);```

`G` is now a MATLAB gpuArray object that represents the magic square stored on the GPU. The input provided to `gpuArray` must be numeric (for example: `single`, `double`, `int8`, etc.) or logical. (See also Considerations for Complex Numbers.)

#### Retrieve Arrays from the GPU

Use the `gather` function to retrieve arrays from the GPU to the MATLAB workspace. This takes an array that is on the GPU represented by a gpuArray object, and transfers it to the MATLAB workspace as a regular MATLAB array. You can use `isequal` to verify that you get the correct values back:

```G = gpuArray(ones(100,'uint32')); D = gather(G); OK = isequal(D,ones(100,'uint32'))```

#### Examples: Transfer Array

Transfer Array to the GPU.  Create a 1000-by-1000 random matrix in MATLAB, and then transfer it to the GPU:

```X = rand(1000); G = gpuArray(X); ```

Transfer Array of a Specified Precision.  Create a matrix of double-precision random values in MATLAB, and then transfer the matrix as single-precision from MATLAB to the GPU:

```X = rand(1000); G = gpuArray(single(X));```

Construct an Array for Storing on the GPU.  Construct a 100-by-100 matrix of `uint32` ones and transfer it to the GPU. You can accomplish this with a single line of code:

`G = gpuArray(ones(100,'uint32'));`

### Create GPU Arrays Directly

A number of methods on the gpuArray class allow you to directly construct arrays on the GPU without having to transfer arrays from the MATLAB workspace. These constructors require only array size and data class information, so they can construct an array without any elements from the workspace. Use any of the following to directly create an array on the GPU:

 `eye(___,'gpuArray')` `rand(___,'gpuArray')` `false(___,'gpuArray')` `randi(___,'gpuArray')` `Inf(___,'gpuArray')` `randn(___,'gpuArray')` `NaN(___,'gpuArray')` `gpuArray.``freqspace` `ones(___,'gpuArray')` `gpuArray.``linspace` `true(___,'gpuArray')` `gpuArray.``logspace` `zeros(___,'gpuArray')` `gpuArray.``colon`

For a complete list of available static methods in any release, type

`methods('gpuArray')`

The constructors appear at the bottom of the output from this command.

For help on any one of the constructors, type

`help gpuArray/functionname`

For example, to see the help on the `colon` constructor, type

`help gpuArray/colon`

#### Example: Construct an Identity Matrix on the GPU

To create a 1024-by-1024 identity matrix of type `int32` on the GPU, type

```II = eye(1024,'int32','gpuArray'); size(II)```
` 1024 1024`

With one numerical argument, you create a 2-dimensional matrix.

#### Example: Construct a Multidimensional Array on the GPU

To create a 3-dimensional array of ones with data class `double` on the GPU, type

```G = ones(100,100,50,'gpuArray'); size(G)```
``` 100 100 50 ```
`classUnderlying(G)`
```double ```

The default class of the data is `double`, so you do not have to specify it.

#### Example: Construct a Vector on the GPU

To create a 8192-element column vector of zeros on the GPU, type

```Z = zeros(8192,1,'gpuArray'); size(Z)```
` 8192 1`

For a column vector, the size of the second dimension is 1.

#### Control the Random Stream for gpuArray

The following functions control the random number stream on the GPU:

 `parallel.gpu.rng` `parallel.gpu.RandStream`

These functions perform in the same way as `rng` and `RandStream` in MATLAB, but with certain limitations on the GPU. For more information on the use and limits of these functions, type

```help parallel.gpu.rng help parallel.gpu.RandStream```

The GPU uses the combined multiplicative recursive generator by default to create uniform random values, and uses inversion for creating normal values. This is not the default stream in a client MATLAB session on the CPU, but is the equivalent of

`RandStream('CombRecursive','NormalTransform','Inversion');`

However, a MATLAB worker session has the same default stream as its GPU, even if it is a worker in a local cluster on the same machine. That is, a MATLAB client and workers do not have the same default stream.

In most cases, it does not matter that the default random stream on the GPU is not the same as the default stream in MATLAB on the CPU. But if you need to reproduce the same stream on both GPU and CPU, you can set the CPU random stream accordingly, and use the same seed to set both streams:

```seed=0; n=4; cpu_stream = RandStream('CombRecursive','Seed',seed,'NormalTransform','Inversion'); RandStream.setGlobalStream(cpu_stream); gpu_stream = parallel.gpu.RandStream('CombRecursive','Seed',seed); parallel.gpu.RandStream.setGlobalStream(gpu_stream); r = rand(n); % On CPU R = rand(n,'gpuArray'); % On GPU OK = isequal(r,R)```
` 1`

There are three supported random generators on the GPU. The combined multiplicative recursive generator (MRG32K3A) is the default because it is a popular and reliable industry standard generator for parallel computing. You can choose the GPU random generator with any of the following commands:

```parallel.gpu.RandStream('combRecursive') parallel.gpu.RandStream('Philox4x32-10') parallel.gpu.RandStream('Threefry4x64-20')```

For more information about generating random numbers on a GPU, and a comparison between GPU and CPU generation, see Control Random Number Streams. For an example that shows performance comparisons for different random generators, see Generating Random Numbers on a GPU.

### Examine gpuArray Characteristics

There are several functions available for examining the characteristics of a gpuArray object:

FunctionDescription
`classUnderlying`Class of the underlying data in the array
`existsOnGPU`Indication if array exists on the GPU and is accessible
`isreal`Indication if array data is real
`length`Length of vector or largest array dimension
`ndims`Number of dimensions in the array
`size`Size of array dimensions

For example, to examine the size of the gpuArray object `G`, type:

```G = rand(100,'gpuArray'); s = size(G)```
` 100 100`