Pikmin-Propagation Simulator

Created By Katja Mathesius

Flask tool for computing the pikmin propagation number of graphs. Based on research of the same title by Katja Mathesius and DJ Henson, as supervised by Dr. Joshua Carlson.

Description - What is Pikmin Propagation?

Pikmin Propagation is a game on graphs which combines elements of graph searching problems and graph coloring problems. The objective of the game is to completely color a graph by utilizing "pikmin agents"- entities that can move between vertices on a graph and color vertices. Pikmin agents have the special property that on a turn they can choose to move to an adjacent vertex, then choose to color that vertex either "red" or "blue". Coloring a vertex red creates an additional pikmin, while coloring blue has no special affects. The game ends when the graph is fully colored, and optimality of a game is judged by minimizing the total turns taken plus the total vertices colored red.

How to Run the Simulation Tool

The simulation tool comes in the form of a flask application. Code for the project can be found under the "simulator" folder in the github repository.

Requirements

• Python >= 3.12.3

Quick-Start Simulation Application Instructions

1. Navigate to the flask_skeleton folder on your terminal
2. Run pip install -r requirements.txt to install the projects required dependencies
3. Run flask --app main run to start the flask app
4. The application should now be available by opening localhost:5000 in your browser

File Guide

• main.py
  • Builds the application. This file is the point through which the flask application gets created.
• routes.py
  • Called by main.py, this file contains all of the information for managing the relationship between the UI as built out in pik_sim.html and the game logic as governed in graphs.py. routes.py contains management for the variables that are supposed to be displayed by pik_sim.html. It also interprets the form inputs from pik_sim.html and runs the correct function in graphs.py to update the simulation.
• graphs.py
  • The brains of the simulation tool. graphs.py contains a plethora of functions for managing the simulation, including functions for creating graphs using pyvis, checking the validity of and executing turns, and converting pyvis graphs to and from flask session saveable components (a flask session is a way of saving variables across a "session" of the application being open in a browser, which allows the multi-step process of simulating something to occur). The most noteable rule of interacting with graphs.py is every function that requires making a check or modification on the graph, the function must begin with net = rematerialize_net() to load the graph and end with dematerialize_net(net) to save the changes.
• /templates/
  • pik_sim.html
    • The interface of the simulation tool. This component contains all of the interfaces a user should have for interacting with the app, the displays of information, and a display of the pik_graph.html graph visualization. It contains many flask enabled intricacies as found in the sections set aside in {}s (e.x. {% if pikmin_agents_control != [] and not game_complete %} and then later {end if}, allows for any html inside the block to only be displayed condition on if those conditions are true. {}s can be used to perform checks on or display variables that are specified in the "render_template()" function at the bottom of routes.py). It recieves stylization from /static/css/simulation_interface.css.
  • pik_graph.html
    • This file is generated by pyvis and contains the information for displaying the visualizations. This file is not for manual editing and should only be modified by way of pyvis.network's "save_graph()" function
  • pik_graph_blank.html
    • This file is generated by pyvis and contains an empty graph visualization space. Like with pik_graph.html this is not a file that should be modified by hand.