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

flwr/serverapp/strategy/fedyogi.py

@@ -0,0 +1,173 @@
+# 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.
+# ==============================================================================
+"""Adaptive Federated Optimization using Yogi (FedYogi) [Reddi et al., 2020] strategy.
+
+Paper: arxiv.org/abs/2003.00295
+"""
+
+
+from collections import OrderedDict
+from collections.abc import Iterable
+from typing import Callable, Optional
+
+import numpy as np
+
+from flwr.common import Array, ArrayRecord, Message, MetricRecord, RecordDict
+
+from ..exception import AggregationError
+from .fedopt import FedOpt
+
+
+# pylint: disable=line-too-long
+class FedYogi(FedOpt):
+    """FedYogi [Reddi et al., 2020] strategy.
+
+    Implementation based on https://arxiv.org/abs/2003.00295v5
+
+
+    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.
+    weighted_by_key : str (default: "num-examples")
+        The key within each MetricRecord whose value is used as the weight when
+        computing weighted averages for both ArrayRecords and 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.
+    eta : float, optional
+        Server-side learning rate. Defaults to 1e-2.
+    eta_l : float, optional
+        Client-side learning rate. Defaults to 0.0316.
+    beta_1 : float, optional
+        Momentum parameter. Defaults to 0.9.
+    beta_2 : float, optional
+        Second moment parameter. Defaults to 0.99.
+    tau : float, optional
+        Controls the algorithm's degree of adaptability.
+        Defaults to 1e-3.
+    """
+
+    # pylint: disable=too-many-arguments, too-many-locals
+    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,
+        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,
+        eta: float = 1e-2,
+        eta_l: float = 0.0316,
+        beta_1: float = 0.9,
+        beta_2: float = 0.99,
+        tau: float = 1e-3,
+    ) -> 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,
+            eta=eta,
+            eta_l=eta_l,
+            beta_1=beta_1,
+            beta_2=beta_2,
+            tau=tau,
+        )
+
+    def aggregate_train(
+        self,
+        server_round: int,
+        replies: Iterable[Message],
+    ) -> tuple[Optional[ArrayRecord], Optional[MetricRecord]]:
+        """Aggregate ArrayRecords and MetricRecords in the received Messages."""
+        aggregated_arrayrecord, aggregated_metrics = super().aggregate_train(
+            server_round, replies
+        )
+
+        if aggregated_arrayrecord is None:
+            return aggregated_arrayrecord, aggregated_metrics
+
+        if self.current_arrays is None:
+            reason = (
+                "Current arrays not set. Ensure that `configure_train` has been "
+                "called before aggregation."
+            )
+            raise AggregationError(reason=reason)
+
+        # Compute intermediate variables
+        delta_t, m_t, aggregated_ndarrays = self._compute_deltat_and_mt(
+            aggregated_arrayrecord
+        )
+
+        # v_t
+        if not self.v_t:
+            self.v_t = {k: np.zeros_like(v) for k, v in aggregated_ndarrays.items()}
+        self.v_t = {
+            k: v
+            - (1.0 - self.beta_2) * (delta_t[k] ** 2) * np.sign(v - delta_t[k] ** 2)
+            for k, v in self.v_t.items()
+        }
+
+        new_arrays = {
+            k: x + self.eta * m_t[k] / (np.sqrt(self.v_t[k]) + self.tau)
+            for k, x in self.current_arrays.items()
+        }
+
+        # Update current arrays
+        self.current_arrays = new_arrays
+
+        return (
+            ArrayRecord(OrderedDict({k: Array(v) for k, v in new_arrays.items()})),
+            aggregated_metrics,
+        )

flwr/serverapp/strategy/result.py

@@ -0,0 +1,105 @@
+# 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.
+# ==============================================================================
+"""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.
+
+    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 ClientApp-side Train Metrics:\n"
+            + pprint.pformat(stringify_dict(self.train_metrics_clientapp), indent=2)
+            + "\n\n"
+        )
+
+        rep += (
+            "Aggregated ClientApp-side Evaluate Metrics:\n"
+            + pprint.pformat(stringify_dict(self.evaluate_metrics_clientapp), indent=2)
+            + "\n\n"
+        )
+
+        rep += (
+            "ServerApp-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

@@ -0,0 +1,285 @@
+# 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.
+# ==============================================================================
+"""Flower message-based strategy."""
+
+
+import io
+import time
+from abc import ABC, abstractmethod
+from collections.abc import Iterable
+from logging import INFO
+from typing import Callable, Optional
+
+from flwr.common import ArrayRecord, ConfigRecord, Message, MetricRecord, log
+from flwr.server import Grid
+
+from .result import Result
+from .strategy_utils import log_strategy_start_info
+
+
+class Strategy(ABC):
+    """Abstract base class for server strategy implementations."""
+
+    @abstractmethod
+    def configure_train(
+        self, server_round: int, arrays: ArrayRecord, config: ConfigRecord, grid: Grid
+    ) -> Iterable[Message]:
+        """Configure the next round of training.
+
+        Parameters
+        ----------
+        server_round : int
+            The current round of federated learning.
+        arrays : ArrayRecord
+            Current global ArrayRecord (e.g. global model) to be sent to client
+            nodes for training.
+        config : ConfigRecord
+            Configuration to be sent to clients nodes for training.
+        grid : Grid
+            The Grid instance used for node sampling and communication.
+
+        Returns
+        -------
+        Iterable[Message]
+            An iterable of messages to be sent to selected client nodes for training.
+        """
+
+    @abstractmethod
+    def aggregate_train(
+        self,
+        server_round: int,
+        replies: Iterable[Message],
+    ) -> tuple[Optional[ArrayRecord], Optional[MetricRecord]]:
+        """Aggregate training results from client nodes.
+
+        Parameters
+        ----------
+        server_round : int
+            The current round of federated learning, starting from 1.
+        replies : Iterable[Message]
+            Iterable of reply messages received from client nodes after training.
+            Each message contains ArrayRecords and MetricRecords that get aggregated.
+
+        Returns
+        -------
+        tuple[Optional[ArrayRecord], Optional[MetricRecord]]
+            A tuple containing:
+            - ArrayRecord: Aggregated ArrayRecord, or None if aggregation failed
+            - MetricRecord: Aggregated MetricRecord, or None if aggregation failed
+        """
+
+    @abstractmethod
+    def configure_evaluate(
+        self, server_round: int, arrays: ArrayRecord, config: ConfigRecord, grid: Grid
+    ) -> Iterable[Message]:
+        """Configure the next round of evaluation.
+
+        Parameters
+        ----------
+        server_round : int
+            The current round of federated learning.
+        arrays : ArrayRecord
+            Current global ArrayRecord (e.g. global model) to be sent to client
+            nodes for evaluation.
+        config : ConfigRecord
+            Configuration to be sent to clients nodes for evaluation.
+        grid : Grid
+            The Grid instance used for node sampling and communication.
+
+        Returns
+        -------
+        Iterable[Message]
+            An iterable of messages to be sent to selected client nodes for evaluation.
+        """
+
+    @abstractmethod
+    def aggregate_evaluate(
+        self,
+        server_round: int,
+        replies: Iterable[Message],
+    ) -> Optional[MetricRecord]:
+        """Aggregate evaluation metrics from client nodes.
+
+        Parameters
+        ----------
+        server_round : int
+            The current round of federated learning.
+        replies : Iterable[Message]
+            Iterable of reply messages received from client nodes after evaluation.
+            MetricRecords in the messages are aggregated.
+
+        Returns
+        -------
+        Optional[MetricRecord]
+            Aggregated evaluation metrics from all participating clients,
+            or None if aggregation failed.
+        """
+
+    @abstractmethod
+    def summary(self) -> None:
+        """Log summary configuration of the strategy."""
+
+    # pylint: disable=too-many-arguments, too-many-positional-arguments, too-many-locals
+    def start(
+        self,
+        grid: Grid,
+        initial_arrays: ArrayRecord,
+        num_rounds: int = 3,
+        timeout: float = 3600,
+        train_config: Optional[ConfigRecord] = None,
+        evaluate_config: Optional[ConfigRecord] = None,
+        evaluate_fn: Optional[
+            Callable[[int, ArrayRecord], Optional[MetricRecord]]
+        ] = None,
+    ) -> Result:
+        """Execute the federated learning strategy.
+
+        Runs the complete federated learning workflow for the specified number of
+        rounds, including training, evaluation, and optional centralized evaluation.
+
+        Parameters
+        ----------
+        grid : Grid
+            The Grid instance used to send/receive Messages from nodes executing a
+            ClientApp.
+        initial_arrays : ArrayRecord
+            Initial model parameters (arrays) to be used for federated learning.
+        num_rounds : int (default: 3)
+            Number of federated learning rounds to execute.
+        timeout : float (default: 3600)
+            Timeout in seconds for waiting for node responses.
+        train_config : ConfigRecord, optional
+            Configuration to be sent to nodes during training rounds.
+            If unset, an empty ConfigRecord will be used.
+        evaluate_config : ConfigRecord, optional
+            Configuration to be sent to nodes during evaluation rounds.
+            If unset, an empty ConfigRecord will be used.
+        evaluate_fn : Callable[[int, ArrayRecord], Optional[MetricRecord]], optional
+            Optional function for centralized evaluation of the global model. Takes
+            server round number and array record, returns a MetricRecord or None. If
+            provided, will be called before the first round and after each round.
+            Defaults to None.
+
+        Returns
+        -------
+        Results
+            Results containing final model arrays and also training metrics, evaluation
+            metrics and global evaluation metrics (if provided) from all rounds.
+        """
+        log(INFO, "Starting %s strategy:", self.__class__.__name__)
+        log_strategy_start_info(
+            num_rounds, initial_arrays, train_config, evaluate_config
+        )
+        self.summary()
+        log(INFO, "")
+
+        # Initialize if None
+        train_config = ConfigRecord() if train_config is None else train_config
+        evaluate_config = ConfigRecord() if evaluate_config is None else evaluate_config
+        result = Result()
+
+        t_start = time.time()
+        # Evaluate starting global parameters
+        if evaluate_fn:
+            res = evaluate_fn(0, initial_arrays)
+            log(INFO, "Initial global evaluation results: %s", res)
+            if res is not None:
+                result.evaluate_metrics_serverapp[0] = res
+
+        arrays = initial_arrays
+
+        for current_round in range(1, num_rounds + 1):
+            log(INFO, "")
+            log(INFO, "[ROUND %s/%s]", current_round, num_rounds)
+
+            # -----------------------------------------------------------------
+            # --- TRAINING (CLIENTAPP-SIDE) -----------------------------------
+            # -----------------------------------------------------------------
+
+            # Call strategy to configure training round
+            # Send messages and wait for replies
+            train_replies = grid.send_and_receive(
+                messages=self.configure_train(
+                    current_round,
+                    arrays,
+                    train_config,
+                    grid,
+                ),
+                timeout=timeout,
+            )
+
+            # Aggregate train
+            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:
+                result.arrays = agg_arrays
+                arrays = agg_arrays
+            if agg_train_metrics is not None:
+                log(INFO, "\t└──> Aggregated MetricRecord: %s", agg_train_metrics)
+                result.train_metrics_clientapp[current_round] = agg_train_metrics
+
+            # -----------------------------------------------------------------
+            # --- EVALUATION (CLIENTAPP-SIDE) ---------------------------------
+            # -----------------------------------------------------------------
+
+            # Call strategy to configure evaluation round
+            # Send messages and wait for replies
+            evaluate_replies = grid.send_and_receive(
+                messages=self.configure_evaluate(
+                    current_round,
+                    arrays,
+                    evaluate_config,
+                    grid,
+                ),
+                timeout=timeout,
+            )
+
+            # Aggregate evaluate
+            agg_evaluate_metrics = self.aggregate_evaluate(
+                current_round,
+                evaluate_replies,
+            )
+
+            # Log training metrics and append to history
+            if agg_evaluate_metrics is not None:
+                log(INFO, "\t└──> Aggregated MetricRecord: %s", agg_evaluate_metrics)
+                result.evaluate_metrics_clientapp[current_round] = agg_evaluate_metrics
+
+            # -----------------------------------------------------------------
+            # --- EVALUATION (SERVERAPP-SIDE) ---------------------------------
+            # -----------------------------------------------------------------
+
+            # Centralized evaluation
+            if evaluate_fn:
+                log(INFO, "Global evaluation")
+                res = evaluate_fn(current_round, arrays)
+                log(INFO, "\t└──> MetricRecord: %s", res)
+                if res is not None:
+                    result.evaluate_metrics_serverapp[current_round] = res
+
+        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