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, 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.
• The trace_product spin-tracing logic assumed that the symmetrizer tensor always appears first; this has been generalized. cc: @ABesharat
• Some evaluation logic also requires canonical ordering. Accordingly, the eval_{ta,btas} cases now use mbpt::cardinal_tensor_labels() with TNC.
• 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

This PR refactors the MBPT operator system from a predefined OpType enum to a runtime OpRegistry, enabling users to define custom operators beyond the predefined set. The implementation introduces a registry-based approach where operator labels map to operator classes (excitation, de-excitation, or general).

Key Changes:

• Introduces OpRegistry for runtime operator registration with two predefined registries (minimal and legacy)
• Removes OpType enum and replaces all usage with string-based operator labels
• Adds support for perturbation orders 0-9 (previously limited to order 1)
• Replaces hard-coded reserved labels (L"A", L"S") with functions returning L"Â", L"Ŝ"

Reviewed changes

Copilot reviewed 54 out of 54 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
SeQuant/core/reserved.hpp	New file defining reserved operator labels (antisymmetrizer, symmetrizer, kronecker, overlap)
SeQuant/domain/mbpt/op_registry.hpp/cpp	New registry class for mapping operator labels to OpClass
SeQuant/domain/mbpt/context.hpp/cpp	Extended to hold OpRegistry with thread-safe manipulation
SeQuant/domain/mbpt/op.hpp/cpp/ipp	Major refactoring: OpMaker/Operator now use strings; added perturbation order support
SeQuant/domain/mbpt/vac_av.hpp/cpp	OpConnections changed from OpType to std::wstring
Test files	Updated to use new string-based API and reserved label functions
Documentation	Added operator registry documentation and examples
Input files (nevpt2, ccsd)	Updated antisymmetrizer label from "A" to "Â"

---

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

[Copilot]

Pull request overview

Copilot reviewed 57 out of 57 changed files in this pull request and generated no new comments.

---

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