Comparison operators

Boolean results

These PyTorch comparison operators return boolean results from comparing values in a pair of inputs:

• allclose - checks if the values in two inputs are all within a comparison tolerance

• close - true for each element in the two inputs that are within tolerance

• equal - checks if both supplied inputs have the same size and identical elements

• eq - equal

• ge - greater than or equal

• gt - greater than

• le - less than or equal

• lt - less than

• ne - not equal

close & allclose

The close function checks if the values in two inputs are within a comparison tolerance and returns boolean true for each element, else false whereas allclose returns a single boolean true if all inputs are within a comparison tolerance, false else. The functions allow relative and absolute comparison tolerances to be given as additional arguments, along with a flag for comparing NaN values.

close(x;y;rtol;atol;nanflag) → booolean scalar

Allowable argument combinations:

• close(x;y)

• close(x;y;nanflag)

• close(x;y;rtol)

• close(x;y;rtol;atol)

• close(x;y;rtol;atol;nanflag)

Parameters:

• x (array,tensor) – 1st required input array or tensor pointer

• y (array,tensor) – 2nd required input array or tensor pointer

• rtol (double) – relative tolerance, default is 1e-05

• atol (double) – absolute tolerance, default is 1e-08

• nanflag (boolean) – set true to consider NaN values as equal, default is false

Returns:

The function returns a k boolean scalar if \(∣x-y∣≤atol+rtol×∣y∣\).

q)close(1 2 3e;1 2.00001 3.0001e)
110b

q)close(1 2 3e;1 2.00001 3.0001e;1e-4)
111b

q)allclose(1 2 3e;1.000001 2.000001 2.99999e)
1b

q)allclose(1 1 1f;.999999999)
1b

equal

The equal function returns true if both supplied inputs have the same size and identical elements, else false.

equal(x;y) → boolean scalar

Parameters:

• x (array,tensor) – 1st required input array or tensor pointer

• y (array,tensor) – 2nd required input array or tensor pointer

Returns:

returns a k boolean scalar, true if x and y are both the same size and have identical elements, else false.

q)equal(2 3#til 6;til 6)
0b
q)equal(2 3#til 6;2 3#til 6)
1b
q)equal(2 3#til 6;1 2 3#til 6)
0b

q)x:tensor 1 2 3e
q)y:tensor 1 2 3.0000001e
q)equal(x;y)
1b

q)use[y]tensor 1 2 3.000001e
q)equal(x;y)
0b

ge, gt, le, lt, ne

These comparison operators accept two inputs and an optional output tensor:

• eq - equal

• ge - greater than or equal

• gt - greater than

• le - less than or equal

• lt - less than

• ne - not equal

comparison(x;y) → k array or tensor

comparison(x;y;output) → null

Parameters:

• x (array,tensor) – 1st required input array or tensor pointer

• y (array,tensor) – 2nd required input array or tensor pointer

• output (pointer) – an api-pointer to a previously allocated tensor to be used for output

Returns:

The function returns a k array if both inputs given as k arrays and otherwise returns a tensor. If an output tensor is supplied, this tensor is filled with the output values and null is returned. A special case of a 3rd argument of unary null is interpreted as an in-place operation, with the output values overwriting the previous values in the first input tensor.

q)eq(1 2 3;4 3 3)
001b

q)x:tensor 1 2 3
q)y:tensor 1 5 1

q)z:ne(x;y)
q)tensor z
011b

q)ne(x;y;z)
q)tensor z
011b

q)ne(x;y;[])
q)tensor x
0 1 1

Special values

These comparison functions return a tensor/array of booleans, one per input element. The k api function name removes the is prefix, e.g. torch.isnan becomes nan.

• finite - returns true for each element that is finite

• inf - returns true if element is positive or negative infinity

• nan - returns true for each element that is NaN

• neginf - returns true for each element that is negative infinity

• posinf - returns true for each element that is positive infinity

special(input) → boolean array or boolean tensor

Parameters:

input (array,tensor) – a k array or tensor pointer

Returns:

Returns a boolean array for each element in given input array, or boolean tensor if input is also a tensor, with true if element matches a special value.

q)x!(x:`finite`inf`neginf`posinf`nan){x y}\:0 0n -0w 0w
finite| 1000b
inf   | 0011b
neginf| 0010b
posinf| 0001b
nan   | 0100b

q)x:tensor 0 0n -0w 0we

q)dtype x
`float

q)y:inf x
q)tensor y
0011b

Min / Max compare

These comparison functions find the maximum or minimum values comparing the elements of two inputs. Function fmax() and fmin() are similar to maximum() and minimum() except in the handling of NaN: fmax()/fmin() will pick the non-NaN value if comparing a mix of NaN and non-NaN elements while maximum()/minimum() will use NaN.

• fmax - compares 2 inputs and returns the maximum for each element

• fmin - compares 2 inputs and returns the minimum for each element

• maximum - compares 2 inputs and returns the maximum for each element

• minimum - compares 2 inputs and returns the minimum for each element

fmax / fmin

fmax(x;y) → tensor or k array with maximum values

fmax(x;y;output) → null

Parameters:

• x (array,tensor) – 1st required input array or tensor pointer

• y (array,tensor) – 2nd required input array or tensor pointer

• output (tensor) – an optional tensor pointer to use for function output

Returns:

Returns tensor with the maximum element across the the two inputs, returns a k array if both inputs are k arrays. Null return if output tensor specified, maximum elements are written to output tensor.

fmin(x;y) → tensor or k array with minimum values

fmin(x;y;output) → null

Param:

Function fmin() uses the same parameters as fmax()

Returns:

Returns tensor with the minimum element across the the two inputs, returns a k array if both inputs are k arrays. Null return if output tensor specified, minimum elements are written to output tensor.

q)fmin(1 2 0n;1 2 3)
1 2 3f

q)maximum(1 2 0n;1 2 3)
1 2 0n

q)r:tensor 0#0n
q)maximum(1 2 0n;1 2 3;r)
q)tensor r
1 2 0n

q)x:tensor 1 2 3e
q)y:tensor 1 1.999999 3.000001
q)z:fmin(x;y)
q)tensor z
1 1.999999 3

maximum / minimum

maximum(x;y) → tensor or k array with maximum values

maximum(x;y;output) → null

Parameters:

• x (array,tensor) – 1st required input array or tensor pointer

• y (array,tensor) – 2nd required input array or tensor pointer

• output (tensor) – an optional tensor pointer to use for function output

Returns:

Returns tensor with the maximum element across the the two inputs, returns a k array if both inputs are k arrays. Null return if output tensor specified, maximum elements are written to output tensor. Any NaN encountered will be returned in the comparison.

minimum(x;y) → tensor or k array with minimum values

minimum(x;y;output) → null

Param:

Function minimum() uses the same parameters as maximum()

Returns:

Returns tensor with the minimum element across the the two inputs, returns a k array if both inputs are k arrays. Null return if output tensor specified, minimum elements are written to output tensor. Any NaN encountered will be returned in the comparison.

q)x:tensor 1 2 3e
q)y:tensor 1 1.999999 3.000001e
q)z:minimum(x;y)

q)tensor z
1 1.999999 3e

Sorting

• sort - returns a sorted array or tensor and the indices used to sort.

• msort - sorts the elements of the input along the first dimension

• argsort - returns the indices to sort the input

• topk - returns k largest/smallest elements and their indices

• kthvalue - return k-th smallest elements and their indices

• In - test if input elements in set

sort

sort(x;dim;descend;stable) → values and indices

sort(x;dim;descend;stable;output) → null

Allowable argument combinations:

• sort(x)

• sort(x;descend)

• sort(x;descend;stable)

• sort(x;dim)

• sort(x;dim;descend)

• sort(x;dim;descend;stable)

• any of the above combinations followed by a trailing output vector

Parameters:

• x (array,tensor) – input array or tensor pointer

• dim (long) – the optional dimension on which to sort, default is last dimension

• descend (bool) – default false, set true to return indices in descending order

• stable (bool) – default false, set true to guarentee the order of equivalent elements

• output (vector) – a vector pointer <vectors>

Returns:

Returns sorted values and indices as k arrays or tensors depending on form of input. If output vector supplied, values and indices are written to the vector and null returned.

q)sort 5 2 9
2 5 9
1 0 2

q)sort(5 2 9;1b) / descending
9 5 2
2 0 1

Using sort() with a 2-d tensor:

q)x:tensor(`randn;5 2)
q)tensor x
-0.198 0.882
0.858  0.628
-0.399 0.72
-0.329 -0.382
2.14   -1.49

q)v:sort(x;0)
q)size v
5 2
5 2

q)vector(v;0)
-0.399 -1.49
-0.329 -0.382
-0.198 0.628
0.858  0.72
2.14   0.882

q)vector(v;1)
2 4
3 3
0 1
1 2
4 0

q)sort(x;0;1b;v)  /descending, re-using vector
q)vector(v;0)
2.14   0.882
0.858  0.72
-0.198 0.628
-0.329 -0.382
-0.399 -1.49

msort

Function msort() sorts the elements of the input along the first dimension, e.g. sorts the rows of a matrix in ascending order.

msort(x) → sorted array or tensor

msort(x;output) → null

Parameters:

• x (array,tensor) – required input array or tensor pointer.

• output (pointer) – an optional pointer to a previously allocated tensor to be used for output.

Returns:

The function returns a k array if given a k array as input and returns a tensor if a tensor is given as the input argument. The output is sorted on the first dimension. If an output tensor is supplied, this tensor is filled with the output values and null is returned.

q)x:tensor(`randn;3 2)
q)tensor x
1.8    -0.534
-0.177 -0.0571
-0.692 -1.36

q)msort tensor x
-0.692 -1.36
-0.177 -0.534
1.8    -0.0571

q)y:msort x
q)tensor y
-0.692 -1.36
-0.177 -0.534
1.8    -0.0571

q)msort(neg tensor x;y)
q)tensor y
-1.8  0.0571
0.177 0.534
0.692 1.36

argsort

The argsort() function returns the indices needed to sort along a given dimension (default is last dimension if non specified). By default the indices specify an ascending order, a flag can be set true to return indices in descending order.

argsort(x;dim;descend) → indices

Allowable argument combinations:

• argsort(x;descend)

• argsort(x;dim)

• argsort(x;dim;descend)

Parameters:

• x (array,tensor) – input array or tensor pointer

• dim (long) – the optional dimension on which to sort, default is last dimension

• descend (bool) – default false, set true to return indices in descending order

Returns:

If a k array is given, an array of indices is returned, else a tensor pointer

q)x:tensor(`randn;2 3)
q)tensor x
-0.628 -0.162 1.19
 1.15   0.677 0.626

q)argsort(tensor x)
0 1 2
2 1 0

q)y:argsort(x;0;1b)
q)tensor y
1 1 0
0 0 1

topk

Function topk() returns the largest/smallest values of given input along with their indices. The sorting is done along the last dimension unless a different dimension is specified.

topk(x;k;dim;largest;sorted) → values and indices

topk(x;k;dim;largest;sorted;output) → null

Allowable argument combinations:

• topk(x;k)

• topk(x;k;dim)

• topk(x;k;dim;largest)

• topk(x;k;dim;largest;sorted)

• topk(x;k;largest)

• topk(x;k;largest;sorted)

• any of the above argument combinations with a trailing output vector

Parameters:

• x (array,tensor) – input array or tensor pointer

• k (long) – the number of values to find, required (cannot exceed input size in operating dimension)

• dim (long) – the optional dimension on which to sort, default is last dimension

• largest (bool) – default true, set false to find smallest values and indices

• sorted (bool) – default true, return elements in sorted order, set false for no defined order

• output (vector) – a vector pointer <vectors>

Returns:

If a k array is given, an array of indices is returned, else a tensor pointer

q)topk(100.1+til 7; 3)
106.1 105.1 104.1
6     5     4

q)x:tensor 100.1+til 7
q)v:topk(x; 3; 0b)
q)vector v
100.1 101.1 102.1
0     1     2

An example using an output vector with a 2-d input and operating over the first dimension:

q)x:tensor 4 2#100.1+til 8
q)v:vector()
q)topk(x;2;0;v)

q)vector(v;0)
106.1 107.1
104.1 105.1

q)vector(v;1)
3 3
2 2

kthvalue

Function kthvalue() returns the k-th smallest value and index over the last or specified dimension of input.

kthvalue(x;k;dim;keepdim) → values and indices

kthvalue(x;k;dim;keepdim;output) → null

Allowable argument combinations:

• kthvalue(x;k)

• kthvalue(x;k;dim)

• kthvalue(x;k;dim;keepdim)

• kthvalue(x;k;keepdim)

• any of the above argument combinations with a trailing output vector

Parameters:

• x (array,tensor) – input array or tensor pointer

• k (long) – k for the k-th smallest element

• dim (long) – the optional dimension on which to sort, default is last dimension

• keepdim (bool) – default false, set true to preserve the dimension of the input for the minimum and maximum values.

• output (vector) – a vector pointer <vectors>

Returns:

Returns k-th smallest values and indices as k arrays or tensors depending on form of input. If output vector supplied, values and indices are written to the vector and null returned.

q)kthvalue(1 2 3 4 5;2)
2 1

q)kthvalue(1 2 3 4 5;3)
3 2

q)show x:5 3#1.1+til 15
1.1  2.1  3.1
4.1  5.1  6.1
7.1  8.1  9.1
10.1 11.1 12.1
13.1 14.1 15.1

q)kthvalue(x;3;1)  / 3rd smallest across columns
3.1 6.1 9.1 12.1 15.1
2   2   2   2    2

q)kthvalue(x;3;0)  / 3rd smallest across rows
7.1 8.1 9.1
2   2   2

q)x:tensor x
q)v:vector()
q)kthvalue(x;3;0;v)
q)vector v
7.1 8.1 9.1
2   2   2

In

Function In(), renamed from PyTorch’s isin tests if first input is in the second input – either input can be a scalar, but not both inputs.

In(x;y;unique;invert) → boolean true for each element of x in y

In(x;y;unique;invert;output) → null

Allowable argument combinations:

• In(x;y)

• In(x;y;unique)

• In(x;y;unique;invert)

• any of the above argument combinations with a trailing output tensor

Parameters:

• x (scalar,array,tensor) – input scalar, array or tensor pointer.

• y (scalar,array,tensor) – input scalar, array or tensor pointer.

• unique (bool) – optional, default false, set true if both inputs have unique elements.

• invert (bool) – optional, default false, set true to return the opposite of x in y.

• output (tensor) – output tensor pointer, must have boolean datatype.

Returns:

If either x or y is a tensor, returns a boolean tensor, else returns k scalar/array indicating if x in y. If output tensor supplied, results are written to the supplied tensor, null return.

q)In(1 2 3;3 4 5 6)
001b

q)In(1 2 3;3 4 5 6;1b;1b)  /turn on unique & invert result
110b

q)x:tensor(`arange;5)
q)r:In(5 9 1 0;x)
q)tensor r
0011b

q)In(5 9 1 0;x;1b;1b;r)  /unique,invert w'output tensor
q)tensor r
1100b