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

This page maps each step of the Augmented Lagrangian Coordination (ALC) 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 2 Augmented Lagrangian Coordination (ALC)

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

Require: initial \({}^{j}_{i}H\!\left({}^{j}r\right),\; {}^{i}_{j}h,\; {}^{j}_{i}z\) in interface storage \(i \leftrightarrow j \;\; \forall\; j \in {}^{i}N,\; i \in M\)

Require: initial \({}^{i}_{j}\lambda^{(0)},\; {}^{i}_{j}s^{(0)} \;\; \forall\; j \in {}^{i}N,\; 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 sequence or parallel do

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

\[\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^{(k)}\right)^{T} \begin{bmatrix} {}^{i}_{j}H\!\left({}^{i}r\right) - {}^{i}_{j}h \\ {}^{i}_{j}S_{z}\,{}^{i}d - {}^{j}_{i}z \end{bmatrix} + \left\|{}^{i}_{j}s^{(k)} \circ \begin{bmatrix} {}^{i}_{j}H\!\left({}^{i}r\right) - {}^{i}_{j}h \\ {}^{i}_{j}S_{z}\,{}^{i}d - {}^{j}_{i}z \end{bmatrix} \right\|_{2}^{2} \right. \\ & \left. \quad\quad + \left({}^{j}_{i}\lambda^{(k)}\right)^{T} \begin{bmatrix} {}^{j}_{i}H\!\left({}^{j}r\right) - {}^{j}_{i}S_{h}\,{}^{i}d \\ {}^{j}_{i}z - {}^{i}_{j}S_{z}\,{}^{i}d \end{bmatrix} + \left\|{}^{j}_{i}s^{(k)} \circ \begin{bmatrix} {}^{j}_{i}H\!\left({}^{j}r\right) - {}^{j}_{i}S_{h}\,{}^{i}d \\ {}^{j}_{i}z - {}^{i}_{j}S_{z}\,{}^{i}d \end{bmatrix} \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\) to interface storage \(i \leftrightarrow j \;\; \forall\; j \in {}^{i}N\)

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)} \leftarrow {}^{i}d^{(k,\,l)} \;\forall\; i \in M\)

 

for every \(i \in M\) in parallel do ▷ decentralized Dual and Penalty Update

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

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

\[\begin{aligned} {}^{i}_{j}\lambda^{(k+1)} &\leftarrow \operatorname{DualUpdate}\!\left( {}^{i}_{j}\lambda^{(k)},\; {}^{i}_{j}s^{(k)},\; {}^{i}_{j}c^{(k+1)} \right) \quad \forall\; j \in {}^{i}N \\ {}^{j}_{i}\lambda^{(k+1)} &\leftarrow \operatorname{DualUpdate}\!\left( {}^{j}_{i}\lambda^{(k)},\; {}^{j}_{i}s^{(k)},\; {}^{j}_{i}c^{(k+1)} \right) \quad \forall\; j \in {}^{i}N \\[0.5em] {}^{i}_{j}s^{(k+1)} &\leftarrow \operatorname{PenaltyUpdate}\!\left( \beta,\; \gamma,\; {}^{i}_{j}s^{(k)},\; {}^{i}_{j}c^{(k+1)},\; {}^{i}_{j}c^{(k)} \right) \quad \forall\; j \in {}^{i}N \\ {}^{j}_{i}s^{(k+1)} &\leftarrow \operatorname{PenaltyUpdate}\!\left( \beta,\; \gamma,\; {}^{j}_{i}s^{(k)},\; {}^{j}_{i}c^{(k+1)},\; {}^{j}_{i}c^{(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 ALC coordination method is selected and configured in the use case InputFile.py by assigning an ALC instance to self._coordinationmethod. All algorithmic behaviour is wired through four constructor arguments:

self._coordinationmethod: CoordinationMethodInterface = ALC(
    convergence_indicator_innerloop=ConvergenceIndicator_Innerloop_DeWit(
        tolerancetotalobjective=1E-5),
    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())

Convergence criteria

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

• Inner loop — convergence_indicator_innerloop, evaluated by SubSystemBasis.evaluate_InnerLoopConvergenceIndicator. 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 (e.g. 1E-5) forces more inner FPI sweeps per outer step (tighter primal-update fixed point); a larger value 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. ALC requires ConvergenceIndicator_Outerloop_DeWit, which terminates once all coupling inconsistencies \(c = \left({}^{i}_{j}H({}^{i}r) - {}^{i}_{j}h,\; {}^{i}_{j}z - {}^{j}_{i}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 LocalSubSystemALC (validate_inputs), which restricts ALC to the DeWit inner/outer indicators.

Update method (dual and penalty update)

updatecouplingparametermethod_outerloop implements the ALC dual and penalty update (pseudocode lines 19–20), applied by LocalSubSystemALC.updateCouplingParameters_outerLoop. 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\) (update_CoordinationMultipliers) and adapts the penalty weights \(s\) (update_CoordinationWeights):

• 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).

Iteration scheme

iterationscheme controls how the inner-loop primal updates are scheduled by the IterationSchemeInterface. ALC has no controller — the primal problem is solved distributedly by an FPI scheme, so the choice selects the fixed-point sweep:

• Parallel — a Jacobi sweep: all subsystem problems (pseudocode line 10) 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 1, lines 1–3) lists the penalty-adaption hyperparameters \(\beta\) and \(\gamma\), alongside the initial 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^{(k+1)}| > \gamma\,|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\) and multipliers \(c\) or \(c_c\)">\(\lambda\) are stored per coupling in CouplingParametersALC, while \(\beta\) and \(\gamma\) are held on the ALC coordination method.