flwr-nightly 1.22.0.dev20250917__py3-none-any.whl → 1.22.0.dev20250919__py3-none-any.whl

flwr/serverapp/dp_fixed_clipping.py

@@ -1,352 +0,0 @@
-# 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 fixed clipping.
-
-Papers: https://arxiv.org/abs/1712.07557, https://arxiv.org/abs/1710.06963
-"""
-
-from abc import ABC
-from collections import OrderedDict
-from collections.abc import Iterable
-from logging import INFO, WARNING
-from typing import Optional
-
-from flwr.common import Array, ArrayRecord, ConfigRecord, Message, MetricRecord, log
-from flwr.common.differential_privacy import (
-    add_gaussian_noise_inplace,
-    compute_clip_model_update,
-    compute_stdv,
-)
-from flwr.common.differential_privacy_constants import (
-    CLIENTS_DISCREPANCY_WARNING,
-    KEY_CLIPPING_NORM,
-)
-from flwr.server import Grid
-
-from .strategy import Strategy
-
-
-class DifferentialPrivacyFixedClippingBase(Strategy, ABC):
-    """Base class for DP strategies with fixed clipping.
-
-    This class contains common functionality shared between server-side and
-    client-side fixed clipping implementations.
-
-    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.
-        A value of 1.0 or higher is recommended for strong privacy.
-    clipping_norm : float
-        The value of the clipping norm.
-    num_sampled_clients : int
-        The number of clients that are sampled on each round.
-    """
-
-    # pylint: disable=too-many-arguments,too-many-instance-attributes
-    def __init__(
-        self,
-        strategy: Strategy,
-        noise_multiplier: float,
-        clipping_norm: float,
-        num_sampled_clients: int,
-    ) -> None:
-        super().__init__()
-
-        self.strategy = strategy
-
-        if noise_multiplier < 0:
-            raise ValueError("The noise multiplier should be a non-negative value.")
-
-        if clipping_norm <= 0:
-            raise ValueError("The clipping norm should be a positive value.")
-
-        if num_sampled_clients <= 0:
-            raise ValueError(
-                "The number of sampled clients should be a positive value."
-            )
-
-        self.noise_multiplier = noise_multiplier
-        self.clipping_norm = clipping_norm
-        self.num_sampled_clients = num_sampled_clients
-
-    def _validate_replies(self, replies: Iterable[Message]) -> bool:
-        """Validate replies and log errors/warnings.
-
-        Returns
-        -------
-        bool
-            True if replies are valid for aggregation, False otherwise.
-        """
-        num_errors = 0
-        num_replies_with_content = 0
-        for msg in replies:
-            if msg.has_error():
-                log(
-                    INFO,
-                    "Received error in reply from node %d: %s",
-                    msg.metadata.src_node_id,
-                    msg.error,
-                )
-                num_errors += 1
-            else:
-                num_replies_with_content += 1
-
-        # Errors are not allowed
-        if num_errors:
-            log(
-                INFO,
-                "aggregate_train: Some clients reported errors. Skipping aggregation.",
-            )
-            return False
-
-        log(
-            INFO,
-            "aggregate_train: Received %s results and %s failures",
-            num_replies_with_content,
-            num_errors,
-        )
-
-        if num_replies_with_content != self.num_sampled_clients:
-            log(
-                WARNING,
-                CLIENTS_DISCREPANCY_WARNING,
-                num_replies_with_content,
-                self.num_sampled_clients,
-            )
-
-        return True
-
-    def _add_noise_to_aggregated_arrays(
-        self, aggregated_arrays: ArrayRecord
-    ) -> ArrayRecord:
-        """Add Gaussian noise to aggregated arrays.
-
-        Parameters
-        ----------
-        aggregated_arrays : ArrayRecord
-            The aggregated arrays to add noise to.
-
-        Returns
-        -------
-        ArrayRecord
-            The aggregated arrays with noise added.
-        """
-        aggregated_ndarrays = aggregated_arrays.to_numpy_ndarrays()
-        stdv = compute_stdv(
-            self.noise_multiplier, self.clipping_norm, self.num_sampled_clients
-        )
-        add_gaussian_noise_inplace(aggregated_ndarrays, 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_arrays.keys(), aggregated_ndarrays)
-                }
-            )
-        )
-
-    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 DifferentialPrivacyServerSideFixedClipping(DifferentialPrivacyFixedClippingBase):
-    """Strategy wrapper for central DP with server-side fixed clipping.
-
-    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.
-        A value of 1.0 or higher is recommended for strong privacy.
-    clipping_norm : float
-        The value of the clipping norm.
-    num_sampled_clients : int
-        The number of clients that are sampled on each round.
-
-    Examples
-    --------
-    Create a strategy::
-
-        strategy = fl.serverapp.FedAvg( ... )
-
-    Wrap the strategy with the `DifferentialPrivacyServerSideFixedClipping` wrapper::
-
-        dp_strategy = DifferentialPrivacyServerSideFixedClipping(
-            strategy, cfg.noise_multiplier, cfg.clipping_norm, cfg.num_sampled_clients
-        )
-    """
-
-    def __init__(
-        self,
-        strategy: Strategy,
-        noise_multiplier: float,
-        clipping_norm: float,
-        num_sampled_clients: int,
-    ) -> None:
-        super().__init__(strategy, noise_multiplier, clipping_norm, num_sampled_clients)
-        self.current_arrays: ArrayRecord = ArrayRecord()
-
-    def __repr__(self) -> str:
-        """Compute a string representation of the strategy."""
-        return "Differential Privacy Strategy Wrapper (Server-Side Fixed Clipping)"
-
-    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 self._validate_replies(replies):
-            return None, None
-
-        # Clip arrays in replies
-        current_ndarrays = self.current_arrays.to_numpy_ndarrays()
-        for reply in replies:
-            for arr_name, record in reply.content.array_records.items():
-                # Clip
-                reply_ndarrays = record.to_numpy_ndarrays()
-                compute_clip_model_update(
-                    param1=reply_ndarrays,
-                    param2=current_ndarrays,
-                    clipping_norm=self.clipping_norm,
-                )
-                # Replace content while preserving keys
-                reply.content[arr_name] = ArrayRecord(
-                    OrderedDict(
-                        {k: Array(v) for k, v in zip(record.keys(), reply_ndarrays)}
-                    )
-                )
-            log(
-                INFO,
-                "aggregate_fit: parameters are clipped by value: %.4f.",
-                self.clipping_norm,
-            )
-
-        # Pass the new parameters for aggregation
-        aggregated_arrays, aggregated_metrics = self.strategy.aggregate_train(
-            server_round, replies
-        )
-
-        # Add Gaussian noise to the aggregated arrays
-        if aggregated_arrays:
-            aggregated_arrays = self._add_noise_to_aggregated_arrays(aggregated_arrays)
-
-        return aggregated_arrays, aggregated_metrics
-
-
-class DifferentialPrivacyClientSideFixedClipping(DifferentialPrivacyFixedClippingBase):
-    """Strategy wrapper for central DP with client-side fixed clipping.
-
-    Use `fixedclipping_mod` modifier at the client side.
-
-    In comparison to `DifferentialPrivacyServerSideFixedClipping`,
-    which performs clipping on the server-side,
-    `DifferentialPrivacyClientSideFixedClipping` expects clipping to happen
-    on the client-side, usually by using the built-in `fixedclipping_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.
-        A value of 1.0 or higher is recommended for strong privacy.
-    clipping_norm : float
-        The value of the clipping norm.
-    num_sampled_clients : int
-        The number of clients that are sampled on each round.
-
-    Examples
-    --------
-    Create a strategy::
-
-        strategy = fl.serverapp.FedAvg(...)
-
-    Wrap the strategy with the `DifferentialPrivacyClientSideFixedClipping` wrapper::
-
-        dp_strategy = DifferentialPrivacyClientSideFixedClipping(
-            strategy, cfg.noise_multiplier, cfg.clipping_norm, cfg.num_sampled_clients
-        )
-
-    On the client, add the `fixedclipping_mod` to the client-side mods::
-
-        app = fl.client.ClientApp(mods=[fixedclipping_mod])
-    """
-
-    def __repr__(self) -> str:
-        """Compute a string representation of the strategy."""
-        return "Differential Privacy Strategy Wrapper (Client-Side Fixed Clipping)"
-
-    def configure_train(
-        self, server_round: int, arrays: ArrayRecord, config: ConfigRecord, grid: Grid
-    ) -> Iterable[Message]:
-        """Configure the next round of training."""
-        # Inject clipping norm in config
-        config[KEY_CLIPPING_NORM] = self.clipping_norm
-        # Call parent method
-        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 self._validate_replies(replies):
-            return None, None
-
-        # Aggregate
-        aggregated_arrays, aggregated_metrics = self.strategy.aggregate_train(
-            server_round, replies
-        )
-
-        # Add Gaussian noise to the aggregated arrays
-        if aggregated_arrays:
-            aggregated_arrays = self._add_noise_to_aggregated_arrays(aggregated_arrays)
-
-        return aggregated_arrays, aggregated_metrics

flwr/serverapp/strategy/strategy_utils_tests.py

@@ -1,323 +0,0 @@
-# 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.
-# ==============================================================================
-"""Tests for message-based strategy utilities."""
-
-
-from collections import OrderedDict
-from unittest.mock import Mock
-
-import numpy as np
-import pytest
-from parameterized import parameterized
-
-from flwr.common import (
-    Array,
-    ArrayRecord,
-    ConfigRecord,
-    Message,
-    MetricRecord,
-    RecordDict,
-)
-from flwr.serverapp.exception import InconsistentMessageReplies
-
-from .strategy_utils import (
-    aggregate_arrayrecords,
-    aggregate_metricrecords,
-    config_to_str,
-    validate_message_reply_consistency,
-)
-
-
-def create_mock_reply(arrays: ArrayRecord, num_examples: float) -> Message:
-    """Create a mock reply Message with default keys."""
-    message = Mock(spec=Message)
-    message.content = RecordDict(
-        {"arrays": arrays, "metrics": MetricRecord({"num-examples": num_examples})}
-    )
-    message.has_error.side_effect = lambda: False
-    message.has_content.side_effect = lambda: True
-    return message
-
-
-def test_config_to_str() -> None:
-    """Test that items of types bytes are masked out."""
-    config = ConfigRecord({"a": 123, "b": [1, 2, 3], "c": b"bytes"})
-    expected_str = "{'a': 123, 'b': [1, 2, 3], 'c': <bytes>}"
-    assert config_to_str(config) == expected_str
-
-
-def test_arrayrecords_aggregation() -> None:
-    """Test aggregation of ArrayRecords."""
-    num_replies = 3
-    num_arrays = 4
-    weights = [0.25, 0.4, 0.35]
-    np_arrays = [
-        [np.random.randn(7, 3) for _ in range(num_arrays)] for _ in range(num_replies)
-    ]
-
-    avg_list = [
-        np.average([lst[i] for lst in np_arrays], axis=0, weights=weights)
-        for i in range(num_arrays)
-    ]
-
-    # Construct RecordDicts (mimicing replies)
-    records = [
-        RecordDict(
-            {
-                "arrays": ArrayRecord(np_arrays[i]),
-                "metrics": MetricRecord({"weight": weights[i]}),
-            }
-        )
-        for i in range(num_replies)
-    ]
-    # Execute aggregate
-    aggrd = aggregate_arrayrecords(records, weighting_metric_name="weight")
-
-    # Assert consistency
-    assert all(np.allclose(a, b) for a, b in zip(aggrd.to_numpy_ndarrays(), avg_list))
-    assert aggrd.object_id == ArrayRecord(avg_list).object_id
-
-
-def test_arrayrecords_aggregation_with_ndim_zero() -> None:
-    """Test aggregation of ArrayRecords with 0-dim arrays."""
-    num_replies = 3
-    weights = [0.25, 0.4, 0.35]
-    np_arrays = [np.array(np.random.randn()) for _ in range(num_replies)]
-
-    # For 0-dimensional arrays, we just compute the weighted average directly
-    avg_list = [np.average(np_arrays, axis=0, weights=weights)]
-
-    # Construct RecordDicts (mimicing replies)
-    records = [
-        RecordDict(
-            {
-                "arrays": ArrayRecord([np_arrays[i]]),
-                "metrics": MetricRecord({"weight": weights[i]}),
-            }
-        )
-        for i in range(num_replies)
-    ]
-    # Execute aggregate
-    aggrd = aggregate_arrayrecords(records, weighting_metric_name="weight")
-
-    # Assert consistency
-    assert np.isclose(aggrd.to_numpy_ndarrays()[0], avg_list[0])
-    assert aggrd.object_id == ArrayRecord([np.array(avg_list[0])]).object_id
-
-
-def test_metricrecords_aggregation() -> None:
-    """Test aggregation of MetricRecords."""
-    num_replies = 3
-    weights = [0.25, 0.4, 0.35]
-    metric_records = [
-        MetricRecord({"a": 1, "b": 2.0, "c": np.random.randn(3).tolist()})
-        for _ in range(num_replies)
-    ]
-
-    # Compute expected aggregated MetricRecord.
-    # For ease, we convert everything into numpy arrays, then aggregate
-    as_np_entries = [
-        {
-            k: np.array(v) if isinstance(v, (int, float, list)) else v
-            for k, v in record.items()
-        }
-        for record in metric_records
-    ]
-    avg_list = [
-        np.average(
-            [list(entries.values())[i] for entries in as_np_entries],
-            axis=0,
-            weights=weights,
-        ).tolist()
-        for i in range(len(as_np_entries[0]))
-    ]
-    expected_record = MetricRecord(dict(zip(as_np_entries[0].keys(), avg_list)))
-    expected_record["a"] = float(expected_record["a"])  # type: ignore
-    expected_record["b"] = float(expected_record["b"])  # type: ignore
-
-    # Construct RecordDicts (mimicing replies)
-    # Inject weighting factor
-    records = [
-        RecordDict(
-            {
-                "metrics": MetricRecord(
-                    record.__dict__["_data"] | {"weight": weights[i]}
-                ),
-            }
-        )
-        for i, record in enumerate(metric_records)
-    ]
-
-    # Execute aggregate
-    aggrd = aggregate_metricrecords(records, weighting_metric_name="weight")
-    # Assert
-    assert expected_record.object_id == aggrd.object_id
-
-
-@parameterized.expand(  # type: ignore
-    [
-        (
-            True,
-            RecordDict(
-                {
-                    "global-model": ArrayRecord([np.random.randn(7, 3)]),
-                    "metrics": MetricRecord({"weight": 0.123}),
-                }
-            ),
-        ),  # Compliant
-        (
-            False,
-            RecordDict(
-                {
-                    "global-model": ArrayRecord([np.random.randn(7, 3)]),
-                    "metrics": MetricRecord({"weight": [0.123]}),
-                }
-            ),
-        ),  # Weighting key is not a scalar (BAD)
-        (
-            False,
-            RecordDict(
-                {
-                    "global-model": ArrayRecord([np.random.randn(7, 3)]),
-                    "metrics": MetricRecord({"loss": 0.01}),
-                }
-            ),
-        ),  # No weighting key in MetricRecord (BAD)
-        (
-            False,
-            RecordDict({"global-model": ArrayRecord([np.random.randn(7, 3)])}),
-        ),  # No MetricsRecord (BAD)
-        (
-            False,
-            RecordDict(
-                {
-                    "global-model": ArrayRecord([np.random.randn(7, 3)]),
-                    "another-model": ArrayRecord([np.random.randn(7, 3)]),
-                }
-            ),
-        ),  # Two ArrayRecords (BAD)
-        (
-            False,
-            RecordDict(
-                {
-                    "global-model": ArrayRecord([np.random.randn(7, 3)]),
-                    "metrics": MetricRecord({"weight": 0.123}),
-                    "more-metrics": MetricRecord({"loss": 0.321}),
-                }
-            ),
-        ),  # Two MetricRecords (BAD)
-    ]
-)
-def test_consistency_of_replies_with_matching_keys(
-    is_valid: bool, recorddict: RecordDict
-) -> None:
-    """Test consistency in replies."""
-    # Create dummy records
-    records = [recorddict for _ in range(3)]
-
-    if not is_valid:
-        # Should raise InconsistentMessageReplies exception
-        with pytest.raises(InconsistentMessageReplies):
-            validate_message_reply_consistency(
-                records, weighted_by_key="weight", check_arrayrecord=True
-            )
-    else:
-        # Should not raise an exception
-        validate_message_reply_consistency(
-            records, weighted_by_key="weight", check_arrayrecord=True
-        )
-
-
-@parameterized.expand(  # type: ignore
-    [
-        (
-            [
-                RecordDict(
-                    {
-                        "global-model": ArrayRecord([np.random.randn(7, 3)]),
-                        "metrics": MetricRecord({"weight": 0.123}),
-                    }
-                ),
-                RecordDict(
-                    {
-                        "model": ArrayRecord([np.random.randn(7, 3)]),
-                        "metrics": MetricRecord({"weight": 0.123}),
-                    }
-                ),
-            ],
-        ),  # top-level keys don't match for ArrayRecords
-        (
-            [
-                RecordDict(
-                    {
-                        "global-model": ArrayRecord(
-                            OrderedDict({"a": Array(np.random.randn(7, 3))})
-                        ),
-                        "metrics": MetricRecord({"weight": 0.123}),
-                    }
-                ),
-                RecordDict(
-                    {
-                        "global-model": ArrayRecord(
-                            OrderedDict({"b": Array(np.random.randn(7, 3))})
-                        ),
-                        "metrics": MetricRecord({"weight": 0.123}),
-                    }
-                ),
-            ],
-        ),  # top-level keys match for ArrayRecords but not those for Arrays
-        (
-            [
-                RecordDict(
-                    {
-                        "global-model": ArrayRecord([np.random.randn(7, 3)]),
-                        "metrics": MetricRecord({"weight": 0.123}),
-                    }
-                ),
-                RecordDict(
-                    {
-                        "global-model": ArrayRecord([np.random.randn(7, 3)]),
-                        "my-metrics": MetricRecord({"weight": 0.123}),
-                    }
-                ),
-            ],
-        ),  # top-level keys don't match for MetricRecords
-        (
-            [
-                RecordDict(
-                    {
-                        "global-model": ArrayRecord([np.random.randn(7, 3)]),
-                        "metrics": MetricRecord({"weight": 0.123}),
-                    }
-                ),
-                RecordDict(
-                    {
-                        "global-model": ArrayRecord([np.random.randn(7, 3)]),
-                        "my-metrics": MetricRecord({"my-weights": 0.123}),
-                    }
-                ),
-            ],
-        ),  # top-level keys match for MetricRecords but not inner ones
-    ]
-)
-def test_consistency_of_replies_with_different_keys(
-    list_records: list[RecordDict],
-) -> None:
-    """Test consistency in replies when records don't have matching keys."""
-    # All test cases expect InconsistentMessageReplies exception to be raised
-    with pytest.raises(InconsistentMessageReplies):
-        validate_message_reply_consistency(
-            list_records, weighted_by_key="weight", check_arrayrecord=True
-        )