RoadSurf-Python

Research version of RoadSurf (https://github.com/fmidev/RoadSurf/). RoadSurf is a Fortran library for predicting road conditions. The code has been converted to Python to make fast research runs easier. A LLM (large language model) has been used to help in the conversion. Authors of RoadSurf: Markku Kangas, Marjo Hippi, Johanna Ruotsalainen, Martti Heikinheimo, Virve Karsisto, Mika Heiskanen and Leif Backman. 1998-2026 Finnish Meteorological Institute

The code does not contain all of the features included in the original FMI road weather model. The included features are road surface temperature and storage term (water, ice, snow, deposit) calculation. Variables determined based on these values, such as friction and road condition, are excluded. The purpose of the python version is to allow quick experimenting with new features.

Licence

The code is published with MIT License

Requirements

Python 3 is required. The following packages should be installed:
*csv
*math
*matplotlib
*numpy
*pandas

Running instructions

The model can be run by with command
python main.py

main.py contains the input reading, simulation, output writing and plotting the output. The input can be replaced with the users own data. The input settings at the beginning should then be updated. The example divides the run to initializaton, where mainly observations are used as input, and forechast phase, where forecast data is used as input. The example uses coupling, which adjusts the radiation so that the modeled surface temperature fits to the observed road surface temperature at the end of the initialization phase. In the plot, the start of the forecast phase is plotted with a dashed line.

Example data

The repository contains an example data that can be used to run the model. The data is compiled as follows:

Start-end of initialization (4 May 2021 3 UTC): Air temperature, dew point temperature, wind speed, precipitation observations from a road weather station near Jyväskylä, Finland

Provider: Fintraffic (https://www.fintraffic.fi/en) with Creative Commons 4.0 Attribution licence (https://creativecommons.org/licenses/by/4.0/deed.en). Values closest to full hour (within 15 minutes) are selected from the original data

Rest of the values are from MEPS control member (MetCoOp ensemble prediction system)
Provider: MetCoOp (https://metcoop.smhi.se/)
Data has been interpolated to road weather station point from the original grid.

The short wave and long wave radiation values are from multiple MEPS forecasts until 4 May 2021 3 UTC. The data is picked so that three hours are taken from each file. The values after 4 May 2021 3 UTC are from a MEPS forecast with start time 4 May 2021 00 UTC.

How to contribute

Your contribution is very welcome, be it bug fixes or new features.

Small changes and bug fixes can be submitted via pull request. In larger contributions, premilinary plan is recommended (in GitHub wiki).

CLA is required in order to contribute. Please contact us for more information!

Communication and Resources

You may contact us from following channels:

Email: beta@fmi.fi
GitHub: issues

The physics of the model have been presented in the following publication:

Karsisto, V. E. 2024: RoadSurf 1.1: open-source road weather model library, Geosci. Model Dev., 17, 4837–4853, https://doi.org/10.5194/gmd-17-4837-2024