Mango.jl

Mango.jl: A Julia-Based Multi-Agent Simulation Framework - Published in JOSS (2024)

https://github.com/offis-dai/mango.jl

Science Score: 100.0%

This score indicates how likely this project is to be science-related based on various indicators:

✓
CITATION.cff file
Found CITATION.cff file
✓
codemeta.json file
Found codemeta.json file
✓
.zenodo.json file
Found .zenodo.json file
✓
DOI references
Found 4 DOI reference(s) in README and JOSS metadata
✓
Academic publication links
Links to: joss.theoj.org
✓
Committers with academic emails
3 of 7 committers (42.9%) from academic institutions
○
Institutional organization owner
✓
JOSS paper metadata
Published in Journal of Open Source Software

Keywords

agent agent-based agent-based-control agent-based-simulation distributed-computing multi-agent-systems

Keywords from Contributors

sciml

Last synced: 4 months ago · JSON representation ·

Repository

Modular Julia-based agent framework to implement multi-agent systems

Basic Info

Host: GitHub
Owner: OFFIS-DAI
License: mit
Language: Julia
Default Branch: development
Homepage: https://mango.offis.de/Mango.jl
Size: 1.21 MB

Statistics

Stars: 8
Watchers: 1
Forks: 1
Open Issues: 4
Releases: 4

Topics

agent agent-based agent-based-control agent-based-simulation distributed-computing multi-agent-systems

Created about 2 years ago · Last pushed 6 months ago

Metadata Files

Readme Contributing License Code of conduct Citation

README.md

![logo](docs/src/assets/logo.svg#gh-light-mode-only) ![logo](docs/src/assets/logo-dark.svg#gh-dark-mode-only)

Docs | GitHub | mail

Mango.jl allows the user to create simple agents with little effort and in the same time offers options to structure agents with complex behaviour.

The agents agents can run in two different ways: in real-time, or simulated. In real-time, the agents will run as fast as possible and communicate as specified by the protocol ("they run as developed"). In the simulation mode, the agent system and their specified tasks will be scheduled and stepped (continous or discrete) and the communication will be simulated using articial delays. One big unique characteristic of Mango.jl is that both ways use the same agent-api, meaning you can develop, evaluate your agent system in a controlled simulated environment and then transfer it to a real-time setting without (majorly) changing the implementation of your agents, as both execution ways use the same API with different environments (and containers).

Note: This project is still in an early development stage. We appreciate constructive feedback and suggestions for improvement.

Features

Container mechanism to speedup local message exchange
Structuring complex agents with loose coupling and agent roles
Built-in codecs
Supports communication between agents directly via TCP and MQTT
Built-in tasks mechanisms for proactive agent actions
Continous and discrete stepping simulation using an external clock to rapidly run and inspect simulations designed for longer time-spans
- Integrated communication and task simulation modules
- Integrated environment with which the agents can interact in a common space

Installation

Mango.jl is registered to JuliaHub. To add it to your Julia installation or project you can use the Julia REPL by calling ]add Mango or import Pkg; Pkg.add("Mango") directly:

```

julia --project=.  ✔ _ _ _ ()_ | Documentation: https://docs.julialang.org () | () () | _ _ _| | __ _ | Type "?" for help, "]?" for Pkg help. | | | | | | |/ ` | | | | || | | | (| | | Version 1.10.4 (2024-06-04) _/ |_'|||_'| |
|_/ |

(project_name) pkg> add Mango Updating registry at ~/.julia/registries/General.toml [...] ```

Example

The following simple showcase demonstrates how you can define agents in Mango. Jl, assign them to containers and send messages via a TCP connection. For more information on the specifics and other features (e.g. MQTT, modular agent using roles, simulation, tasks), please have a look at our Documentation!

With Container Creation

```julia using Mango # Create the container instances with TCP protocol container = create_tcp_container("127.0.0.1", 5555) container2 = create_tcp_container("127.0.0.1", 5556) # An agent in `Mango.jl` is a struct defined with the `@agent` macro. # We define a `TCPPingPongAgent` that has an internal counter for incoming messages. @agent struct TCPPingPongAgent counter::Int end # Create instances of ping pong agents ping_agent = TCPPingPongAgent(0) pong_agent = TCPPingPongAgent(0) # register each agent to a container and give them a name register(container, ping_agent, "Agent_1") register(container2, pong_agent, "Agent_2") # When an incoming message is addressed at an agent, its container will call the `handle_message` function for it. # Using Julias multiple dispatch, we can define a new `handle_message` method for our agent. function Mango.handle_message(agent::TCPPingPongAgent, message::Any, meta::Any) agent.counter += 1 println( "$(agent.aid) got a message: $message." * "This is message number: $(agent.counter) for me!" ) # doing very important work sleep(0.5) if message == "Ping" reply_to(agent, "Pong", meta) elseif message == "Pong" reply_to(agent, "Ping", meta) end end # With all this in place, we can send a message to the first agent to start the repeated message exchange. # To do this, we need to start the containers so they listen to incoming messages and send the initating message. # The best way to start the container message loops and ensure they are correctly shut down in the end is the # `activate(containers)` function. activate([container, container2]) do send_message(ping_agent, "Ping", address(pong_agent)) # wait for 5 messages to have been sent while ping_agent.counter < 5 sleep(1) end end ```

In newer versions of Mango.jl, the express API is introduced, which rewrites the code above to:

With Express API

```julia using Mango @agent struct TCPPingPongAgent counter::Int end function Mango.handle_message(agent::TCPPingPongAgent, message::Any, meta::Any) agent.counter += 1 println( "$(agent.aid) got a message: $message." * "This is message number: $(agent.counter) for me!" ) sleep(0.5) if message == "Ping" reply_to(agent, "Pong", meta) elseif message == "Pong" reply_to(agent, "Ping", meta) end end ping_agent = TCPPingPongAgent(0) pong_agent = TCPPingPongAgent(0) run_with_tcp(2, (ping_agent, :aid => "Agent_1"), (pong_agent, :aid => "Agent_2")) do cl send_message(ping_agent, "Ping", address(pong_agent)) sleep_until(() -> ping_agent.counter >= 5) end ```

License

Mango.jl is developed and published under the MIT license.

Owner

Name: OFFIS-DAI
Login: OFFIS-DAI
Kind: organization

Repositories: 1
Profile: https://github.com/OFFIS-DAI

JOSS Publication

Mango.jl: A Julia-Based Multi-Agent Simulation Framework

Published

October 01, 2024

DOI

10.21105/joss.07098

Volume 9, Issue 102, Page 7098

Authors

Jens Sager

Digitalized Energy Systems Group, Carl von Ossietzky Universität Oldenburg, 26129 Oldenburg, Germany, Energy Division, OFFIS Institute for Information Technology, 26121 Oldenburg, Germany

Rico Schrage

Digitalized Energy Systems Group, Carl von Ossietzky Universität Oldenburg, 26129 Oldenburg, Germany, Energy Division, OFFIS Institute for Information Technology, 26121 Oldenburg, Germany

Editor

Mehmet Hakan Satman

Citation (CITATION.cff)

cff-version: "1.2.0"
authors:
- family-names: Sager
  given-names: Jens
  orcid: "https://orcid.org/0000-0001-6352-4213"
- family-names: Schrage
  given-names: Rico
  orcid: "https://orcid.org/0000-0001-5339-6553"
doi: 10.5281/zenodo.13860452
message: If you use this software, please cite our article in the
  Journal of Open Source Software.
preferred-citation:
  authors:
  - family-names: Sager
    given-names: Jens
    orcid: "https://orcid.org/0000-0001-6352-4213"
  - family-names: Schrage
    given-names: Rico
    orcid: "https://orcid.org/0000-0001-5339-6553"
  date-published: 2024-10-01
  doi: 10.21105/joss.07098
  issn: 2475-9066
  issue: 102
  journal: Journal of Open Source Software
  publisher:
    name: Open Journals
  start: 7098
  title: "Mango.jl: A Julia-Based Multi-Agent Simulation Framework"
  type: article
  url: "https://joss.theoj.org/papers/10.21105/joss.07098"
  volume: 9
title: "Mango.jl: A Julia-Based Multi-Agent Simulation Framework"

GitHub Events

Total

Watch event: 3
Delete event: 4
Push event: 51
Pull request review event: 13
Pull request review comment event: 12
Pull request event: 4
Create event: 1

Last Year

Watch event: 3
Delete event: 4
Push event: 51
Pull request review event: 13
Pull request review comment event: 12
Pull request event: 4
Create event: 1

Committers

Last synced: 5 months ago

All Time

Total Commits: 309
Total Committers: 7
Avg Commits per committer: 44.143
Development Distribution Score (DDS): 0.301

Past Year

Commits: 126
Committers: 6
Avg Commits per committer: 21.0
Development Distribution Score (DDS): 0.278

Top Committers

Name	Email	Commits
Rico Schrage	r**e@u**e	216
Jens Sager	j**r@o**e	79
Jan-Hoerding	1****g	8
Mehmet Hakan Satman	m**n@g**m	2
Daniel S. Katz	d**z@i**g	2
Aurora Rossi	6****i	1
Rico Schrage	r**e@u**g	1

Committer Domains (Top 20 + Academic)

ieee.org: 1 offis.de: 1 uni-oldenburg.de: 1

Issues and Pull Requests

Last synced: 4 months ago

All Time

Total issues: 24
Total pull requests: 54
Average time to close issues: about 2 months
Average time to close pull requests: 5 days
Total issue authors: 5
Total pull request authors: 6
Average comments per issue: 0.58
Average comments per pull request: 0.04
Merged pull requests: 50
Bot issues: 0
Bot pull requests: 0

Past Year

Issues: 1
Pull requests: 14
Average time to close issues: N/A
Average time to close pull requests: 12 days
Issue authors: 1
Pull request authors: 5
Average comments per issue: 0.0
Average comments per pull request: 0.07
Merged pull requests: 12
Bot issues: 0
Bot pull requests: 0

View more stats

Top Authors

Issue Authors

jsagerOffis (15)
rcschrg (6)
jsager621 (1)
Tortar (1)
JuliaTagBot (1)

Pull Request Authors

rcschrg (75)
jsagerOffis (19)
jbytecode (2)
aurorarossi (2)
danielskatz (2)
Jan-Hoerding (1)

Top Labels

Issue Labels

enhancement (8) needs-fix (1) documentation (1)

Pull Request Labels

Packages

Total packages: 1
Total downloads:
- julia 1 total

Total dependent packages: 0
Total dependent repositories: 0
Total versions: 5

juliahub.com: Mango

Modular Julia-based agent framework to implement multi-agent systems

Homepage: https://mango.offis.de/Mango.jl
Documentation: https://docs.juliahub.com/General/Mango/stable/
License: MIT
Latest release: 0.4.0
published over 1 year ago

Versions: 5
Dependent Packages: 0
Dependent Repositories: 0
Downloads: 1 Total

Rankings

Dependent repos count: 10.2%

Average: 23.9%

Dependent packages count: 37.6%

Last synced: 4 months ago

Dependencies

.github/workflows/TagBot.yml actions

JuliaRegistries/TagBot v1 composite

.github/workflows/documentation.yml actions

actions/checkout v4 composite
julia-actions/setup-julia v1 composite

.github/workflows/test-mango.yml actions

actions/checkout v4 composite
codecov/codecov-action v4 composite
julia-actions/cache v1 composite
julia-actions/julia-buildpkg v1 composite
julia-actions/julia-processcoverage v1 composite
julia-actions/julia-runtest v1 composite
julia-actions/setup-julia v1 composite

Mango.jl

Science Score: 100.0%

Keywords

Keywords from Contributors

Repository

Basic Info

Statistics

Topics

Metadata Files

README.md

Features

Installation

Example

License

Owner

JOSS Publication

Mango.jl: A Julia-Based Multi-Agent Simulation Framework

Authors

Editor

Tags

Citation (CITATION.cff)

GitHub Events

Total

Last Year

Committers

All Time

Past Year

Top Committers

Committer Domains (Top 20 + Academic)

Issues and Pull Requests

All Time

Past Year

Top Authors

Issue Authors

Pull Request Authors

Top Labels

Issue Labels

Pull Request Labels

Packages

juliahub.com: Mango

Rankings

Dependencies