nvflare.recipe.cyclic module

class CyclicRecipe(*, name: str = 'cyclic', model: Any | Dict[str, Any] | None = None, initial_ckpt: str | None = None, num_rounds: int = 2, min_clients: int = 2, train_script: str, train_args: str = '', launch_external_process: bool = False, command: str = 'python3 -u', framework: FrameworkType = FrameworkType.NUMPY, server_expected_format: ExchangeFormat = ExchangeFormat.NUMPY, params_transfer_type: TransferType = TransferType.FULL, server_memory_gc_rounds: int = 1, client_memory_gc_rounds: int = 0, cuda_empty_cache: bool = False, task_assignment_timeout: int = 10, shutdown_timeout: float = 0.0, server_config_overrides: Dict[str, Any] | None = None, client_config_overrides: Dict[str, Any] | None = None)[source]

Bases: Recipe

Cyclic federated learning recipe for sequential model training across clients.

This recipe implements a cyclic (sequential) federated learning approach where clients train one after another in a round-robin fashion, rather than training in parallel. Each client receives the model from the previous client, trains on their local data, and passes the updated model to the next client.

The recipe uses the following key components: - CyclicController: Manages the sequential workflow and client coordination on the server - FullModelShareableGenerator: Handles serialization/deserialization of models for transfer - ScriptRunner: Executes client training scripts with specified parameters - FedJob: Orchestrates the overall federated learning job configuration

Parameters:

  • name – Name identifier for the federated learning job. Defaults to “cyclic”.

  • model – Starting model object to begin training. Can be: - Model instance (nn.Module, tf.keras.Model, np.ndarray, etc.) - Dict config: {“class_path”: “module.ClassName”, “args”: {“param”: value}} - None: no initial model

  • initial_ckpt – Path to a pre-trained checkpoint file. Can be: - Relative path: file will be bundled into the job’s custom/ directory. - Absolute path: treated as a server-side path, used as-is at runtime.

  • num_rounds – Number of complete training rounds to execute. Defaults to 2.

  • min_clients – Minimum number of clients required to participate. Must be >= 2.

  • train_script – Path to the client training script to execute.

  • train_args – Additional command-line arguments to pass to the training script. Written in clear text into the generated job config, so it must never contain actual secret values; see nvflare.recipe.secrets for how to pass secrets.

  • launch_external_process – Whether to run training in a separate process. Defaults to False.

  • command – Shell command to execute the training script. Defaults to “python3 -u”.

  • framework – ML framework type for compatibility. Defaults to FrameworkType.NUMPY.

  • server_expected_format – Data exchange format between server and clients. Defaults to ExchangeFormat.NUMPY.

  • params_transfer_type – Method for transferring model parameters. Defaults to TransferType.FULL.

  • server_memory_gc_rounds – Run memory cleanup (gc.collect + malloc_trim) every N rounds on server. Set to 0 to disable. Defaults to 1 (every round).

  • task_assignment_timeout – Seconds to wait for the assigned client to request its task before moving to the next client. Defaults to 10.

  • shutdown_timeout – Seconds to wait for an external client process to exit during shutdown. Defaults to 0.0 and only applies when launch_external_process=True.

  • server_config_overrides – Advanced shallow overrides for CyclicController. Values here take precedence over named constructor parameters. task_check_period must be positive when supplied. This dictionary is stored in the job definition and must not contain secrets.

  • client_config_overrides – Advanced shallow overrides for ScriptRunner. Values here take precedence over named constructor parameters. This dictionary is stored in the job definition and must not contain secrets.

Raises:

ValidationError – If min_clients < 2 or other parameter validation fails.

Example

>>> recipe = CyclicRecipe(
...     name="my_cyclic_job",
...     model=my_model,
...     num_rounds=5,
...     min_clients=3,
...     train_script="client_train.py",
...     train_args="--epochs 10 --lr 0.01"
... )
>>> # The recipe can then be submitted to the federated learning system

This is base class of a recipe. Recipes are implemented by jobs. A concrete recipe must provide the job for recipe implementation.

Security contract – no secrets in recipe parameters:

Recipe parameters (train_args, task_args, eval_args, per_site_config, config overrides, dicts passed to add_client_config/add_server_config, exec params, etc.) can be written in clear text into generated job configuration. These parameters and their nested values must never contain actual passwords, API keys, tokens, private keys, or other credentials. Instead, read secrets from site environment variables or mounted secret files inside your code, or pass a placeholder created with nvflare.recipe.secrets.secret_ref() or nvflare.recipe.secrets.secret_file_ref() at a supported runtime boundary. See nvflare.recipe.secrets for the supported parameter locations.

Before export or run, recipes scan their parameters with heuristics and emit nvflare.recipe.secrets.PotentialSecretWarning when a value looks like an actual secret. The scan is best-effort: absence of a warning does not prove a parameter is safe to share.

Parameters:

job – the job that implements the recipe.