# Running SUEWS with Python (Beginner's Guide)

**URL:** <https://community.suews.io/t/running-suews-with-python-beginners-guide/15>\
**Category:** Getting Started\
**Created:** [8 January 2026 16:45 UTC](https://community.suews.io/t/running-suews-with-python-beginners-guide/15 "2026-01-08T16:45:40Z")\
**Posts on this page:** 3\
**Page:** 1

<div class="post-metadata">

**Author:** ![sunt05](https://dub1.discourse-cdn.com/flex014/user_avatar/community.suews.io/sunt05/32/5_2.png) [@sunt05](https://community.suews.io/u/sunt05)\
**Post date:** [8 January 2026 16:45 UTC](https://community.suews.io/t/running-suews-with-python-beginners-guide/15/1 "2026-01-08T16:45:40Z")

</div>

## 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](https://en.wikipedia.org/wiki/Python_(programming_language))—a way to give computers instructions by typing commands. Modern computers usually have it pre-installed ([how to check](https://realpython.com/installing-python/)).

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:

```auto
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 `--user` to install in your personal folder: `pip3 install --user supy`. For a cleaner setup, see our guide on [Setting Up Python with uv](https://community.suews.io/t/setting-up-python-with-uv-best-practice/16).

* * *

### 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:

```auto
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:

```auto
python3

```

Your prompt changes to `>>>`. Python is listening. Everything you type now is Python code.

Three lines. That’s all you need:

```python
from supy import SUEWSSimulation

```

This loads SuPy’s simulation tools into your computer memory.

```python
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.

```python
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:

```python
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:

```python
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:

```python
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)](https://doi.org/10.1016/j.jhydrol.2011.10.001), [Grimmond & Oke (1991)](https://doi.org/10.1029/91WR00557), and the [SuPy paper](https://doi.org/10.5194/gmd-12-2781-2019) 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.

```python
import matplotlib.pyplot as plt

```

This loads Python’s plotting library.

```python
fig, ax = plt.subplots()

```

This creates a figure—a canvas—and an axes, the space where your plot will live.

```python
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.

---

<div class="post-metadata">

**Author:** ![sunt05](https://dub1.discourse-cdn.com/flex014/user_avatar/community.suews.io/sunt05/32/5_2.png) [@sunt05](https://community.suews.io/u/sunt05)\
**Post date:** [9 January 2026 13:18 UTC](https://community.suews.io/t/running-suews-with-python-beginners-guide/15/2 "2026-01-09T13:18:45Z")

</div>



---

<div class="post-metadata">

**Author:** ![sunt05](https://dub1.discourse-cdn.com/flex014/user_avatar/community.suews.io/sunt05/32/5_2.png) [@sunt05](https://community.suews.io/u/sunt05)\
**Post date:** [9 January 2026 13:21 UTC](https://community.suews.io/t/running-suews-with-python-beginners-guide/15/3 "2026-01-09T13:21:03Z")

</div>