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

Actions and Sequences are used to define a sequence of actions for the agents to follow at every step, or at setup.

\n

A Sequence is a list of actions that are executed consecutively. Sequences are composable, which means a sequence can be a list of other sequences as well as actions. Multiple sequences can be run in a single setup() or step().

\n

Every sequence needs to be run in order for the sequence to be executed.

\n

Creating and running an empty Sequence (Java)

\n
public class MyClass extends AgentBasedModel<GlobalState> {\n  ...\n\n  run (Sequence.create());\n\n  ...\n}
\n

Actions have to be created for a specific class. It is best practice to create actions inside the class of the Agent the action is being defined for.

\n

When creating an action, two parameters need to defined.

\n
    \n
  1. The agent that will execute this action
    2. \n
  2. The function to be executed by the agent
    3. \n
\n

Creating actions and adding them to a sequence (Java)

\n
public static Action<AgentA> sendMessageToAgentB =\n  Action.create(\n    AgentA.class, agentA -> { /** send message */ });\n\npublic static Action<AgentB> recieveMessage =\n  Action.create(\n    AgentB.class, agentB -> { /** recieve message */ });\n\nrun (\n\tSequence.create(\n  \tsendMessageToAgentB,\n  \trecieveMessage\n));
\n

The run method can also take a list of actions which it will execute as though its a sequence, so the above code could also be written like this.

\n

(Java)

\n
public static Action<AgentA> sendMessageToAgentB =\n  Action.create(\n    AgentA.class, agentA -> { /** send message */ });\n\npublic static Action<AgentB> recieveMessage =\n  Action.create(\n    AgentB.class, agentB -> { /** recieve message */ });\n\nrun (\n  \tsendMessageToAgentB,\n  \trecieveMessage\n);
\n
\nAn action will only be executed by an agent if that agent has received a message. If an action needs to be executed by all agents of a type, even if some of those agents have not received a message, this action needs to be at the beginning of a new sequence.\n
\n

Message passing(Java)

\n
//If AgentB isnt sent message, it will not do other processing\nrun (\n  Sequence.create(\n    AgentA.conditionallySendMessage(),\n    AgentB.recieveMessageActionAndDoOtherProcessing())\n  ),\n\n  //Split other processing into another sequence to ensure all AgentB do processing\n  Sequence.create(\n    AgentA.conditionallySendMessage()),\n    AgentB.recieveMessageAction())\n  ),\n\n  Sequence.create(\n    AgentB.doOtherProcessing())\n  )\n);
\n
\n

Messages cannot be passed between sequence runs

\nAll message passing and receiving needs to be done within a single sequence run. (This does not apply to sequences that are composed of other sequences, messages will be passed between sequences called from inside another sequence.)\n
\n

Message passing (Java)

\n
//Message will be passed from AgentA to AgentB\nrun (\n  Sequence.create(\n    Sequence.create(AgentA.sendMessageAction()),\n    Sequence.create(AgentB.recieveMessageAction())\n  ),\n\n  //Message will NOT be passed from AgentA to AgentB\n  Sequence.create(\n    AgentA.sendMessageAction())\n  ),\n\n  Sequence.create(\n    AgentB.recieveMessageAction())\n  )\n);
\n

Executing Action in Parallel

\n

In all the sequences we have shown until now, the actions happen one after the next, like in the following diagram.

\n

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

\n

It is also possible to have two actions happening at the same time, as in the diagram below. Here, AgentA can send a message that both AgentB and AgentC receive and process at the same time. They can then both send a message to AgentA to process.

\n

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

\n

Put the actions that need to happen in parallel in a split.

\n
\nAs for other sequence runs, message cannot be passed between splits.\n
\n

Split (Java)

\n
run (\n    AgentA.doAction1(),\n    Split.create(\n      AgentB.doAction1(),\n      AgentC.doAction1()\n    ),\n    AgentA.doAction2())\n);
\n

It is also possible to want to do several actions in parallel, or sequences of their own in parallel.

\n

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

\n

Multi-Split(Java)

\n
run (\n    AgentA.doAction1(),\n    Split.create(\n      AgentB.doAction1(),\n      Sequence.create(\n        AgentC.doAction1(),\n        AgentB.doAction2()\n      )\n    ),\n    AgentA.doAction2())\n);
\n

The sequence on which actions will be processed in this case is

\n
    \n
  1. AgentA process action1,
    2. \n
  2. AgentB and AgentC process action1
    3. \n
  3. AgentB process action2
    4. \n
  4. AgentA process action2 (having received messages from both AgentB and AgentC)
    5. \n
\n
\nIn all the examples above, doAction includes sending a message to the next agent in the sequence\n
\n
\n

Best Practice

\nIn cases where there are sequences inside splits, or splits inside splits, the model will be a lot easier to work with if sequences and splits were created as variables\n
\n

(Java)

\n
// nested sequence removed and created as a variable\nprivate Sequence agentCActions =\n  Sequence.create(\n    \tAgentC.doAction1(),\n      AgentB.doAction2()\n    )\n\n// main sequence is now easier to read\nrun (\n  Sequence.create(\n    AgentA.doAction1(),\n    Split.create(\n      AgentB.doAction1(),\n      agentCActions\n    ),\n    AgentA.doAction2())\n  )\n);
\n

It is possible to compose sequence's and actions to create the complex sequences as needed. Example of more complex sequence - with a sequence inside a sequence.

\n

\n \n \n \n \n

Messages with arbitrary fields

\n

If your message needs to send an arbitrary amount of data, but no explict type exists, consider extending Message

\n

For organising custom message classes, see Message Organisation

\n
\nWhen running the model in distributed mode, all message types need to be registered with the model. This isn't necessary if running the model locally.\n
\n

Registering messages

\n

(Java)

\n
public class MyClass extends AgentBasedModel<GlobalState> {\n  ...\n  registerMessageTypes(Boolean.class, Messages.Vacancy.class);\n  ...\n}
\n

Sending Messages

\n

A fluent API provides the capability to filter and customise messages sent based on the link the message will be sent along.

\n

All message sending is done by the agents, and so can only be done from inside an agent class.

\n

Sending messages along links.

\n

Messages can be sent along specific links that an agent holds. Methods must be chained in a particular order.

\n\n

Below shows how to use a generic message class.

\n

Generic message along a link (Java)

\n
getLinks(Links.Neighbour.class)\n         .send(Messages.Alive.class, (message, link) -> message.alive=true);
\n

We see the send message takes as second argument a BiConsumer allowing access to link data while constructing the message. In this example we did not require accessing any data on the link; however, it is available if needed. Note, our message class looks like so.

\n
 public static class Alive extends Message {\n    boolean alive;\n  }
\n

However, if our message only contains a single primitive field, like above, extend one of the specialised message classes. Below, a value given is assigned into the body of the constructed message automatically.

\n

Specialised messages

\n
cell.getLinks(Links.Neighbour.class)\n    .send(Messages.Aliveness.class, cell.alive)
\n

Where we now extend Message.Boolean.

\n
 public static class Alive extends Message.Boolean {}
\n

Sending messages directly to agents.

\n

Messages can also be sent directly to an agent, by providing the id associated with the recipient. This is useful when you wish to employ a request-response pattern, where an agent replies directly to the sender of a message.

\n

Request-response pattern (Java)

\n
Messages.Bid bid = seller.getMessageOfType(Messages.Bid.class);\nif (bid.getBody() > minBid) {\n  seller.send(Messages.Asset.class)\n        .to(bid.getSender());\n}
\n

Filtering links.

\n

It is useful to know that you can succinctly filter the list of links getLinks returns. Simply chain filter on the end of getLinks and pass in the predicate you wish to filter on.

\n

Filtering links (Java)

\n
bank.getLinks(Links.MortgageLinks)\n  .filter(mortgageLink -> mortgageLink == isActive)\n  ...
\n

This will return only mortgages that are currently active.

\n

Receiving Messages

\n

Receiving messages is driven by the message types. Any message received is the message type itself.

\n

For getting a single message. If there are multiple messages of this type, it will return one of them (at random).

\n

Receiving Messages (Java)

\n
class Cell extends Agent<GlobalState> {\n  public Action<Cell> getAliveMessage() {\n    return Action.create(\n      Cell.class,\n      cell -> {\n        Message<Messages.Aliveness> messages = cell.getMessageOfType(Messages.Aliveness.class);\n        boolean isAlive = isAliveMessage.getBody();\n      }\n    );\n  }\n}
\n

If expecting multiple message of a particular type use getMessagesOfType. This will return the messages in a List.

\n

Receiving a List of Messages (Java)

\n
class Cell extends Agent<GlobalState> {\n  public Action<Cell> getAliveMessage() {\n    return Action.create(\n      Cell.class,\n      cell -> {\n        List<Messages.Aliveness> aliveMessages = cell.getMessagesOfType(Messages.Aliveness.class);\n        long count = aliveMessages.stream().filter(Message::getBody).count();\n      }\n    );\n  }\n}
\n

hasMessage can be used to check if a message of a particular type has been received.

\n

Checking for messages of given type (Java)

\n
class Cell extends Agent<GlobalState> {\n  public Action<Cell> getAliveMessage() {\n    return Action.create(\n      Cell.class,\n      cell -> {\n        Messages.Aliveness messages = cell.hasMessageOfType(Messages.Aliveness.class);\n      }\n    );\n  }\n}
\n
\n

Replying to a message

\nUse getSender on a message to get the id of the agent who sent the message, and use that id with sendMessage to send a message back to sender.\n
\n

Pre & Post Phase Processing

\n

You have the possibility to apply certain modifications on an Agent before the beginning of a phase or after its end .

\n

The SystemMessage is a new subtype of Message that are processed before the beginning of the Actions. You can use them to apply changes before the phase even begins.

\n

The new method deferTask(Consumer< Vertex< ? extends Serializable>>) allows to postpone the application of a modification after the end of the phase.

\n

deferTask

\n

The method deferTask is a member of the interface Environment, see its declaration below.

\n
Declaration of deferTask() in Environment (Java)
\n
public interface Environment<S extends Serializable> {\n...\n...\n\n\tvoid deferTask(Consumer<Vertex<S>> dataInjector);\n}
\n

You can call this method from an Agent, and use a lambda as argument.\nThe lambda will be processed right after the Actions, at the end of the phase.

\n
Example of use of deferTask() (Java)
\n
deferTask(vertex -> vertex.getLinks().get(0).remove());
\n

This will remove a Link of the Vertex at the end of the phase, but the Link would still exist and would still be available during this phase.

\n

SystemMessage

\n

SystemMessage is a Java Interface. It is used to define Messages that are processed automatically right at the beginning of the phase, before the Actions.

\n
The SystemMessage Interface (Java)
\n
public interface SystemMessage {\n  boolean receivedByVertex(Agent<? extends GlobalState> agent, Environment<? extends GlobalState> env);\n}
\n

The only method you must implement is receivedByVertex. This method will be called by the Agent receiving the message.\nYou must describe the modification you want to apply on the Agent receiving the message in this method (note that the argument agent represent the Agent receiving the message).

\n

The type of return of this method is a boolean deciding whether or not the Agent will handle its Actions.\nIf an Agent receives a SystemMessage with a receivedByVertex returning false, then its Actions will not be processed for this phase.\nIf you do not wish to prevent the execution of the Actions, return true for all your receivedByVertex methods.\nNote that you only need one receivedByVertex returning false to prevent the Actions being processed, even if all the other receivedByVertex methods called by the Agent return true.

\n
\n
SystemMessages are used for lot of purposes
\nBe careful when using a SystemMessage , as some other functionalities are using this method.\nFor instance, the PoisonPill feature is using SystemMessage.\nYou should therefore be careful if you try to access datas with a SystemMessage as Agents may be in an 'intermediate' state and not ready yet for Actions.\n
\n
Example of custom SystemMessage (Java)
\n
public static class MyMessage extends Message implements SystemMessage {\n    public int field1;\n    public int field2;\n\n    @Override\n    public boolean receivedByVertex(Agent<? extends GlobalState> agent, Environment<? extends GlobalState> env) {\n      return true;\n    }\n  }
\n
\n
SystemMessages cannot begin a phase
\nA SystemMessage will not be put into the Agent's inbox. This allows you to send 'invisible' messages to an Agent, as the Agent will not react to it.\nFor instance, you could send a SystemMessage to an `Agent` to update one of its fields, and do so without triggering a phase for this `Agent` (because his inbox would still be empty).\n
","headings":[{"value":"Executing Action in Parallel","depth":3},{"value":"Messaging Semantics","depth":3},{"value":"Message Types","depth":3},{"value":"Empty messages","depth":4},{"value":"Single primitive type messages","depth":4},{"value":"Complex data types","depth":4},{"value":"Messages with arbitrary fields","depth":4},{"value":"Sending Messages","depth":3},{"value":"Sending messages along links.","depth":4},{"value":"Sending messages directly to agents.","depth":4},{"value":"Filtering links.","depth":4},{"value":"Receiving Messages","depth":3},{"value":"Pre & Post Phase Processing","depth":3},{"value":"deferTask","depth":4},{"value":"SystemMessage","depth":4}],"frontmatter":{"title":"Actions and Sequencing","toc":null,"experimental":null}},"site":{"siteMetadata":{"title":"Simudyne Docs","latestVersion":"2.6"}}},"pageContext":{"absolutePath":"/home/vsts/work/1/s/content/2.1/reference/agents/actions-and-sequencing.md","versioned":true,"version":"2.1","kind":"reference","pagePath":"/reference/agents/actions-and-sequencing","chronology":{"prev":{"name":"Topologies","path":"/reference/agents/topologies"},"next":{"name":"Reporting","path":"/reference/agents/reporting"}},"lastUpdated":"2026-04-21T13:56:54.830Z"}}