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

# INIFOR - Mesoscale Interface for Initializing and Forcing PALM-4U

INIFOR provides the meteorological fields required to initialize and drive the
urban-climate model PALM-4U. The required meteorological fields are
interpolated from output data of the meso-scale model COSMO.


## COMPILATION

1. Customize ./Makefile and ./tests/Makefile (netCDF library location, compiler
   and parameters, use Makefile.ifort as a template if you want to use the Intel
   Fortran compiler)
2. Run `make`


## 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

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.


### NAMELIST PARAMETERS

INIFOR mirrors a subset of the PALM-4U's Fortran namelists `inipar` and `d3par`
and supports the following parameters:


#### inipar

    nx, ny, nz - number of PALM-4U grid points in x, y, and z direction
    dx, dy, dz(10) - PALM-4U grid spacings in x, y, and z direction [m]
    dz_stretch_level - height above which the grid will be stretched [m]
    dz_stretch_factor - factor by which the grid will be stretched
    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]
    dz_stretch_level_end(9) - array of height levels until which the grid is to
        be stretched vertically [m]
    longitude, latitude - geographical coordinates of the PALM-4U origin [deg]


#### d3par

    end_time - PALM-4U simulation time. INIFOR will produce hourly forcing data
        from the start date (see -d command-line option) to end_time seconds
        thereafter. [s]


#### EXAMPLE NAMELIST FILE

    &inipar nx = 4679, ny = 3939, nz = 360
            dx = 10., dy = 10., dz = 10.
            dz_stretch_level = 2500.0, dz_stretch_factor = 1.08, dz_max = 100.0
            longitude = 13.082744, latitude = 52.325079
    /
    
    &d3par  end_time = 86400.0
    /


### COMMAND-LINE PARAMETERS

#### INIFOR configuration

    --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>:
        Start date of the simulation in the form YYYYMMDD or YYYYMMDDHH. If no
        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
        as either profiles or three-dimensional fields. The corresponding modes
        are 'profile' and 'volume'. Default: volume

    -r, --surface-pressure, -p0 <pressure>:
        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.

    -u, --geostrophic-u, -ug <velocity>:
        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>:
        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
        above sea level [m]. Default: 35

#### I/O

    -l, --hhl-file, -hhl <netCDF file>:
        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

    -n, --namelist <namelist file>:
        Location of the PALM-4U namelist file. INIFOR expects the file to contain
        two namelists, inipar and d3par, from which it will read grid parameters
        and the simulation time. Default: ./namelist

    -o, --output <output file>:
        Name of the INIFOR output file, i.e. the PALM-4U dynamic driver.
        Default: ./dynamic_driver.nc

    -p, --path, -path <scenario path>:
        Scenario path, i.e. the path of the meteorological input data. Default: ./

    -s, --soil-file, -soil <netCDF file>:
        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 for the case
        to be simulated with PALM-4U. Optional parameter. Default: None



#### FILE PREFIXES

    --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>:
        Set the file prefix of flow input files. Default: laf

    --radiation-prefix <prefix>:
        Set the file prefix of radiation input files. Default: laf

    --soil-prefix <prefix>:
        Set the file prefix of soil input files. Default: laf

    --soilmoisture-prefix <prefix>:
        Set the file prefix of soil moisture input files. Default: laf

#### Non-parameter options

    --debug:
        Enable additional terminal messages and netCDF output for debugging.

    --version:
        Output version number and exit.