5  AI-assisted coding

Author

Gudrun Wallentin and Gedeon Igelspacher

You have written your first working GAML models, debugged reflexes and builds agents that actually move. At some point in this process you probably wondered: Can I use a GenAI tool to help me with this? The answer is yes and in this lesson we will learn how to use these powerful tools effectively and appropriatly.

Learning Objectives

By the end of this lesson, you will be able to:

  • explain what AI-assisted coding is, how it changes the modelling workflow and which tools can be used for implementing spatial simulation models,
  • separate a human-authored conceptual design phase and the subsequent AI-assisted implementation,
  • write effective prompts that produce useful, high-level and well documented code output,
  • review, understand, debug and test AI-generated code to remain in full control of the code, while benefiting from the AI tools as much as possible,
  • use AI-assisted coding with strong human lead to still leverage the full potential of model development as a “tool to think with”.

5.1 Introduction into AI-assisted coding

The way software is developed has changed dramatically since the rise of Large Language Models (LLMs). In 2025 Andrej Karpathy, former co-founder and researcher at OpenAI and AI-Lead at Tesla introduced the term “Vibe Coding” (Karpathy 2025). It describes the process of producing executable code by prompting AI tools in natural language rather then producing the code manually by hand. Karpathy (2025) characterises the approach as one where the developer fully trusts the AI’s output, accepts all changes and barely reads the produced code. Tempting… especially for people, who are not highly skilled in programming. However, this approach misses the core of modelling: to design and develop tools to think with about systems in a structured way. So, this is not the type of AI-assisted coding we are talking about.

This module follows the principle of AI-assisted programming: a responsible approach in which the AI acts as a peer programmer, where the human’s responsibility is to always review, test and understand generated code (Google Cloud 2026). The human stays in the lead with specifying all the details of what the model intends to do, how the model is structured, and the flow of its execution logic. The AI contributes the coding knowledge, the systems thinking fully remains with the human. While this sounds like a simple share of tasks, it is not.

5.1.1 AI-assisted coding workflow

The traditional software developers write their code chunk by chunk in a systematic manner. After each bit of code, the developer verifies the code chunk. Verification and debugging constantly parallels code development. This workflow forces the developer to think about every specification detail, take conscious decisions about every assumption made, and to actively decide on parameters. A skilled programmer writes code that is modular, easily maintainable and elegantly short. In the end, programmers know their codebases well and exactly know, what happens when the code is executed.

In the age of AI-assisted coding this workflow is changing fundamentally. It can be roughly divided in the following separate steps (Google Cloud 2026):

  1. Description of objectives: You describe the desired functionality of what the AI should generate in plain natural language, for example: “Generate a cow agent, that is wandering around in GAMA”
  2. Code generation: The Prompt is processed by AI, which produces a code output
  3. Execution and verification: The generated output is executed and its behaviour is observed
  4. Feedback: If the output does not match the desired functionality, describe the misbehaviour and provide new instructions to the AI
  5. Repeat: This cycle of prompting, generating, testing and refining repeats until the project objectives are met.

So you see there is a change of the role of the developer itself. Rather than writing and understanding the code line by line, the developer acts more like a director, defining objectives, evaluating outcomes and guiding the AI tools through successive iterations (Sapkota, Roumeliotis, and Karkee 2025).

However, in a “human-in-the-lead” approach this shift still comes with the same responsibility to fully understand what the model exactly does.

5.1.2 Model design before coding

Before you start coding a simulation model: sit down and draw an activity UML. What is the exact purpose of your model? What should happen in the initialisation? Which agents? Which attributes will agents need? What will be the behaviour of your agents? Will there be a cellular automaton? Which spatial resolution do cells have? Which attributes? Which temporal resolution will be one time step? What are state variables that report the state of your modelled system over time? What are user-defined parameters? Once you have defined the model specifications, start to implement the model’s structure. Only then start to populate the code with parameters and behaviour.

5.1.3 Tools for AI-assisted coding

AI-assisted coding tools can be designed in several approaches, including web-browser based chats, command line interface (CLI) agents, AI-integration into IDEs or notebooks, and highly autonomous AI-agents in dockerised environments or virtual machines. These approaches differ in how much access the AI has to your files and how much control you retain. Developers often use IDEs with AI integration, however there is no IDE that provides support for GAML. So, for the development of spatial simulation models with GAMA, we focus on browser chats and CLI coding agents:

Web-browser based chats

The web-based chat interface is the most widely known entry point for AI-assisted coding. You describe your problem directly in the browser, paste in relevant code snippets, and review the generated output manually. There is no direct connection to your file system, which keeps the setup simple but requires manual copy-pasting between the chat and your editor. Version control is entirely your own responsibility.

A few examples:

Command Line Interface (CLI) coding agents

The CLI is one of the most powerful yet underestimated options, and for many users the most unfamiliar. A CLI agent runs directly in your terminal, reads and writes files without copy-pasting, and can navigate your entire project structure. It combines naturally with build tools, test runners, and shell scripts, enabling fully automated workflows. The trade-off is that you are granting the AI broad access to your system, which demands a higher level of trust and caution. CLI tools are generally Git-aware and can commit changes directly, which makes version control straightforward, but also means it is important to review diffs carefully before committing, as the agent may modify multiple files at once.

A few examples:

Before reading on, take a moment to think about the following question:

Most of the tools described above work well for mainstream programming languages like Python or JavaScript, which are well-represented in the training data of every major AI model. Spatial simulation with GAMA is a different situation. GAML is a niche language with a small community and limited publicly available code, which means AI models have seen comparatively little of it during training. The result is that no tool will produce reliable GAML out of the box.

The good news is that this can be compensated. GAML is syntactically close to Java and Python, and the underlying concepts are well understood by current models. The gap is not conceptual but contextual: the AI simply needs more guidance than usual. Providing your own .gaml files or relevant sections of the GAMA documentation directly in the conversation makes a substantial difference in output quality, regardless of which tool you use.

Additional thoughts

  • How to minimise hallucination?

This depends a lot on the AI model itself and how much it checks for the inner consistency of its answers. In our experience, there are large differences between AI models, e.g. OpenAI’s “GPT” that is for example used by Copilot hallucinates more than Anthropic’s “Opus”. Usually, if pays off to put effort into what and how to prompt, and in turn use a more token-expensive model.

  • How to limit modifications to just a part of your code?

If we want to change just a snippet of code, e.g. a reflex, sometimes models also change other parts of the code, which makes debugging a nightmare. Claude tends to be more consistent with its modifications and refactors only that code snippet you asked for. But it is worth to compare different tools once in a while, as the landscape of AI-models and tools develops rapidly.

Regardless of the AI model, if you want to make sure to stay in full control and also have clearly defined development versions, it’s highly recommended to use git.

5.1.4 Versioning with git

Developing code is an incremental process: you add a functional detail to the model -> you test, whether the model does, what it should. If you find a bug, you need to debug until you are sure that the improved model works as it should. If you are really sure the model with the added functionality works, make it a new version.

Git versioning is an established App-development workflow. It makes especially sense, when you develop your model with genAI support. With genAI support, you are usually quicker, but that also means that even if you try to stay focused and keep the lead of the design process, this speed may drag you off into a rabbit hole. In such cases it’s very valuable to be able to revisit prior versions.

If you develop your model with a genAI tool, let your AI-tool know when a code is a new (minor) version. It will help you to summarise the major changes. Review the indicated changes: does this summarise your intentions of the change? Edit the change log with your own words, and then copy it into your git documentation. The genAI will learn from your approach and after a while, start to suggest when to declare a new version.

5.1.5 Exercise — setup your AI-assisted coding with a CLI agent for GAMA

Exercise: CLI agent with git versioning

In this exercise you will build the environment to put AI-assisted coding with a CLI agent into practice: a GAMA project under version control, mirrored to a GitHub repository, with a CLI coding agent that has read and write access to that project. This is the recommended approach for coding more complex models. However, you can skip over this exercise, if you prefer to stay with AI chats in a web-browser.

Estimated time: 60–90 minutes, most of it one-off setup you will not have repeat (and that you can also re-use in other UNIGIS modules).

Part 0 — Prerequisites

Before you start, make sure the following is in place.

  1. GAMA is installed and you can open your workspace.

  2. Git is installed. Download it from git-scm.com open Windows PowerShell and verify it is properly installed by typing:

    git --version

    If this prints a version number, you are set.

    Don’t be intimitated by using command-line git. You will have the AI installed, so you can ask to commit to git in natural language, and generally ask any kind of “stupid” questions, as you would do in a AI chat.

  3. A GitHub account. Register at github.com if you do not have one.

  4. A Google account, for authenticating Google’s free coding agent “Antigravity CLI”. Of course, you can use any other CLI agent, e.g. if you have a paid license for Claude Code.

Set your git identity once, so that commits carry your name:

git config --global user.name "Your Name"
git config --global user.email "your.email@example.com"

Part 1 — Put your GAMA project under version control

1.1 Locate your UNIGIS models project folder GAMA workspace folder typically something like C:\Users\<username>\gama_workspace\UNIGIS_models.

1.2 Initialise the repository at project level, not workspace level and version the project (replace the path with your path):

cd C:/Users/<username>/gama_workspace/UNIGIS_models
git init

1.3 Add a .gitignore. Create a file named .gitignore in the project folder containing temporary files and other stuff, you don’t want to version:

# Eclipse / GAMA workspace state
.metadata/
.recommenders/
RemoteSystemsTempFiles/
*.log

# Simulation outputs — regenerate these, don't version them
outputs/
snapshots/
*.csv.tmp

# OS clutter
.DS_Store
Thumbs.db

Note that the .project file is kept, because GAMA needs it to recognise the folder as a project when a colleague clones your repository.

1.4 Make the baseline commit.

git add .
git commit -m "Initial commit of my GAMA models"

You now have a state you can always return to.

Part 2 — Create a GitHub repository and connect it

Git on your computer and GitHub in the cloud are two different things. Git tracks versions locally; GitHub is a hosting service that stores a copy — a remote — which gives you a backup, a way to work across machines, and a way to share the model. You could complete this whole module without GitHub, but you would have no safety net if your laptop fails.

2.1 Create an empty remote repository. Go to github.com/new and set:

  • Repository name: UNIGIS_GAMA_models
  • Visibility: Private (you can make it public later; check your course policy first)
  • Initialize with README / .gitignore / license: leave all three unticked

That last point is something that commonly causes problems. If GitHub creates files in the remote, its history and your local history have no common ancestor and the first push is rejected. Starting empty avoids the problem entirely.

2.2 Authenticate. GitHub does not accept account passwords over HTTPS. The least painful route is the official GitHub CLI: install cli.github.com, then run

gh auth login

and follow the browser prompt. This stores a credential that git will reuse silently from then on. (Alternatives, if you prefer: an SSH key, or a Personal Access Token used in place of a password.)

2.3 Connect and push. Back in your project folder:

git branch -M main
git remote add origin https://github.com/<your-username>/UNIGIS_models.git
git push -u origin main

Reload the repository page in your browser. Your project skeleton should be there. The -u flag sets origin/main as the default upstream, so later pushes are simply git push.

Part 3 — Install the Antigravity CLI agent

3.1 Install. Open a terminal and run the command for your operating system:

irm https://antigravity.google/cli/install.ps1 | iex

The installer places a binary called agy in C:\Users\<username>\AppData\Local\agy\bin (Windows). If your shell reports command not found afterwards, that directory is missing from your PATH — open a new terminal window first, and consult the troubleshooting guide if it persists.

3.2 Launch inside your project. The agent’s working directory determines what it can see and edit, so always start it from the project folder:

cd ~/gama_workspace/UNIGIS_models
agy

3.3 First-run setup. On first launch the terminal interface walks you through a colour scheme, a rendering mode, and a workspace trust confirmation.

3.4 Sign in. Choose Google OAuth when prompted. A browser window opens; after authorising, copy the code back into the terminal.

3.5 Set the permission mode. By default the agent asks before every write operation, shell command, and network call — mode request-review. Keep this default for the whole module. You can inspect and change it with the /permissions command inside the agent, or in ~/.gemini/antigravity-cli/settings.json. Do not switch to autonomous execution while learning: approving each action one at a time is the exercise.

Part 4 — Give the agent the context it lacks

Recall the collapsible box earlier in this lesson: GAML is underrepresented in training data, so you should help your AI agent to produce good code. Rather than repeating the same corrections in every conversation, write them down once. The agent reads a file called AGENTS.md from the project root at startup and treats it as standing instructions (you may know it as the “context”).

Create AGENTS.md in your project folder with instructions, like these. Feel free to modify these instructions!

# Project rules

- This is a GAMA / GAML agent-based simulation project. 
- as you develop code, do not make any assumptions about the modelled system. Always ask back. 
- always check for logical consistency within the code

## Language rules
- use GAML version 2025-06
- check the GAMA documentation on the web, if you are unsure about how to code GAML: https://gama-platform.org/wiki/Home
- If you are still unsure, say so explicitly instead of inventing anything.

## Working style
- Before editing, state which files you will change and why. Wait for my approval.
- Change only what I asked for. Do not refactor, rename or "improve" unrelated code.
- Comment every species, attribute and reflex with its purpose in the model.
- Do not commit to git unless I ask.

Commit it — these rules are part of the project, not a personal setting:

git add AGENTS.md .gitignore
git commit -m "Add agent rules and gitignore"

Part 5 — Generate, review, run a Hello World model

5.1 Prompt. Start the agent with agy in your project folder and give it your specification. For example:

Create a minimal GAMA model in models/HelloWorld_withAI.gaml.

Specification:
- One species called `cows`, 10 instances created at initialisation.
- Each cow moves randomly
- Cows are drawn as brown circles on a 100x100 world.
- let cows be displayed on a map

Show me the file before writing it.

5.2 Review before accepting. When the agent proposes the file, read it line by line and answer, for yourself:

  • Does every line correspond to something in your specification?
  • Is there anything present that you did not ask for?
  • Can you explain what each block does — global, species, reflex, experiment?
  • Are there keywords you do not recognise?

If something is wrong, say so specifically (“the display block is missing the species declaration”) rather than generically (“it doesn’t work”). Use esc to interrupt the agent mid-turn if it starts down the wrong path, and /diff to see pending changes as a diff.

5.3 Run it in GAMA. Refresh the project in GAMA (right-click → Refresh), open HelloWorld_withAI.gaml, and launch the simulation experiment. You should see brown circles moving randomly.

If it does not compile, note the error message and hand it to the agent verbatim. This is the feedback step of the workflow cycle: the GAMA compiler is your verification mechanism, and the error text is far more informative than your paraphrase of it.

Part 6 — Commit, version, push

6.1 Inspect what actually changed and thoroughly test whether it works. Never commit blind.

Everything fine? Only then ask the AI to “please commit”. The AI will suggest a commit text - rephrase so that it makes sense to you.

6.2 Mark the version. Large functional changes justify a new major version (e.g. v1.5 → v2.0); smaller additions are minor increments (v1.1 → v1.2).

6.3 Verify the remote. Reload your GitHub repository page. The model file and the v0.1 tag should both be visible. Your Hello World is now safely on your GitHub Repo.

5.2 Prompt Engineering

Imagine you ask a colleague: “Can you finish the report?” They know what you mean. They have been in the same meetings, know the deadline, the audience, and what “finished” looks like. They fill in the gaps with shared context you never had to spell out.

Now imagine you send that exact message to a language model.

It will produce a report. Confidently. Immediately. Without asking a single question. But which report? How long? For whom? In what format? Based on which data?

The model is not being careless - it simply has no shared history with you, no implicit understanding of your project, and no habit of asking for clarification before diving in. It filled in every gap you left open, just not the way you intended.

A more explicit version might look like this:

Write a two-page summary report of the traffic simulation results from last week.
The audience is urban planners with no programming background. Use plain language,
include one table comparing the three scenarios, and end with three concrete
recommendations.

Same request, but now the model has context, a defined audience, a format, and a clear goal. The output will be fundamentally different.

This is the core idea behind prompt engineering. It is less about speaking differently and more about thinking carefully about what you are actually asking for. It means being explicit about context, intent, format, and constraints in ways that everyday conversation rarely requires.

5.2.1 Anatomy of a Prompt

A prompt can be broken down into 5 building blocks. Together they give the model everything it needs to produce reliable output.

  1. Role: Who should the model act as? (“You are an expert in agent-based modelling…”)
  2. Context: What is the background? What should your model know about the project?
  3. Task: What exactly should the model do?
  4. Format: How should the ouput look like? Code, markdown, step-by-step instructions, a table?
  5. Constraints: What should it avoid or stay within? (“Only use built-in GAMA operators”)

Not every prompt needs all five but the more unfamiliar the task, the more building blocks you will need.

5.2.2 Basic techniques of prompting

The following techniques form the foundation of effective prompting. A good rule of thumb: start simple and add more guidance only when the output is not what you expected.

  • Zero-shot: You provide no examples. The model completes the task based solely on its training. This works well for common or straightforward requests. (“Write a GAMA species that moves randomly.”)

  • One-shot: You provide exactly one example for the model to orientate itself. Useful when you have a specific style or structure in mind. (“Here is an example of how I write a species. Write a new one in the same style.”)

  • Few-shot: You provide multiple examples. The more examples you give, the better the model understands the pattern you expect. This is particularly valuable for GAMA, where you can show the model your own code style and project conventions before asking it to generate something new. (“Here are three species from my model. Write a fourth one that follows the same pattern.”)

  • Chain-of-thought: You ask the model to explain its reasoning explicitly before producing an answer. This noticeably improves quality for complex tasks, as the model works through the problem rather than jumping straight to a response. (“Think through the problem step by step before writing the code.”)

  • Iterative prompting: A prompt is rarely perfect on the first attempt. Rather than starting over, build on the previous response: correct what was wrong, ask for refinements, or add constraints you forgot to include. Treat the conversation as a dialogue, not a single instruction.

5.2.3 Context Engineering

Whether context engineering is a subtopic of prompt engineering or a discipline of its own is still debated. For this lesson we treat it as an important step that comes before writing the actual prompt — the preparation that makes the prompt work. This matters especially for GAML. Because it is a niche language with limited training data in most models, the quality of the AI response depends heavily on what you bring to the conversation. A well-constructed context is often the difference between a code snippet that runs and one that invents operators that do not exist.

Before writing your next GAMA prompt, work through the following checklist:

  1. Model identity: The LLM must understand what will be simulated, not technically, semantically
This is a pedestrian evacuation model in a urban grid environment.
Agents represent citizens trying to reach exit points.
  1. Already existing code: Provide the relevant .gaml files or just the relevant section. Do not only describe the mistake, provide also the code that produced the error.
Here is my current species definition: [.gaml snippet]
  1. GAML - version & constraints: GAMA is evolving over time, and features that exist in older versions are now deprecated or replaced by new ones.
I am using GAMA 2025-06. Only use built-in operators, no external plugins.
  1. Provide project structure: What exists already? Which dependencies between them exist? You can also provide a file-tree with descriptions.
My model has three species: pedestrians, exits, obstacles.
Pedestrians use a graph built from the road network.
  1. Error message & expectations: Error will occure, but if you want help from AI, you need to provide error, the expected behavior and the code snippet that produced the error.
Error: "Cannot find action move_to for species Pedestrian"
Expected: The pedestrian should move towards the nearest exit each step.
Code: [.gaml snippet]
  1. Documentation: For niche languages like GAML it can be beneficial to refer to the documentation in the context, so it knows where to find the right information and reduce hallucination.

Cost of context: Only include what is directly relevant to your question. More context not always better, it can distract the model, and depending on the tool you use, increase costs.

5.2.4 Common Mistakes

In this section, we look at the most common mistakes made when working with LLMs. Now it is your turn to apply your knowledge you have learned so far. You will be presented with a prompt and asked to identify the mistakes and correct them.

Mistake #1

Make my cow model better.

This prompt gives the model no direction. It will produce something — perhaps adding a new behaviour, changing colours, or restructuring the code — but almost certainly not what you had in mind. “Better” means something different to everyone, and the model will simply guess.

Please improve the wandering behaviour of my cow model. The cow should only be
able to turn up to 75 degrees relative to its current walking direction per step,
so that it moves in smoother, more realistic paths rather than turning around
immediately.

Mistake #2

Cannot find action 'goto' for species pedestrians.

The model has no idea what your species looks like, how it is defined, or what you are trying to achieve. It will guess a fix — likely suggesting a generic solution that either uses operators that do not exist in your GAMA version, or contradicts the structure of your existing code. You will spend more time correcting the response than if you had written the fix yourself.

I am using GAMA 1.9.3. My pedestrians should move towards the nearest
exit each simulation step. Here is my current species definition:

[paste your .gaml species block here]

I get the following error: "Cannot find action 'goto' for species pedestrians."
What is causing this and how do I fix it?

This prompt gives the model your GAMA version, the goal of the species, the existing code, and the exact error — everything it needs to produce a targeted and correct fix.

Mistake #3

Create a complete GAMA model with a road network, pedestrian agents that avoid
obstacles, a dynamic traffic system, real-time weather effects on movement speed,
and a dashboard showing live statistics.

The model will attempt to fulfil every requirement at once — and deliver something that technically compiles but is riddled with errors, missing connections between species, and invented operators. The more tasks you pack into a single prompt, the less reliably each one is handled. You will end up with a large block of broken code that is hard to debug because you do not know which part went wrong first.

Break the request into separate, focused prompts — one task at a time:

Step 1:

Create a basic GAMA species called Pedestrian that moves randomly on a grid.
I am using GAMA 2025-6.

Step 2 — once Step 1 works:

Here is my current pedestrians species: [paste code]
Add the ability for the pedestrian to detect and avoid obstacles within
a radius of 5 meters.

Step 3 — and so on.

Each step builds on verified, working code. This way errors stay small and traceable, and the AI has full context of what already works before adding something new.

5.2.5 Optional: Further Readings

If you want to dive deeper into prompt engineering or other topics regarding LLMs, it can be beneficial to visit the website of the companies that are providing the models, respectively. Most of them offer good documentation about the usage of their services and how to get the most out of their models. For example Anthropic has a dedicated section for Prompt Engineering included in their documentation.

5.3 Verification of AI-generated Code

AI assistants can generate plausible-looking code quickly, but plausible is not the same as correct. A model that compiles and runs is not necessarily a model that does what you intended. Verification is the practice of systematically checking AI-generated code before trusting its output.

Effective verification requires three things that no AI tool can replace:

Domain knowledge: you can only verify what you understand. If you do not know how wildfire spreads physically, you will not notice when the model gets it wrong. Verification requires the ability to form an expectation and compare it against what you observe.

Knowledge of your tools and language: hallucinated operators are only suspicious if you know what actually exists in the language, or at least know where to look. The same applies to file formats, coordinate systems, and API conventions.

Critical distance: the greatest risk in vibe coding is accepting output that looks plausible. Verification requires an active stance: assume errors exist until you have proven otherwise.

5.3.1 Why AI errors are different

We tend to think that AI makes mistakes where tasks get complex. In practice, AI makes a different kind of mistake to those humans would make: errors tend to appear exactly where everything looks straightforward. This is a consequence of how language models work. Rather than understanding code semantically and logically, they predict the most statistically likely next token based on patterns seen during the training process. Code that looks plausible gets generated confidently, regardless of whether it is logically correct.

This means verification cannot rely on intuition alone. Errors made by AI do not follow the same patterns as human mistakes, they appear where code looks most plausible, where humans tend to think the code must be correct and not necessarily where it is the most complex (Tambon et al. 2024). You will encounter this in the work with AI-assisted programming and the exercise at the end of this chapter is designed with exactly this in mind.

5.3.2 GAMA debugging toolkit

Debugging is the procedure to identify and eliminate errors and flaws in your code. It is an integral part of programming. As you develop a new part of your code, you will immediately test and debug it. A systematically tested and debugged code is verified: a verified code does, what it is expected to do.

  • Testing is an integral part of programming
  • Test, while you write
  • Test, before you use the model

For effective debugging, you systematically look into the five different kinds of errors. GAMA supports this task, as it continuously compiles the code that you enter and immediately reports on errors. However, the compiler only finds syntactic and semantic errors. Runtime errors happen during simulation runs and cause the simulation to stop with an error report.

Reference documents

This is a collection of resources to support your model programming tasks throughout this course. Especially the statement documentation will be your permanent companion for coding.

The GAMA website http://gama-platform.org

GitHub Wiki: https://github.com/gama-platform/gama/wiki

  • Errors in your model? Code verification helps: Debugging

Syntax (and semantic) errors

Syntactic errors indicate that a piece of code does not conform to the syntax of the programming language. Semantic errors are similar to syntactic errors; they use a correct syntax, but the syntax does not make sense. The most common error sources are:

  • Missing or incorrect brackets,
  • use of statements that do not exist (often just a misspelling), or
  • only one input is given, if GAMA expects two.

Syntactic and semantic errors are shown with red markers at the erroneous code line. If you hover over the red marker, more information about the error will be displayed. This information can be useful, but sometimes it is not pointing directly to the source of the error. Try to implement the two following statements. Can you spot the error? Which error message do you get?

reflexi myProcess { }
if grid_value > 150.0 []

Warnings

If the model can be compiled, although there is a flaw in the code syntax, you will get a warning. Probably, you have encountered the according yellow ‘warning’ markers before. Often these are caused, when parsing an incorrect data type to a variable. For example, if you declare an integer variable and parse a float value:

    int myVariable <- 10.0;

Warnings can be ignored - at least in the draft versions of your code. It is good practice to avoid them, but this is nothing to spend your nights on.

Runtime errors

Runtime errors cannot be found by the compiler beforehand, they appear during a simulation run. Thus, no red markers appear in the code. A typical example would be a division by a variable that at some point in the simulation takes the value of zero. Runtime errors stop the simulation run immediately and display and error message in the experiment view of GAMA. To learn about where in the code the error originated, you can open the drop down context of the error message.

Figure 5.1: Run-time error message in GAMA that tells you that you tried to divide by zero.

This error is common with random number generators: rnd(10) returns a random value between 0 and 9 (not between 1 and 10 as you may expect). For how long do you expect a model with the following code to run?

int myRandomVariable <- rnd(10);
float myResult <- 100 / myRandomVariable;

Misunderstanding of statements

Domain-specific computer languages like GAMA are written for domain experts. They try to use statements that are as simple and intuitive as possible. However, unlike in human language we still have to deal with a computer language. This means, that no fuzziness or inaccuracy is possible.

For example, you want to find all agents that are at the distance of 20 units from you and type in the following.

myAgents at_distance 20;

What GAMA returns is not the set of agents at the distance = 20, but instead all agents that are exactly within the distance of 20.

To avoid such misunderstandings, carefully check the statement in the GAMA documentation: http://gama-platform.org/. Use the search field at the top right to find the command you are interested in. This website is always open alongside to GAMA, when I code a model.

Figure 5.2: The GAMA documentation is indispensable to understand, what a command does.

Logical errors

Logical errors are the most tricky ones. A logical error is, when the program logic does not match your conceptual model. These are difficult to find, and sometimes you do not even realise that they are there! So, to have a fully verified model, you have to test all model parts and the model as a whole for plausibility for common cases, but also extreme parameter settings.

In case your model produces non-plausible results, this is what you can do:

  1. use common sense

Narrow down the problem: What is strange about your model? What happens? When do the strange things happen? Which code part can be responsible for the behaviour? Think like a compiler, go through the model line by line and try to understand what exactly is computed during one simulation step.

  1. Toggle comments

To effectively narrow down an error, you may want to delete a part of the code that you suspect to cause the problem. However, you would loose a lot of work. So it is better to just tell the computer, that it should ignore it. So, you want to comment it out. Remember: this is done with the double-slash at the beginning of the code line //. To do this for an entire code block, select the code and use the shortcut CTRL and 7 to toggle the code on and off.

Of course you can do this only, if these are not essential parts of a model. However, for example a where clause of an if statement can easily be commented out. The same can be true for a reflex statement block.

Report the state of the model to the console

Reporting the model state is actually good practice in programming. Write the current value of a variable to the console. This slows down the model, but performance is not important in the testing phase. It’s quite common that I have 5 or 10 write statements distributed in my code, while I am testing.

The following statement will write the location and the corresponding value of all cells to the console. Try it out and check the result in the Console!

  write "Grid value of " + grid_x + " " + grid_y + ": " + grid_value;

Hint: use write statements within if blocks to test, whether and when it is executed.

Visualise the state of the model to a map or chart

For an exploratory testing phase, visualisation can be more effective than writing values of variables.

  • Make use of the map output to visualise the state of agents and cells. Use different shapes for different types of agents, use size to visualise values, shade the cells, according to the grid_value. Change colours, in case of a certain action or if statement is executed.
  • Make use of the inspect functionality in the map output: right mouse click on the cell or agent you want to explore in more detail -> inspect. The agent will be highlighted and all attribute values displayed.
  • Make use of monitors and the chart output to see the state and trend of variables.

All these visualisations are explorative and part of testing. They are not included in the final code, but are indispensable for verification.

Use the interactive console

There are two types of consoles in GAMA: the ‘regular’ console and the ‘interactive console’. The first reports whatever your model writes to the console. The latter allows you to interact with the current state of your model in a simulation.

If you want to experiment with the interactive console, open the toy model “Life.gaml” and check the code: the cellular automaton in this model is called “life_cell” and it has a variable called new_state. Now, start the experiment and type into the interactive console:

  ask life_cell {write new_state;}

Switch to the regular console and check the results. Now go one simulation step forward, switch back to the interactive console (delete everything with the crossed out A) and type in again the above statement. Check the results.

What happens, if you type in the following?

  ask life_cell {color <- #green;}

The interactive console is extremely valuable, when you want to test whether a piece of code acts like you want, or when you want to interactively explore the state of your model.

You are now well-equipped to identify and eliminate errors. Good luck!

5.3.3 A framework for verification

Regardless of the programming language, simulation platform, or domain, AI-generated code can fail at four distinct levels. Working through them in order is more efficient than searching randomly.

Level 1 — Syntax and compilation Does the code run at all? The development environment will tell you immediately. Errors at this level are the easiest to find but not always the easiest to fix, particularly when the cause is a hallucinated function that looks legitimate. The key question: does every operator or function actually exist in this language?

Level 2 — Data and environment Does the model load the right data correctly? Many environments fail silently when a file is missing or misnamed, no error message, just empty output. The key question: does the model produce the expected number of agents, rows, or features after loading?

Level 3 — Spatial and technical correctness Do the technical relationships hold coordinate systems, units, geometric operations, data types? These errors require looking beyond the code itself and checking the underlying data and configuration. The key question: do the outputs align with a known reference?

Level 4 — Logic and domain correctness Does the model behave as the domain would predict? The code compiles, the data loads, the geometry looks right but the simulation does something physically or conceptually wrong. These are the hardest errors to find because no tool will flag them. The key question: does the output match what I would expect from a simple, controlled test case?

This framework applies to any AI-generated simulation code whether written in GAML, Python, R, or NetLogo. The specific tools change, but the four levels remain the same. In the exercise below, each level is illustrated with a concrete error from an AI-generated GAMA model.

5.3.4 Exercise — Wildfire Salzachauen

Exercise: Wildfire Salzachauen

The following exercise applies these four levels to a concrete example. You receive an AI-generated wildfire simulation for the Salzachauen — a Natura 2000 protected forest area near Salzburg. The model was produced using the prompt from the previous chapter. Your task is to find and fix all errors by working through each verification level systematically.

Download the zip file for this exercise here and place the files as follows in your GAMA project:

Vibe_Coding_Verification_Task/
├── models/
│   └── Wildfire_Salzachauen_errors.gaml   ← AI-generated model with errors
├── includes/
│   ├── salzachauen_forest.shp
│   ├── ...
│   └── salzachauen_water.shp
└── solutions/                            ← solution files for every level
    ├── Wildfire_Salzachauen_level1.gaml
    ├── ...
    └── Wildfire_Salzachauen_final.gaml

Place the model file in your GAMA project models/ folder and the shapefiles in includes/.

Level 1 — Syntax and compilation errors

Load Wildfire_Salzachauen_errors.gaml in GAMA. Do not read the code first — load it directly and observe what happens.

What error messages does GAMA throw? Can you identify which line causes the error?

Look at the error message carefully. It will point to a specific line. If an operator name looks unfamiliar, search for it in the GAMA documentation.

Wildfire spread is a common simulation use case, which means language models have seen many examples of it but not necessarily in GAML. As a result, the model invented a built-in action spread_fire() that does not exist in GAMA. This is a typical hallucination: the operator name sounds plausible and fits the context, but GAMA will throw a compilation error the moment you try to run the model. Always verify unfamiliar operators against the GAMA documentation before running.

The spread logic needs to be implemented manually. Before looking at the solution, try to sketch an approach yourself using the hints below.

  1. The spread reflex should only trigger when the cell state is "burning"
  2. Each burning cell has a timer. When it reaches zero the cell turns "burnt" and stops spreading
  3. Burning cells can only ignite neighbours that are unburned forest cells, water cells act as firebreaks and must be excluded
  4. For each candidate neighbour, calculate the angle from the current cell towards the neighbour using towards
  5. Compute the angular difference between that angle and the wind direction, mirror differences above 180° so the result is always between 0° and 180°
  6. Adjust the ignition probability based on the angular difference: increase it if the neighbour is within the wind cone, decrease it if it lies against the wind
  7. Draw a random number, if it falls below the adjusted probability, ignite the neighbour and update its state, timer, and colour
reflex spread when: state = "burning" {

    burn_timer <- burn_timer - 1;
    if (burn_timer <= 0) {
        state <- "burnt";
        color <- rgb(60, 60, 60);
    }

    ask neighbors where (each.state = "unburned"
        and each.cell_type = "forest") {

        float angle_to_neighbour <- myself.location towards self.location;
        float angle_diff <- abs(angle_to_neighbour - wind_direction) mod 360.0;
        if (angle_diff > 180) { angle_diff <- 360 - angle_diff; }

        float prob <- base_probability;
        if (angle_diff <= wind_cone) {
            prob <- prob - wind_bonus * wind_speed;
        } else if (angle_diff >= (180 - wind_cone)) {
            prob <- max(0.0, prob + wind_penalty * wind_speed);
        }

        if (rnd(1.0) < prob) {
            state      <- "burning";
            burn_timer <- burn_duration;
            color      <- rgb(255, 80, 0);
        }
    }
}

Once you have identified the hallucinated operator, you can ask an AI assistant to help you implement the correct spread logic. A well-structured prompt for this error would look like this:

I am using GAMA 2025-06. I have a grid-based wildfire model where each
FireCell should spread fire to its neighbouring forest cells. The AI-generated
code used spread_fire() which does not exist in GAML.

Here is the relevant species definition: [paste FireCell species]

Please implement the spread reflex manually. It should:
- Only trigger when the cell state is "burning"
- Count down a burn timer and turn the cell "burnt" when it reaches zero
- Spread to unburned forest neighbours within a 4-cell neighbourhood
- Adjust ignition probability based on wind direction and a wind cone angle
- Only use built-in GAML operators

Level 2 — Data and path errors

Fix the compilation error from Level 1 so the model loads. Run the simulation and observe what happens.

Does the simulation produce the expected output?

GAMA does not always throw an error when a file cannot be found — it may simply create zero agents and continue running silently. This makes data and path errors harder to spot than compilation errors. Checking the monitors for agent counts immediately after starting the simulation is a good habit to build whenever you load a new model.

The file paths in the model point to .gpkg files, but the files in your includes/ folder are Shapefiles (.shp). GAMA loads nothing and creates no agents — without throwing an error message.

The fix is to correct the file extension in both paths:

file forest_file <- file("../includes/salzachauen_forest.shp");
file water_file  <- file("../includes/salzachauen_water.shp");

This is also a prompt engineering lesson: always specify the exact file format and extension in your prompt. The more specific you are about file formats, the less room there is for the model to guess incorrectly.

Data and path errors are easy to fix once identified but the prompt matters to prevent them from appearing in future generations:

I am using GAMA 2025-06. My model loads two Shapefiles (.shp) from the
includes/ folder of my GAMA project. The correct paths are:

forest_file: "../includes/salzachauen_forest.shp"
water_file: "../includes/salzachauen_water.shp"

The AI previously used .gpkg instead of .shp. Please correct the file
paths and confirm no other path references exist in the model.

Note that this type of error is best prevented at the prompting stage — specifying the exact file format and path structure in your initial context removes any ambiguity.

Level 3 — Spatial errors

The fire now spreads correctly. Watch it carefully near the water bodies.

Does the fire stop at the water or does it cross it?

There are two separate spatial errors here. One is in the cell classification logic in the code — look at the order in which cell types are assigned in the init block. The other is in the geodata itself, check the CRS of your shapefiles in QGIS under Layer Properties → Information.

Error A — Water priority inverted

In the init block, the cell classification checks for forest before checking for water:

if (forest_union != nil and shape intersects forest_union) {
    cell_type <- "forest";
} else if (water_union != nil and shape intersects water_union) {
    cell_type <- "water";
}

Along riverbanks, many grid cells overlap with both the forest and the water geometry. Because forest is checked first, these cells are classified as forest and can burn, the river no longer acts as a firebreak. The fix is to check water first, so that any cell touching a water body is always classified as water regardless of what else it overlaps:

if (water_union != nil and shape intersects water_union) {
    cell_type <- "water";
} else if (forest_union != nil and shape intersects forest_union) {
    cell_type <- "forest";
}

Error B — Wrong coordinate reference system

Even with the classification fixed, the grid may appear misaligned or the forest and water areas may not correspond to their real-world locations. You have two options to check the CRS:

  1. Hover with the cursor over the shapefile path, a dialog is opening and the corresponding CRS is displayed (see Figure 5.3)
Figure 5.3: Showing the CRS of shapefile when hovering over the file path in GAMA
  1. Open the shapefiles in QGIS and check their CRS under Layer Properties → Information → Coordinate Reference System (CRS)

The Salzachauen area lies in UTM Zone 32N, the correct CRS is EPSG:25832. If your shapefiles are in EPSG:4326 (WGS84, degrees), GAMA will load the geometries in geographic coordinates rather than metric ones. The grid cell size will no longer correspond to real-world metres, and the spatial relationships between cells and geometries will be distorted.

To fix this, reproject both shapefiles in QGIS:

  1. Right-click the layer → Export → Save As
  2. Set CRS to the same as the other shapefile
  3. Save and replace the files in your includes/ folder

For Error A, AI can fix the classification order directly — provide the relevant init block and describe what you observed:

I am using GAMA 2025-06. In my wildfire model, fire crosses water bodies
instead of stopping at them. Here is the cell classification in my init block:

[paste init block]

The shapefiles are salzachauen_forest.shp and salzachauen_water.shp in
EPSG:25832. Water bodies should act as firebreaks, no FireCell classified
as water should ever burn. Please fix the classification logic.

For Error B, AI cannot fix a CRS issue that requires working directly in QGIS. However, AI can help you write the correct processing script to reproject your files or where you find the option to reproject it within QGIS if needed.

Level 4 — Logic errors

The model now loads and the spatial relationships are correct. Run the simulation and observe the fire spread carefully.

Set the wind origin to 90° (East) in the parameter panel. Does the fire spread predominantly eastward? Change to 270° (West). Does the spread direction change accordingly?

Pick a clear wind origin like 0° (North) or 90° (East) and watch where the fire front moves after 20 to 30 steps. If it moves in the opposite direction, look at how the wind bonus and penalty are assigned in the spread reflex — specifically which angular condition receives which probability adjustment.

The wind bonus and penalty are swapped. In the spread reflex, the ignition probability is adjusted based on the angle between the spreading direction and the wind direction:

if (angle_diff <= wind_cone) {
    prob <- max(0.0, prob - wind_penalty * wind_speed); // ERROR: should increase
} else if (angle_diff >= (180 - wind_cone)) {
    prob <- prob + wind_bonus * wind_speed;             // ERROR: should decrease
}

A small angle_diff means the neighbour lies in the wind direction — fire should spread faster there, so the probability should be increased. A large angle_diff means the neighbour lies against the wind — fire should spread slower, so the probability should be decreased. Here the logic is reversed: the model penalises spread in the wind direction and rewards spread against it.

The fix is to swap the two assignments:

if (angle_diff <= wind_cone) {
    prob <- prob + wind_bonus * wind_speed;             // with the wind: increase
} else if (angle_diff >= (180 - wind_cone)) {
    prob <- max(0.0, prob - wind_penalty * wind_speed); // against the wind: decrease
}

This error is a good example of why logic errors are the hardest to find: the model compiles, loads, and runs without any warning. The only way to catch it is to observe the output, form an expectation based on the physical process being modelled, and compare the two. No error message will ever point you here.

Logic errors are where AI assistance is most valuable but only if you describe the observed behaviour precisely rather than just sharing the code:

I am using GAMA 2025-06. My wildfire model has a wind-driven spread
reflex but the fire spreads in the wrong direction. When I set
wind_direction to 90° (East), the fire spreads westward instead.

Here is my spread reflex: [paste reflex code]

The angle_diff variable represents the angular difference between the
spread direction and the wind direction. A small angle_diff means the
neighbour is in the wind direction. Please identify and fix the error
in the probability adjustment logic.

Describing the expected physical behaviour — fire spreads with the wind, not against it — gives the model the domain knowledge it needs to identify the swap without guessing.

References