Add EOS design document #191
Conversation
sbrus89
requested review from
mark-petersen,
mwarusz,
philipwjones and
vanroekel
|
|
||
| # Equation of State | ||
|
|
||
| ## 1 Overview The equation of state relates density to the prognostic state |
There was a problem hiding this comment.
start sentence on new line after the heading for proper formatting
| polynomial). | ||
|
|
||
| ### 2.3 Requirement: computational efficiency | ||
| The eos code should not be major computational bottleneck (criteria?) |
There was a problem hiding this comment.
Bottleneck is unrealistic. In every ocean model I've worked with, the EOS is one of the 2-3 top kernels and is always a bottleneck. TEOS-10 is even more expensive with a larger polynomial. Maybe something more like: As one of the most expensive kernels, the EOS must be as efficient as possible. Developers should be discouraged from calling the EOS too frequently.
| ### 2.6 Desired: freezing temperature calculation | ||
| Later versions should include calculating the freezing temperature of seawater. | ||
|
|
||
| ### 2.7 Desired: output in situ temperature |
There was a problem hiding this comment.
Is this really a function for the EOS?
There was a problem hiding this comment.
TEOS-10 broadly handles all the thermodynamic conversions associated with the Gibbs Free Energy. It is capable of, among other things, converting conservative temperature to in situ temperature. This is something we may likely need for surface coupling.
I think we are taking the broader view of the scope of the "EOS" adopted by TEOS-10 here, rather than just limiting ourselves to computing the density (or specific volume). In this broader view, the freezing point of seawater would also be part of the "EOS".
| (MPAS-Ocean, reanalysis, other models etc.) These functions may be used offline | ||
| in pre- or post-processing but need to be consistent with the EOS | ||
| implementation. | ||
|
|
There was a problem hiding this comment.
I believe we still have a requirement for adiabatically displaced density for the purposes of computing stability or Brunt-Vaisala freq. For stability, this is often from neighboring vertical layers. For mixed-layer models, we sometimes need surface-displaced densities.
| Omega. The GSW-C toolbox sub-module will serve as a baseline reference for our | ||
| ports in unit tests. | ||
|
|
||
| For flexibility in optimizing performance, calls to the EOS function should be |
There was a problem hiding this comment.
As mentioned above, I suspect we want to restrict computing density to one time per step and given the EOS complexity, probably won't be inlined or merged with other kernels. Guess we shouldn't design it out, but the preference would be whole-array if there are any compromises associated with the single-cell support.
| }; | ||
| ``` | ||
|
|
||
| Any function that depends on the EOS will be a template: |
There was a problem hiding this comment.
Similarly here - not sure we need a templated class based on EOS type.
| } | ||
| ``` | ||
|
|
||
| Functions that depend on the EOS will be called as follows: |
There was a problem hiding this comment.
EOS choice should be encapsulated in the class and not exposed external to the EOS. I would prefer a single EOS interface with this choice/conditional embedded inside rather than exposed to external calling routines.
|
|
||
| ### 2.8 Desired: output first derivatives | ||
| The EOS will need to be able to produce alpha and beta (drho/dT and drho/dS) | ||
| for linear expansions in the higher-order pressure gradient. |
There was a problem hiding this comment.
and for some mixing parameterizations.
| Later versions should include a check on the range of ocean properties to | ||
| assess use of TEOS-10 (equivalent to the ``ocean funnel'' check). | ||
|
|
||
| ### 2.10 Desired: check value range |
There was a problem hiding this comment.
duplicate heading - replace with input conversion?
|
|
||
| ### 2.9 Desired: check value range | ||
| Later versions should include a check on the range of ocean properties to | ||
| assess use of TEOS-10 (equivalent to the ``ocean funnel'' check). |
There was a problem hiding this comment.
This is really a hard requirement I think? If the input ocean model quantities exceed the valid range for the polynomial, the deviations can be quite extreme. And how do we want to treat out-of-range values that can unfortunately arise in a typical ocean simulation? In previous models, we have typically truncated the values to the valid range only for the purposes of the EOS calculation while leaving the values unchanged otherwise.
There was a problem hiding this comment.
btw, this requirement also makes the point-wise evaluation a little problematic. In prior implementations, it was often more efficient to do the range restriction as part of some pre-processing together with some other preparatory calculations before hitting the polynomial loop.
This PR adds a design document for the equation of state in OMEGA.
(Developed with @alicebarthel and @xylar with input from @mwarusz and @grnydawn.)
Checklist