The issue submitter improves the issue discussion and adds proposed wording

Author: Dani-Hub

xml/issue4315.xml

@@ -13,50 +13,117 @@
 
 <discussion>
 <p>
-The wording for `vector_two_norm` <sref ref="[linalg.algs.blas1.nrm2]"/> and
-`matrix_frob_norm` <sref ref="[linalg.algs.blas1.matfrobnorm]"/> has two issues.
+The Returns clauses `vector_two_norm` <sref ref="[linalg.algs.blas1.nrm2]"/> and
+`matrix_frob_norm` <sref ref="[linalg.algs.blas1.matfrobnorm]"/> say that the
+functions return the "square root" of the sum of squares of the initial value and 
+the absolute values of the elements of the input `mdspan`. However, nowhere in 
+<sref ref="[linalg]"/> explains how to compute a square root.
 </p>
 <ol>
-<li><p>Their <i>Returns</i> clauses say that the functions return the "square
-root" of the sum of squares of the initial value and the absolute
-values of the elements of the input `mdspan`. However, nowhere in
-<sref ref="[linalg]"/> explains how to compute a square root.</p>
-<ol style="list-style-type: none">
-<li><p>1.a. The input `mdspan`'s `value_type` and the initial value type
-are not constrained in a way that would ensure that calling
-`std::sqrt` on this expression would be well-formed.</p></li>
-<li><p>1.b. There is no provision to find `sqrt` via argument-dependent
-lookup, even though <sref ref="[linalg]"/> has provisions to find `abs`, `conj`,
-`real`, and `imag` via argument-dependent lookup.  There is no
-"`sqrt-if-needed`" analog to `abs-if-needed`, `conj-if-needed`,
-`real-if-needed`, and `imag-if-needed`.</p></li>
-</ol>
-</li>
-<li><p>The overloads that take an initial value parameter `Scalar init`
-return `Scalar`.</p>
-<ol style="list-style-type: none">
-<li><p>2.a. This may silently lose information if the function uses
-`std::sqrt` to compute square roots. For example, if `Scalar` and the
-input `mdspan`'s `value_type` are both `int`, the square root computed
-via `std::sqrt` would return `double`. However, `vector_two_norm` and
-`matrix_frob_norm` returning `Scalar` would force a rounding
-conversion back to `int`.</p></li>
-</ol>
-</li>
+<li><p>The input `mdspan`'s `value_type` and the initial value type are
+not constrained in a way that would ensure that calling `std::sqrt` on
+this expression would be well-formed.</p></li>
+<li><p>There is no provision to find `sqrt` via argument-dependent lookup,
+even though [linalg] has provisions to find `abs`, `conj`, `real`, and
+`imag` via argument-dependent lookup.  There is no "`sqrt-if-needed`"
+analog to `abs-if-needed`, `conj-if-needed`, `real-if-needed`, and
+`imag-if-needed`.</p></li>
 </ol>
 <p>
-<b>Suggested fix:</b>
-<p/>
-The easiest fix for both issues is just to <i>Constrain</i> both `Scalar` and
+The easiest fix for both issues is just to Constrain both `Scalar` and
 the input `mdspan`'s `value_type` to be floating-point numbers or
 specializations of `std::complex` for these two functions. This
-presumes that relaxing this <i>Constraint</i> and fixing the above two issues
+presumes that relaxing this Constraint and fixing the above two issues
 later would be a non-breaking change. If that is <em>not</em> the case, then
 I would suggest removing the two functions entirely.
 </p>
 </discussion>
 
 <resolution>
+<p>
+This wording is relative to <paper num="N5014"/>.
+</p>
+
+<blockquote class="note">
+<p>
+[<i>Drafting note:</i> As a drive-by fix the proposed wording adds a missing closing parentheses in 
+<sref ref="[linalg.algs.blas1.nrm2]"/> p2.]
+</p>
+</blockquote>
+
+<ol>
+
+<li><p>Modify <sref ref="[linalg.algs.blas1.nrm2]"/> as indicated:</p>
+
+<blockquote>
+<pre>
+template&lt;<i>in-vector</i> InVec, class Scalar&gt;
+  Scalar vector_two_norm(InVec v, Scalar init);
+template&lt;class ExecutionPolicy, <i>in-vector</i> InVec, class Scalar&gt;
+  Scalar vector_two_norm(ExecutionPolicy&amp;&amp; exec, InVec v, Scalar init);
+</pre>
+<blockquote>
+<p>
+-1- [<i>Note 1</i>: [&hellip;] &mdash; <i>end note</i>]
+<p/>
+<ins>-?- <i>Constraints</i>: `InVec::value_type` and `Scalar` are either a floating-point type, or
+a specialization of `complex`.</ins>
+<p/>
+-2- <i>Mandates</i>: Let `a` be <tt><i>abs-if-needed</i>(declval&lt;typename InVec::value_type&gt;())</tt>. 
+Then, <tt>decltype(init + a * a<ins>)</ins></tt> is convertible to `Scalar`.
+<p/>
+-3- <i>Returns</i>: The square root of the sum of the square of `init` and the squares of the 
+absolute values of the elements of `v`.
+<p/>
+[<i>Note 2</i>: For `init` equal to zero, this is the Euclidean norm (also called 2-norm) of the vector 
+`v`. &mdash; <i>end note</i>]
+<p/>
+-4- <i>Remarks</i>: If <del>`InVec::value_type`, and `Scalar` are all floating-point types or specializations of `complex`,
+and if</del> `Scalar` has higher precision than `InVec::value_type`, then intermediate terms in the sum use
+`Scalar`'s precision or greater.
+<p/>
+[<i>Note 3</i>: An implementation of this function for floating-point types `T` can use the `scaled_sum_of_squares`
+result `from vector_sum_of_squares(x, {.scaling_factor=1.0, .scaled_sum_of_squares=init})`. &mdash; <i>end note</i>]
+</p>
+</blockquote>
+</blockquote>
+
+</li>
+
+<li><p>Modify <sref ref="[linalg.algs.blas1.matfrobnorm]"/> as indicated:</p>
+
+<blockquote>
+<pre>
+template&lt;<i>in-matrix</i> InMat, class Scalar&gt;
+  Scalar matrix_frob_norm(InMat A, Scalar init);
+template&lt;class ExecutionPolicy, <i>in-matrix</i> InMat, class Scalar&gt;
+  Scalar matrix_frob_norm(ExecutionPolicy&amp;&amp; exec, InMat A, Scalar init);
+</pre>
+<blockquote>
+<p>
+<ins>-?- <i>Constraints</i>: `InVec::value_type` and `Scalar` are either a floating-point type, or
+a specialization of `complex`.</ins>
+<p/>
+-2- <i>Mandates</i>: Let `a` be <tt><i>abs-if-needed</i>(declval&lt;typename InMat::value_type&gt;())</tt>. 
+Then, <tt>decltype(init + a * a)</tt> is convertible to `Scalar`.
+<p/>
+-3- <i>Returns</i>: The square root of the sum of squares of `init` and the absolute values 
+of the elements of `A`.
+<p/>
+[<i>Note 2</i>: For `init` equal to zero, this is the Frobenius norm of the matrix `A`. &mdash; <i>end note</i>]
+<p/>
+-4- <i>Remarks</i>: If <del>`InMat::value_type` and `Scalar` are all floating-point types or specializations of 
+`complex`, and if</del> `Scalar` has higher precision than `InMat::value_type`, then intermediate terms in the 
+sum use `Scalar`'s precision or greater.
+</p>
+<blockquote><pre>
+</pre></blockquote>
+</blockquote>
+</blockquote>
+
+</li>
+
+</ol>
 </resolution>
 
 </issue>