Shapes and extents¶

A tensor's shape says how many elements it has along each axis. In strata a shape is a type, Shape<...>, and each axis is either static, its extent written into the type, or dynamic, its extent known only at run time and marked Dyn.

import strata;
import std;

using strata::Dyn;
using strata::Matrix;
using strata::Shape;

Why a type¶

Putting an extent in the type lets the compiler know it. A static extent costs no memory, can be checked at compile time, and lets small tensors live inside the object with no allocation. A dynamic extent costs one std::size_t and is checked when the program runs. Mixing the two is the point: Shape<3, Dyn> is a matrix with 3 rows and however many columns you decide later.

Making a shape¶

A constructor takes exactly the dynamic extents, in axis order, as integers of any type other than bool. The static ones are already in the type.

constexpr Shape<3, 4> fixed{};                 // nothing to give
const Shape<3, Dyn, 5> mixed{4};               // (1)!
const Shape<Dyn, Dyn> dynamic{rows, columns};  // one per dynamic axis

1. The middle axis is the only dynamic one, so {4} is its extent: the shape is (3, 4, 5).

Giving the wrong number of extents does not compile: Shape<3, Dyn, Dyn>{4} and Shape<3, 4>{4} are both errors.

A default-constructed shape has every dynamic extent equal to 0, as std::extents does.

When you have every extent in hand, static ones included, use from_extents. The static ones must agree with the type:

const auto shape = Shape<3, Dyn>::from_extents({3, 7});   // same as Shape<3, Dyn>{7}

Asking a shape¶

constexpr auto shape = Shape<3, Dyn, 5>{4};

static_assert(shape.rank() == 3);
static_assert(shape.dyn_rank() == 1);   // dynamic axes
static_assert(shape.extent(1) == 4);    // static or dynamic, the number
static_assert(shape.size() == 60);      // 3 * 4 * 5

static_assert(Shape<3, Dyn>::static_extent(0) == 3);   // what the type fixes, if anything
static_assert(!Shape<3, Dyn>::static_extent(1).has_value());
static_assert(Shape<3, Dyn>::is_dynamic(1));

rank, dyn_rank, static_extent and is_dynamic are static: they are facts about the type, and need no object. extent and size read the shape itself. All of them work in constant expressions.

An extent of 0 is allowed and gives a size of 0: Shape<3, 0>{}.size() == 0.

What is checked¶

Invalid extents are caught as early as they can be.

Converting between shapes¶

A shape converts to one that fixes less: a static extent may become dynamic, never the other way round.

Shape<Dyn, Dyn> a = Shape<3, 4>{};      // fine: both become dynamic
Shape<Dyn, 4>   b = Shape<3, 4>{};      // fine: the second stays static
// Shape<3, 4>  c = Shape<Dyn, 4>{};    // error: a dynamic extent may not become static
// Shape<4, Dyn> d = Shape<3, 4>{};     // error: 3 and 4 are not the same

The same rule governs tensors and views, because they hold a shape. A view over a Shape<3, 4> tensor converts to a view over Shape<Dyn, Dyn>, so a function can take the general one and accept both.

Shapes of expressions¶

An expression such as a + b needs a shape for its result. strata takes the most specific one both operands allow: static wherever either operand fixes the extent.

const Matrix<float, 2, 3> a = /* ... */;
const Matrix<float, Dyn, Dyn> b{Shape<Dyn, Dyn>{2, 3}, 0.5F};

Matrix c = a + b;   // Tensor<float, Shape<2, 3>>: the static shape wins

Operands whose shapes can never agree, because their ranks differ or two static extents on the same axis differ, do not compile. When they agree on static extents but a dynamic one hides the difference, the mismatch is found at run time.

Printing a shape¶

A shape formats with std::format:

Any other spec is a compile error.

Under the hood¶

See also¶

• Shapes and extents in the API reference.
• Order and layout: how the axes of a shape are laid out in memory.
• Views and expressions: slice, permute and block change a tensor's shape without copying.