flwr-nightly 1.8.0.dev20240310__py3-none-any.whl → 1.8.0.dev20240312__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
@@ -58,16 +59,18 @@ 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[MAIN_CONFIGS_RECORD] = cfg
 
         for current_round in range(1, context.config.num_rounds + 1):
+            log(INFO, "")
+            log(INFO, "[ROUND %s]", current_round)
             cfg[Key.CURRENT_ROUND] = current_round
 
             # Fit round
@@ -79,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()
@@ -107,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
         )
@@ -128,7 +127,7 @@ def default_init_params_workflow(driver: Driver, context: Context) -> None:
                     content=content,
                     message_type=MessageTypeLegacy.GET_PARAMETERS,
                     dst_node_id=random_client.node_id,
-                    group_id="",
+                    group_id="0",
                     ttl="",
                 )
             ]
@@ -140,7 +139,7 @@ def default_init_params_workflow(driver: Driver, context: Context) -> None:
     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:
@@ -186,7 +185,9 @@ 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__}.")
@@ -207,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(),
     )
@@ -226,7 +226,7 @@ def default_fit_workflow(driver: Driver, context: Context) -> None:
             content=compat.fitins_to_recordset(fitins, True),
             message_type=MessageType.TRAIN,
             dst_node_id=proxy.node_id,
-            group_id="",
+            group_id=str(current_round),
             ttl="",
         )
         for proxy, fitins in client_instructions
@@ -236,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
@@ -288,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(),
     )
@@ -307,7 +306,7 @@ def default_evaluate_workflow(driver: Driver, context: Context) -> None:
             content=compat.evaluateins_to_recordset(evalins, True),
             message_type=MessageType.EVALUATE,
             dst_node_id=proxy.node_id,
-            group_id="",
+            group_id=str(current_round),
             ttl="",
         )
         for proxy, evalins in client_instructions
@@ -317,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

@@ -15,8 +15,10 @@
 """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,
+        )

flwr/server/workflow/secure_aggregation/secaggplus_workflow.py

@@ -17,12 +17,11 @@
 
 import random
 from dataclasses import dataclass, field
-from logging import ERROR, WARN
-from typing import Dict, List, Optional, Set, Union, cast
+from logging import DEBUG, ERROR, INFO, WARN
+from typing import Dict, List, Optional, Set, Tuple, Union, cast
 
 import flwr.common.recordset_compat as compat
 from flwr.common import (
-    Code,
     ConfigsRecord,
     Context,
     FitRes,
@@ -30,7 +29,6 @@ from flwr.common import (
     MessageType,
     NDArrays,
     RecordSet,
-    Status,
     bytes_to_ndarray,
     log,
     ndarrays_to_parameters,
@@ -55,7 +53,7 @@ from flwr.common.secure_aggregation.secaggplus_constants import (
     Stage,
 )
 from flwr.common.secure_aggregation.secaggplus_utils import pseudo_rand_gen
-from flwr.server.compat.driver_client_proxy import DriverClientProxy
+from flwr.server.client_proxy import ClientProxy
 from flwr.server.compat.legacy_context import LegacyContext
 from flwr.server.driver import Driver
 
@@ -67,6 +65,7 @@ from ..constant import Key as WorkflowKey
 class WorkflowState:  # pylint: disable=R0902
     """The state of the SecAgg+ protocol."""
 
+    nid_to_proxies: Dict[int, ClientProxy] = field(default_factory=dict)
     nid_to_fitins: Dict[int, RecordSet] = field(default_factory=dict)
     sampled_node_ids: Set[int] = field(default_factory=set)
     active_node_ids: Set[int] = field(default_factory=set)
@@ -81,6 +80,7 @@ class WorkflowState:  # pylint: disable=R0902
     forward_srcs: Dict[int, List[int]] = field(default_factory=dict)
     forward_ciphertexts: Dict[int, List[bytes]] = field(default_factory=dict)
     aggregate_ndarrays: NDArrays = field(default_factory=list)
+    legacy_results: List[Tuple[ClientProxy, FitRes]] = field(default_factory=list)
 
 
 class SecAggPlusWorkflow:
@@ -101,7 +101,7 @@ class SecAggPlusWorkflow:
     - '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 inputs': Forward encrypted secret key shares to target clients
+    - '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.
 
@@ -195,12 +195,15 @@ class SecAggPlusWorkflow:
         steps = (
             self.setup_stage,
             self.share_keys_stage,
-            self.collect_masked_input_stage,
+            self.collect_masked_vectors_stage,
             self.unmask_stage,
         )
+        log(INFO, "Secure aggregation commencing.")
         for step in steps:
             if not step(driver, context, state):
+                log(INFO, "Secure aggregation halted.")
                 return
+        log(INFO, "Secure aggregation completed.")
 
     def _check_init_params(self) -> None:  # pylint: disable=R0912
         # Check `num_shares`
@@ -287,10 +290,21 @@ class SecAggPlusWorkflow:
         proxy_fitins_lst = context.strategy.configure_fit(
             current_round, parameters, context.client_manager
         )
+        if not proxy_fitins_lst:
+            log(INFO, "configure_fit: no clients selected, cancel")
+            return False
+        log(
+            INFO,
+            "configure_fit: strategy sampled %s clients (out of %s)",
+            len(proxy_fitins_lst),
+            context.client_manager.num_available(),
+        )
+
         state.nid_to_fitins = {
-            proxy.node_id: compat.fitins_to_recordset(fitins, False)
+            proxy.node_id: compat.fitins_to_recordset(fitins, True)
             for proxy, fitins in proxy_fitins_lst
         }
+        state.nid_to_proxies = {proxy.node_id: proxy for proxy, _ in proxy_fitins_lst}
 
         # Protocol config
         sampled_node_ids = list(state.nid_to_fitins.keys())
@@ -362,12 +376,22 @@ class SecAggPlusWorkflow:
                 ttl="",
             )
 
+        log(
+            DEBUG,
+            "[Stage 0] Sending configurations to %s clients.",
+            len(state.active_node_ids),
+        )
         msgs = driver.send_and_receive(
             [make(node_id) for node_id in state.active_node_ids], timeout=self.timeout
         )
         state.active_node_ids = {
             msg.metadata.src_node_id for msg in msgs if not msg.has_error()
         }
+        log(
+            DEBUG,
+            "[Stage 0] Received public keys from %s clients.",
+            len(state.active_node_ids),
+        )
 
         for msg in msgs:
             if msg.has_error():
@@ -401,12 +425,22 @@ class SecAggPlusWorkflow:
             )
 
         # Broadcast public keys to clients and receive secret key shares
+        log(
+            DEBUG,
+            "[Stage 1] Forwarding public keys to %s clients.",
+            len(state.active_node_ids),
+        )
         msgs = driver.send_and_receive(
             [make(node_id) for node_id in state.active_node_ids], timeout=self.timeout
         )
         state.active_node_ids = {
             msg.metadata.src_node_id for msg in msgs if not msg.has_error()
         }
+        log(
+            DEBUG,
+            "[Stage 1] Received encrypted key shares from %s clients.",
+            len(state.active_node_ids),
+        )
 
         # Build forward packet list dictionary
         srcs: List[int] = []
@@ -437,16 +471,16 @@ class SecAggPlusWorkflow:
 
         return self._check_threshold(state)
 
-    def collect_masked_input_stage(
+    def collect_masked_vectors_stage(
         self, driver: Driver, context: LegacyContext, state: WorkflowState
     ) -> bool:
-        """Execute the 'collect masked input' stage."""
+        """Execute the 'collect masked vectors' stage."""
         cfg = context.state.configs_records[MAIN_CONFIGS_RECORD]
 
-        # Send secret key shares to clients (plus FitIns) and collect masked input
+        # Send secret key shares to clients (plus FitIns) and collect masked vectors
         def make(nid: int) -> Message:
             cfgs_dict = {
-                Key.STAGE: Stage.COLLECT_MASKED_INPUT,
+                Key.STAGE: Stage.COLLECT_MASKED_VECTORS,
                 Key.CIPHERTEXT_LIST: state.forward_ciphertexts[nid],
                 Key.SOURCE_LIST: state.forward_srcs[nid],
             }
@@ -461,12 +495,22 @@ class SecAggPlusWorkflow:
                 ttl="",
             )
 
+        log(
+            DEBUG,
+            "[Stage 2] Forwarding encrypted key shares to %s clients.",
+            len(state.active_node_ids),
+        )
         msgs = driver.send_and_receive(
             [make(node_id) for node_id in state.active_node_ids], timeout=self.timeout
         )
         state.active_node_ids = {
             msg.metadata.src_node_id for msg in msgs if not msg.has_error()
         }
+        log(
+            DEBUG,
+            "[Stage 2] Received masked vectors from %s clients.",
+            len(state.active_node_ids),
+        )
 
         # Clear cache
         del state.forward_ciphertexts, state.forward_srcs, state.nid_to_fitins
@@ -485,9 +529,15 @@ class SecAggPlusWorkflow:
             masked_vector = parameters_mod(masked_vector, state.mod_range)
             state.aggregate_ndarrays = masked_vector
 
+        # Backward compatibility with Strategy
+        for msg in msgs:
+            fitres = compat.recordset_to_fitres(msg.content, True)
+            proxy = state.nid_to_proxies[msg.metadata.src_node_id]
+            state.legacy_results.append((proxy, fitres))
+
         return self._check_threshold(state)
 
-    def unmask_stage(  # pylint: disable=R0912, R0914
+    def unmask_stage(  # pylint: disable=R0912, R0914, R0915
         self, driver: Driver, context: LegacyContext, state: WorkflowState
     ) -> bool:
         """Execute the 'unmask' stage."""
@@ -516,12 +566,22 @@ class SecAggPlusWorkflow:
                 ttl="",
             )
 
+        log(
+            DEBUG,
+            "[Stage 3] Requesting key shares from %s clients to remove masks.",
+            len(state.active_node_ids),
+        )
         msgs = driver.send_and_receive(
             [make(node_id) for node_id in state.active_node_ids], timeout=self.timeout
         )
         state.active_node_ids = {
             msg.metadata.src_node_id for msg in msgs if not msg.has_error()
         }
+        log(
+            DEBUG,
+            "[Stage 3] Received key shares from %s clients.",
+            len(state.active_node_ids),
+        )
 
         # Build collected shares dict
         collected_shares_dict: Dict[int, List[bytes]] = {}
@@ -534,7 +594,7 @@ class SecAggPlusWorkflow:
             for owner_nid, share in zip(nids, shares):
                 collected_shares_dict[owner_nid].append(share)
 
-        # Remove mask for every client who is available after collect_masked_input stage
+        # Remove masks for every active client after collect_masked_vectors stage
         masked_vector = state.aggregate_ndarrays
         del state.aggregate_ndarrays
         for nid, share_list in collected_shares_dict.items():
@@ -584,18 +644,30 @@ class SecAggPlusWorkflow:
         for vec in aggregated_vector:
             vec += offset
             vec *= inv_dq_total_ratio
-        state.aggregate_ndarrays = aggregated_vector
-        final_fitres = FitRes(
-            status=Status(code=Code.OK, message=""),
-            parameters=ndarrays_to_parameters(aggregated_vector),
-            num_examples=round(state.max_weight / inv_dq_total_ratio),
-            metrics={},
-        )
-        empty_proxy = DriverClientProxy(
+
+        # Backward compatibility with Strategy
+        results = state.legacy_results
+        parameters = ndarrays_to_parameters(aggregated_vector)
+        for _, fitres in results:
+            fitres.parameters = parameters
+
+        # No exception/failure handling currently
+        log(
+            INFO,
+            "aggregate_fit: received %s results and %s failures",
+            len(results),
             0,
-            driver.grpc_driver,  # type: ignore
-            False,
-            driver.run_id,  # type: ignore
         )
-        context.strategy.aggregate_fit(current_round, [(empty_proxy, final_fitres)], [])
+        aggregated_result = context.strategy.aggregate_fit(current_round, results, [])
+        parameters_aggregated, metrics_aggregated = aggregated_result
+
+        # Update the parameters and write history
+        if parameters_aggregated:
+            paramsrecord = compat.parameters_to_parametersrecord(
+                parameters_aggregated, True
+            )
+            context.state.parameters_records[MAIN_PARAMS_RECORD] = paramsrecord
+            context.history.add_metrics_distributed_fit(
+                server_round=current_round, metrics=metrics_aggregated
+            )
         return True

{flwr_nightly-1.8.0.dev20240310.dist-info → flwr_nightly-1.8.0.dev20240312.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: flwr-nightly
-Version: 1.8.0.dev20240310
+Version: 1.8.0.dev20240312
 Summary: Flower: A Friendly Federated Learning Framework
 Home-page: https://flower.ai
 License: Apache-2.0