jboat.dm_ol

Submodules

jboat.dm_ol.dynamical_system

class jboat.gm_ol.dynamical_system.DynamicalSystem(ll_objective, ul_objective, lower_loop, ul_model, ll_model, solver_config)[source]

Bases: object

abstract optimize(**kwargs)[source]

jboat.dm_ol.sequential_ds

class jboat.gm_ol.sequential_ds.SequentialDS(ordered_instances, custom_order)[source]

Bases: object

A dynamically created class for sequential hyper-gradient operations.

gradient_instances

A list of gradient operator instances, each implementing an optimize method.

Type:: List[object]

custom_order

A custom-defined order for executing the gradient operators.

Type:: List[str]

result_store

An instance of the ResultStore class for storing intermediate and final results.

Type:: ResultStore

optimize(**kwargs)[source]

Compute gradients sequentially using the ordered gradient operator instances.

Parameters:: **kwargs (dict) – Arbitrary keyword arguments required for gradient computations.
Returns:: A list of dictionaries containing results for each gradient operator.
Return type:: List[Dict]

Notes

The results of each gradient operator are passed as inputs to the subsequent operator.
Only the final result is stored in the ResultStore.

jboat.gm_ol.sequential_ds.makes_functional_dynamical_system(custom_order, **kwargs)[source]

Dynamically create a SequentialHyperGradient object with ordered gradient operators.

Parameters:: custom_order (List[str]) – User-defined operator order.
Returns:: An instance with ordered gradient operators and result management.
Return type:: SequentialHyperGradient

jboat.gm_ol.sequential_ds.validate_and_adjust_order(custom_order, gradient_order)[source]

Validate and adjust the custom order to align with the predefined gradient operator groups.

Parameters:

custom_order (List[str]) – The user-defined order of gradient operators.
gradient_order (List[List[str]]) – The predefined grouping of gradient operators, specifying valid order constraints.

Returns:

A validated and adjusted list of gradient operators that conforms to the predefined order.

Return type:

List[str]

Notes

The function filters out invalid operators from custom_order that do not exist in gradient_order.
It ensures that the returned order follows the precedence rules defined in gradient_order.

Example

>>> custom_order = ["op1", "op3", "op2"]
>>> gradient_order = [["op1", "op2"], ["op3"]]
>>> adjusted_order = validate_and_adjust_order(custom_order, gradient_order)
>>> print(adjusted_order)
['op1', 'op2', 'op3']

jboat.dm_ol.di

class jboat.gm_ol.di.DI(ll_objective, ul_objective, ll_model, ul_model, lower_loop, solver_config)[source]

Bases: DynamicalSystem

Implements the lower-level optimization procedure for Dynamic Initialization [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 (jittor.Module) – The lower-level model of the BLO problem.
ul_model (jittor.Module) – The upper-level model of the BLO problem.
lower_loop (int) – The number of iterations for the lower-level optimization process.
solver_config (Dict[str, Any]) – A dictionary containing configurations for the optimization solver, including hyperparameters and specific settings for NGD and GDA.

References

[1] Liu R., Liu Y., Zeng S., et al. “Towards gradient-based bilevel optimization with non-convex followers and beyond,” in NeurIPS, 2021.

optimize(ll_feed_dict, ul_feed_dict, auxiliary_model, auxiliary_opt, current_iter, next_operation=None, **kwargs)[source]

Executes the lower-level optimization procedure using the provided data and models.

Parameters:

ll_feed_dict (Dict[str, Any]) – Dictionary containing the lower-level data used for optimization. Typically includes: - “data” : The input data for lower-level optimization. - “target” : The target output (optional, depending on the task).
ul_feed_dict (Dict[str, Any]) – Dictionary containing the upper-level data used for optimization. Typically includes: - “data” : The input data for upper-level optimization. - “target” : The target output (optional, depending on the task).
auxiliary_model (_MonkeyPatchBase) – A patched lower model wrapped by the higher library. Serves as the lower-level model for optimization in a differentiable way.
auxiliary_opt (DifferentiableOptimizer) – A patched optimizer for the lower-level model, wrapped by the higher library. Allows for differentiable optimization steps.
current_iter (int) – The current iteration number of the optimization process.
next_operation (str) – Specifies the next operation to execute during the optimization process. Must not be None.
**kwargs (dict) – Additional arguments passed to the optimization procedure.

Returns:

A dictionary containing the input parameters and any additional keyword arguments.

Return type:

Dict

Raises:

AssertionError – If next_operation is not defined.

Notes

Ensure that next_operation is defined before calling this function to specify the next operation in the optimization pipeline.

jboat.dm_ol.dm

class jboat.gm_ol.dm.DM(ll_objective, lower_loop, ul_model, ul_objective, ll_model, solver_config)[source]

Bases: DynamicalSystem

Implements the lower-level optimization procedure for Dual Multiplier (DM) [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 (jittor.Module) – The lower-level model of the BLO problem.
ul_model (jittor.Module) – The upper-level model of the BLO problem.
lower_loop (int) – The number of iterations for the lower-level optimization process.
solver_config (Dict[str, Any]) – A dictionary containing configurations for the optimization solver, including hyperparameters and specific settings for NGD, GDA, and DM.

References

[1] Liu R, Liu Y, Yao W, et al., “Averaged method of multipliers for bi-level optimization without lower-level: strong convexity,” ICML, 2023.

optimize(ll_feed_dict, ul_feed_dict, auxiliary_model, auxiliary_opt, current_iter, next_operation=None, **kwargs)[source]

Executes the lower-level optimization procedure with support for NGD, GDA, and RAD operations.

Parameters:

ll_feed_dict (Dict) –
Dictionary containing the lower-level data used for optimization. Typically includes:
- ”data” : Training input data.
- ”target” : Training target data (optional, depending on the task).
ul_feed_dict (Dict) –
Dictionary containing the upper-level data used for optimization. Typically includes:
- ”data” : Validation input data.
- ”target” : Validation target data (optional, depending on the task).
auxiliary_model (_MonkeyPatchBase) – A patched lower model wrapped by the higher library. Used for differentiable optimization.
auxiliary_opt (DifferentiableOptimizer) – A patched optimizer for the lower-level model, wrapped by the higher library. Enables differentiable optimization steps.
current_iter (int) – The current iteration number in the optimization process.
next_operation (str, optional) – Specifies the next operation in the optimization process. Must be None for NGD. (default: None)
kwargs (dict) – Additional keyword arguments for the optimization process.

Returns:

Returns -1 upon successful completion of the optimization process.

Return type:

int

Notes

For GDA operations, this method supports three strategies: ‘s1’, ‘s2’, and ‘s3’.
When using RAD in na_op, a higher-order gradient adjustment is applied to the auxiliary variables.
Ensure that next_operation is None for NGD, as it does not support additional operations.

Raises:: AssertionError – If next_operation is not None for NGD or if an unsupported strategy is specified for GDA.

jboat.dm_ol.gda

class jboat.gm_ol.gda.GDA(ll_objective, ul_objective, ll_model, ul_model, lower_loop, solver_config)[source]

Bases: DynamicalSystem

Implements the optimization procedure of the Gradient Descent Aggregation (GDA) [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 (jittor.Module) – The lower-level model of the BLO problem.
ul_model (jittor.Module) – The upper-level model 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:
- ”GDA” (Dict): Configuration for the GDA algorithm:
  - ”alpha_init” (float): Initial learning rate for the GDA updates.
  - ”alpha_decay” (float): Decay rate for the learning rate.
- ”gda_loss” (Callable): The loss function used in the GDA optimization.

References

[1] R. Liu, P. Mu, X. Yuan, S. Zeng, and J. Zhang, “A generic first-order algorithmic framework for bi-level programming beyond lower-level singleton”, in ICML, 2020.

optimize(ll_feed_dict, ul_feed_dict, auxiliary_model, auxiliary_opt, current_iter, next_operation=None, **kwargs)[source]

Execute the lower-level optimization procedure using provided data, models, and patched optimizers.

Parameters:

ll_feed_dict (Dict) – Dictionary containing the lower-level data used for optimization. Typically includes training data, targets, and other information required to compute the LL objective.
ul_feed_dict (Dict) – Dictionary containing the upper-level data used for optimization. Typically includes validation data, targets, and other information required to compute the UL objective.
auxiliary_model (_MonkeyPatchBase) – A patched lower model wrapped by the higher library. This model is used for differentiable optimization in the lower-level procedure.
auxiliary_opt (DifferentiableOptimizer) – A patched optimizer for the lower-level model, wrapped by the higher library. Allows differentiable optimization.
current_iter (int) – The current iteration number of the optimization process.
next_operation (str, optional) – Specifies the next operation to be executed in the optimization pipeline. Default is None.
**kwargs (dict) – Additional parameters required for the optimization procedure.

Returns:

A dictionary containing:

”ll_feed_dict”Dict
Lower-level feed dictionary.
”ul_feed_dict”Dict
Upper-level feed dictionary.
”auxiliary_model”_MonkeyPatchBase
Patched lower-level model.
”auxiliary_opt”DifferentiableOptimizer
Patched lower-level optimizer.
”current_iter”int
Current iteration number.
”gda_loss”callable
Gradient Descent Aggregation (GDA) loss function.
”alpha”float
Coefficient used in the GDA operation, typically in (0, 1).
”alpha_decay”float
Decay factor for the coefficient alpha.

Return type:

dict

Raises:

AssertionError – If next_operation is not defined. If alpha is not in the range (0, 1). If gda_loss is not properly defined.

Notes

The method assumes that gda_loss is defined and accessible from the instance attributes.
The coefficient alpha and its decay rate alpha_decay must be properly configured.

jboat.dm_ol.ngd

class jboat.gm_ol.ngd.NGD(ll_objective, ul_objective, ll_model, ul_model, lower_loop, solver_config)[source]

Bases: DynamicalSystem

Implements the optimization procedure of the Naive Gradient Descent (NGD) [1].

Jittor version aligned with Torch version.

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 (jittor.Module) – The lower-level model of the BLO problem.
ul_model (jittor.Module) – The upper-level model 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. Keys include:

- "lower_level_opt": optimizer for LL
- "na_op": list of hyper-gradient ops
- "RGT": {"truncate_iter": int}

References

[1] Franceschi et al., ICML 2018

optimize(ll_feed_dict, ul_feed_dict, auxiliary_model, auxiliary_opt, current_iter, next_operation=None, **kwargs)[source]