NetKet 3.22.0.dev3__tar.gz → 3.22.0.dev4__tar.gz

{netket-3.22.0.dev3 → netket-3.22.0.dev4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: NetKet
-Version: 3.22.0.dev3
+Version: 3.22.0.dev4
 Summary: Netket : Machine Learning toolbox for many-body quantum systems.
 Project-URL: homepage, https://www.netket.org
 Project-URL: documentation, https://netket.readthedocs.io/en/latest/#

netket-3.22.0.dev4/netket/_src/operator/spin_flip.py

@@ -0,0 +1,121 @@
+from math import comb
+
+import numpy as np
+
+import jax.numpy as jnp
+from jax.tree_util import register_pytree_node_class
+
+from netket.hilbert import Spin, SpinOrbitalFermions
+from netket.hilbert.constraint import SumConstraint
+from netket.jax import canonicalize_dtypes
+from netket.operator import DiscreteJaxOperator
+
+
+def _spin_hilbert_supports_spin_flip(hilbert: Spin) -> bool:
+    return (not hilbert.constrained) or (
+        isinstance(hilbert.constraint, SumConstraint)
+        and hilbert.constraint.sum_value == 0
+    )
+
+
+@register_pytree_node_class
+class SpinFlipOperator(DiscreteJaxOperator):
+    def __init__(self, hilbert: Spin | SpinOrbitalFermions, *, dtype=float):
+        if isinstance(hilbert, Spin):
+            if not _spin_hilbert_supports_spin_flip(hilbert):
+                raise ValueError(
+                    "Spin flip is only supported on unconstrained `Spin` Hilbert spaces "
+                    "or on `Spin` Hilbert spaces constrained to zero total magnetization."
+                )
+        elif isinstance(hilbert, SpinOrbitalFermions):
+            if hilbert.n_spin_subsectors == 1:
+                raise ValueError(
+                    "Spin flip is only defined for spinful `SpinOrbitalFermions` "
+                    "Hilbert spaces."
+                )
+            if hilbert.n_spin_subsectors != 2:
+                raise ValueError(
+                    "Spin flip requires exactly 2 spin subsectors, "
+                    f"but got {hilbert.n_spin_subsectors}."
+                )
+            n_fps = hilbert.n_fermions_per_spin
+            if n_fps[0] is None or n_fps[1] is None:
+                raise ValueError(
+                    "Spin flip requires fixed fermion numbers per spin sector "
+                    "(specify `n_fermions_per_spin`)."
+                )
+            if n_fps[0] != n_fps[1]:
+                raise ValueError(
+                    "Spin flip does not preserve the spin-subsector constraints: "
+                    f"n_fermions_per_spin={n_fps} requires equal up and down counts."
+                )
+        else:
+            raise TypeError(
+                "Spin flip is only defined on `netket.hilbert.Spin` and "
+                "`netket.hilbert.SpinOrbitalFermions`."
+            )
+
+        super().__init__(hilbert)
+        self._dtype = canonicalize_dtypes(dtype=dtype)
+
+    def tree_flatten(self):
+        return (), {"hilbert": self.hilbert, "dtype": self.dtype}
+
+    @classmethod
+    def tree_unflatten(cls, struct_data, array_data):
+        return cls(**struct_data)
+
+    def __repr__(self):
+        return f"SpinFlipOperator({self.hilbert}, dtype={self.dtype})"
+
+    def __hash__(self):
+        return hash((type(self), self.hilbert, self.dtype))
+
+    def __eq__(self, other):
+        if type(self) is type(other):
+            return self.hilbert == other.hilbert and self.dtype == other.dtype
+        return False
+
+    @property
+    def max_conn_size(self) -> int:
+        return 1
+
+    @property
+    def dtype(self):
+        return self._dtype
+
+    def get_conn_padded(self, x):
+        x = jnp.asarray(x)
+
+        if isinstance(self.hilbert, SpinOrbitalFermions):
+            L = self.hilbert.n_orbitals
+            perm = np.concatenate([np.arange(L, 2 * L), np.arange(L)])
+            x_conn = x.at[..., None, perm].get(
+                unique_indices=True, mode="promise_in_bounds"
+            )
+            # Fermionic sign: (-1)^(N_up * N_down) = (-1)^N with N_up = N_down = N.
+            N = self.hilbert.n_fermions_per_spin[0]
+            mel = int((-1) ** N)
+            mels = (
+                x.at[..., :1].get(unique_indices=True, mode="promise_in_bounds") * 0
+                + mel
+            ).astype(self.dtype)
+        else:
+            x_conn = -x[..., None, :]
+            # Construct the constant matrix element without materialising new sharded arrays.
+            mels = x.at[..., :1].get(unique_indices=True, mode="promise_in_bounds")
+            mels = 1 + (mels * 0).astype(self.dtype)
+
+        return x_conn, mels
+
+    def trace(self) -> int:
+        if isinstance(self.hilbert, SpinOrbitalFermions):
+            # Fixed points: states where each orbital has equal up and down occupation,
+            # i.e., x[i] == x[i + L] for all i in 0..L-1. With n_fermions_per_spin=(N,N)
+            # these are the C(L, N) states where N orbitals are doubly occupied.
+            # Each contributes mel = (-1)^N to the trace.
+            L = self.hilbert.n_orbitals
+            N = self.hilbert.n_fermions_per_spin[0]
+            return int((-1) ** N) * comb(L, N)
+
+        return int(np.any(np.asarray(self.hilbert.local_states) == 0))

{netket-3.22.0.dev3 → netket-3.22.0.dev4}/netket/_src/symmetry/canonical_representation.py

@@ -13,23 +13,38 @@
 # limitations under the License.
 
 import warnings
+from typing import overload
 
 from netket.hilbert import DiscreteHilbert, Qubit, Spin, Fock, SpinOrbitalFermions
 from netket.symmetry.group import PermutationGroup, PointGroup
 from netket.graph.space_group import TranslationGroup, SpaceGroup
 
-from netket._src.symmetry.representation import Representation
+from netket._src.symmetry.labeled_representation import LabeledRepresentation
+from netket._src.symmetry.translation_representation import TranslationRepresentation
 from netket._src.symmetry.representation_construction import (
     physical_to_logical_permutation_group,
+    _to_logical_perm,
 )
 from netket._src.operator.permutation.construct import (
     construct_permutation_operator,
 )
 
 
+@overload
+def canonical_representation(
+    hilbert: DiscreteHilbert, group: TranslationGroup, warn: bool = True
+) -> TranslationRepresentation: ...
+
+
+@overload
+def canonical_representation(
+    hilbert: DiscreteHilbert, group: PermutationGroup, warn: bool = True
+) -> LabeledRepresentation: ...
+
+
 def canonical_representation(
     hilbert: DiscreteHilbert, group: PermutationGroup, warn: bool = True
-) -> Representation:
+) -> LabeledRepresentation:
     r"""
     Construct the representation of a permutation group on a many-body
     Hilbert space where each permutation is mapped to the permutation operator
@@ -81,9 +96,11 @@ def canonical_representation(
             :class:`~netket.graph.space_group.TranslationGroup`.
 
     Returns:
-        A :class:`~netket.symmetry.Representation` object encoding the action of the
-        permutation group on the Hilbert space. The representation includes a dictionary
-        mapping each group element to the corresponding operator that acts on quantum states.
+        A :class:`~netket.symmetry.TranslationRepresentation` if ``group`` is a
+        :class:`~netket.graph.space_group.TranslationGroup` (with Bloch-momentum
+        indexing via :meth:`~netket.symmetry.TranslationRepresentation.projector`),
+        or a :class:`~netket.symmetry.LabeledRepresentation` for all other groups
+        (with automatic irrep labels derived from the character table).
 
     Examples:
         Get the representation of the translation group on a spin system:
@@ -129,7 +146,9 @@ def canonical_representation(
         ... )
 
     See Also:
-        - :class:`~netket.symmetry.Representation`: The representation class that is returned.
+        - :class:`~netket.symmetry.Representation`: Base representation class.
+        - :class:`~netket.symmetry.LabeledRepresentation`: Returned for point/space groups.
+        - :class:`~netket.symmetry.TranslationRepresentation`: Returned for translation groups.
         - :class:`~netket.utils.group.PermutationGroup`: Permutation group class.
         - :meth:`~netket.graph.Lattice.translation_group`: Get the translation group of a lattice.
         - :meth:`~netket.graph.Lattice.space_group`: Get the space group of a lattice.
@@ -169,12 +188,23 @@ def canonical_representation(
             "Make sure that this is the intended representation. "
             "To disable this warning, pass a group of the class "
             "SpaceGroup, PointGroup, or TranslationGroup, "
-            "or pass no_warning=True.\n\n"
+            "or pass warn=False.\n\n"
         )
 
-    # If fermionic hilbert space, increase the size of the permutation so it
-    # matches the number of single-particle states.
+    if isinstance(group, TranslationGroup):
+        # Keep the TranslationGroup as-is so geometry (lattice, group_shape) is
+        # preserved. For fermionic hilbert spaces, remap only the operators.
+        representation_dict = {
+            perm: construct_permutation_operator(
+                hilbert, _to_logical_perm(hilbert, perm)
+            )
+            for perm in group
+        }
+        return TranslationRepresentation(group, representation_dict)
+
+    # For all other groups, remap the group itself for fermionic hilbert spaces.
     group = physical_to_logical_permutation_group(group, hilbert)
-    return Representation(
-        group, {perm: construct_permutation_operator(hilbert, perm) for perm in group}
-    )
+    representation_dict = {
+        perm: construct_permutation_operator(hilbert, perm) for perm in group
+    }
+    return LabeledRepresentation(group, representation_dict)

netket-3.22.0.dev4/netket/_src/symmetry/labeled_representation.py

@@ -0,0 +1,249 @@
+# Copyright 2025 The NetKet Authors - All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from __future__ import annotations
+
+from functools import cached_property
+from typing import TYPE_CHECKING
+
+import numpy as np
+
+
+from netket._src.symmetry.representation import Representation
+
+if TYPE_CHECKING:
+    from netket.operator import DiscreteJaxOperator
+    from netket._src.symmetry.labeled_representation_coset_filter import (
+        LabeledRepresentationCosetFilter,
+    )
+
+
+# ---------------------------------------------------------------------------
+# Private helpers
+# ---------------------------------------------------------------------------
+
+
+def _fmt_char(c: complex) -> str:
+    """Format a root-of-unity character value as a compact string.
+
+    Examples: +1, -1, +i, -i, exp(+0.6667πi).
+    """
+    c = complex(c)
+    r, im = round(c.real, 6), round(c.imag, 6)
+    if abs(im) < 1e-6:  # real
+        if abs(r - 1) < 1e-6:
+            return "+1"
+        if abs(r + 1) < 1e-6:
+            return "-1"
+        return f"{r:+.4g}"
+    if abs(r) < 1e-6:  # pure imaginary
+        if abs(im - 1) < 1e-6:
+            return "+i"
+        if abs(im + 1) < 1e-6:
+            return "-i"
+        return f"{im:+.4g}i"
+    # general: express as exp(θπi)
+    theta_over_pi = round(np.angle(c) / np.pi, 6)
+    return f"exp({theta_over_pi:+.4g}πi)"
+
+
+def _find_separating_elements(char_table: np.ndarray) -> np.ndarray:
+    """Find a minimal set of group-element indices whose character values
+    together uniquely identify every irrep row.
+
+    The identity (column 0, all-ones) is skipped. Elements are added greedily
+    until all n_irreps rows are distinct.
+
+    Returns integer array of column indices.
+    """
+    n_irreps, n_elems = char_table.shape
+    selected: list[int] = []
+    current_distinct = 1  # nothing selected → all rows look the same
+
+    def _rows_as_tuples(cols):
+        if not cols:
+            return [() for _ in range(n_irreps)]
+        sub = np.round(char_table[:, cols], 8)
+        return [
+            tuple(zip(sub[m].real.tolist(), sub[m].imag.tolist()))
+            for m in range(n_irreps)
+        ]
+
+    for j in range(1, n_elems):  # j=0 is identity, skip
+        candidate = selected + [j]
+        nd = len(set(_rows_as_tuples(candidate)))
+        if nd > current_distinct:
+            selected.append(j)
+            current_distinct = nd
+        if current_distinct == n_irreps:
+            break
+
+    return np.array(selected, dtype=int)
+
+
+def _fmt_labels(labels: list[str], n: int = 6) -> str:
+    """Format a label list, showing first 3 + last 3 if longer than n."""
+    if len(labels) <= n:
+        return ", ".join(labels)
+    return ", ".join(labels[:3]) + ", ..., " + ", ".join(labels[-3:])
+
+
+def _label_to_character_index(labels: list[str], label: str) -> int:
+    try:
+        return labels.index(label)
+    except ValueError:
+        raise ValueError(
+            f"Unknown label {label!r}.\n" f"Available labels: {labels}."
+        ) from None
+
+
+# ---------------------------------------------------------------------------
+# LabeledRepresentation
+# ---------------------------------------------------------------------------
+
+
+class LabeledRepresentation(Representation):
+    """A :class:`~netket.symmetry.Representation` with automatic irrep labeling.
+
+    Extends the base :class:`~netket.symmetry.Representation` with:
+
+    * :attr:`irrep_labels` — a human-readable string for each irrep, derived
+      from character values on a minimal set of "separating" group elements.
+      For example: ``"+1"``, ``"-1"``, ``"+i"``, ``"exp(+0.3333πi)"``, or
+      tuples thereof for multi-generator groups.
+    * :meth:`projector` accepting a ``label=`` keyword in addition to the
+      integer ``character_index``.
+
+    The constructor signature is identical to
+    :class:`~netket.symmetry.Representation`, so existing code that passes a
+    ``(group, representation_dict)`` pair works unchanged.
+
+    Subclasses can override :attr:`irrep_labels` to provide physics-specific
+    names (e.g. ``"even"``/``"odd"`` for Z₂).
+
+    Examples
+    --------
+    Project a state onto the antisymmetric sector of a Z₂ group::
+
+        rep = nk.symmetry.spin_flip_representation(hilbert)
+        print(rep.irrep_labels)     # ['+1', '-1']
+        proj = rep.projector(label='-1')
+
+    """
+
+    @cached_property
+    def irrep_labels(self) -> list[str]:
+        """Human-readable label for each irrep (one per ``character_index``).
+
+        Derived from character values on the minimal set of separating group
+        elements:
+
+        * Single separator: ``"+1"``, ``"-1"``, ``"+i"``, etc.
+        * Multiple separators: ``"(+1, -1)"``, ``"(-1, +i)"``, etc.
+
+        Subclasses override this with domain-specific labels.
+        """
+        ct = self.group.character_table()  # (n_irreps, |G|)
+        sep = _find_separating_elements(ct)
+        chars = ct[:, sep]  # (n_irreps, n_sep)
+
+        if chars.shape[1] == 1:
+            return [_fmt_char(chars[m, 0]) for m in range(len(chars))]
+        return [
+            "(" + ", ".join(_fmt_char(chars[m, j]) for j in range(chars.shape[1])) + ")"
+            for m in range(len(chars))
+        ]
+
+    def projector(
+        self, character_index=None, *, label=None, atol=1e-15
+    ) -> DiscreteJaxOperator:
+        """Build the projection operator for an irrep.
+
+        Accepts either:
+
+        * ``character_index`` (int): index into the character table, as in the
+          base :class:`~netket.symmetry.Representation`.
+        * ``label`` (str): human-readable label from :attr:`irrep_labels`.
+
+        Args:
+            character_index: Irrep index (0-based).
+            label: Irrep label string, e.g. ``"+1"`` or ``"-1"``.
+            atol: Tolerance for dropping near-zero projector terms.
+
+        Returns:
+            A :class:`~netket.operator.SumOperator` projection operator.
+
+        Raises:
+            ValueError: if ``label`` is not in :attr:`irrep_labels`.
+            TypeError: if neither or both arguments are supplied.
+        """
+        if character_index is not None and label is not None:
+            raise TypeError("Pass either character_index or label=, not both.")
+        if label is not None:
+            character_index = _label_to_character_index(self.irrep_labels, label)
+        if character_index is None:
+            raise TypeError(
+                "projector() requires either a positional character_index "
+                "or the keyword argument label=."
+            )
+        return super().projector(character_index, atol=atol)
+
+    def __str__(self) -> str:
+        try:
+            n = len(self.irrep_labels)
+            n_part = f", {n} irreps"
+        except Exception:
+            n_part = ""
+        n_elems = len(self.group.elems)
+        group_str = f"{type(self.group).__name__}({n_elems} elements)"
+        return f"{type(self).__name__}(hilbert={self.hilbert!r}, group={group_str}{n_part})"
+
+    def coset_filter(
+        self,
+        subgroup: LabeledRepresentation,
+    ) -> LabeledRepresentationCosetFilter:
+        """
+        Build the coset Fourier filter for this group G modulo subgroup H.
+
+        Args:
+            subgroup: :class:`LabeledRepresentation` for a subgroup H ≤ G.
+
+        Returns:
+            :class:`~netket.symmetry.LabeledRepresentationCosetFilter` for G/H.
+
+        Example::
+
+            rep_d4 = nk.symmetry.canonical_representation(hi, lattice.point_group())
+            rep_c4 = nk.symmetry.canonical_representation(hi, c4_subgroup)
+            C = rep_d4.coset_filter(rep_c4)
+        """
+        from netket._src.symmetry.labeled_representation_coset_filter import (
+            LabeledRepresentationCosetFilter,
+        )
+
+        return LabeledRepresentationCosetFilter(self, subgroup)
+
+    def __repr__(self) -> str:
+        try:
+            labels = self.irrep_labels
+            lbl_part = f"\n  irreps=[{_fmt_labels(labels)}] ({len(labels)} total)"
+        except Exception:
+            lbl_part = ""
+        n_elems = len(self.group.elems)
+        return (
+            f"{type(self).__name__}(\n"
+            f"  hilbert={self.hilbert!r},\n"
+            f"  group={type(self.group).__name__}({n_elems} elements)"
+            f"{lbl_part}\n)"
+        )

netket-3.22.0.dev4/netket/_src/symmetry/labeled_representation_coset_filter.py

@@ -0,0 +1,197 @@
+# Copyright 2025 The NetKet Authors - All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from __future__ import annotations
+
+import numpy as np
+
+from netket.operator import SumOperator, DiscreteJaxOperator
+
+
+class LabeledRepresentationCosetFilter:
+    """
+    Coset refinement operator for G/H where G and H are finite groups.
+
+    Used to extend the symmetry of a variational state one step at a time:
+    if a state is already projected onto the H-symmetric sector (irrep ρ|_H),
+    applying F_C(ρ) promotes it to the full G-symmetric sector (irrep ρ) using
+    only ``len(G)/len(H)`` operator terms instead of the ``len(G)`` terms of the full projector.
+
+    The refinement operator F_C(ρ) for irrep ρ of G satisfies::
+
+        P_G(ρ) = F_C(ρ) @ P_H(ρ|_H)
+
+    where C is a set of left-coset representatives of G/H.
+
+    Obtained via::
+
+        C = full_rep.coset_filter(sub_rep)
+        F = C.projector_refinement(label="A1")  # |C| terms
+
+    Chaining::
+
+        C_d4_c2 = rep_d4.coset_filter(rep_c4).coset_filter(rep_c2)
+    """
+
+    def __init__(self, full_rep, sub_rep, *, _validate: bool = True) -> None:
+        if _validate:
+            # Check proper subgroup: types, same Hilbert space, and H < G.
+            from netket._src.symmetry.labeled_representation import (
+                LabeledRepresentation,
+            )
+
+            if not isinstance(full_rep, LabeledRepresentation):
+                raise TypeError(
+                    f"full_rep must be a LabeledRepresentation, got {type(full_rep)}"
+                )
+            if not isinstance(sub_rep, LabeledRepresentation):
+                raise TypeError(
+                    f"sub_rep must be a LabeledRepresentation, got {type(sub_rep)}"
+                )
+            if full_rep.hilbert != sub_rep.hilbert:
+                raise ValueError(
+                    "full_rep and sub_rep must share the same Hilbert space; "
+                    f"got {full_rep.hilbert!r} and {sub_rep.hilbert!r}."
+                )
+            n_full = len(full_rep.group.elems)
+            n_sub = len(sub_rep.group.elems)
+            if not full_rep.group.is_subgroup(sub_rep.group, proper=True):
+                raise ValueError(
+                    "sub_rep must be a proper subgroup of full_rep: either the "
+                    "groups are equal, |full| is not divisible by |sub|, or at "
+                    "least one element of sub_rep is not in full_rep "
+                    f"(|full|={n_full}, |sub|={n_sub})."
+                )
+
+        self._full_rep = full_rep
+        self._sub_rep = sub_rep
+
+    @property
+    def full_rep(self):
+        """The full-group representation G."""
+        return self._full_rep
+
+    @property
+    def sub_rep(self):
+        """The subgroup representation H."""
+        return self._sub_rep
+
+    @property
+    def n_coset_reps(self) -> int:
+        """``len(G) / len(H)`` — number of coset representatives."""
+        return len(self._full_rep.group.elems) // len(self._sub_rep.group.elems)
+
+    @property
+    def _coset_mask(self) -> np.ndarray:
+        """Bool mask of shape (|G|,) selecting one representative per left-coset.
+
+        np.asarray(group) returns inverse-permutation arrays (shape (|G|, N));
+        coset composition: (g*h)^{-1} = h^{-1}[g^{-1}] via numpy fancy indexing.
+        """
+        G_arr = np.asarray(self._full_rep.group)
+        H_arr = np.asarray(self._sub_rep.group)
+        covered: set[tuple] = set()
+        mask = np.zeros(len(G_arr), dtype=bool)
+        for i, g_inv in enumerate(G_arr):
+            key = tuple(g_inv)
+            if key in covered:
+                continue
+            mask[i] = True
+            for h_inv in H_arr:
+                covered.add(tuple(h_inv[g_inv]))
+        return mask
+
+    @property
+    def _coset_operators(self) -> tuple:
+        return tuple(
+            op for op, keep in zip(self._full_rep.operators, self._coset_mask) if keep
+        )
+
+    def chars(self, label: str) -> np.ndarray:
+        """
+        Character values χ_ρ(c) for each coset representative c.
+
+        Args:
+            label: Irrep label from ``full_rep.irrep_labels``.
+
+        Returns:
+            Complex array of shape (P,).
+        """
+        idx = self._full_rep.irrep_labels.index(label)
+        ct = self._full_rep.group.character_table()
+        return ct[idx, self._coset_mask]
+
+    def projector_refinement(
+        self,
+        *,
+        label: str,
+        atol: float = 1e-15,
+    ) -> DiscreteJaxOperator:
+        """
+        Build the coset refinement operator F_C(ρ).
+
+        This returns F_C alone (``len(G)/len(H)`` terms).  To obtain the full
+        projector compose with the sub-group projector::
+
+            F_C @ sub_rep.projector(label=sub_label)  ==  full_rep.projector(label)
+
+        Args:
+            label: Irrep label from ``full_rep.irrep_labels``.
+            atol:  Drop operator terms with ``abs(coefficient)`` < atol.
+
+        Raises:
+            ValueError: if label is unknown.
+        """
+        try:
+            idx = self._full_rep.irrep_labels.index(label)
+        except ValueError as e:
+            raise ValueError(
+                f"Unknown label {label!r}. Valid: {self._full_rep.irrep_labels}."
+            ) from e
+
+        ct = self._full_rep.group.character_table()
+        d_rho = round(ct[idx, 0].real)
+        chars = ct[idx, self._coset_mask]
+
+        coefficients = d_rho * np.conj(chars) / self.n_coset_reps
+        keep = ~np.isclose(coefficients, 0.0, atol=atol)
+        kept_ops = [op for op, k in zip(self._coset_operators, keep) if k]
+        return SumOperator(*kept_ops, coefficients=coefficients[keep])
+
+    def coset_filter(self, subgroup) -> LabeledRepresentationCosetFilter:
+        """
+        Build the next coset filter in a refinement chain.
+
+        Delegates to :meth:`sub_rep.coset_filter(subgroup)
+        <netket._src.symmetry.labeled_representation.LabeledRepresentation.coset_filter>`,
+        so the result has ``full_rep = self.sub_rep`` and ``sub_rep = subgroup``::
+
+            C = rep_d4.coset_filter(rep_c4).coset_filter(rep_c2)
+            # equivalent to: rep_c4.coset_filter(rep_c2)
+
+        See :meth:`LabeledRepresentation.coset_filter
+        <netket._src.symmetry.labeled_representation.LabeledRepresentation.coset_filter>`
+        for the full documentation.
+        """
+        return self._sub_rep.coset_filter(subgroup)
+
+    def __repr__(self) -> str:
+        n_full = len(self._full_rep.group.elems)
+        n_sub = len(self._sub_rep.group.elems)
+        return (
+            f"{type(self).__name__}("
+            f"size={self.n_coset_reps} ({n_full}/{n_sub}), "
+            f"full_group={n_full} elements, "
+            f"sub_group={n_sub} elements)"
+        )

{netket-3.22.0.dev3 → netket-3.22.0.dev4}/netket/_src/symmetry/representation.py

@@ -149,13 +149,18 @@ class Representation:
         projector = SumOperator(*operators, coefficients=coefficients)
         return projector
 
-    def project(self, state, character_index: int, *, atol: float = 1e-15) -> MCState:
+    def project(
+        self, state, character_index=None, *, atol: float = 1e-15, **kwargs
+    ) -> MCState:
         """Return the state projected onto the subspace associated to the
         irreducible representation specified by character_index.
+
+        Additional keyword arguments are forwarded to :meth:`projector`, so
+        subclasses that accept ``label=``, ``k=``, etc. can be used here too.
         """
         from netket._src.vqs.transformed_vstate import apply_operator
 
-        projector = self.projector(character_index, atol=atol)
+        projector = self.projector(character_index, atol=atol, **kwargs)
         projected_state = apply_operator(projector, state)
         return projected_state