binarize uses user-provided external indices

[evaleev]

Author Summary

even after #495 we cannot handle hyperindices that appear once in bra and once in ker in an expression (and once in result). It's because binarize(ResultExpr expr) did not correctly use expr's indices to guide the deduction of the external indices (hence any index that appeared once in bra and once in ket were deemed contracted). This PR fixes binarize(ResultExpr) to do external index deduction correctly. binarize(ExprPtr) also now accepts extra user-defined external indices (the default is same as before; external indices are those that appear once in an expression). Lastly, this PR introduced ResultExpr::{slots,indices} that mirror their Tensor counterparts.

Copilot Summary

This pull request enhances the handling of external indices (hyperindices) in expression evaluation, improves the API for accessing indices in result expressions, and adds comprehensive tests for these scenarios. The changes ensure that indices appearing multiple times in expressions can be explicitly marked as external (uncontracted), and provides more convenient and safer access to slots and indices. Tests now cover these cases, including integration with the TiledArray backend.

Support for external indices in expression evaluation:

• The binarize function in eval_expr.hpp now accepts an optional external parameter, allowing the caller to specify indices that should not be contracted, even if they appear multiple times in the expression. The function asserts that no null indices are passed and properly handles external indices in the expression tree.
• When binarizing a ResultExpr, the result's non-null indices are automatically collected and passed as external indices to prevent their contraction.

API improvements for index and slot access:

• The ResultExpr class in result_expr.hpp now provides slots() and indices() methods, returning concatenated views of all slots and all non-null indices, respectively. This makes it easier and safer to access all relevant indices for a result.
• Added documentation clarifying the meaning of slots/indices and updated method comments for clarity. [1] [2]

Testing and integration:

• New and expanded unit tests in test_eval_expr.cpp verify correct handling of external hyperindices, including cases where indices should be kept uncontracted and placed in the auxiliary slot.
• Integration tests in test_eval_ta.cpp demonstrate that ResultExpr binarization keeps specified indices uncontracted when evaluating with the TiledArray backend. Helper functions were updated to support the new API. [1] [2] [3] [4]

[Copilot]

Pull request overview

This pull request enhances the handling of hyperindices (indices appearing in multiple positions) in expression evaluation by allowing users to explicitly mark indices as external (uncontracted). It also adds convenient accessor methods to ResultExpr for retrieving slots and indices, mirroring the API of the Tensor class.

Changes:

• Extended binarize(ExprPtr) to accept optional external indices that should not be contracted
• Fixed binarize(ResultExpr) to automatically collect result indices and pass them as external to prevent improper contraction
• Added ResultExpr::slots() and ResultExpr::indices() methods for convenient access to all slots and non-null indices

Reviewed changes

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

Show a summary per file

File	Description
SeQuant/core/eval/eval_expr.hpp	Added external parameter to binarize(ExprPtr) and updated binarize(ResultExpr) to collect result indices as external
SeQuant/core/expressions/result_expr.hpp	Added slots() and indices() methods with appropriate documentation
SeQuant/core/expressions/tensor.hpp	Updated documentation for slots() method for consistency
tests/unit/test_eval_expr.cpp	Added comprehensive tests for external hyperindices functionality
tests/unit/test_eval_ta.cpp	Refactored helper functions and added cluster-specific RDM test demonstrating the fix

---

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