Agentscape is a library for creating agent-based simulations. It provides a simple API for defining agents and their behavior, and for defining the environment in which the agents interact. Agentscape is designed to be flexible and extensible, allowing users to create a wide variety of simulations.
All examples can be found here.
npm i agentscapeWe will create a simple simulation where agents move randomly around a grid.
We start by defining an agent which is a class that extends Entities.Agent. The agent must implement an act method that defines the agent's behavior for each step of the simulation.
import { Entities } from 'agentscape'
import { Color } from 'agentscape/number'
import { CellGrid } from 'agentscape/structures'
export default class Agent extends Entities.Agent {
// we'll keep track of the random
// angle the agent turns each step
public theta: number
// agents have a random number generator
// and a default color (blue)
override color = Color.random(this.rng)
act(grid: CellGrid<Entities.Cell>) {
this.theta = this.rng.uniformFloat(0, 90) - this.rng.uniformFloat(0, 90)
this.rotation.increment(this.theta,'deg')
// agents can move in the direction they are facing
// or to a specific location.
this.move(grid)
}
}Next, we define a model that contains the agents and the grid. A model consists of zero or more agent sets and one grid of cells.
Agents are grouped into an AgentSet and a Cell is grouped into a CellGrid. The Model must implement methods to initialize agent sets and a cell grid.
import { Model, ModelConstructor } from 'agentscape/model'
import { Cell } from 'agentscape/entities'
import { Angle } from 'agentscape/number'
import { CellGrid, AgentSet } from 'agentscape/structures'
import Agent from './Agent'
export default class RandomWalk extends Model<Cell, Agent> {
gridSize = 10
agentCount = 10
randomSeed = 0
constructor(opts: ModelConstructor) {
super(opts)
this.setRandomSeed(this.randomSeed)
}
initAgents() {
// creates an AgentSet using a factory function
// that creates agents with random starting rotations.
const _default = AgentSet.fromFactory(
this.agentCount,
(_, randomSeed) => new Agent({
initialPosition: [
Math.floor(this.gridSize / 2),
Math.floor(this.gridSize / 2)
],
rotation: Angle.random(this.rng),
randomSeed
}),
{
// the agent factory's RNG can be
// seeded to ensure reproducibility
randomSeed: this.randomSeed
}
)
return {_default}
}
initGrid() {
// creates a grid of cells with periodic boundary conditions
// uses the default cell class
return CellGrid.default(
this.gridSize,
{
boundaryCondition: 'periodic'
}
)
}
}Finally, we create an instance of the model and run the simulation.
import RandomWalkModel from './Model'
const documentRoot = document.getElementById('root') as HTMLDivElement
const model = new RandomWalkModel({
documentRoot,
renderWidth: 800,
id: 'random-walk',
autoPlay: false,
frameRate: 10,
})
model.start()We can add parameters to the model that can be controlled by the user. Parameters are defined as an array of ControlVariable objects and passed to the model constructor.
import { ControlVariableConfig } from 'agentscape/ui/Controls'
import RandomWalkModel from './Model'
const documentRoot = document.getElementById('root') as HTMLDivElement
const parameters: ControlVariableConfig[] = [
{
label: 'Grid Size',
name: 'gridSize',
default: 10
},
{
label: 'Number of Agents',
name: 'agentCount',
default: 10
},
{
label: 'Random Seed',
name: 'randomSeed',
default: 0
}
]
const model = new RandomWalkModel({
documentRoot,
renderWidth: 500,
title: 'Random Walk',
id: 'random-walk',
parameters,
frameRate: 10,
autoPlay: false
})
model.start()The parameters can be accessed in the scope of the model class as properties by using the @ControlVariable decorator.
import { ControlVariable, Model, ModelConstructor } from 'agentscape/model'
import { Cell } from 'agentscape/entities'
import { Angle } from 'agentscape/number'
import { CellGrid, AgentSet } from 'agentscape/structures'
import Agent from './Agent'
export default class RandomWalk extends Model<Cell, Agent> {
@ControlVariable()
gridSize: number
@ControlVariable()
agentCount: number
@ControlVariable()
randomSeed: number
constructor(opts: ModelConstructor) {
super(opts)
this.setRandomSeed(this.randomSeed)
}
initAgents() {
const _default = AgentSet.fromFactory(
this.agentCount,
(_, randomSeed) => new Agent({
initialPosition: [
Math.floor(this.gridSize / 2),
Math.floor(this.gridSize / 2)
],
rotation: Angle.random(this.rng),
randomSeed
}),
{
randomSeed: this.randomSeed
}
)
return {_default}
}
initGrid() {
return CellGrid.default(
this.gridSize,
{
boundaryCondition: 'periodic'
}
)
}
}In addition to rendering the simulation, we can also display data via charts.
- Histogram
- Time Series
- Scatter Plot
We will use a histogram to display the cumulative distribution of agent rotations.
First, instantiate a new Histogram in the model constructor.
import { Histogram } from 'agentscape/ui/charts'
export default class RandomWalk extends Model<Cell, Agent> {
@ControlVariable()
gridSize: number
@ControlVariable()
agentCount: number
@ControlVariable()
randomSeed: number
turningAngleDistribution: Histogram
turningAngleCumulative: number[] = []
constructor(opts: ModelConstructor) {
super(opts)
this.setRandomSeed(this.randomSeed)
this.turningAngleDistribution = new Histogram({
root: opts.documentRoot,
title: 'Turning Angle Distribution',
axisLabels: {
x: 'Angle',
y: 'Frequency',
}
})
}
...etc
}Then, using the model's postUpdate method, we can update the histogram with the turning angle of each agent at each step of the simulation. We do this by getting the turning angle (theta) of each agent and pushing it to the turningAngleCumulative array. We then apply the data to the histogram.
export default class RandomWalk extends Model<Cell, Agent> {
@ControlVariable()
gridSize: number
@ControlVariable()
agentCount: number
@ControlVariable()
randomSeed: number
turningAngleDistribution: Histogram
turningAngleCumulative: number[] = []
constructor(opts: ModelConstructor) {
super(opts)
this.setRandomSeed(this.randomSeed)
this.turningAngleDistribution = new Histogram({
root: opts.documentRoot,
title: 'Turning Angle Distribution',
axisLabels: {
x: 'Angle',
y: 'Frequency',
}
})
}
initAgents() {
const _default = AgentSet.fromFactory(
this.agentCount,
(_, randomSeed) => new Agent({
initialPosition: [
Math.floor(this.gridSize / 2),
Math.floor(this.gridSize / 2)
],
rotation: Angle.random(this.rng),
randomSeed
}),
{
randomSeed: this.randomSeed
}
)
return {_default}
}
initGrid() {
return CellGrid.default(
this.gridSize,
{
boundaryCondition: 'periodic'
}
)
}
postUpdate(): () => void {
return () => {
this.turningAngleCumulative.push(...this.agents._default.map((agent) => agent.theta ))
this.turningAngleDistribution.applyData(this.turningAngleCumulative, 1)
}
}
}The complete code the Random Walk example can be found here.
The auto-generated API documentation can be found here.