An important part of building models is that their results should be repeatable if the same inputs are given to them. The Simudyne SDK creates models that rely on numerical seeds that are randomly generated. A number of tools are provided for random number generation, but if a model is built properly, it should still be deterministic with respect to its seed.
\nIt is easy to unintentionally introduce other sources of randomness into the model besides its numerical seed. The output of a properly built model should only change under two conditions: if its input parameters change or if its numerical seed is purposely changed. For the same model running with the same seed, the only source of change should be the input parameters.
\nThe easiest way to enforce determinism is to use the random number generator provided from the model context. The seed will be the same for all instances of this model for the entire run.
\npublic class myModel extends AgentBasedModel<GlobalState> {\n public void setup() {\n SeededRandom pnrg = getContext().getPRNG();\n pnrg.generator.nextDouble();\n }\n ...\n}Health checks are implemented in the SDK to warn modellers if an unanticipated source of randomness may be present. This is achieved by internally running and testing the output of a registered model when starting the server.
\nHealth checks can be disabled by setting the value of the config field nexus-server.health-check in the simudyneSDK.properties file. This value is a boolean, true by default, so setting it to false will disable health checks. To learn more about model configurations related to health checks, click here.
As of v2.5 you are also able to specify a value via nexus-server.health-check-ticks as a number for how many ticks your determinism check should run. This will ensure thhat your behaviors if for example don't occur until a set time you are able to extend this limit for the Health Check to catch any possible issues. By default this value is 3 ticks.
The Determinism Health Check will also provide detailed info on where the issue occurs by telling you the first caught instance of Model Values, Agents, or Links that have differing values. Used in conjunction with Atomic Logging this will indicate where in your model you should investigate potential randomness in your model.
\nA random number generator defined by the user will not use the seed defined in a model's configuration. This generator's seed is not controlled, so determinism is not enforced.
\nRandom r = new Random();\nr.nextBoolean();A model cannot create repeatable results if its numeric seed varies between simulation runs.\nIn this example, a different time would be computed each time the model is called, so the seed would change every time.
\nlong seed = System.currentTimeMillis();\nSeededRandom prng = SeededRandom.create(seed);\nprng.generator.nextDouble();Although the global state can be accessed and updated by any agent using the getGlobals function, doing so may result in non-deterministic behavior. Modifying global variables can have unforeseen effects on other parts of a model.\nIn this example, the agent updates the global state with its own value. Later in the code, the agent accesses this variable again to send a message to its neighbor. However, in the meantime, this variable could have been updated again. There is no certainty about its state.\nThis example is trivial, but updating the GlobalState from an agent is usually considered bad practice.
boolean isTrueLocal = true;\ngetGlobals().isTrueGlobal = isTrueLocal;\n...\n// Later in the agent, undefined behavior!\ngetLinks(BooleanLinks.class).send(BooleanMessage.class, getGlobals().isTrueGlobal);Globals allows you to define variables that can be accessed and modified by both the model and agents within the system. However, during the setup process when you are creating agents via an injector, you should not by modifying globals. This is due to Java 8 lambda's. If you wish to properly modify Globals, make sure it is part of the message passing action of an agent, or make usage of an accumulator.
Agents and messages are not processed in a specific order, so relying on message order will create randomness.\nIn this example, the loan request fulfillment depends on the ordering of messages. If some agents send a request, there is no certainty about which request will be accepted. This dependency on apparent ordering can be found in other places. Links, IDs of agents, and updates of the global state do not possess a proper order.
\nint liquidity = 1000;\nList<LoanRequest> allLoanRequest = getMessagesOfType(LoanRequest.class);\nfor(LoanRequest m: messages) {\n if(m.getBody() < liquidity) {\n liquidity = liquidity - m.getBody();\n getLinksTo(m.getSender()).send(LoanResponse.class, true);\n } else {\n getLinksTo(m.getSender()).send(LoanResponse.class, false);\n }\n}You can also avoid this by using an OrderedMessage see Messaging