How to use this book

How to use this book#

This is not a book you just read; it is a book you do. Some chapters build the ideas behind agent-based modelling through short explanations and interactive activities you complete right on the page; others hand you real Python you can run, edit, and experiment with directly in your browser, with no installation and nothing to download. Either way, you learn by engaging, not by scrolling. This page explains three things: how to study the concept-and-activity chapters, how to get the most out of the code chapters, and how the live code works.

Getting the most out of this book#

This is a do-first book: whatever the page, you are meant to engage with it, not just scroll past. The chapters come in two kinds, and each rewards a slightly different way of working.

Two kinds of chapter, two ways to work

The book has two chapter styles, and each rewards a slightly different way of working. Click each to see how to get the most from it.

The chapters build on one another, so the most reliable route is to work through them in order, starting with Chapter 1: the concepts in Chapters 1 and 2 are what make the code in Chapters 3 and 4 make sense, and Chapter 5 builds on all of them. For a one-line map of what each chapter covers, see What is this book about?.

Three habits that make the book work

However you work through a page, these three habits are what turn it from reading into doing. Tap each card.

Finding your way around#

Every page carries the same small set of controls at the top. Click through them here so they feel familiar before you need them:

Tour the toolbar

These are the controls at the top of every page, in the order you see them. Click each one to find out what it does.

Live coding: running Python in your browser#

The code in this book runs in a Python environment that starts inside your browser tab. Nothing is installed on your computer, and the original book is never affected by what you type. The environment behaves like a small Jupyter notebook: variables created in one cell remain available to later cells, and changing an earlier definition can change every result that follows. This is why the order in which you run cells matters, and why restarting and running from the top is the clearest way to check that an experiment is reproducible.

Activating the live code#

At the top of every page that contains code you will find a rocket icon 🚀. Click it and choose Live Code. A Python environment starts up, and the status changes from launching... to ready after a few seconds. Once it is ready, every code cell on the page becomes interactive:

Run executes a cell and shows its output right below it.
Restart restarts Python and clears everything, giving you a clean slate.
Restart & Run All restarts and then re-runs every cell on the page from top to bottom.

Cells can depend on each other

Just like in a Jupyter notebook, cells on a page often build on one another. If a cell complains about an undefined variable, run the cells above it first, or use Restart & Run All.

Try it right now#

This is your first hands-on moment, so let’s run some real Python. First, click the rocket icon 🚀 at the top of the page and choose Live Code, then wait a few seconds for the status to change from launching... to ready. Now hover over the code cell below and press its Run button (▶). You should see three lines of output appear right underneath, each one a step in a tiny simulation.

message = "Hello, agent!"
for i in range(3):
    print(f"{message} This is step {i + 1} of your simulation. 🐜")

Worked? Now edit it. Click directly inside the cell above and change something: swap the text in message, turn the 3 into a bigger number to make the loop run longer, or delete a bracket on purpose to see the error. Press Run again each time to watch what changes. Then try the empty playground cell below, where you can type any Python you like and press Run. This is exactly how you should treat the whole book:

# Your playground: type anything you like here and press Run
2 + 2

You cannot break anything

The code runs entirely in your browser tab, so experimenting is safe and encouraged: change the examples, push them further, and break them on purpose to see what happens. Press Restart to clear Python and run again from a clean state. Reloading the page does not undo your edits, because they are saved automatically; to put a cell back to its original version, use the Reset button described below.

Saving your progress#

As you work through the book you will edit code cells and answer interactive questions. Your work is saved automatically in your browser (local storage), so you can close the tab and continue later on the same computer. Because it is saved this way, reloading or refreshing a page keeps your changes rather than clearing them.

To move your progress between computers, or to keep a backup, use the Export, Import, and Reset buttons in the top-right toolbar (the same ones from the tour above): Export downloads all of your work as a single file, Import restores it on another computer or after clearing your browser, and Reset returns a single page or the entire book to its original state.

When should I export?

Browser storage can be wiped when you clear cookies or site data, or when you use private browsing. Export your progress at the end of each working session. It takes one click and gives you a file you fully control.

Careful with Reset

Reset cannot be undone, and refreshing the page will not bring cleared work back. If you might want your work later, click Export first.

That’s all you need. Use the next-page arrow (→) at the bottom of this page to carry on, and remember: run the code, change the code, break the code. That is how modellers learn.