Conservative default tensor symmetries, with Context-controllable deserializer defaults

[evaleev]

Supersedes #553 and carries #557 (merged into this branch as 98e3727) to master.

#557 was based on ValeevGroup:default-tensor-symmetry, a staging copy of #553's fork branch that had no PR of its own, so merging it landed the work on a branch with no route to master. This PR is that route. The #557 merge commit is preserved verbatim, so its review history stays attached.

What this changes

Conservative default symmetries. Both the Tensor ctors and the deserializer now default to fully non-symmetric (Nonsymm / NonHermitian / Nonsymm) instead of silently assuming particle symmetry. Applications state their physical facts explicitly; mbpt opts into ColumnSymmetry::Symm at its construction sites.

Deserializer defaults are Context-controllable. Context gains symmetry, hermiticity and column_symmetry. These affect deserialization only — the programmatic Tensor ctors resolve against the fixed Tensor::Defaults and never read the ambient Context, so a ctor call means the same thing regardless of global state (and stays lock-free). There is deliberately no braket knob: braket symmetry is derived per-tensor from hermiticity and base_field.

New API. A TensorSymmetries named-parameter pack (so a per-TU default can be declared once and reused), and make_symmetrizer() / make_antisymmetrizer() alongside make_overlap() / make_kronecker(), built from named symmetrizer_symmetries / antisymmetrizer_symmetries packs.

Reserved labels get their defining symmetries enforced. Ŝ/Â are forced braket-Nonsymm, column-Symm, and perm as defined, whether built programmatically or parsed; contradicting explicit specs are rejected rather than silently corrected.

Bug fixes

Each is a case where two spellings of the same tensor compared unequal, so otherwise-identical terms stopped merging:

• mbpt::F()'s Kronecker deltas bypassed make_kronecker()
• spin.cpp merge_tensors() dropped O1's column symmetry
• rdm.cpp's γ/κ were left column-Nonsymm while op.cpp's were Symm
• a parsed Ŝ inherited the Context's perm symmetry instead of its defining Nonsymm
• the deserializer forced column-Symm for Ŝ but not Â
• check_symmetries() ran its column promotion after the reserved-label check, misreporting  as contradicting
• Context::operator== ignored the new fields, so set_scoped_default_context would refuse to switch between contexts differing only in them
• s, δ and RDMs lost their Hermiticity — make_overlap(), make_kronecker(), the deserializer and expectation_value_impl() never stated it, so the conservative NonHermitian default applied to objects that are Hermitian by definition

Notable fixture change

ccsd.itfaa loses one intermediate. The old output computed I2[c,j,k,l] = K[c,d,k,l] T1[d,j] alongside CSE1[d,k,l,i] = K[c,d,k,l] T1[c,i] — the same contraction, differing only in which of K's virtual slots is contracted, i.e. by K's column symmetry. With the symmetry spellings now consistent, CSE recognizes them as one and drops an intermediate and a contraction. ccsd_r2.md is unchanged apart from an intermediate's slot order; its FLOP cost is identical.

Testing

Full ctest: 93/93. Debug build, clang, all changed C++ passes clang-format-17 --Werror. Note this configuration has the TiledArray/BTAS/TAPP/Torch backends and the Python bindings disabled; a full-backend run is worth doing before merge.

[Copilot]

Pull request overview

This PR makes tensor symmetry defaults conservative (fully non-symmetric / non-Hermitian) for programmatic construction, while making deserialization defaults configurable via sequant::Context. It also introduces a TensorSymmetries named-parameter pack and new (anti)symmetrizer factories, and updates MBPT code/fixtures/tests to explicitly opt into particle-(column)-symmetry where required.

Changes:

• Add Context defaults (symmetry, hermiticity, column_symmetry) that affect deserialization only; programmatic Tensor constructors resolve against fixed Tensor::Defaults.
• Introduce TensorSymmetries and new factories (make_symmetrizer(), make_antisymmetrizer()), and enforce reserved-label symmetry behavior more consistently across ctor/deserializer paths.
• Update MBPT domain code plus unit/integration tests and expected fixtures to use explicit particle-symmetric construction where required and to reflect new canonicalization outcomes.

Reviewed changes

Copilot reviewed 30 out of 30 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
utilities/external-interface/examples/ccsd.itfaa.expected	Updates expected external-interface output due to symmetry/canonicalization changes affecting intermediates and contraction ordering.
utilities/cost_analysis/examples/ccsd_r2.md.expected	Updates expected cost-analysis report output (slot order change in a key intermediate).
tests/unit/test_wick.cpp	Adjusts Wick tests to use shared particle-symmetric symmetry pack and updates ordering expectations.
tests/unit/test_tensor.cpp	Updates tensor tests for new fixed ctor defaults and adds factory / Context-independence coverage.
tests/unit/test_tensor_network.cpp	Updates tensor-network tests for reserved symmetrizer parsing/defaults and index ordering effects.
tests/unit/test_spin.cpp	Updates spin tests to explicitly request particle symmetry where needed and reflect new symmetry spellings.
tests/unit/test_parse.cpp	Adds coverage for Context-driven deserializer defaults and reserved-(anti)symmetrizer constraints.
tests/unit/test_mbpt.cpp	Updates MBPT unit tests to reflect new symmetry defaults and explicit symmetry spellings.
tests/unit/test_main.cpp	Sets test harness default Context column symmetry to Symm for MBPT-heavy unit tests.
tests/unit/test_eval_expr.cpp	Aligns programmatic tensor expectations with Context-driven deserialization defaults.
tests/unit/test_canonicalize.cpp	Updates canonicalization tests to use particle-symmetric construction and updated serialized forms.
tests/unit/test_biorthogonalization.cpp	Updates expected serialized expressions to match new symmetry spellings.
tests/unit/data/sf_r2_direct_real_inc.hpp	Updates fixture string for SF R2 direct real expressions under new symmetry rules.
tests/unit/catch2_sequant.hpp	Adds shared inline constexpr TensorSymmetries particle_symmetric for MBPT test translation units.
tests/integration/stcc.cpp	Sets integration-test Context column symmetry to Symm for MBPT conventions.
tests/integration/srcc.cpp	Sets integration-test Context column symmetry to Symm for MBPT conventions.
SeQuant/domain/mbpt/spin.cpp	Preserves column symmetry during spin removal/merge and switches symmetrizer construction to new symmetry packs.
SeQuant/domain/mbpt/rules/thc.cpp	Makes THC/DF-generated factor tensors explicitly particle-(column)-symmetric.
SeQuant/domain/mbpt/rules/df.cpp	Ensures density-fit factor tensors remain Hermitian and particle-(column)-symmetric under conservative defaults.
SeQuant/domain/mbpt/rdm.cpp	Makes RDM/cumulant/intermediate tensors explicitly particle-(column)-symmetric.
SeQuant/domain/mbpt/op.cpp	Makes MBPT operators / integrals / RDMs explicitly column-symmetric and fixes Kronecker construction.
SeQuant/domain/mbpt/context.cpp	Treats Ŝ/Â as non-Hermitian reserved operators in MBPT context hermiticity lookup.
SeQuant/domain/mbpt/biorthogonalization.cpp	Uses make_symmetrizer() for constructing the NNS projector tensor.
SeQuant/domain/mbpt/antisymmetrizer.cpp	Ensures tensors created during antisymmetrizer manipulations remain particle-(column)-symmetric.
SeQuant/core/io/serialization/v1/deserialize.cpp	Sources deserializer default symmetries from Context instead of hardcoded legacy values.
SeQuant/core/io/serialization/v1/ast_conversions.hpp	Forces defining symmetries for reserved labels during AST→Expr conversion and forces Hermitian overlap/δ where appropriate.
SeQuant/core/expressions/tensor.hpp	Introduces TensorSymmetries, fixed ctor defaults, symmetry resolution refactor, and new (anti)symmetrizer factories.
SeQuant/core/context.hpp	Adds symmetry defaults to Context options (used for deserialization only).
SeQuant/core/context.cpp	Wires new Context fields through ctor/accessors/setters and includes them in operator==.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[evaleev]

Real — fixed in 8471ffd.

Confirmed reachable: with both fields set, resolve_symmetries() used each verbatim, so TensorSymmetries{.braket = Symm, .hermiticity = NonHermitian} produced a Tensor whose braket_symmetry_ and hermiticity_ disagreed. Only the TensorSymmetries pack can express this — the positional ctors take one or the other — so it is a gap in the new API surface.

Giving both is still allowed; they must simply agree. The check compares the derived braket symmetry rather than round-tripping the Hermiticity:

if (syms.braket.has_value() && syms.hermiticity.has_value() &&
    to_braket_symmetry(*syms.hermiticity, base_fld) != *syms.braket)
  throw Exception(...);

That matters because to_braket_symmetry is many-to-one: both AntiHermitian and NonHermitian map to Nonsymm. Comparing on the derived value keeps legal the one reason to spell both — pinning AntiHermitian, which BraKetSymmetry cannot represent, alongside its Nonsymm braket — while rejecting genuine contradictions. Both cases are now covered by a test.

[evaleev]

Real — fixed in 8471ffd.

And it was reachable through the public ctors, which is worse than it first looks: despite its name, assert_nonreserved_label() only checks FNOperator::labels() and BNOperator::labels(), not reserved::labels(). So nothing stopped Tensor(reserved::symm_label(), bra, ket, TensorSymmetries{.perm = Symmetry::Antisymm}) from constructing a Ŝ that silently disagreed with make_symmetrizer() — the same "two spellings of one tensor stop merging" failure this PR fixes elsewhere. (That also explains why make_symmetrizer() and spin.cpp can build reserved-label tensors through the public ctors at all, even though only make_overlap/make_kronecker are friends.)

check_symmetries() now treats the perm symmetry exactly as it already treats the column symmetry — reject a contradicting specified value, supply the defining one otherwise:

const Symmetry defining_symmetry =
    label_ == reserved::antisymm_label() ? Symmetry::Antisymm : Symmetry::Nonsymm;
if (symmetry_specified && symmetry_ != defining_symmetry)
  throw Exception(...);
symmetry_ = defining_symmetry;

That required carrying a symmetry_specified flag on ResolvedSymmetries, alongside the existing column_symmetry_specified. Tests added for both the rejection and the fill-in; they fail on the previous commit.

[evaleev]

Agreed — fixed in 8471ffd, together with the check_symmetries() gap above, since the two are the same invariant on the two construction paths.

The file was treating its three attributes inconsistently: the braket spec was deliberately left intact so the ctor could reject a contradiction, while perm and column were overwritten in place. Perm now gets the braket treatment — the defining value is supplied only when nothing was spelled out:

if (is_reserved_symmetrizer &&
    (!tensor.symmetry.has_value() ||
     tensor.symmetry.value().perm_symm == ast::SymmetrySpec::unspecified))
  perm_symm = tensor.name == reserved::antisymm_label() ? Symmetry::Antisymm
                                                        : Symmetry::Nonsymm;

so Ŝ{i1,i2;a1,a2}:A-N-S and Â{i1,i2;a1,a2}:N-N-S now throw instead of being quietly corrected, while the bare forms and the matching spellings still parse. New test_parse.cpp section covers all four; it fails on the previous commit.

Note this is stricter than before the PR — Â's perm symmetry was overwritten unconditionally even then — so it is a deliberate behavior change, consistent with how the braket and column contradictions are already reported.