******************************* ** TEB simple driver version ** ******************************* METEO-FRANCE / CNRS Version October 2013 contact : Valéry Masson (valery.masson@meteo.fr) This simple driver for the TEB model (Building Energy Balance; Masson 2000 and subsequent papers), is intended to be used by scientists whishing to implement TEB in their own software. This simple driver provides all the source code of TEB alone, making it easier to analyse and to integrate in its own atmospheric model for example. If you wish to use TEB for physical simulations, wihtout intention to extract all the TEB routines into another software environment, you could use the SURFEX platform. It contains TEB and much more, especially the ISBA scheme for vegetation, or several I/O formats, including Netcdf. (http://www.cnrm.meteo.fr/surfex/) Please refer to this website for the complete documentation on TEB. -------------------------------------------------------------------------------- -------------------------------------------------------------------------------- Physical description of TEB -------------------------------------------------------------------------------- -------------------------------------------------------------------------------- The present simple "driver" version of TEB is based on : ------------------------------------------------------------ version7_3 of SURFEX code; branch TEB_DEV_1514, release 1550 ------------------------------------------------------------ The following physical features are included : 1) Historical version of TEB (Masson 2000) : - canyon shape geometry - isotropic direction of roads - 3 energy balances for roofs, roads and walls layers - simplified internal temperature evolution (force-restore) - water reservoirs on roofs and roads - snow mantel on roofs and roads 2) Building Energy Module (BEM) (Bueno et al 2012 doi:10.5194/gmd-5-433-2012) - adds Internal Building Energy Balance - adds floor and building mass energy balances - windows - Heat-Ventilation-air-Conditionning (HVAC) systems - inflitration / ventilation - solar protections - natural ventilation (opening of windows) 3) Roads orientation (Lemonsu et al 2012, DOI 10.1007/s10584-012-0521-6) - possibility to use a specified road orientation (instead of a genericisotropic roads) - possibility to separate the 2 facing walls energy balances (then one have energy balances for walls 'A' and 'wall 'B') 4) Garden (Lemonsu et al 2012, DOI 10.1007/s10584-012-0521-6) - possibility to add a fraction of gardens inside the canyon itself (modifies all energetic exchanges within the canyon) ==> The garden needs its own vegetation energy balance. In this driver version, a simple proxi is used (based on fixed albedo and Bowen ratio) 5) Greenroofs (De Munck et al 2013) - possibility to add greenroofs on the roofs ==> The greenroof needs its own vegetation energy balance. In this driver version, a simple proxi is used (based on fixed albedo and Bowen ratio) 6) Irrigation and solar panels (DeMunck 2013 and Masson 2013) - possibility to have irrigation of greenroofs, gardens and watering of roads - possibility to have solar panels (hot water and/or photovoltaic) -------------------------------------------------------------------------------- -------------------------------------------------------------------------------- Technical description of the driver structure -------------------------------------------------------------------------------- -------------------------------------------------------------------------------- 'src_teb' directory contains the physical sources of TEB ==> If you wish to implement TEB into your own software (e.g. atmospheric model) You only need to use these routines 'src_driver' directory contains the routines of the driver environment ==> Among these routines, you should only look at the driver.F90 program. This program is the main driver of this driver version of TEB. You can modify the values of the urban parameters (where indicated, from line 530 to line 865). 'src_solar' directory contains a simplified sky model, that is in SURFEX, to estimate the part of the diffuse solar radiation that is near solar direction. This code is here only in order to retrieve exactly the same forcings data for TEB that what is in SURFEX (to insure that we have the same results). 'src_proxi-SVAT' directory contains extremely simple vegetation models in case you use the 'garden' option or the 'greenroof' option. ==> These vegetation models are very crude, and you are invited to use your own vegetation models instead (or ISBA using SURFEX if you wish). Note that the physical varaibles that need to be exchanged between TEB and these vegetation model (either on roofs or gradens) are only those that are in arguments of the routines in 'src_proxi-SVAT'directory. 'input' directory contains data from the CAPITOUL experiment (Masson et al 2008), that is used as a test case. 'output' directory contains the results of your run once you have executed driver.exe 'output_ref' contains the results you should obtain, in order to check that everthing went well when you first ran driver.exe (do not change the urban parameters and options in driver.F90 if you want to do this). -------------------------------------------------------------------------------- -------------------------------------------------------------------------------- How to use the TEB driver program ? -------------------------------------------------------------------------------- -------------------------------------------------------------------------------- 1) You first need to create the makefile ------------------------------------- To do this, you have to: a) define your fortran compiler options in file gfortran_args b) run the script this way : mkmf.pl -t gfortran_args -p driver.exe src_driver src_proxi_SVAT src_solar src_teb c) You now should have a 'Makefile' file in your directory Documentation on this mkmf.pl makefile creation tool is provided in mkmf.html 2) Compiling of the code --------------------- Just use the command : make This will compile all the routines and create the executable file driver.exe 3) Running TEB ! ----------- Just use the command : driver.exe The driver program should be running and show prints on your window like this: 17994/17999 17995/17999 17996/17999 17997/17999 17998/17999 17999/17999 -------------------------- | DRIVER ENDS CORRECTLY | -------------------------- 4) Looking at the results ---------------------- Just go to the 'output' directory. It contains the temporal evolution of a few of TEB variables : RN_TOWN.txt : Net radiation (W/m²) H_TOWN.txt : sensible heat flux (W/m²) LE_TOWN.txt : latent heat flux (W/m²) P_CANYON.txt : pressure at road level (Pa) Q_CANYON.txt : specific humidity in canyon (kg/kg) T_CANYON.txt : air temperature in canyon (K) U_CANYON.txt : Wind strength in canyon (m/s) TI_BLD.txt : Internal building temperature (K) T_ROAD1.txt : road surface temperature (K) T_ROOF1.txt : roof surface temperature (K) T_WALLA1.txt : wall surface temperature (wall A) (K) T_WALLB1.txt : wall surface temperature (wall B) (K) If BEM option is activated, you also have these outputs: W / m² of buildings ground surface (not by m² of floor) HVAC_COOL.txt : Cooling Energy Demand HVAC_HEAT.txt : Heating Energy Demand 5) Enjoy ----- You can now modify the urban options and parameters in driver.F90 in order to see their impacts. 6) If you want to change the atmospheric forcing data -------------------------------------------------- a) change the characteristics of your forcing in driver.F90 (lines 97 to 107) b) change the forcing data in the 'input' directory, but you should use the same type of text files c) run driver.exe 7) If you want to implement TEB in your own software ------------------------------------------------- All the TEB sources you need are in the 'src_teb' directory. -------------------------------------------------------------------------------- -------------------------------------------------------------------------------- End. Have fun with TEB. -------------------------------------------------------------------------------- --------------------------------------------------------------------------------