Main Content

codistributed

Access elements of arrays distributed among workers in parallel pool

expand all in page

    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,workerIndex)
    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 distribution scheme 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.

    example

    C = codistributed(X,workerIndex) distributes a local array X that resides on the worker identified by workerIndex, using the default codistributor. 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(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.

    example

    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

    expand all

    Array to distribute, specified as an array.

    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.

    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

    Codistributed array to redistribute, specified as a codistributed array.

    Output Arguments

    expand all

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

    Object Functions

    gatherTransfer distributed array, Composite object, or gpuArray object to local workspace
    getCodistributorCodistributor object for existing codistributed array
    getLocalPartLocal portion of codistributed array
    globalIndicesGlobal indices for local part of codistributed array
    InfCreate codistributed array of all Inf values
    iscodistributedTrue for codistributed array
    redistributeRedistribute codistributed array with another distribution scheme

    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.

    iscodistributedTrue for codistributed array
    isrealDetermine whether array uses complex storage
    isUnderlyingTypeDetermine whether input has specified underlying data type
    lengthLength of largest array dimension
    ndimsNumber of array dimensions
    sizeArray size
    underlyingTypeType of underlying data determining array behavior

    Examples

    collapse all

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

    Version History

    Introduced in R2008b

    See Also

    | | | | | | | | | |

    Topics