Consensus Augmented Lagrangian Coordination (Consensus ALC) Pseudocode-to-Code Traceability¶

This page maps each step of the Consensus Augmented Lagrangian Coordination pseudocode to the implementing classes and methods in the codebase.

Highlighted lines are linked to the implementation. Hover or click to see the implementing classes/methods, then click through to the full API documentation.

Algorithm 3 Consensus Augmented Lagrangian Coordination (Consensus ALC)

Require: hyperparameters $\gamma$, $\beta$

Require: initial ${}^{j}_{i}y^{(0)},\; {}^{i}_{j}y^{(0)} \;\; \forall\; j \in {}^{i}N,\; {}^{i}\lambda^{(0)},\; {}^{i}s^{(0)} \;\; \forall\; i \in M$

$k \leftarrow 0$ ▷ initialize outerloop iterator

repeat

$l \leftarrow 0$ ▷ initialize innerloop iterator

repeat ▷ decentralized Primal Update approximation

for every $i \in M$ in parallel do

\begin{aligned} {}^{i}d^{(k,\,l+1)} \leftarrow{} & \argmin_{{}^{i}d \;\in\; {}^{i}\mathcal{D}} \;\; {}^{i}v_f\!\left({}^{i}r\right) \\ & + \sum_{j \in {}^{i}N} \left( \left({}^{i}_{j}\lambda^{i}\right)^{(k)\,T} {}^{i}_{j}c_c^{i}\!\left({}^{i}d,\; {}^{i}_{j}y\right) + \left\|\left({}^{i}_{j}s^{i}\right)^{(k)} \circ {}^{i}_{j}c_c^{i}\!\left({}^{i}d,\; {}^{i}_{j}y\right)\right\|_{2}^{2} \right. \\ & \left. \quad\quad + \left({}^{j}_{i}\lambda^{i}\right)^{(k)\,T} {}^{j}_{i}c_c^{i}\!\left({}^{i}d,\; {}^{j}_{i}y\right) + \left\|\left({}^{j}_{i}s^{i}\right)^{(k)} \circ {}^{j}_{i}c_c^{i}\!\left({}^{i}d,\; {}^{j}_{i}y\right)\right\|_{2}^{2} \right) \\ & \text{s.t.} \;\; {}^{i}v_g\!\left({}^{i}r\right) \leq 0, \\ & \phantom{\text{s.t.}} \;\; {}^{i}v_h\!\left({}^{i}r\right) = 0. \end{aligned}

Copy ${}^{i}_{j}H\!\left({}^{i}r\right),\; {}^{j}_{i}h,\; {}^{i}_{j}z,\; {}^{j}_{i}\lambda^{i},\; {}^{i}_{j}\lambda^{i},\; {}^{j}_{i}s^{i},\; {}^{i}_{j}s^{i}$ to interface storage $i \leftrightarrow j \;\; \forall\; j \in {}^{i}N$

end for

for every $i \in M$ in parallel do

Copy ${}^{j}_{i}H\!\left({}^{j}r\right),\; {}^{i}_{j}h,\; {}^{j}_{i}z,\; {}^{i}_{j}\lambda^{j},\; {}^{j}_{i}\lambda^{j},\; {}^{i}_{j}s^{j},\; {}^{j}_{i}s^{j}$ from interface storage $i \leftrightarrow j \;\; \forall\; j \in {}^{i}N$

\begin{aligned} {}^{i}_{j}y^{(k,\,l+1)} \leftarrow \Biggl( & - \frac{1}{2}\left(\left({}^{i}_{j}\lambda^{i}\right)^{(k)} + \left({}^{i}_{j}\lambda^{j}\right)^{(k)}\right) + \left(\left({}^{i}_{j}s^{i}\right)^{(k)} \circ \left({}^{i}_{j}s^{i}\right)^{(k)}\right) \circ \begin{bmatrix} {}^{i}_{j}H\!\left({}^{i}r\right) \\ {}^{i}_{j}z \end{bmatrix} \\ & + \left(\left({}^{i}_{j}s^{j}\right)^{(k)} \circ \left({}^{i}_{j}s^{j}\right)^{(k)}\right) \circ \begin{bmatrix} {}^{i}_{j}h \\ {}^{j}_{i}z \end{bmatrix} \Biggr) \\ & \oslash \left(\left({}^{i}_{j}s^{i}\right)^{(k)} \circ \left({}^{i}_{j}s^{i}\right)^{(k)} + \left({}^{i}_{j}s^{j}\right)^{(k)} \circ \left({}^{i}_{j}s^{j}\right)^{(k)}\right) \;\;\; \forall\; j \in {}^{i}N \end{aligned}

\begin{aligned} {}^{j}_{i}y^{(k,\,l+1)} \leftarrow \Biggl( & - \frac{1}{2}\left(\left({}^{j}_{i}\lambda^{j}\right)^{(k)} + \left({}^{j}_{i}\lambda^{i}\right)^{(k)}\right) + \left(\left({}^{j}_{i}s^{j}\right)^{(k)} \circ \left({}^{j}_{i}s^{j}\right)^{(k)}\right) \circ \begin{bmatrix} {}^{j}_{i}H\!\left({}^{j}r\right) \\ {}^{j}_{i}z \end{bmatrix} \\ & + \left(\left({}^{j}_{i}s^{i}\right)^{(k)} \circ \left({}^{j}_{i}s^{i}\right)^{(k)}\right) \circ \begin{bmatrix} {}^{j}_{i}h \\ {}^{i}_{j}z \end{bmatrix} \Biggr) \\ & \oslash \left(\left({}^{j}_{i}s^{j}\right)^{(k)} \circ \left({}^{j}_{i}s^{j}\right)^{(k)} + \left({}^{j}_{i}s^{i}\right)^{(k)} \circ \left({}^{j}_{i}s^{i}\right)^{(k)}\right) \;\;\; \forall\; j \in {}^{i}N \end{aligned}

end for

Compute innerloop convergence criterion (e.g., [@dewitUnifiedApproach2009a; @tosseramsDistributedOptimization2008; @guoDistributedAugmented2025])

$l \leftarrow l + 1$

until innerloop convergence criterion is met

${}^{i}d^{(k+1)},\; {}^{i}_{j}y^{(k+1)} \leftarrow {}^{i}d^{(k,\,l)},\; {}^{i}_{j}y^{(k,\,l)} \;\; \forall\; j \in {}^{i}N,\; i \in M$

for every $i \in M$ do ▷ decentralized Dual and Penalty Update

\begin{aligned} \left({}^{i}_{j}c_c^{i}\right)^{(k+1)} &\leftarrow {}^{i}_{j}y^{(k+1)} - \begin{bmatrix} {}^{i}_{j}H\!\left({}^{i}r\right) \\ {}^{i}_{j}S_{z}\,{}^{i}d^{(k+1)} \end{bmatrix}, \\[0.5em] \left({}^{j}_{i}c_c^{i}\right)^{(k+1)} &\leftarrow {}^{j}_{i}y^{(k+1)} - \begin{bmatrix} {}^{j}_{i}S_{h}\,{}^{i}d^{(k+1)} \\ {}^{i}_{j}S_{z}\,{}^{i}d^{(k+1)} \end{bmatrix} \end{aligned}

\begin{aligned} \left({}^{i}_{j}\lambda^{i}\right)^{(k+1)} &\leftarrow \operatorname{DualUpdate}\!\left( \left({}^{i}_{j}\lambda^{i}\right)^{(k)},\; \left({}^{i}_{j}s^{i}\right)^{(k)},\; \left({}^{i}_{j}c_c^{i}\right)^{(k+1)} \right) \quad \forall\; j \in {}^{i}N \\ \left({}^{j}_{i}\lambda^{i}\right)^{(k+1)} &\leftarrow \operatorname{DualUpdate}\!\left( \left({}^{j}_{i}\lambda^{i}\right)^{(k)},\; \left({}^{j}_{i}s^{i}\right)^{(k)},\; \left({}^{j}_{i}c_c^{i}\right)^{(k+1)} \right) \quad \forall\; j \in {}^{i}N \\[0.5em] \left({}^{i}_{j}s^{i}\right)^{(k+1)} &\leftarrow \operatorname{PenaltyUpdate}\!\left( \beta,\; \gamma,\; \left({}^{i}_{j}s^{i}\right)^{(k)},\; \left({}^{i}_{j}c_c^{i}\right)^{(k+1)},\; \left({}^{i}_{j}c_c^{i}\right)^{(k)} \right) \quad \forall\; j \in {}^{i}N \\ \left({}^{j}_{i}s^{i}\right)^{(k+1)} &\leftarrow \operatorname{PenaltyUpdate}\!\left( \beta,\; \gamma,\; \left({}^{j}_{i}s^{i}\right)^{(k)},\; \left({}^{j}_{i}c_c^{i}\right)^{(k+1)},\; \left({}^{j}_{i}c_c^{i}\right)^{(k)} \right) \quad \forall\; j \in {}^{i}N \end{aligned}

end for

Compute outerloop convergence criterion (e.g., [@dewitUnifiedApproach2009a; @tosseramsDistributedOptimization2008])

$k \leftarrow k + 1$

until outerloop convergence criterion is met

return $\left\{{}^{i}d^{(k)}\right\}_{i \in M}$

CouplingParameters and MiddleLevel¶

Algorithm Options / Hyperparameters¶

The Consensus ALC coordination method is selected and configured in the use case InputFile.py by assigning a Consensus_ALC instance to self._coordinationmethod. All algorithmic behaviour is wired through four constructor arguments:

self._coordinationmethod: CoordinationMethodInterface = Consensus_ALC(
    convergence_indicator_innerloop=ConvergenceIndicator_Innerloop_DeWit(
        tolerancetotalobjective=1000.0),
    convergence_indicator_outerloop=ConvergenceIndicator_Outerloop_DeWit(
        toleranceconsistency=1E-4),
    updatecouplingparametermethod_outerloop=UpdateCouplingParameterMethod_AugLagMultipliersAdaptiveWeights(
        beta=1.3,
        gamma=0.25,
        initialweight=0.01,
        initialmultiplier=0.0),
    iterationscheme=Parallel())

Like ALC, Consensus ALC relaxes constraints with a subgradient dual/penalty scheme, but it relaxes the consensus constraints $c_c$ (introduced by the auxiliary variables $y$) instead of the coupling constraints $c$. The four constructor arguments are therefore identical in role to ALC; the differences are internal to the primal inner loop (see the auxiliary-variable update below).

Convergence criteria¶

Consensus ALC uses a nested inner/outer loop (Algorithm 4 in Consensus ALC), so two convergence indicators are configured:

Inner loop — convergence_indicator_innerloop, evaluated by SubSystemBasis.evaluate_InnerLoopConvergenceIndicator. Consensus ALC requires ConvergenceIndicator_Innerloop_DeWit, which converges on the relative change of the total objective, $\text{error} = |v_f^{\text{new}} - v_f^{\text{old}}| / (1 + |v_f^{\text{new}}|) \le$ tolerancetotalobjective. A smaller tolerancetotalobjective forces more inner FPI sweeps (each alternating the $d$ and $y$ updates) per outer step; a larger value (e.g. 1000.0) terminates the inner loop earlier and shifts most of the work onto the outer dual and penalty updates.
Outer loop — convergence_indicator_outerloop, evaluated by SubSystemBasis.evaluate_OuterLoopConvergenceIndicator. Consensus ALC requires ConvergenceIndicator_Outerloop_DeWit, which terminates once all consensus inconsistencies $c_c = \left(y - [{}^{i}_{j}H({}^{i}r);\, {}^{i}_{j}z],\ldots\right)$ and their step-to-step changes fall within toleranceconsistency. A smaller toleranceconsistency (e.g. 1E-4) enforces tighter consensus between coupled subsystems at the cost of more outer iterations.

Both indicators are validated in LocalSubSystemConsensusALC, which restricts Consensus ALC to the DeWit inner/outer indicators.

Update method (dual and penalty update)¶

updatecouplingparametermethod_outerloop implements the Consensus ALC dual and penalty update, applied by LocalSubSystemConsensusALC.updateCouplingParameters_outerLoop. Consensus ALC requires the adaptive-weight augmented-Lagrangian method UpdateCouplingParameterMethod_AugLagMultipliersAdaptiveWeights, which advances the multipliers by the subgradient step $\lambda \leftarrow \lambda + 2\,s \circ s \circ c_c$ (update_CoordinationMultipliers) and adapts the penalty weights $s$ (update_CoordinationWeights) — the same rule as ALC but evaluated on the consensus residual $c_c$:

initialweight — the initial penalty weight $s$ (recommended $0 < s \le 0.1$, e.g. 0.01). Larger initialweight produces larger multiplier steps and faster constraint enforcement, but risks oscillation/ill-conditioning; smaller values give gentler, more stable but slower consensus.
initialmultiplier — the initial Lagrange multiplier ${}^{i}_{j}\lambda^{(0)}$ (recommended 0.0).

Auxiliary (consensus) variable update¶

The consensus reformulation adds the auxiliary variables $y$, which are optimized inside the inner loop alongside the $d$ step. Because the $y$ subproblem is an unconstrained convex QP (for $s^{(k)} \neq 0$), it has a closed-form solution that each subsystem evaluates locally in LocalSubSystemConsensusALC.update_AuxiliaryVariables (invoked via updateCouplingParameters_innerLoop), eliminating a dedicated controller at the cost of duplicated work but reduced communication. The resulting $y$ values are stored per coupling in CouplingParametersConsensusALC. This step is not user-configurable; it is governed only by the current weights $s$ and multipliers $c$ or $c_c$">$\lambda$.

Iteration scheme¶

iterationscheme controls how the inner-loop primal updates are scheduled by the IterationSchemeInterface. Consensus ALC has no dedicated controller — the $d$ step is fully parallel and alternates with the local $y$ update in an FPI, so the choice selects the fixed-point sweep:

Parallel — a Jacobi sweep: all subsystem problems are solved simultaneously from the previous iterate.
SequentialForward / SequentialBackward — a Gauss–Seidel sweep: subsystems are solved one after another, each using the latest neighbour data (often faster convergence, no parallelism).

Penalty hyperparameters β, γ, s¶

The pseudocode "Require" block (Algorithm 4, lines 1–2) lists the penalty-adaption hyperparameters $\beta$ and $\gamma$, alongside the initial auxiliary variables $y$, penalty weights $s$ and multipliers $c$ or $c_c$">$\lambda$. $\beta$ and $\gamma$ are passed to the update method above and govern the penalty update $s^{(k+1)} \leftarrow \beta\,s^{(k)}$ applied only when $|c_c^{(k+1)}| > \gamma\,|c_c^{(k)}|$:

$\beta$ — the penalty-weight increase factor (must satisfy $\beta > 1$, recommended $\beta \le 3$, e.g. 1.3). A larger $\beta$ grows the weights more aggressively when consensus stalls (stronger constraint enforcement, but risk of ill-conditioning and oscillation); a value closer to 1 grows them gently (more stable, slower consensus).
$\gamma$ — the inconsistency-reduction threshold (must satisfy $0 < \gamma < 1$, e.g. 0.25). The weights are only increased when the inconsistency fails to shrink below a factor $\gamma$ of the previous step. A smaller $\gamma$ demands a larger per-iteration reduction before the weights are held constant, so penalties grow more often; a value closer to 1 tolerates slow reduction and increases penalties rarely.

The corresponding weights $s$, multipliers $c$ or $c_c$">$\lambda$ and auxiliary variables $y$ are stored per coupling in CouplingParametersConsensusALC, while $\beta$ and $\gamma$ are held on the Consensus_ALC coordination method.