Review functional model calculation formulae

[ccrook]

The functional model specification includes formulae defining how the deformation model is to be calculated.

These need reviewing!

I have copied these to a Google doc to make it easier to comment on these. The document is at:

https://drive.google.com/file/d/1HCPmlwlwq5waYxDM6aH-8-2le4FrHOA4/view?usp=sharing

Currently this link permits adding comments, but not directly editing the document.

Comments could include simple corrections, suggestions for alternative or additional formulae and algorithms, changes to style, references to algorithm specifications (especially in other OGC standards), etc.

If you wish to edit directly please send me you email address (possibly only works for google accounts?) and I will add give you editing rights.

Alternatively you can download the document, or a section of it, edit it, and then upload the amended version to a new comment on this issue.

Looking forward to comments on this.

[ccrook]

@kevinmkelly highlighted (in an email) a potential confusion relating to the dimension of time functions. For some functions it appears that the dimension is time. For example the velocity function is defined as t - t₀ which appears to have dimension of time.

In fact the time functions all evaluate dimensionless scalar values. This is reflected in the specification by the statement "All date/time values such as calculation epoch, velocity reference epoch) are converted to decimal years for use in the following formulae."

The description at the beginning of the time function section has been amended to clarify that it defines a scalar value.

[ccrook]

NOTE: The formulation of time functions is currently being considered independently of this in #38. This may impact on the implementation of velocity and acceleration functions, the formulation of cyclic functions, and choosing between piecewise linear functions and combining multiple "ramp" base functions.

[ccrook]

Also relating to time functions, Chris Little has noted via email

On the scale of things, leap seconds certainly do not matter very much, but I think that, if defining decimal years in terms of (UTC as opposed to SI or TAI) seconds, perhaps you should mention that the number of seconds in a year, or part year, may not be known until a few months in advance, and therefore precise bit level reproduction of calculations may not be possible. At least this will stop some poor programmer or scientist agonising over a one or two second.

I propose that this be addressed in the discussion of formulate by noting that the formulae may introduce a potential 1 second inconsistency in converting between UTC time and decimal years depending on whether the leap seconds are added to a year after it has been used in calculations, and also on whether any relevant leap seconds have been incorporated into the software libraries used in the implementation of the deformation formulae. The documentation should note that implementation are considered compliant whether or not they account for leap seconds and that this implies potentially two insignificantly different correct solutions)

Can anyone suggest a better solution or wording (noting that we would prefer that implementors can use standard software libraries for time calculations provided by their development system).

[ccrook]

Jeff Freymueller comments via email (5 Jul 2021):

The notation t0 is used for the reference epoch in the velocity term, but also in the exponential and logarithmic terms. The issue there is that in general the t0 for the exponential or logarithmic terms will not be the same as for the velocity, so I think the non-linear starting times need to have a different name. Same thing for the step terms. It also should be made clear that multiple exponential or logarithmic terms are allowed, each with their own start time (multiple earthquakes with postseismic deformation, for example). The text does clearly say that you can add terms together, but it should be explicitly defined that there can be more than one t0_exp so that code to read the format expects to need an array of parameters for each kind of term.

This requires fixing in the documentation - it is not intended to imply that each base function uses the same "reference epoch". Perhaps a better parameter name for the event specific parameters would be startEpoch or startTime.

A hyperbolic tangent function has proven quite effective at modeling most slow slip events, so I’d suggest we simply add it in to the definition now. It basically just needs an amplitude, a center time (the function is ant-symmetric about its midpoint), and a time constant tau for the exponentials.

This sounds a very valuable additional time function.

[ccrook]

This issue is closed as it has been superseded by https://github.com/opengeospatial/CRS-Deformation-Models/issues/45 (which I have therefore repopened!)