From 6fb335c67f10f915dba1a46ee2ae71cc3e016e25 Mon Sep 17 00:00:00 2001 From: Aki Vehtari Date: Sun, 26 May 2024 20:11:10 +0300 Subject: [PATCH] add warning that inverse transfors may fail due to finite accuracy --- src/reference-manual/transforms.qmd | 27 +++++++++++++++++++++++++++ 1 file changed, 27 insertions(+) diff --git a/src/reference-manual/transforms.qmd b/src/reference-manual/transforms.qmd index 733f79491..679e589d9 100644 --- a/src/reference-manual/transforms.qmd +++ b/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}