Class IndexBasis

Nested Relationships

Nested Types

Class Documentation

class IndexBasis

the basis an Index runs over: an IndexSpace plus an optional basis instance

The instance is an opaque integer that distinguishes several bases of the same IndexSpace that meet in one expression, e.g. an eigenbasis and a localized basis of the space, or bases specific to two different tensors. A null instance (the default) is the IndexSpace’s own basis; every integer, 0 and negative ones included, is an ordinary instance distinct from null.

A basis instance may carry the name it is registered under in an IndexBasisRegistry (see IndexBasisRegistry::add(label, basis)); a basis obtained from the registry carries it, one built from a space and an instance does not. The name is part of the basis’s identity, as a space’s label is of the space’s: equality, ordering and hashing see it, so a named basis and the unnamed basis of the same space and instance are two bases. The registry keeps an instance number and a name one-to-one within a space (see IndexBasisRegistry::resolve()), so an Index given an instance by number resolves it to the named basis; one given an IndexBasis takes it as given. Such an unnamed basis has no spelling of its own: an index in it prints with the bare instance number, which parses back to the named basis.

A basis has an extent (the number of functions in it), a metric (whether it is orthonormal) and a scalar field. Unlike the name, these describe the basis but are not part of its identity, so equality, ordering and hashing ignore them. An unnamed basis, whether the space’s own basis or an unnamed instance, is the space’s own basis up to an orthonormal rotation (e.g. a localized basis): its extent is the dimension of the space, its metric is unit and its field is that of the space’s own basis (IndexSpace::field()), and evaluation keys its axes by base_key(), which is the space’s key for such an instance, and so sizes, tiles and slices it as the space. A basis that differs in any of these (a truncated or an overcomplete set, a non-orthonormal basis) must be registered under a name, which gives it a key and metadata of its own (see IndexBasisRegistry::add(label, basis)). A named basis registered without an extent or a field follows its space’s (own_extent() and own_field() are null), and so sees the registry’s setters for the space’s label; one registered with them, even with the values the space has, does not.

registry keys

An IndexBasisRegistry keys its entries, spaces and named basis instances alike, by the base key of a label (an Index label with its ordinal stripped); a name follows the grammar of a space’s label, so a basis key is reduced as a space key is.

template<std::ranges::contiguous_range View>
static inline auto reduce_key(View &&key)
Parameters:

key – a label of a space, of a named basis instance, or of an Index in either

Returns:

the base key of key, as IndexSpace::reduce_key(key)

template<typename CharT>
static inline auto reduce_key(const CharT *key)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Public Types

using instance_type = std::int32_t
using optional_instance = std::optional<instance_type>

Public Functions

IndexBasis() noexcept = default

null space, null instance

inline IndexBasis(IndexSpace space) noexcept

the space’s own basis (null instance)

template<basic_string_convertible S, typename ...Args>
inline IndexBasis(S &&type_label, Args&&... args)

the own basis of the IndexSpace constructed from type_label and args, so that a braced IndexSpace initializer also initializes an IndexBasis

inline explicit IndexBasis(IndexSpace space, optional_instance basis_instance) noexcept
IndexBasis(IndexSpace space, optional_instance basis_instance, std::wstring name, std::optional<std::size_t> extent = {}, IndexBasisMetric metric = IndexBasisMetric::Unit, std::optional<Field> field = {})
Parameters:

  • name – the label basis_instance is registered under

  • extent – the number of functions in the basis; null for the dimension of space

  • metric – whether the basis is orthonormal

  • field – the scalar field of the basis; null for that of the own basis of space

Pre:

name is empty or basis_instance is non-null; name is non-empty or every other argument is at its default (an unnamed basis is the space’s own basis up to an orthonormal rotation)

inline const IndexSpace &space() const noexcept
inline const optional_instance &basis_instance() const noexcept
inline bool has_basis_instance() const noexcept
inline const std::wstring &name() const noexcept
Returns:

the name the basis instance is registered under, empty if it carries none

inline bool has_name() const noexcept
inline const std::wstring &base_key() const noexcept
Returns:

name() if the basis carries a name, else space().base_key(); the unnamed instances of a space share its key

inline optional_instance unnamed_instance() const noexcept
Returns:

the basis instance unless the basis carries a name, which then stands for it

inline std::size_t extent() const noexcept
Returns:

the number of functions in the basis: the dimension of its space (IndexSpace::dimension()) unless registered with an extent of its own

inline IndexBasisMetric metric() const noexcept
Returns:

whether the basis is orthonormal (IndexBasisMetric::Unit) or not; unit unless registered otherwise

inline Field field() const noexcept
Returns:

the scalar field of the basis: that of its space’s own basis (IndexSpace::field()) unless registered with a field of its own

inline const std::optional<std::size_t> &own_extent() const noexcept
Returns:

the extent the basis was registered with (or mirrors from the entry it follows, see IndexBasisRegistry::follow()), null if extent() follows the dimension of its space (which the registry’s IndexBasisRegistry::extent(label, n) for the space’s label then sets)

inline const std::optional<Field> &own_field() const noexcept
Returns:

the field the basis was registered with (or mirrors from the entry it follows, see IndexBasisRegistry::follow()), null if field() follows that of its space’s own basis (which the registry’s IndexBasisRegistry::field(label, f) for the space’s label then sets)

std::wstring instance_suffix() const
Returns:

L";N" for a non-null instance N, else an empty string

Friends

inline friend bool operator==(const IndexBasis &b1, const IndexBasis &b2) noexcept

compares space, instance and name; the extent, metric and field are ignored

inline friend std::strong_ordering operator<=>(const IndexBasis &b1, const IndexBasis &b2) noexcept

orders by space, then by instance (null first), then by name (unnamed first); the extent, metric and field are ignored

inline friend std::size_t hash_value(const IndexBasis &b)
Returns:

hash_value(b.space()) if b has no instance; the extent, metric and field are ignored

struct bad_key : public sequant::IndexSpace::bad_key

exception type thrown by a registry lookup when no entry, space or named basis instance, is registered under a key; an IndexSpace::bad_key, so that handlers for space lookups catch it

Subclassed by sequant::IndexBasisRegistry::not_a_space