Tutorial

@agent YourAgentType{X} AnotherAgentType [OptionalSupertype] begin
    extra_property::X
    other_extra_property::Int
    # etc...
end

Define an agent struct which includes all fields that AnotherAgentType has, as well as any additional ones the user may provide via the begin block. See below for examples.

Using @agent is the recommended way to create agent types for Agents.jl, however keep in mind that the macro (currently) doesn't work with Base.@kwdef or const declarations in individual fields (for Julia v1.8+).

Structs created with @agent by default subtype AbstractAgent. They cannot subtype each other, as all structs created from @agent are concrete types and AnotherAgentType itself is also concrete (only concrete types have fields). If you want YourAgentType to subtype something other than AbstractAgent, use the optional argument OptionalSupertype (which itself must then subtype AbstractAgent).

Usage

The macro @agent has two primary uses:

1. To include the mandatory fields for a particular space in your agent struct. In this case you would use one of the minimal agent types as AnotherAgentType.
2. A convenient way to include fields from another, already existing struct.

The existing minimal agent types are:

• NoSpaceAgent
• GraphAgent
• GridAgent
• ContinuousAgent
• OSMAgent

All will attribute an id::Int field, and besides NoSpaceAgent will also attribute a pos field. You should never directly manipulate the mandatory fields id, pos that the resulting new agent type will have. The id is an unchangeable field. Use functions like move_agent! etc., to change the position.

Examples

Example without optional hierarchy

Using

@agent Person{T} GridAgent{2} begin
    age::Int
    moneyz::T
end

will create an agent appropriate for using with 2-dimensional GridSpace

mutable struct Person{T} <: AbstractAgent
    id::Int
    pos::NTuple{2, Int}
    age::Int
    moneyz::T
end

and then, one can even do

@agent Baker{T} Person{T} begin
    breadz_per_day::T
end

which would make

mutable struct Baker{T} <: AbstractAgent
    id::Int
    pos::NTuple{2, Int}
    age::Int
    moneyz::T
    breadz_per_day::T
end

Example with optional hierarchy

An alternative way to make the above structs, that also establishes a user-specific subtyping hierarchy would be to do:

abstract type AbstractHuman <: AbstractAgent end

@agent Worker GridAgent{2} AbstractHuman begin
    age::Int
    moneyz::Float64
end

@agent Fisher Worker AbstractHuman begin
    fish_per_day::Float64
end

which would now make both Fisher and Worker subtypes of AbstractHuman.

julia> supertypes(Fisher)
(Fisher, AbstractHuman, AbstractAgent, Any)

julia> supertypes(Worker)
(Worker, AbstractHuman, AbstractAgent, Any)

Note that Fisher will not be a subtype of Worker although Fisher has inherited the fields from Worker.

Example highlighting problems with parametric types

Notice that in Julia parametric types are union types. Hence, the following cannot be used:

@agent Dummy{T} GridAgent{2} begin
    moneyz::T
end

@agent Fisherino{T} Dummy{T} begin
    fish_per_day::T
end

You will get an error in the definition of Fisherino, because the fields of Dummy{T} cannot be obtained, because it is a union type. Same with using Dummy. You can only use Dummy{Float64}.

Example with common dispatch and no subtyping

It may be that you do not even need to create a subtyping relation if you want to utilize multiple dispatch. Consider the example:

@agent CommonTraits GridSpace{2} begin
    age::Int
    speed::Int
    energy::Int
end

and then two more structs are made from these traits:

@agent Bird CommonTraits begin
    height::Float64
end

@agent Rabbit CommonTraits begin
    underground::Bool
end

If you wanted a function that dispatches to both Rabbit, Bird, you only have to define:

Animal = Union{Bird, Rabbit}
f(x::Animal) = ... # uses `CommonTraits` fields

However, it should also be said, that there is no real reason here to explicitly type-annotate x::Animal in f. Don't annotate any type. Annotating a type only becomes useful if there are at least two "abstract" groups, like Animal, Person. Then it would make sense to define

Person = Union{Fisher, Baker}
f(x::Animal) = ... # uses `CommonTraits` fields
f(x::Person) = ... # uses fields that all "persons" have

YourAgentType <: AbstractAgent

Agents participating in Agents.jl simulations are instances of user-defined Types that are subtypes of AbstractAgent.

Your agent type(s) must have the id::Int field as first field. If any space is used (see Available spaces), a pos field of appropriate type is also mandatory. The core model structure, and each space, may also require additional fields that may, or may not, be communicated as part of the public API.

The @agent macro ensures that all of these constrains are in place and hence it is the recommended way to generate new agent types.

AgentBasedModel

An AgentBasedModel is the supertype encompassing models in Agents.jl. All models are some concrete implementation of AgentBasedModel and follow its interface (see below). ABM is an alias to AgentBasedModel.

A model is typically constructed with:

AgentBasedModel(AgentType [, space]; properties, kwargs...) → model

which creates a model expecting agents of type AgentType living in the given space. AgentBasedModel(...) defaults to StandardABM, which stores agents in a dictionary that maps unique IDs (integers) to agents. See also UnremovableABM for better performance in case number of agents can only increase during the model evolution.

Agents.jl supports multiple agent types by passing a Union of agent types as AgentType. However, please have a look at Performance Tips for potential drawbacks of this approach.

space is a subtype of AbstractSpace, see Space for all available spaces. If it is omitted then all agents are virtually in one position and there is no spatial structure. Spaces are mutable objects and are not designed to be shared between models. Create a fresh instance of a space with the same properties if you need to do this.

Keywords

• properties = nothing: additional model-level properties that the user may decide upon and include in the model. properties can be an arbitrary container of data, however it is most typically a Dict with Symbol keys, or a composite type (struct).
• scheduler = Schedulers.fastest: is the scheduler that decides the (default) activation order of the agents. See the scheduler API for more options.
• rng = Random.default_rng(): the random number generation stored and used by the model in all calls to random functions. Accepts any subtype of AbstractRNG.
• warn=true: some type tests for AgentType are done, and by default warnings are thrown when appropriate.

Interface of AgentBasedModel

Here we the most important information on how to query an instance of AgentBasedModel:

• model[id] gives the agent with given id.
• abmproperties(model) gives the properies container stored in the model.
• model.property: If the model properties is a dictionary with key type Symbol, or if it is a composite type (struct), then the syntax model.property will return the model property with key :property.
• abmrng(model) will return the random number generator of the model. It is strongly recommended to use abmrng(model) to all calls to rand and similar functions, so that reproducibility can be established in your modelling workflow.
• abmscheduler(model) will return the default scheduler of the model.

Many more functions exist in the API page, such as allagents.

step!(model::ABM, agent_step!, n::Int = 1)
step!(model::ABM, agent_step!, model_step!, n::Int = 1, agents_first::Bool = true)

Update agents n steps according to the stepping function agent_step!. Agents will be activated as specified by the model.scheduler. model_step! is triggered after every scheduled agent has acted, unless the argument agents_first is false (which then first calls model_step! and then activates the agents).

step! ignores scheduled IDs that do not exist within the model, allowing you to safely remove agents dynamically.

step!(model, agent_step!, model_step!, n::Function, agents_first::Bool = true)

In this version n is a function. Then step! runs the model until n(model, s) returns true, where s is the current amount of steps taken, starting from 0. For this method of step!, model_step! must be provided always (use dummystep if you have no model stepping dynamics).

See also Advanced stepping for stepping complex models where agent_step! might not be convenient.

dummystep(model)

Use instead of model_step! in step! if no function is useful to be defined.

dummystep(agent, model)

Use instead of agent_step! in step! if no function is useful to be defined.

run!(model, agent_step! [, model_step!], n::Integer; kwargs...) → agent_df, model_df
run!(model, agent_step!, model_step!, n::Function; kwargs...) → agent_df, model_df

Run the model (step it with the input arguments propagated into step!) and collect data specified by the keywords, explained one by one below. Return the data as two DataFrames, one for agent-level data and one for model-level data.

See also offline_run! to write data to file while running the model.

Data-deciding keywords

• adata::Vector means "agent data to collect". If an entry is a Symbol, e.g. :weight, then the data for this entry is agent's field weight. If an entry is a Function, e.g. f, then the data for this entry is just f(a) for each agent a. The resulting dataframe columns are named with the input symbol (here :weight, :f).

• adata::Vector{<:Tuple}: if adata is a vector of tuples instead, data aggregation is done over the agent properties.

  For each 2-tuple, the first entry is the "key" (any entry like the ones mentioned above, e.g. :weight, f). The second entry is an aggregating function that aggregates the key, e.g. mean, maximum. So, continuing from the above example, we would have adata = [(:weight, mean), (f, maximum)].

  It's also possible to provide a 3-tuple, with the third entry being a conditional function (returning a Bool), which assesses if each agent should be included in the aggregate. For example: x_pos(a) = a.pos[1]>5 with (:weight, mean, x_pos) will result in the average weight of agents conditional on their x-position being greater than 5.

  The resulting data name columns use the function dataname. They create something like :mean_weight or :maximum_f_x_pos. In addition, you can use anonymous functions in a list comprehension to assign elements of an array into different columns: adata = [(a)->(a.interesting_array[i]) for i=1:N]. Column names can also be renamed with DataFrames.rename! after data is collected.

  Notice: Aggregating only works if there are agents to be aggregated over. If you remove agents during model run, you should modify the aggregating functions. E.g. instead of passing mean, pass mymean(a) = isempty(a) ? 0.0 : mean(a).

• mdata::Vector means "model data to collect" and works exactly like adata. For the model, no aggregation is possible (nothing to aggregate over).

  Alternatively, mdata can also be a function. This is a "generator" function, that accepts model as input and provides a Vector that represents mdata. Useful in combination with an ensemblerun! call that requires a generator function.

By default both keywords are nothing, i.e. nothing is collected/aggregated.

Mixed-Models

For mixed-models, the adata keyword has some additional options & properties. An additional column agent_type will be placed in the output dataframe.

In the case that data is needed for one agent type that does not exist in a second agent type, missing values will be added to the dataframe.

Warning: Since this option is inherently type unstable, try to avoid this in a performance critical situation.

Aggregate functions will fail if missing values are not handled explicitly. If a1.weight but a2 (type: Agent2) has no weight, use a2(a) = a isa Agent2; adata = [(:weight, sum, a2)] to filter out the missing results.

Other keywords

• when=true : at which steps s to perform the data collection and processing. A lot of flexibility is offered based on the type of when. If when::AbstractVector, then data are collected if s ∈ when. Otherwise data are collected if when(model, s) returns true. By default data are collected in every step.
• when_model = when : same as when but for model data.
• obtainer = identity : method to transfer collected data to the DataFrame. Typically only change this to copy if some data are mutable containers (e.g. Vector) which change during evolution, or deepcopy if some data are nested mutable containers. Both of these options have performance penalties.
• agents_first=true : Whether to update agents first and then the model, or vice versa.
• showprogress=false : Whether to show progress