Building Agent-Based Simulations with HASH: From Simple Math to Complex Systems

Overview

When you need to understand how the world works, simple mathematical relationships often suffice. For example, increasing hot water flow by x raises mixture temperature by y. But what about situations where cause and effect aren't so clear? Consider a warehouse: with fewer than four workers, operations run smoothly; add a fifth employee, and they start getting in each other's way, to the point that the newcomer produces no net benefit. You can't predict this with a simple formula because the outcome depends on interactions between agents. That's where HASH comes in—a free, online platform that lets you model complex systems using agent-based simulation. With HASH, you write a bit of JavaScript to define how each agent behaves, then simulate the entire system to see emergent patterns. This tutorial will walk you through creating your first simulation, using a warehouse staffing problem as a running example.

Building Agent-Based Simulations with HASH: From Simple Math to Complex Systems — Source: www.joelonsoftware.com

Prerequisites

What You'll Need

A modern web browser (Chrome, Firefox, or Edge)
A HASH account (free)
Basic familiarity with JavaScript (variables, functions, if/else)
Interest in modeling real-world problems

What You'll Learn

How to create an agent-based model in HASH
How to define agent behaviors using JavaScript
How to run simulations and interpret outputs
How to avoid common pitfalls

Step-by-Step Instructions

1. Creating Your First Model

Log in to hash.ai and click New Simulation. Give it a name like "Warehouse Staffing". You'll see a blank workspace with several tabs: init.json, behavior.js, globals.json, and more. These are the building blocks of your simulation.

2. Setting Up Initial Conditions (init.json)

In init.json, you define the starting state—agents and environment. For our warehouse, we'll create agents for each worker and a global object for the warehouse itself. Here's a sample:

{
  "agents": [
    {
      "agent_name": "worker_1",
      "position": {"x": 0, "y": 0},
      "speed": 1
    },
    {
      "agent_name": "worker_2",
      "position": {"x": 1, "y": 0},
      "speed": 1
    },
    {
      "agent_name": "worker_3",
      "position": {"x": 2, "y": 0},
      "speed": 1
    },
    {
      "agent_name": "worker_4",
      "position": {"x": 3, "y": 0},
      "speed": 1
    },
    {
      "agent_name": "worker_5",
      "position": {"x": 4, "y": 0},
      "speed": 1
    }
  ],
  "globals": {
    "warehouse_capacity": 20,
    "throughput": 0,
    "time": 0
  }
}

This creates five workers in a line. The globals track overall metrics.

3. Defining Behaviors (behavior.js)

The heart of your simulation is in behavior.js. This file runs for each agent every time step. Let's write a simple movement and collision behavior:

function behavior(state, context) {
  // Get current position
  const position = state.position;
  // Simple random walk (move one step in a random direction)
  const directions = [
    {x: 1, y: 0},
    {x: -1, y: 0},
    {x: 0, y: 1},
    {x: 0, y: -1}
  ];
  const dir = directions[Math.floor(Math.random() * 4)];
  let newPos = {
    x: position.x + dir.x,
    y: position.y + dir.y
  };
  // Check if new position is occupied
  const occupied = context.neighbors()
    .filter(a => a.position.x === newPos.x && a.position.y === newPos.y)
    .length > 0;
  if (occupied) {
    // If crowded, worker does nothing (simulates getting in the way)
    return { ...state, throughput_contribution: 0 };
  } else {
    // Move and contribute to throughput
    return { ...state, position: newPos, throughput_contribution: 1 };
  }
}

This is a simplified example; in reality, you'd model more complex workflows. The key point: when workers collide, they are blocked and produce nothing.

4. Running the Simulation

Click Run to execute. You'll see a grid with colored dots moving around. The right panel shows a plot of throughput over time. Under globals.json, add this to aggregate contributions:

{
  "globals": {
    "warehouse_capacity": 20,
    "total_throughput": 0,
    "time": 0
  },
  "update": {
    "total_throughput": "sum(state.agents, 'throughput_contribution')"
  }
}

Now run and watch. You'll notice that with 5 workers, total throughput is often less than with 4—exactly the phenomenon described in the original problem.

5. Analyzing and Tweaking Parameters

To experiment, change the number of workers in init.json or adjust the movement rules. For example, make workers avoid collisions more intelligently—say, by trying a different direction if the first is blocked. Later we'll discuss pitfalls that can skew results.

Common Mistakes

Overcomplicating the Behavior

Start simple. Add complexity only after you understand the basics. In the warehouse example, a random walk with collision detection is enough to reproduce the core effect.

Not Calibrating Parameters

Real-world workers move at specific speeds and have defined tasks. Without calibrating to known data, your simulation may be unrealistic. Always validate against observations.

Ignoring Randomness

Agent-based models are stochastic. Run multiple simulations (use HASH's batch-run feature) to average results. Don't draw conclusions from a single run.

Forgetting to Reset State

When you change init.json, HASH automatically resets. But if you manually edit globals mid-run, the simulation may behave oddly. Always start fresh after changes.

Summary

HASH transforms complex, hard-to-predict systems into programmable simulations. By representing each entity as an agent with simple rules, you can observe emergent behaviors—like the warehouse synergy loss—that are invisible to algebraic equations. This tutorial covered creating a model, writing JavaScript behaviors, running simulations, and avoiding common errors. The same approach applies to traffic flow, epidemiology, market dynamics, and more. Start building your own models at hash.ai and discover the hidden patterns in the world around you.

Tags: