Write the purpose before the agents
A simulation can be visually convincing while answering no clearly defined question. Before assigning agents colours, shapes, or movement rules, state the intended comparison. For a first teaching model, a useful question might be: how does the arrangement of passages affect the time needed for a local signal to reach a set of occupied chambers? This question identifies both an intervention—the passage arrangement—and an outcome that can be measured.
It also helps define what can be left out. A teaching model of signal reach may not need reproduction, feeding, or detailed anatomy. Excluding those processes is acceptable if the stated purpose does not require them. Adding them without evidence can make the model harder to understand while creating a stronger impression of realism. The proposed minimum is therefore a model with a clear purpose, rather than the smallest possible number of lines of code.
A complete specification
The ODD protocol developed by Grimm and colleagues provides a recognised structure for describing agent-based models. Its 2020 update emphasises clearer documentation, replication, rationale, and evaluation. AESRD proposes to use that structure alongside executable source. The description would identify entities and state variables, the process schedule, interaction rules, inputs, and the relationship between the model’s purpose and its evaluation.
For the proposed teaching example, the specification should say whether an agent is an animal or an occupied chamber, whether agents can move, what changes a state from inactive to active, and whether activation can expire. It should state what happens when two events occur during one time step. If a random draw is used, identify its distribution and the point in the schedule at which it is made.
Verify the model in cases a person can inspect
Start with a one-vertex graph: if that vertex begins active and activation persists, the active count should remain one. Next use two connected vertices and a deterministic transmission rule: the second should activate at the specified step. Then disconnect them: no transmission should occur. These checks are not biological validation. They establish whether a few essential consequences of the written rules are present in the program.
Additional invariants depend on the model. The number of agents might be fixed, states might remain within a defined set, or movement might be restricted to existing edges. If the implementation violates one of these conditions, an attractive larger simulation does not compensate for the error. A verified small case gives a reader a foothold for understanding more complicated outputs and makes later changes easier to assess.
Design experiments, not selected performances
A stochastic model produces a distribution of possible outcomes. One recorded seed makes a run repeatable, but does not show that the run is representative. An experiment should therefore record its parameter combinations, repeated runs, output definitions, and treatment of failures. The number of repetitions should be chosen with the precision needed for the comparison in mind. A narrow result from too few runs should not be disguised by a smooth connecting line.
Sensitivity analysis should include structural choices as well as numerical parameters. Compare synchronous with asynchronous schedules when both are plausible. Change the rule for transmission or the definition of neighbourhood. If the main conclusion disappears under an equally defensible alternative, that dependence is part of the result. The purpose of this exercise is to identify what the model demonstrates reliably, not to protect its first interesting output.
Package the evidence and name its limits
A proposed release would include the model description, source version, dependency information, experiment manifest, seeds, generated outputs, and a short guide to reproducing the main comparison. Inputs would be marked as synthetic, measured, or estimated. The FAIR principles provide useful guidance for making research objects discoverable and reusable; they do not require unrestricted publication of sensitive information or remove the need for permissions.
This document is a proposed protocol. It reports no completed colony experiment and validates no simulation against real shrimp. Future empirical use would require suitable observations, a specified evaluation target, and biological review. A successful first model would make its assumptions easy to inspect and its failures easy to report. Those qualities are less theatrical than a living-looking animation, but considerably more useful for cumulative research.