Layout
Layout<Shape, Stride>数 据 结 构 是 描 述 多 维 张 量 内 存 布 局 的 基 础 模 板 类，通 过 编 译 时 的 形 状Shape和 步 长Stride信 息，实 现 逻 辑 坐 标 空 间 到 一 维 内 存 地 址 空 间 的 映 射。借 助 模 板 元 编 程 技 术，该 类 在 编 译 时 完 成 计 算 和 代 码 生 成，从 而 降 低 运 行 时 开 销。
Layout包 含 两 个 核 心 组 成 部 分：
- Shape：定 义 数 据 的 逻 辑 形 状，例 如 二 维 矩 阵 的 行 数 和 列 数 或 多 维 张 量 的 各 维 度 大 小。
- Stride：定 义 各 维 度 在 内 存 中 的 步 长，即 同 维 度 相 邻 元 素 在 内 存 中 的 间 隔，单 位 为 元 素，并 与Shape的 维 度 信 息 一 一 对 应。
例 如，一 个 二 维 矩 阵 的Shape为(4，2)，Stride为(4，1)，表 示：
- 矩 阵 有4行2列。
- 列 方 向 步 长 为1，即 每 行 中 相 邻 元 素 间 隔1个 元 素；行 方 向 步 长 为4，即 相 邻 行 的 起 始 地 址 间 隔4个 元 素。
表1 线 性 地 址 视 图
| 地 址 | 0 | 1 | 2 | 4 | 5 | 6 | 8 | 9 | 10 | 12 | 13 |
|---|---|---|---|---|---|---|---|---|---|---|---|
| 元 素 | a00 | a01 | - | a10 | a11 | - | a20 | a21 | - | a30 | a31 |
表2 矩 阵 逻 辑 视 图
| 索 引 | 列0 | 列1 |
|---|---|---|
| 行0 | a00（地 址0） | a01（地 址1） |
| 行1 | a10（地 址4） | a11（地 址5） |
| 行2 | a20（地 址8） | a21（地 址9） |
| 行3 | a30（地 址12） | a31（地 址13） |
需 要 包 含 的 头 文 件
#include "tensor_api/tensor.h"
原 型 定 义
template <typename T, typename U, typename Info = Std::ignore_t>
struct Layout : private Std::tuple<T, U>
{
static constexpr auto depth = NestingDepthV<T>;
static constexpr auto rank = Std::tuple_size_v<T>;
__aicore__ inline constexpr Layout(const T& shape = {}, const U& stride = {})
: Std::tuple<T, U>(shape, stride)
template <size_t... I>
__aicore__ inline constexpr decltype(auto) Capacity() const
__aicore__ inline constexpr decltype(auto) layout()
__aicore__ inline constexpr decltype(auto) layout() const
template <size_t... I>
__aicore__ inline constexpr decltype(auto) Shape()
template <size_t... I>
__aicore__ inline constexpr decltype(auto) Shape() const
template <size_t... I>
__aicore__ inline constexpr decltype(auto) Stride()
template <size_t... I>
__aicore__ inline constexpr decltype(auto) Stride() const
template <typename S>
__aicore__ inline constexpr auto operator()(const S& coord) const
template <size_t... I>
__aicore__ inline constexpr decltype(auto) Rank() const
template <size_t... I>
__aicore__ inline constexpr decltype(auto) Size() const
template <size_t... I>
__aicore__ inline constexpr decltype(auto) Get()
template <size_t... I>
__aicore__ inline constexpr decltype(auto) Get() const
};
模 板 参 数
| 参 数 名 | 描 述 |
|---|---|
| T | Std::tuple结 构 类 型，用 于 定 义 数 据 的 逻 辑 形 状。 |
| U | Std::tuple结 构 类 型，用 于 定 义 各 维 度 在 内 存 中 的 步 长，并 与Shape的 维 度 信 息 一 一 对 应。 |
| Info | 可 选 模 板 参 数，默 认 为Std::ignore_t。当Layout由MakeFrameLayout或 相 关 接 口 构 造 时，该 参 数 可 携 带 布 局 模 式 和 布 局 特 征 等 附 加 信 息。 |
成 员 函 数
Layout()
功 能 说 明
构 造Layout对 象，使 用 给 定 的Shape和Stride初 始 化 布 局 信 息。
函 数 原 型
__aicore__ inline constexpr Layout(const T& shape = {}, const U& stride = {})
参 数 说 明
参 数 名 输 入/输 出 描 述 shape 输 入 张 量 的 形 状 信 息，必 须 为Std::tuple类 型。 stride 输 入 张 量 的 步 长 信 息，必 须 为Std::tuple类 型。 返 回 值 说 明
构 造 函 数，无 返 回 值。
Capacity()
功 能 说 明
获 取 当 前Layout布 局 所 需 的 实 际 内 存 容 量。
传 入 模 板 参 数I...时，会 先 选 取 指 定 子 维 度，再 计 算 对 应 子 布 局 的 容 量。
函 数 原 型
C++template <size_t... I> __aicore__ inline constexpr decltype(auto) Capacity() const返 回 值 说 明
返 回 当 前Layout或 指 定 子 维 度 对 应 布 局 的 实 际 容 量。
layout()
功 能 说 明
获 取Layout对 象 自 身，用 于 统 一 接 口 中 返 回Layout布 局 实 例。
函 数 原 型
C++__aicore__ inline constexpr decltype(auto) layout() __aicore__ inline constexpr decltype(auto) layout() const返 回 值 说 明
返 回 当 前Layout对 象 的（常 量）引 用。
Shape()
功 能 说 明
获 取Layout中 的Shape信 息。
不 指 定 模 板 参 数I...时 返 回 完 整Shape；传 入I...时 返 回 指 定 子 维 度 对 应 的 子 结 构。
函 数 原 型
C++template <size_t... I> __aicore__ inline constexpr decltype(auto) Shape() template <size_t... I> __aicore__ inline constexpr decltype(auto) Shape() const返 回 值 说 明
返 回Shape对 象 或 其 子 结 构 的（常 量）引 用。
Stride()
功 能 说 明
获 取Layout中 的Stride信 息。
不 指 定 模 板 参 数I...时 返 回 完 整Stride；传 入I...时 返 回 指 定 子 维 度 对 应 的 子 结 构。
函 数 原 型
C++template <size_t... I> __aicore__ inline constexpr decltype(auto) Stride() template <size_t... I> __aicore__ inline constexpr decltype(auto) Stride() const返 回 值 说 明
返 回Stride对 象 或 其 子 结 构 的（常 量）引 用。
operator()
功 能 说 明
将 多 维 逻 辑 坐 标 映 射 为 一 维 线 性 索 引。
该 接 口 内 部 调 用Crd2Idx，根 据 当 前Layout的Shape和Stride计 算 坐 标 在 内 存 中 的 线 性 位 置。
函 数 原 型
C++template <typename S> __aicore__ inline constexpr auto operator()(const S& coord) const参 数 说 明
参 数 名 输 入/输 出 描 述 coord 输 入 多 维 逻 辑 坐 标。 返 回 值 说 明
返 回 坐 标coord对 应 的 一 维 线 性 索 引。
Rank()
功 能 说 明
获 取Layout的 秩，即 维 度 数。
不 指 定 模 板 参 数I...时 返 回 完 整Layout的 秩；传 入I...时 返 回 指 定 子 维 度 的 秩。
函 数 原 型
C++template <size_t... I> __aicore__ inline constexpr decltype(auto) Rank() const返 回 值 说 明
返 回 当 前Layout或 指 定 子 维 度 的 秩。
Size()
功 能 说 明
获 取Layout覆 盖 的 元 素 总 数。
不 指 定 模 板 参 数I...时 返 回 完 整Shape对 应 的 元 素 总 数；传 入I...时 返 回 指 定 子 维 度 下 的 元 素 总 数。
函 数 原 型
C++template <size_t... I> __aicore__ inline constexpr decltype(auto) Size() const返 回 值 说 明
返 回 当 前Layout或 指 定 子 维 度 覆 盖 的 元 素 总 数。
Get()
功 能 说 明
从Layout中 提 取 指 定 位 置 的 元 素 或 子 结 构。
位 置0对 应Shape，位 置1对 应Stride；配 合 模 板 参 数I...可 进 一 步 提 取 子tuple中 的 元 素。
函 数 原 型
C++template <size_t... I> __aicore__ inline constexpr decltype(auto) Get() template <size_t... I> __aicore__ inline constexpr decltype(auto) Get() const返 回 值 说 明
返 回 指 定 位 置 元 素 或 子 结 构 的（常 量）引 用。
depth
功 能 说 明
编 译 期 常 量，表 示Shape类 型 的 嵌 套 深 度，用 于 判 断 当 前Layout是 否 为 嵌 套 布 局 结 构。
rank
功 能 说 明
编 译 期 常 量，表 示 完 整Layout的 秩。
Layout及 成 员 函 数 示 例
下 面 通 过 一 个 二 维Layout示 例，说 明Layout对 象 本 身 以 及 各 成 员 函 数 的 使 用 方 式 和 返 回 结 果。
using namespace AscendC::Te;
auto layout = Layout(MakeShape(4, 2), MakeStride(4, 1));
auto self = layout.layout();
// self = Layout(MakeShape(4, 2), MakeStride(4, 1))
auto shape = layout.Shape();
// shape = (4, 2)
auto shape0 = layout.Shape<0>();
// shape0 = 4
auto stride = layout.Stride();
// stride = (4, 1)
auto stride1 = layout.Stride<1>();
// stride1 = 1
auto rank = layout.Rank();
// rank = 2
auto size = layout.Size();
// size = 8
auto capacity = layout.Capacity();
// capacity = 16
auto index = layout(MakeCoord(1, 1));
// index = 5
auto shapeInfo = layout.Get<0>();
// shapeInfo = (4, 2)
auto strideInfo = layout.Get<1>();
// strideInfo = (4, 1)
constexpr auto depth = decltype(layout)::depth;
// depth = 1
constexpr auto fullRank = decltype(layout)::rank;
// fullRank = 2