PE Shell Version 4.01 - SUPERSEDED - Public Instructions

Documentation for PRZM/EXAMS Graphical Interface

On this Page

Introduction

The program pe4.pl is a graphical interface (shell) that facilitates putting chemical- and use-specific input values into the proper positions in the PRZM input (inp) and the EXAMS chemical files. In order to run the shell, you need to have the official versions of PRZM and EXAMS on your computer and you still need to follow the latest guidance for selecting input parameters for environmental fate and transport models. Once the inputs have been entered, the interface creates the necessary input and run files, calls up PRZM and EXAMS, runs the programs, and creates the output files, just as the DOS versions do.

The interface was created using Perl and Tk, publicly available programming, and requires Perl Tk to run. This guide provides instructions for setting up the shell and models on your computer, for running the shell, and for retrieving the outputs. The shell program code can be viewed in any text editor.

Top of Page

LIMITATIONS OF PE4.PL

In some more complex assessments, users will still need to operate PRZM and EXAMS through the DOS command line. EFED has identified the following known issues with the PE4.PL shell:

PE4.PL does not handle different application rates within the same scenario. For such cases, PE4.PL can still be used to generate a rough PRZM input file, and the user would be required to modify RECORD 16 manually and then run PRZM from a DOS command line.
PE4.PL does not have the capacity for modeling simultaneous formation and degradation kinetics of degradation products.
For modeling volatilization, PE4.PL requires an input value for ENPY even though the actual ENPY value is not used in simulation.
Output files should be given short names with less than 8 characters to allow consistent file management among different operating systems.

Top of Page

Installing and Setting Up pe4.pl

Install Perl and Tk
1. Perl for Windows is available from ActiveState, at Exit http://www.activestate.com.
2. Click on the link for Active Perl (as of this writing it's in the bottom left of the box labeled "solutions"). The following page lists requirements for different operating systems. Depending on the system installed on your computer, you may need to get the "windows installer 2+" (which is a link to Microsoft) before proceeding, via the "next" button and follow the instructions for downloading the PERL program appropriate for your operating system. You want to get the MSI file for Windows.
3. Once you have downloaded the files (you should have instmsi.exe and ActivePerl-5.6.1.631-MSWin32x86.msi) you can install them.
  1. If you need to, first double-click on instmsi.exe to update your Windows installer. After the install is done you will need to restart your computer before proceeding.
  2. Then, to install Perl, double-click on ActivePerl-5.6.1.631-MSWin32x86.msi and follow the instructions. If you skipped step (i) and get a message about needing to update your windows installer, return to step (i). On Windows95/98/ME you should install Perl in a C:\Perl directory; in Windows NT/2000/XP you can install in any directory. Finally, restart the computer once more to be sure the path to the Perl interpreter is set correctly.
4. Versions of Active Perl 5.6, build 631 and later contain Tk and this step is not required. For earlier versions, install Tk by opening a DOS prompt, typing PPM to launch the perl package manager, and then typing "install tk" at the ppm> prompt. You must be connected to the internet for this step.

Set up a C:\Models directory, install PRZM and EXAMS and copy input files.

The shell looks in set folders to call up the programs and supporting files (PRZM crop scenarios, meteorological files, and EXAMS environment files). The official program versions and previously mentioned files must be present in these folders. Links to official version of PRZM and EXAMS can be found on OPP's web page at the following location Water Models - Previous Versions.

The current official model versions are:

PRZM 3.12 (dated May 7, 1998), named PRZM3.12.EXE

EXAMS 2.98.04 (dated July 18, 2002), named EXAMS.EXE

Instructions for setting up your "Models" Folder:

Place the models in separate folders:

The PRZM executable (PRZM312.exe) must be in C:\Models\PRZM3\

The EXAMS executable (EXAMS.exe) must be C:\Models\EXAMS\
Create the folder C:\Models\Inputs with the following subfolders:

PRZMenv contains the PRZM crop scenarios

EXAMSenv contains the index reservoir and pond environment files (not included)

metfiles contains the weather (met) files (not included, but, available via OPP's web page at: Water Models - Previous Versions)
Although not necessary, you may want to create a "Results" or "Runs" folder as a way of collecting and organizing your model runs. This folder must contain a copy of the file exams.daf.
1. You can have as many folders for runs as you like, but each one must contain the exams.daf file, without which EXAMS will not run.
2. You must save your input (using File/Save on the interface's menu) before you do a run. This is how you tell the interface which directory to run PRZM and EXAMS from, and the directory in which to save your output files.

The folder set up is illustrated below:

Folder set up
Folder/subfolders				Required files
Master C:
	Models			pe4.pl
		PRZM3		PRZM312.EXE
		EXAMS
		Inputs	PRZMenv	PRZM Crop scenarios
			EXAMSenv	Index reservoir and pond environment (exv) files
			metfiles	Weather (met) files
		runs		exams.daf folder for the inputs and results of model runs

Use Windows Explorer to open the C:\Models folder and click on the pe4.pl icon. Alternately, you can create a link on your desktop or any other folder where it is convenient.
1. A DOS command box, labeled MSDOS PERL, will open and automatically minimize. You can restore this window to watch PRZM and EXAMS runs and see some other messages written by pe4.pl..
2. The shell, labeled Tk Pe4, will open. All inputs and commands are done through this interface.
Choose your PRZM crop scenario, metfile, and EXAMS environment from the drop down menus found on the upper left side of the screen.
1. Click on the PRZM crop scenario button for a list of scenarios. Move the cursor to highlight the desired scenario and click to select.
2. Click on the Metfile option menu for a list of available met files. Move the cursor to highlight the desired met file and click to select. Alternatively, you can click on the "...From scenario" button to the right of the metfile option menu (after you have selected a PRZM scenario and the program will scan the scenario input file for the documented metfile and, if found, you can click "OK" in the dialog box. NOTE: If the suggested metfile is not present in the metfile folder, the command box will return the message "Error: Couldn't open".
3. Click on the EXAMS environment button for a list of available EXAMS environment (exv) files. Select the appropriate file for the assessment (index reservoir for drinking water assessments; standard pond for ecological exposure assessments).
Enter the output filename and the chemical name in the appropriate boxes. Use the file-naming conventions that suit you best.
Input the chemical parameters in the appropriate boxes.
1. Use the latest approved version of Guidance for Selecting Input Parameters in Modeling the Environmental Fate and Transport of Pesticides to derive the inputs. The guidance can be found at Water Models - Previous Versions
2. PRZM will use the value entered for Kd.. If there is no entered value for Kd, then PRZM will be set to estimate a value for Kd based on the entered value of KOC.(And if there is no KOC value, PRZM will be told to make estimates based on solubility.) The interface will pass any values entered for both Kd and KOC to EXAMS.
3. Degradation rates are entered as half-lives, in days. The script converts half-lives to rates (rate = -ln(1/2)/t1/2), unless the entered value is zero, in which case the script sets the rate to zero.
4. Press the "Set Hydrolysis..." button or go to the "Edit" menu and choose "Hydrolysis..." to bring up a dialog box for hydrolysis values. The script requires either one value or three and uses them to calculate parameters for EXAMS. Because both the Eco Pond and the Index Reservoir are set to pH 7, any value entered at pH 7 will always be used. You can enter either one pH-hydrolysis half-life pair or three. If you enter one pair, EXAMS will assume hydrolysis rates do not change with pH. The values entered for hydrolysis are used to solve the equations in the EXAMS manual for the EXAMS parameters KNH, KAH and KBH. If only one value is entered, it is taken as the value for KNH.
The "More PRZM Parameters..." button is available for PRZM records 17, 18 and 26 (see chapters 4 and 5 of the PRZM manual if you don't know what these records do). If you don't have chemical-specific inputs for these records (and, in most cases, these data are not available), they will be appropriately left to default (or no input) values, as is currently done for PRZM/EXAMS.
Input the use-specific input parameters using the appropriate buttons and boxes in the upper right area of the shell.
1. The CAM button lists the crop application method options used in PRZM Record 16.
2. PRZM documentation is available on the OPP web at Water Models - Previous Versions
  
  Each chapter of the manual is in a separate file and chapter 4 describes the input variables. Because different application methods require different inputs (depth of incorporation, for example), the user should consult with the PRZM manual to ensure that the appropriate application method and associated inputs are used.
Select the field size appropriate to the assessment (Index Reservoir or Pond). If you are running the index reservoir for drinking water assessment, check the box "Use runoff for res. input". This calculates the 30-year average runoff for input into the reservoir, as per the Index Reservoir guidance. Since the pond used for ecological assessments is static, this box should be left unchecked for aquatic exposure estimates for ecological impacts.
You should save your inputs before running PRZM and EXAMS. Choose "Save" from the pull-down menu under "File". The dialog box will prompt you to select a name and a folder to save the file. Although not required, you may find it less cluttered if you create a separate folder under C:\Models to save the input files. The shell gives the saved file a ".pzr" extension, although it will open text files with any extension.
Select the field size appropriate to the assessment (Index Reservoir or Pond). If you are running the index reservoir for drinking water assessment, check the box "Use runoff for res. input". This calculates the 30-year average runoff for input into the reservoir, as per the Index Reservoir guidance. Since the pond used for ecological assessments is static, this box should be left unchecked for aquatic exposure estimates for ecological impacts.
You should save your inputs before running PRZM and EXAMS. Choose "Save" from the pull-down menu under "File". The dialog box will prompt you to select a name and a folder to save the file. Although not required, you may find it less cluttered if you create a separate folder under C:\Models to save the input files. The shell gives the saved file a ".pzr" extension, although it will open text files with any extension.
To pull up a saved file for further work, click on "Open" in the pull-down menu under "File". Navigate to the appropriate folder using the dialog box and click on the appropriate file to open.
The pull-down menu under "Edit" includes options to edit any of the specific PRZM parameters (PRZM env...) or to edit EXAMS command lines (EXAMS command). This option is not something that will be needed for most standard assessments, but is provided for those who may need to go beyond a routine assessment and know what they're doing.
If you created a new input and haven't saved it as a file yet, do so now. The shell runs PRZM and EXAMS from the directory you last saved or opened a file from, and if you do not use the open or save commands, it will use a default. The directory you run from must also contain the exams.daf file required by EXAMS.
Press the "Run PRZM/EXAMS" button. The progress of the run can be followed in the command prompt window launched when you started the script. The following files will be generated in the C:\Models\runs folder:
- przm3.inp, przm3.run - PRZM input and run files
- pz2ex.exa - EXAMS command file
- Kecho.prn - useful to review for any potential errors/bugs in the model run
- Filename.zpm - contains the values PRZM actually used for its simulation
- Filename.zts - PRZM time-series outputs
- Report.xms - standard EXAMS output
- Fgetsexp.xms - daily outputs from EXAMS that can be used to generate time series for daily distributions
- Fgetscmd.xms
- Filename.out - Standard Table 20 summary outputs
You may want to rename and save your przm3.inp and przm3.run files for later documentation. Because PRZM calls up these particular files, the shell will overwrite these files for the next run. As with any PRZM run, you should examine the input files closely to make sure the correct information was entered.

The filename.zpm (PRZM) and report.xms (EXAMS) files contains most of the parameters used by PRZM and EXAMS for their runs. You may want to save these files to verify your inputs.
Use your favorite spreadsheet to open your output file and examine the results. The output file is in tab-delimited format and will be easier to view in a spreadsheet than a text editor.
Use the Quit command under the file menu to quit. While you could also close the shell by clicking on the "X" button in the upper right corner, the Quit command shuts down both the shell and the command prompt that was opened at the beginning.

Questions concerning pe4.pl should be addressed to Dirk Young (young.dirk@epa.gov).

Top of Page