This exercise is designed to help you define, design, and implement your own model in the Simudyne SDK. Whether you are\nnew to the agent-based modelling field, or a seasoned veteran, it is recommended that new users start here when building\nthe first of their own models in order to build a strong foundation in the core concepts and functionalities of the\ntechnology.
\nIf you have never built a model in the Simudyne SDK before, please read the below sections before beginning this\nexercise:
\n\nIt is also recommended that new users begin with some tutorials, sample models, and challenges before attempting this\nexercise:
\nEstimated time to complete: ~1 day
\nSections & topics covered:
\nThe objective of this exercise is to select a system of interest and build the first iteration of an agent-based model\nin the Simudyne SDK.
\nAt the end of this exercise you will have a simulation and data science workflow that includes the following:
\nIf you'd like to get a trial license to the Simudyne SDK, you can follow the link below to get access.
\n\nIf this is the first time you are building an agent-based model of any kind, we recommend starting\nwith What is ABM?, Tutorials, and Challenges which\nprovide you with an example use case and guide your through implementation. It will be easier to grasp the core concepts\nof the paradigm with provided examples.
\nOtherwise, If you have experience building agent-based systems or already have a model / system in mind that you would\nlike to simulate, this will be the best place to start.
\nEach section builds upon the previous and should be followed in order.
\nIterative and incremental development practices are key to Agile software development. The goal is to break down the\ndevelopment of a large application into smaller chunks. Code is designed, developed and tested in cycles. Each iteration\nsees the addition of new features to enhance the overall functionality of the application. At each stage of development,\nthe user should have a functional application.
\nBuilding agent-based models has a number of parallels to developing software. Building these types of models calls for\nthe adoption of a software developer's mindset.
\nRather than trying to build a large and complex model in one attempt, modellers should ensure that sensible model output\ncan be obtained at all stages of model development. Doing so requires the modeller to start by implementing a stripped\ndown version of the desired model. Model complexity is layered on incrementally, ensuring that each iteration of the\nmodel produces sensible output.
\nThis type of workflow is supported by Git version control. Each incremental increase in model complexity, such as the\nintroduction of a new agent type or the addition of a new method to an agent's behaviour, should be tested thoroughly.\nOnce the modeller is satisfied, the new version of the model can be committed to version history. Changes which break\nthe model's functionality can simply be rolled-back.
\nBranches support experimental model development. Modellers can create multiple branches from a model's master branch,\ntesting new concepts and functionalities in each one. When a modeller is satisfied with functionality in a branch, they\ncan merge that branch with the model's master branch.
\nWe've provided a starter project that includes a shell model for ease of getting started and setting up VCS before you\nstart building.
\n\nDownload Starter Project\nIt is not required, but it is recommended that you set up a GitHub repo or another VCS for maintaining this project before moving on to the next section.\n
An important part of building models is that their results should be repeatable if the same inputs are given to them.\nThe Simudyne SDK creates models that rely on numerical seeds that are randomly generated. A number of tools are provided\nfor random number generation, but if a model is built properly, it should still be deterministic with respect to its\nseed.
\nIt is easy to unintentionally introduce other sources of randomness into the model besides its numerical seed. The\noutput of a properly built model should only change under two conditions: if its input parameters change or if its\nnumerical seed is purposely changed. For the same model running with the same seed, the only source of change should be\nthe input parameters.
\nTo learn more about how to ensure determinism in your model, check\nout Determinism
\nIf you are looking to identify a use case or want to assess the suitability of one you have selected to the agent-based\napproach, check out What is ABM?
\nIf you already have a model that you want to implement and have defined specifications for that model, you can skip to\nthe next section.
\nOnce you have identified the system you wish to model, the next objective is to design a simplified version that begins\nto reproduce the dynamics of your real-world system.
\nComponents to identify:
\nLet's start with an example and look at how we approach simulating an equity market. The example being used in this\nsection is the Synthetic Market Tutorial.
\nAn equity market is made up of an exchange and market participants. We can visualize the structure of a market as below:
\n\n
The market is made up of the different types of traders that can represent anything from individuals / retail traders,\nto the tier 1 banks and large hedge funds.
\nAdditionally, the exchange has a complex set of protocols as well as an order book and matching engine.
\nLet's identify and simplify each component from the list above and use the equity market example for each one.
\nEmergent properties and phenomena arise when micro-level interactions produce a macro-level effect. In the case of the\nequity market, the price formation process is an emergent property generated by the varied buying and selling strategies of the market participants and the market mechanism.
\nA key advantage of an agent-based simulation is the ability to capture the non-linear dynamics of a complex adaptive system.\nUnderstanding how the micro leads to the macro can provide powerful insights into how one might optimise for or against\na particular macro outcome.
\nUsing the equity market example, emergent properties include: price, volatility, fire sales, etc. Let's say we select\nprice as the feature to reproduce first.
\nThe price is dictated by the buying and selling of the shares. Thus, we will need to simulate the buying and selling of\nshares by our virtual traders to generate a simple price formation process.
\nComponents to Identify (Equity Market Example):
\nIdentify the emergent properties of your system and select a single emergent phenomena to simulate.
Now that a desired emergent / reactive property has been selected we want to identify the types of agents involved in\nthe system and that contribute to the process.
\nAgent types should be defined based on their unique relationships and capabilities for interaction.
\nFor simplification purposes, we want to create the most undifferentiated version of our agent types. In the equity\nmarket example, the markets consist of an ecosystem of traders deploying different strategies at global exchanges. The simplified model needs just 1 basic trader type and 1 simple exchange.
\nWe could represent fundamental traders, momentum traders, market makers, etc. in our model. However, the first step will\nbe creating a basic trader type agent that sends simple orders to an exchange. The complexity of the trader and the\norder will be layered in after the mechanics of the market have been defined.
\nComponents to identify (Equity Market Example):
\nIdentify the basic agent type or types that will be necessary for your simulation. Focus on selecting the simplest abstraction of each participant in the system.
Agents are capable of reacting to their environment and interacting with other agents in the system. An agent-based simulation may consist of numerous complex sets of interactions and behaviors. The simplest form of\ninteraction should be captured first. This interaction should be driven by 1-2 variables.
\nIn the equity market example, the trader agents and exchange agents both have behaviors:
\nTrader Behaviors: decide when to buy / sell, send buy order, send sell order, receive market\ninformation\nExchange Behaviors: receive orders from traders, match orders / calculate price.
\nNotice that these behaviors are simple, and their logic will also be very simple in the beginning. More on the specifics\nof the equity market example can be found in the Behaviors Section of the Synthetic Market Tutorial.
\nComponents to identify (Equity Market Example):
\nIdentify the minimum set of behaviors required to reproduce the mechanics of your system. The aim is to minimize the amount of interactions and components needed to capture the dynamics.
Agents are programmed to interact with their environment and with other agents. The environment may be a spatial location\nof an agent relative to other agents, or it may provide a set of dynamically determined features, like the price of an\nequity or changes in interest rates.
\nIn the equity market example, the price of the equity, the policies at the exchange, the liquidity, real-world events,\netc. are all elements of the environment.
\nTo simplify the equity market environment, the price at the exchange will represent our main environment variable as this will be the minimum requirement to drive the trader behaviors.
\nComponents to identify (Equity Market Example):
\nIf your environment contains spatial elements, the below models may provide code or insight into how to account for\nspace. (The Simudyne SDK does not contain an explicit set of features for simulating 2D space):
\n\nIdentify the main environment variable that will influence the interactions of your system. Focus on identifying the feature of your environment that will drive agent behaviors
Once you have completed identifying the 4 key components of your system, you are ready to design the implementation of\nyour model.
\nNow that you have defined the basic components of your model, the objective of this section is to design\nthe structure of your code following some best practices in the Simudyne SDK before you begin your implementation.
\nOnly some best practices are mentioned in this section, more information that may be relevant to your model can be found\nin the Reference.
\nUse the structure of the starter project provided in the Iterative Model Building section and refactor the classes to match the specifications from the previous section.\n
The agents within models can be arranged in groups where each group of agents represents a larger entity, such as a pool\nof investors. These groups can be connected together by creating links between agents that span the groups. When two\ngroups are being connected together, one group is considered the \"source\", while the other is the \"target\". When two\ngroups are connected together, the usual layout of those connections is to link every agent in the source group with\nevery agent in the target group.
\nIf the number of agents in the source group is represented by M, and the number of agents in the target group is\nrepresented by N, it takes M x N links to connect the two groups completely. This works well for small models, where\nthere are less than one million agents in total, but the number of connections can skyrocket as the number of agents\nincreases. The large number of connections can cause major slowdowns in model execution.
\nModels can quickly grow to have many actions with splits in a single sequence. Adding the implementation logic for\nagents in the same place can make the sequence of actions hard to follow.
\nActions should be created by functions inside agents. The functions should have clear names indicating the action's\npurpose. With purposeful naming, the sequence of steps becomes a sequence of clear action names, rather than a sequence\nof code that is hard to read.
\nMessages should be defined in a shared message class so they can be used by the entire model. Individual messages should\nbe defined as static classes inside the larger message class. Do not define messages inside agents, inside a model, or\nas many separate classes. This can lead to code duplication and difficulty in class maintenance.
\nThe Simudyne SDK provides built-in classes for messages which contain a single primitive type (integer, long, double,\nfloat, boolean) or an empty body. Modellers need only extend these built-in classes to get all the functionality they\nneed.
\npublic class Messages {\n\n // Custom message classes that extend the built-in message type for doubles\n public static class Bid extends Message.Double {\n }\n\n public static class Vacancy extends Message.Double {\n }\n}If a message needs to pass multiple different primitive types, but no complex objects or behaviour, extend the Simudyne\nSDK Message object.
// Message class for price quotes, which passes only primitive types.\npublic class Messages {\n public static class PriceQuoteMessage extends Message {\n double price;\n double reducedPrice;\n }\n}\n\n// Class demonstrating usage of price quote messages.\npublic class Seller extends Agent<GlobalState> {\n public static Action<Seller> sendPriceQuote() {\n return Action.create(\n Seller.class,\n seller -> {\n seller\n .getLinks(Links.BankLink.class)\n .send(\n Messages.PriceQuoteMessage.class,\n message -> {\n message.price = 3;\n message.reducedPrice = 2.3;\n };\n );\n };\n );\n }\n}To send a complex data type, extend the Simudyne SDK Message.Object<T> generic object. Provide the name of the complex\ndata type object in place of the \"T\" variable. When an agent receives a message containing a complex data type object,\nthat agent has access to the complex data type's functions.
// Message class for price quotes which passes a complex data object.\npublic class Messages {\n public static class PriceQuoteMessage extends Message.Object<PriceQuote> {\n }\n}\n\n// Class demonstrating usage of complex price quote messages.\npublic class Seller extends Agent<GlobalState> {\n public static Action<Seller> sendPriceQuote() {\n return Action.create(\n Seller.class,\n seller -> {\n seller\n .getLinks(Links.BankLink.class)\n .send(Messages.PriceQuoteMessage.class, new PriceQuoteMessage(...))\n };\n );\n }\n}When multiple agent types need to share some common functionality, modellers can reduce code duplication and build\nbetter defined agents using inheritance. Extend the Simudyne SDK Agent class with the base class, and then the derived\nclasses can be implemented with their own unique functionalities. In the following example, an Accommodation agent is the\nbase for two derived agent types, Hotel and Flat. All of these agent types can be used just like other agents which\ndon't implement inheritance.
\n// Accommodation base class.\npublic class Accommodation extends Agent<GlobalState> {\n public int size;\n\n public Action<Accommodation> sendVacancyMessage() {\n return Action.create(\n Accommodation.class,\n accommodation -> {\n // Send message if vacant.\n };\n );\n }\n}\n\n// Flat derived class.\npublic class Flat extends Accommodation {\n public Action<Flat> registerNewHousehold() {\n return Action.create(\n Flat.class,\n flat -> {\n // Register a new flat.\n };\n );\n }\n}\n\n// Hotel derived class.\npublic class Hotel extends Accommodation {\n public Action<Hotel> registerBooking() {\n return Action.create(\n Hotel.class,\n hotel -> {\n // Make a new booking.\n };\n );\n }\n}\n\n// Model containing actions for Accommodation, Hotel, and Flat.\npublic class myModel extends AgentBasedModel<GlobalState> {\n @Override\n public void step() {\n run(\n Accommodation.sendVacancyMessage(),\n Household.requestHome(),\n Split.create(\n Flat.registerNewHousehold(),\n Hotel.registerBooking()\n ); \n );\n }\n}External classes should be used for functionality that is not specific to agents. This functionality may be needed by\nmultiple agents or by the model, but should not be unique to a specific agent type. A data loader or distribution\nbuilder could both be reasonable uses for these external classes. Methods in these classes should be static so that they can\nbe accessed from anywhere in a model.
\n// External distribution class.\npublic class Distribution {\n public static EmpiricalDistribution loadDistribution() {\n // Load a distribution.\n }\n}\n\n// Flat agent class which uses the distribution class.\npublic class Flat extends Agent<GlobalState> {\n public Action<Flat> registerNewHousehold() {\n return Action.create(\n Flat.class,\n flat -> {\n EmpiricalDistribution distribution = Distribution.loadDistribution();\n };\n );\n }\n}Once you have a plan and design for how you wish to implement your model you are ready to move on to the next section.
\nNow that you have designed and specified the structure of your model and all its components, the objective of this\nsection is to implement the logic and compile your code.
\nThe starter project provided above can be used as a template, it contains many of the structures and best practices\nmentioned in previous sections.
\nUsing the output of the previous section, implement the model you specified and make sure you can compile your simulation and pull it up in the interactive console layer.
If at any point you get stuck with the implementation of your model, hop into our Community Discord Server and ask a\nSimudyne Dev for help!
\n\n\tDiscord Server\nNow that you have successfully implemented your model and are able to pull it up in the console, the objective of this\nsection is to experiment with the features and develop a useful dashboard to visualise the dynamics of your\nsimulation.
\nThe below sections contain relevant information on how to design the layout of your console:
\n\nThere is also a public demos site that contains live simulation demos that can be run and may inspire your layout:
\n\n\tView Demo Site\n\nUsing the resources above and your implemented model, expose input parameters, set up charts using @Variable annotations, and build custom accumulators to explain the output of your system.
The console layer is a valuable feature during the conceptual phase of model building. Once the model is\nsufficiently developed, and its behavior needs to be analysed, the SDK is run and deployed in headless mode for\nperformance and scalability.
\ncore-abm.serialize.agents=true\ncore-abm.serialize.links=true\ncore-abm.serialize.accumulators=trueThe console is a powerful prototyping, debugging, and high-level analysis tool. It is not intended to replace the\npopular and advanced data science packages in Python, or other advanced analytics platforms and tools. The Simudyne SDK is\nalso designed to be run headless as one of the key advantages of the software is its ability to swap out different\nbackends for distributing your models using Spark or Akka.
\nConfiguring the SDK to run headless will be the first step towards getting the SDK hooked up to your Jupyter Notebook.
\nThe objective of this section is to learn how to bypass the console layer for running your experiments at speed and\nscale.
\nRelevant sections that provide more detail on the possible configurations of this run mode can be found in the resources\nbelow:
\n\nA separate Main.java class should be created to contain the headless runner code, an example has been provided below:
\npublic class MainHeadless {\n public static void main(String[] args) {\n //Warp in try catch\n try {\n //set up a ModelRunner\n RunnerBackend runnerBackend = RunnerBackend.create();\n ModelRunner modelRunner = runnerBackend.forModel(MyModel.class);\n\n //Define a set of batch runs using BatchDefinitionsBuilder\n BatchDefinitionsBuilder runDefinitionBuilder =\n BatchDefinitionsBuilder.create()\n .forRuns(100) // a required field, must be greater than 0.\n .forTicks(1000); // a required field, must be greater than 0.\n\n modelRunner.forRunDefinitionBuilder(runDefinitionBuilder);\n\n // To run the model and wait for it to complete\n modelRunner.run();\n\n } catch (RuntimeException e) {\n System.out.println(Arrays.toString(e.getStackTrace()));\n e.printStackTrace();\n }\n }\n}The above example uses the BatchDefinitionsBuilder, however there are other tools for setting up experiments in the SDK using ModelSamplerDefinitionsBuilder or the ScenarioDefinitionsBuilder. More on the differences between these features can be found in Multirun Setup.
Use the example provided above or the other run definitions builders provided to set up a headless main for running your simulations
Now that you have a headless main class and an interactive console main, data outputting can be set up for importing and exporting data.
\nYour models can output and input data regardless of interactive console or headless running mode. The objective of this section is to set up any input data channels (if they exist) and configure data outputs, for analysing results.
\nThe focus on this section will be on output data. Input data can be ingested in multiple ways and is less general and more specific to your model depending on whether your data is related to the network, initial agent states, interactions, etc.
\nMore information on input data can be found in the following sections:
\n\nOnce configured, the Simudyne SDK automatically outputs simulation data in a structured and labelled format.
\nData can be exported in the following formats:
\nData can either be exported automatically using the model schema, via custom Simudyne SDK I/O channels, or via a user-defined method.
\nAutomatically exporting data is the fastest way to begin studying your agents and the system.
\nThe following configurations can be added to your simudyneSDK.properties file to set up automatic exporting via the model schema.
\nEach configuration below will also require core.export-path=output to be added to the properties file. output can be swapped with the relevant file path or desired directory name which will be created in the projects root directory.
core.parquet-export.enabled=true\nfeature.interactive-parquet-output=truecore.json-export.enabled=truecore.csv-export.enabled=truecore.export.username=default\ncore.export.password=work12345\ncore.sql-export.enabled=true\ncore.sql-export-path=jdbc:mysql://localhost:3306/sdkcore.export.username=default\ncore.export.password=work12345\ncore.hive-export.enabled=false\ncore.hive-export-path=hive2://localhost:10000/defaultOnce you have added one of the above options you will see data exported in the designated folder.
\nFor more information on data outputting, check out the following sections:
\n\nNow that data exporting has been configured and the state of every agent and the network are being dumped at each step, the model is ready for analysis in a data science tool or workflow.
\nHooking up your simulation to your preferred data science toolkit can be as simple as setting your data export path to a location that your Jupyter Notebook or data science toolkit can access.
\nAdditionally, and because the models built in the Simudyne SDK are packaged as a Java JAR file, it is possible to run the Simudyne SDK using a Python subprocess where you can parameterize and run models from a notebook. More information on this topic can be found in the Jupyter Notebook Tutorial.
","headings":[{"value":"Introduction","depth":2},{"value":"Iterative Model Building","depth":2},{"value":"Repeatable Models","depth":2},{"value":"Use Case Definition","depth":2},{"value":"1. Emergent / Reactive Properties","depth":3},{"value":"2. Agent Types","depth":3},{"value":"3. Agent Behaviors & Interactions","depth":3},{"value":"4. Environment - physical, social, economical, etc","depth":3},{"value":"Model Design & Class Organization","depth":2},{"value":"Groups of Agents","depth":3},{"value":"Actions and Sequences","depth":3},{"value":"Messages","depth":3},{"value":"Agents And Inheritance","depth":3},{"value":"External Classes","depth":3},{"value":"Implementation","depth":2},{"value":"Interactive Console Mode","depth":2},{"value":"Headless (BackendRunner) Mode","depth":2},{"value":"Data Input & Output","depth":2},{"value":"Parquet","depth":3},{"value":"JSON","depth":3},{"value":"CSV","depth":3},{"value":"MySQL","depth":3},{"value":"H2","depth":3},{"value":"Analyzing Results with Jupyter or Another Data Science Tool","depth":2}],"frontmatter":{"title":"Build Your First Model","toc":true,"experimental":null}},"site":{"siteMetadata":{"title":"Simudyne Docs","latestVersion":"2.6"}}},"pageContext":{"absolutePath":"/home/vsts/work/1/s/content/2.6/docs/overview/model_builder.md","versioned":false,"version":"2.6","kind":"docs","pagePath":"/overview/model_builder","chronology":{"prev":{"name":"Setup","path":"/overview/setup"},"next":{"name":"Introductory Course","path":"/overview/intro_course"}},"lastUpdated":"2026-04-21T13:56:54.866Z"}}