image thumbnail

Better memory-mapped files in Matlab

version (121 KB) by Dylan Muir
A better, transparent memmapfile, with complex number support.


Updated 18 May 2020

From GitHub

View license on GitHub

See also
If this function is useful to your academic work, please cite the publication in lieu of thanks:
Muir and Kampa, 2015. "FocusStack and StimServer: A new open source MATLAB toolchain for visual stimulation and analysis of two-photon calcium neuronal imaging data". Frontiers in Neuroinformatics.

This class transparently maps large tensors of arbitrary dimensions to temporary files on disk. Referencing is identical to a standard matlab tensor, so a MappedTensor can be passed into functions without requiring that the function be written specifically to use MappedTensors. This is opposed to memmapfile objects, which cannot be used in such a way. Being able to used MappedTensors as arguments requires that the tensor is indexed inside the function (as opposed to using the object with no indices). This implies that a function using a MappedTensor must not be fully vectorised, but must operate on the mapped tensor in segments inside a for loop.

MappedTensor also offers support for basic operations such as permute and sum, without requiring space for the tensor to be allocated in memory. memmapfile sometimes runs out of virtual addressing space, even if the data is stored only on disk. MappedTensor does not suffer from this problem.

Functions that work on every element of a tensor, with an output the same size as the input tensor, can be applied to a MappedTensor without requiring the entire tensor to be allocated in memory. This is done with the convenience function "SliceFunction".
An existing binary file can also be mapped, similarly to memmapfile. However, memmapfile offers more flexibility in terms of file format. MappedTensors transparently support complex numbers, which is an advantage over memmapfile.

mtVar = MappedTensor(500, 500, 1000, 'Class', 'single');
% A new tensor is created, 500x500x1000 of class 'single'.
% A temporary file is generated on disk to contain the data for this tensor.

for (i = 1:1000)
mtVar(:, :, i) = rand(500, 500);
mtVar(:, :, i) = abs(fft(mtVar(:, :, i)));

mtVar = mtVar';


mtVar(:, 1, 1)

mfSum = sum(mtVar, 3);
% The sum is performed without allocating space for mtVar in
% memory.

mtVar2 = SliceFunction(mtVar, @(m)(fft2(m), 3);
% 'fft2' will be applied to each Z-slice of mtVar
% in turn, with the result returned in the newly-created
% MappedTensor mtVar2.

clear mtVar mtVar2
% The temporary files are removed

mtVar = MappedTensor('DataDump.bin', 500, 500, 1000);
% The file 'DataDump.bin' is mapped to mtVar.

SliceFunction(mtVar, @()(randn(500, 500)), 3);
% "Slice assignment" is supported, by using "generator" functions that accept no arguments. The assignment occurs while only allocating space for a single tensor slice in memory.

mtVar = -mtVar;
mtVar = 5 + mtVar;
mtVar = 5 - mtVar;
mtVar = 12 .* mtVar;
mtVar = mtVar / 5;
% Unary and binary mathematical operations are supported, as long as they are performed with a scalar. Multiplication, division and negation take O(1) time; addition and subtraction take O(N) time.

Cite As

Dylan Muir (2022). Better memory-mapped files in Matlab (, GitHub. Retrieved .

MATLAB Release Compatibility
Created with R2009a
Compatible with any release
Platform Compatibility
Windows macOS Linux

Community Treasure Hunt

Find the treasures in MATLAB Central and discover how the community can help you!

Start Hunting!
To view or report issues in this GitHub add-on, visit the GitHub Repository.
To view or report issues in this GitHub add-on, visit the GitHub Repository.