TopoFlow V3

This is the new (2009) verison of TopoFlow, still in active develop. Included here are some notes I'm working on (Bob Busey) as I get up to speed on the latest version of the model.

So, several configuration elements. The highlights is to start you need a python with these packages installed:
Numpy
MatPlotLib
SciPy
WxPython

Program Components

At present there is quite a collection of subroutines and such:

CSDMS_base.py			diversions_base.py		rtg_file.py
CSDMS_component.py		energy_balance.py		rti_file.py
ET_base.py			gc2d_funcs.py			rts_file.py
ET_energy_balance.py		get_values_BITS.py		save_load.py
ET_priestley_taylor.py		ice_base.py			snow_base.py
GW_base.py			idl_func.py			snow_degree_day.py
GW_darcy_layers.py		infil_base.py			snow_energy_balance.py
basins.py			infil_beven.py			soil_base.py
bob_start.py			infil_green_ampt.py		soil_funcs.py
channels_base.py		infil_richards_1D.py		tf_input.py
channels_diffusive_wave.py	infil_smith_parlange.py		tf_output.py
channels_dynamic_wave.py	met_base.py			tf_utils.py
channels_kinematic_wave.py	pixels2.py			topoflow.py
d8_base.py			precip_base.py			topoflow_Impl.py
d8_flow_funcs.py		radiation_funcs.py
diversions.py			rt3_file.py

I'll fill this in as I have time but breaking down that file list into a bit more categories:

• bob_start.py == Topoflow the package needs to be called from someplace else you can't just run it: python topoflow.py.

So, that's the purpose of bob_start.py.

• topoflow.py -- main engine, I think it is a child of the CSDMS_base.
• tf_utils.py -- more configuration things happen in here including hard coding of directories, case, and data prefixes
• ET_base.py -- main ET object
  • ET_energy_balance -- a child of ET_base, has it's own methods and properties (solving ET using EB method)
  • ET_priestley_taylor -- another child of ET_base, has its' own methods and properties (solving ET using PT method)
• GW_base.py
  • GW_darcy_layers.py
• channels_base.py
  • channels_diffusive_wave.py
  • channels_dynamic_wave.py
  • channels_kinematic_wave.py
• d8_base.py
  • d8_flow_funcs.py
• diversions_base.py
  • diversions.py

etc. etc. More surely to come as I get more deeply into the model.

Quick Start

To start, run bob_start.py

In those files you'll need to make a few edits. Specifically, tf_utils.py has a function TF_Test_Directory(). In that function you'll see the working directory returned. Change the line appropriate for your OS to where the input files are located and where the output files should go.

def TF_Test_Data_Prefix():
def TF_Test_Directory():
def TF_Test_Case_Prefix():

A bit about Config Files

So, that's it for functions in tf_utils.py. In the working directory there are a series of *.cfg files. Treat them as you would the old menu system from the previous version of TopoFlow. Up to and including the integer based options. So, when setting things up you may find it useful to run the old IDL based TopoFlow to see what method is first, second, third etc. Here is some example configuration, from *_met.cfg:

--------------------------------------------------
 Meteorological Variables
--------------------------------------------------
Method code:            1
Method name:            Mostly_Dingman
Time step:              Scalar         3600.00000000           [sec]
rho_H2O:                Scalar         1000.00000000           [kg/m^3]
Cp_air:                 Scalar         1005.70001221           [J/kg/K]
rho_air:                Scalar         1.26139998              [kg/m^3]
T_air:                  Scalar         20.00000000             [deg C]
T_surf:                 Scalar         -5.00000000             [deg C]
RH:                     Scalar         0.50000000              [none]
p0:                     Scalar         1000.00000000           [mbar]
uz:                     Scalar         3.00000000              [m/s]
z:                      Scalar         10.00000000             [m]
z0_air:                 Scalar         0.02000000              [m]
Qn_SW:                  Scalar         100.00000000            [W/m^2]
Qn_LW:                  Scalar         10.00000000             [W/m^2]
Save grid timestep:     Scalar         60.00000000             [sec]
Save ea grids:          0              Case5_2D-ea.rts         [mbar]
Save es grids:          0              Case5_2D-es.rts         [mbar]
Save pixels timestep:   Scalar         60.00000000             [sec]
Save ea pixels:         0              Case5_0D-ea.txt         [mbar]
Save es pixels:         0              Case5_0D-es.txt         [mbar]

Nomenclature for units, time series etc. is the same as with the old IDL. Oh, also, Method Name doesn't do anything at present. You should know that Method Code 1 is the Mostly Dingman method name but if you put in a 2 for method code but don't change the name the program will be running method 2 rather than Mostly Dingman which is method 1...

I also imagine the units are rigid but haven't investigated for certain.

Options (from TopoFlow 1.5): Precipitation

0 = none
1 = Uniform in space, given durations
2 = General data types

Snowmelt

0 = none
1 = Degree-Day
   Inputs: 
      c0
      T0
      T_air
      rho_snow
      h0_snow
      h0_swe
      timestep
2 = Energy Balance
   Inputs: 
      Qnet_SW 
      Qnet_LW
      T_air
      T_surf
      RH
      p0
      uz
      z
      z0_air
      h0_snow
      h0_swe
      rho_snow
      Cp_snow
      rho_air
      Cp_air
      Qcc_snow
      timestep

Evapotranspiration

0 = none
1 = Priestley-Taylor
   Inputs:   
      Qn_SW
      Qn_LW
      T_air
      T_surf
      T_soil_x
      x
      K_soil
      alpha
      timestep
2 = Energy Balance
   Inputs:
      Qn_SW
      Qn_LW
      T_air
      T_surf
      T_soil_x
      x
      K_soil
      uz
      z
      z0_air
      h0_snow
      rho_air
      Cp_air
      timestep

Infiltration

0 = none
1 = 100% infiltration until (h = z)
2 = Simple Green-Ampt, single event
3 = Smith-Parlange 3-param, single event
4 = Richards 1D equation, 3 soil layers

Subsurface Flow

0 = none
1 = Darcy's Law, Surface parallel layers
2 = Darcy's Law, 2D Freeze-Thaw

Channel Flow:

0 = none
1 = Kinematic Wave, Manning Friction
2 = Kinematic Wave, Law of Wall Friction
3 = Diffusive Wave, Manning Friction
4 = Diffusive Wave, Law of Wall Friction
5 = Dynamic Wave, Manning Friction
6 = Dynamic Wave, Law of Wall Friction

Diversions:

0 = none
1 = Sources, Sinks or Canals

Config Files Part 2

Modules & associated required input files

Python Module                  Input file
basins.py ==================== [prefix]_outlets.txt
          ==================== [prefix]_basin.rtm
CSDMS_base.py ================ [prefix].rti
CSDMS_component.py =========== [prefix].rti
                   =========== [prefix]_PROC.cfg
channels_base.py ============= [prefix]_channels_kinematic_wave.cfg
channels_diffusive_wave.py === [prefix]_channels_diffusive_wave.cfg
channels_dynamic_wave.py ===== [prefix]_channels_dynamic_wave.cfg
channels_kinematic_wave.py === [prefix]_channels_kinematic_wave.cfg
d8_base.py =================== [prefix]_flow.rtg
diversions_base.py =========== [prefix]_diversions.cfg
diversions.py ================ [prefix]_diversions.cfg
ET_base.py =================== [prefix]_ET.cfg
ET_energy_balance.py ========= [prefix]_evap_energy_balance.cfg
ET_priestley_taylor.py ======= [prefix]_evap_priestley_taylor.cfg
gc2d_funcs.py ================ Animas_200.mat
GW_base.py =================== [prefix]_GW.cfg
GW_darcy_layers.py =========== [prefix]_GW_darcy_layers.cfg
ice_base.py ================== Animas_200.mat
            ================== [prefix]_ice_valley_glacier.cfg
infil_base.py ================ [prefix]_infil_green_ampt.cfg
infil_richards_1D.py ========= [prefix]_infil_richards_1d.cfg
infil_green_ampt.py ========== [prefix]_infil_green_ampt.cfg
infil_smith_parlange.py ====== [prefix]_infil_smith_parlange.cfg
met_base.py ================== [prefix]_meteorology.cfg
precip_base.py =============== [prefix]_precip.cfg
snow_base.py ================= [prefix]_snow.cfg
snow_degree_day.py =========== [prefix]_snow_degree_day.cfg
snow_energy_balance.py ======= [prefix]_snow_energy_balance.cfg
tf_utils.py ================== [Specify Directory]
tf_utils.py ================== [Specify Prefix]
tf_utils.py ================== [Specify Case]
topoflow_Impl.py ============= [prefix]_topoflow.cfg
topoflow.py ================== [prefix]_topoflow.cfg

Modules & associated required output files

Python Module          Hardcoded output file
channels_base.py ===== [prefix]_0D-Q.txt
channels_base.py ===== [prefix]_2D-Q.rts
channels_base.py ===== [prefix]_2D-u.rts
channels_base.py ===== [prefix]_2D-d.rts
channels_base.py ===== [prefix]_2D-f.rts
channels_base.py ===== [prefix]_0D-Q.txt
channels_base.py ===== [prefix]_0D-u.txt
channels_base.py ===== [prefix]_0D-d.txt
channels_base.py ===== [prefix]_0D-f.txt
ET_base.py =========== [prefix]_2D-ETrate.rts
ET_base.py =========== [prefix]_0D-ETrate.txt
GW_base.py =========== [prefix]_2D-htable.rts
GW_base.py =========== [prefix]_2D-dfreeze.rts
GW_base.py =========== [prefix]_2D-dthaw.rts
GW_base.py =========== [prefix]_0D-htable.txt
GW_base.py =========== [prefix]_0D-dfreeze.txt
GW_base.py =========== [prefix]_0D-dthaw.txt 
ice_base.py ========== [prefix].mat
ice_base.py ========== [prefix]_DEM.rtg
ice_base.py ========== [prefix]_2D-iceH.rts
ice_base.py ========== [prefix]_2D-iceZ.rts
ice_base.py ========== [prefix]_2D-iceMR.rts
ice_base.py ========== [prefix]_0D-iceH.txt
ice_base.py ========== [prefix]_0D-iceZ.txt
ice_base.py ========== [prefix]_0D-iceMR.txt
infil_base.py ======== [prefix]_2D-v0.rts
infil_base.py ======== [prefix]_2D-q0.rts
infil_base.py ======== [prefix]_2D-I.rts
infil_base.py ======== [prefix]_2D-Zw.rts
infil_base.py ======== [prefix]_0D-v0.txt
infil_base.py ======== [prefix]_0D-q0.txt
infil_base.py ======== [prefix]_0D-I.txt
infil_base.py ======== [prefix]_0D-Zw.txt
infil_base.py ======== [prefix]_3D-q.rt3
infil_base.py ======== [prefix]_3D-p.rt3
infil_base.py ======== [prefix]_3D-K.rt3
infil_base.py ======== [prefix]_3D-v.rt3
infil_base.py ======== [prefix]_1D-q.txt
infil_base.py ======== [prefix]_1D_p.txt  <-- notice the switch from hyphen to underscore
infil_base.py ======== [prefix]_1D_K.txt  <-- notice the switch from hyphen to underscore
infil_base.py ======== [prefix]_1D_v.txt  <-- notice the switch from hyphen to underscore
snow_base.py ========= [prefix]_2D-SMrate.rts
snow_base.py ========= [prefix]_2D-hsnow.rts
snow_base.py ========= [prefix]_2D-hswe.rts
snow_base.py ========= [prefix]_2D-Ecc.rts
snow_base.py ========= [prefix]_0D-Smrate.txt
snow_base.py ========= [prefix]_0D-hsnow.txt
snow_base.py ========= [prefix]_0D-hswe.txt
snow_base.py ========= [prefix]_0D-Ecc.txt
topoflow_Impl.py ===== [prefix]_LOG.txt
topoflow.py ========== [prefix]_comments.txt
topoflow.py ========== [prefix].log 
topoflow.py ========== [prefix]_LOG.txt

Side note, see a def embed_child_components(self): in channels_base.py. Should check at some point to see if this is a second place where the

Note, for the radiation funcs the years they're valid for are 1992 - 2020. To go outside those years the table in there will need to be modified. See specifically def Equation_Of_Time()

More Start up Commentary

In summary, to run topoflow (9/30/2009 edition)

1. Edit tf_utils.py and specify: The working directory, the data prefix, and the case prefix
2. Make sure that your configuration files (*.cfg) are set correctly. Method 0 = don't use the module, Method = 1 to n = use a method corresponding to that integer value and then the required parameters are listed below in the rest of the .cfg file.
3. Once all the configuration stuff is good to go you can run the program from the command line:
   

   $python bob_start.py

4. The program will hopefully run to completion.
5. Required modules are:
   

basins 
met_base
channels_kinematic_wave
infil_green_ampt
GW_darcy_layers
diversions_base
ice_base

At least one of:

 snow_degree_day & snow_energy_balance
 ET_priestley_taylor & ET_energy_balance

• [prefix]_outlets.txt must contain at least two entries. The first to n-1 should be the grid cell(s) to be monitored. The last line should have an area and relief equal to 0.0 to avoid grumpiness from the model.

Some additional tips:

1. Be sure you don't have a mix of data prefix names in your configuration files
2. It's possible to specify directories in the configuration files such as
   

   T_air:                  Time_series    ./2007/AT.dat            [deg C]

3. more to come once I use my own data, I'm sure...

• Unit_Test1() -->
• In topoflow.py -->
• read in directory, data prefix, case prefix -->
• create a topoflow instance -->
• set the 'CCA' state -->
• run the model and pass the directory, data prefix, and case prefix information.
• The components to run are set in topoflow.py in this bit of code:
  

   def embed_child_components(self):
       #------------------------------------------------
       # Note: Don't call this if (self.CCA == True).
       #------------------------------------------------
       # Instantiate and embed "process components"
       # in the place of the CCA ports.
       #------------------------------------------------
       # But how do we choose a given process method
       # such as "kinematic wave" ??
       #------------------------------------------------
       import basins
       import met_base
       import channels_kinematic_wave
       import snow_degree_day
       import snow_energy_balance    
       import ET_priestley_taylor
       import ET_energy_balance      
       import infil_green_ampt
       import GW_darcy_layers
       import diversions_base
       import ice_base
       self.bp  = basins.basins_component()
       self.mp  = met_base.met_component()
       self.cp  = channels_kinematic_wave.channels_component()
       self.sp  = snow_degree_day.snow_component()
       self.sp  = snow_energy_balance.snow_component() 
       self.ep  = ET_priestley_taylor.ET_component()
       self.ep  = ET_energy_balance.ET_component()     
       self.ip  = infil_green_ampt.infil_component()
       self.gp  = GW_darcy_layers.GW_component()
       self.dp  = diversions_base.diversions_component()
       self.iip = ice_base.ice_component()   #########        
   #   embed_child_components()    
   #-------------------------------------------------------------------

So, turn routines off and on by commenting out both the import step and the self.xx line.

Soon (stuff bob busey will do as a side project):

1. pass an additional config file on the command line similiar to the .ini that I've been using for a while.
2. instead of bob_start.py make a bob_busey_start.py... pass the command line file here to Unit_Test(input_file as string) read it in and then pass this information to the a new sub in the topoflow.py file that is pretty darn similar to def Unit_Test1(): and start running the model from there... due to embedded directory checking this may be more difficult than it seems perhaps to the point of pointless-ness. It looks like the program has been designed to allow this at some point but it may be tricky.