Math functions: Clarified value ranges and NaN (#476)

* divide, ln, log, mod: Clarified behavior for 0 input / infinity results

* Trigonometric functions: Clarified that NaN is returned outside of their defined ranges and the output value range for some processes

* Clarified for various mathematical functions the defined input and output ranges. Mention that `NaN` is returned outside of the defined input range where possible.

* Remove NaN

Author: m-mohr

CHANGELOG.md

@@ -12,10 +12,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
+- Clarified for various mathematical functions the defined input and output ranges. Mention that `NaN` is returned outside of the defined input range where possible.
+- `divide`: Clarified behavior for division by 0
 - `between`: Clarify that `null` is passed through.
 - `eq` and `neq`: Explicitly set the minimum value for the `delta` parameter.
 - `filter_bbox`, `load_collection`, `load_stac`: Clarified that the bounding box is reprojected to the CRS of the spatial data cube dimensions if required.
 - `filter_spatial`: Clarified that masking is applied using the given geometries. [#469](https://github.com/Open-EO/openeo-processes/issues/469)
+- `mod`: Clarified behavior for y = 0
 - `sqrt`: Clarified that NaN is returned for negative numbers.
 
 ## [2.0.0-rc.1] - 2023-05-25

absolute.json

@@ -1,7 +1,7 @@
 {
     "id": "absolute",
     "summary": "Absolute value",
-    "description": "Computes the absolute value of a real number `x`, which is the \"unsigned\" portion of x and often denoted as *|x|*.\n\nThe no-data value `null` is passed through and therefore gets propagated.",
+    "description": "Computes the absolute value of a real number `x`, which is the \"unsigned\" portion of `x` and often denoted as *|x|*.\n\nThe no-data value `null` is passed through and therefore gets propagated.",
     "categories": [
         "math"
     ],
@@ -95,4 +95,4 @@
             "result": true
         }
     }
-}
+}

arccos.json

@@ -1,29 +1,32 @@
 {
     "id": "arccos",
     "summary": "Inverse cosine",
-    "description": "Computes the arc cosine of `x`. The arc cosine is the inverse function of the cosine so that *`arccos(cos(x)) = x`*.\n\nWorks on radians only.\nThe no-data value `null` is passed through and therefore gets propagated.",
+    "description": "Computes the arc cosine of `x`. The arc cosine is the inverse function of the cosine so that *`arccos(cos(x)) = x`*.\n\nWorks on radians only.\nThe no-data value `null` is passed through and therefore gets propagated. `NaN` is returned for values outside of the allowed range.",
     "categories": [
         "math > trigonometric"
     ],
     "parameters": [
         {
             "name": "x",
-            "description": "A number.",
+            "description": "A number in the range *[-1, 1]*.",
             "schema": {
                 "type": [
                     "number",
                     "null"
-                ]
+                ],
+                "minimum": -1,
+                "maximum": 1
             }
         }
     ],
     "returns": {
-        "description": "The computed angle in radians.",
+        "description": "The computed angle in radians in the range *[0, π]*.",
         "schema": {
             "type": [
                 "number",
                 "null"
-            ]
+            ],
+            "minimum": 0
         }
     },
     "examples": [
@@ -41,4 +44,4 @@
             "title": "Inverse cosine explained by Wolfram MathWorld"
         }
     ]
-}
+}

arcosh.json

@@ -1,29 +1,31 @@
 {
     "id": "arcosh",
     "summary": "Inverse hyperbolic cosine",
-    "description": "Computes the inverse hyperbolic cosine of `x`. It is the inverse function of the hyperbolic cosine so that *`arcosh(cosh(x)) = x`*.\n\nWorks on radians only.\nThe no-data value `null` is passed through and therefore gets propagated.",
+    "description": "Computes the inverse hyperbolic cosine of `x`. It is the inverse function of the hyperbolic cosine so that *`arcosh(cosh(x)) = x`*.\n\nThe no-data value `null` is passed through and therefore gets propagated. `NaN` is returned for values outside of the allowed range.",
     "categories": [
         "math > trigonometric"
     ],
     "parameters": [
         {
             "name": "x",
-            "description": "A number.",
+            "description": "A number in the range *[1, +∞)*.",
             "schema": {
                 "type": [
                     "number",
                     "null"
                 ]
-            }
+            },
+            "minimum": 1
         }
     ],
     "returns": {
-        "description": "The computed angle in radians.",
+        "description": "The computed hyperbolic angle in radians in the range *[0, +∞)*.",
         "schema": {
             "type": [
                 "number",
                 "null"
-            ]
+            ],
+            "minimum": 0
         }
     },
     "examples": [
@@ -41,4 +43,4 @@
             "title": "Inverse hyperbolic cosine explained by Wolfram MathWorld"
         }
     ]
-}
+}

arcsin.json

@@ -1,24 +1,26 @@
 {
     "id": "arcsin",
     "summary": "Inverse sine",
-    "description": "Computes the arc sine of `x`. The arc sine is the inverse function of the sine so that *`arcsin(sin(x)) = x`*.\n\nWorks on radians only.\nThe no-data value `null` is passed through and therefore gets propagated.",
+    "description": "Computes the arc sine of `x`. The arc sine is the inverse function of the sine so that *`arcsin(sin(x)) = x`*.\n\nWorks on radians only.\nThe no-data value `null` is passed through and therefore gets propagated. `NaN` is returned for values < -1 and > 1.",
     "categories": [
         "math > trigonometric"
     ],
     "parameters": [
         {
             "name": "x",
-            "description": "A number.",
+            "description": "A number in the range *[-1, 1]*.",
             "schema": {
                 "type": [
                     "number",
                     "null"
-                ]
+                ],
+                "minimum": -1,
+                "maximum": 1
             }
         }
     ],
     "returns": {
-        "description": "The computed angle in radians.",
+        "description": "The computed angle in radians in the range *[-π/2, π/2]*.",
         "schema": {
             "type": [
                 "number",
@@ -41,4 +43,4 @@
             "title": "Inverse sine explained by Wolfram MathWorld"
         }
     ]
-}
+}

arctan.json

@@ -18,7 +18,7 @@
         }
     ],
     "returns": {
-        "description": "The computed angle in radians.",
+        "description": "The computed angle in radians in the range *(−π/2, π/2)*.",
         "schema": {
             "type": [
                 "number",
@@ -41,4 +41,4 @@
             "title": "Inverse tangent explained by Wolfram MathWorld"
         }
     ]
-}
+}

arsinh.json

@@ -1,7 +1,7 @@
 {
     "id": "arsinh",
     "summary": "Inverse hyperbolic sine",
-    "description": "Computes the inverse hyperbolic sine of `x`. It is the inverse function of the hyperbolic sine so that *`arsinh(sinh(x)) = x`*.\n\nWorks on radians only.\nThe no-data value `null` is passed through and therefore gets propagated.",
+    "description": "Computes the inverse hyperbolic sine of `x`. It is the inverse function of the hyperbolic sine so that *`arsinh(sinh(x)) = x`*.\n\nThe no-data value `null` is passed through and therefore gets propagated.",
     "categories": [
         "math > trigonometric"
     ],
@@ -18,7 +18,7 @@
         }
     ],
     "returns": {
-        "description": "The computed angle in radians.",
+        "description": "The computed hyperbolic angle in radians.",
         "schema": {
             "type": [
                 "number",
@@ -41,4 +41,4 @@
             "title": "Inverse hyperbolic sine explained by Wolfram MathWorld"
         }
     ]
-}
+}

artanh.json

@@ -1,24 +1,26 @@
 {
     "id": "artanh",
     "summary": "Inverse hyperbolic tangent",
-    "description": "Computes the inverse hyperbolic tangent of `x`. It is the inverse function of the hyperbolic tangent so that *`artanh(tanh(x)) = x`*.\n\nWorks on radians only.\nThe no-data value `null` is passed through and therefore gets propagated.",
+    "description": "Computes the inverse hyperbolic tangent of `x`. It is the inverse function of the hyperbolic tangent so that *`artanh(tanh(x)) = x`*.\n\nThe no-data value `null` is passed through and therefore gets propagated. `NaN` is returned for values outside of the allowed range. The computations follow [IEEE Standard 754](https://ieeexplore.ieee.org/document/8766229) whenever the processing environment supports it. Therefore, `x` = 1 results in +infinity and `x` = 0 results in -infinity. Otherwise, an exception is thrown.",
     "categories": [
         "math > trigonometric"
     ],
     "parameters": [
         {
             "name": "x",
-            "description": "A number.",
+            "description": "A number in the range *(-1, 1)*.",
             "schema": {
                 "type": [
                     "number",
                     "null"
-                ]
+                ],
+                "minimumExclusive": -1,
+                "maximumExclusive": 1
             }
         }
     ],
     "returns": {
-        "description": "The computed angle in radians.",
+        "description": "The computed hyperbolic angle in radians.",
         "schema": {
             "type": [
                 "number",
@@ -39,6 +41,11 @@
             "rel": "about",
             "href": "http://mathworld.wolfram.com/InverseHyperbolicTangent.html",
             "title": "Inverse hyperbolic tangent explained by Wolfram MathWorld"
+        },
+        {
+            "rel": "about",
+            "href": "https://ieeexplore.ieee.org/document/4610935",
+            "title": "IEEE Standard 754-2008 for Floating-Point Arithmetic"
         }
     ]
-}
+}

cos.json

@@ -18,12 +18,14 @@
         }
     ],
     "returns": {
-        "description": "The computed cosine of `x`.",
+        "description": "The computed cosine in the range *[-1, 1]*.",
         "schema": {
             "type": [
                 "number",
                 "null"
-            ]
+            ],
+            "minimum": -1,
+            "maximum": 1
         }
     },
     "examples": [
@@ -41,4 +43,4 @@
             "title": "Cosine explained by Wolfram MathWorld"
         }
     ]
-}
+}

cosh.json

@@ -1,14 +1,14 @@
 {
     "id": "cosh",
     "summary": "Hyperbolic cosine",
-    "description": "Computes the hyperbolic cosine of `x`.\n\nWorks on radians only.\nThe no-data value `null` is passed through and therefore gets propagated.",
+    "description": "Computes the hyperbolic cosine of `x`.\n\nThe no-data value `null` is passed through and therefore gets propagated.",
     "categories": [
         "math > trigonometric"
     ],
     "parameters": [
         {
             "name": "x",
-            "description": "An angle in radians.",
+            "description": "An hyperbolic angle in radians.",
             "schema": {
                 "type": [
                     "number",
@@ -18,12 +18,13 @@
         }
     ],
     "returns": {
-        "description": "The computed hyperbolic cosine of `x`.",
+        "description": "The computed hyperbolic cosine in the range *[1, +∞)*.",
         "schema": {
             "type": [
                 "number",
                 "null"
-            ]
+            ],
+            "minimum": 1
         }
     },
     "examples": [
@@ -41,4 +42,4 @@
             "title": "Hyperbolic cosine explained by Wolfram MathWorld"
         }
     ]
-}
+}

divide.json

@@ -1,7 +1,7 @@
 {
     "id": "divide",
     "summary": "Division of two numbers",
-    "description": "Divides argument `x` by the argument `y` (*`x / y`*) and returns the computed result.\n\nNo-data values are taken into account so that `null` is returned if any element is such a value.\n\nThe computations follow [IEEE Standard 754](https://ieeexplore.ieee.org/document/8766229) whenever the processing environment supports it. Therefore, a division by zero results in ±infinity if the processing environment supports it. Otherwise, a `DivisionByZero` exception must the thrown.",
+    "description": "Divides argument `x` by the argument `y` (*`x / y`*) and returns the computed result.\n\nNo-data values are taken into account so that `null` is returned if any element is such a value.\n\nThe computations follow [IEEE Standard 754](https://ieeexplore.ieee.org/document/8766229) whenever the processing environment supports it. A division by zero results in:\n\n- +infinity for `x` > 0,\n- -infinity for `x` < 0,\n- `NaN` for `x` = 0,\n- or otherwise, throws a `DivisionByZero` exception if the other options are not supported by the processing environment.",
     "categories": [
         "math"
     ],
@@ -76,4 +76,4 @@
             "title": "IEEE Standard 754-2019 for Floating-Point Arithmetic"
         }
     ]
-}
+}

exp.json

@@ -18,12 +18,13 @@
         }
     ],
     "returns": {
-        "description": "The computed value for *e* raised to the power of `p`.",
+        "description": "The computed value for *e* raised to the power of `p`. Value is in the range of *(0, +∞)*",
         "schema": {
             "type": [
                 "number",
                 "null"
-            ]
+            ],
+            "minimumExclusive": 0
         }
     },
     "examples": [
@@ -65,4 +66,4 @@
             "result": true
         }
     }
-}
+}

ln.json

@@ -1,19 +1,20 @@
 {
     "id": "ln",
     "summary": "Natural logarithm",
-    "description": "The natural logarithm is the logarithm to the base *e* of the number `x`, which equals to using the *log* process with the base set to *e*. The natural logarithm is the inverse function of taking *e* to the power x.\n\nThe no-data value `null` is passed through.\n\nThe computations follow [IEEE Standard 754](https://ieeexplore.ieee.org/document/8766229) whenever the processing environment supports it. Therefore, *`ln(0)`* results in ±infinity if the processing environment supports it or otherwise an exception is thrown.",
+    "description": "The natural logarithm is the logarithm to the base *e* of the number `x`, which equals to using the *log* process with the base set to *e*. The natural logarithm is the inverse function of taking *e* to the power x.\n\nThe no-data value `null` is passed through.\n\nThe computations follow [IEEE Standard 754](https://ieeexplore.ieee.org/document/8766229) whenever the processing environment supports it. Therefore, *`ln(0)`* results in -infinity if the processing environment supports it or otherwise an exception is thrown. `NaN` is returned for values outside of the allowed range.",
     "categories": [
         "math > exponential & logarithmic"
     ],
     "parameters": [
         {
             "name": "x",
-            "description": "A number to compute the natural logarithm for.",
+            "description": "A number to compute the natural logarithm for in the range *[0, +∞)*.",
             "schema": {
                 "type": [
                     "number",
                     "null"
-                ]
+                ],
+                "minimum": 0
             }
         }
     ],
@@ -64,4 +65,4 @@
             "result": true
         }
     }
-}
+}