linalg: layout_blas_packed概要(#1233)

cpprefjp · Feb 28, 2024 · 9f57615 · 9f57615
1 parent 19cfa92
commit 9f57615
Show file tree

Hide file tree

Showing 5 changed files with 252 additions and 1 deletion.
diff --git a/reference/linalg.md b/reference/linalg.md
@@ -31,7 +31,7 @@ BLAS互換アルゴリズムは、演算対象データの次元数に応じて3
 
 | 名前 | 説明 | 対応バージョン |
 |------|------|----------------|
-| `layout_blas_packed` | 行列要素のBLAS互換パックレイアウトに対応する[レイアウトマッピングポリシー](mdspan/LayoutMappingPolicy.md) (class template) | C++26 |
+| [`layout_blas_packed`](linalg/layout_blas_packed.md) | 行列要素のBLAS互換パックレイアウトに対応する[レイアウトマッピングポリシー](mdspan/LayoutMappingPolicy.md) (class template) | C++26 |
 | `scaled` | 要素値をスカラ倍した読み取り専用`std::mdspan`を作る (function template) | C++26 |
 | `scaled_accessor` | `scaled`関数用の[アクセサポリシー](mdspan/AccessorPolicy.md) (class template) | C++26 |
 | `conjugated_accessor` | `conjugated`関数用の[アクセサポリシー](mdspan/AccessorPolicy.md) (class template) | C++26 |
@@ -134,4 +134,6 @@ BLAS互換アルゴリズムは、演算対象データの次元数に応じて3
 
 ## 参照
 - [P1673R13 A free function linear algebra interface based on the BLAS](https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2023/p1673r13.html)
+- [P1674R2: Evolving a Standard C++ Linear Algebra Library from the BLAS](https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2022/p1674r2.html)
+- [std::linalg: Linear Algebra Coming to Standard C++](https://github.com/CppCon/CppCon2023/blob/main/Presentations/stdlinalg_linear_algebra_coming_to_standard_cpp.pdf), CppCon 2023
 - [BLAS (Basic Linear Algebra Subprograms)](https://www.netlib.org/blas/)
diff --git a/reference/linalg/layout_blas_packed.md b/reference/linalg/layout_blas_packed.md
@@ -0,0 +1,99 @@
+# layout_blas_packed
+* linalg[meta header]
+* class template[meta id-type]
+* std::linalg[meta namespace]
+* cpp26[meta cpp]
+
+```cpp
+namespace std::linalg {
+  template<class Triangle, class StorageOrder>
+  class layout_blas_packed;
+}
+```
+
+## 概要
+`layout_blas_packed`は、多次元配列ビュー[`mdspan`](/reference/mdspan/mdspan.md)を用いた正方行列(square matrix)に対して、BLASにおけるパックレイアウトと互換性のある行列要素配置を表現する[レイアウトマッピングポリシー](/reference/mdspan/LayoutMappingPolicy.md)クラスである。
+
+- `Triangle` : 指定する行列要素の種別を、上三角[`upper_triangle_t`](upper_triangle_t.md.nolink)または下三角[`lower_triangle_t`](lower_triangle_t.md.nolink)から指定する。
+- `StorageOrder` : 行列要素の格納順を、列優先[`column_major_t`](column_major_t.md.nolink)または行優先[`row_major_t`](row_major_t.md.nolink)から指定する。
+
+`layout_blas_packed`を用いて、BLASの Symmetric Packed (SP), Hermitian Packed (HP), Triangular Packed (TP) 行列レイアウトを表現できる。
+
+
+## 適格要件
+- `Triangle`は[`upper_triangle_t`](upper_triangle_t.md.nolink)または[`lower_triangle_t`](lower_triangle_t.md.nolink)のいずれか
+- `StorageOrder`は[`column_major_t`](column_major_t.md.nolink)または[`row_major_t`](row_major_t.md.nolink)のいずれか
+
+
+## メンバ型
+
+| 名前 | 説明 | 対応バージョン |
+|------|------|----------------|
+| `triangle_type` | `Triangle` | C++26 |
+| `storage_order_type` | `StorageOrder` | C++26 |
+| [`mapping`](layout_blas_packed/mapping.md) | レイアウトマッピング | C++26 |
+
+
+## 例
+```cpp example
+#include <linalg>
+#include <mdspan>
+#include <print>
+namespace linalg = std::linalg;
+
+int main()
+{
+  double arr[] = {1, 2, 3, 4, 5, 6};
+
+  // 行優先レイアウトの下三角要素から3x3対称行列を構築
+  std::mdspan<
+    double,
+    std::extents<size_t, 3, 3>,
+    linalg::layout_blas_packed<linalg::lower_triangle, linalg::column_major>
+  > mat{arr};
+  // 1 . .
+  // 2 4 .
+  // 3 5 6
+
+  for (size_t i = 0; i < mat.extent(0); i++) {
+    for (size_t j = 0; j < mat.extent(1); j++) {
+      std::print(" {}", mat[i, j]);
+    }
+    std::println("");
+  }
+}
+```
+* linalg::layout_blas_packed[color ff0000]
+* linalg::lower_triangle[link lower_triangle_t.md.nolink]
+* linalg::column_major[link column_major_t.md.nolink]
+* mat.extent[link /reference/mdspan/mdspan/extent.md]
+* std::print[link /reference/print/print.md]
+* std::println[link /reference/print/println.md]
+
+
+### 出力
+```
+ 1 2 3
+ 2 4 5
+ 3 5 6
+```
+
+
+## バージョン
+### 言語
+- C++26
+
+### 処理系
+- [Clang](/implementation.md#clang): ??
+- [GCC](/implementation.md#gcc): ??
+- [ICC](/implementation.md#icc): ??
+- [Visual C++](/implementation.md#visual_cpp): ??
+
+
+## 関連項目
+- [`mdspan`](/reference/mdspan/mdspan.md)
+
+
+## 参照
+- [P1673R13 A free function linear algebra interface based on the BLAS](https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2023/p1673r13.html)
+- [P1674R2: Evolving a Standard C++ Linear Algebra Library from the BLAS](https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2022/p1674r2.html)
diff --git a/reference/linalg/layout_blas_packed/mapping.md b/reference/linalg/layout_blas_packed/mapping.md
@@ -0,0 +1,148 @@
+# mapping
+* linalg[meta header]
+* class template[meta id-type]
+* std::linalg[meta namespace]
+* layout_blas_packed[meta class]
+* cpp26[meta cpp]
+
+```cpp
+namespace std::linalg {
+  template<class Triangle, class StorageOrder>
+  class layout_blas_packed {
+    template<class Extents>
+    struct mapping;
+  };
+}
+```
+* layout_blas_packed[link ../layout_blas_packed.md]
+* Extents[link /reference/mdspan/extents.md]
+
+## 概要
+`layout_blas_packed::mapping`は、BLASにおける正方行列(square matrix)パックレイアウトと互換性のある[レイアウトマッピング](/reference/mdspan/LayoutMapping.md)を表現するクラスである。
+
+`layout_blas_packed<T, SO>::mapping<E>`は[トリビアルコピー可能](/reference/type_traits/is_trivially_copyable.md)であり、[`regular`](/reference/concepts/regular.md)のモデルである。
+
+
+### 説明専用メンバ変数
+`layout_blas_packed::mapping`クラステンプレートは、下記の説明専用メンバ変数を保持する。
+
+- `extents_` : `extents_type`型の[多次元配列サイズ情報](/reference/mdspan/extents.md)
+
+
+## 適格要件
+- `Extents`は[`extents`](/reference/mdspan/extents.md)の特殊化であること
+- [`Extents::rank()`](/reference/mdspan/extents/rank.md) `== 2`
+- 下記いずれかを満たすこと
+    - `extents_type::static_extent(0) ==` [`dynamic_extent`](/reference/span/dynamic_extent.md)または
+    - `extents_type::static_extent(1) ==` [`dynamic_extent`](/reference/span/dynamic_extent.md)または
+    - `extents_type::static_extent(0) == extents_type::static_extent(1)`
+- [`Extents::rank_dynamic()`](/reference/mdspan/extents/rank.md) `== 0`のとき、`Ns`を[`Extents::static_extent`](/reference/mdspan/extents/static_extent.md)`(0)`としたとき値`Ns * (Ns + 1)`を`index_type`型で表現できること。
+
+
+## メンバ関数
+### 構築・破棄
+
+| 名前 | 説明 | 対応バージョン |
+|------|------|----------------|
+| [`(constructor)`](mapping/op_constructor.md.nolink) | コンストラクタ | C++26 |
+| `(destructor)` | デストラクタ | C++26 |
+| `operator=`    | コピー代入演算子 | C++26 |
+
+### 観測
+
+| 名前 | 説明 | 対応バージョン |
+|------|------|----------------|
+| `extents` | 多次元配列のサイズ`extents_`を取得する | C++26 |
+| [`required_span_size`](mapping/required_span_size.md.nolink) | 要素アクセス範囲を取得する | C++26 |
+| [`operator()`](mapping/op_call.md.nolink) | 多次元配列インデクスから要素位置へ変換する | C++26 |
+| `stride` | 行列サイズ1x1ならば`1` | C++26 |
+| `is_unique`     | 行列サイズ1x1ならば`true` | C++26 |
+| `is_exhaustive` | `true`を返す | C++26 |
+| `is_strided`    | 行列サイズ1x1ならば`true` | C++26 |
+
+
+## 静的メンバ関数
+
+| 名前 | 説明 | 対応バージョン |
+|------|------|----------------|
+| `is_always_unique` | 行または列の静的要素数が1ならば`true` | C++26 |
+| `is_always_exhaustive` | `true`を返す | C++26 |
+| `is_always_strided` | `is_always_unique();` | C++26 |
+
+
+## メンバ型
+
+| 名前 | 説明 | 対応バージョン |
+|------|------|----------------|
+| `extents_type` | [`Extents`](/reference/mdspan/extents.md) | C++26 |
+| `index_type` | [`Extents::index_type`](/reference/mdspan/extents.md) | C++26 |
+| `size_type` | [`Extents::size_type`](/reference/mdspan/extents.md) | C++26 |
+| `rank_type` | [`Extents::rank_type`](/reference/mdspan/extents.md) | C++26 |
+| `layout_type` | [`layout_blas_packed`](../layout_blas_packed.md) | C++26 |
+
+
+## 非メンバ（*Hidden friends*）関数
+### 比較演算子
+
+| 名前 | 説明 | 対応バージョン |
+|------|------|----------------|
+| [`operator==`](mapping/op_equal.md.nolink) | 等値比較 | C++26 |
+| [`operator!=`](mapping/op_equal.md.nolink) | 非等値比較 (`==`により使用可能) | C++26 |
+
+
+## 例
+```cpp example
+#include <linalg>
+#include <mdspan>
+#include <print>
+namespace linalg = std::linalg;
+
+int main()
+{
+  double arr[] = {1, 2, 3, 4, 5, 6};
+
+  // 行優先レイアウトの下三角要素から3x3対称行列を構築
+  using LayoutPacked = linalg::layout_blas_packed<linalg::lower_triangle, linalg::column_major>;
+  using Mapping = LayoutPacked::mapping<std::extents<size_t, 3, 3>>;
+  std::mdspan mat{arr, Mapping{}};
+  // 1 . .
+  // 2 4 .
+  // 3 5 6
+
+  for (size_t i = 0; i < mat.extent(0); i++) {
+    for (size_t j = 0; j < mat.extent(1); j++) {
+      std::print(" {}", mat[i, j]);
+    }
+    std::println("");
+  }
+}
+```
+* linalg::layout_blas_packed[color ff0000]
+* ::mapping[color ff0000]
+
+### 出力
+```
+ 1 2 3
+ 2 4 5
+ 3 5 6
+```
+
+
+## バージョン
+### 言語
+- C++26
+
+### 処理系
+- [Clang](/implementation.md#clang): ??
+- [GCC](/implementation.md#gcc): ??
+- [ICC](/implementation.md#icc): ??
+- [Visual C++](/implementation.md#visual_cpp): ??
+
+
+## 関連項目
+- [`mdspan`](/reference/mdspan/mdspan.md)
+
+
+## 参照
+- [P1673R13 A free function linear algebra interface based on the BLAS](https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2023/p1673r13.html)
+- [P1674R2: Evolving a Standard C++ Linear Algebra Library from the BLAS](https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2022/p1674r2.html)
diff --git a/reference/mdspan/LayoutMapping.md b/reference/mdspan/LayoutMapping.md
@@ -93,6 +93,7 @@ LayoutMappingを満たす型`M`は
 - [`layout_left::mapping<E>`](layout_left/mapping.md)
 - [`layout_right::mapping<E>`](layout_right/mapping.md)
 - [`layout_stride::mapping<E>`](layout_stride/mapping.md)
+- [`layout_blas_packed<T,SO>::mapping<E>`](/reference/linalg/layout_blas_packed/mapping.md)
 
 
 ## バージョン

diff --git a/reference/mdspan/LayoutMappingPolicy.md b/reference/mdspan/LayoutMappingPolicy.md
@@ -40,6 +40,7 @@ LayoutMappingPolicyを満たす型`MP`は
 - [`layout_left`](layout_left.md)
 - [`layout_right`](layout_right.md)
 - [`layout_stride`](layout_stride.md)
+- [`linalg::layout_blas_packed<T,SO>`](/reference/linalg/layout_blas_packed.md)
 
 
 ## バージョン