Create a Fortran Component

An OMS component can be written in the Java Programming Language or in the FORTRAN programming language. Java is the preferred implementation language for components since you will experience all the benefits and advantages of this platform. However, the use of FORTRAN components enables the integration of legacy FORTRAN code as components into the system. In this coding example we will use the FORTRAN version of the Hamon potential evapotranspiration (PET) computation to demonstrate how to implement a FORTRAN component.

Hamon PET is computed as a function of daily mean air temperature and possible hours of sunshine (Hamon, 1961) using the equation:

potet_hamon = hamon_coef * radpl_sunhrs2 * vdsat 

where

• hamon_coef is the monthly air temperature coefficient used in Hamon PET computations,
• radpl_sunhrs is the hours of daylight for each day, in units of 12 hours, and
• vdsat is the saturated water-vapor density (absolute humidity) at the daily mean air temperature (deg C) in grams per cubic meter (g/m3).

The FORTRAN version of the Hamon PET method being used is from the distributed-parameter watershed model PRMS as implemented in the USGS Modular Modeling System (MMS). For watershed-scale applications of PRMS, a watershed is partitioned into spatial units, using characteristics such as slope, aspect, elevation,vegetation type, soil type, and precipitation distribution. Each unit is assumed to be homogeneous with respect to its hydrologic response and to the characteristics listed above; each unit is called a hydrologic response unit (HRU). A water balance and an energy balance are computed daily for each HRU. The sum of the responses of all HRUs, weighted on a unit area basis, produces the daily watershed response.

The basic Hamon PET FORTRAN code therefore has two computational elements. The first computes the daily PET (daily_potet) for each HRU. The second computes the basin average daily PET (basin_potet) as the area-weighted average of the daily HRU PET values. These two code elements are shown below.

C******Compute potential et for each hru using Hamon formulation

   do 20 i=1,nhru
          
   ir = hru_radpl(i)
          

   dyl = radpl_sunhrs(ir)
          

   vpsat = 6.108*EXP(17.26939*tavgc(i)/(tavgc(i)+237.3))
          

   vdsat = 216.7*vpsat/(tavgc(i)+273.3)
          

   daily_potet(i) = hamon_coef(mo)*dyl*dyl*vdsat
   

20   continue

C******Compute basin average daily potential et 

      do 30 i=1,nhru
         if(dt.lt.24.) then
            factor = dt/24.
      else
          

      factor = 1.
        

   end if
        

   potet(i) = factor * daily_potet(i)
        

   basin_potet = basin_potet + potet(i) * hru_area(i)
   

30 continue

      basin_potet = basin_potet / basin_area
      

basin_potet_hamon = basin_potet

To implement FORTRAN code as an OMS component, it must be wrapped with a Java code wrapper that will link the inputs and outputs of the FORTRAN code to the other components of the model being developed. An OMS Java component is written as a Java class that has two required methods and an optional method for component implementation. A method can be considered analogous to a subroutine in FORTRAN. The two required methods are named init and execute. The optional method is named cleanup. The init method is used to initialize variables and perform initial computations needed to run this component. The init method is executed the first time the component is called and is executed only once during a model run. The execute method contains all the component computations that are made each time step of the model execution. The cleanup method is used at the end of a model run to perform any tasks needed to terminate the model. Closing input or output files opened in the init or execute methods is an example of a cleanup task.

To prepare FORTRAN code to be implemented as an OMS component it must be organized into subroutines that represent the init, execute, and cleanup methods. The cleanup method is optional and, if not required, a cleanup subroutine does not need to be created. In this example we will create subroutines for the init, execute, and cleanup methods.

The Hamon PET FORTRAN code shown above contains the basic computational elements that make up the execute subroutine. However, your FORTRAN code may also contain other data management and execution logic. The PRMS model is a variable time-step model that can execute at a 24-hr time-step, switch to a storm time-step that can be from 1-60 minutes in duration, and then switch back to a 24-hr time-step, all in the same run. For PET computations, a check is made to identify whether the model is in a 24-hr or shorter time-step. This is done with a simple check to test if a variable named lday (the previous day) is equal to the current day. If lday equals the current day, then the model is in a storm time-step and does not need to recompute the PET for the day. Rather, the current day’s PET is apportioned equally among all the time-steps within the day. Use of the lday logic check will require that we initialize lday in the init method for use in the first time-step of the execute method.

OMS has a library of methods that can be used to provide information about time. The time variables that are available include the current date from which one can obtain the day, month, and year. Also one can obtain the julian date; the solar date, which is similar to the julian date but starts with December 22 equal to day 1; or the water year date which start with October 1 equal to day 1. However, these OMS methods cannot be called from the FORTRAN code. These date variables must be passed to the FORTRAN code though the Java wrapper. The procedure to do this is explained in more detail below.

The first step in preparing FORTRAN code for implantation as an OMS component is to create a file in which to construct the init, execute, and cleanup subroutines. You can begin with your initial FORTRAN model or subroutine code. The only requirement is that the file name ends in .for so that OMS will recognize it as native FORTRAN code. A modified version of the PRMS Hamon PET FORTRAN module, named potethamonf.for is available for download here. Download this file to your component source directory C:\omswork\OmsEtTutorial\src\gov\usgs\prms.

Open the Component Sources | gov.usgs.prms directory and you will see the potethamonf.for file in the component directory. Double click on potethamonf.for icon and the FORTRAN source code will be opened for viewing and editing. If this were the original version of the code, now is the time that you would edit it to be compatible with the requirements for an OMS FORTRAN component. The potethamonf.for file has been edited to meet these requirements. That editing process will now be described.

The first step is to create three subroutines in the file. The names of these subroutines are your choice. In the potethamonf.for file, subroutine potethamex is the execute method, subroutine potethaminit is the init method, and subroutine potethamcleanup is the cleanup method.

The next step is to identify the input and output variables and parameters associated with each subroutine. These variables and parameters are written to the argument list of each subroutine statement. For example, the argument list for subroutine potethamex is

       subroutine potethamex (hamon_coef, potet, nhru, hru_radpl, \\     +                       basin_potet, basin_area, hru_area, \\     +                       lday, daily_potet, radpl_sunhrs, \\     +                       tavgc, day, basin_potet_hamon)

Each item in the argument list will be declared as a component attribute in the Java wrapper code. Also any variable or parameter value that needs to be saved for use the next time the component is called must be included in the argument list. Otherwise the variable or parameter will be considered local and its value will be lost. In potethamex, the variable lday is a local variable whose value must be saved and so it is included in the argument list.

All variables and parameters also need to be explicitly declared as to their type and dimension. The variable and parameter arrays in this example have dimension names instead of numeric values. This convention comes from the original MMS module declaration rules. To accommodate this situation for this example, the dimensions have been declared as parameters in this subroutine prior to their use.

One other modification has been made to the execute method code. The variable dt is the current time-step in hours. As noted above, PRMS can have a variable time-step. However, for this example application, dt is fixed at 24 hours.

In the init method, subroutine potethaminit, the only computation needed is to initialize the variable lday to zero. The Hamon PET method does not need a cleanup method. However, for demonstration purposes, a cleanup method, subroutine potethamcleanup, has been included but contains no computation.

When all modifications have been completed to the FOTRAN file, you are now ready to use it to create an OMS component. Click on the file name potethamonf.for with the right mouse button and select Tools | Create Components with the left mouse button.

This will open the Create Components window. The Name field will contain the name Potethamonf which is the name of the FORTRAN file minus the .for. To be consistent with Java component naming conventions, the component name begins with the first letter capitalized. Care should also be taken in creating the FORTRAN file name so that it does not contain special characters like underscores or dashes.

Clicking on the selection arrow on the right side of the Initialize input field opens a selection box with the names of the subroutines that are defined in the file potethamonf.for. For the initialize method, select the name potethaminit and click on it with the left mouse button.

Do the same procedure for the Execute and Cleanup input fields. In the upper right corner of the window is the Recreate check box. Selecting this option will recreate the Java wrapper associated with this component when the OK button is clicked. If this is the first time the component is created, this option has no effect. However, if you are modifying the FORTRAN code after having previously created this component, selecting this option will remove the previous version of the wrapper and all attribute links. If you have not made any custom modifications to the Java wrapper, then selecting this option is suggested. If you have made custom modifications to the Java wrapper that you would like to retain, then you should not select this option. However, What are the things the coder is then responsible for ??????

Click the OK button with the left mouse button to complete the component creation process. If the process is successful, the component name with a .java appended to it will appear in the Component Sources directory.

After creating the new component, it needs to be added to the Component Library. Click on the Component Sources directory to highlight the jar icon in the OMS tool bar. Then click on the icon with the left mouse button. The Component Library gov-usgs-prms.jar will be update with the new component. Viewing the contents of gov-usgs-prms.jar in the Component Library window shows that Potethamonf has been added to the jar file.

In the Projects window, double click on the Potethamonf.java source file name to view and edit the source code. You can see that the new component is a Java class named Potethamonf . The list of component attributes following the class statement is the composite list of all the variables and parameters in the argument lists that were included in the three subroutines in your FORTRAN source code. The attribute list is followed by the three method statements to execute the init, execute, and cleanup subroutines in the FORTRAN code. The statement to be executed in each method is the name of the FORTRAN subroutine with the letters do included as a prefix.

In the FORTRAN execute subroutine, we need the value of the variable day, which is the current day of the month. As noted above, there are libraries of methods provided by OMS to compute a variety of date and time related variables. One of these OMS methods is currentTime.getDay(). To provide a value for day, we need to execute this method prior to calling the FORTRAN execute subroutine potethamex. This is accomplished by editing the Potethamonf.java component.

In the Potethamonf Java code, place your cursor between the left brace { and the letter d in dopotethamex on the line public void execute() { dopotethamex();}. Click Enter on the keyboard twice to move the dopotethamex statement down 2 lines.

Then move up one line and enter the code day.setValue(currentTime.getDay()); Note that when you enter this line, a red box with an x appears to the left of this line. This denotes an error with the code on that line.

Place your cursor over the red box and the error message will be displayed. In this case the error is that the Java component cannot find the varirable currentTime which we added in the new line of code. The variable currentTime needs to be added as an attribute to the component.

An easy way to add an attribute is to copy it from another component in the full model that uses it. In this case, the component. Expand the OmsEtTutorial project in the Projects window to show the directory structure of the project. Expand the Models directory to show the model OmsEtCompare.jma. Double click on OmsEtCompare.jma to open a view of the model.

In the model view, click on the model name OmsEtCompare with the left mouse button. This will open a new window to the right of the model displaying all the declared attributes in the model OmsEtCompare.

Locate the attribute currentTime. Click currentTime with the right mouse button and select Copy with the left mouse button.

Then move back to the view windows and click on the Potethamonf.java tab to