Parameters#

group grp_Parameters

Parameters to customize the behavior of solvers and directions.

template<Config Conf = DefaultConfig> struct AndersonAccelParams

#include <alpaqa/accelerators/anderson.hpp>

Parameters for the AndersonAccel class.

Public Members

length_t memory = 10

Length of the history to keep (the number of columns in the QR factorization).

If this number is greater than the problem dimension, the memory is set to the problem dimension (otherwise the system is underdetermined).

real_t min_div_fac = real_t(1e2) * std::numeric_limits<real_t>::epsilon(): Minimum divisor when solving close to singular systems, scaled by the maximum eigenvalue of R.

template<Config Conf = DefaultConfig> struct CBFGSParams

#include <alpaqa/accelerators/lbfgs.hpp>

Cautious BFGS update.

See also

LBFGSStepSize

template<Config Conf> struct SteihaugCGParams

#include <alpaqa/accelerators/steihaugcg.hpp>

Parameters for SteihaugCG.

Public Members

real_t tol_scale = 1

Determines the tolerance for termination of the algorithm.

It terminates if the norm of the residual \( r = -g - Hq \) is smaller than the tolerance

\[ \mathrm{tolerance} = \min\left( \mathrm{tol\_max},\; \mathrm{tol\_scale}\cdot \|g\|\cdot \min\left(\mathrm{tol\_scale\_root},\; \sqrt{\|g\|}\right) \right) \]

real_t tol_scale_root = real_t(0.5)

Determines the tolerance for termination of the algorithm.

See tol_scale.

real_t tol_max = inf<config_t>

Determines the tolerance for termination of the algorithm.

Prevents the use of huge tolerances if the gradient norm is still large. See tol_scale.

real_t max_iter_factor = 1: Limit the number of CG iterations to \( \lfloor n \cdot \mathrm{max\_iter\_factor} \rceil \), where \( n \) is the number of free variables of the problem.

template<Config Conf> struct AndersonDirectionParams

#include <alpaqa/inner/directions/panoc/anderson.hpp>

Parameters for the AndersonDirection class.

Public Members

bool rescale_on_step_size_changes = false: Instead of flushing the buffer when the step size changes, rescale the buffer by a factor \( \gamma_k / \gamma_{k-1} \).

template<Config Conf> struct ConvexNewtonRegularizationParams

#include <alpaqa/inner/directions/panoc/convex-newton.hpp>

Parameters for the ConvexNewtonDirection class.

Public Members

real_t ζ = real_t(1e-8)

real_t ν = 1

bool ldlt = false

template<Config Conf> struct ConvexNewtonDirectionParams

#include <alpaqa/inner/directions/panoc/convex-newton.hpp>

Parameters for the ConvexNewtonDirection class.

Public Members

real_t hessian_vec_factor = 0

Set this option to a nonzero value to include the Hessian-vector product \( \nabla^2_{x_\mathcal{J}x_\mathcal{K}}\psi(x) q_\mathcal{K} \) from equation 12b in [4], scaled by this parameter.

Set it to zero to leave out that term.

bool quadratic = false

template<Config Conf> struct LBFGSDirectionParams

#include <alpaqa/inner/directions/panoc/lbfgs.hpp>

Parameters for the LBFGSDirection class.

Public Members

bool rescale_on_step_size_changes = false: Instead of flushing the buffer when the step size changes, rescale the buffer by a factor \( \gamma_k / \gamma_{k-1} \).

template<Config Conf> struct StructuredLBFGSDirectionParams

#include <alpaqa/inner/directions/panoc/structured-lbfgs.hpp>

Parameters for the StructuredLBFGSDirection class.

Public Types

enum FailurePolicy

Values:

enumerator FallbackToProjectedGradient: If L-BFGS fails, propagate the failure and tell PANOC that no accelerated step is available, causing it to accept the projected gradient step instead.

enumerator UseScaledLBFGSInput: If L-BFGS fails, return \( q_\mathcal{J} = -\gamma\nabla_{x_\mathcal{J}}\psi(x^k) -\gamma\nabla^2_{x_\mathcal{J}x_\mathcal{K}}\psi(x) q_\mathcal{K} \) as the accelerated step (effectively approximating \( \nabla_{x_\mathcal{J}x_\mathcal{J}} \approx \gamma I \)).

Public Members

real_t hessian_vec_factor = 0

Set this option to a nonzero value to include the Hessian-vector product \( \nabla^2_{x_\mathcal{J}x_\mathcal{K}}\psi(x) q_\mathcal{K} \) from equation 12b in [4], scaled by this parameter.

Set it to zero to leave out that term (this usually only slightly increases the number of iterations, and eliminates one Hessian-vector product per iteration, improving the overall runtime).

bool hessian_vec_finite_differences = true: If hessian_vec_factor is nonzero, set this option to true to approximate that term using finite differences instead of using AD.

bool full_augmented_hessian = true: If hessian_vec_factor is nonzero and hessian_vec_finite_differences is true, set this option to true to compute the exact Hessian of the augmented Lagrangian, false to approximate it using the Hessian of the Lagrangian.

enum alpaqa::StructuredLBFGSDirectionParams::FailurePolicy failure_policy = FallbackToProjectedGradient

What to do when L-BFGS failed (e.g.

if there were no pairs (s, y) with positive curvature).

template<Config Conf> struct StructuredNewtonRegularizationParams

#include <alpaqa/inner/directions/panoc/structured-newton.hpp>

Parameters for the StructuredNewtonDirection class.

Public Members

real_t min_eig = std::cbrt(std::numeric_limits<real_t>::epsilon()): Minimum eigenvalue of the Hessian, scaled by \( 1 + |\lambda_\mathrm{max}| \), enforced by regularization using a multiple of identity.

bool print_eig = false: Print the minimum and maximum eigenvalue of the Hessian.

template<Config Conf> struct StructuredNewtonDirectionParams

#include <alpaqa/inner/directions/panoc/structured-newton.hpp>

Parameters for the StructuredNewtonDirection class.

Public Members

real_t hessian_vec_factor = 0

Set this option to a nonzero value to include the Hessian-vector product \( \nabla^2_{x_\mathcal{J}x_\mathcal{K}}\psi(x) q_\mathcal{K} \) from equation 12b in [4], scaled by this parameter.

Set it to zero to leave out that term.

template<Config Conf> struct NewtonTRDirectionParams

#include <alpaqa/inner/directions/pantr/newton-tr.hpp>

Parameters for the NewtonTRDirection class.

Public Members

real_t hessian_vec_factor = real_t(1)

The factor in front of the term \( \langle H_{\mathcal{JK}} d_{\mathcal {K}}, d_{\mathcal{J}} \rangle \) in equation (9) in [1].

Set it to zero to leave out that term (this usually only slightly increases the number of iterations, and eliminates one Hessian-vector product per iteration, improving the overall runtime).

bool finite_diff = false: Use finite differences to compute Hessian-vector products.

real_t finite_diff_stepsize = std::sqrt(std::numeric_limits<real_t>::epsilon())

Size of the perturbation for the finite differences computation.

Multiplied by \( 1+\|x\| \).

template<Config Conf = DefaultConfig> struct FISTAParams

#include <alpaqa/inner/fista.hpp>

Tuning parameters for the FISTA algorithm.

Public Members

LipschitzEstimateParams<config_t> Lipschitz = {}: Parameters related to the Lipschitz constant estimate and step size.

unsigned max_iter = 1000: Maximum number of inner FISTA iterations.

std::chrono::nanoseconds max_time = std::chrono::minutes(5): Maximum duration.

real_t L_min = real_t(1e-5): Minimum Lipschitz constant estimate.

real_t L_max = real_t(1e20): Maximum Lipschitz constant estimate.

PANOCStopCrit stop_crit = PANOCStopCrit::ApproxKKT: What stopping criterion to use.

unsigned max_no_progress = 10: Maximum number of iterations without any progress before giving up.

unsigned print_interval = 0

When to print progress.

If set to zero, nothing will be printed. If set to N != 0, progress is printed every N iterations.

int print_precision = std::numeric_limits<real_t>::max_digits10 / 2: The precision of the floating point values printed by the solver.

real_t quadratic_upperbound_tolerance_factor = 10 * std::numeric_limits<real_t>::epsilon()

Tolerance factor used in the quadratic upper bound condition that determines the step size.

Its goal is to account for numerical errors in the function and gradient evaluations. If you notice that the step size γ becomes very small, you may want to increase this factor.

bool disable_acceleration = false

Don’t compute accelerated steps, fall back to forward-backward splitting.

For testing purposes.

template<Config Conf = DefaultConfig> struct LipschitzEstimateParams

#include <alpaqa/inner/internal/lipschitz.hpp>

Parameters for the estimation of the Lipschitz constant of the gradient of the smooth term of the cost.

This is needed to select a suitable step size for the forward-backward iterations used by solvers like PANOC and PANTR.

Public Members

real_t L_0 = 0

Initial estimate of the Lipschitz constant of ∇ψ(x).

If set to zero, it will be approximated using finite differences.

real_t ε = real_t(1e-6): Relative step size for initial finite difference Lipschitz estimate.

real_t δ = real_t(1e-12): Minimum step size for initial finite difference Lipschitz estimate.

real_t Lγ_factor = real_t(0.95)

Factor that relates step size γ and Lipschitz constant.

Parameter α in Algorithm 2 of [2]. \( 0 < \alpha < 1 \)

template<Config Conf = DefaultConfig> struct PANOCOCPParams

#include <alpaqa/inner/panoc-ocp.hpp>

Tuning parameters for the PANOC algorithm.

Public Members

LipschitzEstimateParams<config_t> Lipschitz = {}: Parameters related to the Lipschitz constant estimate and step size.

unsigned max_iter = 100: Maximum number of inner PANOC iterations.

std::chrono::nanoseconds max_time = std::chrono::minutes(5): Maximum duration.

real_t min_linesearch_coefficient = real_t(1. / 256): Minimum weight factor between Newton step and projected gradient step, line search parameter.

real_t linesearch_strictness_factor = real_t(0.95)

Parameter β used in the line search (see Algorithm 2 in [2]).

\( 0 < \beta < 1 \)

real_t L_min = real_t(1e-5): Minimum Lipschitz constant estimate.

real_t L_max = real_t(1e20): Maximum Lipschitz constant estimate.

unsigned L_max_inc = 16: Maximum number of times to double the Lipschitz constant estimate per iteration.

PANOCStopCrit stop_crit = PANOCStopCrit::ApproxKKT: What stopping criterion to use.

unsigned max_no_progress = 10: Maximum number of iterations without any progress before giving up.

unsigned gn_interval = 1: How often to use a Gauss-Newton step. Zero to disable GN entirely.

bool gn_sticky = true: Keep trying to apply a Gauss-Newton step as long as they keep getting accepted with step size one.

bool reset_lbfgs_on_gn_step = false: Flush the L-BFGS buffer when a Gauss-Newton step is accepted.

bool lqr_factor_cholesky = true

Use a Cholesky factorization for the Riccati recursion.

Use LU if set to false.

LBFGSParams<config_t> lbfgs_params: L-BFGS parameters (e.g. memory).

unsigned print_interval = 0

When to print progress.

If set to zero, nothing will be printed. If set to N != 0, progress is printed every N iterations.

int print_precision = std::numeric_limits<real_t>::max_digits10 / 2: The precision of the floating point values printed by the solver.

real_t quadratic_upperbound_tolerance_factor = real_t(1e2) * std::numeric_limits<real_t>::epsilon()

Tolerance factor used in the quadratic upper bound condition that determines the step size.

Its goal is to account for numerical errors in the function and gradient evaluations. If you notice that the step size γ becomes very small, you may want to increase this factor.

real_t linesearch_tolerance_factor = real_t(1e2) * std::numeric_limits<real_t>::epsilon()

Tolerance factor used in the line search.

Its goal is to account for numerical errors in the function and gradient evaluations. If you notice that accelerated steps are rejected (τ = 0) when getting closer to the solution, you may want to increase this factor.

bool disable_acceleration = false

Don’t compute accelerated steps, fall back to forward-backward splitting.

For testing purposes.

template<Config Conf = DefaultConfig> struct PANOCParams

#include <alpaqa/inner/panoc.hpp>

Tuning parameters for the PANOC algorithm.

Public Members

LipschitzEstimateParams<config_t> Lipschitz = {}: Parameters related to the Lipschitz constant estimate and step size.

unsigned max_iter = 100: Maximum number of inner PANOC iterations.

std::chrono::nanoseconds max_time = std::chrono::minutes(5): Maximum duration.

real_t min_linesearch_coefficient = real_t(1. / 256): Minimum weight factor between Newton step and projected gradient step.

real_t linesearch_coefficient_update_factor = real_t(0.5): Factor to decrease the line search factor by after a line search failure.

bool force_linesearch = false

Ignore the line search condition and always accept the accelerated step.

(For testing purposes only).

real_t linesearch_strictness_factor = real_t(0.95)

Parameter β used in the line search (see Algorithm 2 in [2]).

\( 0 < \beta < 1 \)

real_t L_min = real_t(1e-5): Minimum Lipschitz constant estimate.

real_t L_max = real_t(1e20): Maximum Lipschitz constant estimate.

PANOCStopCrit stop_crit = PANOCStopCrit::ApproxKKT: What stopping criterion to use.

unsigned max_no_progress = 10: Maximum number of iterations without any progress before giving up.

unsigned print_interval = 0

When to print progress.

If set to zero, nothing will be printed. If set to N != 0, progress is printed every N iterations.

int print_precision = std::numeric_limits<real_t>::max_digits10 / 2: The precision of the floating point values printed by the solver.

real_t quadratic_upperbound_tolerance_factor = 10 * std::numeric_limits<real_t>::epsilon()

Tolerance factor used in the quadratic upper bound condition that determines the step size.

Its goal is to account for numerical errors in the function and gradient evaluations. If you notice that the step size γ becomes very small, you may want to increase this factor.

real_t linesearch_tolerance_factor = 10 * std::numeric_limits<real_t>::epsilon()

Tolerance factor used in the line search.

bool update_direction_in_candidate = false: Use the candidate point rather than the accepted point to update the quasi-Newton direction.

bool recompute_last_prox_step_after_stepsize_change = false

If the step size changes, the direction buffer is flushed.

The current step will still be used to update the direction, but may still use the old step size. If set to true, the current step will be recomputed with the new step size as well, to match the step in the candidate iterate.

bool eager_gradient_eval = false

When evaluating ψ(x̂) in a candidate point, always evaluate ∇ψ(x̂) as well.

Can be beneficial if computing ∇ψ(x̂) is not much more expensive than computing just ψ(x), and if ∇ψ(x̂) is required in the next iteration (e.g. for the stopping criterion, or when using the NoopDirection).

template<Config Conf = DefaultConfig> struct PANTRParams

#include <alpaqa/inner/pantr.hpp>

Tuning parameters for the PANTR algorithm.

Public Members

LipschitzEstimateParams<config_t> Lipschitz = {}: Parameters related to the Lipschitz constant estimate and step size.

unsigned max_iter = 100: Maximum number of inner PANTR iterations.

std::chrono::nanoseconds max_time = std::chrono::minutes(5): Maximum duration.

real_t L_min = real_t(1e-5): Minimum Lipschitz constant estimate.

real_t L_max = real_t(1e20): Maximum Lipschitz constant estimate.

PANOCStopCrit stop_crit = PANOCStopCrit::ApproxKKT: What stopping criterion to use.

unsigned max_no_progress = 10: Maximum number of iterations without any progress before giving up.

unsigned print_interval = 0

When to print progress.

If set to zero, nothing will be printed. If set to N != 0, progress is printed every N iterations.

int print_precision = std::numeric_limits<real_t>::max_digits10 / 2: The precision of the floating point values printed by the solver.

real_t quadratic_upperbound_tolerance_factor = 10 * std::numeric_limits<real_t>::epsilon()

Tolerance factor used in the quadratic upper bound condition that determines the step size.

Its goal is to account for numerical errors in the function and gradient evaluations. If you notice that the step size γ becomes very small, you may want to increase this factor.

real_t TR_tolerance_factor = 10 * std::numeric_limits<real_t>::epsilon()

real_t ratio_threshold_acceptable = real_t(0.2): Minimal TR ratio to be accepted (successful).

real_t ratio_threshold_good = real_t(0.8): Minimal TR ratio to increase radius (very successful).

real_t radius_factor_rejected = real_t(0.35): TR radius decrease coefficient when unsuccessful.

real_t radius_factor_acceptable = real_t(0.999): TR radius decrease coefficient when successful.

real_t radius_factor_good = real_t(2.5): TR radius increase coefficient when very successful.

real_t initial_radius = NaN<config_t>: Initial trust radius.

real_t min_radius = 100 * std::numeric_limits<real_t>::epsilon(): Minimum trust radius.

bool compute_ratio_using_new_stepsize = false: Check the quadratic upperbound and update γ before computing the reduction of the TR step.

bool update_direction_on_prox_step = true

bool recompute_last_prox_step_after_direction_reset = false

bool disable_acceleration = false

Don’t compute accelerated steps, fall back to forward-backward splitting.

For testing purposes.

bool ratio_approx_fbe_quadratic_model = true

Compute the trust-region ratio using an approximation of the quadratic model of the FBE, rather than the quadratic model of the subproblem.

Specifically, when set to false, the quadratic model used is

\[ q(d) = \tfrac12 \inprod{\mathcal R_\gamma(\hat x) d}{d} + \inprod{R_\gamma(\hat x)}{d}. \]

When set to true, the quadratic model used is

\[ q_\mathrm{approx}(d) = \inv{(1-\alpha)} q(d), \]

where \( \alpha = \) LipschitzEstimateParams::Lγ_factor. This is an approximation of the quadratic model of the FBE,

\[ q_{\varphi_\gamma}(d) = \tfrac12 \inprod{\mathcal Q_\gamma(\hat x) \mathcal R_\gamma(\hat x) d}{d} + \inprod{\mathcal Q_\gamma(\hat x) R_\gamma(\hat x)}{d}, \]

with \( \mathcal Q_\gamma(x) = \Id - \gamma \nabla^2 \psi(x) \).

template<Config Conf = DefaultConfig> struct WolfeParams

#include <alpaqa/inner/wolfe.hpp>

Tuning parameters for the unconstrained solver with Wolfe line search.

Public Members

unsigned max_iter = 100: Maximum number of inner iterations.

std::chrono::nanoseconds max_time = std::chrono::minutes(5): Maximum duration.

real_t min_linesearch_coefficient = real_t(1. / 256): Minimum weight factor between Newton step and projected gradient step.

bool force_linesearch = false

Ignore the line search condition and always accept the accelerated step.

(For testing purposes only).

real_t decrease_factor = real_t(1e-4)

real_t curvature_factor = NaN<config_t>

PANOCStopCrit stop_crit = PANOCStopCrit::ApproxKKT: What stopping criterion to use.

unsigned max_no_progress = 10: Maximum number of iterations without any progress before giving up.

unsigned print_interval = 0

When to print progress.

If set to zero, nothing will be printed. If set to N != 0, progress is printed every N iterations.

int print_precision = std::numeric_limits<real_t>::max_digits10 / 2: The precision of the floating point values printed by the solver.

real_t linesearch_tolerance_factor = 10 * std::numeric_limits<real_t>::epsilon()

Tolerance factor used in the line search.

template<Config Conf = DefaultConfig> struct ZeroFPRParams

#include <alpaqa/inner/zerofpr.hpp>

Tuning parameters for the ZeroFPR algorithm.

Public Members

LipschitzEstimateParams<config_t> Lipschitz = {}: Parameters related to the Lipschitz constant estimate and step size.

unsigned max_iter = 100: Maximum number of inner ZeroFPR iterations.

std::chrono::nanoseconds max_time = std::chrono::minutes(5): Maximum duration.

real_t min_linesearch_coefficient = real_t(1. / 256): Minimum weight factor between Newton step and projected gradient step.

bool force_linesearch = false

Ignore the line search condition and always accept the accelerated step.

(For testing purposes only).

real_t linesearch_strictness_factor = real_t(0.95)

Parameter β used in the line search (see Algorithm 2 in [2]).

\( 0 < \beta < 1 \)

real_t L_min = real_t(1e-5): Minimum Lipschitz constant estimate.

real_t L_max = real_t(1e20): Maximum Lipschitz constant estimate.

PANOCStopCrit stop_crit = PANOCStopCrit::ApproxKKT: What stopping criterion to use.

unsigned max_no_progress = 10: Maximum number of iterations without any progress before giving up.

unsigned print_interval = 0

When to print progress.

If set to zero, nothing will be printed. If set to N != 0, progress is printed every N iterations.

int print_precision = std::numeric_limits<real_t>::max_digits10 / 2: The precision of the floating point values printed by the solver.

real_t quadratic_upperbound_tolerance_factor = 10 * std::numeric_limits<real_t>::epsilon()

Tolerance factor used in the quadratic upper bound condition that determines the step size.

Its goal is to account for numerical errors in the function and gradient evaluations. If you notice that the step size γ becomes very small, you may want to increase this factor.

real_t linesearch_tolerance_factor = 10 * std::numeric_limits<real_t>::epsilon()

Tolerance factor used in the line search.

bool update_direction_in_candidate = false: Use the candidate point rather than the accepted point to update the quasi-Newton direction.

bool recompute_last_prox_step_after_stepsize_change = false

If the step size changes, the direction buffer is flushed.

bool update_direction_from_prox_step = false: Update the direction between current forward-backward point and the candidate iterate instead of between the current iterate and the candidate iterate.

template<Config Conf = DefaultConfig> struct ALMParams

#include <alpaqa/outer/alm.hpp>

Parameters for the Augmented Lagrangian solver.

Public Members

real_t tolerance = real_t(1e-5): Primal tolerance (used for stopping criterion of inner solver).

real_t dual_tolerance = real_t(1e-5): Dual tolerance (constraint violation and complementarity).

real_t penalty_update_factor = 10: Factor used in updating the penalty parameters.

real_t initial_penalty = 1

Initial penalty parameter.

When set to zero (which is the default), it is computed automatically, based on the constraint violation in the starting point and the parameter initial_penalty_factor.

real_t initial_penalty_factor = 20

Initial penalty parameter factor.

Active if initial_penalty is set to zero.

real_t initial_tolerance = 1: Initial primal tolerance.

real_t tolerance_update_factor = real_t(1e-1): Update factor for primal tolerance.

real_t rel_penalty_increase_threshold = real_t(0.1): Error tolerance for penalty increase.

real_t max_multiplier = real_t(1e9): Lagrange multiplier bound.

real_t max_penalty = real_t(1e9): Maximum penalty factor.

real_t min_penalty = real_t(1e-9): Minimum penalty factor (used during initialization).

unsigned int max_iter = 100: Maximum number of outer ALM iterations.

std::chrono::nanoseconds max_time = std::chrono::minutes(5): Maximum duration.

unsigned print_interval = 0

When to print progress.

If set to zero, nothing will be printed. If set to N != 0, progress is printed every N iterations.

int print_precision = std::numeric_limits<real_t>::max_digits10 / 2: The precision of the floating point values printed by the solver.

bool single_penalty_factor = false: Use one penalty factor for all m constraints.

struct LBFGSBParams

#include <alpaqa/lbfgsb/lbfgsb-adapter.hpp>

Tuning parameters for the L-BFGS-B solver LBFGSBSolver.

Public Members

unsigned memory = 10

unsigned max_iter = 1000

std::chrono::nanoseconds max_time = std::chrono::minutes(5)

PANOCStopCrit stop_crit = PANOCStopCrit::ProjGradUnitNorm

int print = -1

unsigned print_interval = 0

int print_precision = std::numeric_limits<real_t>::max_digits10 / 2