Merge pull request #786 from stan-dev/transforms-and-finite-accuracy

add warning that inverse transforms may fail due to finite accuracy

src/reference-manual/transforms.qmd

@@ -25,6 +25,33 @@ parameters defined in the program.  The C++ classes also include
 code to transform the parameters from unconstrained to constrained and
 apply the appropriate Jacobians.
 
+## Limitations due to finite accuracy presentation
+
+In this section the transformations are described mathematically.
+There are two cases where the observed behavior can be different from
+the exact arithmetic:
+  - Stan’s arithmetic is implemented using double-precision
+    floating-point arithmetic, which may cause computation to behave
+    differently than mathematics. For example, lower bound constraint
+    is defined with logarithm constraint which mathematically excludes
+    the lower bound, but if the closest floating-point number for the
+    inverse transformed value is the boundary, then the value is
+    rounded to the boundary. This may cause unexpected warnings or
+    errors, if in other parts of the code the boundary value is
+    invalid. For example, we may observe floating-point value 0 for
+    a variance parameter that has been declared to be larger than 0. 
+	See more about [Floating point Arithmetic in Stan user's guide](../stan-users-guide/floating-point.qmd)).
+  - CmdStan stores the output to CSV files with 6 significant digits
+    accuracy by default, but the constraints are checked with 8
+    decimal digit accuracy. Due to this, there can be errors if CSV
+    output is further used, for example, to run generated
+    quantities. For example, simplex constraint requires the values to
+    sum up to 1, but when writing the values to CSV they are rounded
+    to 6 significant digits and the sum of those rounded values can be
+    smaller or larger than 1 by more than 8 decimal digits. The
+    solution for CmdStan is to increase the number of significant
+    digits stored as discussed in [CmdStan Command-Line Interface
+    Overview](../cmdstan-guide/command_line_options.qmd).
 
 ## Changes of variables {#change-of-variables.section}