@BeginModule
@NewPage
@Name      = Remapeta
@Title     = Remap vertical hybrid level
@Section   = Interpolation
@Class     = Interpolation
@Arguments = ifile ofile
@Operators = remapeta

@BeginDescription
This operator interpolates between different vertical hybrid levels. 
This include the preparation of consistent data for the free atmosphere.
The procedure for the vertical interpolation is based on the HIRLAM scheme
and was adapted from @cite{INTERA}.
The vertical interpolation is based on the vertical integration of the
hydrostatic equation with few adjustments. The basic tasks are the following one:
@BeginItemize
@Item = at first integration of hydrostatic equation
@Item = extrapolation of surface pressure
@Item = Planetary Boundary-Layer (PBL) profile interpolation
@Item = interpolation in free atmosphere
@Item = merging of both profiles
@Item = final surface pressure correction
@EndItemize

The vertical interpolation corrects the surface pressure. This is simply
a cut-off or an addition of air mass. This mass correction should not
influence the geostrophic velocity field in the middle troposhere. Therefore
the total mass above a given reference level is conserved. As reference level
the geopotential height of the 400 hPa level is used. Near the surface the
correction can affect the vertical structure of the PBL. Therefore the
interpolation is done using the potential temperature. But in the free
atmosphere above a certain n (n=0.8 defining the top of the PBL) the
interpolation is done linearly. After the interpolation both profiles
are merged. With the resulting temperature/pressure correction the hydrostatic
equation is integrated again and adjusted to the reference level finding
the final surface pressure correction. A more detailed description of
the interpolation can be found in @cite{INTERA}.
All input fields have to be on the same horizontal grid.
@EndDescription
@EndModule


@BeginOperator_remapeta
@Title     = Remap vertical hybrid level
@Parameter = vct [oro]

@BeginDescription
@EndDescription
@EndOperator


@BeginParameter
@Item = vct
STRING  File name of an ASCII dataset with the vertical coordinate table
@Item = oro
STRING  File name with the orography (surf. geopotential) of the target dataset (optional)
@EndParameter


@BeginEnvironment
@Item = REMAPETA_PTOP
Sets the minimum pressure level for condensation.
Above this level the humidity is set to the constant 1.E-6.
The default value is 0 Pa.
@EndEnvironment


@BeginNote
The code numbers or the variable names of the required parameter have to
follow the \cite{ECHAM} convention.
@C The netCDF CF convention for vertical hybrid coordinates is not supported, yet!
Presently, the vertical coordinate definition of a netCDF file has also to follow the 
ECHAM convention. This means:
@BeginItemize
@Item = the dimension of the full level coordinate and the corresponding variable is called mlev,
@Item = the dimension of the half level coordinate and the corresponding variable is called ilev (ilev must have one element more than mlev)
@Item = the hybrid vertical coefficient a is given in units of Pa and called hyai (hyam for level midpoints)
@Item = the hybrid vertical coefficient b is given in units of 1 and called hybi (hybm for level midpoints)
@Item = the mlev variable has a borders attribute containing the character string 'ilev'
@EndItemize
Use the @mod{sinfo} command to test if your vertical coordinate system is recognized as hybrid system.

In case @mod{remapeta} complains about not finding any data on hybrid model levels you may wish
to use the @mod{setzaxis} command to generate a zaxis description which conforms to the ECHAM convention.
See section "1.4 Z-axis description" for an example how to define a hybrid Z-axis.
@EndNote


@BeginExample
To remap between different hybrid model level data use:
@BeginVerbatim
   cdo remapeta,vct ifile ofile
@EndVerbatim
Here is an example vct file with 19 hybrid model level:
@BeginListing
    0       0.00000000000000000       0.00000000000000000
    1    2000.00000000000000000       0.00000000000000000
    2    4000.00000000000000000       0.00000000000000000
    3    6046.10937500000000000       0.00033899326808751
    4    8267.92968750000000000       0.00335718691349030
    5   10609.51171875000000000       0.01307003945112228
    6   12851.10156250000000000       0.03407714888453484
    7   14698.50000000000000000       0.07064980268478394
    8   15861.12890625000000000       0.12591671943664551
    9   16116.23828125000000000       0.20119541883468628
   10   15356.92187500000000000       0.29551959037780762
   11   13621.46093750000000000       0.40540921688079834
   12   11101.55859375000000000       0.52493220567703247
   13    8127.14453125000000000       0.64610791206359863
   14    5125.14062500000000000       0.75969839096069336
   15    2549.96899414062500000       0.85643762350082397
   16     783.19506835937500000       0.92874687910079956
   17       0.00000000000000000       0.97298520803451538
   18       0.00000000000000000       0.99228149652481079
   19       0.00000000000000000       1.00000000000000000
@EndListing
@EndExample
