Class Context¶

Defined in File context.hpp

Nested Relationships¶

Nested Types¶

Class Documentation¶

class Context¶

Specifies SeQuant context, such as vacuum choice, whether index spaces are orthonormal, sizes of index spaces, etc.

SeQuant context contains the following information:

a IndexBasisRegistry object: contains information about the known IndexSpace objects and their attributes; managed by shared_ptr and shared by the copies of a context. A context owns its registry: it moves or copies in a registry it is given, and adopts a shared_ptr to one only if that is the registry’s only owner, so the registry cannot change while any context uses it (short of what Context::set(std::shared_ptr<const IndexBasisRegistry>) warns about).
vacuum: the vacuum state used to define normal ordering of NormalOperators
deserialization_symmetry, deserialization_hermiticity, deserialization_column_symmetry: the symmetries given to a deserialized tensor that does not specify them; the programmatic Tensor ctors are unaffected (see Tensor::Defaults), hence the deserialization_ prefix. There is no braket_symmetry knob: a tensor’s BraKetSymmetry is derived from its Hermiticity and base field.
spbasis: whether the bra/ket bases are spinor (SPBasis::Spinor) or spin-free (SPBasis::Spinfree).
first_dummy_index_ordinal: during its operation SeQuant will generate temporary indices with orbitals greater or equal to this; to avoid duplicates user Index objects should have ordinals smaller than this
canonicalization_options: if set, this specifies the default options to use for canonicalization of expressions.
braket_typesetting: whether to_latex() typesets tensor indices of ket (covariant, primal) modes as superscript (BraKetTypesetting::KetSuper, default)
braket_slot_typesetting: whether to_latex() typesets tensor indices using tensor LaTeX package (BraKetSlotTypesetting::TensorPackage, default) or native typesetting (BraKetSlotTypesetting::Naive); the former is preferred for alignment of superscript with subscript slots.
tensor_canonicalizers: the TensorCanonicalizer objects applied to tensors, keyed by tensor label; the one keyed by the empty label applies to tensors without a label-specific canonicalizer. The canonicalizer objects are shared by copies of the context and must not be mutated. The empty label maps to a DefaultTensorCanonicalizer unless a map given to the constructor sets it; unset_tensor_canonicalizer() can remove it.
index_comparer, index_pair_comparer: the objects that order Index objects (and pairs thereof) during tensor canonicalization; default to TensorCanonicalizer::default_index_comparer() and TensorCanonicalizer::default_index_pair_comparer().
cardinal_tensor_labels: Tensor labels with lexicographic preference (in order); default to {reserved::antisymm_label(), reserved::symm_label(), reserved::transposition_label()}.

Note

canonicalization reads tensor_canonicalizers, index_comparer, index_pair_comparer and cardinal_tensor_labels only from the default context for Statistics::Arbitrary; in a context installed for another Statistics they are currently ignored, but keep them identical to those of the Statistics::Arbitrary context, since a future version may consult the statistics-specific context first

Public Functions

Context(Options options = make_default_options())¶

standard named-parameter constructor

Warning

default constructor does not create an IndexBasisRegistry, thus this->index_basis_registry() will return nullptr Example:

Context ctx({.vacuum = Vacuum::SingleProduct, .spbasis = SPBasis::Spinfree});

~Context() = default¶

Context(const Context &ctx) = default¶

copy constructor

Note

created Context uses the same index basis registry as ctx

Parameters:: ctx – [in] a Context

Context &operator=(const Context &ctx) = default¶

copy assignment

Note

this object will use the same index basis registry as ctx

Parameters:: ctx – [in] a Context
Returns:: reference to this object

std::uint64_t version() const¶

Note

the other settings (vacuum, first dummy index ordinal, typesetting, deserialization defaults, strict bra-ket checks) do not affect the version

Note

the version does not track in-place mutation of a TensorCanonicalizer or comparer object that this context refers to

Returns:: the version of this context’s canonicalization configuration: a nonzero number that two contexts share if and only if canonicalization sees the same configuration in both, i.e. they have the same index space registry, tensor canonicalizers and index comparers (the same objects), cardinal tensor labels, canonicalization options and SP basis (which determines the symmetry of NormalOperator); a number is never reused for another configuration

Vacuum vacuum() const¶

Returns:: Vacuum of this context

std::shared_ptr<const IndexBasisRegistry> index_basis_registry() const¶

Note

the registry does not change; to change it, set a modified copy

Warning

can be null when user did not provide one to Context (i.e., it was default constructed)

Returns:: a constant pointer to the IndexBasisRegistry for this context

inline std::shared_ptr<const IndexBasisRegistry> index_space_registry() const¶

Deprecated:: use index_basis_registry()

bool assert_strict_braket_symmetry() const¶

Note

disabling strict bra-ket symmetry assertions is a bad idea if working with complex-valued tensors, or nonunit metric, or in general

Warning

if SeQuant was configured with SEQUANT_ASSERT_BEHAVIOR=IGNORE the strict bra-ket contraction checks are turned off even if this returns true

Returns:: true if strict bra-ket symmetry is asserted; setting this to false (via Context::set(AssertStrictBraKetSymmetry::No)) allows arbitrary contractions of bra/ket modes as if they were aux indices.

SPBasis spbasis() const¶

Returns:: SPBasis of this context

std::size_t first_dummy_index_ordinal() const¶

Returns:: first ordinal of the dummy indices generated by calls to Index::next_tmp_index when this context is active

std::optional<CanonicalizeOptions> canonicalization_options() const¶

Returns:: canonicalization options to use by default, if nonnull

BraKetTypesetting braket_typesetting() const¶

Returns:: BraKetTypesetting of this context; if this returns BraKetTypesetting::ContraSub covariant (ket, creation) and contravariant (bra, annihilation) indices are typeset in superscript and subscript LaTeX, respectively.

BraKetSlotTypesetting braket_slot_typesetting() const¶

Returns:: BraKetSlotTypesetting of this context; see BraKetSlotTypesetting for the meaning of the possible values

Symmetry deserialization_symmetry() const¶

Returns:: the default bra/ket permutational Symmetry for deserialized tensors; programmatic Tensor construction is unaffected by it

Hermiticity deserialization_hermiticity() const¶

Returns:: the default Hermiticity for deserialized tensors; the braket symmetry of a deserialized tensor is derived from this and its base_field. Programmatic Tensor construction is unaffected by it

ColumnSymmetry deserialization_column_symmetry() const¶

Returns:: the default ColumnSymmetry (particle-permutation symmetry) for deserialized tensors; programmatic Tensor construction is unaffected by it

std::shared_ptr<TensorCanonicalizer> tensor_canonicalizer_ptr(std::wstring_view label) const¶

Parameters:: label – a Tensor label
Returns:: the TensorCanonicalizer for label if any, else the one for the empty label; null if neither exists

std::shared_ptr<TensorCanonicalizer> nondefault_tensor_canonicalizer_ptr(std::wstring_view label) const¶