Implement multiagent macro

[Tortar]

Fixes #947

Because I'm a bit crazy I've already implemented it :D

(Notice that the more complicated example in #947 works and also the rabbit_fox_hawk example I modified)

[Tortar]

Now even this more complicated compactification works

@compact struct Animal{T,N,J}(GridAgent{2})
    @agent struct Wolf{T,N}
        energy::T = 0.5
        ground_speed::N
        const fur_color::Symbol
    end
    @agent struct Hawk{T,N,J}
        energy::T = 0.1
        ground_speed::N
        flight_speed::J
    end
end

[Tortar]

Seems kind of fine to me!!

[Datseris]

This is fantastic!!! I assume you have tested it locally and tests passs, and we have the same roblem as with the other PR?

Should we rename the @compact to @multiagent? The front-end user doesn't really need to care about what the implementation detail does (compactifies), they only care that they get a multi-agent or mixed-agent model.

[Tortar]

Hi George, should be okay now if you want to take a look

[Tortar]

I updated the performance tips, I don't anymore mention the problem with working many types, I think our macro is good enough for many use cases already.

However, I don't consider the problem totally solved, and I consider #841 and its variations worth exploring.

E.g. our macro falls short when the types have a memory footprint very different from one another, because when we use the memory efficient version we are actually occupying anyway the memory of the agent with highest memory footprint (instead of the sum of their footprints which happens with :opt_speed) which can be sometimes too much anyway

[Datseris]

great, I will review this on the weekend!

[Datseris]

Okay I will review this now and tomorrow. If you are around, any chance I can get a summary of this PR in a comment here?

[Datseris]

all tests fail, I guess this is the "known" problem and everything passes locally?

[Tortar]

In practice I implemented the multiagent macro where I also give to the user the possibility to choose between a more optimized version for speed or for memory by passing :opt_speed or :opt_memory as the first argument of the macro, by default it optimizes speed. Then I extended internals when needed, and I edited the branching_faster_than_dispatch.jl file so that to see how the two versions perform, you can find the results at the end of the file.

all tests fail, I guess this is the "known" problem and everything passes locally?

exactly, also strangely when we merge tests pass instead

[Datseris]

@Tortar can you remind me what is the performance comparison of this method and the standard Union method that we used before? How much faster this is here? There was some benchmarks somewhere , right?

[Tortar]

Yes, I updated two benchmarks in this PR, I described the results for variable_agent_types_simple_dynamics.jl in the other review comment, for the results of the other, see the bottom of branching_faster_than_dispatch.jl

[Datseris]

right, the first file does not have any comments with the results, but from the second one

Agents.jl/test/performance/branching_faster_than_dispatch.jl

Lines 190 to 193 in f750aef

	# Results:
	# multiple types: 3.732 s (39242250 allocations: 2.45 GiB)
	# @multiagent :opt_speed: 577.185 ms (25818000 allocations: 1.05 GiB)
	# @multiagent :opt_memory: 870.460 ms (25868000 allocations: 1.05 GiB)

it appears that performance is up to 7x which is fantastic.

[Datseris]

i'll merge this in when you adress the comments for the performance tips documentation. then i'll work on a re-worked tutorial and docs.

[Tortar]

Docs updated!

[Datseris]

right, i am merging this in, the plotting PR whcih is the last blocker left I think

[Datseris]

oh, btw, what impliciations does this have for the Event queue abm? does it make it much faster as well? I Guess we should have a specialization there if there are no different agent types?