Index: palm/trunk/UTIL/inifor/README
===================================================================
--- palm/trunk/UTIL/inifor/README	(revision 3182)
+++ palm/trunk/UTIL/inifor/README	(revision 3395)
@@ -1,3 +1,3 @@
-# INIFOR - Mesoscale Interface for Initializing and Forcing PALM-4U (v1.3.0)
+# INIFOR - Mesoscale Interface for Initializing and Forcing PALM-4U (v1.4.0)
 
 INIFOR provides the meteorological fields required to initialize and drive the
@@ -14,11 +14,55 @@
 
 
+## MINIMAL USAGE EXAMPLE
+
+1. Customize `./namelist` (number of grid points and spacings, end_time)
+2. Run `current_version/trunk/SCRIPTS/inifor --path <scenario path> --date <YYYYMMDD>`
+
+
 ## USAGE
 
-1. Customize `./namelist` (number or grid points and spacings, end_time)
-2. Run `current_version/trunk/SCRIPTS/inifor -path <scenario path> -date <YYYYMMDD>`
+After compilation, the `inifor` binary resides in the `$PALM_BIN` path, i.e. in
+`<PALM path>/current_version/trunk/SCRIPTS/`.
+
+In order to run, INIFOR requires three kinds of inputs:
+
+1. hourly COSMO model output,
+2. a steering namelist file, and
+3. command-line options.
+
+In addition, a static driver file may be supplied (see `--static-driver` option
+below) in order to pass the coordinates of the PALM origin to INIFOR. If no
+static driver is passed to INIFOR, origin coordinates are read from the namelist
+file.
+
+A typical `inifor` call looks like this:
+
+    inifor --path /data/evaluation/20170729 --date 2017073006 \
+           --init-mode profile -n namelist -o dynamic_driver.nc \
+           --elevation 110 --input-prefix lff0
+
+### INPUT DATA: COSMO MODEL OUTPUT
+
+INIFOR processes COSMO model output which it requires to be stored in a set of
+netCDF files located in a user-specified path (see `--path` option). These are:
+
+- hhl.nc: This file provides the COSMO numerical grid. (*hhl* abbreviates
+  *height of half layers*, i.e. the heights of the vertical cell boundaries.)
+- soil.nc: This file provides the COSMO soil map and is used to destinguish land
+  from water cells.
+- `<prefix>YYYYMMDDHH-<suffix>.nc`: Each of these files contains COSMO model
+  of one time step at the given time in UTC (Y..year, M..month, D..day, H..hour).
+    - The `<prefix>` distinguishes different DWD products, for instance COSMO
+      analyses (`laf`) or forecasts (`lff`).
+    - The `<suffix>` distinguishes four kinds of COSMO model output data, namely
+        - `flow` (atmospheric fields)
+        - `rad` (radiation)
+        - `soil` (soil moisture and temperature)
+        - `soilmoisture` (precipitation and evaporation)
+    - For example, laf2016010100-flow.nc contains the atmospheric fields of the
+      COSMO analysis of Januray 1st, 2016 for 0:00 UTC.
 
 
-## AVAILABLE NAMELIST PARAMETERS
+### AVAILABLE NAMELIST PARAMETERS
 
 INIFOR mirrors a subset of the PALM-4U's Fortran namelists `inipar` and `d3par`
@@ -26,5 +70,5 @@
 
 
-### inipar
+#### inipar
 
     nx, ny, nz - number of PALM-4U grid points in x, y, and z direction
@@ -34,11 +78,11 @@
     dz_max - maximum vertical grid spacing [m]
     dz_stretch_level_start(9) - array of height levels above which the grid is
-    to be stretched vertically [m]
+        to be stretched vertically [m]
     dz_stretch_level_end(9) - array of height levels until which the grid is to
-    be stretched vertically [m]
+        be stretched vertically [m]
     longitude, latitude - geographical coordinates of the PALM-4U origin [deg]
 
 
-### d3par
+#### d3par
 
     end_time - PALM-4U simulation time. INIFOR will produce hourly forcing data
@@ -47,5 +91,5 @@
 
 
-### EXAMPLE NAMELIST FILE
+#### EXAMPLE NAMELIST FILE
 
     &inipar nx = 4679, ny = 3939, nz = 360
@@ -59,5 +103,13 @@
 
 
-## AVAILABLE COMMAND-LINE PARAMETERS
+### AVAILABLE COMMAND-LINE PARAMETERS
+    --averaging-mode <mode>:
+        Selects how averaged quantities (large-scale forcing terms) are computed.
+        INIFOR supports averaging along input model levels ('level') and along
+        constant heights ('height'). Default: level
+
+    -a, --averaging-angle <angle>:
+        Width of the averaging box in longitudal and latitudal direction in the
+        source coordinate system (COSMO rotated-pole) [deg]. Default: 2.0
 
     -d, --date, -date <date>:
@@ -65,5 +117,5 @@
         hours (HH) are given, INIFOR assumes that the simulation starts at O UTC
         on that day. Default: 20130721
-        
+
     -i, --init-mode, -mode <mode>:
         Set the PALM-4U initialization mode. INIFOR can provide initial conditions
@@ -72,5 +124,5 @@
 
     -l, --hhl-file, -hhl <netCDF file>:
-        Location of the netCDF file containing the vertical COSMO-DE grid levels,
+        Location of the netCDF file containing the vertical COSMO grid levels,
         specifically the heights of half levels (hhl, i.e. vertical cell faces).
         Default: <scenario path>/hhl.nc
@@ -83,5 +135,5 @@
     -o, --output <output file>:
         Name of the INIFOR output file, i.e. the PALM-4U dynamic driver.
-        Default: ./palm-4u-input.nc
+        Default: ./dynamic_driver.nc
 
     -p, --path, -path <scenario path>:
@@ -89,23 +141,22 @@
 
     -r, --surface-pressure, -p0 <pressure>:
-        Surface pressure at z=0 in the PALM-4U domain [Pa].
-        Default: 1e5
+        Manually set the pressure at z=0 in the PALM-4U domain [Pa]. If not
+        given, the surface pressure is computed from the COSMO pressure field.
 
     -s, --soil-file, -soil <netCDF file>:
-        Location of the netCDF file containing the COSMO-DE soil type map.
+        Location of the netCDF file containing the COSMO soil type map.
         Default: <scenario path>/soil.nc
 
     -t, --static-driver, -static <netCDF file>:
-        Location of the netCDF file containing the static driver file for the case
+        Location of the netCDF file containing the static driver for the case
         to be simulated with PALM-4U. Optional parameter. Default: None
 
     -u, --geostrophic-u, -ug <velocity>:
-        Specifies the geostrophic wind in x direction [m/s]. Default: 0
+        Manually specify the geostrophic wind in x direction [m/s]. If not
+        given, the geostrophic wind is computed from the COSMO pressure field.
 
     -v, --geostrophic-v, -vg <velocity>:
-        Specifies the geostrophic wind in y direction [m/s]. Default: 0
-
-    --version:
-        Output version number and exit.
+        Manually specify the geostrophic wind in y direction [m/s]. If not
+        given, the geostrophic wind is computed from the COSMO pressure field.
 
     -z, --elevation, -z0 <height>: Specifies the elevation of the PALM-4U domain
@@ -113,5 +164,9 @@
 
 
-## ADDITIONAL COMMAND-LINE OPTIONS
+#### ADDITIONAL COMMAND-LINE OPTIONS
+
+    --input-prefix <prefix>:
+        Set the file prefixes for all input files. Individual prefixes can be
+        overwritten with the options below. Default: laf
 
     --flow-prefix <prefix>:
@@ -126,2 +181,9 @@
     --soilmoisture-prefix <prefix>:
         Set the file prefix of soil moisture input files. Default: laf
+
+    --debug:
+        Enable debugging messages.
+
+    --version:
+        Output version number and exit.
+
