Custom Operator Registry Support

[ajay-mk]

Custom Operator Registry Support

This PR refactors Operator logic from depending on a predefined OpType enum to a runtime OpRegistry, enabling users to define custom operators beyond the predefined set.

Major Changes

• OpRegistry: a registry for operator labels and their classifications
• mbpt::Context now holds an OpRegistry along with the CSV setting.
• There are two predefined registries available (minimal and legacy).
• Some labels are reserved for internal use (antisymmetrizer, symmetrizer, transposition, kroneker, overlap), and cannot be registered.
• OpType enum is removed, all related logic is gone:
  • OpMaker constructors now use strings.
  • OpConnections now uses strings to specify operator pairs. For example: {{L"f", L"A"}, {L"g", L"A"}, ...}
• Built-in operators (both tensor and Operator level) check the registry if operators are registered.
• Perturbation-related operators now support higher-order perturbations (up to 9).
• mbpt::Context manipulations are thread-safe, and can be toggled by SEQUANT_CONTEXT_MANIPULATION_THREADSAFE option; follows the same pattern as core::Context.

Example Usage

    using namespace sequant;
    using namespace sequant::mbpt;
   
    auto registry = std::make_shared<OpRegistry>();

    registry->add(L"f", OpClass::gen)
        .add(L"g", OpClass::gen)
        .add(L"t", OpClass::ex)
        .add(L"x", OpClass::ex)
        .add(L"y", OpClass::ex);

    // set MBPT context
    auto ctx_resetter = set_scoped_default_mbpt_context(
        {.csv = CSV::No, .op_registry_ptr = registry});

    // use OpMaker to define a custom excitation operator of rank 2
    auto x = OpMaker<Statistics::FermiDirac>(L"x", 2)();

    // particle non-conserving excitation operator with custom IndexSpaces
    const auto& cre_space = get_particle_space(Spin::any);
    const auto& ann_space = get_hole_space(Spin::any);

    auto y = OpMaker<Statistics::FermiDirac>(L"y", ncre(2), nann(1),
                                             cre(cre_space), ann(ann_space))();

Additional Changes

• The antisymmetrizer and symmetrizer labels have been updated to Â and Ŝ, respectively. As a result, several tests and examples were updated. Most hardcoded strings were replaced with calls to the reserved label methods; however, some reference outputs and expressions are still constructed from plain strings.
• In the TNC tests, the reference GraphViz output needed to be updated with the new label and the newly assigned color for the tensor. The rest of the graph remains unchanged.
• The spin-tracing examples in tests/integration were not using mbpt::cardinal_tensor_labels() for expression canonicalization. After the label change, symmetrizer and antisymmetrizer tensors were moved to the end during canonicalization. Since the spin-tracing logic assumes all symmetrizer tensors share the same external indices, they must appear first. This was fixed by canonicalizing with mbpt::cardinal_tensor_labels(), which places symmetrizer tensors first and ensures consistent indexing.
• Some evaluation logic also requires canonical ordering. Accordingly, the eval_{ta,btas} cases now use mbpt::cardinal_tensor_labels() with TNC.
• To ensure consistent indexing of antisymmetrizer/symmetrizer tensors across a Sum, they need to appear first in a Product. When the labels were changed, they appeared at the end of a Product, which caused problems in spin-tracing and eval logic (see the striked points). To prevent this, antisymmetrizer/symmetrizer labels are prepended to the cardinal tensor labels list when set_cardinal_tensor_labels() is called.
• If no list is set, the default cardinal tensor label list will contain antisymmetrizer/symmetrizer labels.
• The trace_product spin-tracing logic assumed that the symmetrizer tensor always appears first; this has been generalized. cc: @ABesharat
• The external interface was updated to use reserved labels instead of hardcoded ones, and the labels in the example inputs were updated accordingly.

[Copilot]

Pull request overview

Copilot reviewed 61 out of 61 changed files in this pull request and generated 5 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[evaleev]

@ajay-mk @Krzmbrzl hat seems to confuse the parser? https://github.com/ValeevGroup/SeQuant/actions/runs/21360724502/job/61479058146#step:14:110

[ajay-mk]

I added the cirumflex/hat character to the word_components object in parser, and that seems to fix it (44d9076). @Krzmbrzl is that okay to do?

auto word_components = x3::unicode::alnum
                       | x3::char_('_') | x3::unicode::char_(L'⁔') | x3::unicode::char_(L'̃') | x3::unicode::char_(to_char_type(0x0302)) 
                       // Superscript and Subscript block
                       | (x3::unicode::char_(to_char_type(0x2070), to_char_type(0x209F)) - x3::unicode::unassigned)
                       // These are defined in the Latin-1 Supplement block and thus need to be listed explicitly
                       | x3::unicode::char_(L'¹') | x3::unicode::char_(L'²') | x3::unicode::char_(L'³')
                       // Arrow block
                       | (x3::unicode::char_(to_char_type(0x2190), to_char_type(0x21FF)) - x3::unicode::unassigned);
// A name begins with a letter, then can container letters, digits and
// underscores, but can not end with an underscore (to not confuse the parser
// with tensors á la t_{…}^{…}.

PS: the third case here is combining tilde, but my editor renders it poorly :(

[Krzmbrzl]

@ajay-mk yes that's perfectly fine. I would add a comment describing what that character is though. That way, it will be easier to understand the code

[ajay-mk]

This is good to go.

• Remaining usages of hardcoded labels have been updated to use reserved labels.
• Registry accessors now check for empty registries.
• Fixed a few docs and comments

[Copilot]

Pull request overview

Copilot reviewed 62 out of 62 changed files in this pull request and generated 2 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

This OpMaker constructor accepts a raw order but does not validate it. If order > 9 and assertions are disabled, decorate_with_pert_order() will index past pert_superscripts and can cause undefined behavior. Suggest validating order here (or removing this overload in favor of the OpParams-based ctor so all call paths go through OpParams::validate()).

Suggested change

	ann_spaces_(ann_list.begin(), ann_list.end()) {
	ann_spaces_(ann_list.begin(), ann_list.end()) {
	if (order_ > 9) {
	throw std::out_of_range(
	"OpMaker: perturbation order out of range [0,9]");
	}

[Copilot]

decorate_with_pert_order() indexes pert_superscripts[pert_order] after a SEQUANT_ASSERT range check. If assertions are compiled out (or pert_order is produced via an unchecked conversion from size_t), this can become out-of-bounds UB. Consider making the range check non-optional (e.g., throw/abort on pert_order > 9) and/or taking std::size_t to avoid lossy conversion from OpParams::order/OpMaker::order_.

Suggested change

	int pert_order = 0) {
	if (pert_order == 0) return std::wstring(base_label);
	SEQUANT_ASSERT(
	pert_order >= 0 && pert_order <= 9,
	"decorate_with_pert_order: perturbation order out of range [0,9]");
	std::size_t pert_order = 0) {
	if (pert_order == 0) return std::wstring(base_label);
	if (pert_order > 9) {
	throw std::out_of_range(
	"decorate_with_pert_order: perturbation order out of range [0,9]");
	}