What you will achieve (in 15 min)
You will run your first urban climate simulation with SUEWS.
No prior Python experience needed. We will explain each step as we go—not just what to type, but why it matters.
Why Python?
As Python is widely used, skills you learn here are transferable.
By writing some code, rather than only clicking buttons:
- others can see exactly what you did—including your future self, six months later (Code is transparent)
- code saves time - one simulation or a hundred - once can rapidly re-use the code by changing a loop, process fifty urban areas overnight (Code scales)
- Download data, run SUEWS, analyse results, generate figures—one script, no copy-pasting. Code connects the steps.
This tutorial assumes you are new to Python.
Step 1: Check Python is available
Python is a programming language—a way to give computers instructions by typing commands. Modern computers usually have it pre-installed (how to check).
Let’s check.
Open a terminal. This is where you’ll type commands:
- Mac: Applications → Utilities → Terminal
- Windows: Search “Command Prompt” or “PowerShell”
- Linux: You know where it is
When the terminal opens, you will see a blinking cursor on a blank screen. This is where you type commands:
python3 --version
See Python 3.x.x? You’re ready. Skip to Step 2.
If the response is “not found”:
- Windows: Type
python—Windows will offer to install Python from the Microsoft Store. Accept (this takes about two minutes). - Permission denied? Try adding
--userto install in your personal folder:pip3 install --user supy. For a cleaner setup, see our guide on Setting Up Python with uv.
Step 2: Install SuPy
Python is used for many applications - so for urban climate we are using SuPy.
SuPy (SUEWS in Python) is a wrapper—a translator between your Python commands and the SUEWS model.
- You will write some simple Python command, that SuPy will use.
To install SuPy - type in the terminal window:
pip3 install supy
Text scrolls past. That’s normal—pip is downloading SuPy and its dependencies. When you see your prompt again, SuPy is ready.
Step 3: Run your first simulation
Now you are ready for the interesting part.
Type:
python3
Your prompt changes to >>>. Python is listening. Everything you type now is Python code.
Three lines. That’s all you need:
from supy import SUEWSSimulation
This loads SuPy’s simulation tools into your computer memory.
sim = SUEWSSimulation.from_sample_data()
This creates a simulation using built-in sample data—a London neighbourhood, one full year of weather observations, complete site characteristics. Everything SUEWS needs, bundled for learning.
output = sim.run()
This runs the model. SUEWS is now calculating the urban energy and water balance for every hour of that year. Heat moving between buildings, air, and sky. Water evaporating from parks and flowing into drains. Thousands of calculations, completed in seconds.
When >>> reappears, you’ve just modelled a year of urban climate.
Step 4: Explore your results
The output object holds everything SUEWS calculated. Let’s look.
Sensible heat flux—energy warming the air above the surface:
print(output.QH.head())
Numbers appear in W/m² (watts per square metre).
- Positive values mean the surface is heating the air
- Negative means the air is warming the surface.
Latent heat flux—energy consumed by evaporation:
print(output.QE.head())
This energy comes from vegetation transpiring, puddles drying, air conditioners exhausting moisture. It cools the surface by using heat to change liquid water to a gas (water vapour).
Air temperature at 2 metres:
print(output.Tair.head())
What you’d feel walking down the street.
Explore further. output.QN for net radiation. output.Precip for rainfall. Each variable tells part of the urban climate story—see Järvi et al. (2011), Grimmond & Oke (1991), and the SuPy paper for the science behind SUEWS.
Step 5: Plot the results
Numbers are very useful but quickly become hard to see patterns when there are lots of values. So we can create some graphs.
import matplotlib.pyplot as plt
This loads Python’s plotting library.
fig, ax = plt.subplots()
This creates a figure—a canvas—and an axes, the space where your plot will live.
output.QH.plot(ax=ax)
ax.set_ylabel('Sensible Heat (W/m²)')
ax.set_title('My First SUEWS Output')
fig.savefig('my_first_plot.png')
print('Saved!')
Check your folder. my_first_plot.png is your first urban climate visualisation.
You should see variations with higher values on summer afternoons when there is more sun heating streets and then the air. At night there are low or negative values. In winter, there is less solar energy so the daily variations are less. These patterns (daily, seasonally) showing different responses of the urban surface heating the atmosphere—is what SUEWS captures.
Type exit() to leave Python.
What you have accomplished
You’ve just:
- Installed scientific software from the command line
- Run a complete urban climate simulation
- Queried model output programmatically
- Created a data visualisation
These are transferable skills. The sample data comes from real measurements. The physics is identical whether you’re learning or publishing.
Next: Understanding what these results mean—we’ll explain the science behind the numbers.
Stuck? Post your question here. There are no silly questions.