codistributed

Access elements of arrays distributed among workers in parallel pool

Description

Arrays partitioned among the workers in a parallel pool are accessible from the workers as Codistributed array objects. Codistributed array objects on workers that you create inside spmd statements or from within task functions of communicating jobs are accessed as distributed arrays on the client.

Creation

Use either the codistributed function, or the codistributed.build function to create a codistributed object.

Syntax

C = codistributed(X)

C = codistributed(X,codist)

C = codistributed(X,workerIndex,codist)

C = codistributed(C1,codist)

Description

C = codistributed(X) distributes a replicated array X using the default codistributor and returns a codistributed array C. X must be a replicated array, that is, it must have the same value on all workers. The size of array C is the same as the size of X.

C = codistributed(X,codist) distributes a replicated array X using the distribution scheme defined by codistributor codist. X must be a replicated array, that is, it must have the same value on all workers. The size of C is the same as the size of X. For information on constructing codistributor objects, see codistributor1d and codistributor2dbc.

C = codistributed(X,workerIndex,codist) distributes a local array X that resides on the worker identified by workerIndex, using the codistributor codist. The local array X must be defined on all workers, but the function uses only the WorkerIndex to construct C. size(C) is the same as the size of X.

C = codistributed(C1,codist) accepts an array C1 that is already codistributed, and redistributes it into C according to the distribution scheme defined by the codistributor codist. This syntax is equivalent to C = redistribute(C1,codist). If the existing distribution scheme for C1 is the same as that specified in codist, then the result C is the same as the input C1.

Input Arguments

X — Array to distribute

array

Array to distribute, specified as an array.

codist — Codistributor

codistributor1d object | codistributor2dbc object

Codistributor, specified as a codistributor1d or codistributor2dbc object. For information on creating codistributors, see codistributor1d and codistributor2dbc. To use the default distribution scheme, you can specify a codistributor constructor without arguments.

workerIndex — Index of worker

positive integer scalar

Index of the worker where the local array is stored, specified as a positive integer scalar.

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64

C1 — Codistributed array to redistribute

codistributed array

Codistributed array to redistribute, specified as a codistributed array.

Output Arguments

C — Codistributed array

codistributed array

Codistributed array stored on parts of workers in a parallel pool.

Object Functions

codistributed.cell	Create codistributed cell array
codistributed.colon	Distributed colon operation
codistributed.spalloc	Allocate space for sparse codistributed matrix
codistributed.speye	Create codistributed sparse identity matrix
codistributed.sprand	Create codistributed sparse array of uniformly distributed pseudo-random values
codistributed.sprandn	Create codistributed sparse array of normally distributed pseudo-random values
eye	Create codistributed identity matrix
false	Create codistributed array of logical 0 (false)
gather	Transfer distributed array, Composite array or gpuArray to local workspace
getCodistributor	Codistributor object for existing codistributed array
getLocalPart	Local portion of codistributed array
globalIndices	Global indices for local part of codistributed array
Inf	Create codistributed array of all Inf values
iscodistributed	True for codistributed array
NaN	Create codistributed array of all NaN values
ones	Create codistributed array of all ones
rand	Create codistributed array of uniformly distributed random numbers
randi	Create codistributed array of uniformly distributed random integers
randn	Create codistributed array of normally distributed random numbers
redistribute	Redistribute codistributed array with another distribution scheme
sparse	Create codistributed sparse matrix
true	Create codistributed array of logical 1 (true)
zeros	Create codistributed array of all zeros

The object functions for codistributed arrays are too numerous to list here. Most resemble and behave the same as built-in MATLAB^® functions. For a complete list of object functions, see Run MATLAB Functions with Distributed Arrays.

Among the object functions there are several for examining the characteristics of the array itself. Most behave like the MATLAB functions of the same name.

iscodistributed	True for codistributed array
isreal	Determine whether array uses complex storage
isUnderlyingType	Determine whether input has specified underlying data type
length	Length of largest array dimension
ndims	Number of array dimensions
size	Array size
underlyingType	Type of underlying data determining array behavior

Examples

Create Codistributed Arrays

Create a 1000-by-1000 codistributed array C1 using the default distribution scheme.

parpool('Processes',4)
spmd
    N = 1000;
    X = magic(N);          
    C1 = codistributed(X); 
end

Array X is replicated on every worker, and array C1 is partitioned among the workers.

Create Codistributed Arrays with Distribution Scheme

Create a 1000-by-1000 codistributed array C2, distributed by rows (over the first dimension) with the codistributor1d distribution scheme.

spmd
    N = 1000;
    X = magic(N);
    C2 = codistributed(X,codistributor1d(1));
end

Tips

The gather function performs the inverse of codistributed. Use the gather function to retrieve codistributed arrays into the client work space.

Alternative Functionality

You can also create a codistributed array explicitly from spmd code or a communicating job task with any of these MATLAB functions.

• codistributed.cell

• codistributed.spalloc

• codistributed.speye

• codistributed.sprand

• codistributed.sprandn

Version History

Introduced in R2008b