A2. Area Input File: File Format Specification
In Version 3.1 the format of the Area Input file has changed totally. Using old files in ENVI-met 3.1 reuqires a load-and-save in the new editor to reformat the file!!
Overview
We are providing this information about the structure of the area input files because we have learned that some users prefer to create their own file (for example out of existing databases) rather than using the ENVI-met Editor.
This is fine with us - but we assume that those users are professionals in computer sciences or at least very enthusiastic. This is why the following sections will provide you with all information required- but on a very compact level. We assume that you will be able to understand it if you are going to build your own Area Input File creator...
Any Area Input File consists of the following sections in fixed order
(followed by)
II. Main Section: Buildings and Plants
III. Main Section: Building Bottoms (optional)
IV. Main Section: Additional Plants (optional)
and the following additional optional sections in any order:
As you see, ENVI-met distinguishes between optional (III, IV) and additional optional (A-D) sections.
(Normal) optional sections offer the possibility to define some of the basic input data more in detail. If they are not used, a dummy line replaces this section. The sequence of these sections is fixed, you must follow it strictly. These sections are a shadow of the past and they are maintained for compatibility reasons.
The additional optional sections are more up-to-date. They can be included in any order inside the file and if they are not needed, they are not mentioned.
I admit that this is not very straight forward, but I also have to say again, that the normal ENVI-met users does not have to mess around with these internals because the editor is taking care of it. For the normal user this way is the most comfortable, because any ENVI-met input file from Version 1.0 on can be loaded into the recent model version. If you are going to program something for ENVI-met... well I'm sorry to tell but you are on the compatibility boat, too.
The file header contains the basic information about the model dimensions and other metadata required to construct the computer model.
01: 2Z-V5
02: % Model description
03: ENVI-met test area
04: % Number of grids in x, y and z direction
05: 20
06: 26
07: 25
08: % Base Horizontal Gridsize dx, dy
09: 2.00
10: 2.00
11: % Vertical Gridsize
12: 2.00
13: % Telecoping vertical Grid? 0= No 1= Yes
14: 0 or 1
14a: % Telecoping factor in %
14b: 20
14c: % Start z-level for telecoping
14d: 30.00
15: % Model rotation out of grid north in deg
16: 0.0
17: % Number of nesting grids
18: 3
19: % Soil Profile ID for Nesting Grid A
20: cl
21: % Soil Profile ID for Nesting Grid B
22: as
23: % Geographical Projection System
24: GK
25: % Real world coordinate lower left grid x and y
26: 2000.00
27: 2000.00
28: % Name of location (city,..)
29: Essen/Germany
30: % Position on earth (longitude and latitude)
31: 53.00
32: 7.00
33: % Name of reference time zone
34: CET/UTC+1
35: % Definition longitude of time zone
36: 15.00
37: % Define where area data are located
38: [INTERNAL]
(...)
Most of the lines are self-explaining, however, a brief description what they mean follows next.
In general, lines beginning with "%" are remark lines. Even if they do not contain information, they must
be kept and they cannot be extended by more remark lines in order to fullfill the format of the file
Defines the number of characters defining one number in the matrix blocks. See annotations here.
-V5 indicates an area input file in format version 5 used by ENVI-met V3.1 and newer.
Other formats are no longer supported by ENVI-met, but can be loaded and then saved in the Editor!
02 - 03: Model description
Free text line describeing the model area
04 - 07: Number of grids in x-, y- and z-direction
The values for x- and y- must correspond to the matrix data following later in the file.
The number of z-values must be defined by the user.
When using the equidistant grid method, the lowest grid box above the surface is automatically split into 5 sub-boxes with Dzs=0.2 Dz. These additional 4 boxes are not included in the number of z-grids given here.
The final model size is increased by the nesting grids and the additional 4 surface-boxes mentioned above. Make sure, that your area is not too big to run ENVI-met.
08 - 12: Base grid size in x-, y- and z-direction
Defines the size of one grid point in meters in the x- y- and z-direction.
Equidistant spacing is used in this version except of the nesting grids and the z-grids if a telecoping grid is used.
For more details see Vertical Grid Layout
13 - 14: Usage of telecoping vertical grid yes/no
If a telecoping grid is used ("1" in line 14) the lines 14 a- d follow.
If no telecoping gird is used, the next line will be line 15 .
15 - 16: Model rotation settings
Model rotation out of grid north in degrees. For more information see here.
17 - 22: Nesting grid settings
L 18 defines the number of nesting grids. For more information see here
Ls 20, 22 define the ID of the soil profiles to be assigned alternating to the nesting grids (e.g. "cl")
For more information see here
23 - 27: Georeference settings
Defines the geographical projection system (not used yet) and the real world reference of the lower left grid.
Will be used for model management later on, for the moment only for information.
28 - 36: Geographical position of the domain
Defines the location in terms of name, longitude, latitude and time zone reference.
See ENVI-met editor for details.
37 - 38: Data file link
In version 3.1, only the [INTERNAL] format is supported which means that the geometry data are included inside this area input file.
II. Main Section: Building height
If the [INTERNAL] format is used, the header is followed by the main section defining the position and height of buildings.
Click here to see an example section.
The format chosen in the first line of the file (Format-ID) is used here. Buildings are set into the area by assigning their height to the corresponding grid points ("20" in the example).
Only integer values are allowed as height information.
ENVI-met will assign the building to the corresponding grid boxes. In the vertical direction, the following rule is used to decide if a grid box is occupied by a building or not: If a grid cell is covered 50% or more by a building, it becomes part of the building. In the other case, it remains free.
Example
A 14 m high building covers 3 grid cells with Dz= 5m (split surface grid not counted).
Contrary, a 12 m building will only be represented by 2 grids in the vertical.
Avoiding captured grids
Captured grids can cause problems in the model simulation.
A "captured grid" is a free grid cell that is surrounded by occupied grid cells only.
Click here to see an example for captured grids.
III. Main Section: Building Bottoms (optional)
Buildings defined using the section explained above all start at ground surface (z=0) as houses normally do.
If you want to define buildings beginning at a different height, an additional Building Bottom Section is needed.
Click here to see an example section
This section begins with the keyword "\BOTTOM" followed by a structure similar to the main section shown before.
Again, the height to building bottom is given in meters. Bottom information without a building on the grid or bottoms higher than the roof level of the associated building are ignored. The vertical grid resolution limits the possibilities of defining overhanging structures.
If you don't need non-zero bottoms, the "\BOTTOM" keyword must be replaced with a single remark line "%....".
This section saves the plants defined in your model area. Contrary to previous formats, plants will not be mixed with buildings in the first section of the input file.
Each plants is defined by its unique two-char ID.
Click here to see an example section
Hint:
Don't forget, that planting trees on a roof increases the total height of the model domain a lot !
Make sure that the total vertical extension of the domain is sufficient !
(see also here)
For every grid in the area, a soil profile and surface material can be chosen individually.
There are two ways to provide this information:
Case A: Each grid in the domain has the same soil profile
In this case no individual information is needed for each single grid point.
A common soil is defined by placing the line
\ALLSOILS=" l"
(if all soils are supposed to be of the " l" type or any other valid soil ID)
Case B: Grids have different soil profiles
In this case, a complete \soils section has to be used to provide this information.
Click here to see an example section.
In both cases, the soil profiles are defined by a two-digit ID (like the vegetation).
All used IDs must be stored in the file PROFILES.DAT.
Invalid profile definitions will be replaced by the default soil profile, which is the first profile defined in PROFILES.DAT.
For more information about databases and their internal connections refer to Database Files Overview.
A. Additional optional sections: Sources
The Sources section begins with the keyword \SOURCES followed by the complete grid matrix like in the \PLANTS section.
This section defines the position of different sources in the model domain. As the concept is the same as for plants, this section is not displayed here.
Any source will be referenced using the two-char ID as defined in SOURCES.DAT or a local database. The two-char ID is non-case sensitive, "XX" is the same as "xx" !
Sources that are inserted in the Area Input File but cannot be found in a database when starting the model will be ignored.
B. Additional optional sections: Receptors
Receptors inside the model area are defined using the \RECEPTOR section. The concept is the same as for the plants explained in the section before. Each receptor is defined by a unique two-char ID. If duplicate receptors are found, the first defined receptor is used, the others are ignored. For more information about receptors click here.
C. Additional optional sections: DB-Links
The database section has no function in ENVI-met. It is used for other programs such as BOTworld (see UNCONVERTED WINHELP MACRO:! ExecFile("www.botworld.info")www.botworld.info) to link certain grid points with database entries.
D. Additional optional sections: DEM
This sections defines a so-called "inline" digital elevation model. The recent version of ENVI-met does not support orography, but ENVI-met already holds a number of interfaces to include it in future versions.