RunMat
GitHub

View all functions

CategoryMath: Rounding
GPUYes

What does the ceil function do in MATLAB / RunMat?

ceil(X) rounds each element of X toward positive infinity, returning the smallest integer greater than or equal to the input. Optional arguments match MATLAB's extended syntax for rounding to fixed decimal places, significant digits, and prototype-based residency.

How does the ceil function behave in MATLAB / RunMat?

  • Works on scalars, vectors, matrices, and higher-dimensional tensors with MATLAB broadcasting semantics.
  • ceil(X, N) rounds toward positive infinity with N decimal digits (positive N) or powers of ten (negative N).
  • ceil(X, N, 'significant') rounds to N significant digits; N must be a positive integer.
  • Logical inputs are promoted to doubles (false → 0, true → 1) before applying the ceiling operation.
  • Character arrays are interpreted numerically (their Unicode code points) and return dense double tensors.
  • Complex inputs are rounded component-wise: ceil(a + bi) = ceil(a) + i·ceil(b).
  • Non-finite values (NaN, Inf, -Inf) propagate unchanged.
  • Empty arrays return empty arrays of the appropriate shape.
  • Appending 'like', prototype forces the result to match the residency of prototype (CPU or GPU). Prototypes must currently be numeric.

ceil Function GPU Execution Behaviour

When tensors already reside on the GPU, RunMat consults the active acceleration provider. If the provider implements the unary_ceil hook, ceil(X) executes entirely on the device and keeps tensors resident. When decimal or significant-digit rounding is requested—or when the provider lacks unary_ceil—RunMat gathers the tensor to host memory, applies the CPU implementation, and honours any 'like' GPU prototype by uploading the result back to the device. This maintains MATLAB-compatible behaviour while exposing GPU acceleration whenever it is available.

Examples of using the ceil function in MATLAB / RunMat

Rounding values up to the next integer

x = [-2.7, -0.3, 0, 0.8, 3.2];
y = ceil(x);

Expected output:

y = [-2, 0, 0, 1, 4];

Rounding a matrix up element-wise

A = [1.2 4.7; -3.4 5.0];
B = ceil(A);

Expected output:

B = [2 5; -3 5];

Rounding fractions upward in a tensor

t = reshape([-1.8, -0.2, 0.4, 1.1, 2.1, 3.6], [3, 2]);
up = ceil(t);

Expected output:

up =
    [-1  2;
      0  3;
      1  4]

Rounding up to two decimal places

temps = [21.452 19.991 22.501];
rounded = ceil(temps, 2);

Expected output:

rounded = [21.46 19.99 22.51];

Rounding to significant digits

measurements = [0.001234 12.3456 98765];
sig2 = ceil(measurements, 2, 'significant');

Expected output:

sig2 = [0.0013 13.0 99000];

Rounding complex numbers toward positive infinity

z = [1.2 + 2.1i, -0.2 - 3.9i];
result = ceil(z);

Expected output:

result = [2 + 3i, 0 - 3i];

Keeping GPU results on-device with unary_ceil

G = gpuArray([1.8 -0.2 0.0; -1.1 2.5 -3.4]);
up = ceil(G);
gather(up);

Expected output:

ans =
    [ 2  0  0;
     -1  3 -3]

Forcing GPU residency with a 'like' prototype

A = [1.8 -0.2; 2.7 3.4];
proto = gpuArray(0);
G = ceil(A, 'like', proto);   % Result remains on the GPU
result = gather(G);

Expected output:

result =
    [ 2  0;
      3  4]

GPU residency in RunMat (Do I need gpuArray?)

You usually do not need to call gpuArray manually. RunMat's planner keeps tensors on the GPU when a provider implements unary_ceil and the workload benefits from device execution. When the hook is missing, RunMat automatically gathers the data, applies the CPU semantics, and allows subsequent operations to re-upload if profitable. Explicit gpuArray calls remain available for compatibility with MathWorks MATLAB.

FAQ

  1. Does ceil always round toward positive infinity? Yes—positive values round up away from zero, while negative values round toward zero (e.g., ceil(-0.1) = 0).
  2. How are complex numbers handled? The real and imaginary parts are ceiled independently, matching MATLAB's component-wise definition.
  3. Can I round to decimal digits or significant digits? Yes. Use ceil(X, N) for decimal digits or ceil(X, N, 'significant') for significant digits. Negative N values round to powers of ten.
  4. What happens with logical arrays? Logical values promote to doubles (0 or 1) before rounding, so the outputs remain 0 or 1.
  5. Can I pass character arrays to ceil? Yes. Character data is treated as its numeric code points, producing a double tensor of the same size.
  6. Do NaN and Inf values change? No. Non-finite inputs propagate unchanged.
  7. Will GPU execution change floating-point results? No. Providers implement IEEE-compliant ceiling; when a provider lacks unary_ceil, RunMat falls back to the CPU to preserve MATLAB-compatible behaviour.
  8. Does 'like' work with ceil? Yes. Append 'like', prototype to request output that matches the prototype's residency. Currently prototypes must be numeric (scalars or dense tensors, host or GPU).
  9. Can fusion keep ceil on the GPU? Yes. ceil participates in elementwise fusion, so fused graphs can stay resident on the device when supported.

See Also

floor, round, gpuArray, gather

Source & Feedback