source: palm/trunk/UTIL/inifor/README @ 3716

Last change on this file since 3716 was 3678, checked in by eckhard, 3 years ago

inifor: bugfix: avoid empty averaging regions, check if all input files are present

File size: 7.2 KB
Line 
1# INIFOR - Mesoscale Interface for Initializing and Forcing PALM-4U (v1.4.4)
2
3INIFOR provides the meteorological fields required to initialize and drive the
4urban-climate model PALM-4U. The required meteorological fields are
5interpolated from output data of the meso-scale model COSMO.
6
7
8## COMPILATION
9
101. Customize ./Makefile and ./tests/Makefile (netCDF library location, compiler
11   and parameters, use Makefile.ifort as a template if you want to use the Intel
12   Fortran compiler)
132. Run `make`
14
15
16## MINIMAL USAGE EXAMPLE
17
181. Customize `./namelist` (number of grid points and spacings, end_time)
192. Run `current_version/trunk/SCRIPTS/inifor --path <scenario path> --date <YYYYMMDD>`
20
21
22## USAGE
23
24After compilation, the `inifor` binary resides in the `$PALM_BIN` path, i.e. in
25`<PALM path>/current_version/trunk/SCRIPTS/`.
26
27In order to run, INIFOR requires three kinds of inputs:
28
291. hourly COSMO model output,
302. a steering namelist file, and
313. command-line options.
32
33In addition, a static driver file may be supplied (see `--static-driver` option
34below) in order to pass the coordinates of the PALM origin to INIFOR. If no
35static driver is passed to INIFOR, origin coordinates are read from the namelist
36file.
37
38A typical `inifor` call looks like this:
39
40    inifor --path /data/evaluation/20170729 --date 2017073006 \
41           --init-mode profile -n namelist -o dynamic_driver.nc \
42           --elevation 110 --input-prefix lff0
43
44### INPUT DATA: COSMO MODEL OUTPUT
45
46INIFOR processes COSMO model output which it requires to be stored in a set of
47netCDF files located in a user-specified path (see `--path` option). These are:
48
49- hhl.nc: This file provides the COSMO numerical grid. (*hhl* abbreviates
50  *height of half layers*, i.e. the heights of the vertical cell boundaries.)
51- soil.nc: This file provides the COSMO soil map and is used to destinguish land
52  from water cells.
53- `<prefix>YYYYMMDDHH-<suffix>.nc`: Each of these files contains COSMO model
54  of one time step at the given time in UTC (Y..year, M..month, D..day, H..hour).
55    - The `<prefix>` distinguishes different DWD products, for instance COSMO
56      analyses (`laf`) or forecasts (`lff`).
57    - The `<suffix>` distinguishes four kinds of COSMO model output data, namely
58        - `flow` (atmospheric fields)
59        - `rad` (radiation)
60        - `soil` (soil moisture and temperature)
61        - `soilmoisture` (precipitation and evaporation)
62    - For example, laf2016010100-flow.nc contains the atmospheric fields of the
63      COSMO analysis of Januray 1st, 2016 for 0:00 UTC.
64
65
66### NAMELIST PARAMETERS
67
68INIFOR mirrors a subset of the PALM-4U's Fortran namelists `inipar` and `d3par`
69and supports the following parameters:
70
71
72#### inipar
73
74    nx, ny, nz - number of PALM-4U grid points in x, y, and z direction
75    dx, dy, dz(10) - PALM-4U grid spacings in x, y, and z direction [m]
76    dz_stretch_level - height above which the grid will be stretched [m]
77    dz_stretch_factor - factor by which the grid will be stretched
78    dz_max - maximum vertical grid spacing [m]
79    dz_stretch_level_start(9) - array of height levels above which the grid is
80        to be stretched vertically [m]
81    dz_stretch_level_end(9) - array of height levels until which the grid is to
82        be stretched vertically [m]
83    longitude, latitude - geographical coordinates of the PALM-4U origin [deg]
84
85
86#### d3par
87
88    end_time - PALM-4U simulation time. INIFOR will produce hourly forcing data
89        from the start date (see -d command-line option) to end_time seconds
90        thereafter. [s]
91
92
93#### EXAMPLE NAMELIST FILE
94
95    &inipar nx = 4679, ny = 3939, nz = 360
96            dx = 10., dy = 10., dz = 10.
97            dz_stretch_level = 2500.0, dz_stretch_factor = 1.08, dz_max = 100.0
98            longitude = 13.082744, latitude = 52.325079
99    /
100   
101    &d3par  end_time = 86400.0
102    /
103
104
105### COMMAND-LINE PARAMETERS
106
107#### INIFOR configuration
108
109    --averaging-mode <mode>:
110        Selects how averaged quantities (large-scale forcing terms) are computed.
111        INIFOR supports averaging along input model levels ('level') and along
112        constant heights ('height'). Default: level
113
114    -a, --averaging-angle <angle>:
115        Width of the averaging box in longitudal and latitudal direction in the
116        source coordinate system (COSMO rotated-pole) [deg]. Default: 2.0
117
118    -d, --date, -date <date>:
119        Start date of the simulation in the form YYYYMMDD or YYYYMMDDHH. If no
120        hours (HH) are given, INIFOR assumes that the simulation starts at O UTC
121        on that day. Default: 20130721
122
123    -i, --init-mode, -mode <mode>:
124        Set the PALM-4U initialization mode. INIFOR can provide initial conditions
125        as either profiles or three-dimensional fields. The corresponding modes
126        are 'profile' and 'volume'. Default: volume
127
128    -r, --surface-pressure, -p0 <pressure>:
129        Manually set the pressure at z=0 in the PALM-4U domain [Pa]. If not
130        given, the surface pressure is computed from the COSMO pressure field.
131
132    -u, --geostrophic-u, -ug <velocity>:
133        Manually specify the geostrophic wind in x direction [m/s]. If not
134        given, the geostrophic wind is computed from the COSMO pressure field.
135
136    -v, --geostrophic-v, -vg <velocity>:
137        Manually specify the geostrophic wind in y direction [m/s]. If not
138        given, the geostrophic wind is computed from the COSMO pressure field.
139
140    -z, --elevation, -z0 <height>: Specifies the elevation of the PALM-4U domain
141        above sea level [m]. Default: 35
142
143#### I/O
144
145    -l, --hhl-file, -hhl <netCDF file>:
146        Location of the netCDF file containing the vertical COSMO grid levels,
147        specifically the heights of half levels (hhl, i.e. vertical cell faces).
148        Default: <scenario path>/hhl.nc
149
150    -n, --namelist <namelist file>:
151        Location of the PALM-4U namelist file. INIFOR expects the file to contain
152        two namelists, inipar and d3par, from which it will read grid parameters
153        and the simulation time. Default: ./namelist
154
155    -o, --output <output file>:
156        Name of the INIFOR output file, i.e. the PALM-4U dynamic driver.
157        Default: ./dynamic_driver.nc
158
159    -p, --path, -path <scenario path>:
160        Scenario path, i.e. the path of the meteorological input data. Default: ./
161
162    -s, --soil-file, -soil <netCDF file>:
163        Location of the netCDF file containing the COSMO soil type map.
164        Default: <scenario path>/soil.nc
165
166    -t, --static-driver, -static <netCDF file>:
167        Location of the netCDF file containing the static driver for the case
168        to be simulated with PALM-4U. Optional parameter. Default: None
169
170
171
172#### FILE PREFIXES
173
174    --input-prefix <prefix>:
175        Set the file prefixes for all input files. Individual prefixes can be
176        overwritten with the options below. Default: laf
177
178    --flow-prefix <prefix>:
179        Set the file prefix of flow input files. Default: laf
180
181    --radiation-prefix <prefix>:
182        Set the file prefix of radiation input files. Default: laf
183
184    --soil-prefix <prefix>:
185        Set the file prefix of soil input files. Default: laf
186
187    --soilmoisture-prefix <prefix>:
188        Set the file prefix of soil moisture input files. Default: laf
189
190#### Non-parameter options
191
192    --debug:
193        Enable additional terminal messages and netCDF output for debugging.
194
195    --version:
196        Output version number and exit.
197
Note: See TracBrowser for help on using the repository browser.