PEP API

Optimal Step Size

oars.pep.getContractionOptGamma(Z, W, ls=None, mus=None, operators=None, alpha=1, scaling=1.0, verbose=False)[source]

Use the dual PEP to get the optimal step size gamma for the resolvent splitting method given by equation (12) in the paper, i.e. where step 2 is given by \(v = v - \gamma W x\)

Parameters:

  • Z (ndarray) – Z matrix n x n numpy array

  • W (ndarray) – W matrix n x n numpy array

  • ls (list) – size n numpy array of Lipschitz constants

  • mus (list) – size n numpy array of strong convexity parameters where mu[i] < l[i]

  • operators (list) – list of proximal operators

  • alpha (float) – proximal scaling parameter

  • verbose (bool) – verbose output

Returns:

  • tau (float) – contraction factor using the optimal step size

  • gamma (float) – optimal step size

Reduced Optimal Step Size

oars.pep.getReducedContractionOptGamma(Z, M, ls=None, mus=None, operators=None, alpha=1, scaling=1.0, verbose=False)[source]

Use the dual PEP to get the optimal step size gamma for the reduced resolvent splitting method given by equation (11) in the paper, i.e. where step 2 is given by \(z = z + \gamma M x\)

Parameters:

  • Z (ndarray) – Z matrix n x n numpy array

  • M (ndarray) – M matrix d x n numpy array

  • ls (list) – size n numpy array of Lipschitz constants

  • mus (list) – size n numpy array of strong convexity parameters where mu[i] < l[i]

  • operators (list) – list of proximal operators

  • alpha (float) – proximal scaling parameter

  • verbose (bool) – verbose output

Returns:

  • tau (float) – contraction factor using the optimal step size

  • gamma (float) – optimal step size

Optimal Consensus Matrix (W)

oars.pep.getOptimalW(Z, ls=None, mus=None, operators=None, Wref=None, W_fixed={}, alpha=1, scaling=1.0, verbose=False)[source]

Use the dual PEP to get the optimal W

Parameters:

  • Z (ndarray) – Z matrix n x n numpy array

  • ls (list, optional) – size n numpy array of Lipschitz constants

  • mus (list, optional) – size n numpy array of strong convexity parameters where mu[i] < l[i]

  • operators (list, optional) – list of proximal operators

  • Wref (ndarray, optional) – Base W if only gamma is desired

  • W_fixed (dict, optional) – Dict of fixed W values

  • alpha (float, optional) – proximal scaling parameter

  • verbose (bool, optional) – verbose output

Returns:

  • W (ndarray) – optimal consensus matrix

  • rho2 (float) – minimal contraction factor

Contraction Factor

oars.pep.getContractionFactor(Z, W, ls=None, mus=None, operators=None, alpha=1, gamma=0.5, scaling=1.0, verbose=False, **kwargs)[source]

Get the contraction factor for the resolvent splitting method \(v = v - \gamma W x\) for given Z and W matrices

Parameters:

  • Z (ndarray) – Z matrix n x n numpy array

  • W (ndarray) – W matrix n x n numpy array

  • ls (list) – size n numpy array of Lipschitz constants

  • mus (list) – size n numpy array of strong convexity parameters where mu[i] < l[i]

  • operators (list) – list of proximal operators

  • alpha (float) – proximal scaling parameter

  • gamma (float) – step size

  • verbose (bool) – verbose output

  • kwargs – additional arguments for cvxpy solver

Returns:

tau (float) – contraction factor

Reduced Contraction Factor

oars.pep.getReducedContractionFactor(Z, M, ls=None, mus=None, operators=None, alpha=1, gamma=0.5, scaling=1.0, verbose=False)[source]

Get contraction factor for resolvent splitting via PEP

Parameters:

  • Z (ndarray) – Z matrix n x n numpy array

  • M (ndarray) – M matrix d x n numpy array

  • ls (list) – size n numpy array of Lipschitz constants

  • mus (list) – size n numpy array of strong convexity parameters where mu[i] < l[i]

  • operators (list) – list of proximal operators

  • alpha (float) – proximal scaling parameter. Default is 1.

  • gamma (float) – step size. Default is 0.5.

  • verbose (bool) – verbose output. Default is False.

Returns:

tau (float) – contraction factor

Lipschitz Strongly Monotone Operator

class oars.pep.LipschitzStronglyMonotoneOperator(L, mu, name=None)[source]

Smooth Strongly Convex Function

class oars.pep.SmoothStronglyConvexSubdifferential(L, mu, name=None)[source]

Class for the smooth strongly convex subdifferential operator in the PEP formulation

Attributes:

  • L (float) – Lipschitz constant

  • mu (float) – strong convexity parameter

get_class_matrices(self)[source]
get_reduced_class_matrices(self)[source]

Constraint Matrices

oars.pep.getConstraintMatrices(Z, W=None, ls=None, mus=None, operators=None, alpha=1, gamma=1, verbose=False)[source]

Get the matrices for the PEP formulation on the resolvent splitting method given by equation (12) in the paper, i.e. where step 2 is given by \(v = v - \gamma W x\), for a given \(Z, W\) over a set of n l_i-Lipschitz, \(\mu_i\)-strongly monotone operators or the set of provided operators

Parameters:

  • Z (ndarray) – Z matrix n x n numpy array

  • W (ndarray) – W matrix n x n numpy array

  • ls (list) – size n numpy array of Lipschitz constants. Default is 2 if no operators are provided.

  • mus (list) – size n numpy array of strong convexity parameters where mu[i] < l[i]. Default is 1 if no operators are provided.

  • operators (list) – list of n operators. If None, LipschitzStronglyMonotoneOperator is used with provided ls and mus.

  • gamma (float) – step size (default is 1 for the dual PEP)

  • verbose (bool) – verbose output

Returns:

  • Ko (ndarray) – 2n x 2n matrix for the objective function

  • K1 (ndarray) – 2n x 2n matrix for the constraint that v sums to 0

  • Ki (ndarray) – 2n x 2n matrix for the equality constraint

  • Kp (list) – list of interpolation matrices

Reduced Constraint Matrices

oars.pep.getReducedConstraintMatrices(Z, M, ls=None, mus=None, operators=None, alpha=1, gamma=1, verbose=False)[source]

Get the matrices for the PEP formulation on the reduced resolvent splitting method given by equation (11) in the paper, i.e. where step 2 is given by \(z = z + \gamma M x\), for a given \(Z, M\) over a set of n l_i-Lipschitz, \(\mu_i\)-strongly convex operators or the set of provided operators

Parameters:

  • Z (ndarray) – Z matrix n x n numpy array

  • M (ndarray) – M matrix d x n numpy array

  • ls (list) – size n numpy array of Lipschitz constants. Default is 2 if no operators are provided.

  • mus (list) – size n numpy array of strong convexity parameters where mu[i] < l[i]. Default is 1 if no operators are provided.

  • operators (list) – list of n operators. If None, LipschitzStronglyMonotoneOperator is used with provided ls and mus

  • gamma (float) – step size (default is 1 for the dual PEP)

  • verbose (bool) – verbose output

Returns:

tuple – tuple of matrices (Ko, Ki, Kp)

Ko (ndarray): (d+n) x (d+n) matrix for the objective function Ki (ndarray): (d+n) x (d+n) matrix for the equality constraint Kp (list): list of interpolation matrices