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.

Traders 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).

Realistic price dynamics (e.g. stylised facts) emerge from the model based on simple behavioural rules and the interaction of heterogeneous agents.

The 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.

Download Tutorial Files

From 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/.

Console

Once you've opened the local server, you will be greeted by the model selection landing page:

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.

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.

For now we can leave things as they are, and click Initialise, upon which a few more elements become active.

We now have a set of charts, showing different outputs of our model. Because we have only just setup, there is only a single tick of data to inspect. However, some of these charts are showing top level values, whereas others are showing aggregations over agent attributes. You can tell the difference by colour, and by the information in the lower left of agent level charts, showing the type of agent, and how many agents of that type are present.

In this model, there is a single Market agent, which holds a price. A more interesting chart is the TradingThres on the Trader agents. Each agent gets their own trading threshold from a distribution, and we can see this is the case by changing the aggregation mode of the chart, available through the ··· menu to the right of the name.

If your charts view gets cluttered, you can turn on and off different charts from the data search bar at the top.

What also become active once the model was setup, was the top right View selector. By default we are on the Variables view, showing the numeric outputs of the model. The other two views available are the Network and the Agents. Agents shows a tabular view of the agents within the model, which can be useful with small numbers of agents to check their exact properties. Network is useful to see the overall structure of the agents and their links. In this particular model, there is a single central agent, with all other agents connected, giving a hub and spoke layout.

The top left menu allows to specify an attribute of each agent type to use as the scale factor for each node in the visualisation, and the top right allows to switch between different layout approaches.

Project Structure

The downloaded zip consists of files defining a Maven build. Some of these files will be common to every Simudyne model project, while others are specific to the model being built.

/README.md                # Human readable description
/pom.xml                  # Maven configuration (dependencies, etc)
/simudyneSDK.properties   # Simudyne SDK configuration
/.gitignore               # Git version control ignore rules

/src/main/resources/log4j.properties              # Logging configuration

/src/main/java/Main.java                          # Application entrypoint
/src/main/java/models/trading/TradingModel.java   # Model class
/src/main/java/models/trading/Trader.java         # Agent class
/src/main/java/models/trading/Market.java         # Agent class
/src/main/java/models/trading/Messages.java       # Message classes
/src/main/java/models/trading/Links.java          # Link classes

/src/test/java/models/trading/MarketTest.java     # Market behavioural tests
/src/test/java/models/trading/TraderTest.java     # Trader behavioural tests

Project configuration and documentation

The top level files define some project configuration and helpful documentation.

• README.md is a markdown file, and a good place to put documentation relating to the model for others (and yourself) to refer to. If hosted on version control services such as GitHub or BitBucket then it will display nicely to other users.
• pom.xml contains the Maven configuration, and is where you can change or add dependencies to your project. This is important for changing version of the SDK, as well as adding additional libraries you may need for modelling.
• simudyneSDK.properties allows configuration of the SDK libraries, such as enabling, disabling or tuning certain features.
• .gitignore is a file for the Git version control system, to ignore certain files from being tracked. These files include files generated by compilation (inside the target folder) as well as caches created by IDE programs such as IntelliJ or Eclipse.
• log4j.properties inside resources defines a default logging setup, writing helpful information to the console. More information on configuration of logging can be found in the reference.

Model definition

The files under /src/main/java define your project.

Main.java defines the entrypoint for your application. The included file is setup to simply register the TradingModel (with a name) and start the server. Your project can include multiple models, but you should think carefully if you need to collaborate with others. A separate project per model will make collaborating and versioning each individual model easier.

The model files themselves are then inside models/trading. The Java convention is to use packages, where a package matches the folder structure to the file itself. So the model class models.trading.TradingModel is located at models/trading/TradingModel.java.

• TradingModel.java defines the model itself (referred to as the Model class).
• Agents are then defined in their own files, each defining a single Agent class of the same name.
• By convention, message and link classes are nested inside a wrapping class, to help reduce the number of files.

Model testing

The final files are tests for the Market and Trader agent behaviours. The Simudyne SDK includes utilities called TestKit for helping test Actions (the unit of behaviour). These can help you verify that your actions operate as expected, especially helpful when making later changes that could introduce errors.

Model

The Model class (TradingModel, inside TradingModel.java) is the root of your model. Broadly, it ties together 3 concerns:

• Initialisation

  • Define global state, including accumulators
  • Define inputs and outputs of the model
  • Register Agent and Link types

• Setup

  • Create the agents within the model (from the console, this is what happens when the Initialise button is pressed).

• Simulation

  • Define a step method which moves the simulation from one tick to the next.

Initialisation

Initialisation covers any top level fields on the model, the Globals class, as well as an implementation of the init method.

Model Fields

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

@Constant(name = "Number of Traders")
public 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:

• @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.

Globals

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

public static final class Globals extends GlobalState {
  @Input(name = "Update Frequency")
  public double updateFrequency = 0.01;

  @Input(name = "Lambda")
  public double lambda = 10;

  @Input(name = "Volatility of Information Signal")
  public double volatilityInfo = 0.001;

  public double informationSignal;
}

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.

Accumulators

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).

Accumulators can be either Long (64bit integer) or Double (64bit floating point), created through createLongAccumulator/createDoubleAccumulator.

TradingModel.java

createLongAccumulator("buys", "Number of buy orders");
createLongAccumulator("sells", "Number of sell orders");
createDoubleAccumulator("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.

Type registration

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

registerAgentTypes(Market.class, Trader.class);
registerLinkTypes(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.

Setup

Topology

Where 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.

TradingModel.java

Group<Trader> traderGroup = generateGroup(Trader.class, nbTraders);
Group<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.

TradingModel.java

traderGroup.fullyConnected(marketGroup, Links.TradeLink.class);
marketGroup.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.

Here 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.

Global Information Update

In 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

private void updateSignal() {
  getGlobals().informationSignal =
      getContext().getPrng().gaussian(0, getGlobals().volatilityInfo).sample();
}

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.

Super

A 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

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.

Super

The 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.

Run Sequences

TradingModel.java

updateSignal();

run(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).

Behaviours

We'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.

Trader#processInformation

Trader.java

@Variable
public double tradingThresh;

@Override
public void init() {
  tradingThresh = getPrng().gaussian(0, 1).sample();
}

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

public static Action<Trader> processInformation() {
  return action(
      trader -> {
        double informationSignal = trader.getGlobals().informationSignal;

        if (Math.abs(informationSignal) > trader.tradingThresh) {
          if (informationSignal > 0) {
            trader.buy();
          } else {
            trader.sell();
          }
        }
      });
}

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.

Trader.java

private void buy() {
  getLongAccumulator("buys").add(1);
  getLinks(Links.TradeLink.class).send(Messages.BuyOrderPlaced.class);
}

private void sell() {
  getLongAccumulator("sells").add(1);
  getLinks(Links.TradeLink.class).send(Messages.SellOrderPlaced.class);
}

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

public static class BuyOrderPlaced extends Message.Empty {}
public 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#calcPriceImpact

Market.java

public class Market extends Agent<TradingModel.Globals> {

  @Variable
  public double price = 4.0;
  int nbTraders;

  private static Action<Market> action(SerializableConsumer<Market> consumer) {
    return Action.create(Market.class, consumer);
  }

  public static Action<Market> calcPriceImpact() {
    return action(
        market -> {
          int buys = market.getMessagesOfType(Messages.BuyOrderPlaced.class).size();
          int sells = market.getMessagesOfType(Messages.SellOrderPlaced.class).size();

          int netDemand = buys - sells;

          if (netDemand == 0) {
            market.getLinks(Links.TradeLink.class).send(Messages.MarketPriceChange.class, 0);
          } else {
            double lambda = market.getGlobals().lambda;
            double priceChange = (netDemand / (double) market.nbTraders) / lambda;
            market.price += priceChange;

            market.getDoubleAccumulator("price").add(market.price);
            market
                .getLinks(Links.TradeLink.class)
                .send(Messages.MarketPriceChange.class, priceChange);
          }
        });
  }
}

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

public 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#updateThreshold

Trader.java

boolean shouldUpdateThreshold() {
  double updateFrequency = getGlobals().updateFrequency;
  return getPrng().uniform(0, 1).sample() <= updateFrequency;
}

public static Action<Trader> updateThreshold() {
  return action(
      trader -> {
        if (trader.shouldUpdateThreshold()) {
          trader.tradingThresh =
              trader.getMessageOfType(Messages.MarketPriceChange.class).getBody();
        }
      });
}

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.

Tests

Using 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.

TestKit (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.

MarketTest.java

public class MarketTest {

  private TestKit<TradingModel.Globals> testKit;
  private Market market;
  public static final int TARGET_LINK_ID = 1;

  @Before
  public void init() {
    testKit = TestKit.create(TradingModel.Globals.class);
    market = testKit.addAgent(Market.class);

    testKit.createDoubleAccumulator("price");

    market.addLink(TARGET_LINK_ID, Links.TradeLink.class);
  }

  // ...

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

  // ...

  @Test
  public void should_handle_zero_netDemand() {
    testKit.send(Messages.BuyOrderPlaced.class).to(market);
    testKit.send(Messages.SellOrderPlaced.class).to(market);

    TestResult testResult = testKit.testAction(market, Market.calcPriceImpact());
    Messages.MarketPriceChange expectedMessage =
        testResult.getMessagesOfType(Messages.MarketPriceChange.class).get(0);

    assertEquals(0, expectedMessage.getBody(), 0);
  }

  @Test
  public void should_handle_priceChange() {
    // Two buys and one sell makes a netDemand of 1
    testKit.send(Messages.BuyOrderPlaced.class).to(market);
    testKit.send(Messages.BuyOrderPlaced.class).to(market);
    testKit.send(Messages.SellOrderPlaced.class).to(market);

    double startingPrice = market.price;

    TestResult testResult = testKit.testAction(market, Market.calcPriceImpact());
    Messages.MarketPriceChange expectedMessage =
        testResult.getMessagesOfType(Messages.MarketPriceChange.class).get(0);

    double expectedPriceChange =
        (1 / (double) testKit.getGlobals().nbTraders) / testKit.getGlobals().lambda;

    assertEquals(0, expectedMessage.getBody(), startingPrice + expectedPriceChange);
  }
}

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.

Summary

Through 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.