flwr 1.21.0__py3-none-any.whl → 1.22.0__py3-none-any.whl

flwr/serverapp/strategy/__init__.py

@@ -15,6 +15,11 @@
 """ServerApp strategies."""
 
 
+from .bulyan import Bulyan
+from .dp_adaptive_clipping import (
+    DifferentialPrivacyClientSideAdaptiveClipping,
+    DifferentialPrivacyServerSideAdaptiveClipping,
+)
 from .dp_fixed_clipping import (
     DifferentialPrivacyClientSideFixedClipping,
     DifferentialPrivacyServerSideFixedClipping,
@@ -22,17 +27,38 @@ from .dp_fixed_clipping import (
 from .fedadagrad import FedAdagrad
 from .fedadam import FedAdam
 from .fedavg import FedAvg
+from .fedavgm import FedAvgM
+from .fedmedian import FedMedian
+from .fedprox import FedProx
+from .fedtrimmedavg import FedTrimmedAvg
+from .fedxgb_bagging import FedXgbBagging
+from .fedxgb_cyclic import FedXgbCyclic
 from .fedyogi import FedYogi
+from .krum import Krum
+from .multikrum import MultiKrum
+from .qfedavg import QFedAvg
 from .result import Result
 from .strategy import Strategy
 
 __all__ = [
+    "Bulyan",
+    "DifferentialPrivacyClientSideAdaptiveClipping",
     "DifferentialPrivacyClientSideFixedClipping",
+    "DifferentialPrivacyServerSideAdaptiveClipping",
     "DifferentialPrivacyServerSideFixedClipping",
     "FedAdagrad",
     "FedAdam",
     "FedAvg",
+    "FedAvgM",
+    "FedMedian",
+    "FedProx",
+    "FedTrimmedAvg",
+    "FedXgbBagging",
+    "FedXgbCyclic",
     "FedYogi",
+    "Krum",
+    "MultiKrum",
+    "QFedAvg",
     "Result",
     "Strategy",
 ]

flwr/serverapp/strategy/bulyan.py

@@ -0,0 +1,238 @@
+# Copyright 2025 Flower Labs GmbH. 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.
+# ==============================================================================
+"""Bulyan [El Mhamdi et al., 2018] strategy.
+
+Paper: arxiv.org/abs/1802.07927
+"""
+
+
+from collections import OrderedDict
+from collections.abc import Iterable
+from logging import INFO, WARN
+from typing import Callable, Optional, cast
+
+import numpy as np
+
+from flwr.common import (
+    Array,
+    ArrayRecord,
+    Message,
+    MetricRecord,
+    NDArrays,
+    RecordDict,
+    log,
+)
+
+from .fedavg import FedAvg
+from .multikrum import select_multikrum
+
+
+# pylint: disable=too-many-instance-attributes
+class Bulyan(FedAvg):
+    """Bulyan strategy.
+
+    Implementation based on https://arxiv.org/abs/1802.07927.
+
+    Parameters
+    ----------
+    fraction_train : float (default: 1.0)
+        Fraction of nodes used during training. In case `min_train_nodes`
+        is larger than `fraction_train * total_connected_nodes`, `min_train_nodes`
+        will still be sampled.
+    fraction_evaluate : float (default: 1.0)
+        Fraction of nodes used during validation. In case `min_evaluate_nodes`
+        is larger than `fraction_evaluate * total_connected_nodes`,
+        `min_evaluate_nodes` will still be sampled.
+    min_train_nodes : int (default: 2)
+        Minimum number of nodes used during training.
+    min_evaluate_nodes : int (default: 2)
+        Minimum number of nodes used during validation.
+    min_available_nodes : int (default: 2)
+        Minimum number of total nodes in the system.
+    num_malicious_nodes : int (default: 0)
+        Number of malicious nodes in the system.
+    weighted_by_key : str (default: "num-examples")
+        The key within each MetricRecord whose value is used as the weight when
+        computing weighted averages for MetricRecords.
+    arrayrecord_key : str (default: "arrays")
+        Key used to store the ArrayRecord when constructing Messages.
+    configrecord_key : str (default: "config")
+        Key used to store the ConfigRecord when constructing Messages.
+    train_metrics_aggr_fn : Optional[callable] (default: None)
+        Function with signature (list[RecordDict], str) -> MetricRecord,
+        used to aggregate MetricRecords from training round replies.
+        If `None`, defaults to `aggregate_metricrecords`, which performs a weighted
+        average using the provided weight factor key.
+    evaluate_metrics_aggr_fn : Optional[callable] (default: None)
+        Function with signature (list[RecordDict], str) -> MetricRecord,
+        used to aggregate MetricRecords from training round replies.
+        If `None`, defaults to `aggregate_metricrecords`, which performs a weighted
+        average using the provided weight factor key.
+    selection_rule : Optional[Callable] (default: None)
+        Function with signature (list[RecordDict], int, int) -> list[RecordDict].
+        The inputs are:
+        - a list of contents from reply messages,
+        - the assumed number of malicious nodes (`num_malicious_nodes`),
+        - the number of nodes to select (`num_nodes_to_select`).
+
+        The function should implement a Byzantine-resilient selection rule that
+        serves as the first step of Bulyan. If None, defaults to `select_multikrum`,
+        which selects nodes according to the Multi-Krum algorithm.
+    """
+
+    # pylint: disable=too-many-arguments,too-many-positional-arguments
+    def __init__(
+        self,
+        fraction_train: float = 1.0,
+        fraction_evaluate: float = 1.0,
+        min_train_nodes: int = 2,
+        min_evaluate_nodes: int = 2,
+        min_available_nodes: int = 2,
+        num_malicious_nodes: int = 0,
+        weighted_by_key: str = "num-examples",
+        arrayrecord_key: str = "arrays",
+        configrecord_key: str = "config",
+        train_metrics_aggr_fn: Optional[
+            Callable[[list[RecordDict], str], MetricRecord]
+        ] = None,
+        evaluate_metrics_aggr_fn: Optional[
+            Callable[[list[RecordDict], str], MetricRecord]
+        ] = None,
+        selection_rule: Optional[
+            Callable[[list[RecordDict], int, int], list[RecordDict]]
+        ] = None,
+    ) -> None:
+        super().__init__(
+            fraction_train=fraction_train,
+            fraction_evaluate=fraction_evaluate,
+            min_train_nodes=min_train_nodes,
+            min_evaluate_nodes=min_evaluate_nodes,
+            min_available_nodes=min_available_nodes,
+            weighted_by_key=weighted_by_key,
+            arrayrecord_key=arrayrecord_key,
+            configrecord_key=configrecord_key,
+            train_metrics_aggr_fn=train_metrics_aggr_fn,
+            evaluate_metrics_aggr_fn=evaluate_metrics_aggr_fn,
+        )
+        self.num_malicious_nodes = num_malicious_nodes
+        self.selection_rule = selection_rule or select_multikrum
+
+    def summary(self) -> None:
+        """Log summary configuration of the strategy."""
+        log(INFO, "\t├──> Bulyan settings:")
+        log(INFO, "\t│\t├── Number of malicious nodes: %d", self.num_malicious_nodes)
+        log(INFO, "\t│\t└── Selection rule: %s", self.selection_rule.__name__)
+        super().summary()
+
+    def aggregate_train(
+        self,
+        server_round: int,
+        replies: Iterable[Message],
+    ) -> tuple[Optional[ArrayRecord], Optional[MetricRecord]]:
+        """Aggregate ArrayRecords and MetricRecords in the received Messages."""
+        valid_replies, _ = self._check_and_log_replies(replies, is_train=True)
+
+        # Check if sufficient replies have been received
+        if len(valid_replies) < 4 * self.num_malicious_nodes + 3:
+            log(
+                WARN,
+                "Insufficient replies, skipping Bulyan aggregation: "
+                "Required at least %d (4*num_malicious_nodes + 3), but received %d.",
+                4 * self.num_malicious_nodes + 3,
+                len(valid_replies),
+            )
+            return None, None
+
+        reply_contents = [msg.content for msg in valid_replies]
+
+        # Compute theta and beta
+        theta = len(valid_replies) - 2 * self.num_malicious_nodes
+        beta = theta - 2 * self.num_malicious_nodes
+
+        # Byzantine-resilient selection rule
+        selected_contents = self.selection_rule(
+            reply_contents, self.num_malicious_nodes, theta
+        )
+
+        # Convert each ArrayRecord to a list of NDArray for easier computation
+        key = list(selected_contents[0].array_records.keys())[0]
+        array_keys = list(selected_contents[0][key].keys())
+        selected_ndarrays = [
+            cast(ArrayRecord, ctnt[key]).to_numpy_ndarrays(keep_input=False)
+            for ctnt in selected_contents
+        ]
+
+        # Compute median
+        median_ndarrays = [np.median(arr, axis=0) for arr in zip(*selected_ndarrays)]
+
+        # Aggregate the beta closest weights element-wise
+        aggregated_ndarrays = aggregate_n_closest_weights(
+            median_ndarrays, selected_ndarrays, beta
+        )
+
+        # Convert to ArrayRecord
+        arrays = ArrayRecord(
+            OrderedDict(zip(array_keys, map(Array, aggregated_ndarrays)))
+        )
+
+        # Aggregate MetricRecords
+        metrics = self.train_metrics_aggr_fn(
+            selected_contents,
+            self.weighted_by_key,
+        )
+        return arrays, metrics
+
+
+def aggregate_n_closest_weights(
+    ref_weights: NDArrays, weights_list: list[NDArrays], beta: int
+) -> NDArrays:
+    """Compute the element-wise mean of the `beta` closest weight arrays.
+
+    For each element (i-th coordinate), the output is the average of the
+    `beta` weight arrays that are closest to the reference weights.
+
+    Parameters
+    ----------
+    ref_weights : NDArrays
+        Reference weights used to compute distances.
+    weights_list : list[NDArrays]
+        List of weight arrays (e.g., from selected nodes).
+    beta : int
+        Number of closest weight arrays to include in the averaging.
+
+    Returns
+    -------
+    aggregated_weights : NDArrays
+        Element-wise average of the `beta` closest weight arrays to the
+        reference weights.
+    """
+    aggregated_weights = []
+    for layer_id, ref_layer in enumerate(ref_weights):
+        # Shape: (n_models, *layer_shape)
+        layer_stack = np.stack([weights[layer_id] for weights in weights_list])
+
+        # Compute absolute differences: shape (n_models, *layer_shape)
+        diffs = np.abs(layer_stack - ref_layer)
+
+        # Find indices of `beta` smallest per coordinate
+        idx = np.argpartition(diffs, beta - 1, axis=0)[:beta]
+
+        # Gather the closest weights
+        closest = np.take_along_axis(layer_stack, idx, axis=0)
+
+        # Average them
+        aggregated_weights.append(np.mean(closest, axis=0))
+
+    return aggregated_weights

flwr/serverapp/strategy/dp_adaptive_clipping.py

@@ -0,0 +1,335 @@
+# Copyright 2025 Flower Labs GmbH. 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.
+# ==============================================================================
+"""Message-based Central differential privacy with adaptive clipping.
+
+Paper (Andrew et al.): https://arxiv.org/abs/1905.03871
+"""
+
+import math
+from abc import ABC
+from collections import OrderedDict
+from collections.abc import Iterable
+from logging import INFO
+from typing import Optional
+
+import numpy as np
+
+from flwr.common import Array, ArrayRecord, ConfigRecord, Message, MetricRecord, log
+from flwr.common.differential_privacy import (
+    adaptive_clip_inputs_inplace,
+    add_gaussian_noise_inplace,
+    compute_adaptive_noise_params,
+    compute_stdv,
+)
+from flwr.common.differential_privacy_constants import KEY_CLIPPING_NORM, KEY_NORM_BIT
+from flwr.server import Grid
+from flwr.serverapp.exception import AggregationError
+
+from .dp_fixed_clipping import validate_replies
+from .strategy import Strategy
+
+
+class DifferentialPrivacyAdaptiveBase(Strategy, ABC):
+    """Base class for DP strategies with adaptive clipping."""
+
+    # pylint: disable=too-many-arguments,too-many-instance-attributes,too-many-positional-arguments
+    def __init__(
+        self,
+        strategy: Strategy,
+        noise_multiplier: float,
+        num_sampled_clients: int,
+        initial_clipping_norm: float = 0.1,
+        target_clipped_quantile: float = 0.5,
+        clip_norm_lr: float = 0.2,
+        clipped_count_stddev: Optional[float] = None,
+    ) -> None:
+        super().__init__()
+
+        if strategy is None:
+            raise ValueError("The passed strategy is None.")
+        if noise_multiplier < 0:
+            raise ValueError("The noise multiplier should be a non-negative value.")
+        if num_sampled_clients <= 0:
+            raise ValueError(
+                "The number of sampled clients should be a positive value."
+            )
+        if initial_clipping_norm <= 0:
+            raise ValueError("The initial clipping norm should be a positive value.")
+        if not 0 <= target_clipped_quantile <= 1:
+            raise ValueError("The target clipped quantile must be in [0, 1].")
+        if clip_norm_lr <= 0:
+            raise ValueError("The learning rate must be positive.")
+        if clipped_count_stddev is not None and clipped_count_stddev < 0:
+            raise ValueError("The `clipped_count_stddev` must be non-negative.")
+
+        self.strategy = strategy
+        self.num_sampled_clients = num_sampled_clients
+        self.clipping_norm = initial_clipping_norm
+        self.target_clipped_quantile = target_clipped_quantile
+        self.clip_norm_lr = clip_norm_lr
+        (
+            self.clipped_count_stddev,
+            self.noise_multiplier,
+        ) = compute_adaptive_noise_params(
+            noise_multiplier,
+            num_sampled_clients,
+            clipped_count_stddev,
+        )
+
+    def _add_noise_to_aggregated_arrays(self, aggregated: ArrayRecord) -> ArrayRecord:
+        nds = aggregated.to_numpy_ndarrays()
+        stdv = compute_stdv(
+            self.noise_multiplier, self.clipping_norm, self.num_sampled_clients
+        )
+        add_gaussian_noise_inplace(nds, stdv)
+        log(INFO, "aggregate_fit: central DP noise with %.4f stdev added", stdv)
+        return ArrayRecord(
+            OrderedDict({k: Array(v) for k, v in zip(aggregated.keys(), nds)})
+        )
+
+    def _noisy_fraction(self, count: int, total: int) -> float:
+        return float(np.random.normal(count, self.clipped_count_stddev)) / float(total)
+
+    def _geometric_update(self, clipped_fraction: float) -> None:
+        self.clipping_norm *= math.exp(
+            -self.clip_norm_lr * (clipped_fraction - self.target_clipped_quantile)
+        )
+
+    def configure_evaluate(
+        self, server_round: int, arrays: ArrayRecord, config: ConfigRecord, grid: Grid
+    ) -> Iterable[Message]:
+        """Configure the next round of federated evaluation."""
+        return self.strategy.configure_evaluate(server_round, arrays, config, grid)
+
+    def aggregate_evaluate(
+        self, server_round: int, replies: Iterable[Message]
+    ) -> Optional[MetricRecord]:
+        """Aggregate MetricRecords in the received Messages."""
+        return self.strategy.aggregate_evaluate(server_round, replies)
+
+    def summary(self) -> None:
+        """Log summary configuration of the strategy."""
+        self.strategy.summary()
+
+
+class DifferentialPrivacyServerSideAdaptiveClipping(DifferentialPrivacyAdaptiveBase):
+    """Message-based central DP with server-side adaptive clipping."""
+
+    # pylint: disable=too-many-arguments,too-many-locals,too-many-positional-arguments
+    def __init__(
+        self,
+        strategy: Strategy,
+        noise_multiplier: float,
+        num_sampled_clients: int,
+        initial_clipping_norm: float = 0.1,
+        target_clipped_quantile: float = 0.5,
+        clip_norm_lr: float = 0.2,
+        clipped_count_stddev: Optional[float] = None,
+    ) -> None:
+        super().__init__(
+            strategy,
+            noise_multiplier,
+            num_sampled_clients,
+            initial_clipping_norm,
+            target_clipped_quantile,
+            clip_norm_lr,
+            clipped_count_stddev,
+        )
+        self.current_arrays: ArrayRecord = ArrayRecord()
+
+    def __repr__(self) -> str:
+        """Compute a string representation of the strategy."""
+        return "Differential Privacy Strategy Wrapper (Server-Side Adaptive Clipping)"
+
+    def summary(self) -> None:
+        """Log summary configuration of the strategy."""
+        log(INFO, "\t├──> DP settings:")
+        log(INFO, "\t│\t├── Noise multiplier: %s", self.noise_multiplier)
+        log(INFO, "\t│\t├── Clipping norm: %s", self.clipping_norm)
+        log(INFO, "\t│\t├── Target clipped quantile: %s", self.target_clipped_quantile)
+        log(INFO, "\t│\t└── Clip norm learning rate: %s", self.clip_norm_lr)
+        super().summary()
+
+    def configure_train(
+        self, server_round: int, arrays: ArrayRecord, config: ConfigRecord, grid: Grid
+    ) -> Iterable[Message]:
+        """Configure the next round of training."""
+        self.current_arrays = arrays
+        return self.strategy.configure_train(server_round, arrays, config, grid)
+
+    def aggregate_train(
+        self, server_round: int, replies: Iterable[Message]
+    ) -> tuple[Optional[ArrayRecord], Optional[MetricRecord]]:
+        """Aggregate ArrayRecords and MetricRecords in the received Messages."""
+        if not validate_replies(replies, self.num_sampled_clients):
+            return None, None
+
+        current_nd = self.current_arrays.to_numpy_ndarrays()
+        clipped_indicator_count = 0
+        replies_list = list(replies)
+
+        for reply in replies_list:
+            for arr_name, record in reply.content.array_records.items():
+                reply_nd = record.to_numpy_ndarrays()
+                model_update = [
+                    np.subtract(x, y) for (x, y) in zip(reply_nd, current_nd)
+                ]
+                norm_bit = adaptive_clip_inputs_inplace(
+                    model_update, self.clipping_norm
+                )
+                clipped_indicator_count += int(norm_bit)
+                # reconstruct array using clipped contribution from current round
+                restored = [c + u for c, u in zip(current_nd, model_update)]
+                reply.content[arr_name] = ArrayRecord(
+                    OrderedDict({k: Array(v) for k, v in zip(record.keys(), restored)})
+                )
+            log(
+                INFO,
+                "aggregate_train: arrays in `ArrayRecord` are clipped by value: %.4f.",
+                self.clipping_norm,
+            )
+
+        clipped_fraction = self._noisy_fraction(
+            clipped_indicator_count, len(replies_list)
+        )
+        self._geometric_update(clipped_fraction)
+
+        aggregated_arrays, aggregated_metrics = self.strategy.aggregate_train(
+            server_round, replies_list
+        )
+
+        if aggregated_arrays:
+            aggregated_arrays = self._add_noise_to_aggregated_arrays(aggregated_arrays)
+
+        return aggregated_arrays, aggregated_metrics
+
+
+class DifferentialPrivacyClientSideAdaptiveClipping(DifferentialPrivacyAdaptiveBase):
+    """Strategy wrapper for central DP with client-side adaptive clipping.
+
+    Use `adaptiveclipping_mod` modifier at the client side.
+
+    In comparison to `DifferentialPrivacyServerSideAdaptiveClipping`,
+    which performs clipping on the server-side,
+    `DifferentialPrivacyClientSideAdaptiveClipping`
+    expects clipping to happen on the client-side, usually by using the built-in
+    `adaptiveclipping_mod`.
+
+    Parameters
+    ----------
+    strategy : Strategy
+        The strategy to which DP functionalities will be added by this wrapper.
+    noise_multiplier : float
+        The noise multiplier for the Gaussian mechanism for model updates.
+    num_sampled_clients : int
+        The number of clients that are sampled on each round.
+    initial_clipping_norm : float
+        The initial value of clipping norm. Defaults to 0.1.
+        Andrew et al. recommends to set to 0.1.
+    target_clipped_quantile : float
+        The desired quantile of updates which should be clipped. Defaults to 0.5.
+    clip_norm_lr : float
+        The learning rate for the clipping norm adaptation. Defaults to 0.2.
+        Andrew et al. recommends to set to 0.2.
+    clipped_count_stddev : float
+        The stddev of the noise added to the count of
+        updates currently below the estimate.
+        Andrew et al. recommends to set to `expected_num_records/20`
+
+    Examples
+    --------
+    Create a strategy::
+
+        strategy = fl.serverapp.FedAvg(...)
+
+    Wrap the strategy with the `DifferentialPrivacyClientSideAdaptiveClipping` wrapper::
+
+        dp_strategy = DifferentialPrivacyClientSideAdaptiveClipping(
+            strategy, cfg.noise_multiplier, cfg.num_sampled_clients, ...
+        )
+
+    On the client, add the `adaptiveclipping_mod` to the client-side mods::
+
+        app = fl.client.ClientApp(mods=[adaptiveclipping_mod])
+    """
+
+    def __repr__(self) -> str:
+        """Compute a string representation of the strategy."""
+        return "Differential Privacy Strategy Wrapper (Client-Side Adaptive Clipping)"
+
+    def summary(self) -> None:
+        """Log summary configuration of the strategy."""
+        log(INFO, "\t├──> DP settings:")
+        log(INFO, "\t│\t├── Noise multiplier: %s", self.noise_multiplier)
+        log(INFO, "\t│\t├── Clipping norm: %s", self.clipping_norm)
+        log(INFO, "\t│\t├── Target clipped quantile: %s", self.target_clipped_quantile)
+        log(INFO, "\t│\t└── Clip norm learning rate: %s", self.clip_norm_lr)
+        super().summary()
+
+    def configure_train(
+        self, server_round: int, arrays: ArrayRecord, config: ConfigRecord, grid: Grid
+    ) -> Iterable[Message]:
+        """Configure the next round of training."""
+        config[KEY_CLIPPING_NORM] = self.clipping_norm
+        return self.strategy.configure_train(server_round, arrays, config, grid)
+
+    def aggregate_train(
+        self, server_round: int, replies: Iterable[Message]
+    ) -> tuple[Optional[ArrayRecord], Optional[MetricRecord]]:
+        """Aggregate ArrayRecords and MetricRecords in the received Messages."""
+        if not validate_replies(replies, self.num_sampled_clients):
+            return None, None
+
+        replies_list = list(replies)
+
+        # validate that KEY_NORM_BIT is present in all replies
+        for msg in replies_list:
+            for _, mrec in msg.content.metric_records.items():
+                if KEY_NORM_BIT not in mrec:
+                    raise AggregationError(
+                        f"KEY_NORM_BIT ('{KEY_NORM_BIT}') not found"
+                        f" in MetricRecord or metrics for reply."
+                    )
+
+        aggregated_arrays, aggregated_metrics = self.strategy.aggregate_train(
+            server_round, replies_list
+        )
+
+        self._update_clip_norm_from_replies(replies_list)
+
+        if aggregated_arrays:
+            aggregated_arrays = self._add_noise_to_aggregated_arrays(aggregated_arrays)
+
+        return aggregated_arrays, aggregated_metrics
+
+    def _update_clip_norm_from_replies(self, replies: list[Message]) -> None:
+        total = len(replies)
+        clipped_count = 0
+
+        for msg in replies:
+            # KEY_NORM_BIT is guaranteed to be present
+            for _, mrec in msg.content.metric_records.items():
+                if KEY_NORM_BIT in mrec:
+                    clipped_count += int(bool(mrec[KEY_NORM_BIT]))
+                    break
+            else:
+                # Check fallback location
+                if hasattr(msg.content, "metrics") and isinstance(
+                    msg.content.metrics, dict
+                ):
+                    clipped_count += int(bool(msg.content.metrics[KEY_NORM_BIT]))
+
+        clipped_fraction = self._noisy_fraction(clipped_count, total)
+        self._geometric_update(clipped_fraction)