ndi.util.writeSparse

  ndi.util.writeSparse - write a sparse N-dimensional array to an .ndisparse file

  ndi.util.writeSparse(FILENAME, A)
  ndi.util.writeSparse(FILENAME, SUBS, VALS, SZ)

  Writes a sparse array to FILENAME using the NDI sparse array binary format
  (see FORMAT below). The file can be read back with ndi.util.readSparse in
  MATLAB or with ndi_sparse.read_sparse in Python; the two implementations
  produce byte-for-byte identical files.

  There are two calling forms:

    ndi.util.writeSparse(FILENAME, A)
        A is a 2-D MATLAB matrix (sparse or full). Its structural nonzeros
        (as returned by FIND) are stored; explicit zeros are dropped.

    ndi.util.writeSparse(FILENAME, SUBS, VALS, SZ)
        An N-dimensional coordinate-list (COO) form.
          SUBS - an nnz-by-ndims matrix of 1-based subscripts. Row k gives the
                 subscripts of the k-th stored entry.
          VALS - an nnz-by-1 vector of values (stored as double).
          SZ   - a 1-by-ndims vector giving the size of the full array along
                 each dimension.
        In this form the entries are written exactly as given; a value that is
        exactly zero is preserved (not dropped).

  =========================================================================
  FORMAT (the NDI sparse array format, version 1)
  =========================================================================
  All multi-byte fields are little-endian. Subscripts are stored 0-based on
  disk; this function converts the 1-based SUBS to 0-based on write, and
  ndi.util.readSparse converts back to 1-based on read.

    offset  type                     meaning
    ------  -----------------------  --------------------------------------
    0       8 x uint8 (ASCII)        magic string 'NDISPARS'
    8       uint32                   format version (currently 1)
    12      uint32                   ndims, the number of dimensions
    16      ndims x uint64           shape (size of each dimension)
    ...     uint64                   nnz, the number of stored entries
    ...     ndims blocks of          subscripts, dimension-major, 0-based:
            nnz x uint64               all nnz indices for dimension 1, then
                                       all nnz indices for dimension 2, etc.
    ...     nnz x float64            the stored values, in the same order

  =========================================================================
  EXAMPLE
  =========================================================================
    A = sparse([1 3 3],[1 2 4],[10 20 30.5],3,4);
    ndi.util.writeSparse('activity.ndisparse', A);
    B = ndi.util.readSparse('activity.ndisparse'); % B is a 3x4 sparse matrix

  See also: ndi.util.readSparse, FIND, SPARSE