C++ API Reference#

namespace alpaqa#

Typedefs

using real_t = double#: Default floating point type.

using realvec = Eigen::Matrix<real_t, Eigen::Dynamic, 1>#: Default type for floating point vectors.

using realmat = Eigen::Matrix<real_t, Eigen::Dynamic, Eigen::Dynamic>#: Default type for floating point matrices.

using vec = realvec #: Default type for vectors.

using rvec = Eigen::Ref<vec>#: Default type for mutable references to vectors.

using crvec = Eigen::Ref<const vec>#: Default type for immutable references to vectors.

using mat = realmat #: Default type for matrices.

using rmat = Eigen::Ref<mat>#: Default type for mutable references to matrices.

using crmat = Eigen::Ref<const mat>#: Default type for immutable references to matrices.

using dim = std::pair<casadi_int, casadi_int>#

Enums

enum class LBFGSStepSize#

Which method to use to select the L-BFGS step size.

Values:

enumerator BasedOnGradientStepSize#

enumerator BasedOnCurvature#

enum class PANOCStopCrit#

Values:

enumerator ApproxKKT#

Find an ε-approximate KKT point in the ∞-norm:

\[ \varepsilon = \left\| \gamma_k^{-1} (x^k - \hat x^k) + \nabla \psi(\hat x^k) - \nabla \psi(x^k) \right\|_\infty \]

enumerator ApproxKKT2#

Find an ε-approximate KKT point in the 2-norm:

\[ \varepsilon = \left\| \gamma_k^{-1} (x^k - \hat x^k) + \nabla \psi(\hat x^k) - \nabla \psi(x^k) \right\|_2 \]

enumerator ProjGradNorm#

∞-norm of the projected gradient with step size γ:

\[ \varepsilon = \left\| x^k - \Pi_C\left(x^k - \gamma_k \nabla \psi(x^k)\right) \right\|_\infty \]

enumerator ProjGradNorm2#

2-norm of the projected gradient with step size γ:

\[ \varepsilon = \left\| x^k - \Pi_C\left(x^k - \gamma_k \nabla \psi(x^k)\right) \right\|_2 \]

This is the same criterion as used by OpEn.

enumerator ProjGradUnitNorm#

∞-norm of the projected gradient with unit step size:

\[ \varepsilon = \left\| x^k - \Pi_C\left(x^k - \nabla \psi(x^k)\right) \right\|_\infty \]

enumerator ProjGradUnitNorm2#

2-norm of the projected gradient with unit step size:

\[ \varepsilon = \left\| x^k - \Pi_C\left(x^k - \nabla \psi(x^k)\right) \right\|_2 \]

enumerator FPRNorm#

∞-norm of fixed point residual:

\[ \varepsilon = \gamma_k^{-1} \left\| x^k - \Pi_C\left(x^k - \gamma_k \nabla \psi(x^k)\right) \right\|_\infty \]

enumerator FPRNorm2#

2-norm of fixed point residual:

\[ \varepsilon = \gamma_k^{-1} \left\| x^k - \Pi_C\left(x^k - \gamma_k \nabla \psi(x^k)\right) \right\|_2 \]

enumerator Ipopt#

The stopping criterion used by Ipopt, see https://link.springer.com/article/10.1007/s10107-004-0559-y equation (5).

Given a candidate iterate \( \hat x^k \) and the corresponding candidate Lagrange multipliers \( \hat y^k \) for the general constraints \( g(x)\in D \), the multipliers \( w \) for the box constraints \( x\in C \) (that are otherwise not computed explicitly) are given by

\[ w^k = v^k - \Pi_C(v^k), \]

where

\[\begin{split} \begin{aligned} v^k &\triangleq \hat x^k - \nabla f(\hat x^k) - \nabla g(\hat x^k)\, \hat y^k \\ &= \hat x^k - \nabla \psi(\hat x^k) \end{aligned} \end{split}\]

The quantity that is compared to the (scaled) tolerance is then given by

\[\begin{split} \begin{aligned} \varepsilon' &= \left\| \nabla f(\hat x^k) + \nabla g(\hat x^k)\, \hat y^k + w^k \right\|_\infty \\ &= \left\| \hat x^k - \Pi_C\left(v^k\right) \right\|_\infty \end{aligned} \end{split}\]

Finally, the quantity is scaled by the factor

\[ s_d \triangleq \max\left\{ s_\text{max},\;\frac{\|\hat y^k\|_1 + \|w^k\|_1}{2m + 2n} \right\} / s_\text{max}, \]

i.e. \( \varepsilon = \varepsilon' / s_d \).

enum class SolverStatus#

Exit status of a numerical solver such as ALM or PANOC.

Values:

enumerator Unknown#: Initial value.

enumerator Converged#: Converged and reached given tolerance.

enumerator MaxTime#: Maximum allowed execution time exceeded.

enumerator MaxIter#: Maximum number of iterations exceeded.

enumerator NotFinite#: Intermediate results were infinite or not-a-number.

enumerator NoProgress#: No progress was made in the last iteration.

enumerator Interrupted#: Solver was interrupted by the user.

Functions

inline const char *enum_name(PANOCStopCrit s)#

inline std::ostream &operator<<(std::ostream &os, PANOCStopCrit s)#

inline InnerStatsAccumulator<PANOCStats> &operator+=(InnerStatsAccumulator<PANOCStats> &acc, const PANOCStats &s)#

inline InnerStatsAccumulator<SecondOrderPANOCSolver::Stats> &operator+=(InnerStatsAccumulator<SecondOrderPANOCSolver::Stats> &acc, const SecondOrderPANOCSolver::Stats &s)#

inline InnerStatsAccumulator<StructuredPANOCLBFGSStats> &operator+=(InnerStatsAccumulator<StructuredPANOCLBFGSStats> &acc, const StructuredPANOCLBFGSStats &s)#

inline void minimize_update_anderson(LimitedMemoryQR &qr, rmat G, crvec rₖ, crvec rₖ₋₁, crvec gₖ, rvec γ_LS, rvec xₖ_aa)#

Solve one step of Anderson acceleration to find a fixed point of a function g(x):

\( g(x^\star) - x^\star = 0 \)

Updates the QR factorization of \( \mathcal{R}_k = QR \), solves the least squares problem to find \( \gamma_\text{LS} \), computes the next iterate \( x_{k+1} \), and stores the current function value \( g_k \) in the matrix \( G \), which is used as a circular buffer.

\[\begin{split} \begin{aligned} \mathcal{R}_k &= \begin{pmatrix} \Delta r_{k-m_k} & \dots & \Delta r_{k-1} \end{pmatrix} \in \mathbb{R}^{n\times m_k} \\ \Delta r_i &= r_{i+1} - r_i \\ r_i &= g_i - x_i \\ g_i &= g(x_i) \\ \DeclareMathOperator*{\argmin}{argmin} \gamma_\text{LS} &= \argmin_\gamma \left\| \mathcal{R}_k \gamma - r_k \right\|_2 \\ \alpha_i &= \begin{cases} \gamma_\text{LS}[0] & i = 0 \\ \gamma_\text{LS}[i] - \gamma_\text{LS}[i-1] & 0 < i < m_k \\ 1 - \gamma_\text{LS}[m_k - 1] & i = m_k \end{cases} \\ x_{k+1} &= \sum_{i=0}^{m_k} \alpha_i\,g_i \end{aligned} \end{split}\]

inline InnerStatsAccumulator<GAAPGASolver::Stats> &operator+=(InnerStatsAccumulator<GAAPGASolver::Stats> &acc, const GAAPGASolver::Stats &s)#

inline InnerStatsAccumulator<LBFGSBStats> &operator+=(InnerStatsAccumulator<LBFGSBStats> &acc, const LBFGSBStats &s)#

inline InnerStatsAccumulator<PGASolver::Stats> &operator+=(InnerStatsAccumulator<PGASolver::Stats> &acc, const PGASolver::Stats &s)#

alpaqa::Problem load_CasADi_problem(const std::string &filename, unsigned n = 0, unsigned m = 0, bool second_order = false)#

Load a problem generated by CasADi (without parameters).

The file should contain functions with the names f, grad_f, g and grad_g. These functions evaluate the objective function, its gradient, the constraints, and the constraint gradient times a vector respecitvely. If second_order is true, additional functions hess_L and hess_L_prod should be provided to evaluate the Hessian of the Lagrangian and Hessian-vector products.

If any of the dimensions are zero, they are determined from the g function in the given file.

Parameters

filename – Filename of the shared library to load the functions from.
n – Number of decision variables ( \( x \in \mathbb{R}^n \)).
m – Number of general constraints ( \( g(x) \in \mathbb{R}^m \)).
second_order – Load the additional functions required for second-order PANOC.

Throws

std::invalid_argument – The dimensions of the loaded functions do not match.

ProblemWithParam load_CasADi_problem_with_param(const std::string &filename, unsigned n = 0, unsigned m = 0, unsigned p = 0, bool second_order = false)#

Load a problem generated by CasADi (with parameters).

If any of the dimensions are zero, they are determined from the g function in the given file.

Parameters

filename – Filename of the shared library to load the functions from.
n – Number of decision variables ( \( x \in \mathbb{R}^n \)).
m – Number of general constraints ( \( g(x) \in \mathbb{R}^m \)).
p – The number of parameters of the problem (second argument to all CasADi functions).
second_order – Load the additional functions required for second-order PANOC.

Throws

std::invalid_argument – The dimensions of the loaded functions do not match.

template<class ObjFunT, class ObjGradFunT, class DirectionT> inline PANOCStats panoc_impl(ObjFunT &ψ, ObjGradFunT &grad_ψ, const Box &C, rvec x, real_t ε, const PANOCParams &params, vec_allocator &alloc, DirectionT &direction_provider)#

template<class DirectionProviderT = LBFGS, class ObjFunT, class ObjGradFunT> PANOCStats panoc(ObjFunT &ψ, ObjGradFunT &grad_ψ, const Box &C, rvec x, real_t ε, const PANOCParams &params, PANOCDirection<DirectionProviderT> direction, vec_allocator &alloc)#

template<class DirectionProviderT = LBFGS, class ObjFunT, class ObjGradFunT> PANOCStats panoc(ObjFunT &ψ, ObjGradFunT &grad_ψ, const Box &C, rvec x, real_t ε, const PANOCParams &params, PANOCDirection<DirectionProviderT> direction)#

template<class Vec> inline auto project(const Vec &v, const Box &box)#

Project a vector onto a box.

\[ \Pi_C(v) \]

Parameters

v – [in] The vector to project
box – [in] The box to project onto

template<class Vec> inline auto projecting_difference(const Vec &v, const Box &box)#

Get the difference between the given vector and its projection.

\[ v - \Pi_C(v) \]

Warning

Beware catastrophic cancellation!

Parameters

v – [in] The vector to project
box – [in] The box to project onto

inline real_t dist_squared(crvec v, const Box &box)#

Get the distance squared between the given vector and its projection.

\[ \left\| v - \Pi_C(v) \right\|_2^2 \]

Warning

Beware catastrophic cancellation!

Parameters

v – [in] The vector to project
box – [in] The box to project onto

inline real_t dist_squared(crvec v, const Box &box, crvec Σ)#

Get the distance squared between the given vector and its projection in the Σ norm.

\[ \left\| v - \Pi_C(v) \right\|_\Sigma^2 = \left(v - \Pi_C(v)\right)^\top \Sigma \left(v - \Pi_C(v)\right) \]

Warning

Beware catastrophic cancellation!

Parameters

v – [in] The vector to project
box – [in] The box to project onto
Σ – [in] Diagonal matrix defining norm

inline EvalCounter &operator+=(EvalCounter &a, const EvalCounter &b)#

inline EvalCounter::EvalTimer &operator+=(EvalCounter::EvalTimer &a, const EvalCounter::EvalTimer &b)#

inline EvalCounter operator+(EvalCounter a, const EvalCounter &b)#

template<class F> auto wrap_load(const std::string &so_name, const char *name, F f)#

template<class T, class ...Args> auto wrapped_load(const std::string &so_name, const char *name, Args&&... args)#

const char *enum_name(SolverStatus s)#

std::ostream &operator<<(std::ostream &os, SolverStatus s)#

Variables

constexpr size_t panoc_min_alloc_size = 10#

constexpr real_t inf = std::numeric_limits<real_t>::infinity()#: \( \infty \)

constexpr real_t NaN = std::numeric_limits<real_t>::quiet_NaN()#: Not a number.

static constexpr auto dims = [](auto... a) {return std::array<casadi_int, sizeof...(a)>{a...};}#

struct ALMParams#

#include <alpaqa/decl/alm.hpp>

Parameters for the Augmented Lagrangian solver.

Public Members

real_t ε = 1e-5#: Primal tolerance.

real_t δ = 1e-5#: Dual tolerance.

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

real_t Δ_lower = 0.8#: Factor to reduce ALMParams::Δ when inner convergence fails.

real_t Σ₀ = 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 ALMParams::σ₀.

real_t σ₀ = 20#

Initial penalty parameter factor.

Active if ALMParams::Σ₀ is set to zero.

real_t Σ₀_lower = 0.6#: Factor to reduce the initial penalty factor by if convergence fails in in the first iteration.

real_t ε₀ = 1#: Initial primal tolerance.

real_t ε₀_increase = 1.1#: Factor to increase the initial primal tolerance if convergence fails in the first iteration.

real_t ρ = 1e-1#: Update factor for primal tolerance.

real_t ρ_increase = 2#: Factor to increase the primal tolerance update factor by if convergence fails.

real_t θ = 0.1#: Error tolerance for penalty increase.

real_t M = 1e9#: Lagrange multiplier bound.

real_t Σ_max = 1e9#: Maximum penalty factor.

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

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

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

unsigned max_num_initial_retries = 20#: How many times can the initial penalty ALMParams::Σ₀ or ALMParams::σ₀ and the initial primal tolerance ALMParams::ε₀ be reduced.

unsigned max_num_retries = 20#: How many times can the penalty update factor ALMParams::Δ and the primal tolerance factor ALMParams::ρ be reduced.

unsigned max_total_num_retries = 40#: Combined limit for ALMParams::max_num_initial_retries and ALMParams::max_num_retries.

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.

bool preconditioning = false#: Apply preconditioning to the problem, based on the gradients in the starting point.

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

template<class InnerSolverT = PANOCSolver<>> class ALMSolver#

#include <alpaqa/decl/alm.hpp>

Augmented Lagrangian Method solver.

Public Types

using Params = ALMParams #

using InnerSolver = InnerSolverT #

Public Functions

inline ALMSolver(Params params, InnerSolver &&inner_solver)#

inline ALMSolver(Params params, const InnerSolver &inner_solver)#

Stats operator()(const Problem &problem, rvec y, rvec x)#

inline std::string get_name() const#

inline void stop()#

Abort the computation and return the result so far.

Can be called from other threads or signal handlers.

inline const Params &get_params() const#

Public Members

InnerSolver inner_solver#

struct Stats#

#include <alpaqa/decl/alm.hpp>

Public Members

unsigned outer_iterations = 0#

Total number of outer ALM iterations (i.e.

the number of times that the inner solver was invoked).

std::chrono::microseconds elapsed_time#: Total elapsed time.

unsigned initial_penalty_reduced = 0#

The number of times that the initial penalty factor was reduced by ALMParams::Σ₀_lower and that the initial tolerance was increased by ALMParams::ε₀_increase because the inner solver failed to converge in the first ALM iteration.

If this number is greater than zero, consider lowering the initial penalty factor ALMParams::Σ₀ or ALMParams::σ₀ or increasing the initial tolerance ALMParams::ε₀ (or both).

unsigned penalty_reduced = 0#

The number of times that the penalty update factor ALMParams::Δ was reduced, that the tolerance update factor ALMParams::ρ was increased, and that an ALM iteration had to be restarted with a lower penalty factor and a higher tolerance because the inner solver failed to converge (not applicable in the first ALM iteration).

If this number is greater than zero, consider lowerering the penalty update factor ALMParams::Δ or increasing the tolerance update factor (or both). Lowering the initial penalty factor could help as well.

unsigned inner_convergence_failures = 0#: The total number of times that the inner solver failed to converge.

real_t ε = inf #: Final primal tolerance that was reached, depends on the stopping criterion used by the inner solver, see for example PANOCStopCrit.

real_t δ = inf #

Final dual tolerance or constraint violation that was reached:

\[ \delta = \| \Pi_D\left(g(x^k) + \Sigma^{-1}y\right) \|_\infty \]

real_t norm_penalty = 0#: 2-norm of the final penalty factors \( \| \Sigma \|_2 \).

SolverStatus status = SolverStatus::Unknown #

Whether the solver converged or not.