Solvers Module

Contents

Solvers Module#

Solver implementations and configurations.

Alternating Direction Method of Multipliers#

class rlaopt.solvers.ADMM(obj, config, detach=True)[source]#

Alternating Direction Method of Multipliers (ADMM) solver.

Solves problems of the form:

minimize f(x) + sum_i g_i(A_i x - b_i)

where f is smooth (differentiable) and each g_i is proxable.

Parameters:
__init__(obj, config, detach=True)[source]#

Initialize the ADMM solver.

Parameters:

  • obj (Expression) – The optimization problem to solve.

  • config (ADMMConfig) – Configuration for the ADMM solver.

  • detach (bool) – Whether to detach params and state from computation graph between iterations. Set to False only if you need to differentiate through the entire solver. Default: True.

init_state(variable_values)[source]#

Initialize the solver state.

Parameters:

variable_values (TensorDict) – Initial variable values.

Returns:

Initial solver state.

Return type:

ADMMState

step(variables_values, state)[source]#

Perform a single ADMM optimization step.

Parameters:

  • variables_values (TensorDict) – Current variable values.

  • state (ADMMState) – Current ADMM solver state.

Returns:

Tuple of updated variable values and solver state.

Return type:

tuple[TensorDict, ADMMState]

solve(variable_values=None, stopping_criteria=ADMMStoppingCriteria(max_iters=1000, eps_abs=0.0001, eps_rel=0.0001))[source]#

Solve the optimization problem using ADMM.

Parameters:

  • variable_values (TensorDict | None) – Initial variable values.

  • stopping_criteria (ADMMStoppingCriteria) – Stopping criteria for the solver.

Returns:

Result of the optimization containing optimized variable values

among other metrics.

Return type:

ADMMResult

pydantic model rlaopt.solvers.ADMMConfig[source]#

Configuration for the ADMM solver.

Parameters:
Return type:

None

field rho: float = 1.0#

Augmented Lagrangian penalty at initialization.

Constraints:

  • gt = 0.0

field rho_update_factor: float = 2.0#

Factor to update rho in primal-dual balancing.

Constraints:

  • gt = 1.0

field rho_update_threshold: float = 10.0#

Threshold for updating rho in primal-dual balancing.

Constraints:

  • gt = 0.0

field rho_update_freq: int = 25#

Frequency (in iterations) for updating rho.

Constraints:

  • ge = 1

field alpha: float = 1.6#

Over-relaxation parameter.

Constraints:

  • gt = 0.0

  • lt = 2.0

field sigma: float = 1e-06#

Regularization parameter for the inexact ADMM linear system.

Constraints:

  • ge = 0.0

field gamma: float = 1.2#

Exponent for the linear system solve tolerance.

Constraints:

  • gt = 1.0

field preconditioner_config: PreconditionerConfig = NystromConfig(rank_init=50, rank_max=50, num_power_iters=10, error_tolerance=0.01, base_damping=0.0, damping_mode='adaptive')#

Configuration for the linear system preconditioner.

field preconditioner_update_freq: int = 20#

Frequency (in iterations) for updating the preconditioner.

Constraints:

  • ge = 1

pydantic model rlaopt.solvers.ADMMStoppingCriteria[source]#

Stopping criteria for the ADMM solver.

Parameters:
Return type:

None

field eps_abs: float = 0.0001#

Absolute tolerance for primal and dual residuals.

Constraints:

  • gt = 0.0

field eps_rel: float = 0.0001#

Relative tolerance for primal and dual residuals.

Constraints:

  • gt = 0.0

field max_iters: int = 1000#

Maximum number of iterations.

Constraints:

  • gt = 0

class rlaopt.solvers.ADMMResult(variable_values, convergence_status, num_iters, solver_time, primal_residual_norm, dual_residual_norm)[source]#

Result container for the ADMM solver.

Parameters:
variable_values#

Optimized variable values.

Type:

rlaopt.ext_tensordict.TensorDict

convergence_status#

Status indicating how the solver terminated.

Type:

rlaopt.solvers.solver_base.ConvergenceStatus

num_iters#

Number of iterations performed.

Type:

int

solver_time#

Time taken by the solver in seconds.

Type:

float

primal_residual_norm#

Norm of the primal residual.

Type:

float

dual_residual_norm#

Norm of the dual residual.

Type:

float

primal_residual_norm: float#
dual_residual_norm: float#

Proximal Gradient#

class rlaopt.solvers.ProxGrad(obj, config, detach=True)[source]#

Proximal gradient solver for optimization problems.

Solves problems of the form:

minimize f(x) + g(x)

where f is smooth (differentiable) and g is proxable (has an efficient proximal operator).

Supports multiple variants: - Basic proximal gradient (fixed step size) - Accelerated proximal gradient (Nesterov momentum) - Backtracking line search for adaptive step sizes - Preconditioned proximal gradient (e.g. Nyström) with optional

automatic stepsize

  • Combinations of acceleration and line search

Combination constraints (enforced by ProxGradConfig): - A non-identity preconditioner is incompatible with both line search

and Nesterov acceleration.

  • Line search and automatic stepsize cannot both be enabled.

Parameters:
__init__(obj, config, detach=True)[source]#

Initialize the proximal gradient solver.

Parameters:

  • obj (Expression) – The optimization objective (Expression).

  • config (ProxGradConfig) – Configuration for the solver.

  • detach – Whether to detach variable values from the autograd graph.

init_state(variable_values)[source]#

Initialize the proximal gradient solver state.

Parameters:

variable_values (TensorDict)

Return type:

ProxGradState

step(variable_values, state)[source]#

Perform a single proximal gradient step.

Parameters:

  • variable_values (TensorDict)

  • state (ProxGradState)

Return type:

tuple[TensorDict, ProxGradState]

pydantic model rlaopt.solvers.ProxGradConfig[source]#

Configuration for proximal gradient solvers.

Validators:

  • _check_combinations » all fields

Parameters:
Return type:

None

field eta: float = 1.0#

Step size for the gradient update.

Constraints:

  • gt = 0.0

Validated by:

  • _check_combinations

field use_acceleration: bool = False#

Whether to use Nesterov acceleration.

Validated by:

  • _check_combinations

field use_linesearch: bool = True#

Whether to use line search for step size selection.

Validated by:

  • _check_combinations

field precond_update_freq: int = 10#

How frequently in iterations the preconditioner and stepsize (if auto_update_stepsize = True) are updated. Defaults to 10 iterations. Ignored when precond_config is identity.

Constraints:

  • gt = 0

Validated by:

  • _check_combinations

field precond_config: PreconditionerConfig = IdentityConfig()#

Preconditioner configuration. Defaults to identity (i.e. no preconditioning).

Validated by:

  • _check_combinations

field subproblem_iters: int = 20#

Number of accelerated proximal gradient iterations performed to evaluate the scaled proximal operator. Not used if the problem is fully smooth or the preconditioner is identity.

Constraints:

  • gt = 0

Validated by:

  • _check_combinations

field auto_update_stepsize: bool = False#

Boolean flag specifying whether to automatically update the stepsize based on an estimate of the local smoothness constant. Defaults to False.

Validated by:

  • _check_combinations

Preconditioned Conjugate Gradient#

class rlaopt.solvers.PCG(lin_sys, config, detach=True)[source]#

Block Preconditioned Conjugate Gradient solver for linear systems.

Solves linear systems of the form:

AW = B

where A is a symmetric positive-definite matrix.

The PCG method uses a preconditioner to improve convergence. The algorithm iteratively refines the solution by moving along conjugate search directions that are scaled by the preconditioner.

Parameters:
__init__(lin_sys, config, detach=True)[source]#

Initialize the PCG solver.

Parameters:

  • lin_sys (LinSys) – The linear system to solve.

  • config (PCGConfig) – Configuration for the solver.

  • detach (bool) – Whether to detach params and state from computation graph between iterations. Set to False only if you need to differentiate through the entire solver. Default: True.

init_state(params)[source]#

Initialize the solver state.

Parameters:

params (Tensor) – Initial parameters (solution estimate).

Returns:

Initial solver state.

Return type:

PCGState

step(params, state)[source]#

Perform a single PCG iteration step.

Parameters:

  • params (Tensor) – Current parameters (solution estimate).

  • state (PCGState) – Current solver state.

Returns:

Tuple of updated parameters and solver state.

Return type:

tuple[Tensor, PCGState]

solve(params=None, stopping_criteria=PCGStoppingCriteria(max_iters=1000, tol=1e-06))[source]#

Solve the linear system AW = B using PCG.

Parameters:

  • params (Tensor | None) – Initial parameters (solution estimate). If None, defaults to parameters in linear system.

  • stopping_criteria (PCGStoppingCriteria) – Criteria to determine when to stop the solver. Defaults to PCGStoppingCriteria().

Returns:

PCGResult containing the solution and convergence information.

Return type:

PCGResult

pydantic model rlaopt.solvers.PCGConfig[source]#

Configuration for the Preconditioned Conjugate Gradient solver.

Parameters:

preconditioner_config (PreconditionerConfig)

Return type:

None

field preconditioner_config: PreconditionerConfig = IdentityConfig()#
pydantic model rlaopt.solvers.PCGStoppingCriteria[source]#

Stopping criteria specific to the PCG solver.

Parameters:
Return type:

None

max_iters#

Maximum number of iterations.

tol#

Relative tolerance for convergence.

field tol: float = 1e-06#
Constraints:

  • gt = 0

field max_iters: int = 1000#

Maximum number of iterations.

Constraints:

  • gt = 0

class rlaopt.solvers.PCGResult(solution, convergence_status, num_iters, solver_time, residual_norm)[source]#

Result container for the PCG solver.

Parameters:
solution#

Converged solution parameters.

Type:

torch.Tensor

convergence_status#

Status indicating how the solver terminated.

Type:

rlaopt.solvers.solver_base.ConvergenceStatus

num_iters#

Number of iterations performed.

Type:

int

solver_time#

Time taken by the solver in seconds.

Type:

float

residual_norm#

Final residual norm per component.

Type:

torch.Tensor

residual_norm: Tensor#

Convergence Status#

class rlaopt.solvers.ConvergenceStatus(value)[source]#

Enumeration of possible solver convergence statuses.

CONVERGED#

Solver converged to within specified tolerance.

NOT_CONVERGED#

Solver did not converge within the maximum iterations.

CONVERGED = 'converged'#
NOT_CONVERGED = 'not_converged'#
Contents