i-Tree cool river: An open source, freeware tool to simulate river water temperature coupled with HEC-RAS

This method paper explains the i-Tree Cool River model algorithms for simulating the response of river water temperature to urban greening. The model captures the warming and cooling impacts of urban development and restoration through a water and energy budget. The water budget includes river inflows from urban storm sewers and reservoirs, and the associated water temperatures. The energy budget adjusts radiation fluxes due to riparian shading and evapotranspiration, and propagates temperature downstream. Restorative cooling of the river can be simulated through algorithms for cool groundwater, either as direct inflows or by river water replacement called hyporheic exchange. Novel features in the model include diurnal variation in riparian shading, use of the Army Corps of Engineers HEC-RAS model predicted river depths and velocities, and periodic boundary conditions to rapidly extend restoration scenarios.• Freely available code in C++ for Visual Studio, with a detailed manual and sample inputs and outputs at http://www.itreetools.org/research_suite/coolriver.• Useful for simulating river warming or cooling due to urban development or greening.• Well documented source code compatible with requirements of other modeling groups.


Specifications
where T w is the cross-sectional averaged river temperature ( °C), t is time in the simulation (s), U is the reach average flow velocity (m/s), ∂x is river cross-sectional intervals (m), D L is the dispersion coefficient (m 2 /s), R h is the heat flux reaction term, and R i is the reaction term of the external inflows. Combining the reaction term, R i , with the first (advection) and second (dispersion) terms in the righthand side in the Eq. (1) , altogether define the mass transfer [ 2 , 3 , 4] . The R h and R i are defined as: R i = Q W T W + Q GW T GW + Q Hyp T Hyp + Q SS T SS Q i + Q GW + Q Hyp + Q SS − T W,t−1 (3) where net is the net thermal energy (W/m 2 ), ρ is the water density as 10 0 0 (kg/m 3 ), C p is the specific heat capacity of water which is defined as 4182 (J/kg °C), y is the average water column depth (m), Q is the discharge (m 3 /s), T is water temperature ( °C), given that the subscripts W represents the river, GW represents the groundwater, Hyp represents the hyporheic exchange, and SS represents the stormwater inflow. In the Eq. (3) the t-1 refers to the prior time step. For surface inflows in Eq. (3) represented by the subscript SS , the users can include an unlimited number of surface inflows for each cross-section. The i-Tree Cool River Model uses inputs of river discharge to solve for the advection and dispersion terms in Eq. (1) as well as solve for the inflow reaction term, R i in Eqs. (1) and (3) . In unsteady conditions, such as during a storm event, the model determines river velocity and dispersion using the one-dimensional St. Venant equation, which is solved numerically using the finite difference method given in Eqs. (3 )-( 25 ) to ( 3 )-( 29 ) by Boyd and Kasper [2] . This St. Venant finite difference method uses the Manning equation to relate velocity with river water depth, wetted perimeter, and cross-sectional area. The Manning equation operates in trapezoidal, triangular, or square channels with prescribed width, roughness, and side slope. The i-Tree Cool River model uses a version of the Manning equation provided by Boyd and Kasper [2] in Eq. (3 )- ( 11 ) [3] . The Newton-Raphson rootfinding iterative method is used to solve the Manning equation and determine the adjusted wetted depth, hydraulic radius, wetted perimeter, cross-sectional area, and bottom width [2] . The i-Tree Cool River model uses the estimated velocity with the MacCormick method to determine the rate at which river water temperature travels between cross-sections, using Eqs. (2 -119) to ( 2 -122) from Boyd and Kasper [2] . The St. Venant finite difference method requires compliance with Courant and frictional stability conditions for each node every timestep, using Eqs. (3 -30 ) and ( 3 -31) of Boyd and Kasper [2] . In steady-state conditions, the model can determine velocity and dispersion using the St. Venant method, as done by Boyd and Kasper [2] , or the user can select the Crank-Nicolson numerical method [ 5 , 6] to solve a coupled set of velocity and temperature equations [3] .
Inflows are composed of surface and subsurface sources. The surface inflow terms, Q ss and T ss of Eq. (3) are input as a time series of flow rate (m 3 /s) and temperature ( °C), respectively, for any node receiving storm sewer, tributary, or other surface inflows. The flow and temperature values are either provided through measured observation or through estimation. The subsurface terms for groundwater inflow, Q GW and T GW of Eq. (3) are input as a time series of groundwater flow rate (m 3 /s) and temperature ( °C) for each node and can be based on observation or estimation. The groundwater temperature is set to a constant value based on a function of annual average air temperature warming slightly in the summertime and cooling slightly in the wintertime as suggested in the literature [6] . Groundwater inflow is determined from observation, or based on measuring baseflow at the upstream (station at the 0 m) and downstream (station at the end of the reach) sections during dry weather , and computing the inflow rate per unit length of the reach. The subsurface hyporheic flow rate (m 3 /s), Q Hyp, and hyporheic flow temperature ( °C), T Hyp terms of Eq. (3) for each node can be based on observation or estimation. Similar to groundwater flow, the hyporheic temperature is set to the constant value. The hyporheic inflow is calculated in the model based on the Darcy Law [7] as where A S is cross-sectional across seepage face (m 2 ), K S is dominant substrate hydraulic conductivity (m/s), h D is hydraulic head for Darcy calculation (m), and x is the model distance step (m). The net exchange of thermal energy in Eq. (2) is defined as a combination of energy fluxes as in Boyd and Kasper [2] as net = longwa v e + shortwa v e + latent + sensible + sediment (5) where the is the heat flux (W/m 2 ), and subscripts net is the net heat flux at the water surface, longwave is the longwave radiation flux at the water surface, shortwave is the shortwave radiation at the water surface, latent is the latent heat flux from evaporation, sensible is the sensible heat flux representing the convective thermal flux from the water surface, and sediment is the bed sediment heat flux representing conduction forcing at the water column interface [3] .

Longwave radiation flux
The longwave radiation flux in Eq. (5) includes three terms determining positive downward fluxes from the atmosphere and land cover over the water surface, and a negative upward flux from the waterbody to the air [ 2 , 3] longwa v e = atmospheric longwa v e + land cov er where atmospheric longwa v e is the atmospheric flux (W/m 2 ), land cov er longwa v e is the land cover flux (W/m 2 ), and back longwa v e is the back-to-air flux (W/m 2 ). Atmospheric longwave radiation is a function of air temperature and exposure from the river surface to the atmosphere, called the view-to-sky factor ( f ), calculated using Boyd et al. [27] atmospheric where T air is air temperature ( °C), the ɛ atm is the emissivity of the atmosphere (0 to 1), σ is the Stefan-Boltzmann constant (5.6696 × 10 −8 , W/m 2 K 4 ), and min( f 1 , f 2 , f 3 ) is the minimum of the three view-to-sky factors (0 to 1), including the f 1 as the building effects, the f 2 as the vegetation effects, Fig. 1. Schematic of a river cross-section where the BSA, TSA, and VSA terms are shading angles due to building, topography, and vegetation respectively. h building , h tree , and h bank are building, vegetation, and bank heights respectively and the D building , D canopy , and D bank terms are the distances of the building, canopy, and bank respectively to the edge of the water. and the f 3 as the topographic effects ( Fig. 1 ). The emissivity of the atmosphere ɛ atm is calculated using [8] ε atm = 1 . 72 0 . 1 e a T air + 273 . 2 1 7 ( where e a is the actual vapor pressure (mbar) and C L is the cloudiness factor, which ranges from 0 for a clear sky to 1 for full cloud cover and can be found from the weather station data or can be estimated from comparison between the solar radiation in the edge of the atmosphere and on the ground [9] . The view-to-sky factors with a value of 1 indicate a full unobstructed sky view and with 0 indicates a blocked condition for the solar radiation [2 , 10] . The general sky-view-factor formula for f i is computed for all the cross-sections with the determined interval [11] where i indicates the object at that cross-section (1 for the building, 2 for the vegetation, and 3 for the topography), and SA is the shade angle (radians), computed as and h c is the combined height of the objects above the water (e.g., if a tree is set on a hill, h c = h tree + h bank ), and max ( D i ) is the maximum distance from all objects at that cross-section to the edge of the water.
The landcover longwave radiation in Eq. (6) also uses the view-to-sky factor parameters as in Eq. (7) . The land cover radiation flux represents the land cover effect, e.g., vegetation cover's influence on water temperature in the form of longwave radiation. The model by default sets land cover temperature equal to atmospheric temperature, following the approach of Boyd and Kasper [2] land cov er The waterbody to air radiation term in Eq. (5) is a function of water temperature, representing heat flux emitted from the water surface, following the approach of Boyd and Kasper [2] back longwa v e = −0 . 96 σ ( T w + 273 . 2) 4 (12) where the T W is the river temperature ( °C).

Shortwave radiation (first method)
The model provides two methods for calculating shortwave radiation. The first method calculates the total shortwave radiation in Eq. (5) is a function of the incoming solar radiation [12] , based on the albedo and a shading factor, which is based on the riparian vegetation condition along the river corridor [ 6 , 11] shortwa v e = S in (1 − a )(1 − SF ) (13) where S in is incoming shortwave radiation, as the sum of direct and diffuse shortwave radiations, a is the albedo (ranging from 0 to 1), and SF is the estimated shading factor (0 to 1, with 1 for complete shade).

Shortwave radiation (second method)
The second method for evaluating the shortwave radiation combines the adjusted direct and diffuse shortwave radiation and uses sky view factors (discussed in section 1.1) and shading width in place of a shading factor [3 , 15] shortwa The view-to-sky factor is applied to compute the topographic shading effect on diffuse solar radiation ( S di f f use shortwa v e ) [ 11 , 15] di f f use Direct shortwave radiation is computed using a two-step adjustment process, accounting for the width of shade across the river surface, and the river slope and aspect, as well as the slope, aspect, solar azimuth, as well as solar altitude [13] direct where W' eff is the width of the effective shading and W river is the river section wetted width. The width of the effective shading and river section wetted width are explained in the next paragraph. The adjusted shortwave radiation ( direct shortwa v e ) is calculated as [13] direct where S direct shortwa v e is the incoming direct shortwave radiation can be imported to the model as an input file, α is the longitudinal water surface slope (radians), β is the aspect with considering the 0 as the true north (radians), θ sun is solar azimuth angle (radians), indicating the angle of the position of the sun relative to true north, and ϕ is solar altitude (radians). The second method for calculating shortwave radiation can reduce to the first method, in cases of full shade and full sun. For the case of full sun, the shade angle, SA = 0 and f i = 1, resulting in in Eq. (17) and W e f f = 0 in Eq. (16) . For the case of full shade, the corollary occurs, with SA = 1 and and W e f f = W river in Eq. (15) , resulting in no solar radiation on the river. The total width for the shading in the river cross-section, W shade , caused by near river objects, is calculated at each time step as a function of solar azimuth, altitude, and river azimuth ( θ river ), in addition to object height at each node [13] where the h i is the combined height of the topography and building or vegetation bordering the river ( i = 3) depending on the cross-sectional condition. When building and vegetation are present, the object is selected based on which has the largest shade angle SA from Eq. (10) . The river width and distance from river to the shading object are compared with W shade to determine the distances across the river cross-section surface covered in shade and to determine the width of river effectively shaded ( W eff ) and the width of the river directly under an overhanging object, W overhang such as tree canopy [11] . The model estimates the tree canopy width protruding from the tree trunk midpoint as 10% of the tree height base on the suggestion by Chen et al., [11] . The overhang is computed for either left or right banks as [11] W ov erhang = where ρ veg is the average density of the vegetation canopy, which ranges from 0 to 1 (unitless) and should be determined by the user. The effective shading width is computed using Beer's Law as [11] where λ, the radiation extinction coefficient, is calculated as a function of the leaf area index, LAI from the Eq. (2) of [14] and L avg is the average path length of direct solar radiation through the shaded zone around the river (m) [13] . When canopy overhangs the river surface, the model uses an adjusted effective width W e f f computed as Using the adjusted direct radiation affected by topographic shading ( direct shortwa v e ) and the calculated adjusted effective width, the net direct solar radiation affected by the topographic and shading barriers reaching to the surface, direct shortwa v e can be calculated as shown in Eq. (14) [13] .

Latent heat flux
The latent heat flux in Eq. (5) is a negative upward flux representing evaporative cooling [ 10 , 15] . The latent heat flux is computed as [2] latent = −ρL e E (22) where L e is the latent heat of vaporization (J/kg), and E is the evaporation rate (m/s). The i-Tree Cool River Model provides two methods for calculation of E from open water, the Penman-Monteith combination method using Eq. (30) of [10] , and a mass transfer method using Eq. (2 -96) of [2] .

Sensible heat flux
Sensible convection of heat in Eq. (5) represents the heat exchange between the surface of the water and the air [15] . The i-Tree Cool River Model provides three flexible methods to calculate the sensible heat flux, first and second methods ( Eqs. (23) and 24 ) based on the Bowen ratio of sensible to latent heat, and the third method ( Eq. (25) ) based on the sensible heat. The simpler of the two Bowen ratio methods is based on [2] where Br is the Bowen ratio. The more complex of the Bowen ratio methods is based on [16] where γ is the latent heat of vaporization (2.4995 × 10 6 J/kg), N is an empirical constant (1.59 × 10 −9 s/m.mb) and U wind is wind speed (m/s). The sensible-heat-based method considers wind speed as a driver of the convective flux, based on [9] , given by [2] as where K H is the heat exchange coefficient for sensible heat (J/ m 3 o C).

Bed sediment heat flux
The bed sediment heat flux in Eq. (5) represents the heat conduction between the bed sediment and the water column in the cross-section and is rate limited by the size and conductance properties of the substrate. The approach used in the i-Tree Cool River model modifies Eq. (2 -90) of [2] as where K CL is the volumetric weighted thermal conductivity (J/ms °C), T bed is the bed temperature ( °C), and d w is the average river depth in the cross-section (m). The sediment interface with the river water is the T bed in Eq. (26) ; some applications prescribe T bed to a depth below the interface. The mid-depth of the river, d W /2, is used in Eq. (26) to represent a mid-point of the river water temperature reservoir. By solving for the heat fluxes of Eq. (5) , the i-Tree Cool River model can solve Eq. (2) and provide the heat flux reaction term, R e , for the governing advection-dispersion-reaction Eq. (1) used to simulate river temperatures.

Coupling the i-Tree cool river model with the HEC-RAS
For coupling the i-Tree Cool River model [3] with the HEC-RAS [17] , Eq. (1) was updated to include HEC-RAS model river water surface materials as [19] where similar to Eq. (1) , T ( °C) is the temperature at a river cross-section, the superscript t-1 indicates the prior time, t (s) is the time step, the subscript up indicates the upstream cross-section, the subscript dn indicates the downstream cross-section, V (m/s) is the cross-section velocity, x (m) is the length of the reach segment bounded by the cross-section and upstream cross-section, D L (m 2 /s) is the reach longitudinal dispersion computed as a function of cross-section velocity and depth, R h ( °C) is the loss or gain (i.e., reaction term) of temperature due to heat flux, and R i ( °C) is the loss or gain of temperature due to lateral inflows [3 , 17] . The velocity is determined by a separate set of hydraulic equations, which in steady-state mode involves simultaneously estimating depth and velocity to satisfy the conservation of energy, mass, and momentum, i.e., the 5-step algorithm used in HEC-RAS [17] , which is an alternative to the Newton-Raphson algorithm used in i-Tree Cool River [18 , 19] .
To combine the i-Tree Cool River with the HEC-RAS model simulation of water surface profiles, Eq. (27) was modified to include the velocity and discharge data from the HEC-RAS model. To that end, the retention time was added to the equation in order to apply the HEC-RAS model calculated velocity data [18 , 19] .
is the temperature of the upstream cross-section at the prior time step, t r (s) is the retention time step defined as t r = x/V and V (m/s) is the HEC-RAS velocity at the cross-section, Q (m 3 /s) is the HEC-RAS discharge at the cross-section, and R h 2 is the heat flux reaction term, and R i2 is lateral inflows reaction term. An updated heat flux reaction term was considered for Eq. (28) [18 , 19] , where ϕ is defined to include the i-Tree Cool River model tree-based terms (e.g. Eq. (5) ). The lateral inflows reaction term equation also was updated as [18 , 19] , where subscripts a, b, and c are defined as the i-Tree Cool River form with Eq. (3) above. Considering this set of the formulation, we coupled the i-Tree Cool River model with the HEC-RAS model in order to utilize water surface profile data from the HEC-RAS model and thereby coordinate evaluations of thermal and flood management impacts. By coupling the hydraulic transport model of HEC-RAS with the temperature transport model of i-Tree Cool River, Eq. (28) can lead to differences in the volume of water predicted by the two transport models. This difference is due to the first right-hand side term in Eq. (28) representing temperature transport as plug flow, with upstream temperature from the prior time step replacing downstream temperature in the current time step, even when upstream and downstream volumes may not be equal for each reach segment. To avoid this continuity error, the i-Tree Cool River model maintains the HEC-RAS model volume for each reach segment and uses a cross-section spacing of 5 m or less to constrain the error in the temperature estimate [18 , 19] .

Model inputs
The i-Tree Cool River Model uses a set of input data including upstream boundary condition, steady or unsteady discharge hydrograph for the river and lateral storm sewer inflows, groundwater and hyporheic exchange data, streambed temperature, meteorological data, etc. for the simulation process, which can be imported to the model using the DAT files (the input data for temperature modeling in time and space) and the XML file (which includes the initial necessary data for the beginning of the simulation). The i-Tree Cool River model has a function to linearly interpolate the input data based on the defined x and t and the input files can be imported at different intervals. The name of the required input files and a brief description for each input file represented in Table 1 . Input files contain three TXT files including the impervious cover, land cover, and tree cover which are converted from raster to ASC Ⅱ and are not effective in the simulation process of the i-Tree Cool River model. Table 2 presents the alternative methods for obtaining the input data for the i-Tree Cool River model input data. Table 3 also represents the description of the initial parameters which are imported to the model in the XML file. More information such as sample inputs and outputs as well as a detailed manual can be downloaded at http://www.itreetools.org/research _ suite/coolriver/ .

Model outputs
After the simulation process, the i-Tree Cool River model generates four comma-separated-value (CSV) files for the predicted temperatures and the net value of the heat flux in minute and hour based intervals ( Table 4 ). The CSV files are two-dimensional vectors in which each row shows each meter of the river reach and each column represents each timestep of the running process. The user can add extra output files in the code as well.

Running the i-Tree cool river m
We provide an application file (iTreeCoolRiver.exe) in the iTreeCoolRiver_x64/86exe folder (can be downloaded at http://www.itreetools.org/research _ suite/coolriver/ ). The model executable is called at the command line along with an extensible markup language (XML) file, which includes the required initial information in the sample input files folder. The target platform for this application is Windows 10. In case of any trouble running this application for a different platform, the users should consider creating a build for their platform (see Compile and Build iTreeCoolRiver via Visual Studio 2017 section). The easiest way to get the application "up and running" is to download the compressed iTreeCoolRiver.exe file (the iTreeCoolRiver_x64/86exe folder) and extract all to the C: drive. (If the user chooses a different location, it will be necessary to edit the Inputs and Outputs tag of the iTreeCoolRiver.xml config file accordingly and specify the correct config location when running the application. See the Input Data section, Table 2 ). Discharge rates of the river in upstream at each timestep defining the hydrograph in steady or unsteady mode.

Inflow Temp Storm ( °C)
Observed stream temperatures corresponding to the river hydrograph timesteps in upstream. Inflow Rate 1 (cms) Discharge rates of the lateral storm sewer inflow at each timestep for the first location defining the hydrograph in steady or unsteady mode.

Inflow Temp 1 ( °C)
Observed stream temperatures corresponding to the first lateral storm sewer inflow hydrograph timesteps. Inflow Rate 2 (cms) Discharge rates of the lateral storm sewer inflow at each timestep for the second location defining the hydrograph in steady or unsteady mode. Inflow Temp 2 ( °C) * * Observed stream temperatures corresponding to the second lateral storm sewer inflow hydrograph timesteps. The row number in the DEM file where the cross-section is located. Column# * * The column number in the DEM file where the cross-section is located. Longitude (deg) * * Longitude of the cross-section in the geographic coordinate system. Latitude (deg) * * Latitude of the cross-section in the geographic coordinate system.

Z (H:V)
The side slope of the trapezoidal channel, equivalent to horizontal distance to vertical distance ratio. Same value for both channel sides. * * These input data are required for calculating the slope and aspect of each cell to apply the values on the hillslope effect and the shortwave radiation. In case of using fixed magnitudes for the shade factor and view-to-sky values, these values are not effective in the simulation process.
Shading.dat * Number The number of observations reflecting the locations of the measured shading information. Distance (m) Distances through the river reach corresponding with the cross-sections where the shading information is recorded.

EastBankH (m)
The height of the bankfull a at the measured cross-section on the Eastside. EastTreeH (m) The height of the canopy at the measured cross-section on the Eastside. EastBuildingH (m) The height of the building at the measured cross-section on the Eastside. EastBankDist (m) Distance from the bankfull to the edge of the water at the measured cross-section on the Eastside. EastCanDist (m) Distance from the canopy to the edge of the water at the measured cross-section on the Eastside. EastBuildingDist (m) Distance from the building to edge of the water at the measured cross-section on the Eastside. EastBufferW (m) The magnitude of the canopy buffer at the location of the measured cross-section on the Westside WestBankH (m) The height of the bankfull at the measured cross-section in the Westside. WestTreeH (m) The height of the canopy at the measured cross-section on the Westside. WestBuildingH (m) The height of the building at the measured cross-section on the Westside. WestBankDist (m) Distance from the bankfull to the edge of the water at the measured cross-section on the Westside. WestCanDist (m) Distance from the canopy to the edge of the water at the measured cross-section on the Westside. WestBuildingDist (m) Distance from the building to edge of the water at the measured cross-section on the Westside. WestBufferW (m) The magnitude of the canopy buffer at the location of the measured cross-section on the Westside Elevation (m) The elevation of the cross-section. StreamAzimuth (deg) The stream azimuth at the location of the measured cross-section. Distances through the river reach corresponding with the cross-sections where the shading factor and the view-to-sky values are calculated. ShadeFactor The value of cross-section shade factor for daily average, with 0 for no shading, and 1 for full shading. This is representative of the entire channel, and can be the average for right and left banks. It can be estimated using site visits, aerial photos, or best estimates. View-to-Sky The value of View-to-Sky in the desired cross-section which is 1-ShadeFactor * In case the topographic, canopy, and building heights and distances are considered for shading calculations, the magnitude of ShadeFactor and View-to-Sky are not effective in the simulation process.

SolarRadiation.dat *
The number of entries in this file should match the attribute value of totTime in the config file (see Table 2 ) The desired time step for the output intervals. Weather.dat * The number of entries in this file should match the attribute value of totTime in the config file (see Table 2  Observed river temperature in the upstream. sedT ( °C) Riverbed temperature. * National Center for Environmental Information a The water level, or stage, at which a stream, river or lake is at the top of its banks and any further rise would result in water moving into the flood plain.  Cross-sectional bottom width for trapezoidal channel (0 value for triangular). Could be estimated: a) using field surveys; or b) using a modification of hydraulic geometry relations to get channel geometry at bankfull based on the watershed area, which is provided by some USGS SteamStats sites and NHD -scale values for lower flow. Depth (m) Initial time step of water depth. Could be estimated: a) using field surveys; or b) using a modification of hydraulic geometry relations to get channel geometry at bankfull based on the watershed area, which is provided by some USGS SteamStats sites and NHD -scale values for lower flow. Discharge (cms) Upstream boundary flow from steady or unsteady state and is either estimated or observed. Estimates could come from i-Tree Hydro model simulation. Slope Longitudinal bed slope. Could be estimated: a) using field surveys; b) using DEM analysis, or c) USGS SteamStats sites and NHD.
USGS's Stream stats: https://streamstats.usgs.gov/ss/ Row# Associated with the DEM.txt input, and is input row number (0 is the first row) of each river cross-section. Used to compute slope and aspect for radiation estimates. Could estimate from observation or overlaying NHD image of the river on DEM in ArcGIS.  The date of the finishing of the simulation in the yyyymmdd format. Timeinterval (h) The intervals of the timesteps in the simulation process. startingHour The starting hour of the simulation process. SWMethod The code of the desired method for calculating the shortwave and longwave radiation energy fluxes: • Number 1 is for solving shortwave and longwave radiation fluxes based on the sky-to-view factor shading angles calculated from the provided heights and distances of the hillslope, vegetation, and building. • Number 2 is for solving shortwave and longwave radiation fluxes based on the fixed values for sky-to-view and shading factors. initialTemp The observed river temperature of the upstream cross-section at the first timestep. canDensity The density of the vegetation in the study area. roughness Manning's roughness coefficient (n). LAI The magnitude of the leaf area index in the study area. Shading_inputs tarLat Representative latitude of the study area. tarLong Representative longitude of the study area. tarRow The row number of the representative cell of the study area. tarCol The column number of the representative cell of the study area. standardMeridian The meridian ranking of the time zone in the study area. totDist The total distance of the river. calcMethod The desired method to calculate the river temperature 1: Solution Method = Crank-Nicolson 2: Solution Method = Explicit finite difference 3: Solution Method = HEC-RAS based method 4: Solution Method = Rung-Kutta depthOfBed The measured or assumed depth of the river bed totTime A total number of the simulation process in an hour. sensMethod The code of the desired method for calculating the sensible heat flux: The required steps for running the i-Tree Cool River model: • Uncompress the "iTreeCoolRiver_x64exe.zip" file to "c: \ iTreeCoolRiver ( Fig. 2 ) • Uncompress the "iTreeCoolRiver_SampleData.zip" file to "c: \ iTreeCoolRiver", creating "C: \ iTreeCoolRiver \ ExampleInputs" and C: \ iTreeCoolRiver \ ExampleOutputs ( Fig. 3 ) • To run the model, either Table 4 List of the default outputs created by simulating the i-Tree Cool River Model.
Output filename Description 2D_Hourly_Temperature.csv A two-dimensional (2D) matrix including the hourly simulated river temperature. The columns reflect the timestep ( T) and the rows show the intervals ( X). 2D_Hourly_TotalFlux A two-dimensional (2D) matrix including the hourly simulated total flux as a combination of the longwave, shortwave, latent, sensible, and sediment fluxes. The columns reflect the timestep ( T) and the rows show the intervals ( X). 2D_Minutely_Temperature A two-dimensional (2D) matrix including the simulated river temperature. The timestep in this output file is one minute and the spatial intervals are one meter. The columns reflect the timestep ( T) and the rows show the intervals ( X). 2D_Minutely_TotalFlux.csv A two-dimensional (2D) matrix including the simulated total flux as a combination of the longwave, shortwave, latent, sensible, and sediment fluxes. The timestep in this output file is one minute and the spatial intervals are one meter. The columns reflect the timestep ( T) and the rows show the intervals ( X).

Fig. 2.
Uncompressing the "iTreeCoolRiver_x64exe.zip" file to get access to the executable file.
• In a DOS Command Prompt navigate to "C: \ iTreeCoolRiver \ " and type the name of the executable and the config file and its path: "C: \ iTreeCoolRiver > iTreeCoolRiver.exe C: \ iTreeCoolRiver \ iTreeCoolRiver.xml" ( Fig. 4 ) • In a Windows Explorer double click on the iTreeCoolRiver.exe file and a DOS Command Prompt will open, type the config file and path: Fig. 3. Uncompressing the "iTreeCoolRiver_SampleData.zip" file to get the sample input and output folders.
The detailed steps for compiling the building the i-Tree Cool River model solution file in Visual Studio 2017 also are described in the model's manual which can be downloaded at http://www. itreetools.org/research _ suite/coolriver/ .

Method validation
Using the model described in the previous sections, we simulated river water temperature for several rivers in different climates for the steady and unsteady states. We used the i-Tree Cool River model in order to simulate the effects of the riparian vegetation and lateral inflows from different sources including urban storm sewers, hyporheic exchange inflows, and groundwater on river temperature in the unsteady state. The model was tested along 1500 m of a New York mountain river with riparian forest and urban areas during 30 h with two summer storm events in 2007 [3 , 20] . The model simulated hourly river temperature for 30 h simulation period with a 2-hour rain event in June 11 and 12, 2007 with an R 2 of 0.98. Our simulations showed that the river water temperatures are sensitive to the inflows of storm sewers, subsurface inflows, riparian shading, and upstream boundary condition temperatures for both steady and unsteady conditions. We removed the riparian shading from the simulation and the R 2 decreased 0.88, indicating the importance of riparian shading in river thermal modeling. We also removed the stormwater inflows from the simulation and observed that the R 2 decreased from 0.98 to 0.92, and by removing the subsurface inflows, we saw that the R 2 decreased to 0.94 [3 , 20] .   We updated our model to couple it with the HEC-RAS as described in section 2 and tested our updates study updates by simulating the impacts of warm surface runoff, lack of riparian forests, and impervious channels that transfer heat and block cool subsurface flows on river water temperature [18] to address the urban river syndrome [21] . We tested the updated i-Tree Cool River model on a 2 km mountain river within the New York City drinking water supply area (Sawmill, SM, Creek in Tannersville, NY), and used for base case and restoration scenarios on the 17.5 km reach of the Los Angeles (LA) River in a 48 h simulation period. The model simulated the LA River average temperature in the base case decreased from 29.5 °C by 0.3 °C when warm surface inflows were converted to cooler groundwater inflows by terrestrial green infrastructure; by 0.7 °C when subsurface hyporheic exchange was increased by removal of armoring and installation of riffle-pool bedforms; by 3.6 °C when riparian forests shaded the river; and by 6.4 °C when floodplain forests were added to riparian forests to cool surface reservoirs and local air temperatures [18 , 22] . We observed that by applying all four restoration treatments on the model, the average river temperature decreased by 7.2 °C [18 , 22] .

Declaration of Competing Interests
The authors declare that they have no known competing financial interests or personal relationships that could have appeared to influence the work reported in this paper.