parameters: (blocks, format=None, dtype=None)
return_statement: return coo_matrix((data, (row, col)), shape=shape).asformat(format)
docstring: Build a sparse matrix from sparse sub-blocks
  
      Parameters
      ----------
      blocks : array_like
          Grid of sparse matrices with compatible shapes.
          An entry of None implies an all-zero matrix.
      format : {'bsr', 'coo', 'csc', 'csr', 'dia', 'dok', 'lil'}, optional
          The sparse format of the result (e.g. "csr").  By default an
          appropriate sparse matrix format is returned.
          This choice is subject to change.
      dtype : dtype, optional
          The data-type of the output matrix.  If not given, the dtype is
          determined from that of `blocks`.
  
      Returns
      -------
      bmat : sparse matrix
  
      See Also
      --------
      block_diag, diags
  
      Examples
      --------
      >>> from scipy.sparse import coo_matrix, bmat
      >>> A = coo_matrix([[1, 2], [3, 4]])
      >>> B = coo_matrix([[5], [6]])
      >>> C = coo_matrix([[7]])
      >>> bmat([[A, B], [None, C]]).toarray()
      array([[1, 2, 5],
             [3, 4, 6],
             [0, 0, 7]])
  
      >>> bmat([[A, None], [None, C]]).toarray()
      array([[1, 2, 0],
             [3, 4, 0],
             [0, 0, 7]])
docstring_summary: Build a sparse matrix from sparse sub-blocks
docstring_tokens: Build a sparse matrix from sparse sub - blocks
function: def bmat(blocks, format=None, dtype=None):
      """
      Build a sparse matrix from sparse sub-blocks
  
      Parameters
      ----------
      blocks : array_like
          Grid of sparse matrices with compatible shapes.
          An entry of None implies an all-zero matrix.
      format : {'bsr', 'coo', 'csc', 'csr', 'dia', 'dok', 'lil'}, optional
          The sparse format of the result (e.g. "csr").  By default an
          appropriate sparse matrix format is returned.
          This choice is subject to change.
      dtype : dtype, optional
          The data-type of the output matrix.  If not given, the dtype is
          determined from that of `blocks`.
  
      Returns
      -------
      bmat : sparse matrix
  
      See Also
      --------
      block_diag, diags
  
      Examples
      --------
      >>> from scipy.sparse import coo_matrix, bmat
      >>> A = coo_matrix([[1, 2], [3, 4]])
      >>> B = coo_matrix([[5], [6]])
      >>> C = coo_matrix([[7]])
      >>> bmat([[A, B], [None, C]]).toarray()
      array([[1, 2, 5],
             [3, 4, 6],
             [0, 0, 7]])
  
      >>> bmat([[A, None], [None, C]]).toarray()
      array([[1, 2, 0],
             [3, 4, 0],
             [0, 0, 7]])
  
      """
  
      blocks = np.asarray(blocks, dtype='object')
  
      if blocks.ndim != 2:
          raise ValueError('blocks must be 2-D')
  
      M,N = blocks.shape
  
      # check for fast path cases
      if (N == 1 and format in (None, 'csr') and all(isinstance(b, csr_matrix)
                                                     for b in blocks.flat)):
          A = _compressed_sparse_stack(blocks[:,0], 0)
          if dtype is not None:
              A = A.astype(dtype)
          return A
      elif (M == 1 and format in (None, 'csc')
            and all(isinstance(b, csc_matrix) for b in blocks.flat)):
          A = _compressed_sparse_stack(blocks[0,:], 1)
          if dtype is not None:
              A = A.astype(dtype)
          return A
  
      block_mask = np.zeros(blocks.shape, dtype=bool)
      brow_lengths = np.zeros(M, dtype=np.int64)
      bcol_lengths = np.zeros(N, dtype=np.int64)
  
      # convert everything to COO format
      for i in range(M):
          for j in range(N):
              if blocks[i,j] is not None:
                  A = coo_matrix(blocks[i,j])
                  blocks[i,j] = A
                  block_mask[i,j] = True
  
                  if brow_lengths[i] == 0:
                      brow_lengths[i] = A.shape[0]
                  elif brow_lengths[i] != A.shape[0]:
                      msg = ('blocks[{i},:] has incompatible row dimensions. '
                             'Got blocks[{i},{j}].shape[0] == {got}, '
                             'expected {exp}.'.format(i=i, j=j,
                                                      exp=brow_lengths[i],
                                                      got=A.shape[0]))
                      raise ValueError(msg)
  
                  if bcol_lengths[j] == 0:
                      bcol_lengths[j] = A.shape[1]
                  elif bcol_lengths[j] != A.shape[1]:
                      msg = ('blocks[:,{j}] has incompatible row dimensions. '
                             'Got blocks[{i},{j}].shape[1] == {got}, '
                             'expected {exp}.'.format(i=i, j=j,
                                                      exp=bcol_lengths[j],
                                                      got=A.shape[1]))
                      raise ValueError(msg)
  
      nnz = sum(block.nnz for block in blocks[block_mask])
      if dtype is None:
          all_dtypes = [blk.dtype for blk in blocks[block_mask]]
          dtype = upcast(*all_dtypes) if all_dtypes else None
  
      row_offsets = np.append(0, np.cumsum(brow_lengths))
      col_offsets = np.append(0, np.cumsum(bcol_lengths))
  
      shape = (row_offsets[-1], col_offsets[-1])
  
      data = np.empty(nnz, dtype=dtype)
      idx_dtype = get_index_dtype(maxval=max(shape))
      row = np.empty(nnz, dtype=idx_dtype)
      col = np.empty(nnz, dtype=idx_dtype)
  
      nnz = 0
      ii, jj = np.nonzero(block_mask)
      for i, j in zip(ii, jj):
          B = blocks[i, j]
          idx = slice(nnz, nnz + B.nnz)
          data[idx] = B.data
          row[idx] = B.row + row_offsets[i]
          col[idx] = B.col + col_offsets[j]
          nnz += B.nnz
  
      return coo_matrix((data, (row, col)), shape=shape).asformat(format)
function_tokens: def bmat ( blocks , format = None , dtype = None ) : blocks = np . asarray ( blocks , dtype = 'object' ) if blocks . ndim != 2 : raise ValueError ( 'blocks must be 2-D' ) M , N = blocks . shape # check for fast path cases if ( N == 1 and format in ( None , 'csr' ) and all ( isinstance ( b , csr_matrix ) for b in blocks . flat ) ) : A = _compressed_sparse_stack ( blocks [ : , 0 ] , 0 ) if dtype is not None : A = A . astype ( dtype ) return A elif ( M == 1 and format in ( None , 'csc' ) and all ( isinstance ( b , csc_matrix ) for b in blocks . flat ) ) : A = _compressed_sparse_stack ( blocks [ 0 , : ] , 1 ) if dtype is not None : A = A . astype ( dtype ) return A block_mask = np . zeros ( blocks . shape , dtype = bool ) brow_lengths = np . zeros ( M , dtype = np . int64 ) bcol_lengths = np . zeros ( N , dtype = np . int64 ) # convert everything to COO format for i in range ( M ) : for j in range ( N ) : if blocks [ i , j ] is not None : A = coo_matrix ( blocks [ i , j ] ) blocks [ i , j ] = A block_mask [ i , j ] = True if brow_lengths [ i ] == 0 : brow_lengths [ i ] = A . shape [ 0 ] elif brow_lengths [ i ] != A . shape [ 0 ] : msg = ( 'blocks[{i},:] has incompatible row dimensions. ' 'Got blocks[{i},{j}].shape[0] == {got}, ' 'expected {exp}.' . format ( i = i , j = j , exp = brow_lengths [ i ] , got = A . shape [ 0 ] ) ) raise ValueError ( msg ) if bcol_lengths [ j ] == 0 : bcol_lengths [ j ] = A . shape [ 1 ] elif bcol_lengths [ j ] != A . shape [ 1 ] : msg = ( 'blocks[:,{j}] has incompatible row dimensions. ' 'Got blocks[{i},{j}].shape[1] == {got}, ' 'expected {exp}.' . format ( i = i , j = j , exp = bcol_lengths [ j ] , got = A . shape [ 1 ] ) ) raise ValueError ( msg ) nnz = sum ( block . nnz for block in blocks [ block_mask ] ) if dtype is None : all_dtypes = [ blk . dtype for blk in blocks [ block_mask ] ] dtype = upcast ( * all_dtypes ) if all_dtypes else None row_offsets = np . append ( 0 , np . cumsum ( brow_lengths ) ) col_offsets = np . append ( 0 , np . cumsum ( bcol_lengths ) ) shape = ( row_offsets [ - 1 ] , col_offsets [ - 1 ] ) data = np . empty ( nnz , dtype = dtype ) idx_dtype = get_index_dtype ( maxval = max ( shape ) ) row = np . empty ( nnz , dtype = idx_dtype ) col = np . empty ( nnz , dtype = idx_dtype ) nnz = 0 ii , jj = np . nonzero ( block_mask ) for i , j in zip ( ii , jj ) : B = blocks [ i , j ] idx = slice ( nnz , nnz + B . nnz ) data [ idx ] = B . data row [ idx ] = B . row + row_offsets [ i ] col [ idx ] = B . col + col_offsets [ j ] nnz += B . nnz return coo_matrix ( ( data , ( row , col ) ) , shape = shape ) . asformat ( format )