* MappedTensor can now read and write an entire tensor in an accelerated fashion, with a smaller memory footprint than previously

* Changed the calling semantics for `MappedTensor/SliceFunction`, to permit specifying a "write-only" function

Author: DylanMuir

MappedTensor.m

@@ -314,7 +314,7 @@ function delete(mtVar)
          end
       end
 
-      %% Overloaded subsref, subsasg and end
+      %% Overloaded subsref, subsasgn and end
       function [varargout] = subsref(mtVar, subs)
          % - More than one return argument means cell or dot referencing was
          % used
@@ -351,67 +351,70 @@ function delete(mtVar)
          nNumTotalDims = numel(mtVar.vnDimensionOrder);
          vnReferencedTensorSize = size(mtVar);
 
-         % - Handle different numbers of referencing dimensions
-         if (nNumDims == 1)
-            % - Translate from linear refs to indices
-            nNumDims = nNumTotalDims;
-            
-            % - Translate colon indexing
-            if (iscolon(S.subs{1}))
-               S.subs{1} = (1:numel(mtVar))';
-            end
-            
-            % - Get equivalent subscripted indexes
-            vnTensorSize = size(mtVar);
-            [cIndices{1:nNumDims}] = ind2sub(vnTensorSize, S.subs{1});
-            
-            % - Permute indices and convert back to linear indexing
-            vnInvOrder(mtVar.vnDimensionOrder(1:nNumTotalDims)) = 1:nNumTotalDims;
-            vnReferencedTensorSize = vnReferencedTensorSize(vnInvOrder);
-            
-            try
-               S.subs{1} = sub2ind(mtVar.vnOriginalSize, cIndices{vnInvOrder});
-            catch
-               error('MappedTensor:badsubscript', ...
+         % - Catch "read entire stack" condition
+         if (~all(cellfun(@iscolon, S.subs)))
+            % - Handle different numbers of referencing dimensions
+            if (nNumDims == 1)
+               % - Translate from linear refs to indices
+               nNumDims = nNumTotalDims;
+               
+               % - Translate colon indexing
+               if (iscolon(S.subs{1}))
+                  S.subs{1} = (1:numel(mtVar))';
+               end
+               
+               % - Get equivalent subscripted indexes
+               vnTensorSize = size(mtVar);
+               [cIndices{1:nNumDims}] = ind2sub(vnTensorSize, S.subs{1});
+               
+               % - Permute indices and convert back to linear indexing
+               vnInvOrder(mtVar.vnDimensionOrder(1:nNumTotalDims)) = 1:nNumTotalDims;
+               vnReferencedTensorSize = vnReferencedTensorSize(vnInvOrder);
+               
+               try
+                  S.subs{1} = sub2ind(mtVar.vnOriginalSize, cIndices{vnInvOrder});
+               catch
+                  error('MappedTensor:badsubscript', ...
                      '*** MappedTensor: Subscript out of range.');
+               end
+               
+            elseif (nNumDims < nNumTotalDims)
+               % - Wrap up trailing dimensions, matlab style, using linear indexing
+               vnReferencedTensorSize(nNumDims) = prod(vnReferencedTensorSize(nNumDims:end));
+               vnReferencedTensorSize = vnReferencedTensorSize(1:nNumDims);
+               
+               % - Inverse permute index order
+               vnInvOrder(mtVar.vnDimensionOrder(1:nNumDims)) = 1:nNumDims;
+               vnReferencedTensorSize = vnReferencedTensorSize(vnInvOrder(vnInvOrder ~= 0));
+               S.subs = S.subs(vnInvOrder(vnInvOrder ~= 0));
+               
+            elseif (nNumDims == nNumTotalDims)
+               % - Simply permute and access tensor
+               
+               % - Permute index order
+               vnInvOrder(mtVar.vnDimensionOrder(1:nNumTotalDims)) = 1:nNumTotalDims;
+               vnReferencedTensorSize = vnReferencedTensorSize(vnInvOrder);
+               S.subs = S.subs(vnInvOrder);
+               
+            else % (nNumDims > nNumTotalDims)
+               % - Check for non-colon references
+               vbNonColon = ~cellfun(@iscolon, S.subs);
+               
+               % - Check only trailing dimensions
+               vbNonColon(1:nNumTotalDims) = false;
+               
+               % - Check trailing dimensions for non-'1' indices
+               if (any(cellfun(@(c)(~isequal(c, 1)), S.subs(vbNonColon))))
+                  % - This is an error
+                  error('MappedTensor:badsubscript', ...
+                     '*** MappedTensor: Subscript out of range.');
+               end
+               
+               % - Permute index order
+               vnInvOrder(mtVar.vnDimensionOrder(1:nNumTotalDims)) = 1:nNumTotalDims;
+               vnReferencedTensorSize = vnReferencedTensorSize(vnInvOrder);
+               S.subs = S.subs(vnInvOrder);
             end
-            
-         elseif (nNumDims < nNumTotalDims)
-            % - Wrap up trailing dimensions, matlab style, using linear indexing
-            vnReferencedTensorSize(nNumDims) = prod(vnReferencedTensorSize(nNumDims:end));
-            vnReferencedTensorSize = vnReferencedTensorSize(1:nNumDims);
-            
-            % - Inverse permute index order
-            vnInvOrder(mtVar.vnDimensionOrder(1:nNumDims)) = 1:nNumDims;
-            vnReferencedTensorSize = vnReferencedTensorSize(vnInvOrder(vnInvOrder ~= 0));
-            S.subs = S.subs(vnInvOrder(vnInvOrder ~= 0));
-            
-         elseif (nNumDims == nNumTotalDims)
-            % - Simply permute and access tensor
-            
-            % - Permute index order
-            vnInvOrder(mtVar.vnDimensionOrder(1:nNumTotalDims)) = 1:nNumTotalDims;
-            vnReferencedTensorSize = vnReferencedTensorSize(vnInvOrder);
-            S.subs = S.subs(vnInvOrder);
-            
-         else % (nNumDims > nNumTotalDims)
-            % - Check for non-colon references
-            vbNonColon = ~cellfun(@iscolon, S.subs);
-            
-            % - Check only trailing dimensions
-            vbNonColon(1:nNumTotalDims) = false;
-            
-            % - Check trailing dimensions for non-'1' indices
-            if (any(cellfun(@(c)(~isequal(c, 1)), S.subs(vbNonColon))))
-               % - This is an error
-               error('MappedTensor:badsubscript', ...
-                  '*** MappedTensor: Subscript out of range.');
-            end
-            
-            % - Permute index order
-            vnInvOrder(mtVar.vnDimensionOrder(1:nNumTotalDims)) = 1:nNumTotalDims;
-            vnReferencedTensorSize = vnReferencedTensorSize(vnInvOrder);
-            S.subs = S.subs(vnInvOrder);            
          end
 
          % - Reference the tensor data element
@@ -876,7 +879,7 @@ function disp(mtVar)
          % - Which dimension should we go along?
          if (nargin < 3)
             % - Find the first non-singleton dimension
-            [nul, nDim] = find(vnSize > 1, 1, 'first');
+            [nul, nDim] = find(vnSize > 1, 1, 'first'); %#ok<ASGLU>
          else
             nDim = varargin{2};
          end
@@ -905,7 +908,7 @@ function disp(mtVar)
          % - Which dimension should we go along?
          if (nargin < 3)
             % - Find the first non-singleton dimension
-            [nul, nDim] = find(vnSize > 1, 1, 'first');
+            [nul, nDim] = find(vnSize > 1, 1, 'first'); %#ok<ASGLU>
          else
             nDim = varargin{2};
          end
@@ -921,11 +924,11 @@ function disp(mtVar)
       end
 
       %% SliceFunction - METHOD Execute a function on the entire tensor, in slices
-      function [mtNewVar] = SliceFunction(mtVar, fhFunction, nSliceDim, vnSliceSize, varargin)
+      function [mtNewVar] = SliceFunction(mtVar, fhFunction, nSliceDim, vnSliceSize, bWriteOnly, varargin)
          % SliceFunction - METHOD Execute a function on the entire tensor, in slices
          %
          % Usage: [<mtNewVar>] = SliceFunction(mtVar,
-         %           fhFunctionHandle, nSliceDim <, vnSliceSize,> ...)
+         %           fhFunctionHandle, nSliceDim <, vnSliceSize, bWriteOnly,> ...)
          %
          % 'mtVar' is a MappedTensor.  This tensor will be sliced up along
          % dimensions 'nSliceDim', with each slice passed individually to
@@ -1011,6 +1014,14 @@ function disp(mtVar)
             end
          end
 
+         % - Do we need to read from the source tensor, or does the slice
+         % function only write?
+         if (nargin(fhFunction) == 0) || exist('bWriteOnly', 'var') || (bWriteOnly == true)
+            bWriteOnly = true;
+         else
+            bWriteOnly = false;
+         end
+         
          % - If an explicit return argument is requested, construct a new tensor
          if (nargout == 1)
             bNewTensor = true;
@@ -1075,8 +1086,14 @@ function disp(mtVar)
             mnTheseDestChunks = bsxfun(@plus, mnDestChunkIndices, [(nIndex-1) * nDestWindowStep 0 0]);
 
             % - Handle a "slice assign" function with no input arguments efficiently
-            if (nargin(fhFunction) == 0)
-               tData = fhFunction();
+            if (bWriteOnly)
+               % - Call function
+               if (nargin(fhFunction) == 0)
+                  tData = fhFunction();
+               else
+                  tData = fhFunction([], nIndex, varargin{:});
+               end
+               
                mtVar.hShimFunc('write_chunks', mtNewVar.hRealContent, mnTheseDestChunks, 1:numel(tData), size(tData), mtNewVar.strClass, mtNewVar.nHeaderBytes, tData ./ mtVar.fRealFactor, mtVar.bBigEndian);
 
             else
@@ -1539,31 +1556,62 @@ function isvalidsubscript(oRefs)
 
 % mt_read_data - FUNCTION Read a set of indices from the file, in an optimsed fashion
 function [tData] = mt_read_data(hShimFunc, hDataFile, sSubs, vnTensorSize, strClass, nHeaderBytes, bBigEndian, hRepSumFunc, hChunkLengthFunc)
+
+   % - Catch "read whole tensor" condition
+   if (all(cellfun(@iscolon, sSubs.subs)))
+      nNumStackElems = prod(vnTensorSize);
+      vnFileChunkIndices = [1 1 nNumStackElems];
+      tData = 1:nNumStackElems;     % Use a pre-allocated vector to save memory
+      
+      % - Read data
+      tData = hShimFunc('read_chunks', hDataFile, vnFileChunkIndices, ...
+         tData, tData, vnTensorSize, ...
+         strClass, nHeaderBytes, double(bBigEndian));
+            
+      % - Reshape stack and return
+      tData = reshape(tData, vnTensorSize);
+      return;
+   end
+
    % - Check referencing and convert to linear indices
    [vnLinearIndices, vnDataSize] = ConvertColonsCheckLims(sSubs.subs, vnTensorSize, hRepSumFunc);
 
    % - Maximise chunk probability and minimise number of reads by reading
    % only sorted unique entries
-   [vnUniqueIndices, nul, vnReverseSort] = unique_accel(vnLinearIndices);
+   [vnLinearIndices, nul, vnReverseSort] = unique_accel(vnLinearIndices); %#ok<ASGLU>
 
    % - Split into readable chunks
-   mnFileChunkIndices = SplitFileChunks(vnUniqueIndices, hChunkLengthFunc);
+   mnFileChunkIndices = SplitFileChunks(vnLinearIndices, hChunkLengthFunc);
 
    % - Call shim read function
-   tData = hShimFunc('read_chunks', hDataFile, mnFileChunkIndices, vnUniqueIndices, vnReverseSort, vnDataSize, strClass, nHeaderBytes, double(bBigEndian));
+   tData = hShimFunc('read_chunks', hDataFile, mnFileChunkIndices, vnLinearIndices, vnReverseSort, vnDataSize, strClass, nHeaderBytes, double(bBigEndian));
 end
 
 % mt_write_data - FUNCTION Read a set of indices from the file, in an optimsed fashion
 function mt_write_data(hShimFunc, hDataFile, sSubs, vnTensorSize, strClass, nHeaderBytes, tData, bBigEndian, hRepSumFunc, hChunkLengthFunc)
+
+   % - Catch "read whole tensor" condition
+   if (all(cellfun(@iscolon, sSubs.subs)))
+      nNumStackElems = prod(vnTensorSize);
+      vnFileChunkIndices = [1 1 nNumStackElems];
+      vnLinearIndices = 1:nNumStackElems;
+      
+      % - Write data and return
+      hShimFunc('write_chunks', hDataFile, vnFileChunkIndices, ...
+         vnLinearIndices, vnTensorSize, ...
+         strClass, nHeaderBytes, cast(tData, strClass), double(bBigEndian));
+      return;
+   end
+
    % - Check referencing and convert to linear indices
    [vnLinearIndices, vnDataSize] = ConvertColonsCheckLims(sSubs.subs, vnTensorSize, hRepSumFunc);
 
    % - Maximise chunk probability and minimise number of writes by writing
    % only sorted unique entries
-   [vnUniqueIndices, vnUniqueDataIndices] = unique_accel(vnLinearIndices);
+   [vnLinearIndices, vnUniqueDataIndices] = unique_accel(vnLinearIndices);
 
    % - Split into readable chunks
-   mnFileChunkIndices = SplitFileChunks(vnUniqueIndices, hChunkLengthFunc);   
+   mnFileChunkIndices = SplitFileChunks(vnLinearIndices, hChunkLengthFunc);
 
    % - Call shim writing function
    hShimFunc('write_chunks', hDataFile, mnFileChunkIndices, vnUniqueDataIndices, vnDataSize, strClass, nHeaderBytes, cast(tData, strClass), double(bBigEndian));
@@ -1790,7 +1838,7 @@ function mt_write_data_chunks(hDataFile, mnFileChunkIndices, vnUniqueDataIndices
       case 'open'
          if (nargin == 2)
             [varargout{1}] = fopen(varargin{1}, 'r+');
-            [nul, nul, varargout{2}, nul] = fopen(varargout{1}); %#ok<NASGU>
+            [nul, nul, varargout{2}, nul] = fopen(varargout{1}); %#ok<ASGLU,NASGU>
          else
             varargout{1} = fopen(varargin{1}, 'r+', varargin{2});
          end