RunMat
GitHub

View all functions

CategoryMath: Elementwise
GPUYes

What does the double function do in MATLAB / RunMat?

double(X) promotes scalars, arrays, complex values, logical masks, character data, and gpuArray handles to MATLAB’s default double-precision (float64) representation while preserving shapes and column-major layout.

How does the double function behave in MATLAB / RunMat?

  • Numeric inputs that are already double precision are returned unchanged; single-precision and integer values are promoted without altering shapes.
  • Logical inputs become dense double arrays containing 0 and 1, matching MATLAB’s promotion rules used by arithmetic on logical masks.
  • Character arrays are converted to their Unicode code points and returned as doubles ('A' becomes 65).
  • Complex scalars and arrays remain complex, but both components are stored as double precision.
  • Empty arrays stay empty, orientation is preserved, and singleton dimensions are untouched.
  • Strings, structs, cells, objects, and other unsupported classes raise MATLAB-style errors of the form "double: conversion to double from <type> is not possible".

double Function GPU Execution Behaviour

RunMat first inspects the active acceleration provider:

  1. Provider exposes float64 (double) precision: gpuArray inputs are kept on device. The runtime downloads once only when the provider lacks a native cast primitive, performs the conversion on the host, and uploads the double-precision result back to the device, freeing the original handle. Providers may later add a unary_double hook to avoid the temporary host hop.
  2. Provider is float32-only: gpuArray inputs are gathered to host memory because the backend cannot store double precision. The result is returned as a host tensor; subsequent operations can choose to re-upload if profitable.
  3. No provider registered: gpuArray values behave like gathered host arrays, mirroring MATLAB’s behaviour when Parallel Computing Toolbox is absent.

All GPU fallbacks are documented so you know exactly when data leaves the device.

Examples of using the double function in MATLAB / RunMat

Convert integers to double precision

ints = int32([1 2 3]);
doubles = double(ints);

Expected output:

doubles = [1 2 3];

Promote logical masks for arithmetic

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

Expected output:

weights = [0 1 0 1];

Convert character arrays to Unicode code points

codes = double('RunMat');

Expected output:

codes = [82 117 110 77 97 116];

Preserve complex numbers while promoting precision

z = [1+2i, 3-4i];
result = double(z);

Expected output:

result = [1+2i  3-4i];

Convert single-precision gpuArray data to double

G = single(gpuArray(1:4));
H = double(G);
gather(H)

Expected output (on a float64-capable backend):

ans = [1 2 3 4];

Handle double precision with 'like' prototypes

proto = gpuArray.zeros(1, 1, 'double');
out = double([pi 0], 'like', proto);

Expected output:

out =
  1×2 gpuArray  double
    3.1416         0

Promote matrices without changing shape

A = single([1.5 2.25; 3.75 4.5]);
B = double(A);

Expected output:

B = [1.5 2.25; 3.75 4.5];

GPU residency in RunMat (Do I need gpuArray?)

RunMat keeps tensors on the GPU whenever the active provider supports double precision. You only need explicit gpuArray / gather calls when interfacing with legacy code or when you must force residency. On float32-only providers, double returns host data, matching MATLAB systems where the GPU lacks native double support.

FAQ

Does double change values that are already double precision?

No. Existing double data is passed through unchanged; the builtin only promotes other types.

How are logical inputs handled?

Logical masks become numeric 0/1 doubles, making it easy to apply arithmetic or linear algebra without extra casts.

What happens to NaN or Inf values?

IEEE special values survive promotion exactly. NaNs stay NaN, and ±Inf remain ±Inf.

Can I convert strings with double?

No. Strings are not implicitly convertible; convert them to character arrays first with char and then take double.

Will double keep results on the GPU?

Yes when the provider supports float64. Otherwise the runtime documents the gather fallback and returns a host tensor.

Does double allocate new memory?

Yes. Results are materialised in a new tensor or, for scalars, a new numeric value. Fusion may fold the cast with neighbouring elementwise operations.

Can I request GPU residency with 'like'?

Yes. Pass 'like', prototype to mirror the prototype’s residency. Provide a gpuArray prototype to keep the result on the device when the backend supports float64.

How does double interact with complex inputs?

Complex values keep both components intact; the builtin simply ensures they are stored as double precision.

See Also

single, real, gpuArray, gather

Source & Feedback