Merge branch 'main' into cherry-pick-4150

YuanTingHsieh · web-flow · commit 053a5780bba1 · 2026-02-26T11:49:11.000-08:00
diff --git a/docs/programming_guide/component_configuration.rst b/docs/programming_guide/component_configuration.rst
@@ -144,15 +144,15 @@ For example:
             "device": "cpu",
             "source_model": "model",
             "optimizer_args": {
-                "path": "torch.optim.SGD",
+                "class_path": "torch.optim.SGD",
                 "args": {
                     "lr": 1.0,
                     "momentum": 0.6
                 },
                 "config_type": "dict"
             },
             "lr_scheduler_args": {
-                "path": "torch.optim.lr_scheduler.CosineAnnealingLR",
+                "class_path": "torch.optim.lr_scheduler.CosineAnnealingLR",
                 "args": {
                     "T_max": "{num_rounds}",
                     "eta_min": 0.9
@@ -166,7 +166,7 @@ Notice the config:
 .. code-block:: json
 
     "optimizer_args": {
-        "path": "torch.optim.SGD",
+        "class_path": "torch.optim.SGD",
         "args": {
             "lr": 1.0,
             "momentum": 0.6
diff --git a/docs/user_guide/data_scientist_guide/available_recipes.rst b/docs/user_guide/data_scientist_guide/available_recipes.rst
@@ -258,7 +258,7 @@ PyTorch FedOpt
         num_rounds=5,
         model=MyModel(),
         train_script="client.py",
-        optimizer_args={"path": "torch.optim.SGD", "args": {"lr": 1.0, "momentum": 0.6}},
+        optimizer_args={"class_path": "torch.optim.SGD", "args": {"lr": 1.0, "momentum": 0.6}},
     )
     env = SimEnv(num_clients=2)
     run = recipe.execute(env)
@@ -281,7 +281,7 @@ TensorFlow FedOpt
         num_rounds=5,
         model=MyTFModel(),
         train_script="client.py",
-        optimizer_args={"path": "tensorflow.keras.optimizers.SGD", "args": {"learning_rate": 1.0}},
+        optimizer_args={"class_path": "tensorflow.keras.optimizers.SGD", "args": {"learning_rate": 1.0}},
     )
     env = SimEnv(num_clients=2)
     run = recipe.execute(env)
diff --git a/examples/advanced/cifar10/pt/cifar10-sim/cifar10_fedopt/README.md b/examples/advanced/cifar10/pt/cifar10-sim/cifar10_fedopt/README.md
@@ -86,19 +86,19 @@ python job.py --n_clients 16 --num_rounds 100 --alpha 0.1 --aggregation_epochs 2
 
 ### Server-Side Optimization
 
-FedOpt is configured in `job.py` by specifying the server optimizer:
+FedOpt is configured in `job.py` using `FedOptRecipe` with `optimizer_args` and optional `lr_scheduler_args`:
 
 ```python
-from nvflare.app_opt.pt.recipes.fedavg import FedAvgRecipe
+from nvflare.app_opt.pt.recipes.fedopt import FedOptRecipe
 
-recipe = FedAvgRecipe(
+recipe = FedOptRecipe(
     name="cifar10_fedopt",
     # ... other parameters ...
-    server_optimizer="sgd",           # Optimizer type
-    server_optimizer_args={
-        "lr": 1.0,                     # Server learning rate
-        "momentum": 0.9                # Momentum coefficient
-    }
+    optimizer_args={"class_path": "torch.optim.SGD", "args": {"lr": 1.0, "momentum": 0.6}},
+    lr_scheduler_args={
+        "class_path": "torch.optim.lr_scheduler.CosineAnnealingLR",
+        "args": {"T_max": num_rounds, "eta_min": 0.9},
+    },
 )
 ```
 
@@ -172,19 +172,18 @@ To try different server optimizers, modify `job.py`:
 
 ```python
 # Try Adam instead of SGD
-recipe = FedAvgRecipe(
+recipe = FedOptRecipe(
     # ... other parameters ...
-    server_optimizer="adam",
-    server_optimizer_args={
-        "lr": 0.01,
-        "betas": (0.9, 0.999)
-    }
+    optimizer_args={
+        "class_path": "torch.optim.Adam",
+        "args": {"lr": 0.01, "betas": (0.9, 0.999)},
+    },
 )
 ```
 
 ## References
 
 - [FedOpt Paper](https://arxiv.org/abs/2003.00295) - Reddi et al., 2020
 - [NVFlare Documentation](https://nvflare.readthedocs.io/)
-- [NVFlare FedAvgRecipe](https://nvflare.readthedocs.io/en/main/apidocs/nvflare.app_opt.pt.recipes.fedavg.html)
+- [NVFlare FedOptRecipe](https://nvflare.readthedocs.io/en/main/apidocs/nvflare.app_opt.pt.recipes.fedopt.html)
 
diff --git a/examples/advanced/cifar10/pt/cifar10-sim/cifar10_fedopt/job.py b/examples/advanced/cifar10/pt/cifar10-sim/cifar10_fedopt/job.py
@@ -80,11 +80,10 @@ def main():
         model=ModerateCNN(),
         train_script=os.path.join(os.path.dirname(__file__), "client.py"),
         train_args=f"--train_idx_root {train_idx_root} --num_workers {num_workers} --lr {lr} --batch_size {batch_size} --aggregation_epochs {aggregation_epochs}",
-        optimizer_args={"path": "torch.optim.SGD", "args": {"lr": 1.0, "momentum": 0.6}, "config_type": "dict"},
+        optimizer_args={"class_path": "torch.optim.SGD", "args": {"lr": 1.0, "momentum": 0.6}},
         lr_scheduler_args={
-            "path": "torch.optim.lr_scheduler.CosineAnnealingLR",
+            "class_path": "torch.optim.lr_scheduler.CosineAnnealingLR",
             "args": {"T_max": num_rounds, "eta_min": 0.9},
-            "config_type": "dict",
         },
     )
     add_experiment_tracking(recipe, tracking_type="tensorboard")
diff --git a/examples/advanced/cifar10/pt/src/data/cifar10_data_utils.py b/examples/advanced/cifar10/pt/src/data/cifar10_data_utils.py
@@ -38,6 +38,7 @@
 # SOFTWARE.
 
 import os
+import warnings
 
 import numpy as np
 import torch
@@ -46,12 +47,17 @@
 from data.cifar10_dataset import CIFAR10_Idx
 from torchvision import transforms
 
+# NumPy 2.4 deprecation when torchvision unpickles CIFAR batch files (align= in dtype)
+warnings.filterwarnings("ignore", message=".*align.*")
+
 CIFAR10_ROOT = "/tmp/cifar10"  # will be used for all CIFAR-10 experiments
 
 
 def load_cifar10_data():
-    # load data
-    train_dataset = datasets.CIFAR10(root=CIFAR10_ROOT, train=True, download=True)
+    # load data (suppress NumPy 2.4 dtype align deprecation from CIFAR pickle files)
+    with warnings.catch_warnings():
+        warnings.filterwarnings("ignore", message=".*align.*")
+        train_dataset = datasets.CIFAR10(root=CIFAR10_ROOT, train=True, download=True)
 
     # only training label is needed for doing split
     train_label = np.array(train_dataset.targets)
@@ -105,20 +111,22 @@ def create_datasets(site_name, train_idx_root, central=False):
     else:
         site_idx = None  # use whole training dataset if central=True
 
-    train_dataset = CIFAR10_Idx(
-        root=CIFAR10_ROOT,
-        data_idx=site_idx,
-        train=True,
-        download=False,
-        transform=transform_train,
-    )
-
-    valid_dataset = torchvision.datasets.CIFAR10(
-        root=CIFAR10_ROOT,
-        train=False,
-        download=False,
-        transform=transform_valid,
-    )
+    with warnings.catch_warnings():
+        warnings.filterwarnings("ignore", message=".*align.*")
+        train_dataset = CIFAR10_Idx(
+            root=CIFAR10_ROOT,
+            data_idx=site_idx,
+            train=True,
+            download=False,
+            transform=transform_train,
+        )
+
+        valid_dataset = torchvision.datasets.CIFAR10(
+            root=CIFAR10_ROOT,
+            train=False,
+            download=False,
+            transform=transform_valid,
+        )
 
     return train_dataset, valid_dataset
 
diff --git a/examples/advanced/cifar10/tf/cifar10_fedopt/job.py b/examples/advanced/cifar10/tf/cifar10_fedopt/job.py
@@ -58,23 +58,21 @@ def main():
 
     # Configure FedOpt optimizer arguments
     optimizer_args = {
-        "path": "tensorflow.keras.optimizers.SGD",
+        "class_path": "tensorflow.keras.optimizers.SGD",
         "args": {
             "learning_rate": args.server_lr,
             "momentum": args.server_momentum,
         },
-        "config_type": "dict",
     }
 
     # Configure FedOpt learning rate scheduler arguments
     lr_scheduler_args = {
-        "path": "tensorflow.keras.optimizers.schedules.CosineDecay",
+        "class_path": "tensorflow.keras.optimizers.schedules.CosineDecay",
         "args": {
             "initial_learning_rate": args.server_lr,
             "decay_steps": args.num_rounds,
             "alpha": args.server_lr_decay_alpha,
         },
-        "config_type": "dict",
     }
 
     # Create FedOpt recipe
diff --git a/examples/advanced/cifar10/tf/requirements.txt b/examples/advanced/cifar10/tf/requirements.txt
@@ -1,3 +1,3 @@
-nvflare~=2.7.2
+nvflare~=2.7.2rc
 tensorflow[and-cuda]
 filelock>=3.12.0
diff --git a/nvflare/app_opt/pt/fedopt.py b/nvflare/app_opt/pt/fedopt.py
@@ -45,9 +45,9 @@ def __init__(
 
         Args:
             optimizer_args: dictionary of optimizer arguments, e.g.
-                {'path': 'torch.optim.SGD', 'args': {'lr': 1.0}} (default).
+                {'class_path': 'torch.optim.SGD', 'args': {'lr': 1.0}} (default). 'path' is also accepted.
             lr_scheduler_args: dictionary of server-side learning rate scheduler arguments, e.g.
-                {'path': 'torch.optim.lr_scheduler.CosineAnnealingLR', 'args': {'T_max': 100}} (default: None).
+                {'class_path': 'torch.optim.lr_scheduler.CosineAnnealingLR', 'args': {'T_max': 100}} (default: None). 'path' is also accepted.
             source_model: either a valid torch model object or a component ID of a torch model object
             device: specify the device to run server-side optimization, e.g. "cpu" or "cuda:0"
                 (will default to cuda if available and no device is specified).
@@ -62,13 +62,13 @@ def __init__(
 
         if not isinstance(optimizer_args, dict):
             raise TypeError(
-                "optimizer_args must be a dict of format, e.g. {'path': 'torch.optim.SGD', 'args': {'lr': 1.0}}."
+                "optimizer_args must be a dict of format, e.g. {'class_path': 'torch.optim.SGD', 'args': {'lr': 1.0}}."
             )
         if lr_scheduler_args is not None:
             if not isinstance(lr_scheduler_args, dict):
                 raise TypeError(
-                    "optimizer_args must be a dict of format, e.g. "
-                    "{'path': 'torch.optim.lr_scheduler.CosineAnnealingLR', 'args': {'T_max': 100}}."
+                    "lr_scheduler_args must be a dict of format, e.g. "
+                    "{'class_path': 'torch.optim.lr_scheduler.CosineAnnealingLR', 'args': {'T_max': 100}}."
                 )
         self.source_model = source_model
         self.optimizer_args = optimizer_args
@@ -82,7 +82,7 @@ def __init__(
 
     def _get_component_name(self, component_args):
         if component_args is not None:
-            name = component_args.get("path", None)
+            name = component_args.get("path") or component_args.get("class_path")
             if name is None:
                 name = component_args.get("name", None)
             return name
diff --git a/nvflare/app_opt/pt/fedopt_ctl.py b/nvflare/app_opt/pt/fedopt_ctl.py
@@ -28,11 +28,11 @@ def __init__(
         *args,
         source_model: Union[str, torch.nn.Module],
         optimizer_args: dict = {
-            "path": "torch.optim.SGD",
+            "class_path": "torch.optim.SGD",
             "args": {"lr": 1.0, "momentum": 0.6},
         },
         lr_scheduler_args: dict = {
-            "path": "torch.optim.lr_scheduler.CosineAnnealingLR",
+            "class_path": "torch.optim.lr_scheduler.CosineAnnealingLR",
             "args": {"T_max": 3, "eta_min": 0.9},
         },
         device=None,
diff --git a/nvflare/app_opt/pt/recipes/fedopt.py b/nvflare/app_opt/pt/recipes/fedopt.py
@@ -78,13 +78,13 @@ class FedOptRecipe(Recipe):
         server_expected_format (str): What format to exchange the parameters between server and client.
         source_model (str): ID of the source model component. Defaults to "model".
         optimizer_args (dict): Configuration for server-side optimizer with keys:
-            - path: Path to optimizer class (e.g., "torch.optim.SGD")
+            - class_path: Fully qualified optimizer class (e.g., "torch.optim.SGD"). "path" is also accepted.
             - args: Dictionary of optimizer arguments (e.g., {"lr": 1.0, "momentum": 0.6})
-            - config_type: Type of configuration, typically "dict"
+            - config_type: Optional; if omitted, set to "dict" so the config is not instantiated at load time.
         lr_scheduler_args (dict): Optional configuration for learning rate scheduler with keys:
-            - path: Path to scheduler class (e.g., "torch.optim.lr_scheduler.CosineAnnealingLR")
+            - class_path: Fully qualified scheduler class (e.g., "torch.optim.lr_scheduler.CosineAnnealingLR"). "path" is also accepted.
             - args: Dictionary of scheduler arguments (e.g., {"T_max": 100, "eta_min": 0.9})
-            - config_type: Type of configuration, typically "dict"
+            - config_type: Optional; if omitted, set to "dict" so the config is not instantiated at load time.
         device (str): Device to use for server-side optimization, e.g. "cpu" or "cuda:0".
             Defaults to None; will default to cuda if available and no device is specified.
         server_memory_gc_rounds: Run memory cleanup (gc.collect + malloc_trim) every N rounds on server.
@@ -102,12 +102,12 @@ class FedOptRecipe(Recipe):
             device="cpu",
             source_model="model",
             optimizer_args={
-                "path": "torch.optim.SGD",
+                "class_path": "torch.optim.SGD",
                 "args": {"lr": 1.0, "momentum": 0.6},
                 "config_type": "dict"
             },
             lr_scheduler_args={
-                "path": "torch.optim.lr_scheduler.CosineAnnealingLR",
+                "class_path": "torch.optim.lr_scheduler.CosineAnnealingLR",
                 "args": {"T_max": "{num_rounds}", "eta_min": 0.9},
                 "config_type": "dict"
             }
@@ -158,7 +158,7 @@ def __init__(
         self.initial_ckpt = v.initial_ckpt
 
         # Validate inputs using shared utilities
-        from nvflare.recipe.utils import recipe_model_to_job_model, validate_ckpt
+        from nvflare.recipe.utils import ensure_config_type_dict, recipe_model_to_job_model, validate_ckpt
 
         validate_ckpt(self.initial_ckpt)
         if isinstance(self.model, dict):
@@ -174,8 +174,10 @@ def __init__(
         self.server_expected_format: ExchangeFormat = v.server_expected_format
         self.device = device
         self.source_model = source_model
-        self.optimizer_args = optimizer_args
-        self.lr_scheduler_args = lr_scheduler_args
+        # Ensure config_type "dict" so the component builder does not try to instantiate
+        # optimizer/scheduler at config load time (params/optimizer are set at runtime).
+        self.optimizer_args = ensure_config_type_dict(optimizer_args)
+        self.lr_scheduler_args = ensure_config_type_dict(lr_scheduler_args)
         self.server_memory_gc_rounds = v.server_memory_gc_rounds
 
         # Replace {num_rounds} placeholder if present in lr_scheduler_args
diff --git a/nvflare/app_opt/tf/recipes/fedopt.py b/nvflare/app_opt/tf/recipes/fedopt.py
@@ -81,10 +81,10 @@ class FedOptRecipe(Recipe):
         params_transfer_type: How to transfer the parameters between server and client.
             FULL means the whole model parameters are sent. DIFF means that only the difference is sent.
             Defaults to TransferType.FULL.
-        optimizer_args: Dictionary of server-side optimizer arguments with keys 'path' and 'args'.
+        optimizer_args: Dictionary of server-side optimizer arguments with keys 'class_path' (or 'path') and 'args'.
             Defaults to SGD with learning_rate=1.0 and momentum=0.6.
         lr_scheduler_args: Dictionary of server-side learning rate scheduler arguments with keys
-            'path' and 'args'. Defaults to CosineDecay with initial_learning_rate=1.0 and alpha=0.9.
+            'class_path' (or 'path') and 'args'. Defaults to CosineDecay with initial_learning_rate=1.0 and alpha=0.9.
         server_memory_gc_rounds: Run memory cleanup (gc.collect + malloc_trim) every N rounds on server.
             Set to 0 to disable. Defaults to 0.
 
@@ -154,7 +154,7 @@ def __init__(
         self.initial_ckpt = v.initial_ckpt
 
         # Validate inputs using shared utilities
-        from nvflare.recipe.utils import recipe_model_to_job_model, validate_ckpt
+        from nvflare.recipe.utils import ensure_config_type_dict, recipe_model_to_job_model, validate_ckpt
 
         validate_ckpt(self.initial_ckpt)
         if isinstance(self.model, dict):
@@ -168,8 +168,8 @@ def __init__(
         self.command = v.command
         self.server_expected_format: ExchangeFormat = v.server_expected_format
         self.params_transfer_type: TransferType = v.params_transfer_type
-        self.optimizer_args = v.optimizer_args
-        self.lr_scheduler_args = v.lr_scheduler_args
+        self.optimizer_args = ensure_config_type_dict(v.optimizer_args)
+        self.lr_scheduler_args = ensure_config_type_dict(v.lr_scheduler_args)
         self.server_memory_gc_rounds = v.server_memory_gc_rounds
 
         # Create BaseFedJob
diff --git a/nvflare/recipe/utils.py b/nvflare/recipe/utils.py
@@ -420,6 +420,34 @@ def _collect_non_local_scripts(job: FedJob) -> List[str]:
     return non_local_scripts
 
 
+def ensure_config_type_dict(config: Optional[Dict[str, Any]]) -> Optional[Dict[str, Any]]:
+    """Ensure a component config dict has config_type 'dict' and is normalized for the config layer.
+
+    Used by FedOpt-style recipes for optimizer_args and lr_scheduler_args: those dicts have 'path' or
+    'class_path' plus 'args', and would otherwise be treated as component configs and instantiated
+    during config scan (e.g. torch.optim.SGD without params). This function:
+    - Accepts either 'path' or 'class_path' (for consistency with recipe model_config); if only
+      'class_path' is set, copies it to 'path' so the component builder and runtime code work unchanged.
+    - Sets config_type to 'dict' when missing so the component builder does not instantiate at load time;
+      the optimizer/scheduler is instantiated at runtime when params/optimizer are available.
+
+    Args:
+        config: A component-style config dict (e.g. {'class_path': 'torch.optim.SGD', 'args': {'lr': 1.0}}
+                or {'path': '...', 'args': {...}}) or None.
+
+    Returns:
+        A copy of config with config_type 'dict' if missing and path set from class_path if needed; None if config is None.
+    """
+    if config is None:
+        return None
+    out = copy.copy(config)
+    if out.get("path") is None and out.get("class_path") is not None:
+        out["path"] = out["class_path"]
+    if out.get("config_type") is None:
+        out["config_type"] = "dict"
+    return out
+
+
 def validate_ckpt(ckpt: Optional[str]) -> None:
     """Validate a checkpoint path if provided.
 
diff --git a/tests/unit_test/recipe/fedopt_recipe_test.py b/tests/unit_test/recipe/fedopt_recipe_test.py
