Agents.jl v6 + releases announcement post

Package Announcements
,
1

Hi everyone,

we are happy to announce v6 of Agents.jl. This could well be the most major-est of Agents.jl major changes. We also hope that this will be last major increment of Agents.jl version, or at least, the last one in the foreseeable future.

We will also be using this Discourse post to post further useful update messages for Agents.jl, so feel free to subscribe here for future updates (we are stopping the REPL messages!).

This new release futures a true plethora of improvements, bugfixes, performance enhancements, and more, a summary of which you can find in the changelog. In this post I will only summarize the most noteworthy features!

Major player in making this release possible is @Tortar who contributed lot’s of new features and performance improvements! Thanks @Tortar!

AgentBasedModel API

Agents.jl now defines a standard interface for what quantifies as an “agent based model” (ABM). Other developers may hook up into the interface to create new model types. A model type only governs how the time evolution of the ABM takes place. Hence, the time evolution “functions” (the stepping functions) are now part of the model struct, and are not given as arguments to step!. This change was made to 1) be more harmonious with the rest of dynamic modelling packages of Julia such as DifferentialEquations.jl or DynamicalSystems.jl (in fact, the AgentBasedModel API was designed to be nearly identical to the DynamicalSystem API). But also 2) to orthogonalize the time evolution with all other Agents.jl features, such as e.g., data collection or movement of agents in a space or searching for nearby agents, etc. Hence, all of these orthogonal features can be used out of the box for a new type of agent based model.

This is particularly useful for developers of other agent based models such as Vanaha.jl (@sfuerst) or CellBasedModels.jl (@gatocor). We believe that it is possible now to integrate these packages directly with the rest of Agents.jl (should the developers wish so), taking advantage of performance enhancements that have been put in place over the years in Agents.jl for e.g., filtering or neighborhood searches, or taking advantage of the flexible Agents.jl data collection, or the existing plotting and GUI infrastructure (all of these things are orthogonal to the AgentBasedModel API).

Generic event queue ABM

To test drive this new API we developed a completely different ABM than the “standard” one that has been the only option in Agents.jl in all previous versions. This new “event queue” ABM operates in continuous time, in contrast to the “standard” ABM that operates in discrete time (or steps).

The event queue ABM is similar to what most people think as “Gillespie ABM”
but much more general. We considered several options for the backend of this
model, such as JumpProcesses.jl or other similar packages, but in the end
we decided to opt for generality of modelling possibilities and implemented
a simple event queue system, where events representing possible agent actions
are pushed into a continuous time queue and triggered when their time comes.

Currently the exact configuration for this event queue abm is in experimental status. We want to first see how the users interact with it to finalize its interface in the next minor release 6.1.

Multi-agent models: incredible inheritance logic and 0 performance downside

Arguably the strongest enhancement of existing features is at multi-agent
models which have multiple different types of agents.
Two highlights there are:

  1. The @agent macro now has incredible “inheritance” logic parallelizing
    as much as possible object oriented inheritance when creating custom
    structs representing user-defined agent types. The macro supports
    all features of Julia’s native struct definition. It supports inheritance
    from another type, and subtyping of any supertype.
  2. The new @multiagent macro allows defining multiple agent “types”.
    These are not true individual Julia structs, but instead “shadow” a
    single Julia struct. Yet, from the user’s side, they look identical to
    how one would handle multi different structs. These “shadow types”
    have 0 performance drops versus using a single agent type (in their
    most optimal performance configuration). This is absolutely major,
    as type instability was the main performance
    hit we had at multi-agent models. The new comparison of performance differences
    in multi-agent models can be found in the new docs.

Brand new Tutorial and updated documentation

To reflect the new features such as different types of ABMs or the new handling of multi-agent models we have fully revamped the tutorial and re-written it almost from scratch! We believe the new tutorial makes a better job of guiding a newcomer through all major Agents.jl features. The rest of the documentation has also been updated accordingly to reflect v6.

For more see the changelog!

39 Likes
This month in Julia world - 2024-03
2

It was a pleasure to help to build some more infrastructure for agent based modelling. I started to use Julia one year ago and one of the reasons why I started to contribute to Agents.jl was to help myself to learn the language…then I become addicted to improve things here and there :smile:

Really hope the functionalities we developed for this new version will be helpful for people using Agents.jl!

22 Likes
3

Just want to say this release looks great, thanks all, and great job with the docs, it’s a pleasure to read!

5 Likes
4

Yes, indeed, a big thank you to @Tortar for all the work. It’s much appreciated!

On a related note, this release also brings a rework of the internals of Agents.jl visualisations. For most users this won’t be noticeable because I tried to keep the necessary changes in line with the previous approach to visualising ABMs. As such, the documentation for plotting static and interactive ABMs hasn’t changed much, see here.

However, the internal changes were necessary to create a more easily approachable API for ABM developers who want to plot their models with custom spaces or who want to change the default plotting behaviour.[1] Agents.jl visualisations now heavily rely on multiple dispatch and by that became more modifiable without having to delve all too deep into the existing code base. Have a look at this section in the developer docs for some more information on what’s possible now. Have fun plotting your ABMs and if you feel anything is missing here, please get in touch. :slight_smile:

  1. Please note that I would still consider this API experimental and subject to change. We’ve tested it with examples from AgentsExampleZoo.jl as well as some custom spaces and are relatively confident that it should cover the most important cases. If you find something that doesn’t work or isn’t clear to you, shoot us a message and we will try to sort things out. ↩︎

5 Likes
5

Indeed, @fbanning 's plotting re-work was a big step that enabled the AgentBasedModel to be orthogonal to plotting, hence allowing completely new model types to be able to hook up to the plotting interface easily.

6

Hi all. I’m really enjoying working with Agents.jl, and have just updated my model to v6. Thanks for all your efforts!

I have a question about scheduling multiagent models. I used to use Schedulers.ByType, is there an equivalent for models with the @multiagent macro? Should I use Schedulers.ByProperty with a function that checks the kindof for each agent? Thanks!

3 Likes
7

yes! In fact, under the hood ByType is ByProperty with typeof function. However in the future we will add a convenience function for it as well.

1 Like
8

Hello, I am totally new to agents.jl, and I was looking to the Shelling Segregation Model example (that I propose to students in manually-coded way here and I wanted to show them the “ok, now you can use an ABM framework” way).

However that specific example has been removed in the Agents v6 version… would it be possible to port it to v6… it is pretty basic, so I assume it shoudn’t be too complex…

9

Hi,

please do not use this thread to ask Agents.jl questions. This thread is for posting update messages for Agents.jl so that people may follow it without getting notifications for other things. Instead, ask a question by opening a new discourse post.

The Schelling example is now the main tutorial, it has not been removed: Tutorial · Agents.jl

1 Like
10

Hi everyone,

Agents.jl v6.1 is out! The @multiagent macro that was newly introduced has been overhauled. We’re sorry for this change when the previous version was so recently released, as both syntax and usage of @multiagent are different now. However, the new version is truly better as it allows re-using existing agent types! It culminated from @Tortar 's work on DynamicSumTypes.jl v3, which by itself has generated a lot of traction! Please have a look at the updated tutorial!

The experimental EventQueueABM now also is based on typeof! kindof and similar functions have been removed!!! (deprecated)

(and remember, you can “subscribe” to this post to receive notifications for new Agents.jl releases! So please don’t reply to this post but rather open new discussions to keep this post “announcement-only”! Thank you very much!)

8 Likes
11

Hello I am sharing this here as people who follow new releases of Agents.jl would likely be interested in this talk:

(go to the Discourse thread there to find the online meeting link)

1 Like
12

Hello, Agents.jl v7 has now been released (pending registration). Although it sounds like a lot of breakage (v6 → v7) almost nothing is actually breaking for the every day user! I am copying here parts of the changelog:

New features

This new version brings two powerful, but both experimental features:

  1. Allowing the agent container to be based on StructVectors, using a Struct-of-Arrays internal layout. Currently it only supports single agent types. To use this, pass container = StructVector to StandardABM or EventQueueABM constructors, as well as use the helper construct SoAType{A} for dispatch purposes instead of your agent type A (read the docstring of SoAType).
  2. Native integration of ABMs with Reinforcement Learning is now provided by the new model type ReinforcementLearningABM. To learn how to use this functionality checkout the new tutorial on the Boltzmann Wealth Model with Reinforcement Learning.

These two features are labelled experimental because they did not yet undergo extensive testing by a broader pool of users. As versions progress and bug reports come in, and get solved, the features will mature to fully stable.

The experimental status allows us as developers to make breaking changes, if need be, to either feature, in order to fully stabilize them.

Breaking changes

This new version also brings some breaking changes that we believe will not affect
typical usage of Agents.jl:

  1. All deprecations existing in Agents.jl v6 have been removed. Use version v6.2 if you are not comfortable with this.
  2. All plotting related source code has been completely overhauled.
    • An unfortunate consequence is that Data inspection (hovering over a plot in GLMakie and getting a pop-up) is currently unavailable, and we welcome PRs to enable again data inspection in the new plotting code which plots directly on Axis/Axis3.
  3. The OpenStreetMapSpace is now not available immediately after using Agents.
    • It is now a package extension. You need to be doing using LightOSM to access it.
    • Now all functionality that is exclusive to OSM is behind the OSM module, with the exception of the core types OpenStreetMapSpace, OpenStreetMapPath, OSMAgent. Thus you must now do OSM.is_stationary, OSM.plan_route!, etc.
  4. The functions plan_route!, plan_best_route!, move_along_route! are no longer top-level Agents functions. You have to preface the with either OSM. or Pathfinding. to use them in their respective submodule. Or do using Agents.OSM/Agents.Pathfinding respectively to bring the functions into scope.
  5. ByKind scheduler removed, which should have happened already in v6.1, but was forgotten.
2 Likes
13

And with this I’d also like to announce that Agents.jl is searching for maintainers. I am unfortunately no longer in a position to keep up with maintaing Agents.jl fully due to increasing responsibilities in work and personal life and the neverending expansion of DynamicalSystems.jl. Thus, I am stepping down from this role for now. I am still happy to commit ~one hour per month to Agents.jl, answering questions on Discourse and/or mentoring new contrbutors that would like to take the lead in maintaining Agents.jl.

At the moment there is noone else in the list of active maintainers, and having around some people that are happy to contribute somewhat regularly by answering questions, reviewing PRs, fixing bugs, or contributing functionality would be fantastic.
Previous people that have meaningful contributed to Agents.jl and were mentored in the meantime had lead on to a promising career in reesarch/simulation software, e.g., Aayush Subwarhal is now a software engineer in JuliaHub while Andriano Meligrana was offered a PhD in computational social sciences (with ABMs) and has now move to be a contributor for the recent Ark.jl project. This is just me selling the “Agents.jl maintainer job” as something that will provide you with valuable skills and experience also for your future career.

I have been spending lots of my time the last month updating the dependencies of Agents.jl, revamping components of the library to be simpler, and making sure all tests/docs pass wonderfully, to set the stage for the next person. If someone wants to take over best to reach out in the Julia Slack or simply have a look at this issue: Reform tests according to Good Scientific Code practices · Issue #634 · JuliaDynamics/Agents.jl · GitHub . Modernizing the test suite is a great way to obtain familiarity with the current capabilities of Agents.jl.

6 Likes