Add support for non-Tuple iterators

[dennisYatunin]

This PR adds an interface to UnrolledUtilities that allows it to handle non-Tuple iterators as both inputs and outputs of unrolled functions.

Content

• Adds what is essentially a simplified version of the Base.AbstractBroadcasted interface for static iterators (a detailed summary is located at the top of src/unrollable_interface.jl).
• Adds support for lazy iterators from Base, such as those generated by the enumerate, zip, and Iterators.map functions. Also removes the unrolled_zip and unrolled_enumerate functions, since they are no longer necessary. These functions were not used outside of this repository, so this shouldn't be a breaking change.
• Adds support for NamedTuples and iterators from StaticArrays.
• Implements and adds support for static lazy iterators, which store unevaluated computations that can be inlined elsewhere, and static bitwise iterators, which reduce the register space needed by a collection of Bools by a factor of 8 in comparison to NTuple{N, Bool}.
• Adds some tests to demonstrate when it is beneficial to use static bitwise iterators. As is shown in the auto-generated comparison table, passing an iterator larger than 32 bytes in size through at least two levels of reduction/accumulation results in allocations, even when everything is unrolled. So, replacing a Tuple with a static bitwise iterator can allow us to use 256 Bools instead of 32 without triggering allocations, which will be useful for optimizing the non-orographic gravity wave tendency in ClimaAtmos. (cc @Xiaoyang-Xie)
• Adds an unrolled version of Base.accumulate, along with an optimized version for static bitwise iterators. This could also be helpful for the gravity wave tendency.
• Improves the auto-generated comparison table by measuring compilation time and memory usage more accurately, splitting memory usage measurements into GC (garbage collector) and RSS (resident set size) values, adding measurements of runtime, and summarizing compiler optimizations more clearly.

[charleskawczynski]

I discussed the design with @dennisYatunin, and it looks good. The generated table is really nice for seeing how things perform, too.

It'll be nice to use this new version in ClimaCore

[dennisYatunin]

@Sbozzolo I have added a bunch of documentation to this PR, with a focus on guiding users through the all of the different problems addressed by UnrolledUtilities. Could you please take a look and let me know whether it is sufficiently clear? In particular, is it enough for UnrolledUtilities to be used in ClimaCore and ClimaAtmos? If so, we can move ahead with CliMA/ClimaAtmos.jl#3267.

[codecov]

Codecov Report

Attention: Patch coverage is 58.37104% with 92 lines in your changes missing coverage. Please review.

Project coverage is 61.18%. Comparing base (0eeebf0) to head (6efc2a5).
Report is 1 commits behind head on main.

Files with missing lines	Patch %	Lines
src/StaticBitVector.jl	30.00%	49 Missing ⚠️
src/unrollable_iterator_interface.jl	48.93%	24 Missing ⚠️
src/UnrolledUtilities.jl	81.81%	6 Missing ⚠️
src/generatively_unrolled_functions.jl	82.85%	6 Missing ⚠️
ext/UnrolledUtilitiesStaticArraysExt.jl	0.00%	4 Missing ⚠️
src/StaticOneTo.jl	60.00%	2 Missing ⚠️
src/recursively_unrolled_functions.jl	95.45%	1 Missing ⚠️

Additional details and impacted files

@@             Coverage Diff              @@
##              main      #10       +/-   ##
============================================
- Coverage   100.00%   61.18%   -38.82%     
============================================
  Files            1        8        +7     
  Lines           46      237      +191     
============================================
+ Hits            46      145       +99     
- Misses           0       92       +92     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[charleskawczynski]

@charleskawczynski Yes, the inference failures demonstrated in the ClimaCore PR linked in #9 were caused by UnrolledUtilities being unable to handle NamedTuples. This PR adds full support for NamedTuples. Also, I've added some benchmarks to compare generative unrolling (what this package was previously doing) with recursive unrolling (what lots of functions in ClimaCore are doing). It turns out that recursive unrolling is faster to compile for small iterators, though it is much slower to compile and generates less optimal code for large iterators. I've modified the interface so that we can switch from generative to recursive unrolling for small iterators (the cutoff is currently set to 16). Since nearly all of the unrolling we do in ClimaCore is over small iterators, this should allow us to use UnrolledUtilities throughout ClimaCore without any increase in compilation time.

Good work, and I think that makes sense. Thanks for taking this on.

[dennisYatunin]

After some offline discussion, it looks like everyone is in agreement that the docs are now usable. The are still a few unit tests I'd like to add, and also a lingering issue regarding unrolled_reduce(f, ::StaticOneTo) vs. unrolled_reduce(f, ::Val) that could be affecting compilation times in ClimaAtmos, but I will address these in a future PR.