Class IndexSpaceRegistry

Class Documentation

class IndexSpaceRegistry

set of known IndexSpace objects

Each IndexSpace object has hardwired base key (label) that gives indexed expressions appropriate semantics; e.g., spaces referred to by indices in \( t_{p_1}^{i_1} \) are defined if IndexSpace objects with base keys \( p \) and \( i \) are registered. Since index spaces have set-theoretic semantics, the user must provide complete set of unions/intersects of the base spaces to cover all possible IndexSpace objects that can be generated in their program.

Registry contains 2 parts: set of IndexSpace objects (managed by a std::shared_ptr, see IndexSpaceRegistry::spaces()) and specification of various spaces (vacuum, reference, complete, etc.). Copy semantics is thus partially shallow, with spaces shared between copies. This allows to have multiple registries share same set of spaces but have different specifications of vacuum, reference, etc.; this is useful for providing different contexts for fermions and bosons, for example.

adding IndexSpace objects to the registry

inline IndexSpaceRegistry &add(const IndexSpace &IS)

add an IndexSpace to this registry.

Parameters:

IS – an IndexSpace

Throws:

std::invalid_argument – if IS.base_key() or IS.attr() matches an already registered IndexSpace

Returns:

reference to this

template<typename S, typename ...OptionalArgs, typename = meta::EnableIfAllBasicStringConvertible<S>>
inline IndexSpaceRegistry &add(S &&type_label, IndexSpace::Type type, OptionalArgs&&... args)

add an IndexSpace to this registry.

Parameters:

  • type_label – a label that will denote the space type, must be convertible to a std::string

  • type – an IndexSpace::Type

  • args – optional arguments consisting of a mix of zero or more of the following:

    • IndexSpace::QuantumNumbers

    • approximate size of the space (unsigned long)

    • any of { is_vacuum_occupied , is_reference_occupied , is_complete , is_hole , is_particle }

Throws:

std::invalid_argument – if type_label or type matches an already registered IndexSpace

Returns:

reference to this

template<typename S, typename IndexSpaceOrLabel, typename ...OptionalArgs, typename = meta::EnableIfAllBasicStringConvertible<S>, typename = std::enable_if_t<(std::is_same_v<std::decay_t<IndexSpaceOrLabel>, IndexSpace> || meta::is_basic_string_convertible_v<std::decay_t<IndexSpaceOrLabel>>)>>
inline IndexSpaceRegistry &add_unIon(S &&type_label, std::initializer_list<IndexSpaceOrLabel> components, OptionalArgs&&... args)

add a union of IndexSpace objects to this registry.

Parameters:

  • type_label – a label that will denote the space type, must be convertible to a std::string

  • components – sequence of IndexSpace objects or labels (known to this) whose union will be known by type_label

  • args – optional arguments consisting of a mix of zero or more of { is_vacuum_occupied , is_reference_occupied , is_complete , is_hole , is_particle }

Returns:

reference to this

template<typename S, typename IndexSpaceOrLabel, typename ...OptionalArgs, typename = meta::EnableIfAllBasicStringConvertible<S>, typename = std::enable_if_t<(std::is_same_v<std::decay_t<IndexSpaceOrLabel>, IndexSpace> || meta::is_basic_string_convertible_v<std::decay_t<IndexSpaceOrLabel>>)>>
inline IndexSpaceRegistry &add_union(S &&type_label, std::initializer_list<IndexSpaceOrLabel> components, OptionalArgs&&... args)

alias to add_unIon

template<typename S, typename IndexSpaceOrLabel, typename ...OptionalArgs, typename = meta::EnableIfAllBasicStringConvertible<S>, typename = std::enable_if_t<(std::is_same_v<std::decay_t<IndexSpaceOrLabel>, IndexSpace> || meta::is_basic_string_convertible_v<std::decay_t<IndexSpaceOrLabel>>)>>
inline IndexSpaceRegistry &add_intersection(S &&type_label, std::initializer_list<IndexSpaceOrLabel> components, OptionalArgs&&... args)

add a union of IndexSpace objects to this registry.

Parameters:

  • type_label – a label that will denote the space type, must be convertible to a std::string

  • components – sequence of IndexSpace objects or labels (known to this) whose intersection will be known by type_label

  • args – optional arguments consisting of a mix of zero or more of { is_vacuum_occupied , is_reference_occupied , is_complete , is_hole , is_particle }

Returns:

reference to this

specifies which spaces have nonzero occupancy in the vacuum wave

function

Note

needed for applying Wick theorem with Fermi vacuum

inline IndexSpaceRegistry &vacuum_occupied_space(const IndexSpace::Type &t)
Parameters:

t – an IndexSpace::Type specifying which base spaces have nonzero occupancy in the vacuum wave function by default (i.e. for any quantum number choice); to specify occupied space per specific QN set use the other overload

Returns:

reference to this

inline IndexSpaceRegistry &vacuum_occupied_space(std::map<IndexSpace::QuantumNumbers, IndexSpace::Type> qn2type)
Parameters:

qn2type – for each quantum number specifies which base spaces have nonzero occupancy in the reference wave function

Returns:

reference to this

inline IndexSpaceRegistry &vacuum_occupied_space(const IndexSpace &s)

equivalent to vacuum_occupied_space(s.type())

Note

QuantumNumbers attribute of s ignored

Parameters:

s – an IndexSpace

Returns:

reference to this

template<typename S, typename = meta::EnableIfAllBasicStringConvertible<S>>
inline IndexSpaceRegistry &vacuum_occupied_space(S &&l)

equivalent to vacuum_occupied_space(retrieve(l).type())

Parameters:

l – label of a known IndexSpace

Returns:

reference to this

inline const IndexSpace::Type &vacuum_occupied_space(bool nulltype_ok = false) const
Throws:

std::invalid_argument – if nulltype_ok is false and vacuum_occupied_space had not been specified

Returns:

the space occupied in vacuum state for any set of quantum numbers

inline const IndexSpace &vacuum_occupied_space(const IndexSpace::QuantumNumbers &qn) const
Parameters:

qn – the quantum numbers of the space

Returns:

the space occupied in vacuum state for the given set of quantum numbers

assign which spaces have nonzero occupancy in the reference wave

function (i.e., the wave function uses to compute reference expectation value)

Note

needed for computing expectation values when the vacuum state does not match the wave function of interest.

inline IndexSpaceRegistry &reference_occupied_space(const IndexSpace::Type &t)
Parameters:

t – an IndexSpace::Type specifying which base spaces have nonzero occupancy in the reference wave function by default (i.e., for any choice of quantum numbers); to specify occupied space per specific QN set use the other overload

Returns:

reference to this

inline IndexSpaceRegistry &reference_occupied_space(std::map<IndexSpace::QuantumNumbers, IndexSpace::Type> qn2type)
Parameters:

qn2type – for each quantum number specifies which base spaces have nonzero occupancy in the reference wave function

Returns:

reference to this

inline IndexSpaceRegistry &reference_occupied_space(const IndexSpace &s)

equivalent to reference_occupied_space(s.type())

Note

QuantumNumbers attribute of s ignored

Parameters:

s – an IndexSpace

Returns:

reference to this

template<typename S, typename = meta::EnableIfAllBasicStringConvertible<S>>
inline IndexSpaceRegistry &reference_occupied_space(S &&l)

equivalent to reference_occupied_space(retrieve(l).type())

Parameters:

l – label of a known IndexSpace

Returns:

reference to this

inline const IndexSpace::Type &reference_occupied_space(bool nulltype_ok = false) const
Throws:

std::invalid_argument – if nulltype_ok is false and reference_occupied_space had not been specified

Returns:

the space occupied in reference state for any set of quantum numbers

inline const IndexSpace &reference_occupied_space(const IndexSpace::QuantumNumbers &qn) const
Parameters:

qn – the quantum numbers of the space

Returns:

the space occupied in vacuum state for the given set of quantum numbers

specifies which spaces comprise the entirety of Hilbert space

Note

needed for creating general operators in mbpt/op

inline IndexSpaceRegistry &complete_space(const IndexSpace::Type &s)
Parameters:

s – an IndexSpace::Type specifying the complete Hilbert space; to specify occupied space per specific QN set use the other overload

inline IndexSpaceRegistry &complete_space(std::map<IndexSpace::QuantumNumbers, IndexSpace::Type> qn2type)
Parameters:

qn2type – for each quantum number specifies which base spaces have nonzero occupancy in the reference wave function

inline IndexSpaceRegistry &complete_space(const IndexSpace &s)

equivalent to complete_space(s.type())

Note

QuantumNumbers attribute of s ignored

Parameters:

s – an IndexSpace

Returns:

reference to this

template<typename S, typename = meta::EnableIfAllBasicStringConvertible<S>>
inline IndexSpaceRegistry &complete_space(S &&l)

equivalent to complete_space(retrieve(l).type())

Parameters:

l – label of a known IndexSpace

Returns:

reference to this

inline const IndexSpace::Type &complete_space(bool nulltype_ok = false) const
Throws:

std::invalid_argument – if nulltype_ok is false and complete_space had not been specified

Returns:

the complete Hilbert space for any set of quantum numbers

inline const IndexSpace &complete_space(const IndexSpace::QuantumNumbers &qn) const
Parameters:

qn – the quantum numbers of the space

Returns:

the complete Hilbert space for the given set of quantum numbers

specifies in which space holes can be created successfully from the

reference wave function

Note

convenience for making operators

inline IndexSpaceRegistry &hole_space(const IndexSpace::Type &t)
Parameters:

t – an IndexSpace::Type specifying where holes can be created; to specify hole space per specific QN set use the other overload

inline IndexSpaceRegistry &hole_space(std::map<IndexSpace::QuantumNumbers, IndexSpace::Type> qn2type)
Parameters:

qn2type – for each quantum number specifies the space in which holes can be created

inline IndexSpaceRegistry &hole_space(const IndexSpace &s)

equivalent to hole_space(s.type())

Note

QuantumNumbers attribute of s ignored

Parameters:

s – an IndexSpace

Returns:

reference to this

template<typename S, typename = meta::EnableIfAllBasicStringConvertible<S>>
inline IndexSpaceRegistry &hole_space(S &&l)

equivalent to hole_space(retrieve(l).type())

Parameters:

l – label of a known IndexSpace

Returns:

reference to this

inline const IndexSpace::Type &hole_space(bool nulltype_ok = false) const
Throws:

std::invalid_argument – if nulltype_ok is false and hole_space had not been specified

Returns:

default space in which holes can be created

inline const IndexSpace &hole_space(const IndexSpace::QuantumNumbers &qn) const
Parameters:

qn – the quantum numbers of the space

Returns:

the space in which holes can be created for the given set of quantum numbers

specifies in which space particles can be created successfully from

the reference wave function

Note

convenience for making operators

inline IndexSpaceRegistry &particle_space(const IndexSpace::Type &t)
Parameters:

t – an IndexSpace::Type specifying where particles can be created; to specify particle space per specific QN set use the other overload

inline IndexSpaceRegistry &particle_space(std::map<IndexSpace::QuantumNumbers, IndexSpace::Type> qn2type)
Parameters:

qn2type – for each quantum number specifies the space in which particles can be created

inline IndexSpaceRegistry &particle_space(const IndexSpace &s)

equivalent to particle_space(s.type())

Note

QuantumNumbers attribute of s ignored

Parameters:

s – an IndexSpace

Returns:

reference to this

template<typename S, typename = meta::EnableIfAllBasicStringConvertible<S>>
inline IndexSpaceRegistry &particle_space(S &&l)

equivalent to particle_space(retrieve(l).type())

Parameters:

l – label of a known IndexSpace

Returns:

reference to this

inline const IndexSpace::Type &particle_space(bool nulltype_ok = false) const
Throws:

std::invalid_argument – if nulltype_ok is false and particle_space had not been specified

Returns:

default space in which particles can be created

inline const IndexSpace &particle_space(const IndexSpace::QuantumNumbers &qn) const
Parameters:

qn – the quantum numbers of the space

Returns:

the space in which particles can be created for the given set of quantum numbers

Public Functions

inline IndexSpaceRegistry()

default constructor creates a registry containing only IndexSpace::null

Note

null space is registered so we don’t have to handle it as a corner case in retrieve() and other methods

inline IndexSpaceRegistry(std::shared_ptr<container::set<IndexSpace, IndexSpace::KeyCompare>> spaces)

constructs an IndexSpaceRegistry from an existing set of IndexSpace objects

inline IndexSpaceRegistry(const IndexSpaceRegistry &other)

copy constructor

inline IndexSpaceRegistry(IndexSpaceRegistry &&other)

move constructor

inline IndexSpaceRegistry &operator=(const IndexSpaceRegistry &other)

copy assignment operator

inline IndexSpaceRegistry &operator=(IndexSpaceRegistry &&other)

move assignment operator

inline const auto &spaces() const
inline decltype(auto) begin() const
inline decltype(auto) end() const
template<typename S, typename = meta::EnableIfAllBasicStringConvertible<S>>
inline const IndexSpace *retrieve_ptr(S &&label) const

retrieve a pointer to IndexSpace from the registry by the label

Parameters:

label – a base_key of an IndexSpace, or a label of an Index (see Index::label() )

Returns:

pointer to IndexSpace associated with that key, or nullptr if not found

template<typename S, typename = meta::EnableIfAllBasicStringConvertible<S>>
inline IndexSpace *retrieve_ptr(S &&label)

retrieve a pointer to IndexSpace from the registry by the label

Parameters:

label – a base_key of an IndexSpace, or a label of an Index (see Index::label() )

Returns:

pointer to IndexSpace associated with that key, or nullptr if not found

template<typename S, typename = meta::EnableIfAllBasicStringConvertible<S>>
inline const IndexSpace &retrieve(S &&label) const

retrieve an IndexSpace from the registry by the label

Parameters:

label – a base_key of an IndexSpace, or a label of an Index (see Index::label() )

Throws:

IndexSpace::bad_key – if matching space is not found

Returns:

IndexSpace associated with that key

inline const IndexSpace *retrieve_ptr(const IndexSpace::Type &type, const IndexSpace::QuantumNumbers &qns) const

retrieve a pointer to IndexSpace from the registry by its type and quantum numbers

Parameters:
Returns:

pointer to the IndexSpace associated with that key, or nullptr if not found

inline const IndexSpace &retrieve(const IndexSpace::Type &type, const IndexSpace::QuantumNumbers &qns) const

retrieve an IndexSpace from the registry by its type and quantum numbers

Parameters:
Throws:

std::invalid_argument – if matching space is not found

Returns:

IndexSpace associated with that key.

inline const IndexSpace *retrieve_ptr(const IndexSpace::Attr &space_attr) const

retrieve pointer to the IndexSpace from the registry by the IndexSpace::Attr

Parameters:

space_attr – an IndexSpace::Attr

Returns:

pointer to the IndexSpace associated with that key, or nullptr if not found

inline const IndexSpace &retrieve(const IndexSpace::Attr &space_attr) const

retrieve an IndexSpace from the registry by the IndexSpace::Attr

Parameters:

space_attr – an IndexSpace::Attr

Throws:

std::invalid_argument – if matching space is not found

Returns:

IndexSpace associated with that key.

template<typename S, typename = meta::EnableIfAllBasicStringConvertible<S>>
inline bool contains(S &&label) const

queries presence of a registered IndexSpace

Parameters:

label – a base_key of an IndexSpace, or a label of an Index (see Index::label() )

Returns:

true, if an IndexSpace with key label is registered

inline bool contains(const IndexSpace &space) const

queries presence of a registered IndexSpace

Parameters:

space – an IndexSpace object

Returns:

true, if an IndexSpace with key {type,qns} is registered

inline bool contains(const IndexSpace::Type &type, const IndexSpace::QuantumNumbers &qns) const

queries presence of a registered IndexSpace

Parameters:
Returns:

true, if an IndexSpace with key {type,qns} is registered

inline bool contains(const IndexSpace::Attr &space_attr) const

queries presence of a registered IndexSpace

Parameters:

space_attr – an IndexSpace::Attr object

Returns:

true, if an IndexSpace with key space_attr is registered

inline IndexSpaceRegistry &remove(const IndexSpace &IS)

removes an IndexSpace associated with IS.base_key() from this

Parameters:

IS – an IndexSpace

Returns:

reference to this

template<typename S, typename = meta::EnableIfAllBasicStringConvertible<S>>
inline IndexSpaceRegistry &remove(S &&label)

equivalent to remove(this->retrieve(label))

Parameters:

label – space label

Returns:

reference to this

inline IndexSpaceRegistry &replace(const IndexSpace &IS)

replaces an IndexSpace registered in the registry under IS.base_key() with IS

Parameters:

IS – an IndexSpace

Returns:

reference to this

inline const std::vector<IndexSpace::Type> &base_space_types() const

returns the list of basis IndexSpace::Type objects

A base IndexSpace::Type object has 1 bit in its bitstring.

See also

IndexSpaceRegistry::is_base

Returns:

(memoized) set of base IndexSpace::Type objects, sorted in increasing order

inline const std::vector<IndexSpace> &base_spaces() const

returns the list of basis IndexSpace objects

A base IndexSpace object has 1 bit in its type() bitstring.

See also

IndexSpaceRegistry::is_base

Returns:

(memoized) set of base IndexSpace objects, sorted in the order of increasing type()

inline IndexSpaceRegistry &clear()

clear the contents of *this

Returns:

reference to this

inline bool valid_intersection(const IndexSpace &space1, const IndexSpace &space2) const

queries if the intersection space is registered

Parameters:

  • space1 –

  • space2 –

Returns:

true if space1.intersection(space2) is registered

inline const IndexSpace &intersection(const IndexSpace &space1, const IndexSpace &space2) const

return the resulting space corresponding to a bitwise intersection between two spaces.

Note

can return nullspace

Note

throw invalid_argument if the nonnull intersection is not registered

Parameters:
Returns:

the intersection of space1 and space2

template<typename S1, typename S2, typename = meta::EnableIfAllBasicStringConvertible<S1, S2>>
inline const IndexSpace &intersection(S1 &&space1_key, S2 &&space2_key) const

Note

can return nullspace

Note

throw invalid_argument if the nonnull intersection is not registered

Parameters:

  • space1_key – base key of a registered IndexSpace

  • space2_key – base key of a registered IndexSpace

Returns:

the intersection of space1 and space2

inline bool valid_unIon(const IndexSpace &space1, const IndexSpace &space2) const

is a union between spaces eligible and registered

Parameters:

  • space1 –

  • space2 –

Returns:

true if space is constructable and registered

inline const IndexSpace &unIon(const IndexSpace &space1, const IndexSpace &space2) const

Note

can only return registered spaces

Note

never returns nullspace

Parameters:

  • space1 –

  • space2 –

Returns:

the union of two spaces.

template<typename S1, typename S2, typename = meta::EnableIfAllBasicStringConvertible<S1, S2>>
inline const IndexSpace &unIon(S1 &&space1_key, S2 &&space2_key) const

Note

can only return registered spaces

Note

never returns nullspace

Parameters:

  • space1_key – base key of a registered IndexSpace

  • space2_key – base key of a registered IndexSpace

Returns:

the union of two spaces.

inline bool is_pure_occupied(const IndexSpace &IS) const

an IndexSpace is occupied with respect to the fermi vacuum or a subset of that space

Note

only makes sense to ask this if in a SingleProduct vacuum context.

inline bool is_pure_unoccupied(const IndexSpace &IS) const

all states are unoccupied in the fermi vacuum

Note

again, this only makes sense to ask if in a SingleProduct vacuum context.

inline bool contains_occupied(const IndexSpace &IS) const

some states are fermi vacuum occupied

inline bool contains_unoccupied(const IndexSpace &IS) const

some states are fermi vacuum unoccupied

inline const IndexSpace &vacuum_unoccupied_space(const IndexSpace::QuantumNumbers &qn) const
Returns:

the space that is unoccupied in the vacuum state

Public Static Functions

static inline bool is_base(const IndexSpace &IS)

checks if an IndexSpace is in the basis

See also

base_spaces

Parameters:

IS – IndexSpace

Returns:

true if IS is in the basis

static inline bool is_base(const IndexSpace::Type &t)

checks if an IndexSpace::Type is in the basis

See also

space_type_basis

Parameters:

t – IndexSpace::Type

Returns:

true if t is in the basis