Clarify the use multiline @tullio

[Emmanuel-R8]

In the README, looking at the following snippet:

@tullio out[x, y] := @inbounds(begin  # sum over k
        a,b = off[k]
        mat[mod(x+a), mod(y+b)]
    end) (x in axes(mat,1), y in axes(mat,2)) grad=Dual nograd=off

I struggled in my code until I made sure that:

• The first := after out[x, y] can either be := or = as described above the snippet.
• However, within the begin ... end, only = can be used. This is not mentioned anywhere.

I wanted to change that with a PR. But I want to confirm first.

Is that correct?

[mcabbott]

Sorry this package really needs a manual, but I got busy.

@tullio out[x, y] = right evaluates right and writes into out, possibly summing. @tullio out[x, y] := right makes a new array. The macro completely rewrites how this looks.

But what appears within the expression on the right isn't processed much, and at some point I allowed it to take an arbitrary block of code. The code is read (to figure out what indices appear, etc.) but evaluated as it stands. So = has no special meaning, it's just a normal block of code, and the last statement is its value, as usual.

The option verbose=2 will print everything, and the main loop here looks like this:

│                    for y = 𝒶𝓍y
│                        for x = 𝒶𝓍x
│                            𝒜𝒸𝒸 = if ♻️ === nothing
│                                    zero(𝒯)
│                                else
│                                    ℛ[x, y]   # this is part of how it handles memory blocking, allows a re-start
│                                end
│                            for k = 𝒶𝓍k  # this is the sum loop
│                                𝒜𝒸𝒸 = 𝒜𝒸𝒸 + @inbounds(begin  # this is the block of code provided, untouched
│                                                (a, b) = off[k] 
│                                                mat[mod(x + a), mod(y + b)]
│                                            end)
│                            end
│                            ℛ[x, y] = 𝒜𝒸𝒸  # writing into an output array, created outside this function
│                        end
│                    end