Index: palm/trunk/DOC/app/chapter_4.1.html
===================================================================
--- palm/trunk/DOC/app/chapter_4.1.html	(revision 83)
+++ palm/trunk/DOC/app/chapter_4.1.html	(revision 97)
@@ -208,5 +208,5 @@
 </td> </tr> <tr> <td style="vertical-align: top;"> <p><a name="pc_pt_t"></a><b>bc_pt_t</b></p>
 </td> <td style="vertical-align: top;">C * 20</td>
-<td style="vertical-align: top;"><span style="font-style: italic;">'initial gradient'</span></td>
+<td style="vertical-align: top;"><span style="font-style: italic;">'initial_ gradient'</span></td>
 <td style="vertical-align: top;"> <p style="font-style: normal;">Top boundary condition of the
 potential temperature.&nbsp; </p> <p>Allowed are the
@@ -299,5 +299,12 @@
 bc_s_t_val * dzu(nz+1)</p> </ul> <p style="font-style: normal;">(up to k=nz the prognostic
 equation for the scalar concentration is
-solved).</p> </td> </tr> <tr> <td style="vertical-align: top;"> <p><a name="bc_uv_b"></a><b>bc_uv_b</b></p>
+solved).</p> </td> </tr> <tr><td style="vertical-align: top;"><a name="bc_sa_t"></a><span style="font-weight: bold;">bc_sa_t</span></td><td style="vertical-align: top;">C * 20</td><td style="vertical-align: top;"><span style="font-style: italic;">'neumann'</span></td><td style="vertical-align: top;"><p style="font-style: normal;">Top boundary condition of the salinity.&nbsp; </p> <p>This parameter only comes into effect for ocean runs (see parameter <a href="#ocean">ocean</a>).</p><p style="font-style: normal;">Allowed are the
+values <span style="font-style: italic;">'dirichlet' </span>(sa(k=nz+1)
+does not change during the run) and <span style="font-style: italic;">'neumann'</span>
+(sa(k=nz+1)=sa(k=nz))<span style="font-style: italic;"></span>.&nbsp;<br><br>
+When a constant salinity flux is used at the top boundary (<a href="chapter_4.1.html#top_salinityflux">top_salinityflux</a>),
+<b>bc_sa_t</b> = <span style="font-style: italic;">'neumann'</span>
+must be used, because otherwise the resolved scale may contribute to
+the top flux so that a constant value cannot be guaranteed.</p></td></tr><tr> <td style="vertical-align: top;"> <p><a name="bc_uv_b"></a><b>bc_uv_b</b></p>
 </td> <td style="vertical-align: top;">C * 20</td>
 <td style="vertical-align: top;"><span style="font-style: italic;">'dirichlet'</span></td>
@@ -331,5 +338,8 @@
 Neumann condition yields the free-slip condition with u(k=nz+1) =
 u(k=nz) and v(k=nz+1) = v(k=nz) (up to k=nz the prognostic equations
-for the velocities are solved).</p> </td> </tr> <tr>
+for the velocities are solved).</p> </td> </tr> <tr><td style="vertical-align: top;"><a name="bottom_salinityflux"></a><span style="font-weight: bold;">bottom_salinityflux</span></td><td style="vertical-align: top;">R</td><td style="vertical-align: top;"><span style="font-style: italic;">0.0</span></td><td style="vertical-align: top;"><p>Kinematic salinity flux near the surface (in psu m/s).&nbsp;</p>This parameter only comes into effect for ocean runs (see parameter <a href="chapter_4.1.html#ocean">ocean</a>).<p>The
+respective salinity flux value is used
+as bottom (horizontally homogeneous) boundary condition for the salinity equation. This additionally requires that a Neumann
+condition must be used for the salinity, which is currently the only available condition.<br> </p> </td></tr><tr>
 <td style="vertical-align: top;"><span style="font-weight: bold;"><a name="building_height"></a>building_height</span></td>
 <td style="vertical-align: top;">R</td> <td style="vertical-align: top;"><span style="font-style: italic;">50.0</span></td> <td>Height
@@ -1111,5 +1121,11 @@
 be an integral multiple of
 the number of processors in x-direction (due to data transposition
-restrictions).</p> </td> </tr> <tr> <td style="vertical-align: top;"> <p><a name="omega"></a><b>omega</b></p>
+restrictions).</p> </td> </tr> <tr><td style="vertical-align: top;"><a name="ocean"></a><span style="font-weight: bold;">ocean</span></td><td style="vertical-align: top;">L</td><td style="vertical-align: top;"><span style="font-style: italic;">.F.</span></td><td style="vertical-align: top;">Parameter to switch on&nbsp;ocean runs.<br><br>By default PALM is configured to simulate&nbsp;atmospheric flows. However, starting from version 3.3, <span style="font-weight: bold;">ocean</span> = <span style="font-style: italic;">.T.</span> allows&nbsp;simulation of ocean turbulent flows. Setting this switch has several effects:<br><br><ul><li>An additional prognostic equation for salinity is solved.</li><li>Potential temperature in buoyancy and stability-related terms is replaced by potential density.</li><li>Potential
+density is calculated from the equation of state for seawater after
+each timestep, using the algorithm proposed by Jackett et al. (2006, J.
+Atmos. Oceanic Technol., <span style="font-weight: bold;">23</span>, 1709-1728).<br>So far, only the initial hydrostatic pressure is entered into this equation.</li><li>z=0 (sea surface) is assumed at the model top (vertical grid index <span style="font-family: Courier New,Courier,monospace;">k=nzt</span> on the w-grid), with negative values of z indicating the depth.</li><li>Initial profiles are constructed (e.g. from <a href="#pt_vertical_gradient">pt_vertical_gradient</a> / <a href="#pt_vertical_gradient_level">pt_vertical_gradient_level</a>) starting from the sea surface, using surface values&nbsp;given by <a href="#pt_surface">pt_surface</a>, <a href="#sa_surface">sa_surface</a>, <a href="#ug_surface">ug_surface</a>, and <a href="#vg_surface">vg_surface</a>.</li><li>Zero salinity flux is used as default boundary condition at the bottom of the sea.</li><li>If switched on, random perturbations are by default imposed to the upper model domain from zu(nzt*2/3) to zu(nzt-3).</li></ul><br>Relevant parameters to be exclusively used for steering ocean runs are <a href="#bc_sa_t">bc_sa_t</a>, <a href="#bottom_salinityflux">bottom_salinityflux</a>, <a href="#sa_surface">sa_surface</a>, <a href="#sa_vertical_gradient">sa_vertical_gradient</a>, <a href="#sa_vertical_gradient_level">sa_vertical_gradient_level</a>, and <a href="#top_salinityflux">top_salinityflux</a>.<br><br>Section <a href="chapter_4.2.2.html">4.4.2</a> gives an example for appropriate settings of these and other parameters neccessary for ocean runs.<br><br><span style="font-weight: bold;">ocean</span> = <span style="font-style: italic;">.T.</span> does not allow settings of <a href="#timestep_scheme">timestep_scheme</a> = <span style="font-style: italic;">'leapfrog'</span> or <span style="font-style: italic;">'leapfrog+euler'</span> as well as <a href="#scalar_advec">scalar_advec</a> = <span style="font-style: italic;">'ups-scheme'</span>.<br><br><span style="font-weight: bold;">Current limitations:</span><br>Using
+a vertical grid stretching is not recommended since it would still
+stretch the grid towards the top boundary of the model (sea surface)
+instead of the bottom boundary.</td></tr><tr> <td style="vertical-align: top;"> <p><a name="omega"></a><b>omega</b></p>
 </td> <td style="vertical-align: top;">R</td>
 <td style="vertical-align: top;"><i>7.29212E-5</i></td>
@@ -1241,5 +1257,5 @@
 temperature to be used in all buoyancy terms (in K).<br><br>By
 default, the instantaneous horizontal average over the total model
-domain is used.</td></tr><tr> <td style="vertical-align: top;"> <p><a name="pt_surface"></a><b>pt_surface</b></p>
+domain is used.<br><br><span style="font-weight: bold;">Attention:</span><br>In case of ocean runs (see <a href="chapter_4.1.html#ocean">ocean</a>), always a reference temperature is used in the buoyancy terms with a default value of <span style="font-weight: bold;">pt_reference</span> = <a href="#pt_surface">pt_surface</a>.</td></tr><tr> <td style="vertical-align: top;"> <p><a name="pt_surface"></a><b>pt_surface</b></p>
 </td> <td style="vertical-align: top;">R</td>
 <td style="vertical-align: top;"><i>300.0</i></td>
@@ -1247,10 +1263,13 @@
 potential temperature (in K).&nbsp; </p> <p>This
 parameter assigns the value of the potential temperature
-pt at the surface (k=0)<b>.</b> Starting from this value,
+<span style="font-weight: bold;">pt</span> at the surface (k=0)<b>.</b> Starting from this value,
 the
 initial vertical temperature profile is constructed with <a href="#pt_vertical_gradient">pt_vertical_gradient</a>
 and <a href="#pt_vertical_gradient_level">pt_vertical_gradient_level
 </a>.
-This profile is also used for the 1d-model as a stationary profile.</p>
+This profile is also used for the 1d-model as a stationary profile.</p><p><span style="font-weight: bold;">Attention:</span><br>In case of ocean runs (see <a href="#ocean">ocean</a>),
+this parameter gives the temperature value at the sea surface, which is
+at k=nzt. The profile is then constructed from the surface down to the
+bottom of the model.</p>
 </td> </tr> <tr> <td style="vertical-align: top;"> <p><a name="pt_surface_initial_change"></a><b>pt_surface_initial</b>
 <br> <b>_change</b></p> </td> <td style="vertical-align: top;">R</td> <td style="vertical-align: top;"><span style="font-style: italic;">0.0</span><br> </td>
@@ -1291,5 +1310,8 @@
 100 m and for z &gt; 1000.0 m up to the top boundary it is
 0.5 K / 100 m (it is assumed that the assigned height levels correspond
-with uv levels). </p> </td> </tr> <tr> <td style="vertical-align: top;"> <p><a name="pt_vertical_gradient_level"></a><b>pt_vertical_gradient</b>
+with uv levels).</p><p><span style="font-weight: bold;">Attention:</span><br>In case of ocean runs (see <a href="chapter_4.1.html#ocean">ocean</a>),
+the profile is constructed like described above, but starting from the
+sea surface (k=nzt) down to the bottom boundary of the model. Height
+levels have then to be given as negative values, e.g. <span style="font-weight: bold;">pt_vertical_gradient_level</span> = <span style="font-style: italic;">-500.0</span>, <span style="font-style: italic;">-1000.0</span>.</p> </td> </tr> <tr> <td style="vertical-align: top;"> <p><a name="pt_vertical_gradient_level"></a><b>pt_vertical_gradient</b>
 <br> <b>_level</b></p> </td> <td style="vertical-align: top;">R (10)</td> <td style="vertical-align: top;"> <p><i>10 *</i>&nbsp;
 <span style="font-style: italic;">0.0</span><br>
@@ -1297,10 +1319,9 @@
 <p>Height level from which on the temperature gradient defined by
 <a href="#pt_vertical_gradient">pt_vertical_gradient</a>
-is effective (in m).&nbsp; </p> <p>The height levels
-are to be assigned in ascending order. The
+is effective (in m).&nbsp; </p> <p>The height levels have to be assigned in ascending order. The
 default values result in a neutral stratification regardless of the
 values of <a href="#pt_vertical_gradient">pt_vertical_gradient</a>
 (unless the top boundary of the model is higher than 100000.0 m).
-For the piecewise construction of temperature profiles see <a href="#pt_vertical_gradient">pt_vertical_gradient</a>.</p>
+For the piecewise construction of temperature profiles see <a href="#pt_vertical_gradient">pt_vertical_gradient</a>.</p><span style="font-weight: bold;">Attention:</span><br>In case of ocean runs&nbsp;(see <a href="chapter_4.1.html#ocean">ocean</a>), the (negative) height levels have to be assigned in descending order.
 </td> </tr> <tr> <td style="vertical-align: top;"> <p><a name="q_surface"></a><b>q_surface</b></p>
 </td> <td style="vertical-align: top;">R</td>
@@ -1453,5 +1474,36 @@
 is switched
 on (see <a href="#prandtl_layer">prandtl_layer</a>).</p>
-</td> </tr> <tr> <td style="vertical-align: top;"> <p><a name="scalar_advec"></a><b>scalar_advec</b></p>
+</td> </tr> <tr><td style="vertical-align: top;"><a name="sa_surface"></a><span style="font-weight: bold;">sa_surface</span></td><td style="vertical-align: top;">R</td><td style="vertical-align: top;"><span style="font-style: italic;">35.0</span></td><td style="vertical-align: top;"> <p>Surface salinity (in psu).&nbsp;</p>This parameter only comes into effect for ocean runs (see parameter <a href="chapter_4.1.html#ocean">ocean</a>).<p>This
+parameter assigns the value of the salinity <span style="font-weight: bold;">sa</span> at the sea surface (k=nzt)<b>.</b> Starting from this value,
+the
+initial vertical salinity profile is constructed from the surface down to the bottom of the model (k=0) by using&nbsp;<a href="chapter_4.1.html#sa_vertical_gradient">sa_vertical_gradient</a>
+and&nbsp;<a href="chapter_4.1.html#sa_vertical_gradient_level">sa_vertical_gradient_level
+</a>.</p></td></tr><tr><td style="vertical-align: top;"><a name="sa_vertical_gradient"></a><span style="font-weight: bold;">sa_vertical_gradient</span></td><td style="vertical-align: top;">R(10)</td><td style="vertical-align: top;"><span style="font-style: italic;">10 * 0.0</span></td><td style="vertical-align: top;"><p>Salinity gradient(s) of the initial salinity profile (in psu
+/ 100 m).&nbsp; </p> <p>This parameter only comes into effect for ocean runs (see parameter <a href="chapter_4.1.html#ocean">ocean</a>).</p><p>This salinity gradient
+holds starting from the height&nbsp;
+level defined by <a href="chapter_4.1.html#sa_vertical_gradient_level">sa_vertical_gradient_level</a>
+(precisely: for all uv levels k where zu(k) &lt;
+sa_vertical_gradient_level, sa_init(k) is set: sa_init(k) =
+sa_init(k+1) - dzu(k+1) * <b>sa_vertical_gradient</b>) down to the bottom boundary or down to the next height level defined
+by <a href="chapter_4.1.html#sa_vertical_gradient_level">sa_vertical_gradient_level</a>.
+A total of 10 different gradients for 11 height intervals (10 intervals
+if <a href="chapter_4.1.html#sa_vertical_gradient_level">sa_vertical_gradient_level</a>(1)
+= <i>0.0</i>) can be assigned. The surface salinity at k=nzt is
+assigned via <a href="chapter_4.1.html#sa_surface">sa_surface</a>.&nbsp;
+</p> <p>Example:&nbsp; </p> <ul><p><b>sa_vertical_gradient</b>
+= <i>1.0</i>, <i>0.5</i>,&nbsp; <br>
+<b>sa_vertical_gradient_level</b> = <i>-500.0</i>,
+-<i>1000.0</i>,</p></ul> <p>That
+defines the salinity to be constant down to z = -500.0 m with a salinity given by <a href="chapter_4.1.html#sa_surface">sa_surface</a>.
+For -500.0 m &lt; z &lt;= -1000.0 m the salinity gradient is
+1.0 psu /
+100 m and for z &lt; -1000.0 m down to the bottom boundary it is
+0.5 psu / 100 m (it is assumed that the assigned height levels correspond
+with uv levels).</p></td></tr><tr><td style="vertical-align: top;"><a name="sa_vertical_gradient_level"></a><span style="font-weight: bold;">sa_vertical_gradient_level</span></td><td style="vertical-align: top;">R(10)</td><td style="vertical-align: top;"><span style="font-style: italic;">10 * 0.0</span></td><td style="vertical-align: top;"><p>Height level from which on the salinity gradient defined by <a href="chapter_4.1.html#sa_vertical_gradient">sa_vertical_gradient</a>
+is effective (in m).&nbsp; </p> <p>This parameter only comes into effect for ocean runs (see parameter <a href="chapter_4.1.html#ocean">ocean</a>).</p><p>The height levels have to be assigned in descending order. The
+default values result in a constant salinity profile regardless of the
+values of <a href="chapter_4.1.html#sa_vertical_gradient">sa_vertical_gradient</a>
+(unless the bottom boundary of the model is lower than -100000.0 m).
+For the piecewise construction of salinity profiles see <a href="chapter_4.1.html#sa_vertical_gradient">sa_vertical_gradient</a>.</p></td></tr><tr> <td style="vertical-align: top;"> <p><a name="scalar_advec"></a><b>scalar_advec</b></p>
 </td> <td style="vertical-align: top;">C * 10</td>
 <td style="vertical-align: top;"><i>'pw-scheme'</i></td>
@@ -1835,5 +1887,19 @@
 Prandtl-layer is available at the top boundary so far.</p><p>See
 also <a href="#surface_heatflux">surface_heatflux</a>.</p>
-</td></tr><tr> <td style="vertical-align: top;">
+</td></tr><tr><td style="vertical-align: top;"><a name="top_salinityflux"></a><span style="font-weight: bold;">top_salinityflux</span></td><td style="vertical-align: top;">R</td><td style="vertical-align: top;"><span style="font-style: italic;">no prescribed<br>
+salinityflux</span></td><td style="vertical-align: top;"><p>Kinematic
+salinity flux at the top boundary, i.e. the sea surface (in psu m/s).&nbsp; </p>
+<p>This parameter only comes into effect for ocean runs (see parameter <a href="chapter_4.1.html#ocean">ocean</a>).</p><p>If a value is assigned to this parameter, the internal
+two-dimensional surface heat flux field <span style="font-family: monospace;">saswst</span> is
+initialized with the value of <span style="font-weight: bold;">top_salinityflux</span>&nbsp;as
+top (horizontally homogeneous) boundary condition for the salinity equation. This additionally requires that a Neumann
+condition must be used for the salinity (see <a href="chapter_4.1.html#bc_sa_t">bc_sa_t</a>),
+because otherwise the resolved scale may contribute to
+the top flux so that a constant value cannot be guaranteed.<span style="font-style: italic;"></span>&nbsp;</p>
+<p><span style="font-weight: bold;">Note:</span><br>The
+application of a salinity flux at the model top additionally requires the setting of
+initial parameter <a href="chapter_4.1.html#use_top_fluxes">use_top_fluxes</a>
+= .T..<span style="font-style: italic;"></span><span style="font-weight: bold;"></span> </p><p>See
+also <a href="chapter_4.1.html#bottom_salinityflux">bottom_salinityflux</a>.</p></td></tr><tr> <td style="vertical-align: top;">
 <p><a name="ug_surface"></a><span style="font-weight: bold;">ug_surface</span></p>
 </td> <td style="vertical-align: top;">R<br> </td>
@@ -1857,5 +1923,8 @@
 value, it is recommended to use a Galilei-transformation of the
 coordinate system, if possible (see <a href="#galilei_transformation">galilei_transformation</a>),
-in order to obtain larger time steps.<br> </td> </tr>
+in order to obtain larger time steps.<br><br><span style="font-weight: bold;">Attention:</span><br>In case of ocean runs (see <a href="chapter_4.1.html#ocean">ocean</a>),
+this parameter gives the velocity value at the sea surface, which is
+at k=nzt. The profile is then constructed from the surface down to the
+bottom of the model.<br> </td> </tr>
 <tr> <td style="vertical-align: top;"> <p><a name="ug_vertical_gradient"></a><span style="font-weight: bold;">ug_vertical_gradient</span></p>
 </td> <td style="vertical-align: top;">R(10)<br>
@@ -1872,5 +1941,8 @@
 total of 10 different gradients for 11 height intervals (10
 intervals&nbsp; if <a href="#ug_vertical_gradient_level">ug_vertical_gradient_level</a>(1)
-= 0.0) can be assigned. The surface geostrophic wind is assigned by <a href="#ug_surface">ug_surface</a>. <br> </td>
+= 0.0) can be assigned. The surface geostrophic wind is assigned by <a href="#ug_surface">ug_surface</a>.<br><br><span style="font-weight: bold;">Attention:</span><br>In case of ocean runs (see <a href="chapter_4.1.html#ocean">ocean</a>),
+the profile is constructed like described above, but starting from the
+sea surface (k=nzt) down to the bottom boundary of the model. Height
+levels have then to be given as negative values, e.g. <span style="font-weight: bold;">ug_vertical_gradient_level</span> = <span style="font-style: italic;">-500.0</span>, <span style="font-style: italic;">-1000.0</span>.<br> </td>
 </tr> <tr> <td style="vertical-align: top;">
 <p><a name="ug_vertical_gradient_level"></a><span style="font-weight: bold;">ug_vertical_gradient_level</span></p>
@@ -1880,8 +1952,7 @@
 gradient defined by <a href="#ug_vertical_gradient">ug_vertical_gradient</a>
 is effective (in m).<br> <br>
-The height levels are to be assigned in ascending order. For the
+The height levels have to be assigned in ascending order. For the
 piecewise construction of a profile of the u-component of the
-geostrophic wind component (ug) see <a href="#ug_vertical_gradient">ug_vertical_gradient</a>.<br>
-</td> </tr> <tr> <td style="vertical-align: top;"> <p><a name="ups_limit_e"></a><b>ups_limit_e</b></p>
+geostrophic wind component (ug) see <a href="#ug_vertical_gradient">ug_vertical_gradient</a>.<br><br><span style="font-weight: bold;">Attention:</span><br>In case of ocean runs&nbsp;(see <a href="chapter_4.1.html#ocean">ocean</a>), the (negative) height levels have to be assigned in descending order.</td> </tr> <tr> <td style="vertical-align: top;"> <p><a name="ups_limit_e"></a><b>ups_limit_e</b></p>
 </td> <td style="vertical-align: top;">R</td>
 <td style="vertical-align: top;"><i>0.0</i></td>
@@ -2063,5 +2134,8 @@
 if possible (see <a href="#galilei_transformation">galilei_transformation</a>),
 in order to obtain larger
-time steps.</td> </tr> <tr> <td style="vertical-align: top;"> <p><a name="vg_vertical_gradient"></a><span style="font-weight: bold;">vg_vertical_gradient</span></p>
+time steps.<br><br><span style="font-weight: bold;">Attention:</span><br>In case of ocean runs (see <a href="chapter_4.1.html#ocean">ocean</a>),
+this parameter gives the velocity value at the sea surface, which is
+at k=nzt. The profile is then constructed from the surface down to the
+bottom of the model.</td> </tr> <tr> <td style="vertical-align: top;"> <p><a name="vg_vertical_gradient"></a><span style="font-weight: bold;">vg_vertical_gradient</span></p>
 </td> <td style="vertical-align: top;">R(10)<br>
 </td> <td style="vertical-align: top;"><span style="font-style: italic;">10
@@ -2081,5 +2155,8 @@
 =
 0.0) can be assigned. The surface
-geostrophic wind is assigned by <a href="#vg_surface">vg_surface</a>.</td>
+geostrophic wind is assigned by <a href="#vg_surface">vg_surface</a>.<br><br><span style="font-weight: bold;">Attention:</span><br>In case of ocean runs (see <a href="chapter_4.1.html#ocean">ocean</a>),
+the profile is constructed like described above, but starting from the
+sea surface (k=nzt) down to the bottom boundary of the model. Height
+levels have then to be given as negative values, e.g. <span style="font-weight: bold;">vg_vertical_gradient_level</span> = <span style="font-style: italic;">-500.0</span>, <span style="font-style: italic;">-1000.0</span>.</td>
 </tr> <tr> <td style="vertical-align: top;">
 <p><a name="vg_vertical_gradient_level"></a><span style="font-weight: bold;">vg_vertical_gradient_level</span></p>
@@ -2089,7 +2166,7 @@
 gradient defined by <a href="#vg_vertical_gradient">vg_vertical_gradient</a>
 is effective (in m).<br> <br>
-The height levels are to be assigned in ascending order. For the
+The height levels have to be assigned in ascending order. For the
 piecewise construction of a profile of the v-component of the
-geostrophic wind component (vg) see <a href="#vg_vertical_gradient">vg_vertical_gradient</a>.</td>
+geostrophic wind component (vg) see <a href="#vg_vertical_gradient">vg_vertical_gradient</a>.<br><br><span style="font-weight: bold;">Attention:</span><br>In case of ocean runs&nbsp;(see <a href="chapter_4.1.html#ocean">ocean</a>), the (negative) height levels have to be assigned in descending order.</td>
 </tr> <tr> <td style="vertical-align: top;">
 <p><a name="wall_adjustment"></a><b>wall_adjustment</b></p>
