New issue from Mark Hoemmen: "Fix Mandates, Preconditions, and Complexity elements of [linalg] algorithms"

Author: Dani-Hub

xml/issue4137.xml

@@ -0,0 +1,349 @@
+<?xml version='1.0' encoding='utf-8' standalone='no'?>
+<!DOCTYPE issue SYSTEM "lwg-issue.dtd">
+
+<issue num="4137" status="New">
+<title>Fix <i>Mandates</i>, <i>Preconditions</i>, and <i>Complexity</i> elements of [linalg] algorithms</title>
+<section><sref ref="[linalg.algs.blas2]"/><sref ref="[linalg.algs.blas3]"/></section>
+<submitter>Mark Hoemmen</submitter>
+<date>08 Aug 2024</date>
+<priority>99</priority>
+
+<discussion>
+<p>
+As <a href="https://github.com/ORNL/cpp-proposals-pub/issues/464">pointed out by Raffaele Solcà</a> 
+(CSCS Swiss National Supercomputing Centre), some of the <i>Mandates</i>, <i>Preconditions</i>, and 
+<i>Complexity</i> elements of some BLAS 2 and BLAS 3 algorithms in [linalg] are incorrect.
+</p>
+</discussion>
+
+<resolution>
+<p>
+This wording is relative to <paper num="N4988"/>.
+</p>
+
+<ol>
+
+<li><p>Modify <sref ref="[linalg.algs.blas2.gemv]"/> as indicated:</p>
+
+<blockquote class="note">
+<p>
+[<i>Drafting note</i>: This change is needed because the matrix <tt>A</tt> does not need to be square. 
+<tt>x.extents(0)</tt> must equal <tt>A.extents(1)</tt>, while <tt>y.extents(0)</tt> must equal 
+<tt>A.extents(0)</tt>.]
+</p>
+</blockquote>
+
+<blockquote>
+<p>
+-3- <i>Mandates</i>:
+</p>
+<ol style="list-style-type: none">
+<li><p>(3.1) &mdash; <tt><i>possibly-multipliable</i>&lt;decltype(A), decltype(x), decltype(y)&gt;()</tt> 
+is <tt>true</tt>, and</p></li>
+<li><p>(3.2) &mdash; <tt><i>possibly-addable</i>&lt;decltype(<ins>y</ins><del>x</del>), decltype(y), 
+decltype(z)&gt;()</tt> is <tt>true</tt> for those overloads that take a <tt>z</tt> parameter.</p></li>
+</ol>
+<p>
+-4- <i>Preconditions</i>:
+</p>
+<ol style="list-style-type: none">
+<li><p>(4.1) &mdash; <tt><i>multipliable</i>(A, x, y)</tt> is <tt>true</tt>, and</p></li>
+<li><p>(4.2) &mdash; <tt><i>addable</i>(<ins>y</ins><del>x</del>, y, z)</tt> is <tt>true</tt> 
+for those overloads that take a <tt>z</tt> parameter.</p></li>
+</ol>
+<p>
+-5- <i>Complexity</i>: &#x1d4aa;(<tt><ins>A</ins><del>x</del>.extent(0)</tt> × 
+<tt><ins>x</ins><del>A</del>.extent(<ins>0</ins><del>1</del>)</tt>).
+</p>
+</blockquote>
+
+</li>
+
+<li><p>Modify <sref ref="[linalg.algs.blas2.symv]"/> as indicated:</p>
+
+<blockquote>
+<p>
+-3- <i>Mandates</i>:
+</p>
+<ol style="list-style-type: none">
+<li><p>(3.1) &mdash; [&hellip;]</p></li>
+<li><p>(3.2) &mdash; [&hellip;]</p></li>
+<li><p>(3.3) &mdash; <tt><i>possibly-multipliable</i>&lt;decltype(A), decltype(x), decltype(y)&gt;()</tt> 
+is <tt>true</tt>, and</p></li>
+<li><p>(3.4) &mdash; <tt><i>possibly-addable</i>&lt;decltype(<ins>y</ins><del>x</del>), decltype(y), 
+decltype(z)&gt;()</tt> is <tt>true</tt> for those overloads that take a <tt>z</tt> parameter.</p></li>
+</ol>
+<p>
+-4- <i>Preconditions</i>:
+</p>
+<ol style="list-style-type: none">
+<li><p>(4.1) &mdash; <tt>A.extent(0)</tt> equals <tt>A.extent(1)</tt>,</p></li>
+<li><p>(4.2) &mdash; <tt><i>multipliable</i>(A, x, y)</tt> is <tt>true</tt>, and</p></li>
+<li><p>(4.3) &mdash; <tt><i>addable</i>(<ins>y</ins><del>x</del>, y, z)</tt> is <tt>true</tt> 
+for those overloads that take a <tt>z</tt> parameter.</p></li>
+</ol>
+<p>
+-5- <i>Complexity</i>: &#x1d4aa;(<tt><ins>A</ins><del>x</del>.extent(0)</tt> × 
+<tt><ins>x</ins><del>A</del>.extent(<ins>0</ins><del>1</del>)</tt>).
+</p>
+</blockquote>
+
+</li>
+
+<li><p>Modify <sref ref="[linalg.algs.blas2.hemv]"/> as indicated:</p>
+
+<blockquote>
+<p>
+-3- <i>Mandates</i>:
+</p>
+<ol style="list-style-type: none">
+<li><p>(3.1) &mdash; [&hellip;]</p></li>
+<li><p>(3.2) &mdash; [&hellip;]</p></li>
+<li><p>(3.3) &mdash; <tt><i>possibly-multipliable</i>&lt;decltype(A), decltype(x), decltype(y)&gt;()</tt> 
+is <tt>true</tt>, and</p></li>
+<li><p>(3.4) &mdash; <tt><i>possibly-addable</i>&lt;decltype(<ins>y</ins><del>x</del>), decltype(y), 
+decltype(z)&gt;()</tt> is <tt>true</tt> for those overloads that take a <tt>z</tt> parameter.</p></li>
+</ol>
+<p>
+-4- <i>Preconditions</i>:
+</p>
+<ol style="list-style-type: none">
+<li><p>(4.1) &mdash; <tt>A.extent(0)</tt> equals <tt>A.extent(1)</tt>,</p></li>
+<li><p>(4.2) &mdash; <tt><i>multipliable</i>(A, x, y)</tt> is <tt>true</tt>, and</p></li>
+<li><p>(4.3) &mdash; <tt><i>addable</i>(<ins>y</ins><del>x</del>, y, z)</tt> is <tt>true</tt> 
+for those overloads that take a <tt>z</tt> parameter.</p></li>
+</ol>
+<p>
+-5- <i>Complexity</i>: &#x1d4aa;(<tt><ins>A</ins><del>x</del>.extent(0)</tt> × 
+<tt><ins>x</ins><del>A</del>.extent(<ins>0</ins><del>1</del>)</tt>).
+</p>
+</blockquote>
+
+</li>
+
+<li><p>Modify <sref ref="[linalg.algs.blas2.trmv]"/> as indicated:</p>
+
+<blockquote class="note">
+<p>
+[<i>Drafting note</i>: The extents compatibility conditions are expressed differently than in the 
+above matrix-vector multiply sections, perhaps more for consistency with the TRSV section below. 
+They look correct here. The original <i>Complexity</i> elements adjusted below are technically correct, 
+since <math><mi>A</mi></math> is square, but changing this would improve consistency with 
+<sref ref="[linalg.algs.blas2.gemv]"/>]
+</p>
+</blockquote>
+
+<blockquote>
+<pre>
+template&lt;<i>in-matrix</i> InMat, class Triangle, class DiagonalStorage, <i>in-vector</i> InVec,
+         <i>out-vector</i> OutVec&gt;
+  void triangular_matrix_vector_product(InMat A, Triangle t, DiagonalStorage d, InVec x, OutVec y);
+template&lt;class ExecutionPolicy,
+         <i>in-matrix</i> InMat, class Triangle, class DiagonalStorage, <i>in-vector</i> InVec,
+         <i>out-vector</i> OutVec&gt;
+  void triangular_matrix_vector_product(ExecutionPolicy&amp;&amp; exec,
+                                        InMat A, Triangle t, DiagonalStorage d, InVec x, OutVec y);
+</pre>
+<blockquote>
+<p>
+-5- [&hellip;]
+<p/>
+-6- <i>Effects</i>: Computes <math><mi>y</mi> <mo>=</mo> <mi>A</mi><mi>x</mi></math>.
+<p/>
+-5- <i>Complexity</i>: &#x1d4aa;(<tt><ins>A</ins><del>x</del>.extent(0)</tt> × 
+<tt><ins>x</ins><del>A</del>.extent(<ins>0</ins><del>1</del>)</tt>).
+</p>
+</blockquote>
+<pre>
+template&lt;<i>in-matrix</i> InMat, class Triangle, class DiagonalStorage, <i>inout-vector</i> InOutVec&gt;
+  void triangular_matrix_vector_product(InMat A, Triangle t, DiagonalStorage d, InOutVec y);
+template&lt;class ExecutionPolicy,
+         <i>in-matrix</i> InMat, class Triangle, class DiagonalStorage, <i>inout-vector</i> InOutVec&gt;
+  void triangular_matrix_vector_product(ExecutionPolicy&amp;&amp; exec,
+                                        InMat A, Triangle t, DiagonalStorage d, InOutVec y);
+</pre>
+<blockquote>
+<p>
+-8- [&hellip;]
+<p/>
+-9- <i>Effects</i>: [&hellip;]
+<p/>
+-10- <i>Complexity</i>: &#x1d4aa;(<tt><ins>A</ins><del>y</del>.extent(0)</tt> × 
+<tt><ins>y</ins><del>A</del>.extent(<ins>0</ins><del>1</del>)</tt>).
+</p>
+</blockquote>
+<pre>
+template&lt;<i>in-matrix</i> InMat, class Triangle, class DiagonalStorage, 
+         <i>in-vector</i> InVec1, <i>in-vector</i> InVec2, <i>out-vector</i> OutVec&gt;
+  void triangular_matrix_vector_product(InMat A, Triangle t, DiagonalStorage d,
+                                        InVec1 x, InVec2 y, OutVec z);
+template&lt;class ExecutionPolicy,
+         <i>in-matrix</i> InMat, class Triangle, class DiagonalStorage, 
+         <i>in-vector</i> InVec1, <i>in-vector</i> InVec2, <i>out-vector</i> OutVec&gt;
+  void triangular_matrix_vector_product(ExecutionPolicy&amp;&amp; exec,
+                                        InMat A, Triangle t, DiagonalStorage d,
+                                        InVec1 x, InVec2 y, OutVec z);
+</pre>
+<blockquote>
+<p>
+-11- [&hellip;]
+<p/>
+-12- <i>Effects</i>: Computes <math><mi>z</mi> <mo>=</mo> <mi>y</mi> <mo>+</mo> <mi>A</mi><mi>x</mi></math>.
+<p/>
+-13- <i>Complexity</i>: &#x1d4aa;(<tt><ins>A</ins><del>x</del>.extent(0)</tt> × 
+<tt><ins>x</ins><del>A</del>.extent(<ins>0</ins><del>1</del>)</tt>).
+</p>
+</blockquote>
+</blockquote>
+
+</li>
+
+<li><p>Modify <sref ref="[linalg.algs.blas3.rankk]"/> as indicated:</p>
+
+<blockquote class="note">
+<p>
+[<i>Drafting note</i>: <paper num="P3371R0"/>, to be submitted in the August 15 mailing for 
+LEWG review, contains the same wording changes to <sref ref="[linalg.algs.blas3.rankk]"/> 
+and <sref ref="[linalg.algs.blas3.rank2k]"/> as proposed here, with additional changes 
+corresponding to that proposal. Please apply this LWG issue's changes first, before P3371 merges]
+</p>
+</blockquote>
+
+<blockquote>
+<p>
+-3- <i>Mandates</i>:
+</p>
+<ol style="list-style-type: none">
+<li><p>(3.1) &mdash; If <tt>InOutMat</tt> has <tt>layout_blas_packed</tt> layout, then the 
+layout's <tt>Triangle</tt> template argument has the same type as the function's 
+<tt>Triangle</tt> template argument; <ins>and</ins></p></li>
+<li><p>(3.2) &mdash; <tt><ins><i>possibly-multipliable</i>&lt;decltype(A),
+decltype(transposed(A)), decltype(C)&gt;</ins> <del><i>compatible-static-extents</i>&lt;decltype(A), 
+decltype(A)&gt;(0, 1)</del></tt> is <tt>true</tt><ins>.</ins><del>;</del></p></li>
+<li><p><del>(3.3) &mdash; <tt><i>compatible-static-extents</i>&lt;decltype(C), decltype(C)&gt;(0, 1)</tt> 
+is <tt>true</tt>; and</del></p></li>
+<li><p><del>(3.4) &mdash; <tt><i>compatible-static-extents</i>&lt;decltype(A), decltype(C)&gt;(0, 0)</tt> 
+is <tt>true</tt>.</del></p></li>
+</ol>
+<p>
+-4- <i>Preconditions</i>: <ins><tt><i>multipliable</i>(A, transposed(A), C)</tt> is <tt>true</tt>.</ins>
+</p>
+<ol style="list-style-type: none">
+<li><p><del>(4.1) &mdash; <tt>A.extent(0)</tt> equals <tt>A.extent(1)</tt>,</del></p></li>
+<li><p><del>(4.2) &mdash; <tt>C.extent(0)</tt> equals <tt>C.extent(1)</tt>, and</del></p></li>
+<li><p><del>(4.3) &mdash; <tt>A.extent(0)</tt> equals <tt>C.extent(0)</tt>.</del></p></li>
+</ol>
+<p>
+-5- <i>Complexity</i>: &#x1d4aa;(<tt>A.extent(0)</tt> × <tt>A.extent(1)</tt> × <tt><ins>A</ins><del>C</del>.extent(0)</tt>).
+</p>
+</blockquote>
+
+</li>
+
+<li><p>Modify <sref ref="[linalg.algs.blas3.rank2k]"/> as indicated:</p>
+
+<blockquote>
+<p>
+-3- <i>Mandates</i>:
+</p>
+<ol style="list-style-type: none">
+<li><p>(3.1) &mdash; If <tt>InOutMat</tt> has <tt>layout_blas_packed</tt> layout, then the 
+layout's <tt>Triangle</tt> template argument has the same type as the function's 
+<tt>Triangle</tt> template argument;</p></li>
+<li><p>(3.2) &mdash; <tt><ins><i>possibly-multipliable</i>&lt;decltype(A),
+decltype(transposed(B)), decltype(C)&gt;()</ins> <del><i>possibly-addable</i>&lt;decltype(A), 
+decltype(B), decltype(C)&gt;()</del></tt> 
+is <tt>true</tt>; and</p></li>
+<li><p>(3.3) &mdash; <tt><ins><i>possibly-multipliable</i>&lt;decltype(B),
+decltype(transposed(A)), decltype(C)&gt;(0, 1)</ins> <del><i>compatible-static-extents</i>&lt;decltype(A), 
+decltype(A)&gt;(0, 1)</del></tt> is <tt>true</tt>.</p></li>
+</ol>
+<p>
+-4- <i>Preconditions</i>:
+</p>
+<ol style="list-style-type: none">
+<li><p>(4.1) &mdash; <tt><ins><i>multipliable</i>(A, transposed(B), C)</ins>
+<del><i>addable</i>(A, B, C)</del></tt> is <tt>true</tt>, and</p></li>
+<li><p>(4.2) &mdash; <ins><tt><i>multipliable</i>(B, transposed(A), C)</tt> is <tt>true</tt></ins>
+<del><tt>A.extent(0)</tt> equals <tt>A.extent(1)</tt></del>.</p></li>
+</ol>
+<p>
+-5- <i>Complexity</i>: &#x1d4aa;(<tt>A.extent(0)</tt> × <tt>A.extent(1)</tt> × <tt><ins>B</ins><del>C</del>.extent(0)</tt>).
+</p>
+</blockquote>
+
+</li>
+
+<li><p>Modify <sref ref="[linalg.algs.blas3.trsm]"/> as indicated:</p>
+
+<blockquote class="note">
+<p>
+[<i>Drafting note</i>: Nothing is wrong here, but it's nice to make the complexity clauses depend 
+only on input if possible]
+</p>
+</blockquote>
+
+<blockquote>
+<pre>
+template&lt;<i>in-matrix</i> InMat1, class Triangle, class DiagonalStorage,
+         <i>in-matrix</i> InMat2, <i>out-matrix</i> OutMat, class BinaryDivideOp>
+  void triangular_matrix_matrix_left_solve(InMat1 A, Triangle t, DiagonalStorage d,
+                                           InMat2 B, OutMat X, BinaryDivideOp divide);
+template&lt;class ExecutionPolicy,
+         <i>in-matrix</i> InMat1, class Triangle, class DiagonalStorage,
+         <i>in-matrix</i> InMat2, <i>out-matrix</i> OutMat, class BinaryDivideOp>
+  void triangular_matrix_matrix_left_solve(ExecutionPolicy&amp;&amp; exec,
+                                           InMat1 A, Triangle t, DiagonalStorage d,
+                                           InMat2 B, OutMat X, BinaryDivideOp divide);
+</pre>
+<blockquote>
+<p>
+[&hellip;]
+<p/>
+-6- <i>Complexity</i>: &#x1d4aa;(<tt>A.extent(0)</tt> × <tt><ins>B</ins><del>X</del>.extent(1)</tt> × <tt><ins>B</ins><del>X</del>.extent(1)</tt>).
+</p>
+</blockquote>
+
+</blockquote>
+
+</li>
+
+
+<li><p>Modify <sref ref="[linalg.algs.blas3.inplacetrsm]"/> as indicated:</p>
+
+<blockquote class="note">
+<p>
+[<i>Drafting note</i>: Nothing is wrong here, but it's nice to make the complexity clauses depend 
+only on input if possible]
+</p>
+</blockquote>
+
+<blockquote>
+<pre>
+template&lt;<i>in-matrix</i> InMat, class Triangle, class DiagonalStorage,
+         <i>inout-matrix</i> InOutMat, class BinaryDivideOp>
+  void triangular_matrix_matrix_right_solve(InMat A, Triangle t, DiagonalStorage d,
+                                           InOutMat B, BinaryDivideOp divide);
+template&lt;class ExecutionPolicy,
+         <i>in-matrix</i> InMat, class Triangle, class DiagonalStorage,
+         <i>inout-matrix</i> InOutMat, class BinaryDivideOp>
+  void triangular_matrix_matrix_right_solve(ExecutionPolicy&amp;&amp; exec,
+                                           InMat A, Triangle t, DiagonalStorage d,
+                                           InOutMat B, BinaryDivideOp divide);
+</pre>
+<blockquote>
+<p>
+[&hellip;]
+<p/>
+-13- <i>Complexity</i>: &#x1d4aa;(<tt><ins>B</ins><del>A</del>.extent(0)</tt> × 
+<tt>A.extent(<ins>0</ins><del>1</del>)</tt> × <tt><ins>A</ins><del>B</del>.extent(1)</tt>).
+</p>
+</blockquote>
+
+</blockquote>
+
+</li>
+</ol>
+</resolution>
+
+</issue>