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

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

Some weird bits:

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.