In this introductory tutorial, we will cover all the components needed to make a simple agent-based model of traders trading in a stylised financial market such as a stock market. The model is comprised of traders and a common information signal observed by all traders, which we can think of as a 'news arrival' process. All traders compare this information signal to an internal trading threshold.
\nTraders place a buy order when they believe the trading signal is positive and a sell order when they believe the signal is negative. The net volume of buy and sell orders is then mapped through a function that generates a change in the asset price (e.g. stock price).
\nRealistic price dynamics (e.g. stylised facts) emerge from the model based on simple behavioural rules and the interaction of heterogeneous agents.
\nThe code for this tutorial is available as a zip download, containing a complete model as a Maven project. This project should be able to be run from any Maven or Java IDE environment.
\n\nFrom a command line you can then run (with Maven installed globally) mvn package exec:java to run the server. This will download all library dependencies, build the project, run any tests and then run the Simudyne server locally with the web console. You can then open the server at http://localhost:8080/.
Once you've opened the local server, you will be greeted by the model selection landing page:
\n\n
Clicking on \"Trading Model\" will take you into the console for that model. When the console is first opened, a model is not setup, and so there isn't much to show. The sidepanel contains the main controls for interacting with a models configuration/inputs.
\n\n
Initialise will setup your model using the defined parameters. After setup, some things cannot be changed (such as the seed, or constants for the model). You can open types of inputs using the headers. In this model we have a single constant, defining the number of traders in the simulation, along with 3 inputs controlling parameters of the trading process.
\nFor now we can leave things as they are, and click Initialise, upon which a few more elements become active.
\n\n
\n
If your charts view gets cluttered, you can turn on and off different charts from the data search bar at the top.
\n\n init and not within the constructor or during field declaration.
Defining inputs and outputs can be done through fields on your Model class. These define model-level properties that only the top level model has access to (agents cannot access these). These fields are useful for defining model constants needed for setup, as well as variables that are computed by the model at the top level.
TradingModel.java
\n@Constant(name = \"Number of Traders\")\npublic long nbTraders = 1000;Fields (on the model, as well as within Globals or on Agents or Links) can be annotated to make them visible to the SDK. There are 3 common annotations needed for most models:
\n@Input denotes a field as being accessible by the outside world, and available at any time during the simulation. This is useful for parameters that may be controlled by an end user, or exogeneous factors to be varied by scenarios.@Constant denotes an @Input which can only be changed prior to setup. This is useful for fixed parameters of the model, such as the initial number of agents, which will make no difference after setup has been called.@Variable denotes an output of the model, which is available only after setup has been called. This means it is safe for fields marked as @Variable to be uninitialised, as long as they are initialised by the setup method.
@Variable can also be used to annotate methods. The method must take no argument, and return a supported type. The method will only be called after setup has been run, and so can depend on internal state such as agents being initialised.If you are using Java version 9 or above, you will need to make all annotated fields or methods public. On Java version 8, fields and methods can also be private or package-private.
A Simudyne ABM makes visible to all agents a single instance of a class extending simudyne.core.abm.GlobalState, as defined by the type in extends AgentBasedModel<TradingModel.Globals>. This class may exist in another file, but by convention it is placed inside the Model class as a public static final class.
Fields on the Globals class can be annotated as with fields. The console interface will treat any annotated fields on the Globals just like fields on the Model class itself.
The Globals class is accessible to all agents within the system, however agents should not mutate (change) any fields in this object. Because agents operate in parallel, the results of agents modifying any information in the Globals class is undefined. Agents should instead contribute to global statistics either eagerly (through Accumulators) or lazily (through model-level queries into agent state).
TradingModel.java
\npublic static final class Globals extends GlobalState {\n @Input(name = \"Update Frequency\")\n public double updateFrequency = 0.01;\n\n @Input(name = \"Lambda\")\n public double lambda = 10;\n\n @Input(name = \"Volatility of Information Signal\")\n public double volatilityInfo = 0.001;\n\n public double informationSignal;\n}Note that informationSignal does not have an annotation. This field will be available inside the system and the agents, but will not be available on the console, or in any data export. The other fields are marked as @Input, allowing you to change these values from the console. These parameters are taken from the Rama Cont paper, and are used to tune the behaviour of the agents in the model. By using Globals these parameters can then be used by behaviours on the agents.
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.
Accumulators can be thought of as named numeric counters that agents can read, add or remove from. As agents act in parallel, they will not see updates to the accumulator within a single phase (even their own), but every agent will see the same value of the counter on the next phase (with all changes to the accumulator from all agents summed together).
\nAccumulators can be either Long (64bit integer) or Double (64bit floating point), created through createLongAccumulator/createDoubleAccumulator.
TradingModel.java
\ncreateLongAccumulator(\"buys\", \"Number of buy orders\");\ncreateLongAccumulator(\"sells\", \"Number of sell orders\");\ncreateDoubleAccumulator(\"price\", \"Price\");We have here created 3 accumulators, identified by a key, e.g. buys, and a friendly display name for the console, e.g. Number of buy orders. Note that the display name is optional, so you could have createDoubleAccumulator("price") if you were happy with that name appearing on the console.
The buys and sells accumulators are used to report on when individual traders are buying and selling, while the price accumulator is used by the Market to report the changing price.
As part of initialisation, you also need to register all Agent and Link types that will be used in the simulation. This allows the SDK to properly handle and output data for these types, even if they might be created dynamically.
TradingModel.java
\nregisterAgentTypes(Market.class, Trader.class);\nregisterLinkTypes(Links.TradeLink.class);In this model we have two agent types, and a single link type, as shown above. We'll see how these Agent and Link types are brought to life next, in setup.
\nWhere init is concerned with declaring the component pieces of a model, the setup method is concerned with declaring an initial state for our model using those pieces. At the time that setup is called, a user on the console (or other client to the model) will have had the chance to change inputs and constants. The setup method can then take these inputs and customise the creation of the model accordingly.
Creating the initial agents is done through the concept of a topology of groups. A group represents a parameterised set of agents, where each group has a type of agent, a number of agents in that group, and optionally an initialiser, which can customise the state for each agent.
\nTradingModel.java
\nGroup<Trader> traderGroup = generateGroup(Trader.class, nbTraders);\nGroup<Market> marketGroup = generateGroup(Market.class, 1, market -> market.nbTraders = nbTraders);In this model we have a group of traders, the size of which is taken as an input, and a group of markets, just the one. As part of its logic, the Market also needs to know how many traders there are. We could place this information into the Globals, however as it doesn't change then we can place it directly into the market. This also allows a possible extension later, where the Market can maintain this information itself, should we make the number of traders dynamic. We use a Java lambda function, which takes the created market and updates its attribute.
We're programmatically defining agents here, as it's quick to get started, but you can also load groups from external data sources.
\nTradingModel.java
\ntraderGroup.fullyConnected(marketGroup, Links.TradeLink.class);\nmarketGroup.fullyConnected(traderGroup, Links.TradeLink.class);With the groups in place, we now need to give them knowledge of each other. This is done through links, which represent knowledge agents have of other agents. In the simple case, the link itself has no attributes, which means it simply represents knowledge that another agent exists. Here we use a pre-defined connector, which gives every agent in that group a link to every agent to the target group. There are many other strategies for linking agents together, including loading from data sources, detailed in the reference on topologies.
\nHere we give each trader a link to the market, and the market links to all traders. Links are unidirectional, and only visible to the originating group.
\nIn this model, there is a global information signal, which is drawn from a gaussian distribution, parameterised on its variance by the volatilityInfo global @Input. As this needs to be initialised at setup, and at each step of the model, we pull that logic out into a separate method, and then call it within both setup and step.
TradingModel.java
\nprivate void updateSignal() {\n getGlobals().informationSignal =\n getContext().getPrng().gaussian(0, getGlobals().volatilityInfo).sample();\n}We use the PRNG from our models context to sample from a gaussian distribution. Using the context means our PRNG seed can be controlled automatically by the Simudyne SDK, allowing for guarantees around reproducibility.
\nA vital final part of setup is to call super.setup(). This tells the underlying system to actually initialise and setup the topology we have described. Usually this will be the last part of your setup method, however a useful pattern can be to call step at the final part of setup. This runs the model forward a step, and can be very useful to avoid a jump on a chart for example, should the agents need to run forwards initially to produce sensible values.
Step is called once every time the model is run forwards a step. Step takes care of the logic that happens between each tick, in an ABM this is mostly concerned with running behavioural sequences over the system to move the system forwards through time.
\nThe start of step calls super.step, signalling to the system that another step is beginning. This performs general lifecycle hooks necessary for agents, and other tasks such as resetting any non-persistent accumulators back to 0.
TradingModel.java
\nupdateSignal();\n\nrun(Trader.processInformation(), Market.calcPriceImpact(), Trader.updateThreshold());As mentioned before, this is also the time to update our information signal. Along with that, we run a sequence of actions. In this model, this consists of running the Trader#processInformationm Market#calcPriceImpact and Trader#updateThreshold actions in sequence. The general idea is that this allows all traders to run processInformation, and then any markets that receive message will get to process during the calcPriceImpact, and again any traders receiving information from the market will get to update. We'll look at these behaviours in depth soon.
The important thing to note above is that only agents that receive messages get to act. The first action in any sequence is special, as at that point every agent gets to act (otherwise no agent would ever get to act, which would be unfortunate).
\nWe'll run through the actions in this sequence in order, to see how they progress. When we see each agent for the first time, we'll also have a quick look at how it's defined.
\nTrader.java
\n@Variable\npublic double tradingThresh;\n\n@Override\npublic void init() {\n tradingThresh = getPrng().gaussian(0, 1).sample();\n}Our Trader is defined as an agent, which has a tradingThreshold. This trading threshold is initialised separately per agent, through its own init method, drawing their initial threshold from a gaussian of mean = 1, standard deviation = 1. Each agent has their own PRNG, available through getPrng(), which is similarly carefully controlled by the Simudyne SDK to be a good source of randomness, and controllable for repeatability.
Trader.java
\npublic static Action<Trader> processInformation() {\n return action(\n trader -> {\n double informationSignal = trader.getGlobals().informationSignal;\n\n if (Math.abs(informationSignal) > trader.tradingThresh) {\n if (informationSignal > 0) {\n trader.buy();\n } else {\n trader.sell();\n }\n }\n });\n}Our action is a function that operates on a given trader. In this models formulation, each agent observes the global information signal. If the signal is above their threshold (either higher or lower) then the agent executes a buy or sell trade, depending on if the signal is negative or positive.
\nTrader.java
\nprivate void buy() {\n getLongAccumulator(\"buys\").add(1);\n getLinks(Links.TradeLink.class).send(Messages.BuyOrderPlaced.class);\n}\n\nprivate void sell() {\n getLongAccumulator(\"sells\").add(1);\n getLinks(Links.TradeLink.class).send(Messages.SellOrderPlaced.class);\n}These helper methods pull the logic of the trader out, so they are easier to see in isolation, separate from the logic of whether it is a buy or sell that is executed. In each case, we update the global information on buys or sells occuring. We then also send the actual message through to the market. We do this by selecting our links (knowing that the only TradeLink the trader has is to the market), and send a message along that link.
Messages.java
\npublic static class BuyOrderPlaced extends Message.Empty {}\npublic static class SellOrderPlaced extends Message.Empty {}These message are empty messages, as defined in the Messages container class, serving as signal messages to the market. In a more elaborate model you could add properties to these messages, indicating the amount to buy, at what price, etc.
Market.java
\npublic class Market extends Agent<TradingModel.Globals> {\n\n @Variable\n public double price = 4.0;\n int nbTraders;\n\n private static Action<Market> action(SerializableConsumer<Market> consumer) {\n return Action.create(Market.class, consumer);\n }\n\n public static Action<Market> calcPriceImpact() {\n return action(\n market -> {\n int buys = market.getMessagesOfType(Messages.BuyOrderPlaced.class).size();\n int sells = market.getMessagesOfType(Messages.SellOrderPlaced.class).size();\n\n int netDemand = buys - sells;\n\n if (netDemand == 0) {\n market.getLinks(Links.TradeLink.class).send(Messages.MarketPriceChange.class, 0);\n } else {\n double lambda = market.getGlobals().lambda;\n double priceChange = (netDemand / (double) market.nbTraders) / lambda;\n market.price += priceChange;\n\n market.getDoubleAccumulator(\"price\").add(market.price);\n market\n .getLinks(Links.TradeLink.class)\n .send(Messages.MarketPriceChange.class, priceChange);\n }\n });\n }\n}The Market is solely defined by two fields (one a reported @Variable) and single action, and this is shown in full above (less imports). Again the behaviour is represented as a function of the market. This time we pull out the trade messages the market has received. In this formulation from the paper, the net demand (difference in buys and sells) is used to calculate an impact on the price. The resulting change in the price is then sent to all agents (remembering the Market is fully connected to all traders) using a MarketPriceChange message.
Messages.java
\npublic static class MarketPriceChange extends Message.Double {}The message itself is defined similarly as before. This time however, it extends a helper class Message.Double, which represents a message containing a single double (64 bit floating point) variable.
Trader.java
\nboolean shouldUpdateThreshold() {\n double updateFrequency = getGlobals().updateFrequency;\n return getPrng().uniform(0, 1).sample() <= updateFrequency;\n}\n\npublic static Action<Trader> updateThreshold() {\n return action(\n trader -> {\n if (trader.shouldUpdateThreshold()) {\n trader.tradingThresh =\n trader.getMessageOfType(Messages.MarketPriceChange.class).getBody();\n }\n });\n}The traders then receive the change in the price. Depending on some update frequency (defined globally), the trader will update its threshold to be equal to the change in the price.
\nUsing the Simudyne TestKit, we have created the following tests to check the behavior of the trader and market is as required. To read more about the TestKit and how you can use it to test the actions you created in your models, see Test Kit.
\nTestKit (and unit testing in general) helps to confirm that small units of logic are correct, so that building larger models from smaller tested componients is easier.
\nMarketTest.java
\npublic class MarketTest {\n\n private TestKit<TradingModel.Globals> testKit;\n private Market market;\n public static final int TARGET_LINK_ID = 1;\n\n @Before\n public void init() {\n testKit = TestKit.create(TradingModel.Globals.class);\n market = testKit.addAgent(Market.class);\n\n testKit.createDoubleAccumulator(\"price\");\n\n market.addLink(TARGET_LINK_ID, Links.TradeLink.class);\n }\n\n // ...In our Market tests, we setup a helper init method, which is run @Before all tests. This creates a new testing model environment, adds a single agent, accumulator, and a testing link.
MarketTest.java
\n // ...\n\n @Test\n public void should_handle_zero_netDemand() {\n testKit.send(Messages.BuyOrderPlaced.class).to(market);\n testKit.send(Messages.SellOrderPlaced.class).to(market);\n\n TestResult testResult = testKit.testAction(market, Market.calcPriceImpact());\n Messages.MarketPriceChange expectedMessage =\n testResult.getMessagesOfType(Messages.MarketPriceChange.class).get(0);\n\n assertEquals(0, expectedMessage.getBody(), 0);\n }\n\n @Test\n public void should_handle_priceChange() {\n // Two buys and one sell makes a netDemand of 1\n testKit.send(Messages.BuyOrderPlaced.class).to(market);\n testKit.send(Messages.BuyOrderPlaced.class).to(market);\n testKit.send(Messages.SellOrderPlaced.class).to(market);\n\n double startingPrice = market.price;\n\n TestResult testResult = testKit.testAction(market, Market.calcPriceImpact());\n Messages.MarketPriceChange expectedMessage =\n testResult.getMessagesOfType(Messages.MarketPriceChange.class).get(0);\n\n double expectedPriceChange =\n (1 / (double) testKit.getGlobals().nbTraders) / testKit.getGlobals().lambda;\n\n assertEquals(0, expectedMessage.getBody(), startingPrice + expectedPriceChange);\n }\n}We then define two test cases, once for the case of there being no net demand, and the other for there being a net demand of 1 (2 - 1). In each case, we check that the sent price change (out of our test result) equals the right value. In the future, when we make changes, if this logic should break, then this test will start failing. When using the build command at the start (mvn package exec:java) the tests will be automatically run each time.
The tests for the trader proceed similarly, testing their behaviour in regards to the information signal.
\nThrough this tutorial we have walked through the initial features to get started with, both on the console and in the definition of the models themselves. The next tutorial, based around building a model of mortgages issued by banks, goes much further into more advanced behaviours, as well as through the initial model building steps, when starting from scratch.
","headings":[{"value":"Console","depth":2},{"value":"Project Structure","depth":2},{"value":"Project configuration and documentation","depth":3},{"value":"Model definition","depth":3},{"value":"Model testing","depth":3},{"value":"Model","depth":1},{"value":"Initialisation","depth":2},{"value":"Model Fields","depth":3},{"value":"Globals","depth":3},{"value":"Accumulators","depth":3},{"value":"Type registration","depth":3},{"value":"Setup","depth":2},{"value":"Topology","depth":3},{"value":"Global Information Update","depth":3},{"value":"Super","depth":3},{"value":"Step","depth":2},{"value":"Super","depth":3},{"value":"Run Sequences","depth":3},{"value":"Behaviours","depth":2},{"value":"Trader#processInformation","depth":3},{"value":"Market#calcPriceImpact","depth":3},{"value":"Trader#updateThreshold","depth":3},{"value":"Tests","depth":2},{"value":"Summary","depth":1}],"frontmatter":{"title":"Synthetic Market Tutorial","toc":true,"experimental":null}},"site":{"siteMetadata":{"title":"Simudyne Docs","latestVersion":"2.6"}}},"pageContext":{"absolutePath":"/home/vsts/work/1/s/content/2.4/docs/tutorials/trader.md","versioned":true,"version":"2.4","kind":"docs","pagePath":"/tutorials/trader","chronology":{"prev":{"name":"Tutorials","path":"/tutorials"},"next":{"name":"Mortgage Portfolio Tutorial","path":"/tutorials/mortgage"}},"lastUpdated":"2026-04-21T13:56:54.849Z"}}