src/peft/tuners/waveft/layer.py

# Copyright 2025-present the HuggingFace Inc. team.
#
# 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.

import warnings
from typing import Any, Optional, Union

import torch
import torch.nn as nn
import torch.nn.functional as F
from transformers.pytorch_utils import Conv1D

from peft.tuners.tuners_utils import BaseTunerLayer, check_adapters_to_merge

from .constants import WAVELET_REDUCTIONS
from .waverec2d import waverec2d


class WaveFTLayer(BaseTunerLayer):
    # All names of layers that may contain (trainable) adapter weights
    adapter_layer_names = ("waveft_spectrum",)
    # All names of other parameters that may contain adapter-related parameters
    other_param_names = (
        "waveft_n_frequency",
        "waveft_scaling",
        "waveft_random_loc_seed",
        "waveft_wavelet_family",
        "waveft_indices",
        "waveft_use_idwt",
    )

    def __init__(self, base_layer: nn.Module, **kwargs) -> None:
        self.base_layer = base_layer
        self.waveft_n_frequency = {}
        self.waveft_scaling = {}
        self.waveft_spectrum = nn.ParameterDict({})
        self.waveft_wavelet_family = {}
        self.waveft_indices = {}
        self.waveft_random_loc_seed = {}
        self.waveft_use_idwt = {}
        # Mark the weight as unmerged
        self._disable_adapters = False
        self.merged_adapters = []
        self.kwargs = kwargs

        base_layer = self.get_base_layer()
        if isinstance(base_layer, nn.Linear):
            self.in_features, self.out_features = base_layer.in_features, base_layer.out_features
        elif isinstance(base_layer, Conv1D):
            self.in_features, self.out_features = (
                base_layer.weight.ds_shape if hasattr(base_layer.weight, "ds_shape") else base_layer.weight.shape
            )
        else:
            raise ValueError(f"Unsupported layer type {type(base_layer)}")

    def update_layer(
        self, adapter_name, n_frequency, scaling, init_weights, random_loc_seed, wavelet_family="db1", use_idwt=True
    ):
        if n_frequency <= 0:
            raise ValueError(f"`n_frequency` should be a positive integer value but the value passed is {n_frequency}")
        if n_frequency > self.in_features * self.out_features:
            raise ValueError(
                f"`n_frequency` should be less than or equal to the product of the input and output dimensions "
                f"but the value passed is {n_frequency} and the product is {self.in_features * self.out_features}"
            )

        self.waveft_n_frequency[adapter_name] = n_frequency
        self.waveft_random_loc_seed[adapter_name] = random_loc_seed
        self.waveft_wavelet_family[adapter_name] = wavelet_family
        self.waveft_use_idwt[adapter_name] = use_idwt

        # Get the expanded dimensions based on wavelet family
        reduction_rows, reduction_cols = WAVELET_REDUCTIONS[wavelet_family]

        # Generate random indices within the original dimensions
        # We handle padding separately in get_delta_weight
        generator = torch.Generator().manual_seed(self.waveft_random_loc_seed[adapter_name])
        indices = torch.randperm(self.out_features * self.in_features, generator=generator)[:n_frequency]

        # Convert to row, col format for the original dimensions
        self.waveft_indices[adapter_name] = torch.stack(
            [indices // self.in_features, indices % self.in_features], dim=0
        )

        self.waveft_scaling[adapter_name] = scaling

        # Actual trainable parameters
        # Initialize based on init_weights
        if init_weights:
            # Initialize with zeros later using reset_wave_parameters
            self.waveft_spectrum[adapter_name] = nn.Parameter(torch.empty(n_frequency), requires_grad=True)
            self.reset_wave_parameters(adapter_name)  # Initialize to zeros now
        else:
            # Initialize with randn scaled by a small std dev to prevent explosion
            std_dev = 0.01  # Using a small std dev for initial random weights
            self.waveft_spectrum[adapter_name] = nn.Parameter(torch.randn(n_frequency) * std_dev, requires_grad=True)

        self._move_adapter_to_device_of_base_layer(adapter_name)
        self.set_adapter(self.active_adapters)

    @torch.no_grad()
    def reset_wave_parameters(self, adapter_name):
        if adapter_name in self.waveft_spectrum.keys():
            nn.init.zeros_(self.waveft_spectrum[adapter_name])

    def get_delta_weight(self, adapter) -> torch.Tensor:
        spectrum = self.waveft_spectrum[adapter]
        indices = self.waveft_indices[adapter].to(spectrum.device)
        wavelet_family = self.waveft_wavelet_family[adapter]

        # Choose whether to use IDWT or direct spectrum based on adapter setting
        if self.waveft_use_idwt[adapter]:
            reduction_rows, reduction_cols = WAVELET_REDUCTIONS[wavelet_family]

            # Create a padded spectrum matrix with additional rows and columns
            # to account for the reduction during wavelet reconstruction
            padded_out_features = self.out_features + reduction_rows
            padded_in_features = self.in_features + reduction_cols

            # Make dimensions even if needed for wavelet processing
            if padded_out_features % 2 != 0:
                padded_out_features += 1
            if padded_in_features % 2 != 0:
                padded_in_features += 1

            # Create the padded dense spectrum matrix
            dense_spectrum = torch.zeros(
                padded_out_features, padded_in_features, device=spectrum.device, dtype=spectrum.dtype
            )

            # Calculate padding offsets to center the original data in the padded matrix
            row_offset = (padded_out_features - self.out_features) // 2
            col_offset = (padded_in_features - self.in_features) // 2

            # Adjust indices to account for padding offsets
            padded_indices = indices.clone()
            padded_indices[0, :] += row_offset
            padded_indices[1, :] += col_offset

            # Place spectrum values in the padded matrix
            # Filter out any indices that would be out of bounds
            valid_mask = (padded_indices[0, :] < padded_out_features) & (padded_indices[1, :] < padded_in_features)
            valid_indices = padded_indices[:, valid_mask]
            valid_spectrum = spectrum[valid_mask]

            # Set the spectrum values in the padded matrix
            dense_spectrum[valid_indices[0, :], valid_indices[1, :]] = valid_spectrum

            # Split into four sub-bands
            H, W = dense_spectrum.shape
            H2, W2 = H // 2, W // 2
            cA = dense_spectrum[:H2, :W2]  # top-left
            cH = dense_spectrum[:H2, W2:]  # top-right
            cV = dense_spectrum[H2:, :W2]  # bottom-left
            cD = dense_spectrum[H2:, W2:]  # bottom-right

            # Construct wavelet-coefficient tuple
            coeffs = (cA, (cH, cV, cD))

            # Reconstruct with the specified wavelet family
            delta_weight = waverec2d(coeffs, wavelet_family) * self.waveft_scaling[adapter]

            # Ensure the delta weight has exactly the correct dimensions
            if delta_weight.shape[0] != self.out_features or delta_weight.shape[1] != self.in_features:
                # Calculate where to start slicing to get a centered crop
                start_row = (delta_weight.shape[0] - self.out_features) // 2
                start_col = (delta_weight.shape[1] - self.in_features) // 2

                # Slice to the exact output size needed
                delta_weight = delta_weight[
                    start_row : start_row + self.out_features, start_col : start_col + self.in_features
                ]
        else:
            # Simple direct use of spectrum without IDWT
            dense_spectrum = torch.zeros(
                self.out_features, self.in_features, device=spectrum.device, dtype=spectrum.dtype
            )
            dense_spectrum[indices[0, :], indices[1, :]] = spectrum
            delta_weight = dense_spectrum * self.waveft_scaling[adapter]

        return delta_weight


class WaveFTLinear(nn.Module, WaveFTLayer):
    # WaveFT implemented in a dense layer
    def __init__(
        self,
        base_layer,
        adapter_name: str,
        n_frequency: int = 1000,
        scaling: float = 150.0,
        fan_in_fan_out: bool = False,  # Set this to True if the layer to replace stores weight like (fan_in, fan_out)
        init_weights: Union[bool, str] = False,
        random_loc_seed: int = 777,
        wavelet_family: str = "db1",
        use_idwt: bool = True,
        **kwargs,
    ) -> None:
        super().__init__()
        WaveFTLayer.__init__(self, base_layer, **kwargs)
        self.fan_in_fan_out = fan_in_fan_out
        self._active_adapter = adapter_name
        self.update_layer(adapter_name, n_frequency, scaling, init_weights, random_loc_seed, wavelet_family, use_idwt)

    def merge(self, safe_merge: bool = False, adapter_names: Optional[list[str]] = None) -> None:
        """
        Merge the active adapter weights into the base weights

        Args:
            safe_merge (`bool`, *optional*):
                If True, the merge operation will be performed in a copy of the original weights and check for NaNs
                before merging the weights. This is useful if you want to check if the merge operation will produce
                NaNs. Defaults to `False`.
            adapter_names (`List[str]`, *optional*):
                The list of adapter names that should be merged. If None, all active adapters will be merged. Defaults
                to `None`.
        """
        adapter_names = check_adapters_to_merge(self, adapter_names)
        if not adapter_names:
            # no adapter to merge
            return

        for active_adapter in adapter_names:
            if active_adapter in self.waveft_spectrum.keys():
                base_layer = self.get_base_layer()
                if safe_merge:
                    # Note that safe_merge will be slower than the normal merge
                    # because of the copy operation.
                    orig_weights = base_layer.weight.data.clone()
                    orig_weights += self.get_delta_weight(active_adapter)

                    if not torch.isfinite(orig_weights).all():
                        raise ValueError(
                            f"NaNs detected in the merged weights. The adapter {active_adapter} seems to be broken"
                        )

                    base_layer.weight.data = orig_weights
                else:
                    base_layer.weight.data += self.get_delta_weight(active_adapter)
                self.merged_adapters.append(active_adapter)

    def unmerge(self) -> None:
        """
        This method unmerges all merged adapter layers from the base weights.
        """
        if not self.merged:
            warnings.warn("Already unmerged. Nothing to do.")
            return
        while len(self.merged_adapters) > 0:
            active_adapter = self.merged_adapters.pop()
            if active_adapter in self.waveft_spectrum.keys():
                self.get_base_layer().weight.data -= self.get_delta_weight(active_adapter)

    def get_delta_weight(self, adapter) -> torch.Tensor:
        return super().get_delta_weight(adapter)

    def forward(self, x: torch.Tensor, *args: Any, **kwargs: Any) -> torch.Tensor:
        previous_dtype = x.dtype

        if self.disable_adapters:
            if self.merged:
                self.unmerge()
            result = self.base_layer(x, *args, **kwargs)
        elif self.merged:
            result = self.base_layer(x, *args, **kwargs)
        else:
            result = self.base_layer(x, *args, **kwargs)
            for active_adapter in self.active_adapters:
                if active_adapter not in self.waveft_spectrum.keys():
                    continue

                delta_w = self.get_delta_weight(active_adapter)
                x = self._cast_input_dtype(x, delta_w.dtype)
                result = result + F.linear(x, delta_w)

        result = result.to(previous_dtype)
        return result

    def __repr__(self) -> str:
        rep = super().__repr__()
        return "waveft." + rep