{"data":{"markdownRemark":{"html":"

The curse of FullyConnected Groups

\n

When connecting two Groups together, FullyConnected is generally the canonical choice as it gives the flexibility of having each agent from the source Group know each agent in the target Group.

\n

This is fine for local models where the number of agents is generally small (less than 1 million agents) but when it comes time to scale your model up, you may encounter some critical slow downs.

\n

This is due to the fact that the number of links increases fast compared to the number of agents.

\n

If the size of your source Group and target Group are respectively n and m, the number of link to create is exactly n * m:

\n

\n \n \n \n \n \n \n \n \n \n \n \n \n \n

\n

Sneaking one Group between the Source and the Target

\n

One way to shrink down the number of links is to introduce an extra group between the source Group and the target Group of a smaller size. Its agents will be dedicated to transfer the messages from the source to the target, possibly aggregating them together. Those agents are called Coordinators.

\n

If p is the size of the Coordinators ' Group; then the number of link is equal to p * m + n.

\n

\n \n \n \n \n \n \n \n \n \n \n \n \n \n

\n

To give you an brief idea of the number of links for each situations, here are some results for a small number of agents.

\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
nm# of links w/o Coordinators# of links with Coordinators with
p = log(n * m)		proportion of links avoided
10100100031069.0 %
2001002000063096.8 %
1000200200000206098.9 %
2001000200000550197.2 %
100001000100000001700099.8 %
\nLet's now see how this transcribes the model.\n

Changing your model logic to use Coordinators

\n

Let's say that you start with a model like this:

\n

Naive implementation (Java)

\n
public class CoordinatorPatternExample extends AgentBasedModel<GlobalState> {\n\n    // Number of agents for each group\n    public int n = 1000;\n    public int m = 10000;\n\n    @Override\n    public void setup() {\n        Group<SourceAgent> sourceGroup = generateGroup(SourceAgent.class, n);\n        Group<TargetAgent> targetGroup = generateGroup(TargetAgent.class, m);\n\n        sourceGroup.fullyConnected(targetGroup, BlankLink.class);\n        super.setup();\n    }\n}
\n

With those agents and this message minimally defined like so :

\n
public class SourceAgent extends Agent<GlobalState> {}\n\npublic class TargetAgent extends Agent<GlobalState> {\n  public void doSomething(int totalAmount, List<Long> sourceAgentIDs){}\n}
\n

We definitively in the first case described by the first figure.

\n

Let's say the behaviour of the model is defined as a sequence with SourceAgents sending a message to the TargetAgents:

\n
@Override\npublic void step() {\n  run(\n    Action.create(SourceAgent.class, sAgent -> {\n      sAgent.broadcastMessage(1);\n    }),\n\n    Action.create(TargetAgent.class, tAgent -> {\n          List<Message<AggregatedTransfer>> aggregatedTransfers =\n            tAgent.getMessagesOfType(AggregatedTransfer.class);\n\n          List<Long> sourceAgentIDs = new ArrayList<>();\n          int totalAmount = 0;\n\n          for (Message<AggregatedTransfer> message : aggregatedTransfers) {\n            sourceAgentIDs.addAll(message.getBody().sourceAgents);\n            totalAmount = +message.getBody().amount;\n          }\n\n          tAgent.doSomething(totalAmount, sourceAgentIDs);\n    })\n  );\n}
\n

At each tick, each SourceAgent sends a transfer message to all the theTargetAgents. Those latter agents can then doSomething with it then.

\n

Here you can convert your model to use Coordinators between the SourceAgents and the TargetAgents as shown on the second figure.

\n

You will also need another type of message, AggregatedTransfer.

\n
public class SourceAgent extends Agent<GlobalState> {}\npublic class TargetAgent extends Agent<GlobalState> {}\npublic class Coordinator extends Agent<GlobalState> {}\n\npublic class AggregatedTransfer{\n  int amount;\n  List<Long> sourceAgents;\n\n  public AggregatedTransfer(int amount, List<Long> sourceAgents) {\n     this.amount = amount;\n     this.sourceAgents = sourceAgents;\n  }\n}
\n

Essentially, the Coordinators will gather the Transfers sent by their SourceAgents and will remap them to all the TargetAgents.

\n
@Override\npublic void step() {\n  run(\n      Action.create(SourceAgent.class, sAgent -> sAgent.broadcastMessage(1)),\n\n      Action.create(Coordinator.class, coordinator -> {\n        List<Message<AggregatedTransfer>> transfers =\n          coordinator.getMessagesOfType(AggregatedTransfer.class);\n\n        List<Long> sourceAgentIDs = new ArrayList<>();\n        int totalAmount = 0;\n\n        for (Message<AggregatedTransfer> message : transfers) {\n          sourceAgentIDs.add(message.getSender());\n          totalAmount += message.getBody().amount;\n        }\n\n        coordinator.broadcastMessage(\n          new AggregatedTransfer(totalAmount, sourceAgentIDs));\n      }),\n\n      Action.create(TargetAgent.class, tAgent -> {\n        List<Message<AggregatedTransfer>> aggregatedTransfers =\n          tAgent.getMessagesOfType(AggregatedTransfer.class);\n\n        List<Long> sourceAgentIDs = new ArrayList<>();\n        int totalAmount = 0;\n\n        for (Message<AggregatedTransfer> message : aggregatedTransfers) {\n          sourceAgentIDs.addAll(message.getBody().sourceAgents);\n          totalAmount = +message.getBody().amount;\n        }\n\n        tAgent.doSomething(totalAmount, sourceAgentIDs);\n      })\n    );\n}
\n
\n

Modification of actions of initial agents

\nHere you will see that you need to change the actions of the `TargetAgents` slightly to use this pattern.\n
\nYou can easily change the topologies of your model introducing two new lines and modify the `Connectors` to include the `Coordinators` :\n

Creating a coordinator group(Java)

\n
public int p = (int) Math.log(n * m);\n\npublic Group<Coordinator> coordinators = system.generateGroup(Coordinator.class, p);\n\nsourceGroup.partitionConnected(coordinators);\ncoordinators.fullyConnected(targetGroup);
\n

We introduce p to represent the number of Coordinators to create.

\n
\n

About the definition of p

\nWe set `p` to be a logarithmic expression of the number of agents, this is a good tradeoff between not having a high number of links and not having a bottle neck at the `Coordinators` level. You can change it at will.\n
\nAt the end you end up having this file here:\n

Coordinator pattern (Java)

\n
import simudyne.core.abm.Agent;\nimport simudyne.core.abm.AgentBasedModel;\nimport simudyne.core.abm.GlobalState;\nimport simudyne.core.abm.Group;\n\nimport java.util.List;\n\npublic class CoordinatorPatternExample extends AgentBasedModel<GlobalState> {\n\n  // Number of agents for each group\n  public int n = 1000;\n  public int m = 10000;\n  public int p = (int) Math.log(n * m);\n\n  @Override\n  public void setup() {\n    // Creating the groups\n    Group<SourceAgent> sourceGroup = generateGroup(SourceAgent.class, n);\n    Group<TargetAgent> targetGroup = generateGroup(TargetAgent.class, m);\n    Group<Coordinatior> coordinatiorGroup = generateGroup(Coordinator.class, p);\n\n    sourceGroup.partitionConnected(coordinators);\n    coordinators.fullyConnected(targetGroup);\n    super.setup();\n  }\n}\n\n  @Override\n  public void step() {\n    run(\n      Action.create(SourceAgent.class, sAgent -> sAgent.broadcastMessage(1)),\n\n      Action.create(Coordinator.class, coordinator -> {\n        List<Message<AggregatedTransfer>> transfers =\n          coordinator.getMessagesOfType(AggregatedTransfer.class);\n\n        List<Long> sourceAgentIDs = new ArrayList<>();\n        int totalAmount = 0;\n\n        for (Message<AggregatedTransfer> message : transfers) {\n          sourceAgentIDs.add(message.getSender());\n          totalAmount += message.getBody().amount;\n        }\n\n        coordinator.broadcastMessage(\n          new AggregatedTransfer(totalAmount, sourceAgentIDs));\n      }),\n\n      Action.create(TargetAgent.class, tAgent -> {\n        List<Message<AggregatedTransfer>> aggregatedTransfers =\n          tAgent.getMessagesOfType(AggregatedTransfer.class);\n\n        List<Long> sourceAgentIDs = new ArrayList<>();\n        int totalAmount = 0;\n\n        for (Message<AggregatedTransfer> message : aggregatedTransfers) {\n          sourceAgentIDs.addAll(message.getBody().sourceAgents);\n          totalAmount = +message.getBody().amount;\n        }\n\n        tAgent.doSomething(totalAmount, sourceAgentIDs);\n      })\n    );\n  }\n}
\n

Using PartitionConnected#weave()

\n

If you have a look more closely at PartitionConnected, you'll see that this ConnectionStrategy exposes two sub-strategies:

\n\n

In the case of the Coordinator Pattern, using one or the other can have different meanings.

\n

Here is an example of coordinating agents on a grid. Here, the Coordinator Pattern allows agents to have information about others agents that are not directly next to them.

\n

\n \n \n \n \n \n \n \n \n \n \n \n \n \n

\n

This is the snippet used to create this topology:

\n

Partition connected weave pattern (Java)

\n
public Group<MyAgent> agents = generateGroup(MyAgent.class,16);\npublic Group<Coordinator> coordinators = generateGroup(Coordinators.class, 3);\n\nagents.gridConnected(OnGrid.class);\nagents.partitionConnected(coordinators, ToCoordinator.class);
\n

This example is very simple but gives the intuition about what weaving the links between the agents and the coordinators allows.

","headings":[{"value":"The curse of FullyConnected Groups","depth":3},{"value":"Sneaking one Group between the Source and the Target","depth":3},{"value":"Changing your model logic to use Coordinators","depth":3},{"value":"Using PartitionConnected#weave()","depth":3}],"frontmatter":{"title":"Coordinator Pattern","toc":false,"experimental":null}},"site":{"siteMetadata":{"title":"Simudyne Docs","latestVersion":"2.6"}}},"pageContext":{"absolutePath":"/home/vsts/work/1/s/content/2.0/docs/practices/coordinator-pattern.md","versioned":true,"version":"2.0","kind":"docs","pagePath":"/practices/coordinator-pattern","chronology":{"prev":{"name":"Iterative Model Building","path":"/practices/iterative-model-building"},"next":{"name":"Release Notes","path":"/release-notes"}},"lastUpdated":"2026-04-21T13:56:54.824Z"}}