arrayfun — Apply a scalar function element-wise across array inputs.
arrayfun invokes a scalar callback at every position of one or more arrays and collects either uniform array output or a cell array of individual results.
Syntax
B = arrayfun(func, A1, An...)
B = arrayfun(func, A1, An..., nameValue...)Inputs
func- Type
Any- Required
- Yes
- Description
- Scalar callback function handle.
A1- Type
Any- Required
- Yes
- Description
- First array input.
An- Type
Any- Required
- Variadic
- Description
- Additional element-wise array inputs.
nameValue- Type
Any- Required
- Variadic
- Description
- `UniformOutput` and `ErrorHandler` name-value pairs.
Returns
B- Type
Any- Description
- Uniform scalar results as an array, or nonuniform results as a cell array.
Errors
RunMat:arrayfun:InvalidInput- When
- The callable, arrays, or option tail violates the arrayfun input contract.
- Message
arrayfun: invalid input arguments
RunMat:arrayfun:UniformOutputOption- When
- UniformOutput is not logical true or false, or double one or zero.
- Message
arrayfun: UniformOutput must be logical true or false
RunMat:arrayfun:CallbackFailed- When
- A callback fails and no ErrorHandler recovers the element.
- Message
arrayfun: callback execution failed
Element-wise callback execution
B = arrayfun(func,A1,A2,...) extracts one scalar from each input at every result position and calls func with those scalars. Ordinary host arrays must have equal sizes. RunMat compatibility mode also permits host scalar expansion; gpuArray inputs follow compatible-size expansion.
A function handle is the portable callable form. Character-vector and string-scalar names are available in RunMat compatibility mode. Source, local, nested, anonymous, bound, and builtin handles use the same callable-resolution boundary.
Output and error handling
UniformOutput defaults to true. Every invocation must then return one scalar, and the results must have one compatible class. Double, single, logical, complex, and all eight fixed-width integer classes retain their supported representation.
Set UniformOutput to false to keep each callback result in a cell. ErrorHandler receives an error structure followed by the scalar arguments for the failed position. RunMat currently supports one callback output per invocation.
An empty input produces an empty result with the planned output shape. When the callback's result class is statically known, analysis retains that class even though no callback invocation runs.
Numeric, logical, character, string, and complex arrays are supported. Multiple callback outputs and cell, structure, and user-object inputs are not yet supported by arrayfun.
Provider-resident inputs
Supported builtin callbacks can execute directly when every input is a gpuArray. Other callbacks gather authoritative typed values through the owning provider, execute on the host, and re-upload supported uniform numeric or logical output.
The direct provider path currently covers sin, cos, abs, exp, log, sqrt, plus, minus, times, rdivide, and ldivide. Other callbacks follow the typed gather path.
The callback makes arrayfun a fusion boundary. Nonuniform, character, and currently unsupported complex provider outputs remain on the host. UniformOutput and ErrorHandler on gpuArray input are RunMat compatibility-mode extensions.
Examples
Square every matrix element
A = [1 2 3; 4 5 6];
B = arrayfun(@(x) x.^2, A)Expected output:
B = [1 4 9; 16 25 36]Map equal-sized arrays together
A = [1 2 3];
offset = [10 20 30];
B = arrayfun(@plus, A, offset)Expected output:
B = [11 22 33]Keep array results in cells
A = [1 2 3];
B = arrayfun(@(x) [x x], A, "UniformOutput", false)Expected output:
B is a 1-by-3 cell arrayPreserve exact integer callback results
base = uint64(2^53);
A = [base + uint64(1) base + uint64(3)];
B = arrayfun(@(x) x + uint64(1), A)Expected output:
B retains exact uint64 values above flintmaxMap a supported callback on the GPU
G = gpuArray(single([0 pi/2 pi]));
S = arrayfun(@sin, G);
H = gather(S)Expected output:
H is single [0 1 0] within floating-point toleranceUsing arrayfun with coding agents
Open a RunMat example with live inputs, then ask the agent to explain how arrayfun changes the result.
Run a small arrayfun example, explain the result, then change one input and compare the output.
FAQ
Must I create a gpuArray first?⌄
No. The planner may select acceleration for suitable work. An explicit gpuArray is useful when source compatibility or deliberate residency matters.
What if callback results have different classes?⌄
Use UniformOutput, false to retain the values in cells. Uniform output rejects heterogeneous result classes rather than silently choosing a new class.
Can arrayfun accept character or string arrays?⌄
Yes. Character elements are passed as scalar character arrays and string elements as string scalars; result collection follows the selected uniform-output policy.
What happens after a callback error?⌄
Without an ErrorHandler, the first failure ends the call. With a handler, arrayfun passes error information and the current scalar inputs to that handler.
How are logical results stored on a GPU?⌄
The provider uses its logical buffer representation while the result is resident. gather restores a RunMat logical array rather than exposing the provider encoding.
Related Acceleration functions
Source you can read
Every RunMat function's source is public. Read exactly how arrayfun is executed, line by line, in Rust.
- View the source for arrayfun in Rust on GitHub
- Learn how the RunMat runtime works
- Found a bug? Open an issue with a minimal reproduction.
About RunMat
RunMat is a runtime that executes MATLAB-syntax code fast on any GPU. The runtime is free for individuals, including freelancers; students and faculty at an academic institution, for teaching or research there; contributors to an open-source project, for work on that project; organizations with 250 or fewer people and US$10M or less in annual revenue; and anyone, for non-production use. See runmat.com/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.