The starting point of every BaseAgent program is a Simulation. All of the parts of your agent-based model are provided to the Simulation. The Simulation runs step-by-step; in each step, each simulation object (including agents and other things you'll read about below) is called to run one step of its existence, and the order in which agents take their steps is well-known (but doesn't have to be the same each time you run, if you don't want it to be). Simulations may be run with or without a visualization.
The Universe is the world in which everything happens. This is where agents live and act. It can be of any shape: a two-dimensional grid, a 3D world, a network of connected nodes, a “soup” in which every position is connected to every other position, and so on.
BaseAgent provides two Universes to support the most commonly-used geometries in agent-based modeling. The first is a Grid, a 2-dimensional world with multiple GridLayers. The second is a PathNetwork, a world of connected positions. (In BaseAgent, a Network itself is a general and powerful concept that can be used in a variety of ways, such as the brains of an agent or to represent social network concepts.)
A spot in the Universe that responds to the simulation but does not change its position or have agency is called a Patch. The logic of a Patch is instantiated once and applied to each position in the Universe like a rubber stamp. Using a Patch is an excellent way to create a computationally efficient simulation of Wolfram’s Cellular Automata, Conway’s Game of Life, or Langton’s Loops.
An Agent has agency in the Universe, and can do a lot of things out-of-the-box. Agents have an Inventory that lets them take and drop items in the Universe, or give and take items with other Agents. They have Knowledge, a map of strings to objects, that can contain things that Agents learn over time, or initial settings about themselves. They have a set of Behaviors and they remember their current Behavior. They can have State. Behaviors could be a function of Knowledge and State. Finally, they are able to send and receive a Message to other Agents.
BaseAgent provides special Agents for the default Universes. A GridAgent is a special type of Agent that knows how to traverse a Grid, and a PathAgent is an Agent that knows how to traverse a PathNetwork.
A special type of GridAgent is an EmbodiedAgent, which exists in a Grid and has a body (which is also a Grid), on which Sensors and Effectors may be placed. Sensors detect things in the environment, including Signals, which could include things like pheromones. They can also detect situations in the Universe, such as being surrounded. Effectors can affect the Universe by moving the agent, moving other things, placing Signals, and so on. Sensors and Effectors may be connected to Processors or special Behaviors that produce a Network between observations and actions.
A Behavior can be a single type of action or a selector that chooses other Behaviors to execute. Special behaviors intended for GridAgents and PathAgents give those kinds of Agents a way to explore their Universe.
Agents communicate with each other using a Message, each of which has a title, a subtitle, and a payload that may consist of any object. Agents may also communicate through Pheromones, which are special types of Signals that spread and dissipate over time.
Messages are sent to other Agents through a Communicator. Examples of Communicators include a BroadcastCommunicator, where all Agents hear all Messages; an InRangeCommunicator, which works in a Grid and limits the receipt of Messages to those Agents that are within a certain distance from the sender; and a PathCommunicator, which limits Messages to Agents who are connected to the sender in a PathNetwork. If you want to implement communication issues that mimic the real world, such as electromagnetic interference, this is where to do it.
An Environment contains processing that affects anything at all in the Universe. It may cause simulated weather, sow simulated seeds, and otherwise affect the world.
Any actions in the Simulation may be triggered by a Schedule, which executes one-time events, conditional events, and recurring events.
If you wish to collect data from a Simulation, a DataCollector collects data at the end of a turn of the simulation. Immediately thereafter, any number of Metrics are evaluated against the collected data.
If you wish to visualize the Simulation, several of the Simulation Components are Drawable and the Universes may be visualized with a GridCanvas or a PathNetworkCanvas. An Indicator is a visualization component that is responsive to settings in the Simulation, and a Toast provides a way to display text on top of the Simulation. BaseAgent provides a number of default visualization techniques, including a library of shapes for visualizing Agents.
Finally, commonly-used functions may be found in BaseAgentUtils, and common agent-based mathematics (such as a Euclidean distance formula) are in BaseAgentMath.
Aside from these high-level concepts, BaseAgent has a philosphy of using common, well-understood programming classes and metaphors whenever possible. For example, the most frequent data structures for sharing data between concepts are standard maps and lists.