Main Content

codistributor2dbc

2-D block-cyclic distribution scheme for codistributed array

    Description

    A codistributor2dbc object defines the two-dimensional block-cyclic distribution scheme for a codistributed array object. The 2-D block-cyclic codistributor can distribute only two-dimensional matrices. It distributes matrices along two subscripts over a rectangular computational grid of workers in a blocked, cyclic manner. For a complete description of 2-D block-cyclic distribution, default parameters, and the relationship between block size and worker grid, see 2-Dimensional Distribution. The parallel matrix computation software library ScaLAPACK uses the 2-D block-cyclic codistributor.

    Creation

    Description

    example

    codist = codistributor2dbc creates a two-dimensional block-cyclic codistributed2dbc codistributor object using the default worker grid and block size.

    codist = codistributor2dbc(WorkerGrid) creates a two-dimensional block-cyclic codistributor object with a specified WorkerGrid value and default block size.

    codist = codistributor2dbc(WorkerGrid,BlockSize) creates a two-dimensional block-cyclic codistributor object with the specified WorkerGrid and BlockSize values.

    codist = codistributor2dbc(WorkerGrid,BlockSize,Orientation) also specifies the Orientation property.

    The resulting codistributor of any of the above syntaxes is incomplete because its global size is not specified. Use a codistributor constructed this way as an argument to other functions as a template codistributor when creating codistributed arrays.

    example

    codist = codistributor2dbc(WorkerGrid,BlockSize,Orientation,gsize) creates a codistributor object with the global size gsize.

    The resulting codistributor object is complete. Use a codistributor constructed this way to build a codistributed array from its local parts with the codistributed.build function. To use the default values for each argument, specify WorkerGrid as codistributor2dbc.defaultWorkerGrid, BlockSize as codistributor2dbc.defaultBlockSize, and Orientation as codistributor2dbc.defaultOrientation.

    Input Arguments

    expand all

    Global size of the codistributed array, specified as an integer.

    Properties

    expand all

    Worker grid of the codistributor2dbc object, specified as a two-element vector defining the rows and columns of the worker grid. The number of rows multiplied by the number of columns must equal the number of workers for the codistributed array.

    Block size of the codistributor2dbc object, specified as a positive integer. This property is the ScaLAPACK block size associated with the codistributor2dbc object.

    Orientation of the codistributor2dbc object, specified as one of these values:

    • 'row' – Row orientation

    • 'col' – Column orientation

    Data Types: char

    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
    codistributor2dbc.defaultWorkerGridDefault computational grid for 2-D block-cyclic distributed arrays
    eyeCreate codistributed identity matrix
    falseCreate codistributed array of logical 0 (false)
    globalIndicesGlobal indices for local part of codistributed array
    InfCreate codistributed array of all Inf values
    isCompleteTrue if codistributor object is complete
    NaNCreate codistributed array of all NaN values
    onesCreate codistributed array of all ones
    randCreate codistributed array of uniformly distributed random numbers
    randnCreate codistributed array of normally distributed random numbers
    sparseCreate codistributed sparse matrix
    trueCreate codistributed array of logical 1 (true)
    zerosCreate codistributed array of all zeros

    Examples

    collapse all

    Use a codistributor2dbc object to create an N-by-N matrix of ones.

    N = 1000;
    spmd
        codistr = codistributor2dbc;  
        D = ones(N,codistr);
    end    

    Use a fully specified codistributor2dbc object to create a N-by-N codistributed matrix from its local parts.

    N = 1000;

    Use the default values for the worker grid and block size, and specify the orientation and the grid size of the worker grid.

    spmd
        codistr = codistributor2dbc(...
                     codistributor2dbc.defaultWorkerGrid, ...
                     codistributor2dbc.defaultBlockSize, ...
                     'row',[N,N]); 
    end

    Use the globalIndices method on the codistributor object to get the global indices for the local part of the codistributed array before creating the array itself. Use length to get the length of the largest global index and set it as the size of the local part of the codistributed array. Create the codistributed array with the codistributed.build function.

    spmd
        myLocalSize = [length(globalIndices(codistr,1)), ...
                       length(globalIndices(codistr,2))];
        myLocalPart = spmdIndex*ones(myLocalSize);
        D = codistributed.build(myLocalPart,codistr);
    end

    Then use the spy function to visualize which elements are stored on worker 2.

    spy(D==2)

    The sparsity pattern shows the distribution of the elements of array D stored on worker 2.

    Version History

    Introduced in R2009b