# bsxfun

Binary singleton expansion function for gpuArray

## Syntax

``C = bsxfun(FUN,A,B)``

## Description

example

``` Note The function `arrayfun` offers improved functionality compared to `bsxfun`. `arrayfun` is recommended.This function behaves similarly to the MATLAB® function `bsxfun`, except that the evaluation of the function happens on the GPU, not on the CPU. Any required data not already on the GPU is moved to GPU memory. The MATLAB function passed in for evaluation is compiled and then executed on the GPU. All output arguments are returned as gpuArray objects. You can retrieve gpuArray data using the `gather` function. `C = bsxfun(FUN,A,B)` applies the element-by-element binary operation specified by `FUN` to arrays `A` and `B`, with singleton expansion enabled.```

## Examples

collapse all

Use `bsxfun` with a matrix to subtract the mean of each column from all elements in that column. Then normalize by the standard deviation of each column.

```A = rand(4,'gpuArray'); B = bsxfun(@minus,A,mean(A)); C = bsxfun(@rdivide,B,std(B))```

You can use `bsxfun` to evaluate a function for different combinations of inputs.

```A = rand(4,'gpuArray'); B = bsxfun(@minus,A,mean(A)); C = bsxfun(@rdivide,B,std(B))```
```C = -1.2957 -1.1587 -0.8727 0.2132 -0.2071 0.9960 0.3272 -1.2763 0.4786 0.6523 -0.7228 1.1482 1.0243 -0.4896 1.2684 -0.0851```

Create a function handle that represents the function f(a,b) = 1 - ae-b. Use `bsxfun` to apply the function to vectors `a` and `b`. `bsxfun` uses singleton expansion to expand the vectors into matrices and evaluates the function with all permutations of the input variables.

```a = gpuArray(1:7); b = gpuArray(pi*[0 1/4 1/2 3/4 1 5/4 6/4 7/4 2]).'; fun = @(a,b) 1 - a.*exp(-b); c = bsxfun(fun,a,b)```
```c = 0 -1.0000 -2.0000 -3.0000 -4.0000 -5.0000 -6.0000 0.5441 0.0881 -0.3678 -0.8238 -1.2797 -1.7356 -2.1916 0.7921 0.5842 0.3764 0.1685 -0.0394 -0.2473 -0.4552 0.9052 0.8104 0.7157 0.6209 0.5261 0.4313 0.3365 0.9568 0.9136 0.8704 0.8271 0.7839 0.7407 0.6975 0.9803 0.9606 0.9409 0.9212 0.9015 0.8818 0.8621 0.9910 0.9820 0.9731 0.9641 0.9551 0.9461 0.9371 0.9959 0.9918 0.9877 0.9836 0.9795 0.9754 0.9713 0.9981 0.9963 0.9944 0.9925 0.9907 0.9888 0.9869```

## Input Arguments

collapse all

Function to apply to the elements of the input arrays, specified as a function handle. `FUN` must be a handle to a supported element-wise function, or an element-wise function written in the MATLAB language that uses supported functions and syntax. `Fun` must return scalar values. For each output argument, `FUN` must return values of the same class each time it is called.

`FUN` must be a handle to a function that is written in the MATLAB language. You cannot specify `FUN` as a handle to a MEX-function.

`FUN` can contain the following built-in MATLAB functions and operators.

 ```abs and acos acosh acot acoth acsc acsch asec asech asin asinh atan atan2 atanh beta betaln bitand bitcmp bitget bitor bitset bitshift bitxor cast ceil complex conj cos cosh cot coth csc ``` ```csch double eps eq erf erfc erfcinv erfcx erfinv exp expm1 false fix floor gamma gammaln ge gt hypot imag Inf int8 int16 int32 int64 intmax intmin isfinite isinf isnan ldivide le log ``` ```log2 log10 log1p logical lt max min minus mod NaN ne not ones or pi plus pow2 power rand randi randn rdivide real reallog realmax realmin realpow realsqrt rem round sec sech sign ``` ```sin single sinh sqrt tan tanh times true uint8 uint16 uint32 uint64 xor zeros + - .* ./ .\ .^ == ~= < <= > >= & | ~ && ||``` Scalar expansion versions of the following:```* / \ ^ ```Branching instructions:```break continue else elseif for if return while```

Functions that create arrays (such as `Inf`, `NaN`, `ones`, `rand`, `randi`, `randn`, and `zeros`) do not support size specifications as input arguments. Instead, the size of the generated array is determined by the size of the input variables to your functions. Enough array elements are generated to satisfy the needs of your input or output variables. You can specify the data type using both class and `"like"` syntaxes. The following examples show supported syntaxes for array-creation functions:

```a = rand; b = ones(); c = zeros("like", x); d = Inf("single"); e = randi([0 9], "uint32");```

When you use `rand`, `randi`, and `randn` to generate random numbers within `FUN`, each element is generated from a different substream. For more information about generating random numbers on the GPU, see Random Number Streams on a GPU.

Input arrays, specified as scalars, vectors, matrices, or multidimensional arrays. Inputs `A` and `B` must have compatible sizes. For more information, see Compatible Array Sizes for Basic Operations. Whenever a dimension of `A` or `B` is singleton (equal to one), `bsxfun` virtually replicates the array along that dimension to match the other array. In the case where a dimension of `A` or `B` is singleton, and the corresponding dimension in the other array is zero, `bsxfun` virtually diminishes the singleton dimension to zero.

At least one of the inputs must be a gpuArray. Each array that is stored on CPU memory is converted to a gpuArray before the function is evaluated. If you plan to make several calls to `bsxfun` with the same array, it is more efficient to convert that array to a gpuArray.

Data Types: `single` | `double` | `int8` | `int16` | `int32` | `int64` | `uint8` | `uint16` | `uint32` | `uint64` | `logical`
Complex Number Support: Yes

## Output Arguments

collapse all

Output array, returned as a scalar, vector, matrix, or multidimensional array, depending on the sizes of `A` and `B`. `C` is returned as a gpuArray.

## Tips

• The first time you call `bsxfun` to run a particular function on the GPU, there is some overhead time to set up the function for GPU execution. Subsequent calls of `bsxfun` with the same function can run faster.

• Nonsingleton dimensions of input arrays must match each other. In other words, the corresponding dimensions of arguments `A`, `B`, etc., must be equal to each other, or equal to one. Whenever a dimension of an input array is singleton (equal to 1), `bsxfun` uses singleton expansion. The array is replicated along the singleton dimension to match the largest of the other arrays in that dimension. When a dimension of an input array is singleton and the corresponding dimension in another argument array is zero, `bsxfun` virtually diminishes the singleton dimension to 0.

Each dimension of the output array `C` is the same size as the largest of the input arrays in that dimension for nonzero size, or zero otherwise. The following code shows how dimensions of size 1 are scaled up or down to match the size of the corresponding dimension in other arguments.

```R1 = rand(2,5,4,'gpuArray'); R2 = rand(2,1,4,3,'gpuArray'); R = bsxfun(@plus,R1,R2); size(R) ```
` 2 5 4 3`
```R1 = rand(2,2,0,4,'gpuArray'); R2 = rand(2,1,1,4,'gpuArray'); R = bsxfun(@plus,R1,R2); size(R) ```
``` 2 2 0 4 ```
• Because the operations supported by `bsxfun` are strictly element-wise, and each computation of each element is performed independently of the others, certain restrictions are imposed:

• Input and output arrays cannot change shape or size.

• Functions such as `rand` do not support size specifications. Arrays of random numbers have independent streams for each element.

• Like `bsxfun` in MATLAB, matrix exponential power, multiplication, and division (`^`, `*`, `/`, `\`) perform element-wise calculations only.

• Operations that change the size or shape of the input or output arrays (`cat`, `reshape`, and so on), are not supported.

• Read-only indexing (`subsref`) and access to variables of the parent (outer) function workspace from within nested functions is supported. You can index variables that exist in the function before the evaluation on the GPU. Assignment or `subsasgn` indexing of these variables from within the nested function is not supported. For an example of the supported usage, see Stencil Operations on a GPU

• Anonymous functions do not have access to their parent function workspace.

• Overloading the supported functions is not allowed.

• The code cannot call scripts.

• There is no `ans` variable to hold unassigned computation results. Make sure to explicitly assign to variables the results of all calculations.

• The following language features are not supported: persistent or global variables, `parfor`, `spmd`, `switch`, and `try`/`catch`.

• P-code files cannot contain a call to `bsxfun` with gpuArray data.

## Version History

Introduced in R2012a