flwr-nightly 1.21.0.dev20250901__py3-none-any.whl → 1.21.0.dev20250903__py3-none-any.whl

flwr/serverapp/strategy/dp_fixed_clipping.py

@@ -0,0 +1,352 @@
+# 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/result.py

@@ -14,17 +14,91 @@
 # ==============================================================================
 """Strategy results."""
 
-
+import pprint
 from dataclasses import dataclass, field
 
 from flwr.common import ArrayRecord, MetricRecord
+from flwr.common.typing import MetricRecordValues
 
 
 @dataclass
 class Result:
-    """Data class carrying records generated during the execution of a strategy."""
+    """Data class carrying records generated during the execution of a strategy.
+
+    This class encapsulates the results of a federated learning strategy execution,
+    including the final global model parameters and metrics collected throughout
+    the federated training and evaluation (both federated and centralized) stages.
+
+    Attributes
+    ----------
+    arrays : ArrayRecord
+        The final global model parameters. Contains the
+        aggregated model weights/parameters that resulted from the federated
+        learning process.
+    train_metrics_clientapp : dict[int, MetricRecord]
+        Training metrics collected from ClientApps, indexed by round number.
+        Contains aggregated metrics (e.g., loss, accuracy) from the training
+        phase of each federated learning round.
+    evaluate_metrics_clientapp : dict[int, MetricRecord]
+        Evaluation metrics collected from ClientApps, indexed by round number.
+        Contains aggregated metrics  (e.g. validation loss) from the evaluation
+        phase where ClientApps evaluate the global model on their local
+        validation/test data.
+    evaluate_metrics_serverapp : dict[int, MetricRecord]
+        Evaluation metrics generated at the ServerApp, indexed by round number.
+        Contains metrics from centralized evaluation performed by the ServerApp
+        (e.g., when the server evaluates the global model on a held-out dataset).
+    """
 
     arrays: ArrayRecord = field(default_factory=ArrayRecord)
     train_metrics_clientapp: dict[int, MetricRecord] = field(default_factory=dict)
     evaluate_metrics_clientapp: dict[int, MetricRecord] = field(default_factory=dict)
     evaluate_metrics_serverapp: dict[int, MetricRecord] = field(default_factory=dict)
+
+    def __repr__(self) -> str:
+        """Create a representation of the Result instance."""
+        rep = ""
+        arr_size = sum(len(array.data) for array in self.arrays.values()) / (1024**2)
+        rep += "Global Arrays:\n" + f"\tArrayRecord ({arr_size:.3f} MB)\n" + "\n"
+        rep += (
+            "Aggregated Client-side Train Metrics:\n"
+            + pprint.pformat(stringify_dict(self.train_metrics_clientapp), indent=2)
+            + "\n\n"
+        )
+
+        rep += (
+            "Aggregated Client-side Evaluate Metrics:\n"
+            + pprint.pformat(stringify_dict(self.evaluate_metrics_clientapp), indent=2)
+            + "\n\n"
+        )
+
+        rep += (
+            "Server-side Evaluate Metrics:\n"
+            + pprint.pformat(stringify_dict(self.evaluate_metrics_serverapp), indent=2)
+            + "\n"
+        )
+
+        return rep
+
+
+def format_value(val: MetricRecordValues) -> str:
+    """Format a value as string, applying scientific notation for floats."""
+    if isinstance(val, float):
+        return f"{val:.4e}"
+    if isinstance(val, int):
+        return str(val)
+    if isinstance(val, list):
+        return str([f"{x:.4e}" if isinstance(x, float) else str(x) for x in val])
+    return str(val)
+
+
+def stringify_dict(d: dict[int, MetricRecord]) -> dict[int, dict[str, str]]:
+    """Return a copy results metrics but with values converted to string and formatted
+    accordingtly."""
+    new_metrics_dict = {}
+    for k, inner in d.items():
+        new_inner = {}
+        for ik, iv in inner.items():
+            new_inner[ik] = format_value(iv)
+        new_metrics_dict[k] = new_inner
+    return new_metrics_dict

flwr/serverapp/strategy/strategy.py

@@ -15,6 +15,7 @@
 """Flower message-based strategy."""
 
 
+import io
 import time
 from abc import ABC, abstractmethod
 from collections.abc import Iterable
@@ -22,11 +23,10 @@ from logging import INFO
 from typing import Callable, Optional
 
 from flwr.common import ArrayRecord, ConfigRecord, Message, MetricRecord, log
-from flwr.common.exit import ExitCode, flwr_exit
 from flwr.server import Grid
 
 from .result import Result
-from .strategy_utils import InconsistentMessageReplies, log_strategy_start_info
+from .strategy_utils import log_strategy_start_info
 
 
 class Strategy(ABC):
@@ -218,15 +218,10 @@ class Strategy(ABC):
             )
 
             # Aggregate train
-            try:
-                agg_arrays, agg_train_metrics = self.aggregate_train(
-                    current_round,
-                    train_replies,
-                )
-            except InconsistentMessageReplies as e:
-                flwr_exit(
-                    ExitCode.SERVERAPP_STRATEGY_PRECONDITION_UNMET, message=str(e)
-                )
+            agg_arrays, agg_train_metrics = self.aggregate_train(
+                current_round,
+                train_replies,
+            )
 
             # Log training metrics and append to history
             if agg_arrays is not None:
@@ -253,15 +248,10 @@ class Strategy(ABC):
             )
 
             # Aggregate evaluate
-            try:
-                agg_evaluate_metrics = self.aggregate_evaluate(
-                    current_round,
-                    evaluate_replies,
-                )
-            except InconsistentMessageReplies as e:
-                flwr_exit(
-                    ExitCode.SERVERAPP_STRATEGY_PRECONDITION_UNMET, message=str(e)
-                )
+            agg_evaluate_metrics = self.aggregate_evaluate(
+                current_round,
+                evaluate_replies,
+            )
 
             # Log training metrics and append to history
             if agg_evaluate_metrics is not None:
@@ -282,5 +272,10 @@ class Strategy(ABC):
         log(INFO, "")
         log(INFO, "Strategy execution finished in %.2fs", time.time() - t_start)
         log(INFO, "")
+        log(INFO, "Final results:")
+        log(INFO, "")
+        for line in io.StringIO(str(result)):
+            log(INFO, "\t%s", line.strip("\n"))
+        log(INFO, "")
 
         return result

flwr/serverapp/strategy/strategy_utils.py

@@ -30,13 +30,17 @@ from flwr.common import (
     RecordDict,
     log,
 )
+from flwr.common.exception import AppExitException
+from flwr.common.exit import ExitCode
 from flwr.server import Grid
 
 
-class InconsistentMessageReplies(Exception):
+class InconsistentMessageReplies(AppExitException):
     """Exception triggered when replies are inconsistent and therefore aggregation must
     be skipped."""
 
+    exit_code = ExitCode.SERVERAPP_STRATEGY_PRECONDITION_UNMET
+
     def __init__(self, reason: str):
         super().__init__(reason)
 

flwr/supercore/cli/flower_superexec.py

@@ -25,6 +25,7 @@ from flwr.common.logger import log
 from flwr.proto.clientappio_pb2_grpc import ClientAppIoStub
 from flwr.proto.serverappio_pb2_grpc import ServerAppIoStub
 from flwr.proto.simulationio_pb2_grpc import SimulationIoStub
+from flwr.supercore.grpc_health import add_args_health
 from flwr.supercore.superexec.plugin import (
     ClientAppExecPlugin,
     ExecPlugin,
@@ -57,6 +58,7 @@ def flower_superexec() -> None:
         appio_api_address=args.appio_api_address,
         flwr_dir=args.flwr_dir,
         parent_pid=args.parent_pid,
+        health_server_address=args.health_server_address,
     )
 
 
@@ -100,6 +102,7 @@ def _parse_args() -> argparse.ArgumentParser:
         help="The PID of the parent process. When set, the process will terminate "
         "when the parent process exits.",
     )
+    add_args_health(parser)
     return parser
 
 

flwr/supercore/grpc_health/__init__.py

@@ -15,8 +15,11 @@
 """GRPC health servicers."""
 
 
+from .health_server import add_args_health, run_health_server_grpc_no_tls
 from .simple_health_servicer import SimpleHealthServicer
 
 __all__ = [
     "SimpleHealthServicer",
+    "add_args_health",
+    "run_health_server_grpc_no_tls",
 ]

flwr/supercore/grpc_health/health_server.py

@@ -0,0 +1,53 @@
+# 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.
+# ==============================================================================
+"""Health servers."""
+
+
+import argparse
+from logging import INFO
+
+import grpc
+from grpc_health.v1.health_pb2_grpc import add_HealthServicer_to_server
+
+from flwr.common.grpc import generic_create_grpc_server
+from flwr.common.logger import log
+
+from .simple_health_servicer import SimpleHealthServicer
+
+
+def run_health_server_grpc_no_tls(address: str) -> grpc.Server:
+    """Run gRPC health server with no TLS."""
+    health_server = generic_create_grpc_server(
+        servicer_and_add_fn=(
+            SimpleHealthServicer(),
+            add_HealthServicer_to_server,
+        ),
+        server_address=address,
+        certificates=None,
+    )
+    log(INFO, "Starting gRPC health server on %s", address)
+    health_server.start()
+    return health_server
+
+
+def add_args_health(parser: argparse.ArgumentParser) -> None:
+    """Add arguments for health server."""
+    parser.add_argument(
+        "--health-server-address",
+        type=str,
+        default=None,
+        help="Health service gRPC server address (IPv4, IPv6, or a domain name) "
+        "with no TLS. If not set, the health server will not be started.",
+    )

flwr/supercore/grpc_health/simple_health_servicer.py

@@ -28,11 +28,11 @@ class SimpleHealthServicer(HealthServicer):  # type: ignore
     """A simple gRPC health servicer that always returns SERVING."""
 
     def Check(
-        self, request: HealthCheckRequest, context: grpc.RpcContext
+        self, request: HealthCheckRequest, context: grpc.ServicerContext
     ) -> HealthCheckResponse:
         """Return a HealthCheckResponse with SERVING status."""
         return HealthCheckResponse(status=HealthCheckResponse.SERVING)
 
-    def Watch(self, request: HealthCheckRequest, context: grpc.RpcContext) -> None:
+    def Watch(self, request: HealthCheckRequest, context: grpc.ServicerContext) -> None:
         """Watch the health status (not implemented)."""
         context.abort(grpc.StatusCode.UNIMPLEMENTED, "Watch is not implemented")