--- jupytext: formats: md:myst text_representation: extension: .md format_name: myst format_version: 0.13 jupytext_version: 1.11.5 kernelspec: display_name: Python 3 language: python name: python3 --- (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. ```{raw} html :file: ../learning_activities_and_widgets/widgets/widget_0_2a_choose_a_chapter_path.html ``` 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 {doc}`about_this_book`. ```{raw} html :file: ../learning_activities_and_widgets/widgets/widget_0_2b_effective_reading_habits.html ``` ### 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: ```{raw} html :file: ../learning_activities_and_widgets/widgets/widget_0_2c_book_interface_tour.html ``` ## 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. ```{admonition} Cells can depend on each other :class: note 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. ```{code-cell} ipython3 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: ```{code-cell} ipython3 # Your playground: type anything you like here and press Run 2 + 2 ``` ```{admonition} You cannot break anything :class: tip 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. ```{admonition} When should I export? :class: important 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. ``` ```{admonition} Careful with Reset :class: warning **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.