the dimension of matrix when using 'sparse' to generate sparse matrix
19 Comments
@Li - MATLAB's tril() and sparse() functions have never supported 3D arrays, so nothing was actually removed between 2017b and 2025a. I would like a second opinion from @Walter and @Torsten who are experts and do respect their opinions always in the post. It might be you had the ndSparse toolbox installed back then and forgot about it. For your specific problem, you need to apply tril to each 8×8 page individually using a loop, and for the block diagonal creation, the issue with H(8,8,:) is that it extracts only single elements (giving you 1×1×20) rather than the full pages—you need to use num2cell(H, [1 2]) to convert each page to a cell, then pass that to blkdiag. I've put together working code (took some time to implement to help you out) in the artifact below that includes tril3d() and blkdiag3d() utility functions that handle this correctly, and everything works fine with complex doubles (the built-in blkdiag has always supported complex matrices, so if you're getting an error about that, check "which blkdiag -all" to see if a custom function is shadowing the built-in). The code demonstrates the correct approach for your 8×8×20 case and creates the sparse block diagonal matrix you need.
Here is the code
% Solution for Li's 3D matrix problem % Problem: tril() doesn't work on 3D arrays, block diagonal syntax %issues %% Your immediate problem - applying tril to 3D matrices
% your data (8x8 pages, 20 deep, complex)
H = rand(8,8,20) + 1i*rand(8,8,20);
fprintf('Starting with %dx%dx%d complex matrix\n', size(H,1),
size(H,2),
size(H,3));
% tril doesn't accept 3D - you have to loop through pages % there's no built-in function for this unfortunately H_lower = zeros(size(H), 'like', H); % pre-allocate (keeps it complex) for i = 1:size(H,3) H_lower(:,:,i) = tril(H(:,:,i)); end
fprintf('Applied tril to all %d pages\n', size(H,3));
% quick check that it worked
if nnz(triu(H_lower(:,:,1), 1)) == 0
fprintf('Looks good - upper triangles are zero\n');
end
%% Block diagonal - THIS is probably where your syntax was wrong
% WRONG WAY (what you might have tried): % BD = blkdiag(H(8,8,:)) % <- this extracts single elements!
% The problem: H(8,8,:) gives you a 1x1x20 array of just the (8,8) %elements You need the full 8x8 pages
% RIGHT WAY:
pages = num2cell(H_lower, [1 2]); % converts each page to a cell
BD = blkdiag(pages{:}); % now this works correctly
fprintf('\nBlock diagonal created: %dx%d\n', size(BD,1), size(BD,2));
% convert to sparse if you want
BD_sparse = sparse(BD);
sparsity = 100 * (1 - nnz(BD_sparse)/numel(BD_sparse));
fprintf('Sparse version is %.1f%% sparse\n', sparsity);
% verify it's still complex
if ~isreal(BD_sparse)
fprintf('Complex values preserved: %.3f%+.3fi (sample)\n', ...
real(full(BD_sparse(1,1))), imag(full(BD_sparse(1,1))));
end
%% Utility functions you can reuse
% I made these into functions so you don't have to write loops every %time
function result = tril3d(A, k) % apply tril to each page of a 3D array % usage: result = tril3d(A) or result = tril3d(A, k) for diagonal %offset
if nargin < 2
k = 0; % main diagonal by default
end result = zeros(size(A), 'like', A);
for i = 1:size(A,3)
result(:,:,i) = tril(A(:,:,i), k);
end
endfunction result = triu3d(A, k) % same thing but for upper triangular
if nargin < 2
k = 0;
end result = zeros(size(A), 'like', A);
for i = 1:size(A,3)
result(:,:,i) = triu(A(:,:,i), k);
end
endfunction BD = blkdiag3d(A, make_sparse) % creates block diagonal from 3D array pages % usage: BD = blkdiag3d(A) or BD = blkdiag3d(A, true) for sparse
if nargin < 2
make_sparse = false;
end pages = num2cell(A, [1 2]);
BD = blkdiag(pages{:}); if make_sparse
BD = sparse(BD);
end
end%% Test the utility functions
fprintf('\n--- Testing utility functions ---\n');
test_data = rand(4,4,5) + 1i*rand(4,4,5);
% test tril3d
lower = tril3d(test_data);
fprintf('tril3d: processed %dx%dx%d -> check upper triangle: ',
size(test_data));
if nnz(triu(lower(:,:,1),1)) == 0
fprintf('pass\n');
else
fprintf('fail\n');
end
% test triu3d
upper = triu3d(test_data);
fprintf('triu3d: processed %dx%dx%d -> check lower triangle: ',
size(test_data));
if nnz(tril(upper(:,:,1),-1)) == 0
fprintf('pass\n');
else
fprintf('fail\n');
end
% test blkdiag3d
bd_test = blkdiag3d(test_data);
fprintf('blkdiag3d: created %dx%d block diagonal\n', size(bd_test));
% with sparse option
bd_sparse_test = blkdiag3d(test_data, true);
fprintf('blkdiag3d (sparse): %d nonzeros out of %d elements\n', ...
nnz(bd_sparse_test), numel(bd_sparse_test));
%% Complete workflow example with your dimensions
fprintf('\n--- Complete example with your 8x8x20 case ---\n');
% generate data H_example = rand(8,8,20) + 1i*rand(8,8,20);
% apply lower triangular H_example_lower = tril3d(H_example);
% create sparse block diagonal BD_example = blkdiag3d(H_example_lower, true);
fprintf('Input: %dx%dx%d complex matrix\n', size(H_example));
fprintf('Output: %dx%d sparse matrix\n', size(BD_example));
fprintf('Nonzeros: %d (%.2f%% full)\n', nnz(BD_example), ...
100*nnz(BD_example)/numel(BD_example));
% check memory usage
mem_full = 8 * 160 * 160 * 2; % bytes for complex double
mem_sparse = whos('BD_example').bytes;
fprintf('Memory: full would be %.1f MB, sparse is %.1f MB\n', ...
mem_full/1e6, mem_sparse/1e6);
%% Common mistakes to avoid
fprintf('\n--- Common mistakes ---\n');
H_mistake = rand(8,8,20);
% Mistake 1: wrong indexing
wrong = H_mistake(8,8,:);
fprintf('H(8,8,:) gives size %dx%dx%d <- extracts SINGLE ELEMENTS\n',
size(wrong));
correct = num2cell(H_mistake, [1 2]);
fprintf('num2cell(H,[1 2]) gives %d cells of %dx%d each <- THIS is
what you want\n', ...
length(correct), size(correct{1}));
% Mistake 2: trying tril on 3D directly
fprintf('\nDirect tril(3D_array) will fail:\n');
try
bad = tril(H_mistake);
fprintf(' No error? Unexpected.\n');
catch ME
fprintf(' Error: %s\n', ME.message);
fprintf(' Solution: use tril3d() or loop through pages\n');
end
% Mistake 3: sparse on 3D
fprintf('\nDirect sparse(3D_array) will fail:\n');
try
bad = sparse(H_mistake);
fprintf(' No error? Unexpected.\n');
catch ME
fprintf(' Error: %s\n', ME.message);
fprintf(' Solution: create block diagonal first, then sparse
it\n');
end
fprintf('\n--- Done ---\n');
fprintf('Copy the utility functions (tril3d, triu3d, blkdiag3d) to use
in your code\n');
Results: please see attached
Let me know how it goes.
Hi @Li,Now I see exactly what's happening - your error screenshots confirm you're using the ndSparse toolbox, and specifically its tril() function is throwing the error because it has a hard-coded check that refuses to work on arrays with more than 2 dimensions (even though ndSparse is designed for N-dimensional arrays, which seems like a bug or limitation in that version). This explains why it worked before - you likely had a different version of ndSparse or your code was structured slightly differently. Here are two solutions you can use right away:
Option 1 - Quick fix with your current ndSparse setup (just replace your line)
% Your original line that's failing: % HL=spblkdiag(H1(:,:,1:end-1)+H1(:,:,2:end))+ (-1i)*tril(spblkdiag(H2(:,:,1:end-1)+H2(:,:,2:end)));
% Replace with this (applies tril BEFORE spblkdiag): H2_sum = H2(:,:,1:end-1) + H2(:,:,2:end); H2_lower = zeros(size(H2_sum)); for k = 1:size(H2_sum, 3) H2_lower(:,:,k) = tril(H2_sum(:,:,k)); end HL = spblkdiag(H1(:,:,1:end-1)+H1(:,:,2:end)) + (-1i)*spblkdiag(H2_lower);
Option 2 - Use pure MATLAB without ndSparse dependency (copy the utility functions from my previous post, then use)
H2_sum = H2(:,:,1:end-1) + H2(:,:,2:end); H2_lower = tril3d(H2_sum); HL = blkdiag3d(H1(:,:,1:end-1)+H1(:,:,2:end), true) + (-1i)*blkdiag3d(H2_lower, true);
Option 1 should work immediately with your current setup. Option 2 removes the ndSparse dependency entirely if you prefer that approach.
You are close solving your problem. You got this.
Let me know how it goes.
Hi @Li, Thankyou for your kind words. The reason your code worked before but doesn't now is likely one of these scenarios:
Most likely: You updated the ndSparse toolbox to a newer (or older) version that changed how tril() handles 3D arrays. The ndSparse tril() implementation has a dimension check that throws an error for arrays with more than 2 dimensions, even though ndSparse is designed for N-dimensional sparse arrays. This seems like an inconsistency in the toolbox itself.
Other possibilities that I can hypothetically think about:
1. Your H2 array structure was different before (maybe it was 2D and you reshaped/concatenated it differently)
2. You were using MATLAB's built-in tril() instead of ndSparse's tril() (path order changed)
3. Your previous code applied tril() before creating the 3D array
To confirm what changed, check these things: % Check which tril you're using which tril -all
% Check your ndSparse version (if it has version info) ver ndSparse
% Check H2 dimensions size(H2) ndims(H2)
If you want to avoid the for-loop and keep your original one-liner style, you could modify ndSparse's tril.m file directly (if you have edit access) to handle 3D arrays, or create a wrapper function that handles the 3D case automatically.
Again, the for-loop solution I provided is actually quite efficient since it's just looping over the third dimension and MATLAB handles 2D tril() operations very quickly. For most applications, the performance difference will be negligible compared to the spblkdiag operations.
If you find your old code version and it works, compare which tril() function it's calling - that will tell you exactly what changed.
@Li, Your screenshots actually pin down the root of the problem. MATLAB isn’t calling the built-in “tril” at all — it’s dispatching to the one inside “ndSparse/tril.m”. Once that happens, the behavior becomes completely different from what your code used to rely on.
Inside that file, there’s a hard-coded dimension check that rejects anything that isn’t strictly 2-D. The moment your 3-D array comes in from spblkdiag, that check fires and you get the “supports only 2D” error. That alone is enough to break the version of your code that worked last year.
Then there’s the second issue you caught in your screenshot. That same tril.m tries to do
zeros(size(A),'like',A)
but ndSparse objects don’t implement “like”, so MATLAB complains exactly as shown: “Argument following “like” must be a variable…”. That’s a toolbox bug, not something you caused.
Put together, once MATLAB starts using the ndSparse version of tril, it can’t handle your 3-D input and it can’t handle its own “like” syntax. That explains why your old code ran fine before — back then, MATLAB was calling the built-in tril instead of the ndSparse one.
If you want everything to behave the way it used to, the clean fix is to patch @ndSparse/tril.m, so it drops the “like” call and processes N-D data slice by slice. After that, your original code will work again without any changes.
The workaround I gave — looping over the third dimension before calling spblkdiag — is completely valid and usually fast enough. But if restoring the original one-line style is important to you, then updating tril.m by you is the way to get there.
Answers (3)
Hi @li,
I saw your question about MATLAB removing 3D sparse matrix support, and I wanted to help clarify what's happening. Both @Torsten and @Walter Roberson are absolutely correct in their responses to you. MATLAB's native sparse function has actually never supported 3D or N-dimensional arrays. It's always been limited to 2D matrices only, going all the way back to before R2006a.
I know this might be confusing because when you call something like sparse(3, 3, 3), MATLAB doesn't throw an error right away. Instead, it interprets this as the sparse(i, j, v) syntax, where i=3 is the row index, j=3 is the column index, and v=3 is the value. So you end up with a 2D matrix that has a single element at position (3,3) with value 3, not a 3D array at all. This might be why you thought it was working before.
The error message you're seeing now, " Error using sparse, inputs must be 2-D", is actually the function working correctly and enforcing its documented 2D-only limitation. Walter mentioned that the only recent change to sparse was in R2025a, when they added support for single precision matrices alongside the existing double and logical types. That's the first major enhancement in many years, and it had nothing to do with removing any dimensional capabilities.
As Torsten suggested, if you truly need 3D sparse functionality, you'll want to look at the N-dimensional sparse arrays contribution on the MATLAB File Exchange ( https://uk.mathworks.com/matlabcentral/fileexchange/29832-n-dimensional-sparse-arrays ). That's a third-party solution that provides the ndSparse class, which can handle the multidimensional sparse arrays that native MATLAB cannot.
I tested this myself to confirm, and here's some code that demonstrates the 2D limitation:
S1 = sparse(5, 5);
disp('2D sparse matrix created successfully');
disp(S1);
% This also works - 2D sparse with values
i = [1 2 3];
j = [1 2 3];
v = [10 20 30];
S2 = sparse(i, j, v, 5, 5);
disp('2D sparse matrix with values:');
disp(S2);
% This doesn't create 3D - it creates 2D with element at (3,3)
S3 = sparse(3, 3, 3);
disp('This is still 2D:');
disp(['Dimensions: ' num2str(size(S3))]);
disp(['Number of dimensions: ' num2str(ndims(S3))]);
% To truly get the error, try converting a 3D array
try
A_3D = rand(3, 3, 3);
S_3D = sparse(A_3D);
catch ME
disp('Error when trying true 3D:');
disp(ME.message);
end
Note: please see attached.
Hope this helps clar things up. The functionality you're looking for was never in base MATLAB, so nothing was actually removed. You'll need to use a File Exchange solution for 3D sparse arrays.
4 Comments
Hi@Dyuman Joshi, Thank you for your feedback. My answer adds clarification on why users might think 3D worked, a code demonstration, and a concrete solution (ndSparse) for true N-dimensional sparse arrays. These details provide unique value. In the spirit of community, it’s always more helpful to contribute clarifying thoughts rather than just flagging. So,could you please share your thoughts to help @Li over here, I would be more happy to hear what you have to say.
Hi @Catalytic,
I want to clarify the intent of my answer. My goal was to provide additional value beyond what was already stated by others:
I explicitly demonstrated the difference between sparse(3,3,3) and a true 3D array with a reproducible MATLAB script. This helps users see why MATLAB behaves the way it does.
I included a practical solution using cell arrays of sparse matrices for 3D data, which is not mentioned in the previous comments. I provided links to official documentation and historical MathWorks support, showing that 3D sparse matrices were never supported, which gives authoritative context.
The combination of explanation, demonstration, and practical workaround is meant to be a complete, step-by-step answer to help users understand the limitation and a working alternative.
I hope this clarifies why this answer adds unique value, rather than simply repeating earlier comments.Let me know what is your feedback to @Li comments, could you please contribute your thoughts, we will really appreciate it.
Note: This answer has been revised in my updated response below, which incorporates technical clarifications from @Walter Roberson.
Hi @Li,
After going through recent comments, I wanted to provide a clear explanation of the situation regarding 3D sparse matrices in MATLAB, step by step.
You asked, “Why MATLAB does not support high-dimensional sparse matrices”
Feedback: MATLAB’s `sparse` function has never supported 3D or N-dimensional sparse arrays. Sparse matrices in MATLAB are always 2D (rows × columns). According to MathWorks Support (2009), “MATLAB only supports two-dimensional sparse matrices” [link]( < Mathworks > )
Also, the official `sparse` documentation also only describes 2D usage and makes no mention of N-dimensional variants ([link]( Mathworks )).
Therefore, there was never a “high-dimension operation” to remove; the function was never designed for that.
Edit comments: As @Walter Roberson demonstrated recently, this limitation is fundamental and not related to syntax conflicts:
sparse(ones(2,3,4))
Error using sparse
Inputs must be 2-D.
This definitively shows MATLAB rejects true 3D arrays regardless of the syntax used.
You asked, “Why you see the error “Inputs must be 2-D”
Feedback: When you pass a true 3D array to `sparse`, MATLAB rejects it, because the sparse format is strictly 2D. Even if you try to `reshape` a 1D or 2D sparse matrix into 3D, MATLAB internally flattens the extra dimensions, returning a 2D matrix rather than a true 3D sparse array.
You asked, “Practical solutions to mimic 3D sparse arrays”
Feedback: Since MATLAB cannot natively create 3D sparse matrices, there are two practical approaches:
1. Cell array of 2D sparse slices
You can create a 3D-like structure by storing each 2D slice as a separate sparse matrix inside a cell array. Example discussion here: [link]( Mathworks )
2. Use third-party N-D sparse implementations
The MATLAB File Exchange has a solution called `ndSparse` for true N-dimensional sparse arrays: [link]( < ndSparse > ) as already suggested by @Torsten in his comments section.
Demonstration Script
%% Step 1: Error for a true 3D array
try
A_3D = rand(3,3,3);
S_3D = sparse(A_3D);
catch ME
disp('Error for true 3D array:');
disp(ME.message);
end
%% Step 2: sparse(3,3,3) creates 2D matrix
S = sparse(3,3,3);
disp('Size of sparse(3,3,3):');
disp(size(S));
disp('Number of dimensions:');
disp(ndims(S));
%% Step 3: Mimic 3D sparse matrix with cell array nSlices = 3; slices = cell(1,nSlices);
for k = 1:nSlices
slices{k} = sparse(rand(3,3)); % 2D sparse slice
end
disp('Slice 3:');
disp(slices{3});
% Access an element
val = slices{2}(2,3);
disp(['Element (2,3) in slice 2: ', num2str(val)]);
Results: please see attached
Explanation: * True 3D array —> error: “Inputs must be 2‑D” * sparse(3,3,3) —> creates a 2D sparse matrix * Cell array —> successfully mimics a 3D sparse structure
This explanation is chronological and addresses both of your questions:
1. MATLAB never supported high-dimensional sparse matrices (so nothing was removed). 2. You can practically work around the 2D limitation using cell arrays or the “ndSparse” class.
Hope this clarifies everything and provides a concrete solution. If you need further assistance, please let us know.
2 Comments
Thank you @Walter Roberson for that crucial clarification. You're absolutely right— the sparse(ones(2,3,4)) example definitively demonstrates the 2D limitation without any syntax ambiguity. This is a much cleaner and more rigorous proof than my sparse(3,3,3) explanation.
I genuinely appreciate you taking the time to provide this correction, and I always respect and value your expertise in helping the MATLAB community understand these technical details correctly.
2 Comments
Categories
Find more on Sparse Matrices in Help Center and File Exchange
Community Treasure Hunt
Find the treasures in MATLAB Central and discover how the community can help you!
Start Hunting!
