Tip

1. Need help? Please let us know in the SUEWS Community.

2. Please report issues with the manual on GitHub Issues (or use Report Issue for This Page for page-specific feedback).

3. Please cite SUEWS with proper information from our Zenodo page.

8. Troubleshooting

8.1. General

8.1.1. How to report an issue of this manual?

Please click the link in the top banner of each page to report page-specific issues.

Please submit your issue via our GitHub page.

8.1.2. 2. How to join your email-list?

Please join our community here.

8.1.3. 3. How to create a directory?

Please search the web using this phrase if you do not know how to create a folder or directory

8.1.4. 4. How to unzip a file

Please search the web using this phrase if you do not know how to unzip a file

8.1.5. 5. A text editor

A program to edit plain text files. If you search on the web using the phrase ‘text editor’ you will find numerous programs. These include for example, NotePad, EditPad, Text Pad etc

8.1.6. 6. Command prompt

From Start select run –type cmd – this will open a window. Change directory to the location of where you stored your files. The following website may be helpful if you do not know what a command prompt is: http://dosprompt.info/

8.1.7. 7. Day of year [DOY]

January 1st is day 1, February 1st is day 32. If you search on the web using the phrase ‘day of year calendar’ you will find tables that allow rapid conversions. Remember that after February 28th DOY will be different between leap years and non-leap years.

8.2. SUEWS related

8.2.1. ESTM output

First time steps of storage output could give NaN values during the initial converging phase.

8.2.2. First things to Check if the program seems to have problems

• Check the Python runtime logs (SuPy logger output). Legacy problems.txt/warnings.txt files are no longer written.

• Check file options – in RunControl.nml.

• Look in the output directory for the SS_FileChoices.txt. This allows you to check all options that were used in the run. You may want to compare it with the original version supplied with the model.

• Note there can not be missing time steps in the data. If you need help with this you may want to checkout UMEP

8.2.3. A pop-up saying “file path not found”

This means the program cannot find the file paths defined in RunControl.nml file. Possible solutions: - Check that you have created the folder that you specified in RunControl.nml. - Check does the output directory exist? - Check that you have a single or double quotes around the FileInputPath, FileOutputPath and FileCode

===="%sat_vap_press.f temp=0.0000 pressure dectime"==== Temperature is zero in the calculation of water vapour pressure parameterization.

• You don’t need to worry if the temperature should be (is) 0°C.

• If it should not be 0°C this suggests that there is a problem with the data.

8.2.4. %T changed to fit limits

[TL =0.1]/ [TL =39.9] You may want to change the coefficients for surface resistance. If you have data from these temperatures, we would happily determine them.

8.2.5. %Iteration loop stopped for too stable conditions.

[zL]/[USTAR] This warning indicates that the atmospheric stability gets above 2. In these conditions MO theory is not necessarily valid. The iteration loop to calculate the Obukhov length and friction velocity is stopped so that stability does not get too high values. This is something you do not need to worry as it does not mean wrong input data.

8.2.6. “Reference to undefined variable, array element or function result”

Parameter(s) missing from input files. See also the error messages and warnings emitted to the console / Python logger.

8.3. SuPy related

8.3.1. I cannot install SuPy following the docs, what is wrong there?

Please check if your environment meets the following requirements:

1. Operating system (OS):

   1. is it 64 bit? only 64 bit systems are supported.

   2. is your OS up to date? only recent desktop systems are supported:

   • Windows 10 and above

   • macOS 10.13 and above

   • Linux: no restriction; If SuPy cannot run on your specific Linux distribution, please report it to us.

   You can get the OS information with the following code:

   import platform
   platform.platform()
   

3. Python interpreter:

   1. is your Python interpreter 64 bit?

      Check running mode with the following code:

      import struct
      struct.calcsize('P')*8
      

   2. is your Python version above 3.5?

      Check version info with the following code:

      import sys
      sys.version
      

If your environment doesn’t meet the requirement by SuPy, please use a proper environment; otherwise, please report your issue.

8.3.2. How do I know which version of SuPy I am using?

Use the following code:

import supy
supy.show_version()

Note

show_version is only available after v2019.5.28.

8.3.3. A kernel may have died exception happened, where did I go wrong?

The issue is highly likely due to invalid input to SuPy and SUEWS kernel. We are trying to avoid such exceptions, but unfortunately they might happen in some edge cases.

Please report such issues to us with your input files for debugging. Thanks!

8.3.4. How can I upgrade SuPy to an up-to-date version?

Run the following code in your terminal:

python3 -m pip install supy --upgrade

8.3.5. How to deal with KeyError when trying to load initial model states or running SuPy (e.g. KeyError: 'sfr_surf')?

This is usually due to the incompatibility between the input files and the model version.

Please check the following:

• if you are using the init_supy to generate the initial model states from your input data, please make sure the file format is consistent with the sample data shipped by SuPy.

• if you are using the df_state generated from a previous run, please double-check if your df_state has the same format as the sample df_state generated by load_SampleData.

A general rule of thumb is to use the load_SampleData to generate the initial model states from the sample data shipped by SuPy.

8.3.6. Wind speed seems incorrect when using EPW data

Symptom: Wind-related outputs (turbulent fluxes, roughness parameters, u*) appear unrealistic when using EPW weather files.

Likely cause: Mismatch between EPW wind speed measurement height (10 m) and configured forcing height (z).

EPW files contain wind speed measured at 10 m above ground level. If your site configuration uses a different forcing height (e.g., z: 50), SUEWS will incorrectly assume the EPW wind data originated from 50 m, leading to erroneous friction velocity and flux calculations.

Solution: Ensure your site configuration sets z: 10 when using EPW data:

sites:
  - name: "MySite"
    properties:
      z: 10.0  # Match EPW standard wind measurement height

Alternatively, use the target_height parameter in read_epw() to extrapolate wind speed to your desired forcing height:

import supy as sp
from pathlib import Path

# Extrapolate EPW wind speed from 10 m to 50 m
df_epw = sp.util.read_epw(
    Path("weather.epw"),
    target_height=50.0,
    z0m=0.5  # roughness length for urban areas
)

See Meteorological Forcing Data for detailed guidance on EPW data usage.

8.3.7. YAML Configuration Validation Errors

When your YAML configuration has missing or invalid parameters, SUEWS will:

1. Display clear error messages in the log indicating which parameters are missing

2. Generate an annotated YAML file with helpful guidance

The annotated YAML file features:

• File location: {config_file}_annotated.yml

• Missing parameters are marked with [ERROR] MISSING:

• Helpful tips are marked with [TIP] ADD HERE:

• Each error includes the expected type and description

Example of annotated output:

sites:
  - name: "London_KCL"
    properties:
      lat: {value: 51.5115}
      lng: {value: -0.1160}
      # [ERROR] MISSING: alt (Site altitude above sea level [m])
      # [TIP] ADD HERE:
      alt: {value: 10.0}  # Example: 10.0 meters above sea level

      land_cover:
        bldgs:
          sfr: {value: 0.45}
          # [ERROR] MISSING: bldgh (Mean building height [m])
          # [TIP] ADD HERE:
          bldgh: {value: 20.0}  # Example: 20.0 meters

To fix validation errors:

1. Generate an annotated YAML file using one of these methods:

   • Manual: Call config.generate_annotated_yaml('config.yml')

   • Automatic: Load with SUEWSConfig.from_yaml('config.yml', auto_generate_annotated=True)

2. Look for the annotated YAML file ({config}_annotated.yml) in the same directory

3. Search for [ERROR] markers to find missing parameters

4. Add the missing parameters with appropriate values

5. Re-run your simulation with the corrected configuration

Common validation errors:

• Missing building height (bldgh) when buildings are present

• Missing thermal properties when using advanced storage heat methods

• Missing surface fractions that don’t sum to 1.0

• Missing vegetation parameters when vegetation surfaces are present

8.3.8. FcPhoto (Photosynthesis Flux) Near Zero in Summer

Problem: FcPhoto values become close to 0 during the growing season (summer months) when they should be at their highest.

Cause: This typically occurs when using SMD (Soil Moisture Deficit) method 0 with improper soil moisture initialization or parameters, leading to severe water stress that shuts down photosynthesis.

Background: The photosynthesis flux (FcPhoto) is regulated by several environmental stress factors:

• g_dq: Vapour pressure deficit stress

• g_ta: Temperature stress

• g_smd: Soil moisture stress

• g_kdown: Light stress

These are combined into a total stress factor: gfunc = g_dq × g_ta × g_smd × g_kdown

When using SMD method 0 (modelled soil moisture), the soil water balance is calculated internally. If the soil moisture becomes too low, g_smd approaches 0, causing FcPhoto to approach 0.

Solutions:

1. Switch to SMD method 1 or 2 (recommended if you have observed soil moisture data):

   In your YAML configuration:

   smd_method: {value: 1}  # Use observed volumetric soil moisture
   # or
   smd_method: {value: 2}  # Use observed gravimetric soil moisture
   

   This requires providing soil moisture data in your forcing file.

2. If using SMD method 0, check and adjust:

   1. Initial soil moisture states - ensure reasonable starting values:

      initial_conditions:
        soilstore_bldgs: {value: 50.0}  # Not too low
        soilstore_paved: {value: 50.0}
        soilstore_evetr: {value: 100.0}
        soilstore_dectr: {value: 100.0}
        soilstore_grass: {value: 80.0}
        soilstore_bsoil: {value: 60.0}
      

   2. Soil capacity parameters - verify they match your site:

      soil:
        bldgs:
          soilstorecap: {value: 150.0}  # mm
        paved:
          soilstorecap: {value: 150.0}
        # ... similar for other surfaces
      

   3. Soil moisture stress parameters:

      vegetation:
        s1: {value: 5.56}   # Wilting point threshold (mm)
        s2: {value: 100.0}  # Capacity threshold (mm)
        g_sm: {value: 3.5}  # Soil moisture sensitivity
      

   4. Enable irrigation if appropriate for your site:

      water_use:
        method: {value: 1}  # Enable irrigation
        # Configure irrigation parameters
      

Diagnostic Steps:

1. Check the daily state output for soil moisture values

2. Plot SMD alongside precipitation and FcPhoto

3. Look for correlation between rain events and FcPhoto spikes

4. Verify that LAI values are reasonable for the vegetation present

Example: If FcPhoto only appears briefly after rain events, this confirms severe water stress is limiting photosynthesis between precipitation.

Prevention: When setting up a new simulation:

• Use realistic initial soil moisture (not 0 or very low values)

• Consider seasonal variation in soil parameters

• If modelling urban areas, account for irrigation

• Validate soil parameters against local measurements if available