bandwidth — Compute matrix lower and upper bandwidth in MATLAB and RunMat.
bandwidth(A) inspects the nonzero pattern of matrix A and returns the lower bandwidth as its first output and the upper bandwidth as its optional second output. A 'lower' or 'upper' selector returns one side.
Syntax
[lower, upper] = bandwidth(A)
b = bandwidth(A, selector)Inputs
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
A | Any | Yes | — | Input matrix. |
selector | Any | No | — | Selector string: "lower" or "upper". |
Returns
| Name | Type | Description |
|---|---|---|
lower | NumericScalar | Lower bandwidth scalar. |
upper | NumericScalar | Upper bandwidth scalar. |
b | NumericScalar | Selected lower or upper bandwidth scalar. |
Returned values from bandwidth depend on how many outputs the caller requests.
Errors
| Identifier | When | Message |
|---|---|---|
RunMat:bandwidth:InvalidArgument | Selector argument is invalid or argument count exceeds supported forms. | bandwidth: invalid argument |
RunMat:bandwidth:InvalidInput | Input type/shape cannot be processed as a numeric or logical 2-D matrix. | bandwidth: invalid input |
RunMat:bandwidth:Internal | Runtime fails while constructing intermediate tensors or values. | bandwidth: internal runtime failure |
How bandwidth works
lower = bandwidth(A)returns the lower bandwidth.[lower, upper] = bandwidth(A)returns separate lower and upper double scalars. A diagonal matrix has zero for both, and each side counts the furthest nonzero from the main diagonal.bandwidth(A, 'lower')returns only the lower bandwidth, whilebandwidth(A, 'upper')returns only the upper bandwidth.- The documented matrix domain is full or sparse single/double, including complex values. RunMat mode additionally accepts logical matrices and all eight real or paired complex-integer classes; MATLAB-compatible mode rejects those extensions before host or provider dispatch.
- Integer matrices are scanned through authoritative storage, so exact zero/nonzero structure never crosses a floating conversion. Outputs remain double scalar metadata.
- Nonzero detection treats any value that is not numerically equal to zero (including
NaNorInf) as nonzero, matching MATLAB semantics. - Empty matrices and all-zero matrices report zero for both the lower and upper outputs.
- Inputs must be two-dimensional matrices. Higher-dimensional arrays (with any dimension beyond the second larger than one) raise an error.
- Complex matrices are supported. A complex entry counts as nonzero if either the real or imaginary part is nonzero.
Does RunMat run bandwidth on the GPU?
bandwidth leverages the active acceleration provider for documented floating input when available. The WGPU backend scans the matrix on-device and reads back lower/upper metadata. Providers without the hook gather and reuse the CPU implementation. Admitted integer/logical extensions gather before provider dispatch so packed typed buffers are never interpreted by floating shaders.
GPU memory and residency
Documented single/double GPU inputs use the provider bandwidth hook when available and otherwise gather. Integer and logical GPU inputs are gated RunMat extensions; admitted values gather exactly before the floating-only provider hook and return host double scalar metadata.
Examples
Checking the bandwidth of a diagonal matrix
A = eye(4);
bw = bandwidth(A)Expected output:
bw = 0Requesting only the lower bandwidth
A = [-1 0 0; 2 3 0; 4 5 6];
lower_bw = bandwidth(A, 'lower')Expected output:
lower_bw = 2Requesting only the upper bandwidth
B = [1 2 0 0; 0 3 4 0; 0 0 5 6];
upper_bw = bandwidth(B, 'upper')Expected output:
upper_bw = 1Analysing a rectangular matrix
C = [0 0 7; 8 0 0; 0 9 0; 0 0 10];
[lower, upper] = bandwidth(C)Expected output:
lower = 1, upper = 2Working with complex-valued matrices
Z = [1+2i 0; 0 3-4i; 5i 0];
[lower, upper] = bandwidth(Z)Expected output:
lower = 2, upper = 0Inspecting a GPU-resident matrix
G = gpuArray([0 1 0; 2 0 3; 0 0 0]);
[lower, upper] = bandwidth(G)Expected output:
lower = 1, upper = 1Using bandwidth with coding agents
Open a RunMat example with live inputs, then ask the agent to explain how bandwidth changes the result.
Run a small bandwidth example, explain the result, then change one input and compare the output.
FAQ
What do lower and upper bandwidths of zero mean?⌄
Separate lower and upper outputs of zero indicate that all nonzero elements are on the main diagonal.
How are rows or columns full of zeros handled?⌄
Zero rows or columns do not increase the bandwidth; only nonzero entries affect the result.
Does bandwidth treat NaN values as nonzero?⌄
Yes. Any value that is not exactly zero—including NaN or Inf—counts as nonzero.
Can I request only the lower or upper bandwidth?⌄
Yes. Pass 'lower' or 'upper' as the second argument to obtain a scalar result.
Why does bandwidth error on higher-dimensional arrays?⌄
The builtin matches MATLAB and only operates on two-dimensional matrices. Use reshape to collapse trailing singleton dimensions before calling bandwidth.
Does bandwidth work with sparse matrices?⌄
RunMat currently stores inputs as dense tensors but mirrors MATLAB's numerical semantics. Future releases will preserve sparsity metadata while returning the same bandwidth values.
What precision does the result use?⌄
The result is always returned as double precision (double), matching MATLAB.
Will this function keep my data on the GPU?⌄
Documented floating input stays resident when the provider implements the hook, with only lower/upper metadata read back. Providers without the hook gather. Integer and logical extension inputs gather exactly before provider dispatch.
Can I call bandwidth inside fused expressions?⌄
Yes. The builtin returns host double scalar metadata, so it behaves like other metadata queries.
What happens if I pass logical matrices?⌄
Logical input is a gated RunMat extension because the documented matrix domain is single/double. In RunMat mode, true entries count as nonzero.
Related Linalg functions
Structure
isdiag · ishermitian · issymmetric · istril · istriu · symrcm
Ops
cross · ctranspose · dot · mldivide · mpower · mrdivide · mtimes · pagemtimes · pagetranspose · trace · transpose
Open-source implementation
Unlike proprietary runtimes, every RunMat function is open-source. Read exactly how bandwidth is executed, line by line, in Rust.
- View the source for bandwidth in Rust on GitHub
- Learn how the RunMat runtime works
- Found a bug? Open an issue with a minimal reproduction.
About RunMat
RunMat is an open-source runtime that executes MATLAB-syntax code blazing on any GPU. It is licensed under the Apache 2.0 license.
- RunMat automatically optimizes your math for GPU execution on Apple, Nvidia, and AMD hardware. No code changes needed. Simulations that took hours now take minutes.
- Start running code in seconds. RunMat runs in the browser, on the desktop, or from the CLI. No license server, no IT ticket.