RunMat
GitHub

View all functions

CategoryArray: Creation
GPUYes

What does the eye function do in MATLAB / RunMat?

eye creates identity matrices (and higher-dimensional identity tensors) containing ones along the leading diagonal and zeros everywhere else. RunMat mirrors MATLAB semantics across scalar, vector, matrix, and N-D inputs, including 'logical' and 'like' options.

How does the eye function behave in MATLAB / RunMat?

  • eye() returns the scalar 1.
  • eye(n) returns an n × n double-precision identity matrix.
  • eye(m, n, ...) returns an m × 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 with size(I) == sz.
  • eye(A) matches the size of A. 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 of prototype, including GPU handles.

eye Function GPU Execution Behaviour

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.

Examples of using the eye function in MATLAB / RunMat

Creating a 3-by-3 identity matrix

I = eye(3);

Expected output:

I =
     1     0     0
     0     1     0
     0     0     1

Generating a rectangular identity matrix

J = eye(2, 4);

Expected output:

J =
     1     0     0     0
     0     1     0     0

Replicating an identity matrix across pages

K = eye(2, 3, 2);   % Two 2x3 identity slices stacked along the third dimension

Expected output (page 1 shown):

K(:, :, 1) =
     1     0     0
     0     1     0

K(:, :, 2) =
     1     0     0
     0     1     0

Creating 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     1

Matching type and residency with 'like'

G = gpuArray(rand(128));     % Prototype on the GPU
I = eye(size(G, 1), 'like', G);

The result I stays on the GPU; gather(I(1:3, 1:3)) returns a 3x3 identity block on the host.

GPU residency in RunMat (Do I need gpuArray?)

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.

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.

See Also

zeros, ones, diag, gpuArray, gather

Source & Feedback