starcode-labyrinth 0.1.0

A module to draw labyrinth maps and navigate through them. This is intended for teaching.

Starcode Labyrinth

Copyright (C) 2022 - Benjamin Paassen
starcode

This program 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; if not, see http://www.gnu.org/licenses/.

Introduction

This module provides functions to draw labyrinth maps and execute agents in form of finite state machines on them. This module is intended for teaching, in particular during the courses of starcode.

Overview

The key concept for this module is that of an agent, which is described by a function of the following form.

from starcode_labyrinth import logic

def agent(free, memory):
    return logic.GO, 'new_memory'

The function receives two inputs. The first one is a boolean indicating whether the field ahead of the agent is free or not. The second one is the current memory state of the agent. The first output is the next action of the agent (either logic.GO, logic.LEFT, or logic.RIGHT). The second output is the next memory state of the agent.

You can execute your agent on a level via the following function. In this case, we use the first standard level provided by the logic package.

trace = logic.execute_agent(agent, level = logic.levels[0], start_memory = 'start_memory')

This function calls your agent again and again and executes the actions (if possible). The output is a list of states, indicating where the agent is in the level and the memory state.

If you want to inspect the trace, you can use the drawing function.

from starcode_labyrinth import drawing
drawing.draw_trace(trace, level = logic.levels[0])

This will look something like this:

The agent is visualized via the blue triangle. The orientation of the agent is indicated by its point. The goal of the labyrinth is the orange star. In this case, the agent does indeed end up at the goal.

The module also provides a feedback function to execute an agent on an entire list of levels and check where it fails.

from starcode_labyrinth import feedback
feedback.evaluate_agent(agent, start_memory = 'start_memory')