The Simudyne SDK allows you to define topologies, that is pairs of groups of agents equipped with a strategy of connection that defines links between them.
\nThe following section will guide you through:
\nGroups and Connectors.Connectors available and some of their advanced features.Group using probabilistic distributions defining the graph properties.Agent-Based Modelling aims to provide a bottom up approach to simulating different situations. With entities, called agents, that have their own behaviour and interact with one and other.
\nIn the Simudyne SDK, those interactions are made possible through message passing. As we shall see, Links are a good way to ease this process.
\nIt is necessary to register Agents and Links in the init of your model. This is required in order to assure that the shape of your data remains constant during the course of the simulation.
To register links and agents simply call the provided methods passing in all of the Agents and Links you require.
AgentBasedModels (Java)
\n@Override\npublic void init() {\n registerAgentTypes(MyAgent.class);\n registerLinkTypes(MyLink.class);\n}Each Agent can register links from itself to others agents. Its links allow it to have a reference to other agents it knows or it communicates with so that it can send messages to them.
\nFrom one agent, you can create links to other agents using their IDs like so:
\nAdding a link (Java)
\nMyAgent agent;\n// The ID of another agent to connect to\nlong targetID;\n\nagent.addLink(targetID, Links.Neighbour.class);Where we define a Neighbour link class that extends Empty.Link. Defining meaningful link names is encouraged in order to avoid confusion as your models get more complex.
Defining a link (Java)
\npublic class Links {\n public static class Neighbour extends Link.Empty {}\n}Links are not just simple references: they can embed data as well. This data generally deals with a relation between an agent and one of its peers.
\nHere is how to create a Link that embeds data.\nFirst, define a specific class for your link:
\nDefinition of a Link class (Java)
\npublic class MyLink extends Link {\n int someData;\n}When adding links you can now provide a serializable consumer to addLink in order to assign link fields.
Adding a custom Link with fields(Java)
\nagent.addLink(targetID, MyLink.class, myLink -> myLink.someData=2));The Link can in the same manner:
\ngetLinks() and getLinksTo()removeLinks() and removeLinksTo()An agent can also check if it has links with, hasLinks() and hasLinksTo().
However, you are still able to create pairs of unidirectional links between agents.
\nWhen an agent wants to interact with its environment or with its peers, it has to send messages to them. An agent can:
\nLinks give rise to specific behaviours of the model.
\nThe Simudyne SDK exposes tools to automate and ease the creation of links and complex link structures known as topologies.
\nThe next part will get you started with topologies.
\nBefore getting started, let's define concepts introduced in the Simudyne SDK to create topologies, that is the concepts of Group and Connectors.
Intuitively, in modelling one tends to define their models in terms of sets or groups of agents having identical properties and behaviours.
\nThis is exactly what a Group in the Simudyne SDK is : a set of agents of a particular class. In a Group, all the agents are identical in the sense that they are instances of the same class. Thus a Group is parametrised by its type of agent and also by its size, the number of agents present in the Group.
Using a MyAgent class defined as above, Groups can be created using the AgentSystem like so:
Generating Groups (Java)
\nint nbAgents = 10;\n\n// Creating a group of 10 agents of class MyAgent\nGroup<MyAgentClass> group = generateGroup(MyAgent.class, nbAgents);After these snippets being executed and the system being set up, 10 agents will be spawned in the model and will live their life according to their behaviour defined in the model.
Note Group created is typed by the agent class (in this example MyAgentClass).
If you are interested to define your agents' fields, we recommend you check the section Defining agents more precisely in Groups.
\nNow that we have Groups, we would like to describe the way to connect their agents together.
Connectors implement this concept and are used to specify how to connect agents in one group together or how to connect agents of two different groups together.
\n
We provide different Connectors ready to use; here we are going to use the most popular and simple one, FullyConnected, to explains how to connect Groups together`.
Using this Connector, every agent from the source group will be connected to all other agents in the target group.
Let's create and connect to groups together:
\nFullyConnected on 2 Groups (Java)
\nGroup<MyAgentClass> sourceGroup = generateGroup(MyAgent.class, 5);\nGroup<MyAgentClass> targetGroup = generateGroup(MyAgent.class, 5);\n\n// Connecting the two groups together using the FullyConnected ConnectionStrategy\nsourceGroup.fullyConnected(targetGroup, MyLink.class);Similar to before, we create two Group using the system generateGroup() method. We then use fullyConnected() on the source group with the target group this Connector to register the topology. Here is a graphical representation - the nodes represent the agents and the edges their links:
\n
You can also use a Connector on only one group. This group would be the source but also its own target. Taking a groups created above, we can link its agents using this Connector with this line:
Registering a ConnectionStrategy on a Group (Java)
\nGroup<MyAgentClass> group = generateGroup(MyAgent.class, 5);\n\n// FullyConnecting one group\ngroup.fullyConnected(group, MyLink.class);And that's all ! After the setup being setup, the agents would be created with their link as specified by the Connector.
If the FullyConnected strategy can be used on two different groups, some other Connectors can only be used on one Group. This is, for example, the case of GridConnected whose role is to connect agents as if they were on a grid.
Such restrictions on Connectors exist because it is hard to conceive what would some strategy look like on two different Groups.
\nIn every case, the Simudyne SDK only gives you access to topologies that are possible to create so that you don't have to worry about it..
With those concept defined, you are now able to create topologies, that is a pair of Groups and Connectors!
\nMore precisely, you are able:
\nGroups of agents of a specific type and of a certain population as you want;Groups as you want, shall those groups be identical or different;Connectors if you want to (see the following dedicated section)Let's give an concrete example to recap but also show all the possibilities of this API.
\nSomeone might want to simulate some transport problems using Agent Based Modelling. What they can begin with is defining the structure of countries and cities in a continent. One can come with this natural modelling using UML:
\n\n
Specifying agents in Groups (Java)
\nGroup<City> cities =\n generateGroup(City.class,10000, city -> {\n SeededRandom ran = city.getPrng();\n RealDistribution populationDistrib = ran.gaussian(43000,6000);\n RealDistribution coordinatesDistrib = ran.uniform(-10,20);\n\n // Changing the city fields\n city.population = (int) populationDistrib.sample();\n city.latitude = coordinatesDistrib.sample();\n city.longitude = coordinatesDistrib.sample();\n });Here, we get access to the agent's pseudo random number generator that we have named ran. With this object, we the define two distributions to use to change fields for each city.
More precisely we choose to spawn Cities with:
\nDefining links more precisely when using Connectors\nAs it is the case for agent, link will be spawned with fields having default values. You can define the links to create for precisely using the optional lambda when connecting groups.
\nHere is an example with FullyConnected:
Defining Link (Java)
\ncities.fullyConnected(City.class, Road.class, road -> {\n SeededRandom ran = road.getPrng();\n RealDistribution lengthDistribution = ran.gaussian(50,25);\n\n road.length = lengthDistribution.sample();\n});A summary of the Connectors available in the SDK as well as their parametrisation.
In a FullyConnected network, all source agents are connected to all target agents.
\n
1 Group (Java)
\ngroup.fullyConnected(group, MyLink.class);\nsourceGroup.fullyConnected(targetGroup, MyLink.class);This connector can be used on one or two groups. In the latter case, the connection will be similar to connections in a complete bipartite graph (like connections between two layers in a simple artificial neural network).
\n\n
2 Groups (Java)
\nsourceGroup.fullyConnected(targetGroup, MyLink.class);This topology is also called Complete Graph in mathematics and graph theory.
\nFullyConnected does not scale very well. The number of links is on the order of n * m (where n and m are the respective number of agents of each group).
For better scaling, use the PartitionConnected connector and the coordinator pattern to produce a similar topology.
\nIn a PartitionConnected network, agents from the source group are equally connected to agents of the target group.
The behaviour of this connector adapts to the number of source and target agents:
\n\n
PartitionConnected - 2 Groups (Java)
\nsourceGroup.partitionConnected(targetGroup, MyLink.class);PartitionConnected has two sub-strategies for connections.
The shard() sub-strategy will partition the two groups of agents in term of proximity of agents.
\n The \n PartitionConnected -- Weave (Java) Used alone, those sub-strategies seems identical and will indeed give the same results. However if you use another connector on one of the groups this will give a completely different behaviour. In essence, a small-world network is an intermediate between a ring lattice and a random graph. It is parametrised by two coefficients: More exactly, \n SmallWorldConnected (Java) This type of structure has been used a lot to model social networks in simulations. More about Small-World network on Wikipedia: Small-world network - Wikipedia GridConnected connects agents as if they were on a square grid. This is the main connector used for cellular automata. \n By default, the grid used is a square and is also responsive to the number of agents (its width is adapted so that all the agents can fit in it). However you can change the grid using several sub-strategies, let's present them. The grid can be wrapped (so that it becomes a torus): this way, agents on a grid edge will be connected to the agent on the opposite edge. This can be triggered using \n GridConnected -- wrapped2(Java) By default, the grid is a square but you can make it a rectangle if you specify the width to use. \n This Chebyshev distance can be changed to a number GridConnected -- Moore Neighbourhood (Java) More about the Moore Neighbourhood on Wikipedia: Moore Neighborhood - Wikipedia The other neighbourhood available is the Von Neumann Neighbourhood that is by default defined for a Manhattan distance of \n GridConnected -- Von Neumann Neighbourhood (Java) This Manhattan distance can also be changed to a number More about the Von Neumann Neighbourhood on Wikipedia: Von Neumann Neighbourhood - Wikipedia A Banana Tree is a graph obtained by connecting one leaf of each of n copies of a star graph with a single root vertex that is distinct from all the stars. Here are examples of different Banana Trees. \n BananaTree(Java) Banana Trees can be centred or not: \n BananaTree -- Centered (Java) GraphConnected can be used to generate a graph using a degree distribution and a local clustering coefficient. The Apache commons math distributions are expected as the distribution parameters. Apache commons distributions can be created using the generator methods provided in the Simudyne class The degree distribution lower bound must be a positive number, and the clustering coefficient must have an upper bound of 1 and a lower bound of 0. GraphConnected The way the degree distribution and clustering coefficent is used to create a graph internally is based on the Darwini method. Connectors are composable: you can combine their parameters and different substrategies. Let's give an example using Composing substrategies(Java) With The Simudyne SDK provides some useful connectors you can use to build ABM easily. If the 'out the box' connections do not suffice, the Simudyne SDK lets you define and use your own connector. Here is how to proceed. You first need to extend the the Defining a Connector(Java) The algorithm to use for you to define for In order to define this algorithm: Let's create a custom Example of definition of a Connector(Java) You can then use your Using your CustomConnector (Java) This part will get you started with populating models using data. Let's take a simplified version of the agent class More precisely the data is organised like so: Here, there is an additional field called Each record will be mapped to an agent, and each field of a record, except the indexing field (that is defaulted to id), will be mapped to the eponymous agent attribute. Hence, if your data does not have a field identifying each of your record, you should add a new id column to your dataset to use. We can come up with a simplified version of the Agent class \n To import data, you have to annotate your fields like so so that records in your data can be mapped to Cities. Class definition (Java) Finally, to import your agents in your model, you have to use the system loadGroup() method. You have to specify a Source to use ; this object is dedicated to import data from your file or data base. Let's use a CSVSource to import the data from a CSV file ! Creating data group (Java) And now, all the Cities contains as records in your data are imported into your model ! Thus, IDs present in your data still remain important as they identify agents; but won't be used in the system once the records are imported. Let's now imagine that you want to introduce Roads between your Cities. \n ... and that you have another a data sets of Roads linking Cities together: Here, The remaining fields will be injected in the link at their creation. In our context, there is just one remaining field, You can import those links in your model and between your two groups using the Connecting a Group Using Data (Java) You can also connect two different Connect two Groups using Data If you have data you want to import from a database, you can use a Using JDBC Sources (java) Java JDBC connection string examplesWeaved connections
\nweave() sub-stategy will partition the two groups of agents weaving the links together.sourceGroup.partitionConnected(targetGroup, MyLink.class).weave();Using PartitionConnected to scale your model
\nPartitionConnected can be used to scale your model easily using the coordinator pattern. The idea is to use a set of agents called coordinators that act as intermediary agent between your two original groups.\nSmallWorldConnected
\nSmallWorldConnected operates on one group and will create a small-world network.\n
\ninDegree, a positive integer that specifies the number of outgoing links to create for each agent - it must be strictly smaller than n, the number of agents in the Group;beta, a double in [0,1] that specifies the degree of randomness of the graphinDegree is equal to the number of agents in the group minus one.\nFurthermore, if beta is equal to 0, the graph will be a complete ring lattice and if beta is equal to 1 the graph will be completely random.// the number of outgoing links to create for each agent\nint inDegree;\n\n// a double in `[0,1]` that specifies the degree of randomness of the graph\ndouble beta;\n\ngroup.smallWorldConnected(inDegree, beta, MyLink.class);GridConnected
\nWrapping the grid
\nGridConnection.wrapped().group.gridConnected(MyLink.class).wrapped();Specifying the width of the grid
\nn (supposed greater than 1), making each agents connected to (2 * n + 1)^2 - 1 other agents.group.gridConnected(MyLink.class).mooreConnected();\n\n// Specifying a distance for the neighboorhood.\nint maxDistance;\ngroup.gridConnected(MyLink.class).mooreConnected(maxDistance);1. Using this neighbourhood, each agent is connected to 4 other agents.group.gridConnected(MyLink.class).vonNeumannConnected();\n\n// Specifying a distance for the neighboorhood.\nint maxDistance;\ngroup.gridConnected(MyLink.class).vonNeumannConnected(maxDistance);n (supposed greater than 1), connecting agents to 2 * n * (n + 1) other agents.BananaTree
\n// the number of subgraphs to use\nint nbStars;\n\ngroup.bananaTreeConnected(nbStars, MyLink.class);\n
\ngroup.bananaTreeConnected(nbStars, MyLink.class).setCentered();GraphConnected
\nSeededRandom.SeededRandom randomGenerator = getContext().getPRNG();\nPoissonDistribution degreeDistribution = randomGenerator.poison(10);\nUniformRealDistribution clusterCoefficient = randomGenerator.uniform(0, 1);\ngroup.graphConnected(degreeDistribution, clusterCoefficient, MyLink.class);Composability of connectors
\nGridConnected:// Using a flat square grid (default case)\ngroup.gridConnected(MyLink.class);\n\n// Using a wrapped grid\ngroup.gridConnected(MyLink.class).wrapped();\n\n// Using a flat grid of width w\ngroup.gridConnected(MyLink.class).width(w);\n\n// Using a grid with a different neighborhood definition\ngroup.gridConnected(MyLink.class).vonNeumannConnected();\n\n// Composition them all !\n// Using a torus of width w with a Von Neumann neighborhood\ngroup.gridConnected(MyLink.class).wrapped().width(w).vonNeumannConnected();Connector Summary
\nn and m being respectively the sourceGroup and targetGroup size, we can summaries the number of links created:\n \n
\n\n \n \n \n Connector \n # of links on 1 Group \n # of links on 2 Groups \n \n \n FullyConnected \n n*(n-1) \n n*m \n \n \n PartitionConnected \n n \n max(n,m) \n \n \n SmallWorldConnected \n n*inDegree \n Does not apply \n \n \n GridConnected\n \n 8 * w^2 - 12w + 4\n with w = ceil(sqrt(n)) (in the base case ) \n Does not apply \n \n \n \nBananaTree \n 2 * n - 2 \n Does not apply \n Defining your own connector
\nConnector abstract class like this:public class CustomConnector<T> implements Connector {\n private final Class<T> linkClass;\n private final SerializableBiConsumer<InitContext, T> dataInjector;\n\n public CustomConnector(Class<T> linkClass,\n SerializableBiConsumer<InitContext, T> dataInjector) {\n this.linkClass = linkClass;\n this.dataInjector = dataInjector;\n }\n\n @Override\n public void connectAgent(ConnectionInitializer connectInit,\n GroupInformation sourceInfo,\n GroupInformation targetInfo) {\n // ... the connection strategy is to define here\n }\n}CustomConnector is in connectAgent(). You will have to analytically define an algorithm that can be applied individually to each node.\n
\nGroupInformation sourceInfo and targetInfo give you respectively global information about each of the group used as source and target for your CustomConnector.Agent, is the current agent and gives you access in your algorithm to a given node information.ConnectionStrategy that will connect each agent in a ring.public class CustomConnector<A extends Agent<?>, L extends Link> implements Connector {\n private final Class<L> linkClass;\n private final SerializableBiConsumer<A, L> dataInjector;\n\n public CustomConnector(Class<L> linkClass, SerializableBiConsumer<A, L> dataInjector) {\n this.linkClass = linkClass;\n this.dataInjector = dataInjector;\n }\n\n @Override\n public void connectAgent(Agent agent, GroupInformation sourceInfo, GroupInformation targetInfo) {\n agent.addLink(targetInfo.getBaseID(), linkClass, link -> dataInjector.accept(agent, link));\n }\n}CustomConnector using Group.connect(): cellsGroup.connect(cellsGroup, new CustomConnector<>(MyLink.class, (cell, link) -> link.x = cell.id);Loading Data
\nLoading agents from data
\nCity and let's say you have the following kind of data where each City has:\n
\nname, that is a Stringpopulation, that is an intsurface, that is a float\n \n
\n\n \n \n \n id \n name \n population \n surface \n \n \n 23323443 \n Kodiak \n 783 904 \n 20 229 \n \n \n 48217039 \n Firebrick \n 13 003 \n 4320 \n \n \n 37410058 \n Onalaska \n 2 377 843 \n 61 839 \n \n \n 93749281 \n Ak-Chin Village \n 453 150 \n 17 323 \n \n \n 55283047 \n Blacktail \n 1 921 613 \n 49 315 \n \n \n \n... \n ... \n ... \n ... \n id (which is a unique number) that identifies each record.On the type of data supported
\nThe Simudyne SDK supports consistent schema of data : the records present in your data should not be duplicated and there must exist a field that identifies each individual record.\nCity described above to match this data:class City extends Agent {\n @Constant\n String name;\n\n @Constant\n int population;\n\n @Constant\n float surface;\n\n //...\n}Is there only Source for CSV (CSVSource) out there ?
\nIn our example we suppose the data is stored in a CSV so we use a CSVSource to trigger it. However, you can use other Source -- like JDBCSource -- to import data from other data storage. Check the dedicated section in the following.\nWindows user
The `/` in the paths needs to be replaced with `\\`.// Creating a Source to import data -- you can use another type of source too\nCSVSource citySource = new CSVSource(\"/path/to/myCities.csv\");\n\nGroup<City> cities = loadGroup(City.class, citySource);On IDs present in data vs IDs used in the AgentBasedModel
\nThe IDs present in the AgentBasedModel when importing data are not used any more as data gets remapped to agent that are given a new ID adapted to the state of the system.\nWhat if I do not have enough of fields for the agent that I want to model ?
\nIf you do not have enough fields in your dataset compared to what you would like to have in your model for an agent class, this is not restrictive to use data import. The fields present into your data will be mapped to some of the fields of your agents, leaving the remaining ones with their default values.\nCreating Links from Data
\n\n \n
\n\n \n \n \n id \n name \n population \n surface \n \n \n 23323443 \n Kodiak \n 783904 \n 20229 \n \n \n 48217039 \n Firebrick \n 13003 \n 4320 \n \n \n 37410058 \n Onalaska \n 2377843 \n 61839 \n \n \n 93749281 \n Ak-Chin Village \n 453150 \n 17323 \n \n \n 55283047 \n Blacktail \n 1921613 \n 49315 \n \n \n \n... \n ... \n ... \n ... \n \n \n
\n\n \n \n \n from \n to \n length \n \n \n 23323443 \n 48217039 \n 23.32 \n \n \n 37410058 \n 23323443 \n 343.3 \n \n \n 23323443 \n 55283047 \n 43.13 \n \n \n 55283047 \n 93749281 \n 33.38 \n \n \n \n... \n ... \n ... \n from and to identify respectively the source agents and the target agents.length, that represent the length of a Road from the City identified by the ID from to the City identified by the ID to.connect() with a 'Source'.CSVSource citySource = new CSVSource(\"/path/to/myCities.csv\");\nCSVSource roadSource = new CSVSource(\"/path/to/myRoads.csv\");\n\nGroup<City> cities = loadGroup(City.class, citySource);\n\ncities.loadConnections(cities, Road.class, roadSource);Groups as well:CSVSource citySource = new CSVSource(\"/path/to/myCities.csv\");\nCSVSource countrySource = new CSVSource(\"/path/to/myCountry.csv\");\n\nCSVSource linkSource = new CSVSource(\"/path/to/myLinks.csv\");\n\nGroup<City> cities = loadGroup(City.class, citySource);\nGroup<Country> countries = loadGroup(Country.class, countrySource);\n\ncities.loadConnections(countries, MyLink.class, linkSource);More about Sources
\nJDBCSource that supports MySQL, SQLite as well as PostGreSQL. Here is an example for SQLite:String connectionString = s\"jdbc:sqlite:path/to/myDataBase.db\";\n\nJDBCSource citySource = new JDBCSource(connectionString, \"Country\", \"username\", \"password\");How about supporting other Sources ?
\nFor now, Source have been implemented for CSV files and relational databases. In the future, more solutions will be covered, especially non-relational databases a la NoSQL.\n