Update to DynamicSumTypes 3

CHANGELOG.md

@@ -18,12 +18,7 @@ _We tried to deprecate every major change, resulting in practically no breakage
 - Every aspect of Agents.jl is orthogonal to `AgentBasedModel`: movement and neighbor searching in any space, data collection, visualizations, etc., are independent of the specific type of `AgentBasedModel` and work out of the box with any model.
 - Logic of when to collect data in `run!` has been improved to accommodate both discrete and continuous time models. This is reflected in the new options for the keyword `when`.
   - A new keyword `init` is now available for `run!` to data collect from the model before evolving it. Whether data were collected at time 0 or not was not really obvious in the original version of `run!` due to the ambiguity of the previous handling of `when`.
-- A new `@multiagent` macro allows to run multi-agent simulations much more efficiently. It has
-  two version: In `:opt_speed` the created agents are optimized such as there is virtually
-  no performance difference between having 1 agent type at the cost of each agent occupying
-  more memory that in the `Union` case. In `:opt_memory` each agent is optimized to occupy practically
-  the same memory as the `Union` case, however this comes at a cost of performance versus having 1 type.
-- `@multiagent` kinds support multiple dispatch like syntax with the `@dispatch` macro.
+- Integration with `DynamicSumTypes.@sumtype` macro allows to run multi-agent simulations much more efficiently.
 - A new experimental model type `EventQueueABM` has been implemented. It operates in continuous time through
   the scheduling of events at arbitrary time points, in contrast with the discrete time nature of a `StandardABM`.
 - Both the visualization and the model abstract interface have been refactored to improve the user

Project.toml

@@ -1,7 +1,7 @@
 name = "Agents"
 uuid = "46ada45e-f475-11e8-01d0-f70cc89e6671"
 authors = ["George Datseris", "Tim DuBois", "Aayush Sabharwal", "Ali Vahdati", "Adriano Meligrana"]
-version = "6.0.16"
+version = "6.1.0"
 
 [deps]
 CSV = "336ed68f-0bac-5ca0-87d4-7b16caf5d00b"
@@ -47,7 +47,7 @@ DataFrames = "0.21, 0.22, 1"
 DataStructures = "0.18"
 Distributed = "1"
 Distributions = "0.25"
-DynamicSumTypes = "2"
+DynamicSumTypes = "3"
 Downloads = "1"
 GraphMakie = "0.5"
 Graphs = "1.4"

docs/Project.toml

@@ -9,6 +9,7 @@ ColorTypes = "3da002f7-5984-5a60-b8a6-cbb66c0b333f"
 DataFrames = "a93c6f00-e57d-5684-b7b6-d8193f3e46c0"
 DiffEqCallbacks = "459566f4-90b8-5000-8ac3-15dfb0a30def"
 Distributions = "31c24e10-a181-5473-b8eb-7969acd0382f"
+DynamicSumTypes = "5fcdbb90-de43-509e-b9a6-c4d43f29cf26"
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
 DocumenterTools = "35a29f4d-8980-5a13-9543-d66fff28ecb8"
 DrWatson = "634d3b9d-ee7a-5ddf-bec9-22491ea816e1"

docs/src/api.md

@@ -31,11 +31,6 @@ AgentEvent
 ```@docs
 @agent
 AbstractAgent
-@multiagent
-kindof
-allkinds
-@dispatch
-@finalize_dispatch
 ```
 
 ### Minimal agent types

docs/src/index.md

@@ -16,7 +16,7 @@ using CairoMakie, Agents
     Please see the online [CHANGELOG](https://github.com/JuliaDynamics/Agents.jl/blob/main/CHANGELOG.md) for a full list of changes.
     The most noteworthy ones are:
 
-    - A new `@multiagent` macro allows to run multi-agent simulations much more efficiently.
+    - Integration with `DynamicSumTypes.@sumtype` allows to run multi-agent simulations much more efficiently.
     - A new experimental model type `EventQueueABM` has been implemented. It operates in continuous time through the scheduling of events at arbitrary time points. It is a generalization of "Gillespie-like" models.
     - `AgentBasedModel` defines an API that can be extended by other models.
     - Stronger inheritance capabilities in `@agent`.

docs/src/performance_tips.md

@@ -117,17 +117,14 @@ Specifically, you can represent this property as a standard Julia `Array` that i
 
 For an example of how this is done, see the [Forest fire](@ref) model, which is a cellular automaton that has no agents in it, or the [Daisyworld](@ref) model, which has both agents as well as a spatial property represented by an `Array`.
 
-## [Multiple agent types: `@multiagent` versus `Union` types](@id multi_vs_union)
+## [Multiple agent types: `@sumtype` versus `Union` types](@id sum_vs_union)
 
 Due to the way Julia's type system works, and the fact that agents are grouped in a container mapping IDs to agent instances, using a `Union` for different agent types always creates a performance hit because it leads to type instability.
-On the other hand, a `Union` of different types allows utilizing Julia's multiple dispatch system.
 
-The [`@multiagent`](@ref) macro does not make multiple types. It only makes one large type and defines convenience "constructors" on top of it, giving the illusion that multiple types exist. Therefore it completely eliminates type instability.
-[`@multiagent`](@ref) has two versions. In `:opt_speed` the created agents are optimized such as there is virtually no performance difference between having 1 agent type at the cost of each agent occupying more memory that in the `Union` case.
-In `:opt_memory` each agent is optimized to occupy practically the same memory as the `Union` case, however this comes at a cost of performance versus having 1 type.
+The [`@sumtype`](@ref) macro enclose all types in a single one making working with it type stable.
 
 In the following script, which you can find in `test/performance/variable_agent_types_simple_dynamics.jl`, we create a basic money-exchange ABM with many different agent types (up to 15), while having the simulation rules the same regardless of how many agent types are there.
-We then compare the performance of the three versions for multiple agent types, incrementally employing more agents from 2 to 15.
+We then compare the performance of the two versions for multiple agent types, incrementally employing more agents from 2 to 15.
 Here are the results of how much time it took to run each version:
 
 ```@example performance
@@ -138,5 +135,16 @@ include(t)
 ```
 
 We see that Unions of up to three different Agent types do not suffer much.
-Hence, if you have less than four agent types in your model, using different types is still a valid option and allows you to utilize multiple dispatch.
-For more agent types however we recommend using the [`@multiagent`](@ref) macro.
+Hence, if you have less than four agent types in your model, using different types is still a valid option.
+For more agent types however we recommend using the [`@sumtype`](@ref) macro.
+
+Finally, we also have a more realistic benchmark of the two approaches at `test/performance/sum_faster_than_multi.jl` where the
+result of running the model with the two methodologies are
+
+```@example performance_2
+using Agents
+x = pathof(Agents)
+t = joinpath(dirname(dirname(x)), "test", "performance", "sum_faster_than_multi.jl")
+include(t)
+```
+

docs/src/tutorial.jl

@@ -680,12 +680,11 @@ adf
 
 # In realistic modelling situations it is often the case the the ABM is composed
 # of different types of agents. Agents.jl supports two approaches for multi-agent ABMs.
-# The first uses the `Union` type, and the second
-# uses the [`@multiagent`](@ref) command. `@multiagent` is recommended
-# as default, because in many cases it will have performance advantages over the `Union` approach
-# without having tangible disadvantages. However, you should read through
-# the [comparison of the two approaches](@ref multi_vs_union) to
-# be better informed on which one to choose.
+# The first uses the `Union` type (this subsection), and the second uses the [`@sumtype`](@ref)
+# command (next subsection) available in [DynamicSumTypes.jl](https://github.com/JuliaDynamics/DynamicSumTypes.jl). 
+# This approach is recommended as default, because in many cases it will have performance advantages 
+# over the `Union` approach without having tangible disadvantages. However, we strongly recommend you 
+# to read through the [comparison of the two approaches](@ref sum_vs_union).
 
 # _Note that using multiple agent types is a possibility entirely orthogonal to
 # the type of `AgentBasedModel` or the type of space. Everything we describe here
@@ -695,7 +694,7 @@ adf
 
 # The simplest way to add more agent types is to make more of them with
 # [`@agent`](@ref) and then give a `Union` of agent types as the agent type when
-# making the `AgentBasedModel`. This is the most "native Julia" approach.
+# making the `AgentBasedModel`. 
 
 # For example, let's say that a new type of agent enters
 # the simulation; a politician that would "attract" a preferred demographic.
@@ -708,161 +707,87 @@ end
 # and, when making the model we would specify
 
 model = StandardABM(
-    Union{SchellingAgent, Politician}, # type of agents
+    Union{Schelling, Politician}, # type of agents
     space; # space they live in
 )
 
 # Naturally, we would have to define a new agent stepping function that would
 # act differently depending on the agent type. This could be done by making
 # a function that calls other functions depending on the type, such as
 
-function union_step!(agent, model)
-    if typeof(agent) <: AgentSchelling
-        schelling_step!(agent, model)
-    elseif typeof(agent) <: Politician
-        politician_step!(agent, model)
-    end
-end
-
-# and then passing
-
-model = StandardABM(
-    Union{SchellingAgent, Politician}, # type of agents
-    space; # space they live in
-    agent_step! = union_step!
-)
-
-# This approach also works with the [`@multiagent`](@ref) possibility we discuss below.
-# `Union` types however also offer the unique possibility of utilizing fully the Julia's
-# [multiple dispatch system](https://docs.julialang.org/en/v1/manual/methods/).
-# Hence, we can use the same function name and add dispatch to it, such as:
-
-function dispatch_step!(agent::SchellingAgent, model)
+function agent_step!(agent::Schelling, model)
     ## stuff.
 end
 
-function dispatch_step!(agent::Politician, model)
+function agent_step!(agent::Politician, model)
     ## other stuff.
 end
 
-# and give `dispatch_step!` to the `agent_step!` keyword during model creation.
-
-# ## Multiple agent types with `@multiagent`
-
-# [`@multiagent`](@ref) is a macro, and hence not "native Julia" syntax like `Union`,
-# however it has been designed to be as similar to [`@agent`](@ref) as possible.
-# The syntax to use it is like so:
-
-@multiagent struct MultiSchelling{X}(GridAgent{2})
-    @subagent struct Civilian # can't re-define existing `Schelling` name
-        mood::Bool = false
-        group::Int
-    end
-    @subagent struct Governor{X} # can't redefine existing `Politician` name
-        group::Int
-        influence::X
-    end
-end
-
-# This macro created three names into scope:
-
-(MultiSchelling, Civilian, Governor)
-
-# however, only one of these names is an actual Julia type:
-
-fieldnames(MultiSchelling)
-
-# that contains all fields of all subtypes without duplication, while
+# and then passing
 
-fieldnames(Civilian)
+model = StandardABM(
+    Union{Schelling, Politician}, # type of agents
+    space; # space they live in
+    agent_step!
+)
 
-# doesn't have any fields. Instead,
-# you should think of `Civilian` and `Governor` as just convenience functions that have been
-# defined for you to "behave like" types. That's why we call these **kinds** and not
-# **types**.
+# ## Multiple agent types with `@sumtype`
 
-# E.g., you can initialize
+# By using `@sumtype` from `DynamicSumTypes.jl` it is possible to improve the 
+# computational performance of simulations requiring multiple types, while almost
+# everything works the same 
 
-civ = Civilian(; id = 2, pos = (2, 2), group = 2) # default `mood`
+using DynamicSumTypes
 
-# or
+@sumtype MultiSchelling(Schelling, Politician) <: AbstractAgent
 
-gov = Governor(; id = 3 , pos = (2, 2), group = 2, influence = 0.5)
+# Now when you create instances you will need to enclose them in `MultiSchelling`
 
-# exactly as if these were types made with [`@agent`](@ref).
-# These are all of type `MultiSchelling`
+p = MultiSchelling(Politician(model; pos = random_position(model), preferred_demographic = 1))
 
-typeof(gov)
+# agents are then all of type `MultiSchelling`
 
-# and hence you can't use `typeof` to differentiate them. But you can use
+typeof(p)
 
-kindof(gov)
+# and hence you can't use only `typeof` to differentiate them. But you can use
 
-# instead.
+typeof(variant(p))
 
-# Since these kinds are not truly different Julia types, multiple dispatch cannot
-# be used to create different agent stepping functions for them.
-# The simplest "native Julia" solution here is to create a function where `if`
-# clauses decide what to do:
+# instead. Hence, the agent stepping function should become something like
 
-function multi_step!(agent, model)
-    if kindof(agent) == :Civilian
-        civilian_step!(agent, model)
-    elseif kindof(agent) == :Governor
-        politician_step!(agent, model)
-    end
-end
+agent_step!(agent, model) = agent_step!(agent, model, variant(agent))
 
-function civilian_step!(agent, model)
+function agent_step!(agent, model, ::Schelling)
     ## stuff.
 end
 
-function politician_step!(agent, model)
+function agent_step!(agent, model, ::Politician)
     ## other stuff.
 end
 
-# This however can be made to look much more like multiple dispatch with the
-# introduction of another macro, `@dispatch`:
-
-@dispatch function multi_step!(agent::Civilian, model)
-    ## stuff.
-end
-
-@dispatch function multi_step!(agent::Politician, model)
-    ## other stuff.
-end
-
-# This essentially reconstructs the version previously described with the `if`
-# clauses. In general you can use this macro with anything you would dispatch 
-# on, but this allows also kinds, unlike normal multiple dispatch, for example
-# this would also work:
-
-@dispatch function sub_multi_step!(k::Int, agent::Civilian)
-    ## some more stuff.
-end
-
-# After we defined the functions with `@dispatch` or the `if` clauses, we can create the model
+# and you need to give `MultiSchelling` as the type of agents in model initialization
 
 model = StandardABM(
-    MultiSchelling, # the multi-agent supertype is given as the type
+    MultiSchelling, # the sum type is given as the type
     space;
-    agent_step! = multi_step!
+    agent_step!
 )
 
 # ## Adding agents of different types to the model
 
-# Regardless of whether you went down the `Union` or `@multiagent` route,
+# Regardless of whether you went down the `Union` or `@sumtype` route,
 # the API of Agents.jl has been designed such that there is no difference in subsequent
-# usage. To add agents to a model, we use the existing [`add_agent_single!`](@ref)
-# command, but now specifying as a first argument the type of agent to add.
+# usage except when adding agents to a model, when doing that with `@sumtype` it is only
+# possible to use the existing [`add_agent!`](@ref) command adding an already defined 
+# agent.
 
 # For example, in the union case we provide the `Union` type when we create the model,
 
-model = StandardABM(Union{SchellingAgent, Politician}, space)
+model = StandardABM(Union{Schelling, Politician}, space)
 
 # we add them by specifying the type
 
-add_agent_single!(SchellingAgent, model; group = 1, mood = true)
+add_agent_single!(Schelling, model; group = 1, mood = true)
 
 # or
 
@@ -872,17 +797,19 @@ add_agent_single!(Politician, model; preferred_demographic = 1)
 
 collect(allagents(model))
 
-# For the `@multiagent` case, there is really no difference. We have
+# For the `@sumtype` case instead
 
 model = StandardABM(MultiSchelling, space)
 
-# we add
+# we add agents like so
 
-add_agent_single!(Civilian, model; group = 1)
+agent = MultiSchelling(Schelling(model; pos = random_position(model), group = 1, mood = true))
+add_agent_single!(agent, model)
 
 # or
 
-add_agent_single!(Governor, model; influence = 0.5, group = 1)
+agent = MultiSchelling(Politician(model; pos = random_position(model), preferred_demographic = 1))
+add_agent_single!(agent, model)
 
 # and we see