index space registry: make occupancy predicates robust to non-physical spaces

evaleev · evaleev · commit 0f69597718cf · 2026-07-10T07:50:05.000-04:00
is_pure_occupied/is_pure_unoccupied/contains_occupied/contains_unoccupied
reduced an index's quantum numbers to physical-particle (spin) attributes and
then looked up the vacuum-(un)occupied space at those qns via a throwing
retrieve. For an index whose reduced qns has no registered occupied space this
threw instead of answering the occupancy question. Two cases motivated this:

- Physical spaces (AO, PAO) span real particle states and are spin-independent,
  not spin-less; they must carry the convention's spin_any in the physical
  sector. add_ao_spaces/add_pao_spaces registered them with only their LCAO
  trait bit (spin bits empty), so physical_particle_attributes() reported no
  spin and the occupancy lookup queried a spin flavor with no occupied space.
  Fix: add_ao_spaces/add_pao_spaces now take an explicit spin_any parameter
  (Spin::null for SpinConvention::Legacy, else Spin::any, matching make_*_spaces)
  and register the AO/PAO spaces with spin_any | trait.

- Non-physical auxiliary spaces (density-fitting, batching) legitimately carry
  no spin; asking whether they are occupied must answer false, not throw. The
  four occupancy predicates now route through non-throwing helpers
  (vacuum_occupied_type_or_null / complete_type_or_null /
  vacuum_unoccupied_type_or_null) that return a null type when no space is
  registered at the reduced qns. Byte-identical for physical inputs.

Update unit-test callers of add_ao_spaces/add_pao_spaces to pass the spin_any
matching each test's registry convention.
diff --git a/SeQuant/core/index_space_registry.hpp b/SeQuant/core/index_space_registry.hpp
@@ -905,8 +905,16 @@ class IndexSpaceRegistry {
       return false;
     }
     // this introduces icky dependence on bit footprint of vacuum_occupied_space
-    if (IS.type().to_int32() <=
-        vacuum_occupied_space(IS.qns()).type().to_int32()) {
+    // Reduce qns to physical-particle (e.g. spin) attributes before the
+    // occupancy lookup: non-particle traits (LCAO/factorization bits) do not
+    // participate in occupancy. The non-throwing lookup returns a null
+    // vacuum-occupied type for a non-physical auxiliary space (e.g. a
+    // density-fitting or batching index that carries no particle/spin
+    // character), so such a space is reported not pure-occupied rather than
+    // triggering a throw.
+    auto const vacocc_type =
+        vacuum_occupied_type_or_null(physical_particle_attributes(IS.qns()));
+    if (IS.type().to_int32() <= vacocc_type.to_int32()) {
       return true;
     } else {
       return false;
@@ -938,8 +946,10 @@ class IndexSpaceRegistry {
       // Q: would be better to express as IS is a subspace of
       // vacuum_unoccupied_space? Then subspaces that are part of neither (this
       // is not supposed to happen) will not cause an issue here
+      // non-throwing lookup: a non-physical auxiliary space yields null
+      // vacuum-occupied type, so this reports it as (trivially) unoccupied
       return !IS.type().intersection(
-          vacuum_occupied_space(physical_particle_attributes(IS.qns())).type());
+          vacuum_occupied_type_or_null(physical_particle_attributes(IS.qns())));
     }
   }
 
@@ -960,7 +970,10 @@ class IndexSpaceRegistry {
 
   /// @brief some states are fermi vacuum occupied
   bool contains_occupied(const IndexSpace& IS) const {
-    return IS.type().intersection(vacuum_occupied_space(IS.qns()).type()) !=
+    // non-throwing lookup on physical-particle attributes: a non-physical
+    // auxiliary space (no particle/spin character) contains no occupied states
+    return IS.type().intersection(vacuum_occupied_type_or_null(
+               physical_particle_attributes(IS.qns()))) !=
            IndexSpace::Type::null;
   }
 
@@ -981,7 +994,11 @@ class IndexSpaceRegistry {
 
   /// @brief some states are fermi vacuum unoccupied
   bool contains_unoccupied(const IndexSpace& IS) const {
-    return IS.type().intersection(vacuum_unoccupied_space(IS.qns()).type()) !=
+    // non-throwing lookup on physical-particle attributes: a non-physical
+    // auxiliary space (no particle/spin character) contains no unoccupied
+    // states
+    return IS.type().intersection(vacuum_unoccupied_type_or_null(
+               physical_particle_attributes(IS.qns()))) !=
            IndexSpace::Type::null;
   }
 
@@ -1385,6 +1402,51 @@ class IndexSpaceRegistry {
     return bits && !(bits & (bits - 1));
   }
 
+  /// @brief non-throwing counterpart of `vacuum_occupied_space(qn).type()`
+  /// @param qn quantum numbers (typically already reduced to
+  ///        physical-particle attributes)
+  /// @return the vacuum-occupied TYPE registered for @p qn (per-qns override if
+  ///         present, else the default), or IndexSpace::Type::null when no
+  ///         occupied space is registered at @p qn -- e.g. a non-physical
+  ///         auxiliary space (density-fitting, batching) that carries no
+  ///         particle/spin character, hence no occupancy.
+  IndexSpace::Type vacuum_occupied_type_or_null(
+      IndexSpace::QuantumNumbers qn) const {
+    auto const& qn2type = std::get<1>(vacocc_);
+    auto const it = qn2type.find(qn);
+    IndexSpace::Type const t =
+        (it != qn2type.end()) ? it->second : std::get<0>(vacocc_);
+    if (!t) return IndexSpace::Type::null;
+    return retrieve_ptr(t, qn) ? t : IndexSpace::Type::null;
+  }
+
+  /// @brief non-throwing counterpart of `complete_space(qn).type()`
+  /// @param qn quantum numbers
+  /// @return the complete-space TYPE registered for @p qn, or
+  ///         IndexSpace::Type::null when none is registered at @p qn
+  IndexSpace::Type complete_type_or_null(IndexSpace::QuantumNumbers qn) const {
+    auto const& qn2type = std::get<1>(complete_);
+    auto const it = qn2type.find(qn);
+    IndexSpace::Type const t =
+        (it != qn2type.end()) ? it->second : std::get<0>(complete_);
+    if (!t) return IndexSpace::Type::null;
+    return retrieve_ptr(t, qn) ? t : IndexSpace::Type::null;
+  }
+
+  /// @brief non-throwing counterpart of `vacuum_unoccupied_space(qn).type()`
+  /// @param qn quantum numbers (typically already reduced to
+  ///        physical-particle attributes)
+  /// @return the vacuum-unoccupied TYPE (complete minus vacuum-occupied) for
+  ///         @p qn, or IndexSpace::Type::null when no complete space is
+  ///         registered at @p qn (non-physical auxiliary space)
+  IndexSpace::Type vacuum_unoccupied_type_or_null(
+      IndexSpace::QuantumNumbers qn) const {
+    auto const complete_t = complete_type_or_null(qn);
+    if (!complete_t) return IndexSpace::Type::null;
+    auto const vacocc_t = vacuum_occupied_type_or_null(qn);
+    return complete_t.xOr(vacocc_t).intersection(complete_t);
+  }
+
   /// @brief find an IndexSpace from its attr. return nullspace if not present.
   /// @param attr the attribute of the IndexSpace
   const IndexSpace& find_by_attr(const IndexSpace::Attr& attr) const {
diff --git a/SeQuant/domain/mbpt/convention.cpp b/SeQuant/domain/mbpt/convention.cpp
@@ -71,30 +71,44 @@ void add_fermi_spin(IndexSpaceRegistry& isr) {
   isr = std::move(result);
 }
 
-void add_ao_spaces(std::shared_ptr<IndexSpaceRegistry>& isr, bool vbs,
-                   bool abs) {
+void add_ao_spaces(std::shared_ptr<IndexSpaceRegistry>& isr,
+                   IndexSpace::QuantumNumbers spin_any, bool vbs, bool abs) {
   // matches the MPQC layout, see spindex.h
   // this will not work for MR
+  // AO spaces are physical (spin-specific AOs can support particle states of a
+  // given spin), so they carry the convention's spin-agnostic quantum numbers
+  // (spin_any) in the physical (spin) sector alongside the LCAOQNS::ao trait
+  // bit; leaving the spin bits empty would make physical_particle_attributes()
+  // report no spin and break occupancy lookups (e.g. is_pure_occupied) that key
+  // on spin. spin_any matches how make_*_spaces sets the base spaces' spin.
+  auto const ao_qns = spin_any | LCAOQNS::ao;
   auto obs_lcao = isr->retrieve(vbs ? L"m" : L"p");
-  isr->add(IndexSpace{L"μ", obs_lcao.type(), LCAOQNS::ao});  // OBS AO
+  isr->add(IndexSpace{L"μ", obs_lcao.type(), ao_qns});  // OBS AO
   if (vbs) {
     auto vbs_lcao = isr->retrieve(L"e");
-    isr->add(IndexSpace{L"Α", vbs_lcao.type(), LCAOQNS::ao})  // VBS AO
-        .add_union(L"Γ", {L"μ", L"Α"});  // VBS+ = OBS + VBS
+    isr->add(IndexSpace{L"Α", vbs_lcao.type(), ao_qns})  // VBS AO
+        .add_union(L"Γ", {L"μ", L"Α"});                  // VBS+ = OBS + VBS
   }
   if (abs) {
     auto abs_lcao = isr->retrieve(L"α'");
-    isr->add(IndexSpace{L"σ", abs_lcao.type(),
-                        LCAOQNS::ao})  // ABS AO in F12 methods
+    isr->add(
+           IndexSpace{L"σ", abs_lcao.type(), ao_qns})  // ABS AO in F12 methods
         .add_union(L"ρ", {L"μ", L"σ"});
     if (vbs)                               // ABS+ = OBS + ABS
       isr->add_union(L"Ρ", {L"Γ", L"σ"});  // VABS+ = VBS+ + ABS
   }
 }
 
-void add_pao_spaces(std::shared_ptr<IndexSpaceRegistry>& isr) {
+void add_pao_spaces(std::shared_ptr<IndexSpaceRegistry>& isr,
+                    IndexSpace::QuantumNumbers spin_any) {
   auto uocc_space = isr->particle_space(/* nulltype_ok = */ false);
-  isr->add(IndexSpace{L"μ̃", uocc_space, LCAOQNS::pao})  // OBS PAO
+  // PAO states are physical (spin-independent, but still particle states), so
+  // they carry the convention's spin-agnostic quantum numbers (spin_any) in the
+  // physical (spin) sector alongside the LCAOQNS::pao trait bit; leaving the
+  // spin bits empty would make physical_particle_attributes() report no spin
+  // and break occupancy lookups (e.g. is_pure_occupied) that key on spin.
+  // spin_any matches how make_*_spaces sets the base spaces' spin.
+  isr->add(IndexSpace{L"μ̃", uocc_space, spin_any | LCAOQNS::pao})  // OBS PAO
       ;
 }
 
diff --git a/SeQuant/domain/mbpt/convention.hpp b/SeQuant/domain/mbpt/convention.hpp
@@ -45,8 +45,13 @@ void add_fermi_spin(IndexSpaceRegistry& isr);
 /// @brief add AO spaces to registry
 
 /// @param isr the IndexSpaceRegistry to which add the AO spaces
+/// @param spin_any the quantum numbers carried by spin-agnostic physical
+///        spaces in the target convention (Spin::null for
+///        SpinConvention::Legacy, else Spin::any); AO spaces are physical, so
+///        they carry it in the spin sector alongside the LCAOQNS::ao trait bit
 /// @param vbs if true, have separate virtual basis
-void add_ao_spaces(std::shared_ptr<IndexSpaceRegistry>& isr, bool vbs = false,
+void add_ao_spaces(std::shared_ptr<IndexSpaceRegistry>& isr,
+                   IndexSpace::QuantumNumbers spin_any, bool vbs = false,
                    bool abs = false);
 
 /// @brief add DF spaces to registry
@@ -58,7 +63,12 @@ void add_thc_spaces(std::shared_ptr<IndexSpaceRegistry>& isr);
 /// @brief add PAO spaces to registry
 
 /// expects \p isr to have a defined particle space
-void add_pao_spaces(std::shared_ptr<IndexSpaceRegistry>& isr);
+/// @param spin_any the quantum numbers carried by spin-agnostic physical
+///        spaces in the target convention (Spin::null for
+///        SpinConvention::Legacy, else Spin::any); PAO spaces are physical, so
+///        they carry it in the spin sector alongside the LCAOQNS::pao trait bit
+void add_pao_spaces(std::shared_ptr<IndexSpaceRegistry>& isr,
+                    IndexSpace::QuantumNumbers spin_any);
 
 /// @brief add batching spaces to registry
 void add_batching_spaces(std::shared_ptr<IndexSpaceRegistry>& isr);
diff --git a/tests/unit/test_canonicalize.cpp b/tests/unit/test_canonicalize.cpp
@@ -34,7 +34,7 @@ TEST_CASE("canonicalization", "[algorithms]") {
   TensorCanonicalizer::register_instance(
       std::make_shared<DefaultTensorCanonicalizer>());
   auto isr = sequant::mbpt::make_legacy_spaces();
-  mbpt::add_pao_spaces(isr);
+  mbpt::add_pao_spaces(isr, mbpt::Spin::null);
   auto ctx = get_default_context();
   ctx.set(isr);
   auto ctx_resetter = set_scoped_default_context(ctx);
@@ -319,8 +319,8 @@ TEST_CASE("canonicalization", "[algorithms]") {
     // intermediate.
     {
       auto sr_reg = mbpt::make_min_sr_spaces(mbpt::SpinConvention::None);
-      mbpt::add_pao_spaces(sr_reg);  // μ̃ (PAO)
-      mbpt::add_df_spaces(sr_reg);   // Κ  (DF aux)
+      mbpt::add_pao_spaces(sr_reg, mbpt::Spin::any);  // μ̃ (PAO)
+      mbpt::add_df_spaces(sr_reg);                    // Κ  (DF aux)
       std::vector<std::wstring> keys;
       for (auto const& s : *sr_reg) keys.push_back(s.base_key());
       for (auto const& k : keys)
diff --git a/tests/unit/test_eval_btas.cpp b/tests/unit/test_eval_btas.cpp
@@ -590,8 +590,8 @@ TEST_CASE("binarize_highorder_aux_hyperindex", "[eval_btas][hyperindex]") {
   // register the OBS AO space (μ) and the batching space (z) on top of the
   // standard single-reference spaces
   auto isr = mbpt::make_sr_spaces();
-  mbpt::add_ao_spaces(isr);        // μ (OBS AO)
-  mbpt::add_batching_spaces(isr);  // z (batching)
+  mbpt::add_ao_spaces(isr, mbpt::Spin::any);  // μ (OBS AO)
+  mbpt::add_batching_spaces(isr);             // z (batching)
   auto ctx_resetter =
       set_scoped_default_context(Context{get_default_context()}.set(isr));
 
diff --git a/tests/unit/test_optimize.cpp b/tests/unit/test_optimize.cpp
@@ -1166,8 +1166,8 @@ TEST_CASE("optimize", "[optimize]") {
         set_scoped_default_context(get_default_context().clone());
     auto reg = get_default_context().mutable_index_space_registry();
     mbpt::add_df_spaces(reg);
-    mbpt::add_pao_spaces(reg);
-    mbpt::add_ao_spaces(reg);
+    mbpt::add_pao_spaces(reg, mbpt::Spin::any);
+    mbpt::add_ao_spaces(reg, mbpt::Spin::any);
     // i 10
     // a 40
     // μ̃ 50
@@ -1364,8 +1364,8 @@ TEST_CASE("OSV early-contraction reproducer", "[optimize][osv]") {
   auto ctx_resetter = set_scoped_default_context(get_default_context().clone());
   auto reg = get_default_context().mutable_index_space_registry();
   mbpt::add_df_spaces(reg);
-  mbpt::add_pao_spaces(reg);
-  mbpt::add_ao_spaces(reg);
+  mbpt::add_pao_spaces(reg, mbpt::Spin::any);
+  mbpt::add_ao_spaces(reg, mbpt::Spin::any);
   for (auto&& [k, v] :
        std::initializer_list<std::pair<std::wstring_view, size_t>>{
            {L"i", 10}, {L"a", 40}, {L"μ̃", 50}, {L"Κ", 90}}) {
@@ -1421,8 +1421,8 @@ TEST_CASE("OSV early-contraction reproducer (full term #1)",
   auto ctx_resetter = set_scoped_default_context(get_default_context().clone());
   auto reg = get_default_context().mutable_index_space_registry();
   mbpt::add_df_spaces(reg);
-  mbpt::add_pao_spaces(reg);
-  mbpt::add_ao_spaces(reg);
+  mbpt::add_pao_spaces(reg, mbpt::Spin::any);
+  mbpt::add_ao_spaces(reg, mbpt::Spin::any);
   for (auto&& [k, v] :
        std::initializer_list<std::pair<std::wstring_view, size_t>>{
            {L"i", 56}, {L"a", 12}, {L"μ̃", 602}, {L"Κ", 1652}}) {
@@ -1475,8 +1475,8 @@ TEST_CASE("OSV deferral reproducer (tetramer term 3)", "[optimize][osv]") {
   auto ctx_resetter = set_scoped_default_context(get_default_context().clone());
   auto reg = get_default_context().mutable_index_space_registry();
   mbpt::add_df_spaces(reg);
-  mbpt::add_pao_spaces(reg);
-  mbpt::add_ao_spaces(reg);
+  mbpt::add_pao_spaces(reg, mbpt::Spin::any);
+  mbpt::add_ao_spaces(reg, mbpt::Spin::any);
   for (auto&& [k, v] :
        std::initializer_list<std::pair<std::wstring_view, size_t>>{
            {L"i", 16}, {L"a", 12}, {L"μ̃", 170}, {L"Κ", 472}}) {
@@ -1711,8 +1711,8 @@ TEST_CASE("C60 member-2 double-proto probe", "[optimize][osv][c60]") {
   auto ctx_resetter = set_scoped_default_context(get_default_context().clone());
   auto reg = get_default_context().mutable_index_space_registry();
   mbpt::add_df_spaces(reg);
-  mbpt::add_pao_spaces(reg);
-  mbpt::add_ao_spaces(reg);
+  mbpt::add_pao_spaces(reg, mbpt::Spin::any);
+  mbpt::add_ao_spaces(reg, mbpt::Spin::any);
   // C60 cc-pVDZ-F12-ish extents: active occ 120, PNO domain 42, PAO 1800,
   // DF aux 6000 (sliced to batch 30 by the batched objective).
   for (auto&& [k, v] :
@@ -1835,8 +1835,8 @@ TEST_CASE("PPL: form 4-PNO W vs fold-t (peak-neutral, flop tie-break)",
   auto ctx_resetter = set_scoped_default_context(get_default_context().clone());
   auto reg = get_default_context().mutable_index_space_registry();
   mbpt::add_df_spaces(reg);
-  mbpt::add_pao_spaces(reg);
-  mbpt::add_ao_spaces(reg);
+  mbpt::add_pao_spaces(reg, mbpt::Spin::any);
+  mbpt::add_ao_spaces(reg, mbpt::Spin::any);
   for (auto&& [k, v] :
        std::initializer_list<std::pair<std::wstring_view, size_t>>{
            {L"i", 16}, {L"a", 12}, {L"μ̃", 170}, {L"Κ", 472}})
@@ -1995,8 +1995,8 @@ TEST_CASE("optimize emits an external batch axis for the PPL term",
   auto ctx_resetter = set_scoped_default_context(get_default_context().clone());
   auto reg = get_default_context().mutable_index_space_registry();
   mbpt::add_df_spaces(reg);
-  mbpt::add_pao_spaces(reg);
-  mbpt::add_ao_spaces(reg);
+  mbpt::add_pao_spaces(reg, mbpt::Spin::any);
+  mbpt::add_ao_spaces(reg, mbpt::Spin::any);
   for (auto&& [k, v] :
        std::initializer_list<std::pair<std::wstring_view, size_t>>{
            {L"i", 16}, {L"a", 12}, {L"μ̃", 170}, {L"Κ", 472}})
@@ -2077,8 +2077,8 @@ TEST_CASE("quadratic bubble: early-K integral vs late-K t·(gC)",
   auto ctx_resetter = set_scoped_default_context(get_default_context().clone());
   auto reg = get_default_context().mutable_index_space_registry();
   mbpt::add_df_spaces(reg);
-  mbpt::add_pao_spaces(reg);
-  mbpt::add_ao_spaces(reg);
+  mbpt::add_pao_spaces(reg, mbpt::Spin::any);
+  mbpt::add_ao_spaces(reg, mbpt::Spin::any);
   // water-20-scale extents (≈ water-14 OSV extents scaled by 20/14).
   for (auto&& [k, v] :
        std::initializer_list<std::pair<std::wstring_view, size_t>>{
@@ -2287,8 +2287,8 @@ TEST_CASE(
   auto ctx_resetter = set_scoped_default_context(get_default_context().clone());
   auto reg = get_default_context().mutable_index_space_registry();
   mbpt::add_df_spaces(reg);
-  mbpt::add_pao_spaces(reg);
-  mbpt::add_ao_spaces(reg);
+  mbpt::add_pao_spaces(reg, mbpt::Spin::any);
+  mbpt::add_ao_spaces(reg, mbpt::Spin::any);
   // water-20-scale extents (matches the "quadratic bubble" test above).
   for (auto&& [k, v] :
        std::initializer_list<std::pair<std::wstring_view, size_t>>{
@@ -2404,8 +2404,8 @@ TEST_CASE("batched DP peak matches oracle with two axes and accumulation",
   auto ctx_resetter = set_scoped_default_context(get_default_context().clone());
   auto reg = get_default_context().mutable_index_space_registry();
   mbpt::add_df_spaces(reg);
-  mbpt::add_pao_spaces(reg);
-  mbpt::add_ao_spaces(reg);
+  mbpt::add_pao_spaces(reg, mbpt::Spin::any);
+  mbpt::add_ao_spaces(reg, mbpt::Spin::any);
   for (auto&& [k, v] :
        std::initializer_list<std::pair<std::wstring_view, size_t>>{
            {L"i", 20}, {L"a", 20}, {L"μ̃", 200}, {L"Κ", 300}}) {
@@ -2780,8 +2780,8 @@ TEST_CASE("fast_flops equals flops_of over all bipartitions (parity)",
   auto ctx_resetter = set_scoped_default_context(get_default_context().clone());
   auto reg = get_default_context().mutable_index_space_registry();
   mbpt::add_df_spaces(reg);
-  mbpt::add_pao_spaces(reg);
-  mbpt::add_ao_spaces(reg);
+  mbpt::add_pao_spaces(reg, mbpt::Spin::any);
+  mbpt::add_ao_spaces(reg, mbpt::Spin::any);
   for (auto&& [k, v] :
        std::initializer_list<std::pair<std::wstring_view, size_t>>{
            {L"i", 10}, {L"a", 40}, {L"μ̃", 50}, {L"Κ", 90}})
diff --git a/tests/unit/test_space.cpp b/tests/unit/test_space.cpp
@@ -209,7 +209,7 @@ TEST_CASE("index_space", "[elements]") {
 
   SECTION("AO spaces") {
     auto isr = sequant::mbpt::make_min_sr_spaces();
-    REQUIRE_NOTHROW(mbpt::add_ao_spaces(isr));
+    REQUIRE_NOTHROW(mbpt::add_ao_spaces(isr, mbpt::Spin::any));
 
     // OBS AO space ...
     REQUIRE_NOTHROW(isr->retrieve(L"μ"));
@@ -229,7 +229,7 @@ TEST_CASE("index_space", "[elements]") {
 
   SECTION("PAO spaces") {
     auto isr = sequant::mbpt::make_min_sr_spaces();
-    REQUIRE_NOTHROW(mbpt::add_pao_spaces(isr));
+    REQUIRE_NOTHROW(mbpt::add_pao_spaces(isr, mbpt::Spin::any));
 
     // OBS PAO space ...
     REQUIRE_NOTHROW(isr->retrieve(L"μ̃"));
diff --git a/tests/unit/test_tensor_network.cpp b/tests/unit/test_tensor_network.cpp
@@ -62,7 +62,7 @@ TEMPLATE_TEST_CASE("tensor_network_shared", "[elements]", TensorNetworkV1,
   TensorCanonicalizer::register_instance(
       std::make_shared<DefaultTensorCanonicalizer>());
   auto isr = sequant::mbpt::make_legacy_spaces();
-  mbpt::add_pao_spaces(isr);
+  mbpt::add_pao_spaces(isr, mbpt::Spin::null);
   auto ctx = get_default_context();
   ctx.set(isr);
   ctx.set(Vacuum::SingleProduct);
