Class Index

Nested Relationships

Nested Types

Inheritance Relationships

Base Type

Class Documentation

class Index : public sequant::Taggable

Index = IndexSpace + nonnegative integer ordinal.

Index is defined by an IndexSpace (IndexSpace::base_key()) and a non-negative ordinal (by default can be null). Indices with ordinals greater or equal to the value returned by min_tmp_label() cannot be constructed directly. Unlike SeQuant1’s ParticleIndex, Index supports dependencies between indices to be able to express e.g. hierarchical partitioning of index spaces or hierarchical nesting of spaces.

Since Index objects are most of the time created from string representation, Index will use default Context’s index space registry to map base labels to index spaces. Since SeQuant can still operate without explicit initialization of the default index space registry Index still supports this mode. In such mode all Index objects created from strings will use the same index space (see Index::default_space_attr) with the base label stored into its space’s base_key (ordinal, if any, is used as usual).

Note

Index and other SeQuant classes currently use wide characters to represent labels and other strings; this goes against some popular recommendations to use narrow strings (bytestrings) everywhere. The rationale for such a choice is that this makes “character”-centric operations easy without the need to grok Unicode and to introduce extra dependencies such as ICU. Many functions accept bytestrings as input, but they are recoded to wide (but UTF-8 encoded) strings. For optimal efficiency and simplicity users are recommended to use wide strings until further notice.

Public Types

using ordinal_type = std::uint64_t

ordinals are represented by this type

using index_vector = container::vector<Index>

protoindices cannot be represented by small_vector because it does not accept incomplete types, see https://www.boost.org/doc/libs/master/doc/html/container/main_features.html#container.main_features.containers_of_incomplete_types N.B. hard-coding alignment should lift this restriction but it seems that alignof is still invoked (for no good reason)

Public Functions

Index() = default
inline Index(const Index &idx) noexcept

copy constructor

Warning

memoized data (label, full_label) is not copied

inline Index(Index &&idx) noexcept

move constructor

Note

memoized data (label, full_label) is moved

Parameters:

idx – [inout] on output: null Index

inline Index &operator=(const Index &idx)

copy assignment

Warning

memoized data (label, full_label) is not copied

inline Index &operator=(Index &&idx) noexcept

move assignment

Note

memoized data (label, full_label) is moved

Parameters:

idx – [inout] on output: null Index

inline explicit Index(const IndexSpace &space)
Parameters:

space – (a const ref to) the IndexSpace object that specifies to this space this object belongs

inline Index(const IndexSpace &space, meta::integral auto ord)
Parameters:

  • space – (a const ref to) the IndexSpace object that specifies to this space this object belongs

  • ord – the index ordinal

template<meta::integral I>
inline Index(const IndexSpace &space, std::optional<I> ord)
Parameters:

  • space – (a const ref to) the IndexSpace object that specifies to this space this object belongs

  • ord – the index ordinal

inline Index(const IndexSpace &space, container::vector<Index> proto_indices, bool symmetric_proto_indices = true)
Parameters:

  • space – (a const ref to) the IndexSpace object that specifies to this space this object belongs

  • proto_indices – labels of proto indices (all must be unique, i.e. duplicates are not allowed)

  • symmetric_proto_indices – if true, proto_indices can be permuted at will and will always be sorted

inline Index(const IndexSpace &space, meta::integral auto ord, IndexList proto_indices, bool symmetric_proto_indices = true)
Parameters:

  • space – (a const ref to) the IndexSpace object that specifies to this space this object belongs

  • ord – the index ordinal

  • proto_indices – labels of proto indices (all must be unique, i.e. duplicates are not allowed)

  • symmetric_proto_indices – if true, proto_indices can be permuted at will and will always be sorted

template<meta::integral I>
inline Index(const IndexSpace &space, std::optional<I> ord, IndexList proto_indices, bool symmetric_proto_indices = true)
Parameters:

  • space – (a const ref to) the IndexSpace object that specifies to this space this object belongs

  • ord – the index ordinal

  • proto_indices – labels of proto indices (all must be unique, i.e. duplicates are not allowed)

  • symmetric_proto_indices – if true, proto_indices can be permuted at will and will always be sorted

inline Index(const IndexSpace &space, IndexList proto_indices, bool symmetric_proto_indices = true)
Parameters:

  • space – (a const ref to) the IndexSpace object that specifies to this space this object belongs

  • proto_indices – labels of proto indices (all must be unique, i.e. duplicates are not allowed)

  • symmetric_proto_indices – if true, proto_indices can be permuted at will and will always be sorted

inline Index(const IndexSpace &space, meta::integral auto ord, container::vector<Index> proto_indices, bool symmetric_proto_indices = true)
Parameters:

  • space – (a const ref to) the IndexSpace object that specifies to this space this object belongs

  • ord – the index ordinal

  • proto_indices – labels of proto indices (all must be unique, i.e. duplicates are not allowed)

  • symmetric_proto_indices – if true, proto_indices can be permuted at will and will always be sorted

template<meta::integral I>
inline Index(const IndexSpace &space, std::optional<I> ord, container::vector<Index> proto_indices, bool symmetric_proto_indices = true)
Parameters:

  • space – (a const ref to) the IndexSpace object that specifies to this space this object belongs

  • ord – the index ordinal

  • proto_indices – labels of proto indices (all must be unique, i.e. duplicates are not allowed)

  • symmetric_proto_indices – if true, proto_indices can be permuted at will and will always be sorted

template<basic_string_convertible String>
inline Index(String &&label)

See also

IndexSpace::instance ); if label is an rvalue reference will scavenge it for the label of the new index

Warning

nonexplicit to make Index creation as ergonomic as possible, at the cost of slightly increased danger

Parameters:

label – the index label, does not need to be unique, but must be convertible into an IndexSpace (

template<index_or_index_label IndexOrIndexLabel, typename I>
inline Index(IndexOrIndexLabel &&index_or_index_label, std::initializer_list<I> proto_indices, bool symmetric_proto_indices = true)

constructs an Index using an existing Index’s label and space and a list of proto indices

Template Parameters:
Parameters:

  • index_or_index_label – an Index or a label, does not need to be unique; if index_or_index_label is a label and an rvalue reference will scavenge it for the label of the new index

  • proto_indices – list of proto indices, or their labels (all must be unique, i.e. duplicates are not allowed)

  • symmetric_proto_indices – if true, proto_indices can be permuted at will and will always be sorted

template<index_or_index_label IndexOrIndexLabel, typename IndexContainer, typename = std::enable_if_t<std::is_convertible_v<std::remove_cvref_t<IndexContainer>, container::vector<Index>>>>
inline Index(IndexOrIndexLabel &&index_or_index_label, IndexContainer &&proto_indices, bool symmetric_proto_indices = true)

constructs an Index using an existing Index’s label and space and a list of proto indices

Template Parameters:

IndexOrIndexLabel – either Index or a type that can be viewed/converted to a string (i.e., meta::is_basic_string_convertible_v<std::decay_t<IndexOrIndexLabel>>==true)

Parameters:

  • index_or_index_label – an Index or a label, does not need to be unique; if index_or_index_label is a label and an rvalue reference will scavenge it for the label of the new index

  • proto_indices – list of proto indices (all must be unique, i.e. duplicates are not allowed)

  • symmetric_proto_indices – if true, proto_indices can be permuted at will and will always be sorted

template<typename IndexOrIndexLabel>
inline Index(IndexOrIndexLabel &&index_or_index_label, IndexSpace space)

constructs an Index using an existing Index’s label and proto indices (if any) and an IndexSpace

Template Parameters:

IndexOrIndexLabel – either Index or a type that can be viewed/converted to a string (i.e., meta::is_basic_string_convertible_v<std::decay_t<IndexOrIndexLabel>>==true)

Parameters:

  • index_or_index_label – [in] an Index object or a label

  • space – (a const ref to) the IndexSpace object that specifies the space to which ths object refers to

inline explicit operator bool() const

return true if this is non-null

Returns:

true if *this != null

inline bool nonnull() const
Returns:

true if *this != null

inline Index replace_space(IndexSpace space) const

constructs an Index using this object’s label and proto indices (if any) and a new IndexSpace

Parameters:

space – (a const ref to) the IndexSpace object that specifies the space to which ths object refers to

inline Index replace_qns(QuantumNumbersAttr qns) const

constructs an Index using this object’s label and proto indices (if any), its IndexSpaceType, and a new set of QuantumNumbers

inline Taggable &tag()
Returns:

this cast to Taggable&

inline const Taggable &tag() const
Returns:

this cast to const Taggable&

inline void reset_tag() const

resets tag of this and its protoindices (if any)

Note

do this->tag().reset() if you only want to reset tag on this (not its protoindices)

inline std::wstring_view label() const

Note

label format is base or base_ordinal

Warning

this does not include the proto index labels, use Index::full_label() instead

Returns:

the memoized label as a UTF-8 encoded wide-character string

inline std::optional<ordinal_type> ordinal() const noexcept
Returns:

the ordinal

std::string ascii_label() const

Replaces non-ascii wstring characters with human-readable analogs, each such UTF-8 character will be encoded by one or more chars.

Note

Maps: ↑ -> a, ↓ -> b, and all greek characters to their english language equivalents (e.g. α -> alpha, Ξ -> XI, etc.)

Warning

not to be used with proto indices

Returns:

A string label representable in ASCII encoding

std::string to_string() const

Note

equivalent to sequant::to_string(this->label())

Warning

not to be used with proto indices

Returns:

A UTF-8 encoded narrow-character string label

inline std::wstring_view full_label() const

Warning

this includes the proto index labels (if any), use Index::label() instead if only want the label

Returns:

the full label as a UTF-8 encoded wide-character string

template<typename WS, typename = std::enable_if_t<(meta::is_wstring_convertible_v<std::decay_t<WS>>)>>
inline std::wstring make_label_plus_suffix(WS &&suffix) const

makes a new label by appending a suffix to the label

Appends suffix to the label itself (if plain) or to its core (if composite)

Parameters:

suffix – a string to append to the label

Returns:

this->label() with suffix appended

template<typename WS, typename = std::enable_if_t<(meta::is_wstring_convertible_v<std::decay_t<WS>>)>>
inline std::wstring make_label_minus_substring(WS &&substr) const

makes a new label by removing a substring from the label

Removes substr from the label itself (if plain) or from its core (if composite)

Parameters:

substr – a string to remove from the label

Returns:

this->label() with substr removed

inline const IndexSpace &space() const noexcept
Returns:

the IndexSpace object

inline bool has_proto_indices() const noexcept
Returns:

true if this index has proto indices

inline const index_vector &proto_indices() const noexcept
Returns:

the list of proto indices of this index

inline bool symmetric_proto_indices() const noexcept
Returns:

true if the index is symmetric with respect to the permutation of protoindices

inline Index drop_proto_indices() const noexcept

drops the proto indices from this Index

Returns:

a copy of this Index without proto indices

std::wstring to_latex() const noexcept
inline auto proto_indices_color() const

See also

Index::color()

Returns:

the color of the protoindices

inline auto color() const

Color of an Index = hashed IndexSpace + IndexSpace objects of the protoindices

Returns:

the color of this object

template<template<typename, typename, typename ...Args> class Map, typename ...Args>
inline bool transform(const Map<Index, Index, Args...> &index_map) noexcept

index replacement replaces this object with its image in the Index map. If this object was not found in the map, tries replacing its subindices.

Parameters:

index_map – maps Index to Index

Returns:

false if no replacements were made

Pre:
this->tag().has_value() == false ||
(this->tag().has_value() == true && this->tag().value<int>() == 0)
Post:

if return value is true: 

this->tag().has_value() == true &&
this->tag().value<int>() == 0

Public Static Functions

static inline std::optional<std::size_t> get_ordinal(std::wstring_view label)
Returns:

Ordinal of the index corresponding to the provided label. If the label is malformed, returns nullopt.

static inline Index make_tmp_index(const IndexSpace &space)

creates a globally-unique temporary index in space space . The label of the resulting index = IndexSpace::base_key(space) + ‘_’ + temporary counter. Each call increments the current tmp counter (see next_tmp_index() ) . To make neater temporary indices unique in a given scope (e.g. a single term in an expression) use IndexFactory.

Parameters:

space – an IndexSpace object

Returns:

a unique temporary index in space space

template<typename IndexRange, typename = std::enable_if_t<meta::is_range_v<std::remove_reference_t<IndexRange>>>>
static inline Index make_tmp_index(const IndexSpace &space, IndexRange &&proto_indices, bool symmetric_proto_indices = true)

creates a globaly-unique temporary index in space space . The label of the resulting index = IndexSpace::base_key(space) + ‘_’ + temporary counter. Each call increments the current tmp counter (see next_tmp_index() ) . To make neater temporary indices unique in a given scope (e.g. a single term in an expression) use IndexFactory.

Parameters:

  • space – an IndexSpace object

  • proto_indices – list of proto indices (all must be unique, i.e. duplicates are not allowed)

  • symmetric_proto_indices – if true, proto_indices can be permuted at will and will always be sorted

Returns:

a unique temporary index in space space

static inline std::wstring base_label(std::wstring_view label)
Parameters:

label – an Index label (e.g., returned by Index::label())

Returns:

base part of label

static inline std::wstring base_label(std::string_view label)
Parameters:

label – an Index label (e.g., returned by Index::label())

Returns:

base part of label

template<typename Char, typename = std::enable_if_t<meta::is_char_v<Char>>>
static inline std::wstring base_label(Char label)
template<typename WS1, typename WS2, typename = std::enable_if_t<(meta::is_wstring_or_view_v<std::decay_t<WS1>> && meta::is_wstring_convertible_v<std::decay_t<WS2>>)>>
static inline std::wstring make_label_plus_suffix(WS1 &&label, WS2 &&suffix)

makes a new label by appending a suffix to the label

Appends suffix to label itself (if plain) or to its core (if composite)

Parameters:

  • label – the label to append the suffix to

  • suffix – a string to append to the label

Returns:

this->label() with suffix appended

template<typename WS1, typename WS2, typename = std::enable_if_t<(meta::is_wstring_or_view_v<std::decay_t<WS1>> && meta::is_wstring_convertible_v<std::decay_t<WS2>>)>>
static inline std::wstring make_label_minus_substring(WS1 &&label, WS2 &&substr)

makes a new label by removing a substring from the label

Removes substr from label itself (if plain) or from its core (if composite)

Parameters:

  • label – the label to remove the substring from

  • substr – a string to remove from the label

Returns:

this->label() with substr removed

template<typename Range>
static inline auto proto_indices_color(const Range &protoindex_range) noexcept

See also

Index::color()

Parameters:

protoindex_range – a range of Index objects

Returns:

the color of the protoindices

static std::size_t min_tmp_index() noexcept
Returns:

the smallest index of a generated index

static inline std::size_t next_tmp_index() noexcept
Returns:

a unique temporary index, its value is equal to or greater than that returned by min_tmp_index()

static void reset_tmp_index() noexcept

resets the temporary index counter so that the next call to next_tmp_index() will return the value returned by min_tmp_index()

Warning

should only to be used when reproducibility matters (e.g. unit testing)

Public Static Attributes

static const IndexSpace::Attr default_space_attr = {IndexSpace::Attr::reserved}

With default context (i.e., in absence of an index space registry) will use this attribute to generate IndexSpace of indices from their labels

static const Index null
struct FullLabelCompare

compares Index objects using full labels only

See also

Index::full_label()

Note

since full label is defined by the space, ordinal, and protoindices only (i.e. tags are ignored) comparison uses them directly for efficiency

Public Functions

inline bool operator()(const Index &first, const Index &second) const
struct LabelCompare

compares Index objects using their labels

See also

Index::label()

Note

since label is defined by the space and ordinal only (i.e. protoindices and tags are ignored) comparison uses them directly for efficiency

Public Functions

inline bool operator()(const Index &first, const Index &second) const
struct TypeCompare

compares Index objects using type only (but since type is defined by the values of proto indices those are not ignored)

Public Functions

inline bool operator()(const Index &first, const Index &second) const
struct TypeEquality

tests equality of Index objects using type only (but since type is defined by the values of proto indices those are not ignored)

Public Functions

inline bool operator()(const Index &first, const Index &second) const