[Dragongfly] Boundary Layer parametrization


Dear Dragonfly developers,

First of all, thanks for having implemented this plugin, which seems very powerful for the UHI assessment… but in the same time potentially dangerous with many default data with high impact and far from easy to customize.

I’m trying to use and understand the Dragonfly_Boundary_Layer_Parameters block, whose parameter setting seems to have a huge impact on the UHI results. In particular the nightBndLayerHeight parameter. First of all, the default value in the doc (800m) does not correspond to the one in the code (80m). After having set it at 800m with a constant block, the RunUWG component doesn’t run until the end, giving the following error message : “Error in ReferenceSite/VerticalDifussionModel (line 141) / Error in xml_new (line 394)”. It seems that some combinaisons of nightBndLayerHeight / referenceHeight work (80 / 100 or 800 / 800) and others not (800 / 100).

Does that comes from the model preparation? Or the UWG algorithm itself?

I tried to find for some “tables” linking these weather layers to the different urban typologies… without success. Would have someone ref / paper recommandations?

Kind regards,



The night boundary layer height default of 80m in the code is the right one, not 800m. I’m not exactly sure why the reference height and boundary layer height are interacting that way to produce your error, but resetting the height to <100m should fix things.

The height of the night boundary reflects the diurnal pattern of the urban boundary layer (image below). During the day the solar shortwave radiation heats up the urban surface, mixes with the air above creating a tall boundary layer. During the night the surface cools down, the boundary layer becomes more stable, and it’s height is reduced. So typical heights for daytime is ~ 1000m, and for nightime ~ >100m.

So increasing it by a factor of 8 to 10 is likely what is causing issues with the UWG calculation for you. I started a github issue here: https://github.com/chriswmackey/Dragonfly/issues/11 so that we can fix this typo. Also we should figure out why exactly the calculation is failing so that can potentially put an upper bound to the inputs or a better error message. Thanks for catching it!

Finding some reference data linking weather layers to urban typologies is a good question, I’d like to find some too. Perhaps Chris/Mostapha might be able to provide some? You can check out the following thesis [1],[2] that the UWG algorithm is based on, which references three case studies for Singapore (Punggol), Capitoul and Bubble:

[1] https://dspace.mit.edu/handle/1721.1/107347

[2] https://dspace.mit.edu/handle/1721.1/59107


Thank you very much for the detailed answer Saeran! (which would deserve to be integrated in the Dragonfly documentation :-))
Last question concerning the Reference Height. I assume the “Temperature Reference Height” of this table does not correspond to the Reference height parameter of Dragonfly. Should the common sizing rule “twice the top building height” be considered here?




Yeah, the table Reference height refers to the referenceHeight input on the Boundary Layer Parameters component. The Temperature Reference Height refers to the height of the weather station where temperature is measured i.e tempMeasureHeight on Dragonfly_Reference EPW Parameters component.

As for calculating the Reference height, where are you getting the “common sizing rule of ‘twice the top building height’”? I can’t find that rule anywhere… I think keeping the default value of 150m as the component advises would be better.

Something that helped me a lot, and I think will be of interest to you is this thesis:https://dspace.mit.edu/handle/1721.1/99251?show=full. Specifically, chapter 4 has a set of sensitivity analysis for UWG input parameters, which shows you the % impact of varying the various parameters in terms of heating/cooling energy, and temperature change. In general, it found that varying the meteorological parameters (like the boundary layer inputs) deviated simulated temperature less then 0.5 K, for less then 43 hours of the year from the original empirical measurement. Which is why the study concludes its safe to keep the meterological inputs to default values.

An important caveat here is that the Reference height, is a slight exception to this as it had an effect on Boston temperatures beyond that limit (pg 43). That being said, I spent some time trying to figure out how the 150m value was calculated, and as far as I can tell, its based on an atmospheric simulation model, referenced in Bueno’s thesis. So unless you have access to your own vertical temperature dataset, I think keeping the meterological values as they are is a good rule of thumb.



Sorry for reviving this old topic but I found this paper by Martilli to be relevant: https://journals.ametsoc.org/doi/pdf/10.1175/1520-0450(2002)041<1247%3ANSOUIO>2.0.CO%3B2
Fig. 8 in particular shows the relation between urban and rural boundary layer heights in different wind regimes, which might help in some studies.

I did some searching but it seems that there is no practical rule for relating UBL height to other urban parameters, although UWG is highly sensitive to this parameter.


This is an old conversation but it’s still very relevant. Thanks for sharing that paper, @ArisVartholomaios .

I also wanted to add that any parameter that was found to greatly affect the sensitivity of the UWG results in the study done by Aiko Nanoko that @SaeranVasanthakumar linked to earlier in this thread is now a required input in the version of Dragonfly we released a few months ago. Boundary layer parameters are not required for the reasons @SaeranVasanthakumar listed. Still, any further info that can be provided on recommended boundary layer parameters is always helpful.