RunMat
GitHub

View all functions

CategoryArray: Shape
GPUYes

tril — Extract the lower triangular portion of a matrix (optionally including super-diagonals).

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

  • k = 0 (default) keeps the main diagonal.
  • k > 0 includes super-diagonals above the main diagonal.
  • k < 0 drops the main diagonal and starts below it.

The operation applies independently to every matrix "page" of N-D tensors.

How does the tril function behave in MATLAB / RunMat?

  • Works on numeric, logical, and complex arrays.
  • Operates on the first two dimensions; trailing dimensions are handled as independent pages.
  • Accepts scalar, vector, matrix, or paged inputs of any size, including empty dimensions.
  • Logical inputs remain logical, and complex values keep their real/imaginary components.
  • Scalars are treated as 1×1 matrices and honour negative offsets (k < 0 yields zero).
  • gpuArray inputs stay on the device when the provider exposes a native tril hook; otherwise RunMat performs a gather → compute → upload cycle.

GPU behavior

If the active acceleration provider implements the custom tril hook the entire operation runs on the GPU.

When the hook is missing, RunMat gathers the data once, computes the result on the host, uploads the lower triangular tensor back to the device, and returns a gpuArray handle so residency is preserved for downstream kernels.

Falling back to the host never changes numerical results; it only affects where the computation is carried out.

GPU residency

G = gpuArray(rand(5));
L = tril(G, -2);
isa(L, 'gpuArray')

Expected output:

ans =
  logical
   1

Examples of using tril in MATLAB / RunMat

Extracting the lower triangular part of a matrix

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

Expected output:

L =
     1     0     0
     4     5     0
     7     8     9

Keeping one super-diagonal above the main diagonal

A = magic(4);
L = tril(A, 1)

Expected output:

L =
    16     2     0     0
     5    11    10     0
     9     7     6    12
     4    14    15     1

Dropping the main diagonal with a negative offset

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

Expected output:

strict =
     0     0     0
     4     0     0
     7     8     0

Applying tril to every page of a 3-D array

T = reshape(1:18, [3 3 2]);
L = tril(T)

Expected output:

L(:, :, 1) =
     1     0     0
     4     5     0
     7     8     9

L(:, :, 2) =
    10     0     0
    13    14     0
    16    17    18

Preserving gpuArray residency with tril

G = gpuArray(rand(5));
L = tril(G, -2);
isa(L, 'gpuArray')

Expected output:

ans =
  logical
   1

FAQ

What happens when k is larger than the matrix size?

The entire matrix is preserved; tril never removes elements below the chosen diagonal.

Does tril work with logical arrays?

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

How are complex numbers handled?

Each element keeps its real and imaginary parts intact. Only the elements above the chosen diagonal are zeroed out (0 + 0i).

What about empty matrices or zero-sized dimensions?

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

Does tril change the class of character arrays?

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

See also

triu, diag, kron, reshape, gpuArray, gather

Source & Feedback