Update usage.rst (MITgcm#252)

* Update usage.rst * Update usage.rst * address atmospheric configurations
fraserwg · Mar 2, 2021 · 1324448 · 1324448
1 parent 26fa060
commit 1324448
Showing 1 changed file with 14 additions and 4 deletions.
diff --git a/doc/usage.rst b/doc/usage.rst
@@ -152,9 +152,9 @@ standard names have been assigned according to `CF Conventions`_.
 +----------------------+---------------------------------------+
 | YG                   | latitude_at_f_location                |
 +----------------------+---------------------------------------+
-| Zl                   | depth_at_upper_w_location             |
+| Zl                   | depth_at_lower_w_location             |
 +----------------------+---------------------------------------+
-| Zu                   | depth_at_lower_w_location             |
+| Zu                   | depth_at_upper_w_location             |
 +----------------------+---------------------------------------+
 | Z                    | depth                                 |
 +----------------------+---------------------------------------+
@@ -206,9 +206,9 @@ conventions. These logical spatial dimensions are
 +------+----------------------------------+------+-------------------+
 | k    | z_grid_index                     | Z    |                   |
 +------+----------------------------------+------+-------------------+
-| k_u  | z_grid_index_at_lower_w_location | Z    | -0.5              |
+| k_l  | z_grid_index_at_lower_w_location | Z    | -0.5              |
 +------+----------------------------------+------+-------------------+
-| k_l  | z_grid_index_at_upper_w_location | Z    | 0.5               |
+| k_u  | z_grid_index_at_upper_w_location | Z    | 0.5               |
 +------+----------------------------------+------+-------------------+
 | k_p1 | z_grid_index_at_w_location       | Z    | (-0.5, 0.5)       |
 +------+----------------------------------+------+-------------------+
@@ -233,6 +233,16 @@ xarray_ distinguishes between "coordinates" and "data_vars". By default,
 this behavior and treat grid variables as data_vars, use
 ``grid_vars_to_coords=False``.
 
+.. warning::
+   For vertical coordinates (``Zl``, ``k_l``, etc.) the notion of "lower" and
+   "upper" always refers to the *logical* grid position, NOT the *physical* grid position.
+   This can be a major point of confusion. In array index space, the point ``k_l``
+   is indeed lower than ``k_u``; however, for typical MITgcm ocean model configurations,
+   in physical space the point ``k_l`` is physically *above* ``k_u``. This is because, 
+   the Z axis starts from the ocean surface and increases downward.
+   In contrast, for atmospheric configurations which start from the ground and increase upwards,
+   the logical and physical positions are self-consistent.
+
 Time
 ----