tril — Extract lower-triangular portions of matrices with optional diagonal offsets.
tril(A) keeps elements on and below a selected diagonal and sets elements above that diagonal to zero. Optional k selects the diagonal boundary using MATLAB-compatible semantics.
Syntax
B = tril(A)
B = tril(A, k)Inputs
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
A | Any | Yes | — | Input scalar, matrix, or paged matrix array. |
k | NumericScalar | Yes | — | Diagonal offset for the preserved lower triangle. |
Returns
| Name | Type | Description |
|---|---|---|
B | Any | Lower triangular output array with preserved shape/type domain. |
Errors
| Identifier | When | Message |
|---|---|---|
RunMat:tril:TooManyInputs | More than one optional argument is supplied after A. | tril: too many input arguments |
RunMat:tril:InvalidOffset | Diagonal offset is not a finite integer scalar value. | tril: invalid diagonal offset |
RunMat:tril:UnsupportedInput | Input value is not supported by tril. | tril: unsupported input type |
RunMat:tril:Internal | Internal masking/upload path fails. | tril: internal operation failed |
How tril works
- 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.
- All eight integer classes preserve their exact values and class; masked entries become a zero of that same class.
- Native typed-integer diagonal offsets are decoded exactly as structural selectors and must fit the runtime index range.
- Scalars are treated as
1×1matrices and honour negative offsets (k < 0yields zero). - gpuArray inputs stay on the device when the provider exposes a native
trilhook; otherwise RunMat performs a gather → compute → upload cycle.
Does RunMat run tril 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
1Examples
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 9Keeping 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 1Dropping 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 0Applying 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 18Preserving gpuArray residency with tril
G = gpuArray(rand(5));
L = tril(G, -2);
isa(L, 'gpuArray')Expected output:
ans =
logical
1Using tril with coding agents
Open a RunMat example with live inputs, then ask the agent to explain how tril changes the result.
Run a small tril example, explain the result, then change one input and compare the output.
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 remain character arrays. Entries above the selected diagonal become null characters while retained entries keep their original values.
Related Array functions
Shape
blkdiag · cat · circshift · diag · flip · fliplr · flipud · horzcat · ipermute · kron · permute · repelem · repmat · reshape · rot90 · squeeze · toeplitz · triu · vertcat
Grouping
accumarray · combinations · discretize · findgroups · groupcounts · grp2idx · splitapply
Sorting Sets
argsort · intersect · ismember · ismembertol · issorted · issortedrows · setdiff · setxor · sort · sortrows · union · unique
Open-source implementation
Unlike proprietary runtimes, every RunMat function is open-source. Read exactly how tril is executed, line by line, in Rust.
- View the source for tril in Rust on GitHub
- Learn how the RunMat 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 blazing on any GPU. It is licensed under the Apache 2.0 license.
- RunMat automatically optimizes your math for GPU execution on Apple, Nvidia, and AMD hardware. No code changes needed. Simulations that took hours now take minutes.
- Start running code in seconds. RunMat runs in the browser, on the desktop, or from the CLI. No license server, no IT ticket.