RunMat
GitHub

View all functions

CategoryMath: Linalg & Structure
GPUYes
BLAS/LAPACK

What does the bandwidth function do in MATLAB / RunMat?

bandwidth(A) inspects the nonzero pattern of a matrix and reports two numbers: the lower bandwidth (how many subdiagonals contain nonzeros) and the upper bandwidth (how many superdiagonals contain nonzeros). These metrics help determine whether a matrix is banded, which is essential for selecting the most efficient solver or factorisation.

How does the bandwidth function behave in MATLAB / RunMat?

  • bandwidth(A) returns a row vector [lower upper]. A diagonal matrix has [0 0], a strictly upper-triangular matrix has [0 k], and a strictly lower-triangular matrix has [k 0], where k counts the furthest nonzero from the main diagonal.
  • bandwidth(A, 'lower') returns only the lower bandwidth, while bandwidth(A, 'upper') returns only the upper bandwidth.
  • Nonzero detection treats any value that is not numerically equal to zero (including NaN or Inf) as nonzero, matching MATLAB semantics.
  • Empty matrices and all-zero matrices report [0 0].
  • Inputs must be numeric or logical and two-dimensional. 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.

bandwidth Function GPU Execution Behaviour

bandwidth leverages the active acceleration provider when available. The WGPU backend launches a lightweight compute kernel that scans the matrix on-device and returns the lower and upper bandwidths without transferring the entire tensor. Providers that do not implement the bandwidth hook trigger a graceful fallback that gathers the matrix and executes the CPU implementation instead. Either way, the result is returned as a small host-side double tensor.

Examples of using the bandwidth function in MATLAB / RunMat

Checking the bandwidth of a diagonal matrix

A = eye(4);
bw = bandwidth(A);

Expected output:

bw = [0 0];

Requesting only the lower bandwidth

A = [-1 0 0; 2 3 0; 4 5 6];
lower_bw = bandwidth(A, 'lower');

Expected output:

lower_bw = 2;

Requesting 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 = 1;

Analysing a rectangular matrix

C = [0 0 7; 8 0 0; 0 9 0; 0 0 10];
bw = bandwidth(C);

Expected output:

bw = [1 2];

Working with complex-valued matrices

Z = [1+2i 0; 0 3-4i; 5i 0];
bw = bandwidth(Z);

Expected output:

bw = [2 0];

Inspecting a GPU-resident matrix

G = gpuArray([0 1 0; 2 0 3; 0 0 0]);
bw = bandwidth(G);

Expected output:

bw = [1 1];

GPU residency in RunMat (Do I need gpuArray?)

You usually do NOT need to move data manually. When the active provider exposes the bandwidth hook (the WGPU backend does), RunMat launches a device-side kernel and only reads back the two bandwidth values. Providers without support seamlessly gather the tensor and reuse the CPU implementation, so explicit gpuArray / gather calls remain optional.

FAQ

What does a bandwidth of [0 0] mean?

It indicates the matrix is diagonal: 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?

Yes, when the provider implements the hook: the matrix stays resident on the GPU and only the two bandwidth values are copied back. If the provider lacks support, RunMat gathers the tensor and computes the bandwidth on the CPU instead.

Can I call bandwidth inside fused expressions?

Yes. The builtin returns a small host tensor, so it behaves like any other metadata query.

What happens if I pass logical matrices?

Logical values are promoted to doubles (0 or 1) internally. true entries count as nonzero and contribute to the bandwidth calculation.

See Also

diag, tril, triu, spdiags, issymmetric, find, gpuArray, gather

Source & Feedback