RunMat
GitHub

View all functions

CategoryArray: Shape
GPUYes

What does the tril function do in MATLAB / RunMat?

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.

tril Function GPU Execution Behaviour

  • 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.

Examples of using the tril function 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

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 will promote large CPU tensors to GPU residency when it detects a benefit. Explicit gpuArray / gather calls remain available for MATLAB compatibility or to force a particular residency in workflows that interact with other libraries.

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

Source & Feedback