### Navigation

- index
- modules |
- next |
- previous |
- NumPy v1.3 Manual (DRAFT) »
- NumPy Reference »
- Routines »
- Input and output »

# numpy.memmap

class `numpy.``memmap`

  Create a memory-map to an array stored in a file on disk.

  Memory-mapped files are used for accessing small segments of large files on disk, without reading the entire file into memory. Numpy’s memmap’s are array-like objects. This differs from Python’s `mmap` module, which uses file-like objects.

  > Parameters: | filename : string or file-like object The file name or file object to be used as the array data buffer. dtype : data-type, optional The data-type used to interpret the file contents. Default is uint8 mode : {‘r+’, ‘r’, ‘w+’, ‘c’}, optional The file is opened in this mode:
  > ‘r’ | Open existing file for reading only.
  > ‘r+’ | Open existing file for reading and writing.
  > ‘w+’ | Create or overwrite existing file for reading and writing.
  > ‘c’ | Copy-on-write: assignments affect data in memory, but changes are not saved to disk. The file on disk is read-only.
  Default is ‘r+’. offset : integer, optional In the file, array data starts at this offset. offset should be a multiple of the byte-size of dtype. Requires shape=None. The default is 0. shape : tuple, optional The desired shape of the array. By default, the returned array will be 1-D with the number of elements determined by file size and data-type. order : {‘C’, ‘F’}, optional Specify the order of the ndarray memory layout: C (row-major) or Fortran (column-major). This only has an effect if the shape is greater than 1-D. The defaullt order is ‘C’.
  Methods: | close : Close the memmap file. flush : Flush any changes in memory to file on disk. When you delete a memmap object, flush is called first to write changes to disk before removing the object.

  Notes

  Memory-mapped arrays use the the Python memory-map object which (prior to Python 2.5) does not allow files to be larger than a certain size depending on the platform. This size is always < 2GB even on 64-bit systems.

  Examples

      >>> data = np.arange(12, dtype='float32')
      >>> data.resize((3,4))

  This example uses a temporary file so that doctest doesn’t write files to your directory. You would use a ‘normal’ filename.

      >>> from tempfile import mkdtemp
      >>> import os.path as path
      >>> filename = path.join(mkdtemp(), 'newfile.dat')

  Create a memmap with dtype and shape that matches our data:

      >>> fp = np.memmap(filename, dtype='float32', mode='w+', shape=(3,4))
      >>> fp
      memmap([[ 0.,  0.,  0.,  0.],
              [ 0.,  0.,  0.,  0.],
              [ 0.,  0.,  0.,  0.]], dtype=float32)

  Write data to memmap array:

      >>> fp[:] = data[:]
      >>> fp
      memmap([[  0.,   1.,   2.,   3.],
              [  4.,   5.,   6.,   7.],
              [  8.,   9.,  10.,  11.]], dtype=float32)

  Deletion flushes memory changes to disk before removing the object:

      >>> del fp

  Load the memmap and verify data was stored:

      >>> newfp = np.memmap(filename, dtype='float32', mode='r', shape=(3,4))
      >>> newfp
      memmap([[  0.,   1.,   2.,   3.],
              [  4.,   5.,   6.,   7.],
              [  8.,   9.,  10.,  11.]], dtype=float32)

  Read-only memmap:

      >>> fpr = np.memmap(filename, dtype='float32', mode='r', shape=(3,4))
      >>> fpr.flags.writeable
      False

  Cannot assign to read-only, obviously:

      >>> fpr[0, 3] = 56
      Traceback (most recent call last):
          ...
      RuntimeError: array is not writeable

  Copy-on-write memmap:

      >>> fpc = np.memmap(filename, dtype='float32', mode='c', shape=(3,4))
      >>> fpc.flags.writeable
      True

  It’s possible to assign to copy-on-write array, but values are only written into the memory copy of the array, and not written to disk:

      >>> fpc
      memmap([[  0.,   1.,   2.,   3.],
              [  4.,   5.,   6.,   7.],
              [  8.,   9.,  10.,  11.]], dtype=float32)
      >>> fpc[0,:] = 0
      >>> fpc
      memmap([[  0.,   0.,   0.,   0.],
              [  4.,   5.,   6.,   7.],
              [  8.,   9.,  10.,  11.]], dtype=float32)

  File on disk is unchanged:

      >>> fpr
      memmap([[  0.,   1.,   2.,   3.],
              [  4.,   5.,   6.,   7.],
              [  8.,   9.,  10.,  11.]], dtype=float32)

  Offset into a memmap:

      >>> fpo = np.memmap(filename, dtype='float32', mode='r', offset=16)
      >>> fpo
      memmap([  4.,   5.,   6.,   7.,   8.,   9.,  10.,  11.], dtype=float32)

### Navigation

- index
- modules |
- next |
- previous |
- NumPy v1.3 Manual (DRAFT) »
- NumPy Reference »
- Routines »
- Input and output »