nvflare.app_opt.feature_election.controller module

class FeatureElectionController(freedom_degree: float = 0.5, aggregation_mode: str = 'weighted', min_clients: int = 2, num_rounds: int = 5, task_name: str = 'feature_election', train_timeout: int = 300, auto_tune: bool = False, tuning_rounds: int = 0, wait_time_after_min_received: int = 10)[source]

Bases: Controller

Three-phase FL controller for federated feature selection and FedAvg training.

Phase 1 — Local Feature Selection: each client runs its configured FS method and returns a feature mask and per-feature scores.

Phase 2 — Tuning & Global Mask Distribution: the server optionally runs hill-climbing to find the optimal freedom_degree, then aggregates client masks via weighted voting and distributes the global feature mask to all clients. If fewer than min_clients clients acknowledge the mask, the entire workflow is aborted.

Phase 3 — FedAvg Training: standard federated averaging on the reduced feature set for num_rounds rounds.

Parameters:

  • freedom_degree – Threshold in [0, 1] controlling which features survive the vote. 0 = intersection (all clients must select), 1 = union (any client suffices).

  • aggregation_mode – 'weighted' weights each client by sample count; 'uniform' treats all clients equally.

  • min_clients – Minimum number of clients that must respond in each phase.

  • num_rounds – Number of FedAvg training rounds in Phase 3.

  • task_name – Must match the task_name configured on FeatureElectionExecutor.

  • train_timeout – Per-phase timeout in seconds.

  • auto_tune – If True, Phase 2 runs hill-climbing to optimise freedom_degree. Has no effect when tuning_rounds=0 (a warning is logged in that case).

  • tuning_rounds – Number of hill-climbing iterations. Must be >= 2 for meaningful tuning; tuning_rounds=0 disables tuning (with a warning if auto_tune=True); tuning_rounds=1 is also disabled (same warning).

  • wait_time_after_min_received – Seconds to wait for additional client responses after min_clients have already replied. Set to 0 only for local simulation; a non-zero value (default 10 s) prevents slower clients from being silently excluded in heterogeneous production networks.

Controller logic for tasks and their destinations.

Must set_communicator() to access communication related function implementations.

Parameters:

task_check_period (float, optional) – interval for checking status of tasks. Applicable for WFCommServer. Defaults to 0.2.

advance_tuning(score: float, first_step: bool = False) → None[source]

Record a tuning-round score and update freedom_degree for the next round.

This is the public interface for the simulation path in FeatureElection.simulate_election() so that the simulation does not need to mutate private controller state directly. The real FL path in control_flow uses the same internal helpers.

Parameters:

  • score – Weighted evaluation score for the current freedom_degree.

  • first_step – True only on the very first tuning round; passed through to _calculate_next_fd to seed the initial direction.

aggregate_selections(client_selections: Dict[str, Dict]) → ndarray[source]

Aggregate feature selections from all clients.

Freedom degree controls the blend between intersection and union: - FD=0: Intersection (only features selected by ALL clients) - FD=1: Union (features selected by ANY client) - 0<FD<1: Weighted voting based on scores

control_flow(abort_signal: Signal, fl_ctx: FLContext) → None[source]

Main Orchestration Loop

process_result_of_unknown_task(client: Client, task_name: str, client_task_id: str, result: Shareable, fl_ctx: FLContext)[source]

Called when a result is received for an unknown task. This is a fallback - normally results come through task_done_cb.

start_controller(fl_ctx: FLContext) → None[source]

Starts the controller.

This method is called at the beginning of the RUN.

Parameters:

  • fl_ctx – the FL context. You can use this context to access services provided by the

  • example (framework. For)

  • your (you can get Command Register from it and register)

  • modules. (admin command)

stop_controller(fl_ctx: FLContext)[source]

Stops the controller.

This method is called right before the RUN is ended.

Parameters:

  • fl_ctx – the FL context. You can use this context to access services provided by the

  • example (framework. For)

  • your (you can get Command Register from it and unregister)

  • modules. (admin command)