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
n- Type
SizeArg- Required
- Yes
- Description
- Square size.
size_vector- Type
SizeArg- Required
- Yes
- Description
- Size vector defining output dimensions.
dims- Type
SizeArg- Required
- Variadic
- Description
- Dimension sizes.
prototype- Type
LikePrototype- Required
- Yes
- Description
- Prototype value when no numeric dimension arguments are provided.
typename- Type
StringScalar- Required
- No
- Default
"double"- Description
- Class name override (double|single|logical|int8|int16|int32|int64|uint8|uint16|uint32|uint64).
like_kw- Type
StringScalar- Required
- Yes
- Default
"like"- Description
- Like keyword.
prototype- Type
LikePrototype- Required
- Yes
- Description
- Prototype array used for class/device.
Returns
A- Type
NumericArray- Description
- Identity matrix/tensor.
Errors
- When
- The 'like' keyword is provided without a prototype argument.
- Message
eye: expected prototype after 'like'
- When
- A class keyword and a 'like' prototype are both provided.
- Message
eye: cannot combine 'like' with other class specifiers
- When
- A trailing option string is not a supported class keyword.
- Message
eye: unrecognised option
- When
- Dimension arguments fail numeric/shape parsing.
- Message
eye: dimension arguments must be numeric and nonnegative
Behavior
eye() returns the scalar 1.
eye(n) returns an n × n double-precision identity matrix.
eye(m, n) returns an m × n identity 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) supports double, single, logical, and all eight signed and unsigned integer class names.
eye(___, 'like', prototype) uses prototype for 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.
Execution and residency
Ordinary eye construction does not guarantee GPU residency. RunMat may select an accelerator for a larger admitted computation; a resident 'like' prototype requests construction through that handle's exact owning provider and preserves supported representation metadata.
For a resident 'like' prototype, RunMat uses that handle's owning provider. Real floating identities use the provider hook when it preserves the prototype representation; unsupported pre-effect hook forms and logical, complex, or integer identities use exact typed host upload when necessary. A failed operational hook or upload returns an error rather than gathering the prototype and silently changing residency.
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. Without a class selector or 'like' prototype, the result is dense double-precision. Explicit single, logical, and supported integer selectors choose their own storage classes.
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 · int16.empty · int32.empty · int64.empty · int8.empty · linspace · logspace · magic · meshgrid · nan · ndgrid · nonzeros · ones · peaks · rand · randi · randn · randperm · range · sparse · spdiags · speye · spones · sprand · true · uint16.empty · uint32.empty · uint64.empty · uint8.empty · zeros
Accumulation
Sorting Sets
argsort · intersect · ismember · ismembertol · issorted · issortedrows · setdiff · setxor · sort · sortrows · union · unique
Shape
blkdiag · cat · circshift · diag · flip · fliplr · flipud · horzcat · ipermute · kron · permute · repelem · repmat · reshape · rot90 · shiftdim · squeeze · toeplitz · tril · triu · vertcat
Combinatorics
Binning
Grouping
Source you can read
Every RunMat function's source is public. 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 a runtime that executes MATLAB-syntax code fast on any GPU. The runtime is free for individuals, including freelancers; students and faculty at an academic institution, for teaching or research there; contributors to an open-source project, for work on that project; organizations with 250 or fewer people and US$10M or less in annual revenue; and anyone, for non-production use. See runmat.com/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.