Introduction · Agents.jl

Agents — Module

Agents.jl

Agents.jl is a pure Julia framework for agent-based modeling (ABM): a computational simulation methodology where autonomous agents react to their environment (including other agents) given a predefined set of rules. Some major highlights of Agents.jl are:

It is fast (faster than MASON, NetLogo, or Mesa)
It is simple: has a very short learning curve and requires writing minimal code
Has an extensive interface of thousands of out-of-the box possible agent actions
Straightforwardly allows simulations on Open Street Maps

The simplicity of Agents.jl is due to the intuitive space-agnostic modelling approach we have implemented: agent actions are specified using generically named functions (such as "move agent" or "find nearby agents") that do not depend on the actual space the agents exist in, nor on the properties of the agents themselves. Overall this leads to ultra fast model prototyping where even changing the space the agents live in is matter of only a couple of lines of code.

More information and an extensive list of features can be found in the documentation, which you can either find online or build locally by running the docs/make.jl file.

Citation

If you use this package in a publication, or simply want to refer to it, please cite the paper below:

@article{Agents.jl,
  doi = {10.1177/00375497211068820},
  url = {https://doi.org/10.1177/00375497211068820},
  year = {2022},
  month = jan,
  publisher = {{SAGE} Publications},
  pages = {003754972110688},
  author = {George Datseris and Ali R. Vahdati and Timothy C. DuBois},
  title = {Agents.jl: a performant and feature-full agent-based modeling software of minimal code complexity},
  journal = {{SIMULATION}},
  volume = {0},
  number = {0},
}

source

Star us on GitHub!

If you have found this package useful, please consider starring it on GitHub. This gives us an accurate lower bound of the (satisfied) user count.

Highlights

Software quality

Free and open source.
Small learning curve due to intuitive design based on a modular space-agnostic function-based modelling implementation.
Extremely high performance when compared to other open source frameworks, routinely being 100x faster versus other ABM frameworks (proof)
User-created models typically have much smaller source code versus implementations in other open source ABM frameworks (proof)
High quality, extensive documentation featuring tutorials, example ABM implementations, an extra zoo of ABM examples, and integration examples with other Julia packages

Agent based modelling

Universal model structure where agents are identified by a unique id: AgentBasedModel.
Extendable API that provides out of the box thousands of possible agent actions.
Support for many types of space: arbitrary graphs, regular grids, continuous space
Support for simulations on Open Street Maps including support for utilizing the road's max speed limit, finding nearby agents/roads/destinations and pathfinding
Multi-agent support, for interactions between disparate agent species
Scheduler interface (with default schedulers), making it easy to activate agents in a specific order (e.g. by the value of some property)
Automatic data collection in a DataFrame at desired intervals
Aggregating collected data during model evolution
Distributed computing
Batch running and batch data collection
Extensive pathfinding capabilities in continuous or discrete spaces
Customizable visualization support for all kinds of models via the Makie ecosystem: publication-quality graphics and video output
Interactive applications for any agent based models, which are created with only 5 lines of code and look like this:

Getting started

To install Agents.jl, launch Julia and then run this command:

using Pkg; Pkg.add("Agents")

To learn how to use Agents.jl, please visit the Tutorial before anything else.

Design philosophy of Agents.jl

Agents.jl was designed with the following philosophy in mind:

Simple to learn and use, yet extendable, focusing on fast and scalable model creation and evolution.

(it should be said nevertheless, that when we have to make a choice between a simpler API or a more performant implementation, we tend to lean in favor of simplicity)

There are multiple examples that highlight this core design principle, that one will quickly encounter when scanning through our API page. Here we just give two quick examples: first, there exists a universal function nearby_agents, which returns the agents nearby a given agent and within a given "radius". What is special for this function, which is allowed by Julia's Multiple Dispatch, is that nearby_agents will work for any space type the model has, reducing the learning curve of finding neighbors in ABMs made with Agents.jl. An even better example is perhaps our treatment of spaces. A user may create an entirely new kind of space (e.g. one representing a planet, or whatever else) by only extending 5 functions, as discussed in our Creating a new space type documentation.

Many other agent-based modeling frameworks have been constructed to ease the process of building and analyzing ABMs (see e.g. here for an outdated review), spanning a varying degree of complexity. In the page ABM Framework Comparison we compare how our design philosophy puts us into comparison with other well accepted ABM software. Fascinatingly, even though the main focus of Agents.jl is simplicity and ease of use, it outperforms all software we compared it with.

Crash course on agent based modeling

An agent-based (or individual-based) model is a computational simulation of autonomous agents that react to their environment (including other agents) given a predefined set of rules [1]. ABMs have been adopted and studied in a variety of research disciplines. One reason for their popularity is that they enable a relaxation of many simplifying assumptions usually made by mathematical models. Relaxing such assumptions of a "perfect world" can change a model's behavior [2].

Agent-based models are increasingly recognized as a useful approach for studying complex systems [3,4,5,6]. Complex systems cannot be fully understood using traditional mathematical tools which aggregate the behavior of elements in a system. The behavior of a complex system depends on both the behavior of and interactions between its elements (agents). Small changes in the input to complex systems or the behavior of its agents can lead to large changes in outcome. That is to say, a complex system's behavior is nonlinear, and that it is not only the sum of the behavior of its elements. Use of ABMs have become feasible after the availability of computers and has been growing ever since, especially in modeling biological and economic systems, and has extended to social studies and archaeology.

An ABM consists of autonomous agents that behave given a set of rules. A classic example of an ABM is Schelling's segregation model, which we implement as an example here. This model uses a regular grid and defines agents at random positions on the grid. Agents can be from different social groups. Agents are happy/unhappy based on the fraction of their neighbors that belong to the same group as they are. If they are unhappy, they keep moving to new locations until they are happy. Schelling's model shows that even small preferences of agents to have neighbors belonging to the same group (e.g. preferring that at least 30% of neighbors to be in the same group) could lead to total segregation of neighborhoods. This is an example of emergent behavior from simple interactions of agents that can only be captured in an agent-based model.

Getting help

You're looking for support for Agents.jl? Look no further! Here's some things you can do to resolve your questions about Agents.jl:

Read the online documentation! It is likely that the thing you want to know is already documented, so use the search bar and search away!
Chat with us in the channel #dynamics-bridged in the Julia Slack!
Post a question in the Julia discourse in the category “Modelling and simulations”, using “agent” as a tag!
If you believe that you have encountered unexpected behavior or a bug in Agents.jl, then please do open an issue on our GitHub page providing a minimal working example!

Contributing

Any contribution to Agents.jl is welcome! For example you can:

Add new feature or improve an existing one (plenty to choose from the "Issues" page)
Improve the existing documentation
Add new example ABMs into our existing pool of examples
Report bugs and suggestions in the Issues page

Have a look at contributor's guide of the SciML organization for some good information on contributing to Julia packages!

Citation

If you use this package in work that leads to a publication, then please cite the paper below:

@article{Agents.jl,
  doi = {10.1177/00375497211068820},
  url = {https://doi.org/10.1177/00375497211068820},
  year = {2022},
  month = jan,
  publisher = {{SAGE} Publications},
  pages = {003754972110688},
  author = {George Datseris and Ali R. Vahdati and Timothy C. DuBois},
  title = {Agents.jl: a performant and feature-full agent-based modeling software of minimal code complexity},
  journal = {{SIMULATION}},
  volume = {0},
  number = {0},
}