Wolfram Research

Function Repository Resource:

BoolEval

Source Notebook

Fast vectorized evaluation of array inequalities

Contributed by: Szabolcs Horvát

ResourceFunction["BoolEval"][array>value]

replaces elements of array which are greater than value with 1 and the rest with 0.

ResourceFunction["BoolEval"][condition]

takes a condition expressed in terms of >, ≥, <, ≤, ⩵, ≠ and logical operators, and evaluates it for each element of the arrays appearing in the condition, returning a Boolean array of 1s and 0s.

Details and Options

ResourceFunction["BoolEval"] is intended for use with numerical arrays.
The arrays appearing in the conditions must have compatible sizes.
ResourceFunction["BoolEval"] has attribute HoldAll, and only processes operators that appear literally in the input.
The primary purpose of ResourceFunction["BoolEval"] is to achieve maximum performance, therefore it does not check its input for correctness. This is left to the programmer.
Effectively, ResourceFunction["BoolEval"][x>a] is equivalent to Boole@Thread[x>a].
Internally, ResourceFunction["BoolEval"] converts inequalities to expressions in terms of UnitStep and logical operators to arithmetic ones.
The BoolEval package contains the same function (BoolEval) as well as related utilities and documentation.

Examples

Basic Examples

Identify elements of an array that are larger than 5:

In[1]:=
ResourceFunction["BoolEval"][Range[10] > 5]
Out[1]=

Identify elements that are greater than or equal to 3 but less than 7:

In[2]:=
ResourceFunction["BoolEval"][3 <= Range[10] < 7]
Out[3]=

Scope

Higher dimensional arrays are supported:

In[4]:=
ResourceFunction["BoolEval"][( {
    {1, 2},
    {3, 4}
   } ) != 3]
Out[4]=

Compare each row of a matrix with a different constant:

In[5]:=
ResourceFunction["BoolEval"][{{1, 2}, {3, 4}} <= {2, 3}]
Out[5]=

Compare two arrays:

In[6]:=
ResourceFunction["BoolEval"][Range[5] == Range[5, 1, -1]]
Out[6]=

BoolEval supports any expression that works with arithmetic and basic numerical operations:

In[7]:=
ResourceFunction["BoolEval"][<|"a" -> 10, "b" -> 3|> < 5]
Out[7]=

BoolEval works with images:

In[8]:=
(* Evaluate this cell to get the example input *) CloudGet["https://www.wolframcloud.com/obj/666e3c88-207a-4199-b60b-2a067ee4cf99"]
Out[8]=

Applications

Count the number of array elements that are greater than 0.3:

In[9]:=
array = RandomReal[1, 100];
Total@ResourceFunction["BoolEval"][array > 0.3]
Out[10]=

Pick non-positive elements of an array:

In[11]:=
array = RandomVariate[NormalDistribution[], 10];
Pick[array, ResourceFunction["BoolEval"][array <= 0], 1]
Out[12]=

Process an array much faster than it would be possible using Select or Cases:

In[13]:=
array = RandomReal[1, 1000000];
result1 = Pick[array, ResourceFunction["BoolEval"][array > 0.5], 1]; // RepeatedTiming
Out[4]=
In[14]:=
result2 = Select[array, # > 0.5 &]; // RepeatedTiming
Out[14]=
In[15]:=
result3 = Cases[array, x_ /; x > 0.5]; // RepeatedTiming
Out[15]=
In[16]:=
result1 === result2 === result3
Out[16]=

Properties and Relations

BoolEval effectively threads comparisons over arrays, then converts truth values to 0 or 1:

In[17]:=
ResourceFunction["BoolEval"][Range[5] < 3]
Out[17]=
In[18]:=
Boole[Thread[Range[5] < 3]]
Out[18]=

Literal truth values are also converted to 0s and 1s:

In[19]:=
ResourceFunction["BoolEval"][{True, False}]
Out[19]=

Passing symbolic input to BoolEval reveals how it translates inequalities to UnitStep and logical operators to arithmetic ones:

In[20]:=
ResourceFunction["BoolEval"][a <= 3]
Out[20]=
In[21]:=
ResourceFunction["BoolEval"][a > 3]
Out[21]=
In[22]:=
ResourceFunction["BoolEval"][a && b && ! c]
Out[22]=

Possible Issues

Only those operators are processed which appear literally in the argument of BoolEval:

In[23]:=
f[arr_] := arr > 3
ResourceFunction["BoolEval"][f[Range[5]]]
Out[24]=
In[25]:=
ResourceFunction["BoolEval"][Range[5] > 3]
Out[25]=

Evaluate the argument explicitly using the Evaluate function to allow BoolEval to see the operators:

In[26]:=
f[arr_] := arr > 3
ResourceFunction["BoolEval"][f[Range[5]] // Evaluate]
Out[27]=

BoolEval is optimized for performance, and does not check its arguments for correctness:

In[28]:=
ResourceFunction["BoolEval"][{1, 2, 3} < {2, 3}]
Out[28]=

The arrays in the argument must be numeric:

In[29]:=
ResourceFunction["BoolEval"][{"a", "b", "c"} < "b"]
Out[29]=

Neat Examples

Estimate the value of π using Monte Carlo integration:

In[30]:=
With[{n = 1000000},
 4 N@Total@ResourceFunction["BoolEval"][
      Total[RandomReal[{-1, 1}, {2, n}]^2] < 1
      ]/n
 ]
Out[30]=

Resource History

Source Metadata

Author Notes

This resource function serves as a preview to the BoolEval package, and implements the package’s core functionality. The package contains additional utility functions, additional documentation, a tutorial and it is compatible Mathematica version 10.0 or later.

License Information