RUNNING AN INDIVIDUAL HGSYSTEM MODEL

3. RUNNING AN INDIVIDUAL HGSYSTEM MODEL

User Guide MAIN MENU

3.1 General introduction

HGSYSTEM is a software package with several modules. These modules are separate computer programs that can be run individually. Before any individual model can be run, an appropriate input file must have been prepared. For every model available in HGSYSTEM, example input file can be found in directory C:\HGSYSTEM\STINPUT. For file name conventions see below.

3.2. Running an individual HGSYSTEM model

As an example let us consider an individual run of the AEROPLUME model. AEROPLUME input files always have the file extension API. The example AEROPLUME input file is called SKELETON.API.
Start by copying the example AEROPLUME input file to a file called EXAMPLE.API in a working directory (say C:\HGWORK):

        COPY C:\HGSYSTEM\STINPUT\SKELETON.API C:\HGWORK\EXAMPLE.API

Now, using a file editor, the input file (EXAMPLE.API in this case) can be changed so that the input information corresponds to the case to be simulated. The general structure of input files will be discussed below. When the input file has been updated, running AEROPLUME with this input data is performed by giving the following command:

        AEROPLUME EXAMPLE

In general, running HGSYSTEM model with name 'MODELNAME' in combination with an input file which has a file name 'CASENAME.EXT' is done by the command

        MODELNAME CASENAME

The (up to eight-characters) 'CASENAME' part of the input file name can be freely specified by the user (following DOS file name conventions). The (three-character) 'EXT' part of any HGSYSTEM file follows a strict convention which will be discussed below. All model output names will have 'CASENAME' as the first part of their file name. As explained later, the type of file is indicated by the last character of the three-character extension. Please note that using the same 'CASENAME' twice means that all model output files created during the first run will be overwritten during the second run of the model. Preferably use different names for different model runs.

The 'MODELNAME' for any HGSYSTEM model is simply the name as it is used in this Manual. For HEGADAS-S and HEGADAS-T the names are HEGADASS and HEGADAST respectively.

In our current example, AEROPLUME is actually the name of a batch file AEROPLUM.BAT which can be found in the C:\HGSYSTEM directory. This batch file calls the programs that read in the input file, check the input data and perform the actual AEROPLUME calculations. The batch file also does all the file manipulations needed for a model run.

The program that reads in the input data from the input file and checks whether the input data is valid is called FFMAIN. FFMAIN can only check whether all necessary data is given and whether the data falls within the range specified in the so-called 'data dictionary' of the specific model. For example, the input file for AEROPLUME must contain the orifice diameter and this diameter must have a value between 0.001 and 5 meter. A missing value for the diameter or a value outside this range would cause FFMAIN to signal an input file error.

If an input file contains invalid data of this kind, the program execution will stop. The input file will now contain error messages at the appropriate positions in file. The user must correct the errors before restarting the model run. The user does not have to remove the error messages from the input file: these will be automatically deleted once the input data is found to be correct.

Every model will perform its own checks on input data consistency. If errors are found these will be reported in the model report file or in a specific error file. For example, if specified, the reservoir pressure in an AEROPLUME input file must exceed the ambient pressure.

Each HGSYSTEM model will produce several different output files. The model batch file will display a screen message, after the model run, naming all output files created during this run.
Usually the most important one is the report file. This file contains calculated results and model run information. The user will be mainly interested in this information. Possible link files are also important as they contain information needed in subsequent runs of other HGSYSTEM models for a particular scenario (see Chapter 4). A monitor file, if created by the model, echoes all screen messages for later reference. Error and warning files will only be created if found necessary by the program.

Some files, containing information useful for expert users only, are deleted in the final part of the model batch file. Expert users may want to disable these DOS 'delete' commands by editing the corresponding batch files in the C:\HGSYSTEM directory.

File name conventions are discussed in a later paragraph of this chapter.

3.3. The interactive program HGINTER

The HGSYSTEM package comes with an interactive utility program that allows the user to run one or more HGSYSTEM models. This program is particularly useful if a complete scenario is followed (that is, several models are run consecutively to perform a complete source/near-field/far-field simulation), but it can also be used to run one model. The interactive program can be started by giving the following command:

        HGSYSTEM CASENAME

In a question and answer session, the interactive program determines which models to run in what order. The user only has to modify standard input files to specify the parameters to be used for the model runs. More details on using HGINTER to run a series of models are given in Chapter 4.

3.4. Input files

All HGSYSTEM input files have the same structure. All input data is organised in input block, each with a unique keyword. Within every input block, several input values are entered. Every input value has a unique keyword, followed by the data value. The order of keyword within an input block is irrelevant. The order of input block within the input file is also irrelevant. Information beyond the '*' symbol is treated as a comment. Spaces and comma's can be used as delimiters. Input file are 'free format' or 'flat' files: input data does not have to be in a specific location or column. Input files are ASCII files: they can be edited by any file editor (not by a word processor).

In table 1 an example HGSYSTEM input file is given. This example is for the AEROPLUME model. The use of input blocks, block parameters and comments is clear. The input keywords in this example are: RESERVOIR, RELEASE, GASDATA, PIPE, AMBIENT, DISP, TERMINAT and MATCH. The RESERVOIR block, for example, has two parameters, TRES and PRES. These two parameters are given a value. The TITLE input block is slightly exceptional in that here it is the input block keyword itself which is given a value. The TITLE input block has no further parameters.

For all HGSYSTEM models a complete discussion of all input blocks and parameters in given in subsequent chapters of this User's Manual. The permitted range of every parameter is indicated as well as physical units if applicable. It is also clearly indicated whether a parameters is mandatory or optional and, if optional, what the default values are. Mandatory parameters are parameters that must be specified in every input file. Optional parameters need not occur in the input file. If all parameters of an input block are optional, then the whole input block is optional. Sometimes precisely one of two alternative input blocks must be specified. This will be clearly indicated in the description.

3.5. HGSYSTEM input and output file names

All DOS files names used in the HGSYSTEM environment for input and output of a model, follow a strict nomenclature system.
All input and output file names have the structure:

        <casename>.MMK

where <casename> is an identifier of up to 8 characters specified by the user when calling an HGSYSTEM module. It can be freely chosen within the DOS file name conventions.

The 'MM' in the file extension is a two letter code, which is unique for every HGSYSTEM module. Table 2 shows the letter combinations that are used within HGSYSTEM.

The last letter K of the file extension indicates the type of the file. Table 3 shows the types of file that can occur during a run of an HGSYSTEM module.

Not all types of file will occur for all modules. Several files will normally be deleted in the batch files controlling a module run. Removing the appropriate 'delete' statements from the batch file will make the file available for inspection for more experienced users. Every module will have an input and report file for every model run. Almost always link files will also be generated.

Please note that link files will have the 'MM' code of the model which will use the link information, not of the model which generated the link file.

3.6. Data dictionaries

Pre-processed data dictionaries are all in the directory C:\HGSYSTEM. Their name is of the form DICT.'MM'D where the 'MM' is again as given in table 2. Data dictionary definition files are given in the directory C:\HGSYSTEM\DATADICT. These files can be modified using a file editor. Their name is of the form 'NNN'DDF.DCT. Every data dictionary definition file must be processed by a corresponding batch file to create a new pre-processed data dictionary. The batch files are named 'NNN'DD.BAT and are in the same directory as the definition files. The batch files use the program DDMAIN.

Normally the user will not have to be concerned about the data dictionaries. They are only used internally by the HGSYSTEM program. Expert users may want to change them, preferably after consultation with the HGSYSTEM developers.

Table 1. Example of HGSYSTEM input file (AEROPLUME model).

TITLE		Example input file AEROPLUME
RESERVOIR			* RESERVOIR FLUID THERMODYNAMIC STATE
	TRES	= 20.0	* Storage/reservoir temperature (°C).
	PRES	= 4.0	* Reservoir (absolute) pressure (atm).
*RELEASE			* STACK RELEASE CONDITIONS
	*TSTACK	= 150.0	* Stack release temperature (Degrees C).
GASDATA			* ____________________ POLLUTANT DAT
	WATERPOL	= 1.0E-03	* Water in pollutant (mole fraction).
	CPGAS	= 48.66	* J/MOLE/C specific heat of dry pollutant.
	MMGAS	= 29.72	* KG/KMOLE molecular mass of dry pollutant.
	HEATGR	= 26.53	* ..... heat group (used for HEGADAS link only).
	SPECIES	= METHANE , 0.5990 , 8 35.41 , 63.28 , 6593. , 190.6 , 45.35 -6.029 , 1.251 ,-0.9105 , -1.233 , 16.04 , 354.6
	SPECIES	= ISO-OCTANE , 0.1000 , 8, 186.7 , 255.3 , 3.3361E+04, 543.8 , 25.29, -7.489 , 1.434 , -3.267 , -2.452 , 114.2 , 658.5
PIPE			* PIPE EXIT-PLANE CONDITIONS
	DMDT	= -1.0	* Mass (discharge) flow-rate (kg/s).
	DEXIT	= 0.03200	* (Effective) release orifice diameter (m).
	ZEXIT	= 1.0	* Height of release above level ground (m).
	ANGLE	= 0.0	* Angle of release to horizontal (degrees).
	DURATION	= 100.0	* Release duration (negative steady) (s).
AMBIENT			* ATMOSPHERIC AMBIENT CONDITIONS
	Z0	= 2.0	* Reference height for measurements (m).
	U0	= 3.0	* Wind-speed at reference height (m/s).
	AIRTEMP	= 20.0	* Air temperature at reference height (C).
	AIRPRESS	= 1.00	* Atmosphere pressure at release height (atm).
	RHPERC	= 70.0	* Relative humidity at release height (%).
DISP			* DISPERSION DATA
	PQSTAB	= D	* Pasquill/Gifford stability class (-).
	ZR	= 0.003	* Ground surface roughness (m).
TERMINAT			* JET/PLUME DEVELOPMENT TERMINATION CRITERIA
	XLST	= 100	* Last required downwind (horizontal) distance (m).
	SLST	= -1.0	* Last required distance along plume axis (m).
	ULST	= -1.0	* Last required plume velocity (m/s).
MATCH			* MATCHING CRITERIA FOR HEGADAS/PGPLUME
	RULST	= 0.1	* Matching criterion based on velocities (-).
	RELST	= 0.3	* Matching criterion based on entrainment (-).
	RGLST	= 0.3	* Matching constraint based on buoyancy (-).
	RNLST	= 0.1	* Matching criterion for heavy-gas/neutral limit (-).
	RALST	= 0.2	* Constraint based upon aspect ratio (-).

Table 2. Two-character combinations used in HGSYSTEM model files.

Module name	Code MM
DATAPROP	DP
SPILL	SP
HFSPILL	HL
HFFLASH	HF
LPOOL	LP
AEROPLUME	AP
HFPLUME	HP
HEGABOX	HB
HEGADAS-S	HS
HEGADAS-T	HT
PGPLUME	PG
POSTHS	PS
POSTHT	PT
PROFILE	PR
GET2COL	G2

BACK

Table 3. Types of files that can occur during an HGSYSTEM model run.

Type of file	Code K
Input file	I
Partial input file	P
Report file	R
Monitor or Model Output file	M
Link file	L
Warning messages	W
Error messages	E
Match data (jet models)	1
Match data (jet models)	2
Mixture composition (AEROPLUME)	3
Matching criteria (jet models)	Z
Spreadsheet data or expansion info	X
NAESOL messages	N
Emission rates (LPOOL)	T
Heat transfer details (LPOOL)	H
Cloud composition (LPOOL)	C
SPRINT messages or pool composition	S
Debug information	D

BACK