Current Version: heatsource 9.0.0b26 (beta 26)

Heat Source is a computer model used by the Oregon Department of Environmental Quality to simulate stream thermodynamics and hydraulic routing. It was originally developed by Matt Boyd in 1996 as a Masters Thesis at Oregon State University in the Departments of Bioresource Engineering and Civil Engineering. Since then, it has grown and changed significantly. Oregon DEQ currently maintains the Heat Source methodology and computer programming. Appropriate model use and application are the sole responsibility of the user.

Heat Source 7-8 and user manual: http://www.oregon.gov/deq/wq/tmdls/Pages/TMDLs-Tools.aspx

Authors: Matt Boyd, Brian Kasper, John Metta, Ryan Michie, Dan Turner

Contact: Ryan Michie, michie.ryan@deq.state.or.us

Download the heat source python wheel appropriate to your OS platform and python version. Requires install of Python 3.6, 3.7, or 3.8. It is recommended you use Python 3.8.

https://www.python.org/downloads/

Install the wheel from command line using pip:

cd path\to\directory_where_you_saved_the_heatsource9_wheel\
pip install <name of wheel file>

1. Place the control file (HeatSource_Control.csv) and the model run scripts in the same directory. You can generate a template control file by executing hs_setup_control_file.py or by using commend line.

   cd path\to\model_directory
   hs setup -cf

2. Open the control file and parameterize it with your model information. The control file must be named HeatSource_Control.csv

3. Use hs9_setup_model_inputs.py to build template input files or by using commend line. The input files will be saved to the input file directory that is specified in the control file).

   cd path\to\model_directory
   hs setup -mi

4. Edit the template csv files with your input data. You can use excel although make sure the datetimes are formatted correctly. Save the files as a csv.

5. Run the model by executing one of the following model python scripts/executables: hs9_run_hydraulics,
   hs9_run_solar,
   hs9_run_temperature,

   Or you can use command line to run the model:

   cd path\to\model_directory
   hs run -t

   A console should open and you should see the model running.

6. Outputs are saved in the output directory (specified in the control file).

1. Control and input files are ASCII comma delimited files.
2. The heat source control file must be named HeatSource_Control.csv.
3. The other input files can be named whatever you want (file names are specified in the control file).
4. Do not change the key names in the control file. Only change the VALUE column (column 4).
5. The column header names can be changed but the data needs to be in the correct column number (see below).
6. Use the specified unit and data format identified in the control file and input files. Example mm/dd/yyyy hh:mm is 07/01/2001 16:00
7. An input parameter value that is not applicable may be left blank although all values with float data type will be assigned as zero.

Key to model input information:
Required: Input value required
Required (Not Used): Input value required but not used other than for model setup (may be changed in future versions)
Optional 1: Input value optional (can be left blank).
Optional 2: Input value may be optional based on control file parameterization.

To write blank input files from a python script:

# requires a parameterized control file 
from heatsource9 import BigRedButton

control_file = 'HeatSource_Control.csv'
model_dir = r'C://path/to/model_directory/'

BigRedButton.setup_mi(model_dir, control_file,
                      use_timestamp=True, overwrite=False)

To write a blank inputs files from command line:

hs setup -mi

Heat Source can be setup and run directly from command line.

usage: hs [options]

commands:
run Command to run a model with arguments -t | -s | -hy
setup Command to setup a model with arguments -cf | -mi

run options:
-h, --help show this help message
-t, --temperature Runs a temperature model.
-s, --solar Runs solar routines only.
-hy, --hydraulics Runs hydraulics only.

setup options:
-h, --help show this help message
-cf, --control-file Writes a blank control file.
-mi, --model-inputs Write blank input files. Control file must already be parameterized.
-t, --timestamp Use -t to add a timestamp to the file name.
-o, --overwrite Use -o to overwrite any existing file.

other options
-h, --help show this help message
-v The heat source version and install directory.
-md [MODEL_DIR], --model-dir [MODEL_DIR]
Path to the model directory. If not used the default is current
working directory.

HeatSource_Control.csv

The control file is where most of the model operation and initial parameterization is set.

To write a blank template control file from a python script:

from heatsource9 import BigRedButton

control_file = 'HeatSource_Control.csv'
model_dir = r'C://path/to/model_directory/'

BigRedButton.setup_cf(model_dir, control_file,
                      use_timestamp=False, overwrite=False)

To write a blank template control file from command line:

cd path\to\model_directory
hs setup -cf

You can also parameterize the control file directly using **kwargs. Any control file key arguments passed will be parameterized into the control file.

from heatsource9 import BigRedButton
from os.path import join

control_file = 'HeatSource_Control.csv'
model_dir = r'C://path/to/model_directory/'

# Parameterize the control file and write to csv
BigRedButton.setup_cf(model_dir, control_file, use_timestamp=True, overwrite=False,
                      usertxt="This model is an example model",
                      name="example model",
                      inputdir=join(model_dir, "inputs", ""),
                      outputdir=join(model_dir, "outputs", ""),
                      length=1.8,
                      outputkm="all",
                      datastart="05/06/2003",
                      modelstart="07/01/2003",
                      modelend="07/14/2003",
                      dataend="09/21/2003",
                      flushdays=1,
                      offset=-7,
                      dt=1,
                      dx=30,
                      longsample=50,
                      bcfile="bc.csv",
                      inflowsites=4,
                      inflowinfiles="inflow1.csv, inflow2.csv, inflow3.csv, inflow4.csv",
                      inflowkm="1.65, 1.5, 1.3, 0.85",
                      accretionfile="accretion.csv",
                      metsites=4,
                      metfiles="met1.csv, met2.csv, met3.csv, met4.csv",
                      metkm="1.75, 1.45, 1.10, 0.9",
                      calcevap="False",
                      evapmethod="Mass Transfer",
                      wind_a=1.51E-09,
                      wind_b=1.6E-09,
                      calcalluvium="True",
                      alluviumtemp=12.0,
                      morphfile="morphology.csv",
                      lcdatafile="lcdata.csv",
                      lccodefile="lccodes.csv",
                      trans_count=8,
                      transsample_count=4,
                      transsample_distance=8,
                      emergent="True",
                      lcdatainput="Codes",
                      canopy_data="CanopyCover",
                      lcsampmethod="point",
                      heatsource8="False")

Below are all the input parameters that must be included in the control file.

UserDefinedFileName.csv

The temperature and flow rates of accretion are defined in this file.

Accretion flows are inflows that enter the stream over more than one stream data node, and typically are subsurface seeps that occur over longer distances than discrete subsurface inflows (i.e. a spring).

When accretion flows are close enough so that more than one occurs in a model distance step, the accretion flow rates will be summed and a flow based average accretion temperature will be derived and used in the mixing calculations

UserDefinedFileName.csv

The stream flow and temperature conditions at the upstream model boundary are defined in this file. The boundary conditions are defined at an hourly timestep.

(formally called Continuous data in heat source 8) UserDefinedFileName.csv

Note - multiple csv files may be used for each set of meteorological inputs with the format above or all data can be saved in the same file like the example below. This is controlled in the control file by designating the number of inputs and the input stream km.

Can also be outflows. Use negative flows.
UserDefinedFileName.csv

The tributary input files define the inflow/outflow rates and temperatures at different points along the model stream. Inflows refers to localized (non-accretion) type flows such as tributaries, springs, returns, point sources, etc. Outflows can be various types of water withdrawals. They are input with a negative flow rate. Temperatures for outflows are not used by the model.

The number and stream km of the inflow/outflows is defined in the control file. The flow and temperature are defined at an hourly timestep.

Note - multiple csv files may be created for each tributary input with the format above or all data can be saved in the same file like in the example below. This is controlled in the control file by designating the number of inputs and the input stream km.

UserDefinedFileName.csv

The landcover codes file contains the physical attribute information associated with each land cover code. Land cover codes can be alphanumeric values. Zero should be avoided as a land cover code. The physical attribute such as height, canopy closure, LAI, or overhang must be numeric. There cannot be skipped rows (i.e. rows without information in between rows with information) because the model routines see a blank row as the end of the data sequence.

land cover canopy information can be input as either canopy closure or effective leaf area index. This option is specified in the control file using the key canopy_data.

Input file formatting when canopy_data = "CanopyCover" in the control file.

Input file formatting when canopy_data = "LAI" in the control file.

The landcover codes file can be paramaterized from script.

from heatsource9.ModelSetup.Inputs import Inputs
from heatsource9.Dieties.IniParamsDiety import IniParams
from heatsource9.Dieties.IniParamsDiety import dtype

control_file = 'HeatSource_Control.csv'
model_dir = r'C://path/to/model_directory/'

# create an input object
inputs = Inputs(model_dir, control_file)

# imports the control file into input object
inputs.import_control_file()

# Parameterize the lccodes input. Uses canopy closure data.
lccodes = [('Active River Channel',100,0,0,0), 
           ('Barren - Clearcut',127,0,0,0), 
           ('Brush',128,1,0.4,0), 
           ('Dominate Coniferous',133,32,0.7,1.5), 
           ('Dominate Broadleaf (Riparian)',149,32,0.5,2), 
           ('Dominate Broadleaf (Upland)',150,32,0.5,2), 
           ('Road Unpaved',255,0,0,0)]

inputs.parameterize_lccodes(lccodes, overwrite=True)

(formally called TTools in heatsource 8)
UserDefinedFileName.csv

This file defines land cover information. This data can be derived from geospatial data using TTools.

Land cover information can be input into the model in two different ways: Using codes or values. If using codes unique land cover attribute information is represented as a unique code. The land cover attribute associated to each code is parameterized in the Land Cover Codes file in long format. If using values, the land cover attribute information for each transect sample is explicitly in the land cover data file.

The land cover data input type is identified in the control file.

When lcdatainput = "Codes", the following columns will be used after column 8:

When lcdatainput = "Values", and canopy_data = "CanopyClosure" the following columns will be used after column 8:

When lcdatainput = "Values", and canopy_data = "LAI" the following columns will be used after column 8:

Note - the number of columns are dependent on the number of transects and samples specified in the control file.

UserDefinedFileName.csv

This file defines channel morphology and substrate information. Refer to the user manual for more information about each parameter.

GNU General Public License v3 (GPLv3)

Heat Source, Copyright (C) 2000-2021, Oregon Department of Environmental Quality

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see http://www.gnu.org/licenses/.