Two new dimensionless vertical coordinate specifications for s coordinate ocean models

[rsignell]

1. Title

Two new dimensionless vertical coordinates to support ocean models

2. Moderator

Rich Signell

3. Requirement

The ocean modeling community needs two additional vertical coordinate specifications to allow modern s-coordinate model output to be CF-compliant and allow more general specification of s-coordinate model output for future development.

4. Initial Statement of Technical Proposal

The existing ocean_s_coordinate dimensionless vertical coordinate specification in CF is limited to a specific vertical stretching function and set of control parameters, while modern versions of ROMS allow for more flexible specification. Additional of these two new generalized vertical coordinate specifications would allow output from existing ROMS-derived models (and other s coordinate models) to be CF-compliant, as well as allowing more flexibility for future s_coordinate model developers and users to write and read CF-compliant model output.

Here are the proposed additions to Appendix D. Dimensionless Vertical Coordinates

Ocean s-coordinate, generic form 1

   standard_name = "ocean_s_coordinate_g1"

Definition:

   z(n,k,j,i) = S(k,j,i) + eta(n,j,i) * (1 + S(k,j,i) / depth(j,i))

    where S(k,j,i) = depth_c * s(k) + (depth(j,i) - depth_c) * C(k)

and where z(n,k,j,i) is the height, positive upwards, relative to ocean datum (e.g. mean sea level) at gridpoint (n,k,j,i); eta(n,j,i) is the height of the ocean surface, positive upwards, relative to ocean datum at gridpoint (n,j,i); s(k) is the dimensionless coordinate at vertical gridpoint (k) with a range of -1 <= s(k) <= 0, s(0) corresponds to eta(n,j,i) whereas s(-1) corresponds to depth(j,i); C(k) is the dimensionless vertical coordinate stretching function at gridpoint (k) with a range of -1 <= C(k) <= 0, C(0) corresponds to eta(n,j,i) whereas C(-1) corresponds to depth(j,i); and the constant depth_c, (positive value), is a critical depth controlling the stretching.

The format for the formula_terms attribute is

formula_terms = "s: var1 C: var2 eta: var3 depth: var4 depth_c: var5"

Ocean s-coordinate, generic form 2

   standard_name = "ocean_s_coordinate_g2"

Definition:

   z(n,k,j,i) = eta(n,j,i) + (eta(n,j,i) + depth(j,i)) * S(k,j,i)

    where S(k,j,i) = (depth_c * s(k) + depth(j,i) * C(k)) / (depth_c + depth(j,i))

and where z(n,k,j,i) is the height, positive upwards, relative to ocean datum (e.g. mean sea level) at gridpoint (n,k,j,i); eta(n,j,i) is the height of the ocean surface, positive upwards, relative to ocean datum at gridpoint (n,j,i); s(k) is the dimensionless coordinate at vertical gridpoint (k) with a range of -1 <= s(k) <= 0, s(0) corresponds to eta(n,j,i) whereas s(-1) corresponds to depth(j,i); C(k) is the dimensionless vertical coordinate stretching function at gridpoint (k) with a range of -1 <= C(k) <= 0, C(0) corresponds to eta(n,j,i) whereas C(-1) correspond to depth(j,i); and the constant depth_c, (positive value) is a critical depth controlling the stretching.

The format for the formula_terms attribute is

formula_terms = "s: var1 C: var2 eta: var3 depth: var4 depth_c: var5"

5. Benefits

The oceanographic community, especially those producing or consuming products from s coordinate models (e.g. variants and derivatives of the Regional Ocean Modeling System (ROMS)) would benefit from the addition of these two new dimensionless vertical coordinate specifications. These two new coordinates have been exercised in the Unidata Common Data Model and the Unidata NetCDF-Java Library for the last two years. It's time to add them officially to the CF Conventions.

6. Status Quo

The only option currently to store modern ROMS results as CF compliant would be to write the entire Z field as a 4D array.

[rsignell]

Summary: There have been no comments on this proposal since I posted it one month ago, so there don't appear to be any issues.

The next step according to: ​http://cf-pcmdi.llnl.gov/governance/governance-rules is to provide an example dataset and wait 3 more weeks. So here is an example dataset, and with links to visualization in the IDV (to prove that this specification is already working correctly in Unidata's NetCDF-Java and in the Unidata Integrated Data Viewer:

Example dataset: May be obtained via OPeNDAP or HTTPServer server download at this location: ​http://geoport.whoi.edu/thredds/catalog/examples/catalog.html?dataset=examples/coawst_g1.nc (e.g. wget ​http://geoport.whoi.edu/thredds/fileServer/examples/coawst_g1.nc)

Example 3D view of the temperature field from dataset above in Unidata's Integrated Data Viewer (​http://www.unidata.ucar.edu/software/idv/), showing that the new vertical coordinate specification is being correctly represented: ​https://docs.google.com/open?id=0BzAHlPEEP_ujUE5zcG03VkVLY1k

If you want to test yourself, download the IDV, download the bundle URL below, and load this bundle in IDV: ​https://docs.google.com/open?id=0BzAHlPEEP_ujaDZnWGIwampJckU This bundle accesses the OPeNDAP link, so you don't need to download the NetCDF file to visualize the data in IDV.

• Rich Signell

[jonathan]

Dear Rich

Thanks for this proposal. It needs a moderator, and according to the rules it needs at least three people in favour of it. I'm happy to support it in principle, and it would be good to hear from others in support.

I have some comments, though. Apologies for being slow: I was on holiday. I don't follow the description of the formulae. By "s(0)" do you mean "s=0", and similarly for other conditions? It appears that s and C must be linked in some way; you get eta, for instance, by imposing conditions on both s and C. Would it be better, therefore, to state them as simultaneous conditions, rather than describing the conditions for s and C separately? Having said that, it have to admit that I may have misunderstood it completely. If s=0 and C=0 in the first case, for example, then S=0 and z=eta/depth, not eta. What have I done wrong? Or perhaps that is what is supposed to happen? If so, maybe you could start by saying that the resulting coordinate is a fraction of the local depth.

Thanks

Jonathan

[rsignell]

Jonathan, Yes, s(0) means "at s = 0", and s(-1) means "at s = -1". Both "s" and "C" are functions that have a valid_range [-1,0]. "s" has uniform spacing with values determined by the number of layers and the position of the variable within the layer. For example, if the model has 5 layers, the "w" vertical velocity component (and other variables located at the interfaces between the layers) will have a vertical coordinate "s" variable with values [-1.0 -0.8 -0.6 -0.4 -0.2 -0.0]. The "u" and "v" horizontal velocity components (and other variables located in the middle of the layers) will have a different "s" variable with values [-0.9 -0.7 -0.5 -0.3 -0.1]. The "C" function, meanwhile, is free to be any monotonic function with values in the range [-1.0 0], and is used to control the stretching (more resolution near the surface, near the bottom, etc). I have made a plot of these functions for the test file I provided at: ​http://www.screencast.com/t/2nodlugvo

Based on this information, can you suggest language for the CF conventions doc that would make this more clear to you (and others)?

-Rich

[rsignell]

Jonathan, You mentioned that I needed a moderator for this ticket. I have been playing the role of moderator for this ticket because it seems like the natural thing to do, and don't want to bug others to do a job that I feel I should be doing myself.

Reading the rules again at: ​http://cf-pcmdi.llnl.gov/governance/governance-rules it doesn't seem to explicitly exclude the proposer from being the moderator as well. The important thing, it would seem is to reconcile the differences of opinion enough to get at least three folks to support for it, including at least two members of the conventions committee. Do you (or others) see this the same way, or do you feel it's important that the proposer be barred from the moderator role?

[russ]

I support the proposal. If an alternate moderator is needed, I also volunteer to serve in that role.

[jonathan]

Dear Rich

Thanks for your explanations. To avoid my initial misunderstandings, I would say:

where z(n,k,j,i) is the height, positive upwards, relative to ocean datum (e.g. mean sea level) at gridpoint (n,k,j,i); eta(n,j,i) is the height of the ocean surface, positive upwards, relative to ocean datum at gridpoint (n,j,i); depth(j,i) is the distance from ocean datum to sea floor (positive value) at gridpoint (j,i); s(k) is the dimensionless coordinate at vertical gridpoint (k); C(k) is the dimensionless vertical coordinate stretching function at gridpoint (k); and the constant depth_c, (positive value), is a critical depth controlling the stretching. s(k) and C(k) are both monotonic functions of k in the range -1 to 0; both s and C equal -1 at the sea floor, where z=depth, and both equal 0 at the sea surface, where z=eta. At intermediate depths their values are unrelated.

It's the same words in both cases, isn't it, but different formulae. The above isn't very different from what you said, and I hope it's correct.

This proposal also implies that two new standard_names are needed (for the two new types of s coordinate). I suggest it would be helpful to propose those to the email list, as otherwise they might not get picked up.

I note that the datum is not defined, and the same formulae might be applied to eta and depth wrt geoid or wrt mean sea level, for example. I suppose that is OK. The standard_names of the components would distinguish the datum, but it would depend on software that computed the dimensional coordinate using it in a way which was consistent with the datum.

Regarding moderators, that's probably a subject for a different ticket. You are right, the rules don't say that the proposer can't be the moderator, but I've always assumed it, as it seems good practice to me. It can be hard to be completely objective about one's own proposal. That is absolutely not a comment on your conduct of this ticket!

Best wishes

Jonathan

[rsignell]

Jonathan, As per your suggestion, I'll submit these vertical coordinate standard names "ocean_s_coordinate_g1" and "ocean_s_coordinate_g2" to the standard_name list. And your suggestioned rewording of the description is fine with me. So here is my modified proposal with rewording:

Proposed additions to: Appendix D. Dimensionless Vertical Coordinates

Ocean s-coordinate, generic form 1

   standard_name = "ocean_s_coordinate_g1"

Definition:

   z(n,k,j,i) = S(k,j,i) + eta(n,j,i) * (1 + S(k,j,i) / depth(j,i))

    where S(k,j,i) = depth_c * s(k) + (depth(j,i) - depth_c) * C(k)

and where z(n,k,j,i) is the height, positive upwards, relative to ocean datum (e.g. mean sea level) at gridpoint (n,k,j,i); eta(n,j,i) is the height of the ocean surface, positive upwards, relative to ocean datum at gridpoint (n,j,i); depth(j,i) is the distance from ocean datum to sea floor (positive value) at gridpoint (j,i); s(k) is the dimensionless coordinate at vertical gridpoint (k); C(k) is the dimensionless vertical coordinate stretching function at gridpoint (k); and the constant depth_c, (positive value), is a critical depth controlling the stretching. s(k) and C(k) are both monotonic functions of k in the range -1 to 0; both s and C equal -1 at the sea floor, where z=depth, and both equal 0 at the sea surface, where z=eta. At intermediate depths their values are unrelated.

The format for the formula_terms attribute is

formula_terms = "s: var1 C: var2 eta: var3 depth: var4 depth_c: var5"

Ocean s-coordinate, generic form 2

   standard_name = "ocean_s_coordinate_g2"

Definition:

   z(n,k,j,i) = eta(n,j,i) + (eta(n,j,i) + depth(j,i)) * S(k,j,i)

    where S(k,j,i) = (depth_c * s(k) + depth(j,i) * C(k)) / (depth_c + depth(j,i))

and where z(n,k,j,i) is the height, positive upwards, relative to ocean datum (e.g. mean sea level) at gridpoint (n,k,j,i); eta(n,j,i) is the height of the ocean surface, positive upwards, relative to ocean datum at gridpoint (n,j,i); depth(j,i) is the distance from ocean datum to sea floor (positive value) at gridpoint (j,i); s(k) is the dimensionless coordinate at vertical gridpoint (k); C(k) is the dimensionless vertical coordinate stretching function at gridpoint (k); and the constant depth_c, (positive value), is a critical depth controlling the stretching. s(k) and C(k) are both monotonic functions of k in the range -1 to 0; both s and C equal -1 at the sea floor, where z=depth, and both equal 0 at the sea surface, where z=eta. At intermediate depths their values are unrelated.

The format for the formula_terms attribute is

formula_terms = "s: var1 C: var2 eta: var3 depth: var4 depth_c: var5"

[jonathan]

Since Rich, Russ and I support this and no-one has commented for more than three weeks, I think we can conclude that this proposal is accepted (regardless of who is the moderator!). It should therefore be included in the next version of CF. Rich is already named as an author of CF. Thanks, Rich.

Jonathan

[markh]

closed by ​https://github.com/cf-convention/cf-conventions/pull/62