linalg : matrix_frob_normを追加 (#1233)

Signed-off-by: Yuya Asano <64895419+sukeya@users.noreply.github.com>

Author: sukeya

reference/linalg.md

@@ -72,7 +72,7 @@ BLAS 1, 2, 3のアルゴリズムでテンプレートパラメータが特に
 | [`vector_two_norm`](linalg/vector_two_norm.md) | xNRM2: ベクトルのユークリッドノルム(Euclidean norm)を求める (function template) | C++26 |
 | [`vector_abs_sum`](linalg/vector_abs_sum.md) | xASUM: ベクトル要素の絶対値和を求める (function template) | C++26 |
 | [`vector_idx_abs_max`](linalg/vector_idx_abs_max.md) | xIAMAX: ベクトル要素のうち最大絶対値インデクスを返す (function template) | C++26 |
-| `matrix_frob_norm` | 行列のフロベニウスノルム(Frobenius norm)を求める (function template) | C++26 |
+| [`matrix_frob_norm`](linalg/matrix_frob_norm.md) | 行列のフロベニウスノルム(Frobenius norm)を求める (function template) | C++26 |
 | `matrix_one_norm` | 行列の1ノルム(One norm)を求める (function template) | C++26 |
 | `matrix_inf_norm` | 行列の無限大ノルム(Infinity norm)を求める (function template) | C++26 |
 

reference/linalg/matrix_frob_norm.md

@@ -0,0 +1,128 @@
+# matrix_frob_norm
+
+* [mathjax enable]
+* linalg[meta header]
+* function template[meta id-type]
+* std::linalg[meta namespace]
+* cpp26[meta cpp]
+
+```cpp
+namespace std::linalg {
+  template<in-matrix InMat, class Scalar>
+  Scalar matrix_frob_norm(InMat A, Scalar init);          // (1)
+
+  template<class ExecutionPolicy,
+           in-matrix InMat,
+           class Scalar>
+  Scalar matrix_frob_norm(
+    ExecutionPolicy&& exec,
+    InMat A,
+    Scalar init);                                         // (2)
+
+  template<in-matrix InMat>
+  auto matrix_frob_norm(InMat A);                         // (3)
+
+  template<class ExecutionPolicy, in-matrix InMat>
+  auto matrix_frob_norm(ExecutionPolicy&& exec, InMat A); // (4)
+}
+```
+
+
+## 概要
+行列のフロベニウスノルムを計算する。
+
+- (1): 逐次実行する。
+- (2): 指定された実行ポリシーに応じて実行する。
+- (3): (1)で`init`に`InMat::value_type`のデフォルト値を与えて逐次実行する。
+- (4): (2)で`init`に`InMat::value_type`のデフォルト値を与えて、指定された実行ポリシーに応じて実行する。
+
+
+## 適格要件
+- (1), (2): `decltype(init + `[`abs-if-needed`](abs-if-needed.md)`(declval<typename InMat::value_type>()) * abs-if-needed(declval<typename InMat::value_type>()))`が`Scalar`に変換可能。
+
+## 効果
+- (3), (4): `T`を`decltype(abs-if-needed(declval<typename InMat::value_type>()) * abs-if-needed(declval<typename InMat::value_type>()))`とすると、
+  + (3): `matrix_frob_norm(v, T{})`を返す。
+  + (4): `matrix_frob_norm(std::forward<ExecutionPolicy>(exec), v, T{})`を返す。
+
+
+## 戻り値
+- (1), (2): `A`が $m \times n$ 行列とすると、以下の式の値を返す。
+
+$$
+\sqrt{\sum_{i = 0}^{m - 1} \sum_{j = 0}^{n - 1} |\verb|A[|i, j\verb|]||^2 + \verb|init|^2}
+$$
+
+- (3), (4): `T`を`decltype(abs-if-needed(declval<typename InMat::value_type>()) * abs-if-needed(declval<typename InMat::value_type>()))`とすると、
+  + (3): `matrix_frob_norm(v, T{})`を返す。
+  + (4): `matrix_frob_norm(std::forward<ExecutionPolicy>(exec), v, T{})`を返す。
+
+
+## 備考
+- (1), (2): もし`InMat::value_type`と`Scalar`がどちらも浮動小数点数型または`std::complex`の特殊化で、`Scalar`が`InMat::value_type`より精度が高い場合、和の各項は`Scalar`またはより高い精度の型が使われる。
+
+
+## 例
+**[注意] 処理系にあるコンパイラで確認していないため、間違っているかもしれません。**
+
+```cpp
+#include <array>
+#include <cmath>
+#include <execution>
+#include <iostream>
+#include <linalg>
+#include <mdspan>
+
+int main()
+{
+  constexpr size_t M = 4;
+  constexpr size_t N = 4;
+
+  std::array<double, M * N> vec;
+
+  std::mdspan v(vec.data(), M, N);
+
+  for(int i = 0; i < A.extent(0); ++i) {
+    for(int j = 0; j < A.extent(1); ++j) {
+      A(i,j) = ((i + j) % 2 == 0 ? 1.0 : -1.0) / (i * A.extent(1) + j + 1);
+    }
+  }
+
+  std::cout << stdex::linalg::matrix_frob_norm(A, 1.0 / (M + N + 1)) << '\n'
+            << stdex::linalg::matrix_frob_norm(std::execution::par, A, 1.0 / (M + N + 1)) << '\n'
+            << stdex::linalg::matrix_frob_norm(A) << '\n'
+            << stdex::linalg::matrix_frob_norm(std::execution::par, A) << '\n';
+
+  return 0;
+}
+```
+
+
+### 出力
+```
+1.2636
+1.2636
+1.25871
+1.25871
+```
+
+
+## バージョン
+### 言語
+- C++26
+
+### 処理系
+- [Clang](/implementation.md#clang): ??
+- [GCC](/implementation.md#gcc): ??
+- [ICC](/implementation.md#icc): ??
+- [Visual C++](/implementation.md#visual_cpp): ??
+
+
+## 関連項目
+- [`execution`](/reference/execution.md)
+- [`mdspan`](/reference/mdspan.md)
+
+
+## 参照
+- [P0788R3 Standard Library Specification in a Concepts and Contracts World](http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2018/p0788r3.pdf)
+