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 tril works in 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.

How tril runs on the GPU

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 memory and residency

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

Expected output:

ans =
  logical
   1

Examples

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.

Related functions to explore

These functions work well alongside tril. Each page has runnable examples you can try in the browser.

triu, diag, kron, reshape, gpuArray, gather, cat, circshift, flip, fliplr, flipud, horzcat, ipermute, permute, repmat, rot90, squeeze, vertcat

Open-source implementation

Unlike proprietary runtimes, every RunMat function is open-source. Read exactly how tril works, line by line, in Rust.

• View tril.rs on GitHub
• Learn how the 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 — faster, on any GPU, with no license required.

• Simulations that took hours now take minutes. RunMat automatically optimizes your math for GPU execution on Apple, Nvidia, and AMD hardware. No code changes needed.
• Start running code in seconds. Open the browser sandbox or download a single binary. No license server, no IT ticket, no setup.
• A full development environment. GPU-accelerated 2D and 3D plotting, automatic versioning on every save, and a browser IDE you can share with a link.

Getting started · Benchmarks · Pricing