Skip to article frontmatterSkip to article content
Site not loading correctly?

This may be due to an incorrect BASE_URL configuration. See the MyST Documentation for reference.

Constrained

The constrained module in GTSAM provides constrained nonlinear optimization on top of factor graphs. It includes classes for representing constraints, building constrained problems, and solving them with penalty and augmented Lagrangian methods.

Core Problem Model

Equality Constraints

Inequality Constraints

QP and QCQP Problems

D=1 QCQP vectors carry no homogenizing coordinate. Affine terms are stated directly: as linear and constant terms of a QpCost, as the linear term of a QuadraticConstraint, or as the right-hand side of a LinearConstraint. The lifted SDP adds the constant 1 once per PSD block instead.

The leading factor of 1/2 in row-space QpCost construction is intentional: it follows GTSAM’s standard factor-error convention. To represent a QCQP objective written without the 1/2, pass twice the row-space Q blocks to QpCost.

The rotation conversion has two tracks. Rot2 at D=1 uses the exact minimal lift [cos⁡θ,sin⁡θ]⊤[\cos\theta,\sin\theta]^\top and supports a sign-pinning hard prior. The identities r01=−r10r_{01}=-r_{10} and r11=r00r_{11}=r_{00} are structural, so its SDP block has order 3 rather than 5, counting the constant entry. At D>=N, Rot2 (D>=2) and Rot3 (D>=3) use row-Stiefel variables satisfying XX⊤=IXX^\top=I. Between costs have a common right-O(D)O(D) gauge. Matrix-form priors are intentionally unsupported: a fixed target ∥X−[M⊤  0]∥F2\|X-[M^\top\;0]\|_F^2 breaks that gauge and cannot be represented by the Burer--Monteiro Gram matrix alone. A future BM-compatible lowering can introduce an anchor block and use the invariant cost ∥X−M⊤Xanchor∥F2\|X-M^\top X_{\mathrm{anchor}}\|_F^2. The Stiefel constraints do not enforce determinant +1, so square variables also admit reflections. Unsupported factors throw from NonlinearFactor::qcqpFactors.

Optimizers

How the Pieces Fit Together

For a new user, it helps to think in two phases:

  1. Build a constrained problem.

  2. Run a constrained solver on that problem.

Inequality constraints can use different smooth penalty shapes via InequalityPenaltyFunction (ramp, smooth polynomial ramps, or softplus), which controls behavior near the active constraint boundary in PenaltyOptimizer. AugmentedLagrangianOptimizer instead requires exact PHR inequality terms and rejects custom smooth penalties so its projected multiplier update remains mathematically consistent.

Both ALM frontends share one internal engine for penalty and multiplier updates, LM damping, diagnostics and stopping. AugmentedLagrangianSolver accepts native Gaussian graphs and VectorValues; AugmentedLagrangianOptimizer supplies nonlinear function evaluations, Jacobians and manifold retraction. Each call retains one Gaussian step graph and damped multifrontal workspace, with an ordering and symbolic structure reused across outer iterations. A standalone nonlinear iterate() call creates its own workspace.

The Gaussian adapter copies objective coefficient storage once, shifts only RHS/linear terms, and updates augmented constraint coefficients when penalties or PHR activity change. The nonlinear adapter reuses each original linearization for its step and stationarity tests. Inactive PHR rows retain zero Jacobians and their factor slots. Original whitened residuals supply outer diagnostics and projected multipliers directly. On terminal BCL convergence, those multipliers agree with the reported stationarity.

lmParams supplies damping, ordering, multifrontal settings and iteration limits. Numerical elimination is repeated for attempted inner solves; numerical factor reuse is not implemented. Stable model reduction uses gradient/Hessian products; a trial-gradient check handles roundoff-sized merit differences. Native ALM convergence does not include an absolute QP gap test. See the Gaussian solver guide for a small driver, multiplier units, counters and profiling.

The BCL inner stationarity schedule is bounded below by absoluteStationarityTolerance. This lets feasibility updates continue without demanding inner accuracy beyond the requested final tolerance.

timeAugmentedLagrangianPolicies --warmup 3 --repeats 21 benchmarks the policy examples and sparse inequality chains with 512 and 2,048 variables, reporting time, iteration counts, success, and final KKT residuals.

1) Build the Problem

This stage is about modeling: you separate what you want to minimize (objective terms) from what must hold (constraints), then combine them into a single ConstrainedOptProblem object that the solvers can consume.

2) Solve the Problem

This stage is algorithmic: pick a constrained solver, form iterative unconstrained subproblems internally, and solve those subproblems with a standard nonlinear optimizer until constraint violation and cost are reduced.