No documentation examples for using "higher-order interactions"-related functions

[jacobusmmsmit]

Is your feature request related to a problem? Please describe.
As a game theory guy, my agents need to interact in groups, often pairwise. Currently it's not clear how to use the functions from the higher-order interactions section i.e. there are no examples in the docs of a model using it.

Particularly, it's not clear (to me) what can and can't be done with the passed function f, and it may be worth putting in another keyword to give f some arguments.

Describe the solution you'd like
Create a new docs example showcasing a very simple discrete time, nospace, evolutionary game theory model which makes use of map_agent_groups.

Describe alternatives you've considered
Perhaps we could put this in the model zoo, but given that it's documented functionality it would be nice to have an example of its use in the docs themselves.

[jacobusmmsmit]

When I read the docs and code for the functions in question, it seems rather that the functions I originally referred to do not do what I think they did.

In this case I would like to propose that we add functionality for users to give a pairwise_agent_step! or nwise_agent_step! function to run! or step! and a new keyword argument interaction_arity or interaction_order.

It would then look like this:

run!(game_theory_model, pairwise_step!, model_step!, steps; interaction_order = 2)

This would save users (see: me) from having to write custom higher order interaction code in their model_step! function.

One question that arises from this is that in almost all cases of higher-order interactions you would want the scheduler to be Schedulers.randomly so should it be the default in these cases? I believe it would make sense to make this the default if the interaction_order is greater than 1 and throw a warning if the scheduler is not explicitly set by the user that randomly is being used and how to change it if necessary.

I believe that the new functionality is a connected but distinct issue to the documentation part. If my understanding of the situation is correct, I think we should separate these issues and discuss them separately as, in any case, my original request for examples of using the Higher-order interactions functions remains.