Incorporating a Module into the FRAMEwork System (FRAMES)


Title Page
Legal Notice
Table of Contents
Introduction
Example
STEP 1
STEP 2
STEP 3
STEP 4
STEP 5
APPENDIX A
APPENDIX B
APPENDIX C
APPENDIX D

One of the most powerful features about FRAMES is its ability to accomodate a wide range of models and databases. This document provides an example of model incorporation. For step-by-step instructions on utilizing the FRAMES Application Programming Interface (API) to incorporate a model, see the five steps in that process: 1) add units and measures, 2) define model inputs and boundary conditions, 3) develop an invocation for the model, 4) provide a description of the model, and 5) categorize the model. Additional documentation describes how a database owner can incorporate a database into FRAMES.

This example demonstrates the incorporation of a Constantly Stirred Tank Reactor (CSTR) model into FRAMES 2.0. This FORTRAN model was chosen to express the wide range of programming styles that FRAMES 2.0 can support. The CSTR model is essentially a simple exponential release of chemicals into the environment. The example does not focus on this environment other than to choose standard output datasets that this model will produce. For more details on this model, see Appendix A, CSTR Model Complete Source Code.

Note that FRAMES documentation distinguishes between a module and a model. A model is the actual code that performs computations by itself. A module consists of that model, its input and output dictionaries, associated measures, and any wrappers.

Step One: Add Units and Measures

The inputs to the CSTR are described in their entirety in the table below. The following discussion focuses on the Unit and Measure columns. These columns must be checked to see whether new units and measures are needed. Note, however, that new units and measures should only be used if necessary. Use the existing measure first if possible. That the units of a measure match is a fundamental test FRAMES 2.0 performs on all transactions with the API.

Inputs to the Constantly Stirred Tank Reactor Model

Name Description Unit Measure Type Range S D U K prep Indices
b Soil Type Exponent     FLOAT 0-1E+36 Y 1 Y N    
Bd Bulk density g/cm3 Mass/Solid Volume FLOAT 0-1E+36 Y 1 Y N    
CASID Constituent ID     STRING -2147483648-80 Y 1 N N    
CName Chemical Name     STRING -2147483648-20 N 0 N N for  
Ct Intial concentration on total volume g/cm3 Mass/Solid Volume FLOAT 0-1E+36 Y 1 Y N    
CtFlag Flag for entering Ct or Ctp     LOGICAL 0-1 Y 1 N N    
Ctp Initial Concentration on total weight mg/kg Mass/Mass FLOAT 0-1E+36 Y 1 N N    
i Infiltration rate cm/yr Distance/Time FLOAT 0-1E+36 Y 1 Y N    
kd Soil Partition Coefficient cm^3/g Solid Volume/Mass FLOAT 0-1.36 Y 1 Y N    
Ks Saturated K cm/s Distance/Time FLOAT 0-1E+36 Y 1 Y N    
l Length of the area where concentration is coming in cm Distance FLOAT 0-1E+36 Y 1 Y N    
lamdba Decay rate of the chemical 1/y 1/Time FLOAT 0-1E+36 Y 1 Y N    
NTimes Number of times to report     INTEGER 0-10000 Y 1 Y N    
Qco Mass flux into CSTR g/yr Mass/Time FLOAT 0-1E+36 Y 1 Y N    
RhoS Particle Density g/cm3 Mass/Solid Volume FLOAT 0-1E+36 Y 1 Y N    
S Solubility Limit mg/L Mass/Liquid Volume FLOAT 0-1E+36 Y 1 Y N    
TFinal Last year to report y Time FLOAT 0-1E+36 Y 1 N N    
Th Thick of layer cm Distance FLOAT 0-1E+36 Y 1 Y N    
ThetaFC Field Capacity     FLOAT 0-1E+36 Y 1 N N    
w Width of area where contaminant is coming in cm Distance FLOAT 0-1E+36 Y 1 Y N    
Legend
S Scalar
D Dimensional Size
U Uncertainty can apply (Stochastic)
K Is the variable a key to others

For this example, assume that the measure of "Mass/Solid Volume" and unit "g/cm3" for the parameter Bd are not currently part of FRAMES 2.0. In FRAMES Framework Development Environment (FDE), go to the Editors menu and select Conversion Editor. This will bring up a display similar to the one below.

As shown on this screen, all known measures are displayed under the Conversions list. This tree control is similar to a directory structure in Windows Explorer. Under each Measure is a list of units that belong to that measure. Under the "Area" measure, for example, there are three units "A^2", "m^2" and "m2" represented. The double entry of "m2" and "m^2" demonstrates the flexibility of the system to incorporate different unit notation standards. The system is still able to detect when units do not match if they are not in the same measure. "A^2" is for square Angstroms, demonstrating the range of values that can be represented under a single measure. The Edit, Add, and Del Measure buttons allow the user to maintain the list of measures. The Publish Conversion button allows the user to publish their collection of measures to the FRAMES website so that others can download and use the same set of measures.

To add "Mass/Solid Volume" as a measure, the user would press the Add Measure button. Three dialogs will appear. The first asks for the Measure Name; the user would type in Mass/Solid Volume. The next dialog prompts the user for the base units, a text description of the base measure. The user would enter something like "Grams per cubic centimeter of volume." The final dialog prompts the user for the units abbreviation. Because this is the string that is most frequently used in the later interfaces, select this with care. In this example, the user would enter g/cm3. An error stating the measure is already in the list will appear if the text duplicates something already in the list because the measure names are required to be unique.

To add a unit is slightly more complex. Let's assume that the user wants to support another notation for "g/cm3" where "^" is used to represent raising a number to a power. So "g/cm3" and "g/cm^3" are the same unit but with different notation standards. In the tree control, the user would find "Mass/Solid Volume" and click on that measure. The following screen will appear.

Notice that the unit of "g/cm^3" is missing from the list. To add it, the user would click the "Add Unit" button. The Conversion Editor will prompt the user for a new text description of the unit and for an abbreviation. As noted previously, the abbreviation is what is used most frequently later. When this information has been entered, the screen will refresh and "g/cm^3" should be on the list. The user would then need to add the base unit to "g/cm^3." To do this, the user would choose "g/cm^3" from the list on the left, and the screen would look like this:

Notice the "Slope" and "Y-Int" input fields at the lower right. This is where the user inputs conversion factors for the new measure. The base unit for this measure is "mg/m3," so the user would need to input the appropriate slope. The "Y-Int" of zero is correct because this is a simple multiplicative factor. The "Y-Int" field is used to resolve issues such as temperature scale differences. Note that when putting in the conversion factor, if the user chooses to use dimensional analysis (resolve units as an equation), the user should start with the units on the left side of the equation ("mg/m3" in this case). For simpler units, such as converting meters from feet, the equation would be 1 m = 3.2808ft+0. In this case 1"mg/m3" is 1e-9"g/cm^3," so a value of 1e-9 is put in for the slope.

All the measures and units needed for the model must be incorporated into FRAMES 2.0. Because units and measures are the foundation of the modeling system, care should be taken in entering this information. An incorrect conversion can change simulated results by orders of magnitude. From a conceptual stand point, measures and units define how model values produced or consumed are measured. Even different measurement techniques could be segregated by using the measure name to indicate the technique. So "Estimated Distance" could be a separate measure from "Measured Distance" if there is a significant difference in how those measures would be used.

Step 2: Define Model Inputs and Boundary Conditions

The previous table showed the module input dictionary for the CSTR model. The following table shows the output dictionary. These parameters represent all the information needed to run and all the outputs produced by the CSTR.

Outputs of the Constantly Stirred Tank Reactor Model
Name Description Unit Measure Type Range S D U K Prep Indices
CASID Constituent ID     STRING -2147483648-80 Y 1 N N    
CName Name of chemical     STRING -2147483648-80 N 0 N N for  
Conc Concentration mg/L Mass/Liquid Volume FLOAT 0-1E+36 Y 1 Y N  
CName
Time
Flux Flux of chemical g/yr Mass/Time FLOAT 0-1E+36 Y 1 Y N  
CName
Time
Time   yr Time FLOAT 0-1E+36 N 0 N N    
Legend
Column Name Meaning
S Scalar
D Dimensional Size
U Uncertainty can apply (Stochastic)
K Is the variable a key to others

The next step in the process of incorporating a model into FRAMES is to create these dictionary entries in the FRAMES 2.0 Dictionary Editor. Below is shown the Dictionary Editor dialog.

The Dictionary Editor allows the user to navigate the set of dictionaries by the tree control on the left. It also allows the user to export the entire set of dictionaries to a single html document. The dictionaries are tables similar to tables shown in this document. The "Goto Scope" allows the user to navigate to the FRAMES web site, which contains dictionaries that other users have created.

Dictionaries can be categorized in several ways. One way is between dictionaries used as model input (expected to be populated by the user) and those used as boundary conditions. Boundary condition dictionaries are used to define datasets produced or consumed by models as part of calculations. They are not designated as input or output because their function in that regard depends on the model's perspective: What one model produces, another consumes.

Another way to categorize dictionaries is between those needed by the system (System Developer) and those needed by a model (Model Developer). This categorization separates dictionaries that appear universal from dictionaries that are idiosyncratic to a model or a modeling system.

Each dictionary consumed or produced by the model must be added to FRAMES. In addition, variables and their attributes must also be added. The picture above shows that the CSTRInput Dictionary has already been defined. HOW DID THIS HAPPEN?

Parameters are added in the following manner, using Bd as an example. The user clicks the CSTRInput Dictionary in the left part of the window, then clicks the "Add Variable" button. In the dialog box, the user provided the variable's name as Bd. That added the variable to the dictionary, but the attributes still need to be defined. Clicking the "Edit Variable" button or clicking on the variable itself in the left tree control will cause a dialog box like the one shown below to appear.

Note that the user can manipulate all the attributes of the variable described earlier. The up and down arrows by the list of indices allow the user to edit the order the indices appear for the parameter. The Dimension field is shown but cannot be directly changed by the user. Instead the user is required to add/delete indices and change the status of the Scalar/Vector flag at the bottom right. The related variable field shows the user which variables in the set of variables have the same indices as the current variable.

The process of adding a "Boundary Condition" dictionary is identical to the one for adding a model dictionary.

Step 3: Develop an Invocation for the Model

After all the information in the two tables above is entered into FRAMES 2.0, it is time to make some design decisions about how a model is going to be incorporated. A model can be incorporated into FRAMES in two ways: by using the API and suite of editors provided with FRAMES, or by using a pre- and post-processor for the model. By far the easiest way is to use the API and FRAMES tools. If a model developer chooses instead to wrap the model in a pre- and post-processor, that developer will have to create new code and fire off the pieces of the module with a batch file. A simple batch file for the existing CSTR model and its pre- and post-processors might look like this:

CSTRPre.exe %1 %2 %3
CSTR.exe
CSTRPost.exe %1 %2 %3

where %1 %2 %3 are the path, simulation, and module name that all FRAMES 2.0 modules are given when they are invoked. Specific pre-processor codes can be found in Appendix B and post-processor codes can be found in Appendix C.

Most of the code for the CSTR model is concerned with defining the data elements that the model needs. So, in both the pre-processor and the model, the Bd variable is defined. This duplication is because the pre-processor is trying to prepare itself to populate the data structure the model itself uses to calculate the results. In this case, "read" statements could simply be replaced by API calls to get the values. There are two benefits to this replacement: 1) less code to keep synchronized and 2) speed. If the model was modified, it will read directly the data sets in the API and write its results directly to the API. So even if the API wrote the data to disk (which it does not do directly) the model that directly ties to the API would be roughly twice as fast.

Additional arguments can be passed before the path, simulation, and module name. So if an additional argument of "/fast" was needed by a module when it is invoked, the arguments would be something like the following:

yourModule.exe /fast "c:\program files\framesv2" mytestsim.sim mymod

The quotes around the path are a result of the space in "program files". This space sometimes causes problems between different versions of MS-Windows. There is no limit to the number of additional arguments passed to the module (other than a MS-Windows limit), but the module needs to find the path, simulation, and module name correctly.

Step 4: Provide a Description of the Model

Each module needs a description file. To enter information for this description, the user utilizes the Module Editor. Below is a picture that shows the executable information for the CSTR module.

Notice that the CSTRWrapped.bat is used in the executable location. This is the program that FRAMES will execute when the module is run. Also note that the DCE has been chosen for the user interface of the module. The two argument fields are where the user can put additional arguments.

The Connection Schemes screen allows user to edit the current list of schemes. In this case the CSTR only has one called "typical." This screen below also shows that CSTRInput is the dictionary for user input. The "Scheme Builder" button facilitates creating schemes for modules that have many combinations of inputs that are acceptable.

Clicking the "Edit Scheme" button will provide the user with a screen similar to the one below.

The user can choose which dictionaries are part of the "Consume" and "Produce" boundary conditions by simply using the up and down arrow buttons by the "Consume" and "Produce" lists. All these module data are stored in a module description file.

Step 5: Categorize the Model

The model should also be categorized so that others know how it can be used in FRAMES. The Domain Editor provides a mechanism to organize how models are shown. This editor behaves in a similar manner to the other editors except that it allows a user to state the categories of models available. This information controls the model tree that is shown in the Simulation Editor, where the models are connected and used. Below is a picture of the Domain Editor showing both the 3MRA domain (expanded) and the FRAMES domain.

The Domain Editor allows for two different systems to co-exist as different domains. Currently FRAMES and 3MRA are two different domains because not all the models use the same dictionaries for communicating information between components. Conceptually they would be in the same domain, but until they can be interconnected they are left as two domains.

The CSTR model could be added to either domain, depending on which class and subclass the user chose to categorize it. For more information on classes and subclasses, see the the instructions for Step 5.

Writing an Installation Script

Most models can be published online using tools provided by FRAMES 2.0. If this approach is not feasible, modelers can use the FRAMES 2.0 installation and scripting capability to write a short script that will incorporate their module into the system. Appendix D contains the complete list of the installation script for the CSTR module. It is still the modeler's responsibility that the user receives all the required executables, dictionaries, module files, and batch files to make the script work. This script only registers all these files with FRAMES 2.0.

The FRAMES 2.0 scripting mechanism uses BeanShell to allow for any API calls to be made from a text file that contains Java code. Modelers do not need the Java compiler (Java Software Development Kit) to use BeanShell, which was chosen because it is readily available, has active support, and is free. Note that, even though the rest of FRAMES 2.0 is language neutral, the scripting mechanism uses Java. However, all the functions are available to the other languages, so if, for example, a FORTRAN scripting mechanism was available, modelers could write an installation in that tool as well.

The Install subroutines have the following arguments and functions:


Start(String path)					
Function
Begins an installation
Arguments
Path	The path of where to install the FRAMES 2.0 files 

Domain(String name,String location_of_icon)
Function	
Add a domain
Arguments
Name	Name of the domain to add
Location_of_Icon	File location of the .ico file to show for this domain

ModelGroup(String domain,String name,location_of_icon)
DatabaseGroup(String domain,String name,location_of_icon)
SystemGroup(String domain,String name,location_of_icon)
ViewerGroup(String domain,String name,location_of_icon)
Function  
Add a Model, Database, System or Viewer group
Arguments
Domain	Name of the domain's new group
Name	The name of the new group
Location_of_Icon	File location of the .ico file to show for this domain group

Unit(String measure,String unit,String abbreviation,double slope,double intercept)
Function  
Add a Unit and Measure to FRAMES
Arguments
Measure	Measure name
Unit	Unit name
Abbreviation	Abbreviation for the unit (most frequently shown to the user)
Slope	Slope to convert between base unit and this new unit
Intercept	Intercept to convert between base unit and this new unit (probably 0 except for temperature)

Dic(String dictionary_path,String dictionary_file_name)
Function  
Register and entire dictionary with FRAMES
Arguments
Dictionary_path	Path to the dictionary file
Dictionary_file_name	Name of the dictionary including .dic extension

Mod(String module_path,String module_file_name,String New_ExePath)
Function  
Adds a module to FRAMES
Arguments
Module_path	Path to the .mod file to install
Module_file_name	Name of the .mod file to install including the .mod extension
New_ExePath	New path to use for the executable (in case model's is not the default of "c:\program files\FRAMESV2")
End()
Function  
Ends a installation process.

For specific information on formulations and coding used in this example, see



Battelle Logo
Home | Security and Privacy | Contact Us