CoffeeScript API Documentation

AgentBase

The AgentBase software library allows you to build Agent Based Models (ABMs) that run in the browser. It follows NetLogo's Agent oriented Programming model and is entirely implemented in CoffeeScript. Tinker with models on AgentBase.org or drop by our Google Group to get involved. Documentation is here.

AgentBase:

Allows you to easily share and run ABM models, directly from a webpage. No software to install.
Is optimized for the quick development of illustrative ABM models: It values minimalism over complexity, readable and pretty code over CPU performance, and sensible defaults over choice. It is opinionated software.
While NetLogo formed a great inspiration (the most commonly used ABM toolset), AgentBase does not try to copy it (unlike AgentScript). The web is not the desktop. Coffeescript is not Logo.
AgentBase is well-tested through automated testing and thus a library that you can trust. See for yourself.

Sample models

Have a look at these example models.

Template shows the basic structure of a model and is a good place to get started when you want to try building your own. Advanced Template is more elaborate.

Ants is a model of ant foraging behavior incorporating a nest location and food pheromone diffusion.

Buttons provides Stuart Kauffman's example of randomly connecting pairs of buttons in a pile resulting in a tipping point.

Diffusion has randomly flying agents on a patch grid dropping a color which is diffused over the grid.

Fire is a cellular automata model of fire spreading.

Flock is the classic "boids" model where agents each follow three simple rules resulting in realistic flocking. This example uses the as.dat.gui.js extra.

Grid Path shows one of Knuth's great puzzles on the probability of all Manhattan traversals diagonally traversing a grid.

Life provides an implementation of Conway's Game of Life with a twist. This example demonstrates running multiple models on the same page.

Link Travel has agents traversing a graph of nodes and links.

N body is a simulation of the nonlinear gravitation of n bodies.

Preferential Attachment models a dynamic graph where new links preferentially attach to the nodes that have the most links. This results in a power-law distribution.

Traveling Salesman demonstrates a Traveling Sales Person solution via a Genetic Algorithm showing the rapid conversion of stochastic methods.

The format of sample models

Our example models use CoffeeScript directly within the browser via text/coffeescript script tags:

  <html>
    <head>
      <title>AgentScript Model</title>
      <script src="agentscript.js"></script>
      <script src="coffee-script.js"></script>
      <script type="text/coffeescript">
        class MyModel extends ABM.Model
          setup: ->
            @patches.create()

            for agent in @agents.create 25
              agent.shape = u.shapes.names().sample()

          step: ->
            for agent in @agents
              agent.forward()

        model = new MyModel {
          div: "model"
          patchSize: 6
          mapSize: 32
        }

        model.start()
      </script>
    </head>
    <body>
      <div id="model"></div>
    </body>
  </html>

You can see this by running a sample model from the 'models/' directory, then using the browser's View Page Source.

Building a model

Visit agentbase.org and tinker with the Template, the Advanced Template or any other example model to get started.

Class ABM.Model has two methods that it calls automatically for you:

setup()     # Initializes the model. Called during startup and by Model.reset().
step()      # A time step. Called by the animator to advance the model one step.

To build a model from scratch, simply subclass ABM.Model to build a model, supplying the three methods. You can also edit models locally: Download AgentBase, unzip it), then go to the models directory and edit the template.html model you find there.

We'd be grateful if you cite/link to AgentBase when you use it for a model or publication.

Development installation

If you want to tinker with AgentBase itself, instead of just building a model that uses it, you will need to do as follows (on Mac/Linux).

Git clone with

git clone git@github.com:wybo/agentbase.git

cd agentbase

install the development dependencies with

npm install

and build with.

npm run watch

Tasks are all run via npm run ` and they are:

watch       # Watch for source file updates, invoke build
build       # compile and minify src/ and extras/ to lib/
doc         # use codo on sources to create docs/
all         # Compile coffee, minify js, create docs

Behind the scenes npm invokes gulp, whose tasks are defined in Gulpfile.coffee. The command "npm run all" is equivalent to "gulp all". All "npm run" commands are defined in package.json.

If you get reports about missing dependencies, you may have to upgrade node or npm. To do this, type: sudo npm install -g n; sudo n stable; then check that node is updated with node -v

Contribute

If you would like to contribute, please make sure all the unit tests ("cake test") and sample models work as expected before you create a pull-request. If you add new functionality, add matching tests as well.

In addition, make sure the docs build correctly. They can be built with npm run codo. Use your browser on doc/ to test.

Finally, be sure to follow the STYLEGUIDE.txt for code you'd like to see included.

The typical workflow looks like:

Process files when they change

npm run watch

compile & minify all code, create docs. Done before git add to insure everything is ready for git.

npm run all

and commit locally.

git commit -a

See github for more information on forking and pull-requests.

Files

Gulpfile.coffee   # Gulp file for build, docs etc.
LICENSE           # GPLv3 License
README.md         # This file
STYLEGUIDE.txt    # Suggestions for coding-style 
package.json      # NPM Package file, see npm install below
doc/              # Documentation
lib/              # All .js/min.js files
models/           # Sample models
src/              # Component .coffee files for agentscript.coffee
tools/            # coffee-script.js and others

Inside src/ the most important files are:

Agent.coffee contains the agents that populate your model.

Agents.coffee is the set of @agents you see called in models.

Patches.coffee provides the set of @patches that each model has.

Model.coffee holds the basis for your model. It is subclassed by all models.

Util.coffee is the base module for tools.

Util_array.coffee contains helpers that are included in ABM.Array. You will be using these.

Full documentation can be found on doc.agentbase.org.

License

AgentBase Copyright (c) Wybo Wiersma, 2014. The AgentBase library is Free Software, licensed under the GNU General Public License, version 3 or any later version. AgentBase was derived from AgentScript by Owen Densmore and RedfishGroup LLC, 2012-13 (under the same license).

AgentBase is Free Software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program, see LICENSE within the distribution. If not, see http://www.gnu.org/licenses/.