RunMat
GitHub

View all functions

CategoryArray: Creation
GPUYes

What does the fill function do in MATLAB / RunMat?

fill(value, size, ...) constructs dense MATLAB arrays whose entries are all the supplied value. It aligns with the MATLAB-compatible RunMat array creation suite (zeros, ones, eye, etc.) while supporting GPU residency, 'like' prototypes, and logical/complex outputs.

How does the fill function behave in MATLAB / RunMat?

  • fill(v) returns the scalar v.
  • fill(v, n) returns an n × n matrix with every element equal to v.
  • fill(v, m, n, ...) supports arbitrary N-D dimensions.
  • fill(v, sz) accepts a size vector (row or column).
  • fill(v, A) uses the shape (and default type) of A.
  • fill(v, ___, 'logical') produces a logical array where each element is v ~= 0.
  • fill(v, ___, 'like', prototype) matches the type, device residency, and shape of prototype.
  • When a GPU prototype or 'like' argument is provided, RunMat keeps the result on the device. When provider hooks are incomplete, it falls back to uploading a host tensor to guarantee correctness.

GPU execution behaviour

RunMat asks the active acceleration provider to materialise the constant directly via the dedicated fill hook. Providers that do not supply this capability fall back to a zero buffer plus scalar add or, as a last resort, upload the fully materialised host tensor. This guarantees MATLAB-compatible results while still benefiting from GPU residency whenever possible.

Examples of using the fill function in MATLAB / RunMat

Creating a 3x3 matrix of 2.5s

A = fill(2.5, 3);

Expected output:

A = [2.5 2.5 2.5; 2.5 2.5 2.5; 2.5 2.5 2.5];

Filling a rectangular matrix with -4

B = fill(-4, 2, 5);

Expected output:

B = [-4 -4 -4 -4 -4; -4 -4 -4 -4 -4];

Filling using a size vector

sz = [2 3 4];
C = fill(10, sz);

Expected output:

size(C)  % 2-by-3-by-4

Creating a logical mask with fill

mask = fill(3, 4, 1, 'logical');

Expected output:

mask = [1; 1; 1; 1];

Matching an existing array with 'like'

prototype = rand(2, 3, 'like', gpuArray(1));
D = fill(pi, 2, 3, 'like', prototype);

Expected output:

D is gpuArray
gather(D) = ones(2, 3) * pi;

Filling a complex array

E = fill(1 + 2i, 2, 2, 'complex');

Expected output:

E = [1+2i 1+2i; 1+2i 1+2i];

Using a prototype to infer shape automatically

F = rand(4, 2);
G = fill(7, F);

Expected output:

isequal(size(G), [4 2])  % true

Filling an empty matrix

H = fill(0, 0, 5);

Expected output:

size(H)  % 0-by-5

Keeping GPU residency without explicit gpuArray

A = rand(512, 512);
J = fill(0.5, size(A), 'like', gpuArray(A));

Expected output:

isa(J, 'gpuArray')  % true

Filling with boolean semantics

K = fill(false, [2 2], 'logical');

Expected output:

K = [0 0; 0 0];

FAQ

Which argument order does fill support?

The first argument is always the scalar value. Remaining arguments specify dimensions, size vectors, or options ('logical', 'like', 'double', 'complex').

Does fill accept non-scalar values?

No. The fill value must be numeric, logical, or complex scalar. Use repmat when you need to tile an array.

How does fill behave with complex values?

If you request complex output (explicitly or via 'like'), the real and imaginary parts are copied verbatim. Otherwise the imaginary component must be zero.

How do logical arrays handle nonzero values?

Logical outputs treat any nonzero real or complex magnitude as true, matching MATLAB semantics.

Can I match GPU residency automatically?

Yes. Pass a GPU prototype via 'like' and fill will allocate on the device. It falls back to host allocation and upload when the provider cannot construct the constant directly.

What happens when I omit dimensions?

If you only pass the value, fill returns a scalar. When you pass a prototype (e.g., fill(v, A)), the prototype shape is reused. Otherwise RunMat follows MATLAB's default of 1 × 1.

Are string or char outputs supported?

Not yet. fill currently targets numeric, logical, and complex arrays. Use string-manipulation functions for text.

How do I create empty outputs?

Include a zero dimension (fill(value, 0, n) or fill(value, [0 n])). RunMat returns an empty array of the requested size and type.

Does fill honour 'single' outputs?

Single precision outputs are not implemented yet. The function returns an error mirroring other array creation builtins.

Is the GPU path deterministic?

Yes. Providers either execute the constant fill entirely on the GPU or RunMat uploads a deterministic host tensor, ensuring identical results.

See Also

zeros, ones, repmat, gpuArray, gather

Source & Feedback