RunMat
GitHub

View all functions

CategoryArray: Shape
GPUYes

What does the triu function do in MATLAB / RunMat?

triu(A) keeps the elements on and above a selected diagonal of A and sets everything below that diagonal to zero. The optional second argument k controls which diagonal is retained:

  • k = 0 (default) keeps the main diagonal.
  • k > 0 keeps the diagonal k steps above the main diagonal (the main diagonal and everything below it become zero).
  • k < 0 includes additional sub-diagonals beneath the main diagonal.

Every matrix "page" in an N-D tensor is processed independently.

How does the triu function behave in MATLAB / RunMat?

  • Works on numeric, logical, and complex arrays.
  • Operates on the first two dimensions; trailing dimensions act as independent pages.
  • Preserves logical types and complex-valued elements.
  • Scalars are treated as 1×1 matrices and honour diagonal offsets (for example triu(5, 1) returns 0).
  • gpuArray inputs stay on the device when an acceleration provider supplies a native triu hook; otherwise the runtime gathers, masks on the host, and uploads the result back to the GPU.

triu Function GPU Execution Behaviour

  • If the active acceleration provider implements a triu kernel the entire operation executes on the GPU.
  • Without a provider hook, RunMat gathers the tensor to host memory once, applies the mask, uploads the result, and returns a gpuArray so residency is preserved for downstream kernels.
  • Fallbacks never affect numerical results—only where the computation runs.

Examples of using the triu function in MATLAB / RunMat

Extracting the upper triangular part of a matrix

A = [1 2 3; 4 5 6; 7 8 9];
U = triu(A);

Expected output:

U =
     1     2     3
     0     5     6
     0     0     9

Keeping one sub-diagonal beneath the main diagonal

A = magic(4);
U = triu(A, -1);

Expected output:

U =
    16     2     3     13
     5    11    10     8
     0     7     6    12
     0     0    15     1

Dropping the main diagonal with a positive offset

A = [1 2 3; 4 5 6; 7 8 9];
strict = triu(A, 1);

Expected output:

strict =
     0     2     3
     0     0     6
     0     0     0

Applying triu to every page of a 3-D array

T = reshape(1:18, [3 3 2]);
U = triu(T);

Expected output:

U(:, :, 1) =
     1     2     3
     0     5     6
     0     0     9

U(:, :, 2) =
    10    11    12
     0    14    15
     0     0    18

Preserving gpuArray residency with triu

G = gpuArray(rand(5));
U = triu(G, -2);
isa(U, 'gpuArray')

Expected output:

ans =
  logical
   1

GPU residency in RunMat (Do I need gpuArray?)

No additional steps are required. RunMat keeps gpuArray inputs on the device, and the auto-offload planner promotes large CPU tensors to GPU residency when profitable. Explicit gpuArray / gather calls remain available for MATLAB compatibility or when coordinating with external libraries.

FAQ

What happens when k is smaller than the matrix size (large negative)?

The entire matrix is preserved; triu never removes elements above the chosen diagonal.

Does triu work with logical arrays?

Yes. Elements below the retained diagonal become false, while the rest keep their logical values.

How are complex numbers handled?

Each element retains its real and imaginary parts. Only elements below the chosen diagonal become 0 + 0i.

What about empty matrices or zero-sized dimensions?

triu returns an array of the same shape, leaving all entries at zero. Trailing dimensions with size zero are treated as empty batches.

Does triu change the class of character arrays?

Character arrays are converted to their numeric codes (double precision) before the triangular mask is applied, matching MATLAB behaviour.

See Also

Source & Feedback