@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
