Main Content


Access elements of arrays distributed among workers in parallel pool


    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.


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



    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

    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

    codistributed.cellCreate codistributed cell array
    codistributed.colonDistributed colon operation
    codistributed.spallocAllocate space for sparse codistributed matrix
    codistributed.speyeCreate codistributed sparse identity matrix
    codistributed.sprandCreate codistributed sparse array of uniformly distributed pseudo-random values
    codistributed.sprandnCreate codistributed sparse array of normally distributed pseudo-random values
    eyeCreate codistributed identity matrix
    falseCreate codistributed array of logical 0 (false)
    gatherTransfer distributed array, Composite array or gpuArray 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
    NaNCreate codistributed array of all NaN values
    onesCreate codistributed array of all ones
    randCreate codistributed array of uniformly distributed random numbers
    randiCreate codistributed array of uniformly distributed random integers
    randnCreate codistributed array of normally distributed random numbers
    redistributeRedistribute codistributed array with another distribution scheme
    sparseCreate codistributed sparse matrix
    trueCreate codistributed array of logical 1 (true)
    zerosCreate 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.

    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


    collapse all

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

        N = 1000;
        X = magic(N);          
        C1 = codistributed(X); 

    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.

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


    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