OFFIS-DAI · rcschrg · Sep 30, 2025 · Sep 4, 2024 · Sep 4, 2024 · Sep 4, 2024
diff --git a/.github/workflows/test-mango.yml b/.github/workflows/test-mango.yml
@@ -1,6 +1,12 @@
 name: Test Mango.jl
 
-on: [push]
+on: 
+  push:
+    branches:
+      - main
+      - development
+  pull_request:
+    types: [opened, synchronize, reopened]
 
 
 # needed to allow julia-actions/cache to delete caches

diff --git a/CITATION.cff b/CITATION.cff
@@ -0,0 +1,32 @@
+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"
diff --git a/Project.toml b/Project.toml
@@ -2,13 +2,16 @@ name = "Mango"
 uuid = "5e49fdec-d473-4d14-b295-7bff2fcf1925"
 authors = ["OFFIS e.V."]
 repo = "https://github.com/OFFIS-DAI/Mango.jl"
-version = "0.4.0"
+version = "0.5.0"
 
 [deps]
+Colors = "5ae59095-9a9b-59fe-a467-6f913c188581"
 ConcurrentCollections = "5060bff5-0b44-40c5-b522-fcd3ca5cecdd"
 ConcurrentUtilities = "f0e56b4a-5159-44fe-b623-3e5288b988bb"
 Dates = "ade2ca70-3891-5945-98fb-dc099432e06a"
 Distributed = "8ba89e20-285c-5b6f-9357-94700520ee1b"
+Distributions = "31c24e10-a181-5473-b8eb-7969acd0382f"
+Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
 Graphs = "86223c79-3864-5bf0-83f7-82e725a168b6"
 JSON = "682c06a0-de6a-54ab-a142-c8b1cf79cde6"
 LightBSON = "a4a7f996-b3a6-4de6-b9db-2fa5f350df41"
@@ -17,24 +20,40 @@ MetaGraphsNext = "fa8bd995-216d-47f1-8a91-f3b68fbeb377"
 Mosquitto = "db317de6-444b-4dfa-9d0e-fbf3d8dd78ea"
 OrderedCollections = "bac558e1-5e72-5ebc-8fee-abe8a469f55d"
 Parameters = "d96e819e-fc66-5662-9728-84c9c7592b0a"
+Random = "9a3f8284-a2c9-5f02-9a11-845980a1fd5c"
 Sockets = "6462fe0b-24de-5631-8697-dd941f90decc"
 UUIDs = "cf7118a7-6976-5b1a-9a39-7adc72f591a4"
 
+[weakdeps]
+GraphMakie = "1ecd5474-83a3-4783-bb4f-06765db800d2"
+Makie = "ee78f7c6-11fb-53f2-987a-cfe4a2b5a57a"
+
+[extensions]
+MangoGraphVisualization = ["Makie", "GraphMakie"]
+MangoPlotVisualization = ["Makie"]
+
 [compat]
+CairoMakie = "0.13.1"
+Colors = "~0.12"
 ConcurrentCollections = "~0.1"
 ConcurrentUtilities = "~2.2"
+Distributions = "~0.25"
+GraphMakie = "0.5.13"
+Graphs = "~1.10"
 JSON = "~0.21"
 LightBSON = "~0.2"
+Makie = "0.22.1"
+MetaGraphsNext = "~0.7"
 Mosquitto = "~0.10"
 OrderedCollections = "~1.6"
 Parameters = "~0.12"
-Graphs = "~1.11"
-MetaGraphsNext = "~0.7"
 julia = "^1.9"
 
 [extras]
-Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
+CairoMakie = "13f3f980-e62b-5c42-98c6-ff1f3baf88f0"
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+Makie = "ee78f7c6-11fb-53f2-987a-cfe4a2b5a57a"
+Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
 
 [targets]
-test = ["Test", "Documenter"]
+test = ["Test", "Documenter", "CairoMakie", "Makie", "GraphMakie"]
diff --git a/README.md b/README.md
@@ -1,29 +1,20 @@
 
 <p align="center">
 
-![logo](docs/src/Logo_mango_ohne_sub.svg#gh-light-mode-only)
-![logo](docs/src/Logo_mango_ohne_sub_white.svg#gh-dark-mode-only)
+![logo](docs/src/assets/logo.svg#gh-light-mode-only)
+![logo](docs/src/assets/logo-dark.svg#gh-dark-mode-only)
 
 </p>
 
 [Docs](https://offis-dai.github.io/Mango.jl/stable)
 | [GitHub](https://github.com/OFFIS-DAI/Mango.jl) | [mail](mailto:mango@offis.de)
 
-<!-- Tidyverse lifecycle badges, see https://www.tidyverse.org/lifecycle/ Uncomment or delete as needed. -->
 ![lifecycle](https://img.shields.io/badge/lifecycle-maturing-blue.svg)
 [![MIT License](https://img.shields.io/badge/license-MIT-green.svg)](https://github.com/OFFIS-DAI/Mango.jl/blob/development/LICENSE)
+[![DOI](https://joss.theoj.org/papers/10.21105/joss.07098/status.svg)](https://doi.org/10.21105/joss.07098)
 [![Test Mango.jl](https://github.com/OFFIS-DAI/Mango.jl/actions/workflows/test-mango.yml/badge.svg)](https://github.com/OFFIS-DAI/Mango.jl/actions/workflows/test-mango.yml)
 [![codecov](https://codecov.io/gh/OFFIS-DAI/Mango.jl/graph/badge.svg?token=JRZB5T2T2M)](https://codecov.io/gh/OFFIS-DAI/Mango.jl)
 
-<!--
-![lifecycle](https://img.shields.io/badge/lifecycle-experimental-orange.svg)
-![lifecycle](https://img.shields.io/badge/lifecycle-stable-green.svg)
-![lifecycle](https://img.shields.io/badge/lifecycle-retired-orange.svg)
-![lifecycle](https://img.shields.io/badge/lifecycle-archived-red.svg)
-![lifecycle](https://img.shields.io/badge/lifecycle-dormant-blue.svg) 
--->  
-
-
 
 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.
 
@@ -67,7 +58,10 @@ To add it to your Julia installation or project you can use the Julia REPL by ca
 
 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](https://offis-dai.github.io/Mango.jl/stable)!
 
-```julia
+<details open>
+  <summary>With Container Creation</summary>    
+
+  ```julia
 using Mango
 
 # Create the container instances with TCP protocol
@@ -94,7 +88,7 @@ function Mango.handle_message(agent::TCPPingPongAgent, message::Any, meta::Any)
     agent.counter += 1
 
     println(
-        "$(agent.aid) got a message: $message." *
+        "$(aid(agent)) got a message: $message." *
         "This is message number: $(agent.counter) for me!"
     )
 
@@ -120,17 +114,46 @@ activate([container, container2]) do
         sleep(1)
     end
 end
-```
+  ```
+</details>
+
+In newer versions of Mango.jl, the express API is introduced, which rewrites the code above to:
+
+<details open>
+  <summary>With Express API</summary>
+
+  ```julia
+using Mango
+
+@agent struct TCPPingPongAgent
+    counter::Int
+end
+
+function Mango.handle_message(agent::TCPPingPongAgent, message::Any, meta::Any)
+    agent.counter += 1
+
+    println(
+        "$(aid(agent)) 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
+  ```
+</details>
 
 ## License
 Mango.jl is developed and published under the MIT license.
-<!-- travis-ci.com badge, uncomment or delete as needed, depending on whether you are using that service. -->
-<!-- [![Build Status](https://travis-ci.com/mango/mango.jl.svg?branch=master)](https://travis-ci.com/mango/mango.jl) -->
-<!-- Coverage badge on codecov.io, which is used by default. -->
-<!-- Documentation -- uncomment or delete as needed -->
-<!--
-[![Documentation](https://img.shields.io/badge/docs-stable-blue.svg)](https://mango.github.io/mango.jl/stable)
-[![Documentation](https://img.shields.io/badge/docs-master-blue.svg)](https://mango.github.io/mango.jl/dev)
--->
-<!-- Aqua badge, see test/runtests.jl -->
-<!-- [![Aqua QA](https://raw.githubusercontent.com/JuliaTesting/Aqua.jl/master/badge.svg)](https://github.com/JuliaTesting/Aqua.jl) -->
diff --git a/docs/Project.toml b/docs/Project.toml
@@ -1,9 +1,9 @@
 [deps]
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+Graphs = "86223c79-3864-5bf0-83f7-82e725a168b6"
+Logging = "56ddb016-857b-54e1-b83d-db4d58db5568"
 Mango = "5e49fdec-d473-4d14-b295-7bff2fcf1925"
 Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
-Logging = "56ddb016-857b-54e1-b83d-db4d58db5568"
-Graphs = "86223c79-3864-5bf0-83f7-82e725a168b6"
 
 [compat]
 Documenter = "~0.27"
diff --git a/docs/make.jl b/docs/make.jl
@@ -6,9 +6,9 @@ logger = Test.TestLogger(min_level=Info);
 with_logger(logger) do
     makedocs(
         modules=[Mango],
-        format=Documenter.HTML(; prettyurls=get(ENV, "CI", nothing) == "true"),
+        format=Documenter.HTML(; assets=["assets/mango_theme_overrides.css"], prettyurls=get(ENV, "CI", nothing) == "true"),
         authors="mango Team",
-        sitename="Mango.jl",
+        sitename="Mango.jl Documentation",
         pages=Any["Home"=>"index.md",
             "Getting Started"=>"getting_started.md",
             "Agents"=>"agent.md",

diff --git a/docs/src/api.md b/docs/src/api.md
@@ -17,7 +17,7 @@ Here, the API for the agent structs created with @agent/@role is listed.
 ```@autodocs
 Modules = [Mango]
 Private = false
-Pages = ["agent/api.jl", "agent/core.jl", "agent/role.jl"]
+Pages = ["agent/api.jl", "agent/core.jl", "agent/role.jl", "agent/services.jl"]
 Order = [:macro, :function, :constant, :type, :module]
 ```
 
@@ -33,12 +33,22 @@ Pages = ["container/api.jl", "container/core.jl", "container/mqtt.jl", "containe
 
 # Simulation
 
-In the following the APIs regarding the simulation container are listed.
+In the following the APIs regarding the simulation world are listed.
 
 ```@autodocs
 Modules = [Mango]
 Private = false
-Pages = ["container/simulation.jl", "simulation/communication.jl", "simulation/tasks.jl"]
+Pages = ["simulation/container.jl", "simulation/communication.jl", "simulation/tasks.jl", "simulation/world.jl"]
+```
+
+# Simulation Environment
+
+In the following the APIs regarding the simulation environment are listed.
+
+```@autodocs
+Modules = [Mango]
+Private = false
+Pages = ["environment/api.jl", "environment/core.jl"]
 ```
 
 # Scheduling
@@ -58,7 +68,7 @@ In the following the APIs for creating, aplying and using topologies is listed.
 ```@autodocs
 Modules = [Mango]
 Private = false
-Pages = ["world/topology.jl"]
+Pages = ["util/topology.jl"]
 ```
 
 # Encoding/Decoding

diff --git a/docs/src/Logo_mango_ohne_sub_white.svg → docs/src/assets/logo-dark.svg b/docs/src/Logo_mango_ohne_sub_white.svg → docs/src/assets/logo-dark.svg
diff --git a/docs/src/Logo_mango_ohne_sub.svg → docs/src/assets/logo.svg b/docs/src/Logo_mango_ohne_sub.svg → docs/src/assets/logo.svg
diff --git a/docs/src/assets/mango_theme_overrides.css b/docs/src/assets/mango_theme_overrides.css
@@ -0,0 +1,91 @@
+body {
+  font-family: -apple-system, BlinkMacSystemFont, Segoe UI, Helvetica, Arial, sans-serif, Apple Color Emoji, Segoe UI emojiEmoji;
+}
+
+html.theme--documenter-dark body {
+  font-family: -apple-system, BlinkMacSystemFont, Segoe UI, Helvetica, Arial, sans-serif, Apple Color Emoji, Segoe UI emojiEmoji;
+}
+
+html.theme--documenter-dark #documenter .docs-sidebar {
+  border-right: none;
+}
+
+html.theme--documenter-dark .select select,
+html.theme--documenter-dark .textarea,
+html.theme--documenter-dark .input,
+html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input {
+  border-color: #2f4547;
+}
+
+#documenter {
+  width: 100%;
+  display: flex;
+}
+
+@media screen and (min-width: 1056px) {
+  #documenter .docs-sidebar {
+    position: sticky;
+    height: 100vh;
+    padding-left: calc(50% - 1200px / 2);
+    display: flex;
+    min-width: 18rem;
+    box-sizing: content-box;
+  }
+
+  html.theme--documenter-dark #documenter .docs-sidebar {
+    position: sticky;
+    height: 100vh;
+    padding-left: calc(50% - 1200px / 2);
+    display: flex;
+    min-width: 18rem;
+    box-sizing: content-box;
+    background-color: #252929;
+  }
+}
+
+html.theme--documenter-dark #documenter .docs-sidebar ul.docs-menu .tocitem {
+  background-color: transparent;
+}
+
+@media screen and (min-width: 1056px) {
+  #documenter .docs-main {
+    max-width: 52rem;
+    padding-right: 1rem;
+    margin-left: 50px;
+  }
+
+  html.theme--documenter-dark #documenter .docs-main {
+    max-width: 52rem;
+    padding-right: 1rem;
+    margin-left: 50px;
+  }
+}
+
+#documenter .docs-sidebar .docs-package-name {
+  visibility: hidden;
+  height: 0;
+}
+
+html.theme--documenter-dark .button.is-static {
+  border-color: #2f4547;
+}
+
+html.theme--documenter-dark #documenter .docs-main header.docs-navbar {
+  border-bottom: 1px solid #2f4547;
+}
+
+html.theme--documenter-dark #documenter .docs-sidebar ul.docs-menu ul.internal {
+  border-top: 1px solid #2f4547;
+}
+
+html.theme--documenter-dark #documenter .docs-sidebar ul.docs-menu li.is-active {
+  border-color: #2f4547;
+}
+
+html.theme--documenter-dark #documenter .docs-sidebar ul.docs-menu {
+  border-color: #2f4547;
+}
+
+html.theme--documenter-dark #documenter .docs-main .docs-footer {
+  border-color: #2f4547;
+}
diff --git a/docs/src/getting_started.md b/docs/src/getting_started.md
@@ -4,7 +4,7 @@ In this getting started guide, we will explore the essential features of Mango.j
 
 You can also find working examples of the following code in [examples.jl](../../test/examples.jl).
 
-## 0. Quickstart
+## Quickstart
 
 In Mango.jl, you can define agents using a number of roles using [`@role`](@ref) and [`agent_composed_of`](@ref), or directly using [`@agent`](@ref). To define the behavior of the agents, [`handle_message`](@ref) can be defined, and messages can be send using [`send_message`](@ref). To run the agents with a specific protocol in real time the fastest way is to use [`run_with_tcp`](@ref), which will distribute the agents to tcp-containers and accepts a function in which some agent intializiation and/or trigger-code could be put. The following example illustrates the basic usage of the functions.
 
@@ -70,7 +70,7 @@ function Mango.handle_message(agent::TCPPingPongAgent, message::Any, meta::Any)
     agent.counter += 1
 
     println(
-        "$(agent.aid) got a message: $message." *
+        "$(aid(agent)) got a message: $message." *
         "This is message number: $(agent.counter) for me!"
     )