eye — Create identity matrices with an exact requested class, sparsity, and residency.
eye creates a two-dimensional identity matrix with ones on the leading diagonal and zeros elsewhere. MATLAB-compatible mode supports scalar dimensions, two scalar dimensions, a row size vector with at most two elements, a documented typename, and the 'like' form. RunMat's older implicit-prototype, column-size-vector, and N-D forms remain available only when RunMat extensions are enabled.
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|single|logical|int8|int16|int32|int64|uint8|uint16|uint32|uint64). |
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 |
| — | 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 × nidentity matrix. Negative finite integer dimensions are treated as zero; noninteger, nonfinite, or platform-unrepresentable dimensions are rejected before allocation.eye(sz)accepts a row size vector with no more than two elements. A one-element vector requests a square matrix.eye(___, typename)supportsdouble,single,logical, and all eight signed and unsigned integer class names.eye(___, 'like', prototype)usesprototypefor class, complexity, sparsity, and applicable device residency, but never for output shape. With no dimensions, the result is 1 × 1.- Dense integer identities and real or logical sparse identities retain exact storage. Complex sparse prototypes remain a representation gap because RunMat's sparse value type does not yet carry complex values.
eye(A), column size vectors, and more than two dimensions are explicit RunMat extensions rather than MATLAB-compatible syntax.
Does RunMat run eye on the GPU?
For a resident 'like' prototype, RunMat first resolves the handle's owning provider. A compatible real floating result can use the provider eye hook; exact integer, logical, or complex construction can use one typed host upload. RunMat validates the new handle before returning it and otherwise gathers the prototype and produces a host result instead of silently returning the wrong device or class.
GPU memory and residency
You usually do not need to call gpuArray yourself in RunMat. The fusion planner keeps data on the GPU whenever downstream work benefits from staying on the device. With a resident 'like' prototype, eye routes construction through that handle's owning provider and preserves supported representation metadata.
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 0Creating an exact unsigned integer identity matrix
K = eye(2, 3, 'uint64')Expected output:
K =
2x3 uint64 matrix
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?⌄
Only as a RunMat extension. MATLAB-compatible mode accepts at most two dimensions; extension mode retains the older replicated-slice N-D behavior.
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?⌄
Yes. Use eye(..., 'single') or a single-precision 'like' prototype.
Does eye(A) match the class of A?⌄
The implicit eye(A) form is a RunMat extension. Portable code should provide dimensions and write eye(size(A), 'like', A); 'like' controls representation and does not infer shape.
How efficient is the GPU path?⌄
RunMat routes a resident prototype through its owning provider and validates the returned owner, device, shape, storage, class metadata, and precision. Exact typed upload is used when a provider identity hook cannot represent the requested logical, complex, or integer result.
Related Array functions
Creation
colon · createArray · empty · false · full · inf · linspace · logspace · magic · meshgrid · nan · nchoosek · ndgrid · nonzeros · ones · peaks · perms · rand · randi · randn · randperm · range · sparse · spdiags · speye · spones · sprand · true · zeros
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 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.