sae-lens 6.14.2__py3-none-any.whl → 6.15.0__py3-none-any.whl

sae_lens/__init__.py

@@ -1,5 +1,5 @@
 # ruff: noqa: E402
-__version__ = "6.14.2"
+__version__ = "6.15.0"
 
 import logging
 
@@ -19,6 +19,8 @@ from sae_lens.saes import (
     JumpReLUTrainingSAEConfig,
     JumpReLUTranscoder,
     JumpReLUTranscoderConfig,
+    MatryoshkaBatchTopKTrainingSAE,
+    MatryoshkaBatchTopKTrainingSAEConfig,
     SAEConfig,
     SkipTranscoder,
     SkipTranscoderConfig,
@@ -101,6 +103,8 @@ __all__ = [
     "SkipTranscoderConfig",
     "JumpReLUTranscoder",
     "JumpReLUTranscoderConfig",
+    "MatryoshkaBatchTopKTrainingSAE",
+    "MatryoshkaBatchTopKTrainingSAEConfig",
 ]
 
 
@@ -115,6 +119,11 @@ register_sae_training_class("jumprelu", JumpReLUTrainingSAE, JumpReLUTrainingSAE
 register_sae_training_class(
     "batchtopk", BatchTopKTrainingSAE, BatchTopKTrainingSAEConfig
 )
+register_sae_training_class(
+    "matryoshka_batchtopk",
+    MatryoshkaBatchTopKTrainingSAE,
+    MatryoshkaBatchTopKTrainingSAEConfig,
+)
 register_sae_class("transcoder", Transcoder, TranscoderConfig)
 register_sae_class("skip_transcoder", SkipTranscoder, SkipTranscoderConfig)
 register_sae_class("jumprelu_transcoder", JumpReLUTranscoder, JumpReLUTranscoderConfig)

sae_lens/llm_sae_training_runner.py

@@ -22,17 +22,13 @@ from sae_lens.constants import (
 )
 from sae_lens.evals import EvalConfig, run_evals
 from sae_lens.load_model import load_model
-from sae_lens.saes.batchtopk_sae import BatchTopKTrainingSAEConfig
-from sae_lens.saes.gated_sae import GatedTrainingSAEConfig
-from sae_lens.saes.jumprelu_sae import JumpReLUTrainingSAEConfig
+from sae_lens.registry import SAE_TRAINING_CLASS_REGISTRY
 from sae_lens.saes.sae import (
     T_TRAINING_SAE,
     T_TRAINING_SAE_CONFIG,
     TrainingSAE,
     TrainingSAEConfig,
 )
-from sae_lens.saes.standard_sae import StandardTrainingSAEConfig
-from sae_lens.saes.topk_sae import TopKTrainingSAEConfig
 from sae_lens.training.activation_scaler import ActivationScaler
 from sae_lens.training.activations_store import ActivationsStore
 from sae_lens.training.sae_trainer import SAETrainer
@@ -395,12 +391,8 @@ def _parse_cfg_args(
         )
 
     # Map architecture to concrete config class
-    sae_config_map = {
-        "standard": StandardTrainingSAEConfig,
-        "gated": GatedTrainingSAEConfig,
-        "jumprelu": JumpReLUTrainingSAEConfig,
-        "topk": TopKTrainingSAEConfig,
-        "batchtopk": BatchTopKTrainingSAEConfig,
+    sae_config_map: dict[str, type[TrainingSAEConfig]] = {
+        name: cfg for name, (_, cfg) in SAE_TRAINING_CLASS_REGISTRY.items()
     }
 
     sae_config_type = sae_config_map[architecture]

sae_lens/saes/__init__.py

@@ -14,6 +14,10 @@ from .jumprelu_sae import (
     JumpReLUTrainingSAE,
     JumpReLUTrainingSAEConfig,
 )
+from .matryoshka_batchtopk_sae import (
+    MatryoshkaBatchTopKTrainingSAE,
+    MatryoshkaBatchTopKTrainingSAEConfig,
+)
 from .sae import SAE, SAEConfig, TrainingSAE, TrainingSAEConfig
 from .standard_sae import (
     StandardSAE,
@@ -65,4 +69,6 @@ __all__ = [
     "SkipTranscoderConfig",
     "JumpReLUTranscoder",
     "JumpReLUTranscoderConfig",
+    "MatryoshkaBatchTopKTrainingSAE",
+    "MatryoshkaBatchTopKTrainingSAEConfig",
 ]

sae_lens/saes/matryoshka_batchtopk_sae.py

@@ -0,0 +1,143 @@
+import warnings
+from dataclasses import dataclass, field
+
+import torch
+from jaxtyping import Float
+from typing_extensions import override
+
+from sae_lens.saes.batchtopk_sae import (
+    BatchTopKTrainingSAE,
+    BatchTopKTrainingSAEConfig,
+)
+from sae_lens.saes.sae import TrainStepInput, TrainStepOutput
+from sae_lens.saes.topk_sae import _sparse_matmul_nd
+
+
+@dataclass
+class MatryoshkaBatchTopKTrainingSAEConfig(BatchTopKTrainingSAEConfig):
+    """
+    Configuration class for training a MatryoshkaBatchTopKTrainingSAE.
+
+    [Matryoshka SAEs](https://arxiv.org/pdf/2503.17547) use a series of nested reconstruction
+    losses of different widths during training to avoid feature absorption. This also has a
+    nice side-effect of encouraging higher-frequency features to be learned in earlier levels.
+    However, this SAE has more hyperparameters to tune than standard BatchTopK SAEs, and takes
+    longer to train due to requiring multiple forward passes per training step.
+
+    After training, MatryoshkaBatchTopK SAEs are saved as JumpReLU SAEs.
+
+    Args:
+        matryoshka_widths (list[int]): The widths of the matryoshka levels. Defaults to an empty list.
+        k (float): The number of features to keep active. Inherited from BatchTopKTrainingSAEConfig.
+            Defaults to 100.
+        topk_threshold_lr (float): Learning rate for updating the global topk threshold.
+            The threshold is updated using an exponential moving average of the minimum
+            positive activation value. Defaults to 0.01.
+        aux_loss_coefficient (float): Coefficient for the auxiliary loss that encourages
+            dead neurons to learn useful features. Inherited from TopKTrainingSAEConfig.
+            Defaults to 1.0.
+        rescale_acts_by_decoder_norm (bool): Treat the decoder as if it was already normalized.
+            Inherited from TopKTrainingSAEConfig. Defaults to True.
+        decoder_init_norm (float | None): Norm to initialize decoder weights to.
+            Inherited from TrainingSAEConfig. Defaults to 0.1.
+        d_in (int): Input dimension (dimensionality of the activations being encoded).
+            Inherited from SAEConfig.
+        d_sae (int): SAE latent dimension (number of features in the SAE).
+            Inherited from SAEConfig.
+        dtype (str): Data type for the SAE parameters. Inherited from SAEConfig.
+            Defaults to "float32".
+        device (str): Device to place the SAE on. Inherited from SAEConfig.
+            Defaults to "cpu".
+    """
+
+    matryoshka_widths: list[int] = field(default_factory=list)
+
+    @override
+    @classmethod
+    def architecture(cls) -> str:
+        return "matryoshka_batchtopk"
+
+
+class MatryoshkaBatchTopKTrainingSAE(BatchTopKTrainingSAE):
+    """
+    Global Batch TopK Training SAE
+
+    This SAE will maintain the k on average across the batch, rather than enforcing the k per-sample as in standard TopK.
+
+    BatchTopK SAEs are saved as JumpReLU SAEs after training.
+    """
+
+    cfg: MatryoshkaBatchTopKTrainingSAEConfig  # type: ignore[assignment]
+
+    def __init__(
+        self, cfg: MatryoshkaBatchTopKTrainingSAEConfig, use_error_term: bool = False
+    ):
+        super().__init__(cfg, use_error_term)
+        _validate_matryoshka_config(cfg)
+
+    @override
+    def training_forward_pass(self, step_input: TrainStepInput) -> TrainStepOutput:
+        base_output = super().training_forward_pass(step_input)
+        hidden_pre = base_output.hidden_pre
+        inv_W_dec_norm = 1 / self.W_dec.norm(dim=-1)
+        # the outer matryoshka level is the base SAE, so we don't need to add an extra loss for it
+        for width in self.cfg.matryoshka_widths[:-1]:
+            inner_hidden_pre = hidden_pre[:, :width]
+            inner_feat_acts = self.activation_fn(inner_hidden_pre)
+            inner_reconstruction = self._decode_matryoshka_level(
+                inner_feat_acts, width, inv_W_dec_norm
+            )
+            inner_mse_loss = (
+                self.mse_loss_fn(inner_reconstruction, step_input.sae_in)
+                .sum(dim=-1)
+                .mean()
+            )
+            base_output.losses[f"inner_mse_loss_{width}"] = inner_mse_loss
+            base_output.loss = base_output.loss + inner_mse_loss
+        return base_output
+
+    def _decode_matryoshka_level(
+        self,
+        feature_acts: Float[torch.Tensor, "... d_sae"],
+        width: int,
+        inv_W_dec_norm: torch.Tensor,
+    ) -> Float[torch.Tensor, "... d_in"]:
+        """
+        Decodes feature activations back into input space for a matryoshka level
+        """
+        # Handle sparse tensors using efficient sparse matrix multiplication
+        if self.cfg.rescale_acts_by_decoder_norm:
+            # need to multiply by the inverse of the norm because division is illegal with sparse tensors
+            feature_acts = feature_acts * inv_W_dec_norm[:width]
+        if feature_acts.is_sparse:
+            sae_out_pre = (
+                _sparse_matmul_nd(feature_acts, self.W_dec[:width]) + self.b_dec
+            )
+        else:
+            sae_out_pre = feature_acts @ self.W_dec[:width] + self.b_dec
+        sae_out_pre = self.run_time_activation_norm_fn_out(sae_out_pre)
+        return self.reshape_fn_out(sae_out_pre, self.d_head)
+
+
+def _validate_matryoshka_config(cfg: MatryoshkaBatchTopKTrainingSAEConfig) -> None:
+    if cfg.matryoshka_widths[-1] != cfg.d_sae:
+        # warn the users that we will add a final matryoshka level
+        warnings.warn(
+            "WARNING: The final matryoshka level width is not set to cfg.d_sae. "
+            "A final matryoshka level of width=cfg.d_sae will be added."
+        )
+        cfg.matryoshka_widths.append(cfg.d_sae)
+
+    for prev_width, curr_width in zip(
+        cfg.matryoshka_widths[:-1], cfg.matryoshka_widths[1:]
+    ):
+        if prev_width >= curr_width:
+            raise ValueError("cfg.matryoshka_widths must be strictly increasing.")
+    if len(cfg.matryoshka_widths) == 1:
+        warnings.warn(
+            "WARNING: You have only set one matryoshka level. This is equivalent to using a standard BatchTopK SAE and is likely not what you want."
+        )
+    if cfg.matryoshka_widths[0] < cfg.k:
+        raise ValueError(
+            "The smallest matryoshka level width cannot be smaller than cfg.k."
+        )

{sae_lens-6.14.2.dist-info → sae_lens-6.15.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sae-lens
-Version: 6.14.2
+Version: 6.15.0
 Summary: Training and Analyzing Sparse Autoencoders (SAEs)
 License: MIT
 License-File: LICENSE

{sae_lens-6.14.2.dist-info → sae_lens-6.15.0.dist-info}/RECORD

@@ -1,4 +1,4 @@
-sae_lens/__init__.py,sha256=U6PI8XxNzEqTakvBsTnn6i8EvoMbpcviRffWBke2frk,3589
+sae_lens/__init__.py,sha256=ab8Lj2QJE3i1uOP_4B9LLh_vCgi__3XXx66_eO8rcrA,3886
 sae_lens/analysis/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 sae_lens/analysis/hooked_sae_transformer.py,sha256=vRu6JseH1lZaEeILD5bEkQEQ1wYHHDcxD-f2olKmE9Y,14275
 sae_lens/analysis/neuronpedia_integration.py,sha256=Gx1W7hUBEuMoasNcnOnZ1wmqbXDd1pSZ1nqKEya1HQc,4962
@@ -6,7 +6,7 @@ sae_lens/cache_activations_runner.py,sha256=cNeAtp2JQ_vKbeddZVM-tcPLYyyfTWL8NDna
 sae_lens/config.py,sha256=IdRXSKPfYY3hwUovj-u83eep8z52gkJHII0mY0KseYY,28739
 sae_lens/constants.py,sha256=CSjmiZ-bhjQeVLyRvWxAjBokCgkfM8mnvd7-vxLIWTY,639
 sae_lens/evals.py,sha256=P0NUsJeGzYxFBiVKhbPzd72IFKY4gH40HHlEZ3jEAmg,39598
-sae_lens/llm_sae_training_runner.py,sha256=8Km519LH080RZnUBeaG2T1trq5UqxoAqokNmpX4xMTM,15200
+sae_lens/llm_sae_training_runner.py,sha256=UHRcLqvtnORsZ7u7ymbrv-Ib2BD84czHBvu03jNbtcE,14834
 sae_lens/load_model.py,sha256=C8AMykctj6H7tz_xRwB06-EXj6TfW64PtSJZR5Jxn1Y,8649
 sae_lens/loading/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 sae_lens/loading/pretrained_sae_loaders.py,sha256=SM4aT8NM6ezYix5c2u7p72Fz2RfvTtf7gw5RdOSKXhc,49846
@@ -14,10 +14,11 @@ sae_lens/loading/pretrained_saes_directory.py,sha256=4Vn-Jex6SveD7EbxcSOBv8cx1gk
 sae_lens/pretokenize_runner.py,sha256=x-reJzVPFDS9iRFbZtrFYSzNguJYki9gd0pbHjYJ3r4,7085
 sae_lens/pretrained_saes.yaml,sha256=6ca3geEB6NyhULUrmdtPDK8ea0YdpLp8_au78vIFC5w,602553
 sae_lens/registry.py,sha256=nhy7BPSudSATqW4lo9H_k3Na7sfGHmAf9v-3wpnLL_o,1490
-sae_lens/saes/__init__.py,sha256=jVwazK8Q6dW5J6_zFXPoNAuBvSxgziQ8eMOjGM3t-X8,1475
+sae_lens/saes/__init__.py,sha256=sIfZUxZ4m3HPtPymCJlpBEofiCrL8_QziE6ChS-v4lE,1677
 sae_lens/saes/batchtopk_sae.py,sha256=zxIke8lOBKkQEMVFk6sSW6q_s6F9RKhysLqfqG9ecwI,5300
 sae_lens/saes/gated_sae.py,sha256=qcmM9JwBA8aZR8z_IRHV1_gQX-q_63tKewWXRnhdXuo,8986
 sae_lens/saes/jumprelu_sae.py,sha256=HHBF1sJ95lZvxwP5vwLSQFKdnJN2KKYK0WAEaLTrta0,13399
+sae_lens/saes/matryoshka_batchtopk_sae.py,sha256=zrS4MksbxdhhftmU3UWjRCWjR7iEBpAk6N00c6GrXks,6291
 sae_lens/saes/sae.py,sha256=nuII6ZmaVtJWhPjyhasHQyiv_Wj-zdAtRQqJRYbVBQs,38274
 sae_lens/saes/standard_sae.py,sha256=9UqYyYtQuThYxXKNaDjYcyowpOx2-7cShG-TeUP6JCQ,5940
 sae_lens/saes/topk_sae.py,sha256=tzQM5eQFifMe--8_8NUBYWY7hpjQa6A_olNe6U71FE8,21275
@@ -33,7 +34,7 @@ sae_lens/training/types.py,sha256=1FpLx_Doda9vZpmfm-x1e8wGBYpyhe9Kpb_JuM5nIFM,90
 sae_lens/training/upload_saes_to_huggingface.py,sha256=r_WzI1zLtGZ5TzAxuG3xa_8T09j3zXJrWd_vzPsPGkQ,4469
 sae_lens/tutorial/tsea.py,sha256=fd1am_XXsf2KMbByDapJo-2qlxduKaa62Z2qcQZ3QKU,18145
 sae_lens/util.py,sha256=tCovQ-eZa1L7thPpNDL6PGOJrIMML2yLI5e0EHCOpS8,3309
-sae_lens-6.14.2.dist-info/METADATA,sha256=WDlgsdDyQT4jmu5hxMU-pqm5PfBh0h65MTEbyuMuE3c,5318
-sae_lens-6.14.2.dist-info/WHEEL,sha256=zp0Cn7JsFoX2ATtOhtaFYIiE2rmFAD4OcMhtUki8W3U,88
-sae_lens-6.14.2.dist-info/licenses/LICENSE,sha256=DW6e-hDosiu4CfW0-imI57sV1I5f9UEslpviNQcOAKs,1069
-sae_lens-6.14.2.dist-info/RECORD,,
+sae_lens-6.15.0.dist-info/METADATA,sha256=UmBQ8quUJBWyLclhbnDcXAkL-6jnOW4SbT8_X3rrcbE,5318
+sae_lens-6.15.0.dist-info/WHEEL,sha256=zp0Cn7JsFoX2ATtOhtaFYIiE2rmFAD4OcMhtUki8W3U,88
+sae_lens-6.15.0.dist-info/licenses/LICENSE,sha256=DW6e-hDosiu4CfW0-imI57sV1I5f9UEslpviNQcOAKs,1069
+sae_lens-6.15.0.dist-info/RECORD,,