Solvers¶

This page is a sparse map of the solver families exposed by PYDGENS. It is not yet a full theory guide.

Linear-Quadratic Games¶

The LQ path solves finite-horizon linear-quadratic dynamic games for feedback Nash strategies.

Used by:

• tug_o_war.py
• satellite_lady_bandit_guard.py

Theory notes:

• TODO: summarize finite-horizon coupled Riccati/backward-recursion structure.
• TODO: document sign conventions and frontend-to-IR quadratic scaling.
• References: Dynamic Noncooperative Game Theory, Feedback LQ Nash Derivation.

Iterative Linear-Quadratic Games¶

The iLQ path repeatedly builds local linear-quadratic approximations of a nonlinear game and solves those approximations for local feedback Nash updates.

The iLQ solver accepts scalar or per-state-component absolute bounds for both its convergence check (converged_max_diff) and backtracking rollout check (backtrack_scale_max_diff). Supplying a vector of length nx is useful for mixed-unit states, for example separate position and heading tolerances.

Iterative solvers accept diagnostics_level="off", "basic", or "detailed". This controls retained diagnostics rather than logger configuration: solver loggers emit compact renderings of retained records only when the caller has independently enabled the corresponding logging level. For iLQ, each basic iteration record includes the raw state-update infinity norm, its componentwise convergence-tolerance-normalized infinity norm, and the numeric time-node and state-index location of that normalized maximum. With diagnostics_level="detailed", iLQ also records per-player nonlinear costs before and after each rollout, the local LQ model's predicted cost change, and cost_change_ratio: actual signed cost change divided by predicted signed cost change. A ratio of one indicates exact agreement whether a player's cost increases or decreases; it is None only for exactly zero predicted change. These are model-agreement observations only; they do not alter backtracking or step acceptance.

Detailed iLQ records also include a feedback-aligned, per-player control-stationarity residual: the root-mean-square L2 norm of the nonlinear total-cost gradient with respect to additive, stage-indexed deviations to that player's current affine feedback policy. All feedback gains remain active during the perturbed rollout, so other players' future controls respond to the resulting state changes. Each record reports its ratio to the residual at the propagated initial strategy. These relative values measure progress and are used to identify the best-stationarity iterate by their maximum across players with nonzero initial residuals. A player with a zero initial residual reports None for relative progress rather than an undefined infinite ratio; its raw residual remains available. These are not absolute convergence tolerances. Worst-coordinate fields remain based on the largest absolute gradient component.

Used by:

• unicycle.py
• multi_car_intersection.py

Theory notes:

• TODO: summarize local game approximation, feedback update, and line-search behavior.
• TODO: clarify convergence diagnostics and failure modes.
• References: iLQGames, Smooth Game Theory.

Augmented-Lagrangian Games¶

The AL path targets constrained nonlinear games with local open-loop trajectories. This solver path is currently beta/pre-release.

Used by:

• constrained_integrators.py

Theory notes:

• TODO: document the augmented-Lagrangian state, multiplier updates, and regularization strategy.
• TODO: explain which constraints are currently supported by the frontend.
• Reference: ALGAMES.