boat_torch.fo_ol

Submodules

boat_torch.fo_ol.alto

class boat_torch.fo_ol.alto.ALTO(ll_objective, lower_loop, ul_model, ul_objective, ll_model, ll_var, ul_var, solver_config)[source]

Bases: DynamicalSystem

Implements a simple Alternating Optimization (ALT) procedure for bi-level optimization.

optimize(ll_feed_dict, ul_feed_dict, current_iter)[source]: Executes the simple alternating optimization procedure.

boat_torch.fo_ol.gaffo

class boat_torch.fo_ol.gaffo.GAFFO(ll_objective, lower_loop, ul_model, ul_objective, ll_model, ll_var, ul_var, solver_config)[source]

Bases: DynamicalSystem

Implements the optimization procedure of Gap-Function-based First-Order Method (GAFFO) [1].

This first-order implementation treats lower-level variables as the current task state and writes the meta-gradient to matching upper-level variables.

Parameters:

ll_objective (Callable) – The lower-level objective of the BLO problem.
ul_objective (Callable) – The upper-level objective of the BLO problem.
ll_model (torch.nn.Module) – The lower-level model of the BLO problem.
ul_model (torch.nn.Module) – The upper-level model of the BLO problem.
ll_var (List[torch.Tensor]) – The list of lower-level variables of the BLO problem.
ul_var (List[torch.Tensor]) – The list of upper-level variables of the BLO problem.
lower_loop (int) – Number of iterations for lower-level optimization.
solver_config (Dict[str, Any]) –
A dictionary containing solver configurations. Expected keys include:
- ”lower_level_opt”: The optimizer for the lower-level model.
- ”GAFFO” (Dict): A dictionary containing the following optional keys:
  - ”lambda” or “gap_lambda”: Regularization weight for the gap term.
  - ”sigma”: Probe step size used to estimate the regularized gap.
  - ”lower_step_size”: Step size for the lower-level update. If not specified, the learning rate of “lower_level_opt” is used.
  - ”use_sign_lower_step”: Whether to use the sign of lower-level gradients for the lower-level update.
  - ”maximize”: Whether to use the ascent-form GAFFO direction.
  - ”sync_lower_from_upper”: Whether to synchronize lower-level variables from upper-level variables before each update.
  - ”projection”: Optional projection operator for constrained lower-level variables.

References

[1] Yao W, Yin H, Zeng S, and Zhang J. “Overcoming Lower-Level Constraints in Bilevel Optimization: A Novel Approach with Regularized Gap Functions,” arXiv:2406.01992, 2024.

optimize(ll_feed_dict, ul_feed_dict, current_iter)[source]

boat_torch.fo_ol.meso

class boat_torch.fo_ol.meso.MESO(ll_objective, lower_loop, ul_model, ul_objective, ll_model, ll_var, ul_var, solver_config)[source]

Bases: DynamicalSystem

Implements the optimization procedure of Moreau Envelope based Single-loop Method (MESO) [1].

Parameters:

ll_objective (Callable) – The lower-level objective of the BLO problem.
ul_objective (Callable) – The upper-level objective of the BLO problem.
ll_model (torch.nn.Module) – The lower-level model of the BLO problem.
ul_model (torch.nn.Module) – The upper-level model of the BLO problem.
ll_var (List[torch.Tensor]) – The list of lower-level variables of the BLO problem.
ul_var (List[torch.Tensor]) – The list of upper-level variables of the BLO problem.
lower_loop (int) – Number of iterations for lower-level optimization.
solver_config (Dict[str, Any]) –
A dictionary containing solver configurations. Expected keys include:
- ”lower_level_opt”: The optimizer for the lower-level model.
- ”MESO” (Dict): A dictionary containing the following keys:
  - ”eta”: Learning rate for the MESO optimization procedure.
  - ”gamma_1”: Regularization parameter for the MESO algorithm.
  - ”c0”: Initial constant for the update steps.
  - ”y_hat_lr”: Learning rate for optimizing the surrogate variable y_hat.

References

[1] Liu R, Liu Z, Yao W, et al. “Moreau Envelope for Nonconvex Bi-Level Optimization: A Single-loop and Hessian-free Solution Strategy,” ICML, 2024.

optimize(ll_feed_dict, ul_feed_dict, current_iter)[source]

Executes the optimization procedure using the provided data and model configurations.

Parameters:

ll_feed_dict (Dict) – Dictionary containing the lower-level data used for optimization. Typically includes training data or parameters for the lower-level objective.
ul_feed_dict (Dict) – Dictionary containing the upper-level data used for optimization. Usually includes parameters or configurations for the upper-level objective.
current_iter (int) – The current iteration count of the optimization process, used for tracking progress or adjusting optimization parameters.

Returns:

A dictionary containing the upper-level objective and the status of hypergradient computation.

Return type:

Dict

boat_torch.fo_ol.pgdo

class boat_torch.fo_ol.pgdo.PGDO(ll_objective, lower_loop, ul_model, ul_objective, ll_model, ll_var, ul_var, solver_config)[source]

Bases: DynamicalSystem

Implements the optimization procedure of Penalty-based Gradient Descent Method (PGDO) [1].

Parameters:

ll_objective (Callable) – The lower-level objective of the BLO problem.
ul_objective (Callable) – The upper-level objective of the BLO problem.
ll_model (torch.nn.Module) – The lower-level model of the BLO problem.
ul_model (torch.nn.Module) – The upper-level model of the BLO problem.
ll_var (List[torch.Tensor]) – The list of lower-level variables of the BLO problem.
ul_var (List[torch.Tensor]) – The list of upper-level variables of the BLO problem.
lower_loop (int) – Number of iterations for lower-level optimization.
solver_config (Dict[str, Any]) –
A dictionary containing solver configurations. Expected keys include:
- ”lower_level_opt”: The optimizer for the lower-level model.
- ”PGDO” (Dict): A dictionary containing the following keys:
  - ”y_hat_lr”: Learning rate for optimizing the surrogate variable y_hat.
  - ”gamma_init”: Initial value of the hyperparameter gamma.
  - ”gamma_max”: Maximum value of the hyperparameter gamma.
  - ”gamma_argmax_step”: Step size of the hyperparameter gamma.

References

[1] Shen H, Chen T. “On penalty-based bilevel gradient descent method,” in ICML, 2023.

optimize(ll_feed_dict, ul_feed_dict, current_iter)[source]

Executes the optimization procedure using the provided data and model configurations.

Parameters:

ll_feed_dict (Dict) – Dictionary containing the lower-level data used for optimization. Typically includes training data or parameters for the lower-level objective.
ul_feed_dict (Dict) – Dictionary containing the upper-level data used for optimization. Usually includes parameters or configurations for the upper-level objective.
current_iter (int) – The current iteration count of the optimization process, used for tracking progress or adjusting optimization parameters.

Returns:

A dictionary containing the upper-level objective and the status of hypergradient computation.

Return type:

Dict

boat_torch.fo_ol.vfo

class boat_torch.fo_ol.vfo.VFO(ll_objective, lower_loop, ul_model, ul_objective, ll_model, ll_var, ul_var, solver_config)[source]

Bases: DynamicalSystem

Implements the optimization procedure of Value-function based First-Order Method (VFO) [1].

Parameters:

ll_objective (Callable) – The lower-level objective function of the BLO problem.
ul_objective (Callable) – The upper-level objective function of the BLO problem.
ll_model (torch.nn.Module) – The lower-level model of the BLO problem.
ul_model (torch.nn.Module) – The upper-level model of the BLO problem.
ll_var (List[torch.Tensor]) – A list of lower-level variables of the BLO problem.
ul_var (List[torch.Tensor]) – A list of upper-level variables of the BLO problem.
lower_loop (int) – The number of iterations for lower-level optimization.
solver_config (Dict[str, Any]) –
A dictionary containing configurations for the solver. Expected keys include:
- ”lower_level_opt” (torch.optim.Optimizer): Optimizer for the lower-level model.
- ”VFO” (Dict): Configuration for the VFO algorithm:
  - ”y_hat_lr” (float): Learning rate for optimizing the surrogate variable y_hat.
  - ”eta” (float): Step size for value-function updates.
  - ”u1” (float): Hyperparameter controlling the penalty in the value function.
- ”device” (str): Device on which computations are performed, e.g., “cpu” or “cuda”.

References

[1] R. Liu, X. Liu, X. Yuan, S. Zeng and J. Zhang, “A Value-Function-based Interior-point Method for Non-convex Bi-level Optimization,” in ICML, 2021.

optimize(ll_feed_dict, ul_feed_dict, current_iter)[source]

Executes the optimization procedure using the provided data and model configurations.

Parameters:

ll_feed_dict (Dict) – Dictionary containing the lower-level data used for optimization. Typically includes training data or parameters for the lower-level objective.
ul_feed_dict (Dict) – Dictionary containing the upper-level data used for optimization. Usually includes parameters or configurations for the upper-level objective.
current_iter (int) – The current iteration count of the optimization process, used for tracking progress or adjusting optimization parameters.

Returns:

A dictionary containing the upper-level objective and the status of hypergradient computation.

Return type:

Dict

boat_torch.fo_ol.vso

class boat_torch.fo_ol.vso.VSO(ll_objective, lower_loop, ul_model, ul_objective, ll_model, ll_var, ul_var, solver_config)[source]

Bases: DynamicalSystem

Implements the optimization procedure of Value-function based Sequential Method (VSO) [1].

Parameters:

ll_objective (Callable) – The lower-level objective function of the BLO problem.
ul_objective (Callable) – The upper-level objective function of the BLO problem.
ll_model (torch.nn.Module) – The lower-level model of the BLO problem.
ul_model (torch.nn.Module) – The upper-level model of the BLO problem.
ll_var (List[torch.Tensor]) – A list of lower-level variables of the BLO problem.
ul_var (List[torch.Tensor]) – A list of upper-level variables of the BLO problem.
lower_loop (int) – The number of iterations for lower-level optimization.
solver_config (Dict[str, Any]) –
A dictionary containing configurations for the solver. Expected keys include:
- ”lower_level_opt” (torch.optim.Optimizer): Optimizer for the lower-level model.
- ”VSO” (Dict): Configuration for the VSO algorithm:
  - ”z_loop” (int): Number of iterations for optimizing the auxiliary variable z.
  - ”ll_l2_reg” (float): L2 regularization coefficient for the lower-level model.
  - ”ul_l2_reg” (float): L2 regularization coefficient for the upper-level model.
  - ”ul_ln_reg” (float): Logarithmic regularization coefficient for the upper-level model.
  - ”reg_decay” (float): Decay rate for the regularization coefficients.
  - ”z_lr” (float): Learning rate for optimizing the auxiliary variable z.
- ”device” (str): Device on which computations are performed, e.g., “cpu” or “cuda”.

References

[1] Liu B, Ye M, Wright S, et al. “BOME! Bilevel Optimization Made Easy: A Simple First-Order Approach”, in NeurIPS, 2022.

optimize(ll_feed_dict, ul_feed_dict, current_iter)[source]

Executes the optimization procedure using the provided data and model configurations.

Parameters:

ll_feed_dict (Dict) – Dictionary containing the lower-level data used for optimization. Typically includes training data or parameters for the lower-level objective.
ul_feed_dict (Dict) – Dictionary containing the upper-level data used for optimization. Usually includes parameters or configurations for the upper-level objective.
current_iter (int) – The current iteration count of the optimization process, used for tracking progress or adjusting optimization parameters.

Returns:

A dictionary containing the upper-level objective and the status of hypergradient computation.

Return type:

Dict