Deploying to gh-pages from @ 24056a1 🚀

_sources/changelog.md.txt

@@ -8,10 +8,17 @@ All notable changes to this project will be documented in this file.
   a basis state index (``hilbert_space::max_n_bits``) to 63. This way
   ``hilbert_space::dim()`` can return a valid value of type ``sv_index_type``
   even when all 63 bits are used up.
+- ``n_fermion_sector_view`` and ``n_fermion_multisector_view`` are now
+  parametrized on the type of ranking algorithm used to map basis state indices
+  from a full Hilbert space to a sector. Supported ranking algorithms are
+  ``combination_ranking`` (selected by default), ``staggered_ranking`` and
+  ``trie_ranking``. All three algorithms are described in M. Wallerberger,
+  [K. Held, Phys. Rev. Research 4, 033238 (2022)](
+  https://doi.org/10.1103/PhysRevResearch.4.033238).
 - Fixed a negative index bug in ``n_fermion_sector_view``.
   Credits to Dr. Cezary Śliwa for providing the patch.
 - Whenever possible, use compiler intrinsics to speed up complex bit
-  manipulation operations (``popcount``).
+  manipulation operations (``popcount``, ``tzcount``, ``pdep``, ``pext``).
 - New CMake option ``CPPCHECK_EXTRA_FLAGS``. It can be used to pass additional
   command line flags to ``cppcheck``.
 
@@ -23,7 +30,7 @@ All notable changes to this project will be documented in this file.
   ``${CMAKE_INSTALL_PREFIX}/lib/cmake/libcommute``, which is the recommended
   location.
 - Upgraded bundled Catch2 to version 2.13.9 (this fixes issue #2 a.k.a.
-  catchorg/Catch2#2178).
+  [catchorg/Catch2#2178](https://github.com/catchorg/Catch2/issues/2178)).
 - Fixed compilation with clang/libc++ 15 (issue #5).
 - Added project citation information.
 

_sources/loperator/state_vector.rst.txt

@@ -303,11 +303,19 @@ N-fermion sector views
 
 There are two more specialized flavours of the basis mapping views called
 :math:`N`-fermion sector views and :math:`N`-fermion multisector views. They
-can come in handy when working with particle-number preserving models of
-fermions. If the model is large, then generating and storing a basis state index
-map for :type:`mapped_basis_view` may become too expensive.
-
-.. class:: template<typename StateVector, bool Ref = true> n_fermion_sector_view
+can come in handy when working with particle-number preserving models with
+fermions. If a model involves :math:`M` fermionic degrees of freedom, then
+storing a basis state index map for :class:`mapped_basis_view` requires
+exponentially much memory, :math:`O(2^M)`.
+It is possible to alleviate the memory consumption problem by employing a
+(somewhat slower) algorithm that ranks bit patterns in the binary representation
+of a basis state index. A computed rank is then used to index into the
+:math:`N`-fermion (multi)sector.
+
+.. class:: template<typename StateVector, \
+                    bool Ref = true, \
+                    typename RankingAlgorithm = combination_ranking> \
+                    n_fermion_sector_view
 
   *Defined in <libcommute/loperator/n_fermion_sector_view.hpp>*
 
@@ -316,12 +324,6 @@ map for :type:`mapped_basis_view` may become too expensive.
   fixed total occupation of fermionic degrees of freedom :math:`N`. The full
   Hilbert space does not have to be purely fermionic.
 
-  :type:`n_fermion_sector_view` is generally less performant than
-  :type:`mapped_basis_view` in terms of the index translation speed. However,
-  its required storage space scales only as :math:`O(M \min(N, M - N))`, where
-  :math:`M` is the total number of the fermionic degrees of freedom. This
-  scaling law is much milder that the exponential growth of the sector size.
-
   :type:`StateVector` - type of the underlying state vector object. Defining a
   read-only view (such that prohibits :expr:`update_add_element()` operations)
   requires using a ``const``-qualified type here. For example, one can use
@@ -330,12 +332,15 @@ map for :type:`mapped_basis_view` may become too expensive.
 
   .. _n_fermion_sector_view_Ref:
 
-  :type:`Ref` - by default, :type:`n_fermion_sector_view`
+  :type:`Ref` - by default, :class:`n_fermion_sector_view`
   stores a reference to the underlying state vector. Setting this option to
   ``false`` will result in a copy being created and stored instead. This feature
   can be useful when the underlying type is already a view-like object similar
   to ``Eigen::Map``.
 
+  :type:`RankingAlgorithm` - one of the types implementing
+  :ref:`bit pattern ranking <ranking_algorithms>`.
+
   .. function:: template <typename SV, typename HSType> \
                          n_fermion_sector_view(SV&& sv, \
                          HSType const& hs, unsigned int N)
@@ -363,7 +368,9 @@ map for :type:`mapped_basis_view` may become too expensive.
 
     Total occupation of the sector.
 
-.. class:: template<typename StateVector, bool Ref = true> \
+.. class:: template<typename StateVector, \
+                    bool Ref = true, \
+                    typename RankingAlgorithm = combination_ranking> \
            n_fermion_multisector_view
 
   *Defined in <libcommute/loperator/n_fermion_sector_view.hpp>*
@@ -377,14 +384,7 @@ map for :type:`mapped_basis_view` may become too expensive.
   contributing to the multisector) as long as all subsets :math:`\{S_i\}` are
   disjoint. The full Hilbert space does not have to be purely fermionic.
 
-  :type:`n_fermion_multisector_view` is generally less performant than
-  :type:`mapped_basis_view` in terms of the index translation speed. However,
-  its required storage space scales only as
-  :math:`O(\sum_i M_i \min(N_i, M_i - N_i))`, where
-  :math:`M_i = |\{S_i\}|`. This scaling law is much milder that the exponential
-  growth of the multisector size.
-
-  It is advised to use :type:`n_fermion_sector_view` instead, if there is only
+  It is advised to use :class:`n_fermion_sector_view` instead, if there is only
   one contributing sector that also spans all fermionic degrees of freedom.
 
   :type:`StateVector` - type of the underlying state vector object. Defining a
@@ -395,12 +395,15 @@ map for :type:`mapped_basis_view` may become too expensive.
 
   .. _n_fermion_multisector_view_Ref:
 
-  :type:`Ref` - by default, :type:`n_fermion_multisector_view`
+  :type:`Ref` - by default, :class:`n_fermion_multisector_view`
   stores a reference to the underlying state vector. Setting this option to
   ``false`` will result in a copy being created and stored instead. This feature
   can be useful when the underlying type is already a view-like object similar
   to ``Eigen::Map``.
 
+  :type:`RankingAlgorithm` - one of the types implementing
+  :ref:`bit pattern ranking <ranking_algorithms>`.
+
   .. function:: template <typename SV, typename HSType> \
                 n_fermion_multisector_view(SV&& sv, HSType const& hs, \
                 std::vector<sector_descriptor<HSType>> const& sectors)
@@ -430,6 +433,8 @@ utility functions that help working with (multi)sectors.
   :expr:`sv` within the full Hilbert space :expr:`hs`. If :expr:`sv` is not an
   lvalue reference, the resulting view will
   :ref:`hold a copy <n_fermion_sector_view_Ref>` of :expr:`sv`.
+  A returned view uses :class:`combination_ranking` as its bit pattern ranking
+  algorithm.
 
 .. function:: template <typename StateVector, typename HSType> \
               auto make_nfms_view(StateVector&& sv, HSType const& hs, \
@@ -444,6 +449,8 @@ utility functions that help working with (multi)sectors.
   :math:`(\{S_i\}, N_i)` pairs). If :expr:`sv` is not an lvalue reference,
   the resulting view will
   :ref:`hold a copy <n_fermion_sector_view_Ref>` of :expr:`sv`.
+  A returned view uses :class:`combination_ranking` as its bit pattern ranking
+  algorithm.
 
 .. function:: template <typename HSType> sv_index_type \
               n_fermion_sector_size(HSType const& hs, unsigned int N)
@@ -494,3 +501,45 @@ utility functions that help working with (multi)sectors.
     for(sv_index_type n = 0; n < basis_states.size(); ++n) {
       view.map_index(basis_states[n]) == n; // true for all n
     }
+
+.. _ranking_algorithms:
+
+The following classes implement the three ranking algorithms described in
+[WH22]_. They precompute and store a certain amount of data in order to speed up
+calculations.
+
+*
+  .. class:: combination_ranking
+
+    *Defined in <libcommute/loperator/n_fermion_sector_view.hpp>*
+
+    The ranking algorithm based on the combinatorial number system.
+    The :math:`N`-fermion (multi)sector view types use this algorithm by
+    default. The storage space required by this class scales as
+    :math:`O(M \min(N, M - N))`, where :math:`M` is the total number of
+    the fermionic degrees of freedom.
+
+*
+  .. class:: template <unsigned int R> staggered_ranking
+
+    *Defined in <libcommute/loperator/n_fermion_sector_view.hpp>*
+
+    The improved combinatorial ranking with staggered lookup and a chunk size of
+    :expr:`R` bits.
+    The storage space required by this class scales as
+    :math:`O\left(2^R (M-R+2)(\frac{M}{2R}+1)\right)`, where :math:`M` is the
+    total number of the fermionic degrees of freedom.
+
+*
+  .. class:: template <unsigned int R> trie_ranking
+
+    *Defined in <libcommute/loperator/n_fermion_sector_view.hpp>*
+
+    The trie-based ranking algorithm with a chunk size of :expr:`R` bits.
+    The storage space required by this class is roughly proportional to the size
+    of the (multi)sector.
+
+.. [WH22] "Trie-based ranking of quantum many-body states",
+   M. Wallerberger and K. Held,
+   Phys. Rev. Research **4**, 033238 (2022),
+   https://doi.org/10.1103/PhysRevResearch.4.033238

changelog.html

@@ -101,10 +101,16 @@ <h2>[0.8.0] - Unreleased<a class="headerlink" href="#unreleased" title="Permalin
 a basis state index (<code class="docutils literal notranslate"><span class="pre">hilbert_space::max_n_bits</span></code>) to 63. This way
 <code class="docutils literal notranslate"><span class="pre">hilbert_space::dim()</span></code> can return a valid value of type <code class="docutils literal notranslate"><span class="pre">sv_index_type</span></code>
 even when all 63 bits are used up.</p></li>
+<li><p><code class="docutils literal notranslate"><span class="pre">n_fermion_sector_view</span></code> and <code class="docutils literal notranslate"><span class="pre">n_fermion_multisector_view</span></code> are now
+parametrized on the type of ranking algorithm used to map basis state indices
+from a full Hilbert space to a sector. Supported ranking algorithms are
+<code class="docutils literal notranslate"><span class="pre">combination_ranking</span></code> (selected by default), <code class="docutils literal notranslate"><span class="pre">staggered_ranking</span></code> and
+<code class="docutils literal notranslate"><span class="pre">trie_ranking</span></code>. All three algorithms are described in M. Wallerberger,
+<a class="reference external" href="https://doi.org/10.1103/PhysRevResearch.4.033238">K. Held, Phys. Rev. Research 4, 033238 (2022)</a>.</p></li>
 <li><p>Fixed a negative index bug in <code class="docutils literal notranslate"><span class="pre">n_fermion_sector_view</span></code>.
 Credits to Dr. Cezary Śliwa for providing the patch.</p></li>
 <li><p>Whenever possible, use compiler intrinsics to speed up complex bit
-manipulation operations (<code class="docutils literal notranslate"><span class="pre">popcount</span></code>).</p></li>
+manipulation operations (<code class="docutils literal notranslate"><span class="pre">popcount</span></code>, <code class="docutils literal notranslate"><span class="pre">tzcount</span></code>, <code class="docutils literal notranslate"><span class="pre">pdep</span></code>, <code class="docutils literal notranslate"><span class="pre">pext</span></code>).</p></li>
 <li><p>New CMake option <code class="docutils literal notranslate"><span class="pre">CPPCHECK_EXTRA_FLAGS</span></code>. It can be used to pass additional
 command line flags to <code class="docutils literal notranslate"><span class="pre">cppcheck</span></code>.</p></li>
 </ul>
@@ -118,7 +124,7 @@ <h2>[0.7.2] - 2022-11-12<a class="headerlink" href="#id1" title="Permalink to th
 <code class="docutils literal notranslate"><span class="pre">${CMAKE_INSTALL_PREFIX}/lib/cmake/libcommute</span></code>, which is the recommended
 location.</p></li>
 <li><p>Upgraded bundled Catch2 to version 2.13.9 (this fixes issue #2 a.k.a.
-catchorg/Catch2#2178).</p></li>
+<a class="reference external" href="https://github.com/catchorg/Catch2/issues/2178">catchorg/Catch2#2178</a>).</p></li>
 <li><p>Fixed compilation with clang/libc++ 15 (issue #5).</p></li>
 <li><p>Added project citation information.</p></li>
 </ul>

examples/n_fermion_sectors.html

@@ -112,10 +112,10 @@
 single <span class="math notranslate nohighlight">\(N\)</span>-fermion sector or within a
 <span class="math notranslate nohighlight">\((N_\uparrow, N_\downarrow)\)</span>-multisector.</p>
 <p>In <em>libcommute</em>’s terms, an <span class="math notranslate nohighlight">\(N\)</span>-fermion
-<a class="reference internal" href="../loperator/state_vector.html#_CPPv4I0_bEN10libcommute21n_fermion_sector_viewE" title="libcommute::n_fermion_sector_view"><code class="xref cpp cpp-class docutils literal notranslate"><span class="pre">sector</span></code></a> is a subspace of a full
+<a class="reference internal" href="../loperator/state_vector.html#_CPPv4I0_b0EN10libcommute21n_fermion_sector_viewE" title="libcommute::n_fermion_sector_view"><code class="xref cpp cpp-class docutils literal notranslate"><span class="pre">sector</span></code></a> is a subspace of a full
 Hilbert space, which is spanned by all basis states with a fixed total
 occupation of fermionic degrees of freedom (FDOF). Similarly, a
-<a class="reference internal" href="../loperator/state_vector.html#_CPPv4I0_bEN10libcommute26n_fermion_multisector_viewE" title="libcommute::n_fermion_multisector_view"><code class="xref cpp cpp-class docutils literal notranslate"><span class="pre">multisector</span></code></a> is
+<a class="reference internal" href="../loperator/state_vector.html#_CPPv4I0_b0EN10libcommute26n_fermion_multisector_viewE" title="libcommute::n_fermion_multisector_view"><code class="xref cpp cpp-class docutils literal notranslate"><span class="pre">multisector</span></code></a> is
 spanned by all basis states with a fixed occupation <span class="math notranslate nohighlight">\(N_1\)</span> of a subset of
 the FDOF <span class="math notranslate nohighlight">\(\{S_1\}\)</span>, occupation <span class="math notranslate nohighlight">\(N_2\)</span> of another subset
 <span class="math notranslate nohighlight">\(\{S_2\}\)</span> and so on. There can be any number of pairs

genindex.html

@@ -107,6 +107,8 @@ <h2 id="L">L</h2>
       <li><a href="expression/generator.html#_CPPv4N10libcommute5bosonE">libcommute::boson (C++ member)</a>
 </li>
       <li><a href="loperator/hilbert_space.html#_CPPv4N10libcommute20boson_es_constructorE">libcommute::boson_es_constructor (C++ type)</a>
+</li>
+      <li><a href="loperator/state_vector.html#_CPPv4N10libcommute19combination_rankingE">libcommute::combination_ranking (C++ class)</a>
 </li>
       <li><a href="loperator/hilbert_space.html#_CPPv4N10libcommute22default_es_constructorE">libcommute::default_es_constructor (C++ type)</a>
 </li>
@@ -488,7 +490,7 @@ <h2 id="L">L</h2>
 </li>
       <li><a href="loperator/state_vector.html#_CPPv4I0EN10libcommute26n_fermion_multisector_sizeE13sv_index_typeRK6HSTypeRKNSt6vectorI17sector_descriptorI6HSTypeEEE">libcommute::n_fermion_multisector_size (C++ function)</a>
 </li>
-      <li><a href="loperator/state_vector.html#_CPPv4I0_bEN10libcommute26n_fermion_multisector_viewE">libcommute::n_fermion_multisector_view (C++ class)</a>
+      <li><a href="loperator/state_vector.html#_CPPv4I0_b0EN10libcommute26n_fermion_multisector_viewE">libcommute::n_fermion_multisector_view (C++ class)</a>
 </li>
       <li><a href="loperator/state_vector.html#_CPPv4NK10libcommute26n_fermion_multisector_view9map_indexE13sv_index_type">libcommute::n_fermion_multisector_view::map_index (C++ function)</a>
 </li>
@@ -498,7 +500,7 @@ <h2 id="L">L</h2>
 </li>
       <li><a href="loperator/state_vector.html#_CPPv4I0EN10libcommute21n_fermion_sector_sizeE13sv_index_typeRK6HSTypej">libcommute::n_fermion_sector_size (C++ function)</a>
 </li>
-      <li><a href="loperator/state_vector.html#_CPPv4I0_bEN10libcommute21n_fermion_sector_viewE">libcommute::n_fermion_sector_view (C++ class)</a>
+      <li><a href="loperator/state_vector.html#_CPPv4I0_b0EN10libcommute21n_fermion_sector_viewE">libcommute::n_fermion_sector_view (C++ class)</a>
 </li>
       <li><a href="loperator/state_vector.html#_CPPv4NK10libcommute21n_fermion_sector_view9map_indexE13sv_index_type">libcommute::n_fermion_sector_view::map_index (C++ function)</a>
 </li>
@@ -563,6 +565,8 @@ <h2 id="L">L</h2>
       <li><a href="expression/generator.html#_CPPv4N10libcommute14spin_component4plusE">libcommute::spin_component::plus (C++ enumerator)</a>
 </li>
       <li><a href="expression/generator.html#_CPPv4N10libcommute14spin_component1zE">libcommute::spin_component::z (C++ enumerator)</a>
+</li>
+      <li><a href="loperator/state_vector.html#_CPPv4I_jEN10libcommute17staggered_rankingE">libcommute::staggered_ranking (C++ class)</a>
 </li>
       <li><a href="expression/factories.html#_CPPv4I0DpEN10libcommute14static_indices1aE10expressionI10ScalarTypeDp10IndexTypesEDpRR10IndexTypes">libcommute::static_indices::a (C++ function)</a>
 </li>
@@ -595,6 +599,8 @@ <h2 id="L">L</h2>
       <li><a href="expression/factories.html#_CPPv4I0DpEN10libcommute14static_indices3S_zE10expressionI10ScalarTypeDp10IndexTypesEDpRR10IndexTypes">libcommute::static_indices::S_z (C++ function)</a>, <a href="expression/factories.html#_CPPv4I_i0DpEN10libcommute14static_indices3S_zE10expressionI10ScalarTypeDp10IndexTypesEDpRR10IndexTypes">[1]</a>
 </li>
       <li><a href="loperator/state_vector.html#_CPPv4N10libcommute13sv_index_typeE">libcommute::sv_index_type (C++ type)</a>
+</li>
+      <li><a href="loperator/state_vector.html#_CPPv4I_jEN10libcommute12trie_rankingE">libcommute::trie_ranking (C++ class)</a>
 </li>
   </ul></td>
 </tr></table>