P1673: LWG review 2023/11/06 (Kona) and follow-ons
Resuming from [linalg.alg.blas2.trsv], where we stopped last time (2023/10/25).
Done, either in the main branch or in PR #426
[x] Generally, we need to qualify use of forward as std::forward. Change throughout.
[x] Replace multiplyable with multipliable throughout. (Fix spelling.)
[x] Fix parallel algorithms "element access function" wording in [algorithms.parallel.defns] 3, by adding "or mdspan types" after "iterators": "All operations of the categories of the iterators or mdspan types that the algorithm is instantiated with."
[x] Add BinaryDivideOp to the list in [algorithms.parallel.user] (Requirements on user-provided function objects).
[x] Generally, say "y may alias x" instead of "x and y may alias." This is consistent with the definition of "alias" in the front matter. Generally, "out-argument may alias in-argument." (PR #426)
[x] Change label xmm to xxmm. (DONE)
[x] When passing an ExecutionPolicy exec into Effects-equivalent-to code, always use std::forward<ExecutionPolicy>(exec).
[x] Fix matrix_rank_1_update* to use inout matrix as intended. Wording is wrong!
[x] Change the updating wording to use $C'$ instead of relying on [linalg.general] 1.4. "Computes a matrix $C'$ such that $C' = C + \alpha A A^T$ and assigns each element of $C'$ to the corresponding element of $C$. Do this generally, e.g., for triangular_matrix_vector_product.
[x] Change linalg.alg.blas3.* stable names to linalg.algs.blas3.*.
[x] Fix stable names for BLAS 2 rank-1 symmetric and Hermitian updates.
[x] For symmetric_matrix_rank_k_update and hermitian_matrix_rank_k_update, change the template parameter name InMat1 to InMat, because there's no InMat2. Fix this in the synopsis as well.
[x] Fix everything under transposed (e.g., layout_transposed) to match wording of existing layouts. Remove references to the padded layouts.
[x] Fix layout_blas_packed analogously.
[x] Remove editorial comments and italics from [linalg.reqs.val].
[x] For [linalg.algs.reqs] Para 1, avoid ambiguity by changing "type requirements" to "Constraints." However, the first (1.1) is more than just a Constraint, so separate (1.1) to the top, and add the Constraint that ExecutionPolicy is an execution policy. (This indicates that the algorithm is a parallel algorithm.)
[x] Verify that the wording up front explains that ill-formed constructions (e.g., x and y complex, A real for hermitian rank-2 update) are forbidden (you may find an overload, but instantiating it would fail -- it's a precondition). (linalg.reqs.alg] expresses this for plus, times, etc. How about for complex number operations?) (See LWG question below.)
Check with LWG
[x] For [linalg.algs.reqs] Para 1 (changing "type requirements" to "Constraints"; see above): Fixed by changing "type requirements" to "Constraints." Added the Constraint that ExecutionPolicy is an execution policy. Removed the requirement that the algorithms that take ExecutionPolicy are parallel algorithms, because that would be circular with [algorithms.parallel] 2 ("A parallel algorithm is a function template listed in this document with a template parameter named ExecutionPolicy").
[ ] For [mdspan.layout.policy.reqmts], it's not clear whether this says that MP::mapping<E> must be valid for ANY specialization E of extents. That was not our intent. Should we add a Note or just add clarifying normative language? (The latter would probably not break existing user code, unless users are somehow depending on generic code being able to take any layout MP and any extents specialization E, and get MP::mapping<E> from it.) This matters for P1673 because layout_transposed::mapping<E> requires that E have rank 2.
Christian asked some LWG people; they said we might want to add a Note, but the wording itself permits this.
[ ] Remove constraint that stride(r) requires rank 2? Note that stride in layout_left and layout_right impose a Constraint that rank() > 0, but layout_stride only has this as a precondition.
[ ] Rename layout_transpose to layout_transposed?
Resolved (don't need to check with LWG)
[x] Verify that the wording up front explains that ill-formed constructions (e.g., x and y complex, A real for hermitian rank-2 update) are forbidden (you may find an overload, but instantiating it would fail -- it's a precondition). (linalg.reqs.alg] expresses this for plus, times, etc. How about for complex number operations?)
We think [linalg.helpers.conj] partly covers this.
conj-if-needed(E) only evaluates to conj(E) if conj(E) is a valid expression and the type of E is not an arithmetic type. Otherwise, it evaluates to E.
If conj(E) is a valid expression but "the function selected by overload resolution does not return the complex conjugate of its input, the program is ill-formed, no diagnostic required."
The main question is whether conj(E) is a linear algebra value type.
Ditto for the few algorithms that use real and imag.
We don't need to ask this question.
Points for specific sections
[linalg.alg.blas2.trsv]
("take an x parameter" cannot be misread as "take a symbolic name of a parameter x"; "take a parameter x" can be misread in that way. Therefore, we prefer the existing wording, "take an x parameter.") (OK)
Para 6: "Computes a vector $x'$ such that..." (instead of just saying "Computes $x'$ ..."). (This permits nonunique $x'$.) (DONE)
Para 12: "Computes a vector $x'$ such that" (instead of just saying "Computes $x'$ ..."), as above. (DONE)
Para 13: Complexity method differs from in Para 7. Flip order of b and A in Para 13 to be consistent with Para 7. (DONE)
[linalg.alg.blas2.rank1]
Para 7: Put forward<ExecutionPolicy> around exec. Generally do this where needed. (DONE)
Split Para 7 into two sentences, to avoid possible confusion due to code-font semicolons. (DONE)
[linalg.alg.blas2.symrank1]
Para 3: Mandates here does not follow the decltype convention; change that. (DONE)
(LWG appreciates the Para 1 unambiguous self-reference : - ) . ) (OK)
Para 7: "Computes a matrix $A'$..." instead of "Computes $A'$...." (DONE)
Para 11: "Computes a matrix $A'$..." instead of "Computes $A'$...." (DONE)
[linalg.algs.blas2.rank2]
Verify that the wording up front explains that ill-formed constructions (e.g., x and y complex, A real for hermitian rank-2 update) are forbidden (you may find an overload, but instantiating it would fail -- it's a precondition). (linalg.reqs.alg] expresses this for plus, times, etc. How about for complex number operations?) (DONE -- see question for LWG)
[linalg.algs.blas3.gemm]
Mandates: the above and also? (see notes)
Scribe missed some time
The in-place triangular_matrix_right_product etc. need a complexity clause. (DONE)
[linalg.alg.blas3.rankk]
Change label from linalg.alg to linalg.algs here. (DONE)
For symmetric_matrix_rank_k_update function signature, change InMat1 to InMat, because there's no InMat2. Fix this in the synopsis as well. (DONE)
Para 6: Change the updating wording to use $C'$ instead of relying on [linalg.general] 1.4. "Computes a matrix $C'$ such that $C' = C + \alpha A A^T$ and assigns each element of $C'$ to the corresponding element of $C$. Generally do that. It's OK to leave [linalg.general] 1.4, as it is still needed. (We'll need to fix in-place triangular_matrix_vector_product ("Computes $y = A y$"). (DONE)
For [linalg.algs.reqs] Para 1, does "type requirements" mean constraints? Yes, it does, to avoid ambiguity. Therefore, change "type requirements" to "Constraints." However, the first (1.1) is more than just a Constraint. We can separate (1.1) to the top, add the Constraint that ExecutionPolicy is an execution policy. (This indicates that the algorithm is a parallel algorithm.) (DONE)
P1673: LWG review 2023/11/06 (Kona) and follow-ons
Resuming from [linalg.alg.blas2.trsv], where we stopped last time (2023/10/25).
Done, either in the main branch or in PR #426
forward
asstd::forward
. Change throughout.multiplyable
withmultipliable
throughout. (Fix spelling.)mdspan
types" after "iterators": "All operations of the categories of the iterators ormdspan
types that the algorithm is instantiated with."BinaryDivideOp
to the list in [algorithms.parallel.user] (Requirements on user-provided function objects).y
may aliasx
" instead of "x
andy
may alias." This is consistent with the definition of "alias" in the front matter. Generally, "out-argument may alias in-argument." (PR #426)xmm
toxxmm
. (DONE)exec
into Effects-equivalent-to code, always usestd::forward<ExecutionPolicy>(exec)
.matrix_rank_1_update*
to use inout matrix as intended. Wording is wrong!triangular_matrix_vector_product
.linalg.alg.blas3.*
stable names tolinalg.algs.blas3.*
.symmetric_matrix_rank_k_update
andhermitian_matrix_rank_k_update
, change the template parameter nameInMat1
toInMat
, because there's noInMat2
. Fix this in the synopsis as well.transposed
(e.g.,layout_transposed
) to match wording of existing layouts. Remove references to the padded layouts.layout_blas_packed
analogously.Check with LWG
ExecutionPolicy
are parallel algorithms, because that would be circular with [algorithms.parallel] 2 ("A parallel algorithm is a function template listed in this document with a template parameter namedExecutionPolicy
").MP::mapping<E>
must be valid for ANY specializationE
ofextents
. That was not our intent. Should we add a Note or just add clarifying normative language? (The latter would probably not break existing user code, unless users are somehow depending on generic code being able to take any layoutMP
and anyextents
specializationE
, and getMP::mapping<E>
from it.) This matters for P1673 becauselayout_transposed::mapping<E>
requires thatE
have rank 2.stride(r)
requires rank 2? Note thatstride
inlayout_left
andlayout_right
impose a Constraint thatrank() > 0
, butlayout_stride
only has this as a precondition.layout_transpose
tolayout_transposed
?Resolved (don't need to check with LWG)
conj-if-needed(E)
only evaluates toconj(E)
ifconj(E)
is a valid expression and the type ofE
is not an arithmetic type. Otherwise, it evaluates toE
.conj(E)
is a valid expression but "the function selected by overload resolution does not return the complex conjugate of its input, the program is ill-formed, no diagnostic required."conj(E)
is a linear algebra value type.real
andimag
.Points for specific sections
[linalg.alg.blas2.trsv]
("take an
x
parameter" cannot be misread as "take a symbolic name of a parameterx
"; "take a parameterx
" can be misread in that way. Therefore, we prefer the existing wording, "take anx
parameter.") (OK)Para 6: "Computes a vector $x'$ such that..." (instead of just saying "Computes $x'$ ..."). (This permits nonunique $x'$.) (DONE)
Para 12: "Computes a vector $x'$ such that" (instead of just saying "Computes $x'$ ..."), as above. (DONE)
Para 13: Complexity method differs from in Para 7. Flip order of
b
andA
in Para 13 to be consistent with Para 7. (DONE)[linalg.alg.blas2.rank1]
Para 7: Put
forward<ExecutionPolicy>
aroundexec
. Generally do this where needed. (DONE)Split Para 7 into two sentences, to avoid possible confusion due to code-font semicolons. (DONE)
[linalg.alg.blas2.symrank1]
Para 3: Mandates here does not follow the
decltype
convention; change that. (DONE)(LWG appreciates the Para 1 unambiguous self-reference : - ) . ) (OK)
Para 7: "Computes a matrix $A'$..." instead of "Computes $A'$...." (DONE)
Para 11: "Computes a matrix $A'$..." instead of "Computes $A'$...." (DONE)
[linalg.algs.blas2.rank2]
Verify that the wording up front explains that ill-formed constructions (e.g., x and y complex, A real for hermitian rank-2 update) are forbidden (you may find an overload, but instantiating it would fail -- it's a precondition). (linalg.reqs.alg] expresses this for plus, times, etc. How about for complex number operations?) (DONE -- see question for LWG)
[linalg.algs.blas3.gemm]
Mandates: the above and also? (see notes)
Scribe missed some time
The in-place
triangular_matrix_right_product
etc. need a complexity clause. (DONE)[linalg.alg.blas3.rankk]
Change label from
linalg.alg
tolinalg.algs
here. (DONE)For
symmetric_matrix_rank_k_update
function signature, changeInMat1
toInMat
, because there's noInMat2
. Fix this in the synopsis as well. (DONE)Para 6: Change the updating wording to use $C'$ instead of relying on [linalg.general] 1.4. "Computes a matrix $C'$ such that $C' = C + \alpha A A^T$ and assigns each element of $C'$ to the corresponding element of $C$. Generally do that. It's OK to leave [linalg.general] 1.4, as it is still needed. (We'll need to fix in-place
triangular_matrix_vector_product
("Computes $y = A y$"). (DONE)For [linalg.algs.reqs] Para 1, does "type requirements" mean constraints? Yes, it does, to avoid ambiguity. Therefore, change "type requirements" to "Constraints." However, the first (1.1) is more than just a Constraint. We can separate (1.1) to the top, add the Constraint that
ExecutionPolicy
is an execution policy. (This indicates that the algorithm is a parallel algorithm.) (DONE)[linalg.alg.blas3.rank2k]
Change linalg.alg to linalg.algs. (DONE)
Fix Effects generally. (DONE)
For next time
Next starting point is BLAS 3 TRSM.