RunMat
GitHub

View all functions

CategoryMath: Elementwise
GPUYes

What does the single function do in MATLAB / RunMat?

single(X) converts scalars, arrays, complex values, characters, logical inputs, and gpuArray handles into single-precision (float32) values while preserving MATLAB's column-major shapes.

How does the single function behave in MATLAB / RunMat?

  • Numeric scalars and arrays (double or integer) are rounded to IEEE single precision. Scalars remain scalars; arrays keep their exact shape and column-major layout.
  • Logical inputs become floating-point 0/1, matching MATLAB’s implicit promotion rules for logical arithmetic.
  • Complex values convert both the real and imaginary components to single precision using MATLAB’s analytic extension rules.
  • Character arrays return their Unicode code points (equivalent to double(char)), quantised to single precision. Strings, structs, cells, objects, and other unsupported classes raise MATLAB-style errors ("single: conversion to single from <type> is not possible").
  • Empty arrays stay empty, singleton expansion is unaffected, and metadata such as orientation is preserved exactly.

single Function GPU Execution Behaviour

  • When the input is a gpuArray and the provider implements unary_single, RunMat keeps the data on device and returns a new gpuArray handle that already contains single-precision values. This path is also used by fused elementwise kernels emitted by Turbine.
  • If the provider lacks the hook, RunMat gathers the data to host memory, converts it to single precision, and re-uploads it so downstream GPU code still receives a device-resident value. The original handle is freed once the replacement upload succeeds.
  • When no provider is active the fallback stops after the host conversion, returning a CPU tensor that still respects single-precision rounding. Scalars follow the same logic (single(gpuArray(pi)) returns a device scalar when possible, or a host scalar if the provider is absent).

Examples of using the single function in MATLAB / RunMat

Convert a matrix to single precision

A = [1 2 3; 4 5 6];
B = single(A);

Expected output:

B =
  2×3 single matrix
     1     2     3
     4     5     6

Convert a scalar double to single precision

pi_single = single(pi);

Expected output:

pi_single =
  single
     3.1416

Convert complex numbers to single precision

z = [1+2i, 3-4i];
single_z = single(z);

Expected output:

single_z =
  1×2 single complex row vector
   1.0000 + 2.0000i   3.0000 - 4.0000i

Convert a character array to single precision codes

codes = single('ABC');

Expected output:

codes =
  1×3 single row vector
    65    66    67

Keep gpuArray inputs on the GPU

G = gpuArray(reshape(0:5, 3, 2));
H = single(G);
gather(H)

Expected output:

ans =
  3×2 single matrix
     0     3
     1     4
     2     5

Convert logical masks to single precision values

mask = logical([0 1 0 1]);
weights = single(mask);

Expected output:

weights =
  1×4 single row vector
     0     1     0     1

GPU residency in RunMat (Do I need gpuArray?)

You rarely need to call gpuArray solely for type conversion. RunMat’s planner already keeps hot paths on the GPU. When single runs on gpuArray inputs it attempts a device-side cast first, and falls back to gather/convert/re-upload when hooks are missing. The fallback is documented so users understand the temporary host hop.

FAQ

Why does single change the numeric value slightly?

Single precision has ~7 decimal digits of accuracy. Values that require more precision are rounded to the nearest representable float32 number, matching MATLAB exactly.

Does single accept integer types?

Yes. Integer and logical inputs are promoted to floating point with MATLAB’s semantics. Saturation is not required because the target type is floating-point.

Can I convert strings with single?

No. RunMat mirrors MATLAB’s behaviour: strings raise "single: conversion to single from string is not possible". Convert strings to character arrays first with char.

What about structs, cells, or user objects?

They raise the same conversion error with their class name. Extract the numeric data you need before calling single.

Does single support complex numbers?

Yes. Both the real and imaginary components are converted elementwise, just like MATLAB’s analytic extension.

How does single behave on empty arrays?

Empty arrays stay empty. Shapes and orientations are preserved (0×n stays 0×n).

Will gpuArray inputs stay on the GPU?

Yes. RunMat attempts a device-side cast, and if the provider lacks one it converts on the host and re-uploads the result so downstream GPU code still sees a gpuArray.

How does this affect class or isa?

RunMat currently reports host tensors as "double" because their backing storage is f64. This mirrors other parts of the runtime (for example, gather of a single-precision gpuArray). GPU results still behave correctly when dispatched through Accelerate.

Do NaN or Inf values survive the cast?

Yes. IEEE semantics are preserved; NaNs, ±Inf, and signed zeros remain after conversion.

Where can I learn more?

See MathWorks’ documentation linked above or inspect this builtin’s source file for the exact implementation.

See Also

gpuArray, gather, logical, single (MathWorks)

Source & Feedback