doc: Reduction operators: .any() vs .bool()

[meithecatte]

This section lists, among others, the following two reduction operators:

• a.any() – reduction OR; is any bit set?
• a.bool() – conversion to boolean; is non-zero?

If I am understanding these descriptions correctly, a.any() == a.bool() for all a. However, the existence of both has me confused – am I missing something?

If these two operators are just aliases, this fact should be called out in the docs. Otherwise, the difference between them should be explained.

[wanda-phi]

oh, fancy seeing you here :3

they have the exact same semantics, and exist essentially because they are a carbon copy of corresponding distinct yosys cells, which exist because RTLIL is based directly on Verilog language to an insane degree, and $reduce_or is used to represent the unary |abc operator, while $reduce_bool is used to represent the implicit conversion to a boolean as part of an if condition and similar.

thus using .any() vs .bool(), while semantically the same, will result in using different RTLIL cells in the output, resulting in slightly different (but still semantically identical) Verilog output.

ie. don't worry about it, just use whichever you feel makes sense for the code you're writing.

[whitequark]

Otherwise, the difference between them should be explained.

I would describe the difference as:

• Use .bool() when you would be treating the result as a boolean if it was Python (i.e. using if, or, and, etc with it).
• Use .any() when you would be treating the result as a bit container if it was Python (i.e. using any(...) with it).

Python has a similar ambiguity--you can write both if bool(x) and if any(x)--it's just that it has richer types so it's less ambiguous. I hope this clears it up a bit.

[whitequark]

We should probably add the explanation above to the doc.

[whitequark]

@meithecatte Does this clarify it? #1263

[meithecatte]

Yes, I think that's a good way to clarify this.