How to set the messages before the simulation begins?

[jthrelfall777]

Hi,

I would like to set the messages with custom values for each agent before the simulation starts. How would it be possible to achieve this in Python?

Kind Regards,

John.

[Robadob]

It's not currently possible to initialise messages from the host, they can only be output by agents and we don't currently have on-device/agent initialisation functions (#329) where you could create such messages.

To emulate this behaviour you could create your agents in an initial state "init", which only runs for one agent function whereby these initial messages are output. The same function should also transition the agents from "init" state to some other state e.g. "ready", which all the other agent functions have as their begin/end state.

The user guide's coverage for this flow is currently lacking (I will try to find time to address this today FLAMEGPU/FLAMEGPU2-docs#169).

Some relevant links:

• https://docs.flamegpu.com/guide/defining-agents/index.html#agent-states
• https://docs.flamegpu.com/guide/agent-functions/conditional-behaviours.html (typically agent states would involve conditions for transitioning partial agent populations between states, but not required in your case).

The code would roughly look

# todo declare messages
agent= model.newAgent("agent")
# todo declare vars
agent.newState("init")
agent.newState("ready")
# Create the initialiser agent function, which ouputs messages
af1 = a.newRTCFunction("init_function", InitFn_source)
af1.setInitialState("init")
af1.setEndState("ready")
af1.outputdata.setMessageOutput("init_message")
# Create remaining agent functions
af2 = a.newRTCFunction("behaviour_function", BehaviourFn_source)
af2.setInitialState("ready")
af2.setEndState("ready")
# Setup the execution order of functions
model.newLayer().addAgentFunction(af1)
model.newLayer().addAgentFunction(af2)
# Create initial agents in the "init" state
# Create a population of 1000 agents
population = pyflamegpu.AgentVector(agent, 1000)
# todo initialise the agents
# Add the agents to a simulation in "init" state and execute
simulation = pyflamegpu.CUDASimulation(model)
simulation.setPopulationData(population, "init")
simulation.initialise(sys.argv)
simulation.simulate()

Unclear what you require this for, so it seems worth additionally highlighting this quote from the user guide:

By default messages within FLAME GPU 2 are not persistent, message lists are cleared at the end of each simulation step. If persistent messages are desired, so that message lists hold messages until messages are next output to the message list in a subsequent simulation step, this can be enabled for specific message types via setPersistent() on the message’s respective Description object.

[jthrelfall777]

Many thanks for your detailed response which is really helpful. The initial state of all agents needs to be known for the agents to decided on their next state. Since I believe agents can't communicate directly they will need to find the neighbour states from the message array at fixed indices. Different simulations will have set stating states to better understand how initial states lead to quicker ordered convergence. The simulation will have 250,000+ agents running on Nvidia Tesla hardware.

[Robadob]

Since I believe agents can't communicate directly

The primary means of agent communication is via sending a message in one agent function and receiving it in another. This avoids issues that would otherwise be present in parallel execution, however can require certain (typically conflict resolution) algorithms to be restructured.

FLAME GPU 2 adds support for environment macro properties, these provide agent's access to a limited number of atomic operations. This can allow for direct agent communication, however you have to be very careful with usage to avoid bias (e.g. with a large agent population agents on lower thread indices are likely to execute earlier).

---

I've now restructured the conditional-behaviours documentation page, to better cover your use-case. You can find the PR here it will likely be merged and available on the main docs site before the end of next week (when my colleague has a chance to check it).

[jthrelfall777]

Many thanks for this Robert. One last question, can the host function access a list of agents and read the internal variables of these agents?

[Robadob]

To directly access agent data on the host you want device agent vectors.

I would avoid using these too heavily though, as copying data between host and device is relatively costly.

Agent variable reductions are computed on the device with only the result being copied back, these might be useful to you too.