This repository provides a Tutorial on using the Python 3 interface for FLAME GPU 2.
The tutorial is a jupyter notebook which uses a predator-prey model to demonstrate how models can be described and implemented using FLAME GPU 2's python interface, and then simulated to observe population dynamics over the duration of a single simulation.
A number of exercises are presented to change and extend the behaviour of the model and observe the differences. Solutions are provided.
Instructor-led delivery of this tutorial will typically use hosted Jupyter solutions, such as cloud instances on InstanceHub or through Google Colab.
Please refer to the instructions provided during by the instructor(s) on how to access the tutorial in this case.
If you are interested in an instructor-led delivery of this tutorial, please contact us.
This tutorial was previously delivered at:
- 2021-09-08 SeptembRSE 2021 Workshop S1005: FLAME GPU 2: Complex Systems Simulation using GPUs
- Delivered by Paul Richmond, Matthew Leach, Peter Heywood and Robert Chisholm
- Introductory Talk Recording
If you wish to follow this tutorial at your own pace, you can run this tutorial locally, or use a hosted service such as Google Colab.
The tutorial can be completed independently in the browser using Google Colab, which is a hosted fork of Jupyter.
- Open the tutorial on Google Colab
- If present, click the "Connect" button in the top right corner
If successful, the Connect button should be replaced with a green tick and RAM/Disk indicators, so it can be used like a regular Jupyter notebook. It's possible that a free instance will fail to be allocated, in which case please try again later. Free Google Colab instances use a variety of hardware, so performance may vary between instances.
Note: The notebook currently assumes you are using python 3.6, with CUDA 11.0 on a Linux x86_64 machine. This will be corrected in the future.
To run this tutorial locally you will require:
- Python
>= 3.6 - CUDA
>= 11.0and a Compute Capability >= 3.5 NVIDIA GPU - Linux with
glibc >= 2.17- Windows support/instructions will be introduced at a later date
- An
x86_64CPU- Including
NVRTC - If you wish to run this tutorial on an
ppc64leorarm64-sbsabased-system, you will need to buildpyflamegpufrom source. Please see the main FLAMEGPU/FLAMEGPU2 repository for instructions on building from source.
- Including
-
Clone the repository if you have not already done so
-
Create a new python
venvor conda environment and activate it# I.e. if using a venv on linux python3 -m venv venv source venv/bin/activate
-
Install Jupyterlab (or jupyter notebook)
# I.e. if using a venv and pip python3 -m pip install -U jupyterlab matplotlib -
Launch
jupyter labor the legacyjupyter notebookinterface and openFLAME_GPU_2_python_tutorial.ipynb# Using jupyter lab jupyter lab FLAME_GPU_2_python_tutorial.ipynb # Using jupyter notebook jupyter notebook FLAME_GPU_2_python_tutorial.ipynb
Run time compilation of agent functions may fail if there are errors in the agent functions.
These errors are output to stdout by Jitify, a c++ library used to simplify run time compilation via NVRTC.
Older versions of ipykernel (< 6.0.0a5) do not capture stdout or stderr from python cells correctly, meaning that the error messages explaining compilation errors are not visible within the notebook.
To avoid this, and have visible error messages please ensure that you are using ipykernel >= 6.0.0a5.
Note:
ipykernel >= 6.0requirespython >= 3.7
Alternatively the errors will be visible in the shell the ipython/jupyter server, if this is available to you.
Google Colab uses an older version of ipykernel, which exhibits this issue.
It is possible to update this, by upgrading ipykernel via pip inside the Colab session, and then restarting the kernel.
WARNING: This may cause other errors with package version mismatches
-
Execute the following in a notebook cell in Google Colab
import sys !{sys.executable} -m pip install -U -q ipython ipykernel>=6.0.0
-
Restart the Runtime by either:
Runtime>Restart Runtime>Yesctrl+M .>Yes