PROGRAMMER S GUIDE TO TRNSED

Transcription

1 TRNSHELL APPENDIX I 33 APPENDIX I PROGRAMMER S GUIDE TO TRNSED TRNSED is the utility program that provides a user-friendly interface to the TRNSYS input file TRNSYS input files may be modified by the TRNSED programmer to display only selected information, hiding less important details from an end-user of the TRNSYS simulation TRNSED input files may also be configured to provide detailed help, unit conversions, and input range checking TRNSED relies on two basic features of the standard TRNSYS input file First, any line in a TRNSYS input file that begins with an asterisk (*) is interpreted by TRNSYS as a comment TRNSED statements placed within an input file are ignored by TRNSYS because they begin with an asterisk Second, any numerical value in a TRNSYS input file can be equated with an alpha-numeric name with the EQUATIONS or CONSTANTS statements as described in Chapter 2 of the main TRNSYS Reference Manual The TRNSED program changes the information on the EQUATIONS or CONSTANTS statements immediately preceding certain TRNSED command statements, thereby changing the numerical values that TRNSYS uses in the simulation TRNSED statements that might appear in an input file fall into three general categories: parameter statements, format statements, and file reference statements Each is described below TRNSYS input files that are to be read by the TRNSHELL or TRNSED programs as TRNSED input files must have a trd filename extension or have the following first line: *trnsed TRNSED Parameter Statements The most fundamental type of TRNSED statement is the parameter statement It is the parameter statement which makes it possible for certain CONSTANTS and EQUATIONS statements from the TRNSYS input file to be edited from the user-friendly TRNSED input window Consider as an example a simulation of a solar domestic hot water system Two key PARAMETERS which might be investigated with the simulation include F R (τα) and F R U L, which describe the collector performance The experienced TRNSYS programmer would ordinarily enter numerical values for these PARAMETERS directly in the input file As an alternative, these two PARAMETERS might be identified with variable names by placing the following EQUATIONS (or CONSTANTS) statement in the input file (see Chapter 2 of the main TRNSYS Reference Manual):

2 34 TRNSHELL APPENDIX I EQUATIONS 2 EFF = 07 FRUL = 143 The variable names defined in the CONSTANTS and EQUATIONS statements can be used anywhere in the TRNSYS input file in place of their corresponding numerical values The use of CONSTANTS or EQUATIONS statements simplifies the process of changing values which might appear multiple times in the simulation input file and also makes the file more readable TRNSED takes this process one step further by allowing the TRNSED programmer to display selected variables to the TRNSED end-user on a customized input screen The advantages of TRNSED are several: longer variable descriptions and context-sensitive help screens allow any user to understand the meaning of a given simulation variable unit information and optional unit conversions make specification of variable values more clear input range checking prohibits users from entering unreasonable variable values These capabilities are provided by supplying a TRNSED statement (TRNSYS comment) of the following form after a defined name in a CONSTANTS or EQUATIONS statement: * DescriptiveName PrimaryUnits SecondaryUnits Add Mult Min Max&Format HelpNo The first character is an asterisk so that TRNSYS interprets the statement as a comment The second character is a vertical bar that denotes the line as a TRNSED statement The remaining fields of the TRNSED statement are delimited by the vertical bar character and have the following interpretations: Descriptive Name - The text describing the meaning of the TRNSYS EQUATION or CONSTANT variable name This field can contain up to 70 characters, including spaces Primary Units - A text string indicating the units that the TRNSYS program expects for this EQUATION or CONSTANT variable The primary units are displayed when the File/Setup/TRNSED - Primary Units button is chosen The primary units should generally be the units required by the TRNSYS program Secondary Units - A text string indicating a secondary unit system for this EQUATION or CONSTANT The secondary unit system is displayed when the File/Setup/TRNSED - Secondary Units button is chosen The secondary unit system should be chosen with the end-user in mind

3 TRNSHELL APPENDIX I 35 Add and Mult - Together, these two fields allow unit conversion between the primary and secondary unit systems The formula for unit conversion is: Secondary Unit Value = (Primary Unit Value + Add) * Mult Min - The minimum value that can be entered in the input box for the EQUATION or CONSTANT (in the primary unit system) Max & Format - The maximum allowable value (in the primary unit system) which TRNSED will accept as input In addition, the format of this field controls the format of the display in the TRNSED window If, for example, an input has a maximum value of 100 and the programmer wishes to display one decimal point, this field should be written as 1000 Help No - A number ranging from 1 to 999 which refers to one or more paragraphs of text information to be displayed in a window when the user requests help on this particular input field Additional information on providing TRNSED help is presented later in this appendix To illustrate the use of TRNSED Parameter Statements, recall the solar domestic hot water system example introduced above To modify the TRNSYS input file so that the important collector PARAMETERS can be input in TRNSED format, a TRNSED Parameter Statement is supplied for each PARAMETER as shown below EQUATIONS 6 PANA= 65000E+0000 * Area of Single Panel m2 ft NPAR= 10000E+0000 * Number of Panels in Parallel EFF= 70000E-0001 * Intercept Efficiency (FrTauAlpha) FRUL= 14300E+0001 * Negative of 1st-Order Eff Coeff (FrUL) kj/hr-m2-c Btu/hr-ft2-F MPAN = 95500E+0001 * Mass Flow Rate per Panel in Parallel kg/hr lbm/hr PMAX = 90000E-0001 * Hydraulic Pumping Power for One Panel kj/hr Btu/hr This input file may now be viewed in two unique forms: as a TRNSYS input file (standard text-file) or as a TRNSED input file (customized, user-friendly display) The TRNSYS input file looks exactly like the input file just typed The TRNSED input file looks much different

4 36 TRNSHELL APPENDIX I (Figure 1) Since it is the same file, only displayed in a different format, changes made in either the TRNSYS or TRNSED input file will affect the other mode as well From the TRNSED window, values of the variables selected for inclusion can be modified within the specified range When the user places the cursor on one of the input fields and presses the F1 key, a help message related to this variable is displayed in a separate help window The text of this help message can be customized as described later When the TRNSED input file is saved, TRNSED converts the user's input values to the primary unit system, if necessary, and then rewrites the EQUATIONS and CONSTANTS statements in the TRNSYS input file with new values as required Figure 1: Sample TRNSED window display TRNSED File Reference Statements Occasionally, it is convenient to have a TRNSYS input selected from a list of alternatives which are stored in a file Consider, as an example, a TRNSYS simulation that uses the TYPE 54 Weather Generator The location for which weather data are to be generated is determined by specifying the city number (an integer between 1 and 329) as the fourth PARAMETER for TYPE 54 The Weather Generator uses the city number to access the appropriate monthlyaverage weather information from the wdatadat file supplied with TRNSYS If the TRNSED programmer wishes to allow users to change the city number, a TRNSED Parameter statement could be entered, following the procedures described above Setting the minimum and maximum values to 1 and 329, respectively, would ensure that the city number entered by the user is valid Problematic would be that the user would have to relate the city number to its corresponding location One solution would be for this information to be placed in the TRNSED help file (described below) A much better solution is to allow the user to select the city name directly The File Reference statement makes this list-selection process possible by creating a pull-down menu of

5 TRNSHELL APPENDIX I 37 options on the TRNSED input window When the user clicks the mouse or types a key within the editing field associated with a File Reference statement, a dialog box appears with a scrollable list of alternatives from which the user may select The choice that is left highlighted is set as the input TRNSED will then insert the city number corresponding to the selected city name in the TRNSYS input file Figure 2: Example Pull-Down Menu The File Reference statement has the following format: * < Name FileName Display Field Value Field HelpNo The fields of the File Reference statement are separated with the vertical bar ( ) character with the following interpretations: Name - text describing the TRNSYS input or PARAMETER This field is identical to that for the TRNSED Parameter statement File Name - a valid DOS file name (including path) that holds the information required by TRNSED to produce a list The first line in this text file is the number of items in the list Each following line contains two or more fields, separated by tabs or commas For example, the information used to produce the list of city names shown in Figure 2 is in a file called citiesdat having the following format 329 1,ABILENE 2,AKRON-CANTON 3,ALBANY 4,ALBUQUERQUE 5,ALLENTOWN TX OH NY NM PA

6 38 TRNSHELL APPENDIX I Display Field - the field number in which the text information that is to appear in the scrollable list is located Fields are separated by a comma or tab character and begin with field 1 The city names in the above example are found in field 2 in the citiesdat file Value Field - the field number in which the numerical value associated with a selected text option is located The city numbers are in field 1 for the above example The Value Field corresponding to a selected text item from the Display Field will be inserted into the appropriate EQUATIONS or CONSTANTS statement in the TRNSYS input file HelpNo - a number ranging from 1 to 999 which refers to one or more paragraphs of text information In some cases it is desirable to set multiple EQUATIONS or CONSTANTS values from one menu choice In the example discussed previously, it would be helpful to not only get the city number from the menu choice, but also the corresponding latitude for the TYPE 16 radiation processor The citiesdat file is modified to the following format: 329 1,ABILENE TX, ,AKRON-CANTON OH, ,ALBANY NY, ,ALBUQUERQUE NM, ,ALLENTOWN PA, 4065 The following TRNSED statements would allow for the choice of latitude and city from one menu selection: EQUATIONS 2 CITYNO = 1 * <City for Simulation LAT = 3243 * <City for Simulation CITIESDAT CITIESDAT The user would see just one menu, because the display field for the LAT equation is set to zero, while retrieving the city number (value field 1) and the latitude (value field 3) When

7 TRNSHELL APPENDIX I 39 more than one variable is set by a single menu selection, the second and subsequent variables are set based on TRNSED s assessment of which line in the data file was selected for the first variable In this case, LAT would be set from the first row with a 1 (the value of CITYNO) in the first column The programmer should avoid creating pull-down menu data files with multiple lines having the same value in this primary field For example, if there were more than one line with 1 in the first field, then incorrect values might be used for the subsequent TRNSED variables based on the first selection TRNSED ASSIGN Statements There are two methods by which a TRNSED user can assign a file to an ASSIGN statement in the TRNSED input file The two methods work in different situations Each is described below ASSIGN File Reference Statement The first method is really a special adaptation of the File Reference statement The user selects a filename (or description of a file) from a list (weatherdat in this example) and then this filename is placed into the ASSIGN statement The ASSIGN File Reference Statement has the following format: * < Name FileName Display Field Value Field HelpNo The fields in this File Reference statement have the same meaning as those for the general File Reference Statement described above ASSIGN\TRNWIN\WEATHER\MADISNWI 12 * <City for Simulation weatherdat The file weatherdat would have the following form: 329 1,ABILENE 2,AKRON-CANTON 3,ALBANY 4,ALBUQUERQUE 5,ALLENTOWN TX, \trnwin\weather\abilenetx OH, \trnwin\weather\akronoh NY, \trnwin\weather\albanyny NM, \trnwin\weather\albuquenm PA, \trnwin\weather\allentwnpa

8 40 TRNSHELL APPENDIX I Display Field - the field number in which the text information which is to appear in the scrollable list is located Fields are separated by a comma or tab character and begin with field 1 The city names in the above example are found in field 2 in the weatherdat file Value Field - the field number in which the value associated with a selected text option is located The weather file names are in field 3 for the above example The Value Field corresponding to a selected text item from the Display Field will be inserted into the appropriate ASSIGN statement in the TRNSYS input file HelpNo - a number ranging from 1 to 999 which refers to one or more paragraphs of text information See Creating TRNSED Help for more information In some cases it is desirable to choose several filenames from one menu choice This can be done with the ASSIGN File Reference Statement just as it can be done with the general File Reference Statement ASSIGN Open File Dialog Box Statement The second method for allowing TRNSED users to access an ASSIGN statement in the input file is to use the ASSIGN Open File Dialog Box statement When the user clicks on the TRNSED display box that contains the filename, the standard Windows Open File dialog box appears The user can then type in the desired filename or browse the computer file structure to select a filename The syntax of the ASSIGN Open File Dialog Box statement is: *? Name HelpNo The? character in column 3 identifies the ASSIGN Open File Dialog Box statement The meanings of the two fields in this statement are the same as those in the ASSIGN File Reference Statement As an example, an application of the ASSIGN Open File Dialog Box statement might look like this: ASSIGN \TRNWIN\WEATHER\MADISNWI 12 *?Weather File to Be Used 5 TRNSED Format Statements In the above example, the information for the various PARAMETERS was shown singlespaced starting at the top of the window Adding spaces to the text can control the horizontal placement of the descriptive text and the numerical value It is also possible to add blank lines and additional text with the general TRNSED format statement that has the following form * * Text Optional input

9 TRNSHELL APPENDIX I 41 The asterisk (column 3) indicates to TRNSED that this is a format statement which can have text and optional user input This statement may be placed anywhere within the TRNSYS input file The text field will be shown in the TRNSED window just as it is entered, including spaces To insert a blank line in the TRNSED display, just enter * * The optional input allows the end-user to enter text, such as a date, serial number, or other information The text entered in this input box is not used by TRNSYS in any way COLOR, FONT, SIZE, STYLE, ALIGN, and TAB The TRNSED programmer can customize the TRNSED window with much more than the basic spaces and blank lines The TRNSED statements COLOR, FONT, SIZE, STYLE, ALIGN, and TAB give the TRNSED programmer a great deal of control over the look and feel of the final TRNSED input window These statements control the appearance and position of the text in the TRNSED window For purposes of formatting, the text appearing in the TRNSED input window is placed in three categories: 1 Simple text This text is not descriptive text for a certain input field or pull-down menu in the TRNSED window but appears only to present information and organize the display of the window For example, simple text would be used to provide a title or other comments for the TRNSED display 2 Descriptive text This is text associated with the input fields and pull-down menus appearing in the window and describes the meaning of the particular inputs Descriptive text is that entered in the TRNSED Parameter and File Reference Statements to describe a particular input 3 Units This is the text inserted by TRNSED adjacent to the input fields for which units have been specified These TRNSED format statements affect all corresponding text positioned below them in the TRNSED input file until they are reset to new values or to their default values The COLOR statement is used to set the color of text of any of the three categories The statement has the form of one of the following depending on which category of text is being formatted: * <COLOR1> color * <COLOR2> color * <COLOR3> color The color can be specified as BLACK, RED, BLUE, GREEN, GRAY, PURPLE, AQUA, YELLOW, SILVER, NAVY, FUCHSIA, LIME, WHITE, or DEF (default)

10 42 TRNSHELL APPENDIX I The FONT statement is used to set the font (and, optionally, the size) of the text of any of the three categories The statement has the form of one of the following depending on which category of text is being formatted: * <FONT1> font size * <FONT2> font size * <FONT3> font size The font can be specified as any legal Windows font name (MS Sans Serif, Arial, etc) The specification of the size of the font in points using the FONT statement is optional (the same function can be executed with the SIZE statement) The SIZE statement changes the font size for the text in any of the three categories: * <SIZE1> size * <SIZE2> size * <SIZE3> size Here size is specified in points The STYLE statement determines the text style for the given category of text: * <STYLE1> style * <STYLE2> style * <STYLE3> style Here style can be one or more of the following: BOLD, ITALIC, UNDERLINE, NONE The ALIGN statement determines the horizontal alignment of simple text in the TRNSED window The following is the correct form of the ALIGN statement: * <ALIGN1> align Here align can be assigned one of the following values: LEFT, RIGHT, or CENTER LEFT will left-justify the text, RIGHT will right-justify the text, and CENTER will center the text in the TRNSED window The TAB statement determines the position of descriptive text relative to the left side of the TRNSED window The following is the correct form of the TAB statement: * <TAB2> tab

11 TRNSHELL APPENDIX I 43 Here tab can be specified in inches (in) or centimeters (cm) and is measured from the left side of the TRNSED window If not specified in inches or centimeters, tab is taken to be measured in pixels For example, the following statement would cause descriptive text to begin 3 inches from the left side of the TRNSED window: * <TAB2> 3 in The following statement will return to the default tab condition for descriptive text: * <TAB2> DEF BACKGROUND and PICTURE The TRNSED format statements BACKGROUND and PICTURE allow the programmer to customize the TRNSED window display as desired The BACKGROUND statement sets the color of the background of the TRNSED window: * <BACKGROUND> color Any of the colors used with the COLOR statement described above can be used with the BACKGROUND statement Only one BACKGROUND statement can be used in the TRNSED input file The PICTURE statement displays a picture file in the TRNSED window at the point where the PICTURE statement appears The PICTURE statement has the form: * <PICTURE> filename The complete path for the picture file should be provided with the PICTURE statement PICTURE files must be bitmap files (bmp) or Windows meta files (wmf) Multiple PICTURE statements can be used in a TRNSED input file BEFORE and AFTER The TRNSED statements BEFORE and AFTER allow the TRNSED programmer to specify command line (DOS) statements which should be executed before and after the TRNSED input file is run by TRNSYS, respectively The syntax for the statements is as follows: * <BEFORE> statement * <AFTER> statement Example: * <BEFORE> \trnwin\preprocexe simpledat -v In the example above, the BEFORE statement is used to execute a user-created preprocessing

12 44 TRNSHELL APPENDIX I program, before TRNSYS is run, to create a certain data file The command line statements used with BEFORE and AFTER should include the complete path to the particular executable file and any command line switches required for running it Through the use of the many TRNSED Format statements described above, the TRNSED input window can be made to look any way the TRNSED programmer likes Figure 3 shows an example of a completed TRNSED window with formatting Figure 3: Completed document in TRNSED format Providing Help in TRNSED The TRNSED program allows programmers to create context-sensitive help information for the TRNSED input window The help information is entered into an external help file with a hlp extension and a prefix matching that of the TRNSED input file For example, the help file for the input file called sdhwtrd should be sdhwhlp This hlp file is simply a text file and

13 TRNSHELL APPENDIX I 45 should reside in the same directory as the corresponding TRNSED input file To properly write the hlp file, follow the steps below 1 Supply a unique help number to each TRNSED Parameter or File Reference statement in the input file (between 1 and 999) For the example shown below, 2 is the help number EFF = 07 * Intercept Efficiency Open the help file for editing This file should have the same name as the input file but with a hlp extension 3 Add the desired help text to the hlp file The required help entry syntax is best illustrated by an example All text information between topic lines will be displayed as contextsensitive help information topic EFF=2 The collector efficiency is a measure of the performance of the solar collector The efficiency represents the fraction of incoming solar radiation that is transferred in the form of heat to the collector fluid Since the collector efficiency is a ratio, it must be greater than zero and less than one The user will then see the following information when help is requested (the F1 key is pressed) with the mouse cursor positioned over the collector efficiency parameter input field in the TRNSED window The collector efficiency is a measure of the performance of the solar collector The efficiency represents the fraction of incoming solar radiation that is transferred in the form of heat to the collector fluid Since the collector efficiency is a ratio, it must be greater than zero and less than one Using TRNSED Index Files Sometimes multiple TRNSED input files are associated with a given TRNSYS simulation project In these cases, it may be desirable for the TRNSED programmer to make use of TRNSED index files when sharing such TRNSED projects with others Once created, the index file (idx) will be opened when the TRNSED program is launched (provided the idx file resides in the same directory as TRNSEDEXE) When the index file is opened, a Select Project dialog box lists the TRNSED input files in the project and can display associated pictures and help messages for each The TRNSED user can open any of the TRNSED input files from this window The index file is a text file containing, for each TRNSED input file in the project, a title for the particular TRNSED input file, the path to the input file, the path to an optional bitmap picture associated with the input file, and the path to an optional help file

14 46 TRNSHELL APPENDIX I associated with the input file Also included at the top of the index file are three lines of text used as title material for the Select Project dialog box For a project with just one input file, this dialog box might look like the following: Figure 4: The Select Project Dialog Box from an Index File The index file on which this dialog window is based contains only these lines: Simple SDHW System TRNSYS 142 UW-Madison Solar Energy Laboratory Simple SDHW System sdhwtrd sdhwbmp sdhwtxt The first three lines of this file are arbitrary and affect only the display of Select Project dialog window Following these lines is any number of groups of two lines (one set for each TRNSED input file in the project): title of TRNSED input file TRNSED input file name picture file name help file name The text for title of TRNSED input file is arbitrary TRNSED input file name, picture file name, and help file name are separated by spaces and should contain the complete path to the specified files Creating TRNSED Files with IISiBat All input files generated by IISIBat are TRNSED files Which variables are given TRNSED statements within IISiBat is determined by which parameters and unconnected inputs are locked or unlocked within IISiBat Figure 5 shows the IISiBat Parameters Window for the Type 9 TMY Data Reader

15 TRNSHELL APPENDIX I 47 Figure 5: Parameters Window for Type 9 TMY Data Reader Notice that on the left of the Parameter window is a vertical row of icons The first two are Lock and Lock All which make it possible to lock a parameter or all parameters so they cannot be changed Simply click on the Lock icon and then click on the little lock next to the parameter name to lock that parameter The locking of a parameter, input or derivative has several important effects An unlocked parameter or unlocked initial value of an unconnected input will be written to the generated TRNSYS input file in TRNSED format Only these variables that are written in TRNSED format can be changed by the TRNSED end-user or used in a parametric table Therefore, the decision to leave a parameter (or unconnected input) locked or unlocked should be made with some thought as to the future use of the TRNSYS input file Thus every TRNSYS input file generated by IISiBat automatically includes TRNSED statements The IISiBat user can go directly to using TRNSED with this input file without using the Make TRNSED utility of the TRNSHELL program or generating a custom TRNSED file Refer to the IISiBat manual for more information about this IISiBat feature