Tip

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

2. Please report issues with the manual on the GitHub Issues.

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

5. Troubleshooting

5.1. General

5.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.

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

Please join our email-list here.

5.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

5.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

5.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

5.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/

5.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.

5.2. SUEWS related

5.2.1. ESTM output

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

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

• Check the problems.txt file.

• 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`_

5.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.

5.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.

5.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.

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

Parameter(s) missing from input files. See also the error messages provided in problems.txt and warnings.txt

5.3. SuPy related

5.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.

5.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.

5.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!

5.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

5.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.