eye — Create identity matrices and N-D identity tensors in MATLAB and RunMat.
eye creates identity matrices (and higher-dimensional identity tensors) with ones on the leading diagonal and zeros elsewhere. Scalar, vector, matrix, and N-D sizing forms, including 'logical' and 'like' options, follow MATLAB semantics.
Syntax
A = eye()
A = eye(n)
A = eye(size_vector)
A = eye(m, n, ...)
A = eye(prototype)
A = eye(..., typename)
A = eye(..., "like", prototype)Inputs
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
n | SizeArg | Yes | — | Square size. |
size_vector | SizeArg | Yes | — | Size vector defining output dimensions. |
dims | SizeArg | Variadic | — | Dimension sizes. |
prototype | LikePrototype | Yes | — | Prototype value when no numeric dimension arguments are provided. |
typename | StringScalar | No | "double" | Class name override (double|logical). |
like_kw | StringScalar | Yes | "like" | Like keyword. |
prototype | LikePrototype | Yes | — | Prototype array used for class/device. |
Returns
| Name | Type | Description |
|---|---|---|
A | NumericArray | Identity matrix/tensor. |
Errors
| Identifier | When | Message |
|---|---|---|
| — | The 'like' keyword is provided without a prototype argument. | eye: expected prototype after 'like' |
| — | A class keyword and a 'like' prototype are both provided. | eye: cannot combine 'like' with other class specifiers |
| — | The 'single' class option is requested. | eye: single precision output is not implemented yet |
| — | A trailing option string is not a supported class keyword. | eye: unrecognised option |
| — | Dimension arguments fail numeric/shape parsing. | eye: dimension arguments must be numeric and nonnegative |
How eye works
eye()returns the scalar1.eye(n)returns ann × ndouble-precision identity matrix.eye(m, n, ...)returns anm × n × ...tensor whose first two dimensions form an identity slice that is replicated across all trailing dimensions.eye(sz)accepts a size vector (row or column) and returns an array withsize(I) == sz.eye(A)matches the size ofA. Logical, complex, and GPU prototypes preserve their logical/complex/device traits; other inputs default to double precision for MATLAB parity.eye(___, 'logical')returns a logical identity tensor instead of double precision.eye(___, 'like', prototype)matches the numeric flavour and device residency ofprototype, including GPU handles.
Does RunMat run eye on the GPU?
When the result should live on a GPU (either because the prototype is a GPU tensor or the 'like' argument references one), RunMat first asks the active acceleration provider for an identity buffer via the eye / eye_like hooks. The WGPU backend implements these hooks directly; simpler providers may return Err, in which case the runtime materialises the identity tensor on the host, performs a single upload, and returns a GpuTensorHandle. Because the allocation happens in one step, the auto-offload planner can keep subsequent fused expressions resident on the device without extra gathers.
GPU memory and residency
You usually do not need to call gpuArray yourself in RunMat. The fusion planner keeps data on the GPU whenever it determines that downstream work will benefit from staying on the device. The eye builtin respects that residency: if the planner or user requests GPU output (via 'like'), it will either construct the identity tensor directly on the device (when the provider implements eye) or generate it on the host and upload it as a single transfer.
Examples
Creating a 3-by-3 identity matrix
I = eye(3)Expected output:
I =
1 0 0
0 1 0
0 0 1Generating a rectangular identity matrix
J = eye(2, 4)Expected output:
J =
1 0 0 0
0 1 0 0Replicating an identity matrix across pages
K = eye(2, 3, 2) % Two 2x3 identity slices stacked along the third dimensionExpected output:
K(:, :, 1) =
1 0 0
0 1 0
K(:, :, 2) =
1 0 0
0 1 0Creating a logical identity mask
mask = eye(4, 'logical')Expected output:
mask =
1 0 0 0
0 1 0 0
0 0 1 0
0 0 0 1Matching type and residency with 'like'
G = gpuArray(rand(128)); % Prototype on the GPU
I = eye(size(G, 1), 'like', G)Using eye with coding agents
Open a RunMat example with live inputs, then ask the agent to explain how eye changes the result.
Run a small eye example, explain the result, then change one input and compare the output.
FAQ
When should I use the eye function?⌄
Use eye whenever you need an identity matrix—for example, when solving linear systems, creating initial values for iterative methods, or building block-diagonal structures.
Does eye produce double arrays by default?⌄
Yes. Unless you request 'logical' or use 'like', the result is a dense double-precision array.
How do I create an identity matrix that matches another array's type or residency?⌄
Use the 'like' syntax: I = eye(size(A, 1), 'like', A);. The result adopts the same type and device residency as A.
Can eye generate higher-dimensional identity tensors?⌄
Yes. Extra dimensions replicate the identity slice. For example, eye(2, 3, 4) creates four 2 × 3 identity matrices stacked along the third dimension.
What happens if I request zero-sized dimensions?⌄
If any leading dimension is zero, the result contains zero elements (consistent with MATLAB).
Is single precision supported?⌄
Not yet. Requesting 'single' currently reports an error. Use 'like' with a single-precision prototype once single-precision support lands.
Does eye(A) match the class of A?⌄
For logical, complex, and GPU prototypes, yes—eye(A) behaves like eye(size(A), 'like', A). Other numeric inputs produce double precision to mirror MATLAB's default.
How efficient is the GPU path?⌄
Providers with dedicated identity allocation avoid host involvement entirely. Providers without the hook fall back to a single host upload, which is still efficient for typical sizes.
Related Array functions
Creation
colon · false · fill · inf · linspace · logspace · magic · meshgrid · nan · ones · peaks · rand · randi · randn · randperm · range · true · zeros
Open-source implementation
Unlike proprietary runtimes, every RunMat function is open-source. Read exactly how eye is executed, line by line, in Rust.
- View the source for eye 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.