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)[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.

  • 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).

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.

Parameters:

job – the job that implements the recipe.