flwr-nightly 1.8.0.dev20240309__py3-none-any.whl → 1.8.0.dev20240311__py3-none-any.whl

flwr/server/workflow/default_workflows.py

@@ -15,8 +15,9 @@
 """Legacy default workflows."""
 
 
+import io
 import timeit
-from logging import DEBUG, INFO
+from logging import INFO
 from typing import Optional, cast
 
 import flwr.common.recordset_compat as compat
@@ -27,11 +28,7 @@ from ..compat.app_utils import start_update_client_manager_thread
 from ..compat.legacy_context import LegacyContext
 from ..driver import Driver
 from ..typing import Workflow
-
-KEY_CURRENT_ROUND = "current_round"
-KEY_START_TIME = "start_time"
-CONFIGS_RECORD_KEY = "config"
-PARAMS_RECORD_KEY = "parameters"
+from .constant import MAIN_CONFIGS_RECORD, MAIN_PARAMS_RECORD, Key
 
 
 class DefaultWorkflow:
@@ -62,17 +59,19 @@ class DefaultWorkflow:
         )
 
         # Initialize parameters
+        log(INFO, "[INIT]")
         default_init_params_workflow(driver, context)
 
         # Run federated learning for num_rounds
-        log(INFO, "FL starting")
         start_time = timeit.default_timer()
         cfg = ConfigsRecord()
-        cfg[KEY_START_TIME] = start_time
-        context.state.configs_records[CONFIGS_RECORD_KEY] = cfg
+        cfg[Key.START_TIME] = start_time
+        context.state.configs_records[MAIN_CONFIGS_RECORD] = cfg
 
         for current_round in range(1, context.config.num_rounds + 1):
-            cfg[KEY_CURRENT_ROUND] = current_round
+            log(INFO, "")
+            log(INFO, "[ROUND %s]", current_round)
+            cfg[Key.CURRENT_ROUND] = current_round
 
             # Fit round
             self.fit_workflow(driver, context)
@@ -83,22 +82,19 @@ class DefaultWorkflow:
             # Evaluate round
             self.evaluate_workflow(driver, context)
 
-        # Bookkeeping
+        # Bookkeeping and log results
         end_time = timeit.default_timer()
         elapsed = end_time - start_time
-        log(INFO, "FL finished in %s", elapsed)
-
-        # Log results
         hist = context.history
-        log(INFO, "app_fit: losses_distributed %s", str(hist.losses_distributed))
-        log(
-            INFO,
-            "app_fit: metrics_distributed_fit %s",
-            str(hist.metrics_distributed_fit),
-        )
-        log(INFO, "app_fit: metrics_distributed %s", str(hist.metrics_distributed))
-        log(INFO, "app_fit: losses_centralized %s", str(hist.losses_centralized))
-        log(INFO, "app_fit: metrics_centralized %s", str(hist.metrics_centralized))
+        log(INFO, "")
+        log(INFO, "[SUMMARY]")
+        log(INFO, "Run finished %s rounds in %.2fs", context.config.num_rounds, elapsed)
+        for idx, line in enumerate(io.StringIO(str(hist))):
+            if idx == 0:
+                log(INFO, "%s", line.strip("\n"))
+            else:
+                log(INFO, "\t%s", line.strip("\n"))
+        log(INFO, "")
 
         # Terminate the thread
         f_stop.set()
@@ -111,12 +107,11 @@ def default_init_params_workflow(driver: Driver, context: Context) -> None:
     if not isinstance(context, LegacyContext):
         raise TypeError(f"Expect a LegacyContext, but get {type(context).__name__}.")
 
-    log(INFO, "Initializing global parameters")
     parameters = context.strategy.initialize_parameters(
         client_manager=context.client_manager
     )
     if parameters is not None:
-        log(INFO, "Using initial parameters provided by strategy")
+        log(INFO, "Using initial global parameters provided by strategy")
         paramsrecord = compat.parameters_to_parametersrecord(
             parameters, keep_input=True
         )
@@ -141,10 +136,10 @@ def default_init_params_workflow(driver: Driver, context: Context) -> None:
         msg = list(messages)[0]
         paramsrecord = next(iter(msg.content.parameters_records.values()))
 
-    context.state.parameters_records[PARAMS_RECORD_KEY] = paramsrecord
+    context.state.parameters_records[MAIN_PARAMS_RECORD] = paramsrecord
 
     # Evaluate initial parameters
-    log(INFO, "Evaluating initial parameters")
+    log(INFO, "Evaluating initial global parameters")
     parameters = compat.parametersrecord_to_parameters(paramsrecord, keep_input=True)
     res = context.strategy.evaluate(0, parameters=parameters)
     if res is not None:
@@ -164,13 +159,13 @@ def default_centralized_evaluation_workflow(_: Driver, context: Context) -> None
         raise TypeError(f"Expect a LegacyContext, but get {type(context).__name__}.")
 
     # Retrieve current_round and start_time from the context
-    cfg = context.state.configs_records[CONFIGS_RECORD_KEY]
-    current_round = cast(int, cfg[KEY_CURRENT_ROUND])
-    start_time = cast(float, cfg[KEY_START_TIME])
+    cfg = context.state.configs_records[MAIN_CONFIGS_RECORD]
+    current_round = cast(int, cfg[Key.CURRENT_ROUND])
+    start_time = cast(float, cfg[Key.START_TIME])
 
     # Centralized evaluation
     parameters = compat.parametersrecord_to_parameters(
-        record=context.state.parameters_records[PARAMS_RECORD_KEY],
+        record=context.state.parameters_records[MAIN_PARAMS_RECORD],
         keep_input=True,
     )
     res_cen = context.strategy.evaluate(current_round, parameters=parameters)
@@ -190,15 +185,17 @@ def default_centralized_evaluation_workflow(_: Driver, context: Context) -> None
         )
 
 
-def default_fit_workflow(driver: Driver, context: Context) -> None:
+def default_fit_workflow(  # pylint: disable=R0914
+    driver: Driver, context: Context
+) -> None:
     """Execute the default workflow for a single fit round."""
     if not isinstance(context, LegacyContext):
         raise TypeError(f"Expect a LegacyContext, but get {type(context).__name__}.")
 
     # Get current_round and parameters
-    cfg = context.state.configs_records[CONFIGS_RECORD_KEY]
-    current_round = cast(int, cfg[KEY_CURRENT_ROUND])
-    parametersrecord = context.state.parameters_records[PARAMS_RECORD_KEY]
+    cfg = context.state.configs_records[MAIN_CONFIGS_RECORD]
+    current_round = cast(int, cfg[Key.CURRENT_ROUND])
+    parametersrecord = context.state.parameters_records[MAIN_PARAMS_RECORD]
     parameters = compat.parametersrecord_to_parameters(
         parametersrecord, keep_input=True
     )
@@ -211,12 +208,11 @@ def default_fit_workflow(driver: Driver, context: Context) -> None:
     )
 
     if not client_instructions:
-        log(INFO, "fit_round %s: no clients selected, cancel", current_round)
+        log(INFO, "configure_fit: no clients selected, cancel")
         return
     log(
-        DEBUG,
-        "fit_round %s: strategy sampled %s clients (out of %s)",
-        current_round,
+        INFO,
+        "configure_fit: strategy sampled %s clients (out of %s)",
         len(client_instructions),
         context.client_manager.num_available(),
     )
@@ -240,14 +236,14 @@ def default_fit_workflow(driver: Driver, context: Context) -> None:
     # collect `fit` results from all clients participating in this round
     messages = list(driver.send_and_receive(out_messages))
     del out_messages
+    num_failures = len([msg for msg in messages if msg.has_error()])
 
     # No exception/failure handling currently
     log(
-        DEBUG,
-        "fit_round %s received %s results and %s failures",
-        current_round,
-        len(messages),
-        0,
+        INFO,
+        "aggregate_fit: received %s results and %s failures",
+        len(messages) - num_failures,
+        num_failures,
     )
 
     # Aggregate training results
@@ -266,7 +262,7 @@ def default_fit_workflow(driver: Driver, context: Context) -> None:
         paramsrecord = compat.parameters_to_parametersrecord(
             parameters_aggregated, True
         )
-        context.state.parameters_records[PARAMS_RECORD_KEY] = paramsrecord
+        context.state.parameters_records[MAIN_PARAMS_RECORD] = paramsrecord
         context.history.add_metrics_distributed_fit(
             server_round=current_round, metrics=metrics_aggregated
         )
@@ -278,9 +274,9 @@ def default_evaluate_workflow(driver: Driver, context: Context) -> None:
         raise TypeError(f"Expect a LegacyContext, but get {type(context).__name__}.")
 
     # Get current_round and parameters
-    cfg = context.state.configs_records[CONFIGS_RECORD_KEY]
-    current_round = cast(int, cfg[KEY_CURRENT_ROUND])
-    parametersrecord = context.state.parameters_records[PARAMS_RECORD_KEY]
+    cfg = context.state.configs_records[MAIN_CONFIGS_RECORD]
+    current_round = cast(int, cfg[Key.CURRENT_ROUND])
+    parametersrecord = context.state.parameters_records[MAIN_PARAMS_RECORD]
     parameters = compat.parametersrecord_to_parameters(
         parametersrecord, keep_input=True
     )
@@ -292,12 +288,11 @@ def default_evaluate_workflow(driver: Driver, context: Context) -> None:
         client_manager=context.client_manager,
     )
     if not client_instructions:
-        log(INFO, "evaluate_round %s: no clients selected, cancel", current_round)
+        log(INFO, "configure_evaluate: no clients selected, skipping evaluation")
         return
     log(
-        DEBUG,
-        "evaluate_round %s: strategy sampled %s clients (out of %s)",
-        current_round,
+        INFO,
+        "configure_evaluate: strategy sampled %s clients (out of %s)",
         len(client_instructions),
         context.client_manager.num_available(),
     )
@@ -321,14 +316,14 @@ def default_evaluate_workflow(driver: Driver, context: Context) -> None:
     # collect `evaluate` results from all clients participating in this round
     messages = list(driver.send_and_receive(out_messages))
     del out_messages
+    num_failures = len([msg for msg in messages if msg.has_error()])
 
     # No exception/failure handling currently
     log(
-        DEBUG,
-        "evaluate_round %s received %s results and %s failures",
-        current_round,
-        len(messages),
-        0,
+        INFO,
+        "aggregate_evaluate: received %s results and %s failures",
+        len(messages) - num_failures,
+        num_failures,
     )
 
     # Aggregate the evaluation results

flwr/server/workflow/secure_aggregation/__init__.py

@@ -0,0 +1,24 @@
+# Copyright 2024 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.
+# ==============================================================================
+"""Secure Aggregation workflows."""
+
+
+from .secagg_workflow import SecAggWorkflow
+from .secaggplus_workflow import SecAggPlusWorkflow
+
+__all__ = [
+    "SecAggPlusWorkflow",
+    "SecAggWorkflow",
+]

flwr/server/workflow/secure_aggregation/secagg_workflow.py

@@ -0,0 +1,112 @@
+# Copyright 2024 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.
+# ==============================================================================
+"""Workflow for the SecAgg protocol."""
+
+
+from typing import Optional, Union
+
+from .secaggplus_workflow import SecAggPlusWorkflow
+
+
+class SecAggWorkflow(SecAggPlusWorkflow):
+    """The workflow for the SecAgg protocol.
+
+    The SecAgg protocol ensures the secure summation of integer vectors owned by
+    multiple parties, without accessing any individual integer vector. This workflow
+    allows the server to compute the weighted average of model parameters across all
+    clients, ensuring individual contributions remain private. This is achieved by
+    clients sending both, a weighting factor and a weighted version of the locally
+    updated parameters, both of which are masked for privacy. Specifically, each
+    client uploads "[w, w * params]" with masks, where weighting factor 'w' is the
+    number of examples ('num_examples') and 'params' represents the model parameters
+    ('parameters') from the client's `FitRes`. The server then aggregates these
+    contributions to compute the weighted average of model parameters.
+
+    The protocol involves four main stages:
+    - 'setup': Send SecAgg configuration to clients and collect their public keys.
+    - 'share keys': Broadcast public keys among clients and collect encrypted secret
+      key shares.
+    - 'collect masked vectors': Forward encrypted secret key shares to target clients
+      and collect masked model parameters.
+    - 'unmask': Collect secret key shares to decrypt and aggregate the model parameters.
+
+    Only the aggregated model parameters are exposed and passed to
+    `Strategy.aggregate_fit`, ensuring individual data privacy.
+
+    Parameters
+    ----------
+    reconstruction_threshold : Union[int, float]
+        The minimum number of shares required to reconstruct a client's private key,
+        or, if specified as a float, it represents the proportion of the total number
+        of shares needed for reconstruction. This threshold ensures privacy by allowing
+        for the recovery of contributions from dropped clients during aggregation,
+        without compromising individual client data.
+    max_weight : Optional[float] (default: 1000.0)
+        The maximum value of the weight that can be assigned to any single client's
+        update during the weighted average calculation on the server side, e.g., in the
+        FedAvg algorithm.
+    clipping_range : float, optional (default: 8.0)
+        The range within which model parameters are clipped before quantization.
+        This parameter ensures each model parameter is bounded within
+        [-clipping_range, clipping_range], facilitating quantization.
+    quantization_range : int, optional (default: 4194304, this equals 2**22)
+        The size of the range into which floating-point model parameters are quantized,
+        mapping each parameter to an integer in [0, quantization_range-1]. This
+        facilitates cryptographic operations on the model updates.
+    modulus_range : int, optional (default: 4294967296, this equals 2**32)
+        The range of values from which random mask entries are uniformly sampled
+        ([0, modulus_range-1]). `modulus_range` must be less than 4294967296.
+        Please use 2**n values for `modulus_range` to prevent overflow issues.
+    timeout : Optional[float] (default: None)
+        The timeout duration in seconds. If specified, the workflow will wait for
+        replies for this duration each time. If `None`, there is no time limit and
+        the workflow will wait until replies for all messages are received.
+
+    Notes
+    -----
+    - Each client's private key is split into N shares under the SecAgg protocol, where
+      N is the number of selected clients.
+    - Generally, higher `reconstruction_threshold` means better privacy guarantees but
+      less tolerance to dropouts.
+    - Too large `max_weight` may compromise the precision of the quantization.
+    - `modulus_range` must be 2**n and larger than `quantization_range`.
+    - When `reconstruction_threshold` is a float, it is interpreted as the proportion of
+      the number of all selected clients needed for the reconstruction of a private key.
+      This feature enables flexibility in setting the security threshold relative to the
+      number of selected clients.
+    - `reconstruction_threshold`, and the quantization parameters
+      (`clipping_range`, `quantization_range`, `modulus_range`) play critical roles in
+      balancing privacy, robustness, and efficiency within the SecAgg protocol.
+    """
+
+    def __init__(  # pylint: disable=R0913
+        self,
+        reconstruction_threshold: Union[int, float],
+        *,
+        max_weight: float = 1000.0,
+        clipping_range: float = 8.0,
+        quantization_range: int = 4194304,
+        modulus_range: int = 4294967296,
+        timeout: Optional[float] = None,
+    ) -> None:
+        super().__init__(
+            num_shares=1.0,
+            reconstruction_threshold=reconstruction_threshold,
+            max_weight=max_weight,
+            clipping_range=clipping_range,
+            quantization_range=quantization_range,
+            modulus_range=modulus_range,
+            timeout=timeout,
+        )