Binary operations

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)

Binary operations between two objects can be handled in a variety of ways in Horace. You can either use the Matlab symbols +, - , *, / and \, or you can use the explicit function names `plus, minus, mtimes, mrdivide` and `mldivide`.

There are several options for the input parameters to binary operations

sqw objects

Let us take for our example the addition operator '+', and our initial single sqw object is called `w1` and has the 'pix' array retained (note this is an important point - you can have an sqw object without the pix array by converting a dnd object to sqw. In that case the result is referred to as an sqw object of dnd type. In our example `w1` has a pix array, so is referred to as an sqw of sqw type).

Single sqw object

You can add to w1 in the following way

```wout = w1 + w2_sqw

wout = w1 + w2_sqw_dnd_type

wout = w1 + w2_dnd

wout = w1 + scalar

```

The conditions for these operations are as follows:

• `w2_sqw` is an sqw of sqw type, with a pix array of identical size to the pix array of `w1`. There is only really one circumstance in which doing a binary operation of this type makes sense - when a background dataset has been created that maps exactly onto the real dataset, and needs to be subtracted.
• `w2_sqw_dnd_type` is an sqw of dnd type (i.e. no it has pix array) whose plot axes overlap exactly with those of `w1`. An example is taking a 1d cut along the energy axis from two different regions of reciprocal space, and then adding or subtracting one from the other. In this case the output will be a sqw object of dnd type, since the pixel information has lost its connection with the signal and error that are plottable.
• `w2_dnd` as above, but `w2_dnd` is a dnd object rather than an sqw of dnd type. Similarly to the above, the output is an sqw object of dnd type.
• `scalar` is a single number, e.g. if you want to add 4.782 to all of the data in `w1`. The output stays as a full sqw of sqw type (with pix array).

Array of sqw objects

You can use the same binary operation syntax as for single sqw objects, with the following conditions

• `w2_sqw` is either an array of sqw of sqw type objects with the pix array of each element matching the pix array of each element of `w1`. Or a single sqw object if the pix array happens to be the same size for all elements of the `w1` array.
• `w2_sqw_dnd` is as above, i.e. an array of dnd-type sqw objects whose plot axes match element by element those of the array `w1`.
• `w2_dnd` same rules as for sqw of dnd type above.
• `scalar` the same scalar is subtracted from every pix array in the array of sqw objects.

```wout = w1 + numeric_array
```
• `numeric_array` is an array of scalars whose size matches the size of the sqw array. The output will continue to be an sqw of sqw type, with a pix array.

dnd objects

Note that here we will use the phrase dnd object also to mean sqw object of dnd type, since the two are very closely related.

Single dnd object

The choices for a dnd object are:

```wout = w1 + w2_sqw

wout = w1 + w2_sqw_dnd_type

wout = w1 + w2_dnd

wout = w1 + scalar

```

The forms of these objects are as described for the sqw case. In all cases the output will be a dnd object. Note that the pix field of `w2_sqw` is ignored for this operation.

Array of dnd objects

As with arrays of sqw objects, there is one further choice compared to a single dnd:

```wout = w1 + numeric_array
```

As for sqw objects, the numeric array has to be the same size as the array of dnd objects.

List of operations and their equivalent code

The arithmetic operations above correspond to equivalent Matlab functions. You should never need to use these, but for reference the corresponding functions are:

```w1 + w2 --> plus(w1,w2)

w1 - w2 --> minus(w1,w2)

w1 * w2 --> mtimes(w1,w2)

w1 / w2 --> mrdivide(w1,w2)

w1 \ w2 --> mldivide(w1,w2)

w1 ^ w2 --> mpower(w1,w2)
```

Important the matrix operations *, /, \ and ^ (mtimes, mrdivide, mldivide and mpower) are performed element-by-element. So the equivalent Matlab routines would be .*, ./, .\ and .^