From f3a28e43355b0f439fb99a2210bd497ca59c8003 Mon Sep 17 00:00:00 2001
From: Stanley Tsang <stanley.tsang@amd.com>
Date: Tue, 23 Apr 2024 16:06:33 -0600
Subject: [PATCH] Adding bitwise reproducibility documentation (#403)

* Adding bitwise reproducibility documentation

* fix typo

* Change wording

* Grammar fix

* Add notes to individual function documentation
---
 docs/bitwise-repro.rst  | 16 ++++++++++++++++
 docs/index.rst          |  1 +
 docs/sphinx/_toc.yml.in |  1 +
 thrust/reduce.h         | 12 ++++++++++++
 thrust/transform_scan.h |  8 ++++++++
 5 files changed, 38 insertions(+)
 create mode 100644 docs/bitwise-repro.rst

diff --git a/docs/bitwise-repro.rst b/docs/bitwise-repro.rst
new file mode 100644
index 000000000..f2007449b
--- /dev/null
+++ b/docs/bitwise-repro.rst
@@ -0,0 +1,16 @@
+.. meta::
+  :description: rocThrust documentation and API reference
+  :keywords: rocThrust, ROCm, API, reference, data type, support
+  
+.. _bitwise-repro:
+
+******************************************
+Bitwise reproducibility
+******************************************
+
+With the exception of the following functions, all rocThrust API functions are bitwise reproducible.  That is, given identical inputs, the function will return the exact same result in repeated invocations.
+
+* scan (inclusive & exclusive)
+* scan_by_key (inclusive & exclusive)
+* reduce_by_key
+* transform_scan
diff --git a/docs/index.rst b/docs/index.rst
index 1a56aefb5..bf7454ed1 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -24,6 +24,7 @@ The documentation is structured as follows:
   .. grid-item-card:: API reference
 
     * :ref:`data-type-support`
+    * :ref:`bitwise-repro`
     * :ref:`api-reference`
     * :ref:`genindex`
 
diff --git a/docs/sphinx/_toc.yml.in b/docs/sphinx/_toc.yml.in
index b3c936fa7..d55000a1c 100644
--- a/docs/sphinx/_toc.yml.in
+++ b/docs/sphinx/_toc.yml.in
@@ -12,6 +12,7 @@ subtrees:
 - caption: API reference
   entries:
   - file: data-type-support
+  - file: bitwise-repro
   - file: cpp_api
 
 - caption: About
diff --git a/thrust/reduce.h b/thrust/reduce.h
index c7b378f72..cd3d00a72 100644
--- a/thrust/reduce.h
+++ b/thrust/reduce.h
@@ -351,6 +351,8 @@ template<typename InputIterator,
  *  This version of \p reduce_by_key uses the function object \c equal_to
  *  to test for equality and \c plus to reduce values with equal keys.
  *
+ *  Results from this function may vary from run to run depending on the inputs provided.
+ *
  *  The algorithm's execution is parallelized as determined by \p exec.
  *
  *  \param exec The execution policy to use for parallelization.
@@ -421,6 +423,8 @@ __host__ __device__
  *  This version of \p reduce_by_key uses the function object \c equal_to
  *  to test for equality and \c plus to reduce values with equal keys.
  *
+ *  Results from this function may vary from run to run depending on the inputs provided.
+ *
  *  \param keys_first The beginning of the input key range.
  *  \param keys_last  The end of the input key range.
  *  \param values_first The beginning of the input value range.
@@ -482,6 +486,8 @@ template<typename InputIterator1,
  *  This version of \p reduce_by_key uses the function object \c binary_pred
  *  to test for equality and \c plus to reduce values with equal keys.
  *
+ *  Results from this function may vary from run to run depending on the inputs provided.
+ *
  *  The algorithm's execution is parallelized as determined by \p exec.
  *
  *  \param exec The execution policy to use for parallelization.
@@ -557,6 +563,8 @@ __host__ __device__
  *  This version of \p reduce_by_key uses the function object \c binary_pred
  *  to test for equality and \c plus to reduce values with equal keys.
  *
+ *  Results from this function may vary from run to run depending on the inputs provided.
+ *
  *  \param keys_first The beginning of the input key range.
  *  \param keys_last  The end of the input key range.
  *  \param values_first The beginning of the input value range.
@@ -626,6 +634,8 @@ template<typename InputIterator1,
  *  This version of \p reduce_by_key uses the function object \c binary_pred
  *  to test for equality and \c binary_op to reduce values with equal keys.
  *
+ *  Results from this function may vary from run to run depending on the inputs provided.
+ *
  *  The algorithm's execution is parallelized as determined by \p exec.
  *
  *  \param exec The execution policy to use for parallelization.
@@ -710,6 +720,8 @@ __host__ __device__
  *  This version of \p reduce_by_key uses the function object \c binary_pred
  *  to test for equality and \c binary_op to reduce values with equal keys.
  *
+ *  Results from this function may vary from run to run depending on the inputs provided.
+ *
  *  \param keys_first The beginning of the input key range.
  *  \param keys_last  The end of the input key range.
  *  \param values_first The beginning of the input value range.
diff --git a/thrust/transform_scan.h b/thrust/transform_scan.h
index 6c0fe8116..4b86c0081 100644
--- a/thrust/transform_scan.h
+++ b/thrust/transform_scan.h
@@ -51,6 +51,8 @@ THRUST_NAMESPACE_BEGIN
  *  assigned to <tt>\*(result + 1)</tt>, and so on.  The transform scan
  *  operation is permitted to be in-place.
  *
+ *  Results from this function may vary from run to run depending on the inputs provided.
+ *
  *  The algorithm's execution is parallelized as determined by \p exec.
  *
  *  \param exec The execution policy to use for parallelization.
@@ -121,6 +123,8 @@ __host__ __device__
  *  assigned to <tt>\*(result + 1)</tt>, and so on.  The transform scan
  *  operation is permitted to be in-place.
  *
+ *  Results from this function may vary from run to run depending on the inputs provided.
+ *
  *  \param first The beginning of the input sequence.
  *  \param last The end of the input sequence.
  *  \param result The beginning of the output sequence.
@@ -181,6 +185,8 @@ template<typename InputIterator,
  *  to <tt>\*(result + 1)</tt>, and so on.  The transform scan operation is 
  *  permitted to be in-place.
  *
+ *  Results from this function may vary from run to run depending on the inputs provided.
+ *
  *  The algorithm's execution is parallelized as determined by \p exec.
  *
  *  \param exec The execution policy to use for parallelization.
@@ -255,6 +261,8 @@ __host__ __device__
  *  to <tt>\*(result + 1)</tt>, and so on.  The transform scan operation is 
  *  permitted to be in-place.
  *
+ *  Results from this function may vary from run to run depending on the inputs provided.
+ *
  *  \param first The beginning of the input sequence.
  *  \param last The end of the input sequence.
  *  \param result The beginning of the output sequence.