Code covered by the BSD License  

Highlights from
MappedTensor class - memory-mapped files

5.0 | 2 ratings Rate this file 16 Downloads (last 30 days) File Size: 27.5 KB File ID: #29694
image thumbnail

MappedTensor class - memory-mapped files


Dylan Muir (view profile)


13 Dec 2010 (Updated )

A better, transparent memmapfile, with complex number support.

| Watch this File

File Information

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.

Required Products MATLAB
MATLAB release MATLAB 7.8 (R2009a)
MATLAB Search Path
Tags for This File   Please login to tag files.
Please login to add a comment or rating.
Comments and Ratings (4)
10 Feb 2015 Wouter

Wouter (view profile)

Just what I needed in order to process huge (18GB) files in a memory map fashion without the excessive virtual memory usage from matlab's builtin memmapfile functionality.

07 Jul 2014 Dylan Muir

Dylan Muir (view profile)

Hi Holger,
Thanks a lot for your bug report.
I converted the single-line // comments to /*-style comments. I also fixed the htobe16 issue. However, I can't replicate the "fopen" error, and can't see what the problem would be with the line. Could you please try the updated code and let me know?

Comment only
24 Jun 2014 Holger

Holger (view profile)

I found various bugs in the code:
- Line 1590 in mapped_tensor_shim_nomex: One or more output arguments not assigned during call to "fopen".

- In the mex files: The //-style comments are not allowed in ANSI C-code, which is why I had to specify that as a compiler flag (would have been good to know).

- mapped_tensor_shim doesn't compile at all, since htobe16 passed 2 arguments, but takes just 1.

Is it possible that you rework the current for Matlab 2014?

Comment only
06 Nov 2012 Stanislas Rapacchi  
14 Dec 2010

Added a brief example, more details of restrictions.

15 Dec 2010

Added support for "sum"; added SliceFunction.

21 Dec 2010

Fixed a bug in linear indexing of a permuted tensor; added support for slice assignment; added support for complex values.

23 Dec 2010

Added support for unary uplus, uminus; binary plus, minus, times, mtimes, m/l/r/divide (all with a scalar).

16 Aug 2011

Updated image

07 Nov 2011

Updated description

29 May 2012

MappedTensor now does not rely internally on memmapfile, but performs optimised direct binary file reads. It is now much faster than memmapfile, for some tasks. You can now specify a header offset to skip, when mapping an existing file.

31 May 2012

Accelerated SliceFunction; SliceFunction now provides a slice index argument; better error reporting when too many dimensions were used for indexing; SliceFunction now provides feedback during operation

09 Jul 2012

Fixed a referencing bug, where repeated indices and multi-dimensional indices were not referenced correctly on reads.

07 Aug 2012

MappedTensor now uses mex-accellerated internal functions, if possible. MappedTensor is now much faster.

25 Sep 2012

Minor bug fixes

09 Nov 2012

Fixed a regression, such that SliceFunction no longer worked. Thanks to Stanislas Rapacchi for the bug report.

02 Dec 2013

Updated description

26 Mar 2014

Updated description

18 Jun 2014

Updated summary

07 Jul 2014

Fixed several mex compilation bugs.

07 Jul 2014

Removed compiled MEX files from archive

07 Jul 2014

Fixed bug where call to fopen failed

27 Oct 2014

Updated description

05 Nov 2014

Accelerated reading of data, especially when accessing chunks of data in sequential order.

05 Dec 2014

Indexing improvement

08 Dec 2014

Added paper reference.

21 Jan 2015

Updated usage notes.

Contact us