single — Convert values to IEEE single-precision (float32) with MATLAB-compatible type conversion rules.
single(X) converts scalar or array values to single precision (float32). It preserves MATLAB-compatible shape behavior while converting supported numeric, logical, character, and complex inputs.
Syntax
Y = single(X)
Y = single(X, "like", prototype)Inputs
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
X | Any | Yes | — | Input scalar/array value to convert. |
like | StringScalar | Yes | — | Literal string "like". |
prototype | LikePrototype | Yes | — | Output class/device prototype. |
Returns
| Name | Type | Description |
|---|---|---|
Y | NumericArray | Single-precision output value. |
Errors
| Identifier | When | Message |
|---|---|---|
RunMat:single:InvalidArgument | Optional arguments are malformed or unsupported. | single: invalid argument |
RunMat:single:InvalidInput | Input value or prototype cannot be converted to single. | single: invalid input |
RunMat:single:GpuUnsupported | GPU output via "like" is requested but no compatible provider is active. | single: gpu output not supported |
RunMat:single:Internal | Internal conversion, gather, or provider upload failed. | single: internal error |
How single works
- Numeric scalars and arrays (double or integer) are rounded directly into native IEEE single-precision storage. Scalars remain scalar values; 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.
- The two-argument
single(X, 'like', prototype)form is a RunMat extension. It is available inrunmatcompatibility mode and rejected in MATLAB-compatible modes because the compatibility target's publicsinglecontract documents onlysingle(X).
Does RunMat run single on the GPU?
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 selected by the shared execution planner.
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).
GPU memory and residency
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.
Examples
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 6Convert a scalar double to single precision
pi_single = single(pi)Expected output:
pi_single =
single
3.1416Convert 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.0000iConvert a character array to single precision codes
codes = single('ABC')Expected output:
codes =
1×3 single row vector
65 66 67Keep 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 5Convert 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 1Using single with coding agents
Open a RunMat example with live inputs, then ask the agent to explain how single changes the result.
Run a small single example, explain the result, then change one input and compare the output.
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?⌄
Host and gathered results use native float32 storage, so class(single(X)) reports single and isa(single(X), 'single') is true. The class is not a metadata label over a double buffer.
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.
Related Math functions
Elementwise
abs · angle · bsxfun · complex · conj · double · erf · erfcinv · exp · expm1 · factorial · flintmax · gamma · gammaln · heaviside · hypot · idivide · imag · intmax · intmin · ldivide · log · log10 · log1p · log2 · minus · nextpow2 · plus · pow2 · power · rdivide · real · realmax · realmin · realsqrt · rescale · sign · sqrt · swapbytes · times · typecast · uint16 · uint32 · uint8
Trigonometry
acos · acosh · asin · asinh · atan · atan2 · atanh · cos · cosd · cosh · cospi · deg2rad · pol2cart · rad2deg · sin · sind · sinh · sinpi · tan · tand · tanh
Reduction
all · any · bounds · cummax · cummin · cumprod · cumsum · cumtrapz · diff · gradient · max · maxk · mean · median · min · mink · movmax · movmean · movmedian · movmin · movprod · movstd · movsum · movvar · nnz · prod · rms · std · sum · trapz · var
Structure
bandwidth · isdiag · ishermitian · issymmetric · istril · istriu · symrcm
Signal
blackman · butter · buttord · cheb2ord · conv · conv2 · deconv · downsample · envelope · filter · filtfilt · fir1 · freqz · gauspuls · hamming · hann · hilbert · periodogram · pulstran · pwelch · rectpuls · resample · sawtooth · sinc · spectrogram · square · tripuls · unwrap · upsample · zplane
Optim
coneprog · fminbnd · fminunc · fsolve · fzero · integral · linprog · lsqcurvefit · lsqnonlin · optimoptions · optimset · quad · secondordercone
Ops
cross · ctranspose · dot · mldivide · mpower · mrdivide · mtimes · pagemtimes · pagetranspose · trace · transpose
Open-source implementation
Unlike proprietary runtimes, every RunMat function is open-source. Read exactly how single is executed, line by line, in Rust.
- View the source for single in Rust on GitHub
- Learn how the RunMat runtime works
- Found a bug? Open an issue with a minimal reproduction.
About RunMat
RunMat is an open-source runtime that executes MATLAB-syntax code blazing on any GPU. It is licensed under the Apache 2.0 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.