C++

Interface

The C++ interface is located in the 

1
<pogs>/src/pogs.h
file. To use the solver your code must include this file. The solver consists of a single function 
1
Pogs
, with signature

1
2
template <typename T, typename M>
void Pogs(PogsData<T, M> *pogs_data);

The type 

1
T
represents the data type (either 
1
float
or 
1
double
), and 
1
M
is the matrix type (currently 
1
float*
and 
1
double*
are supported, but further types will be added for sparse matrices). 
1
PogsData
is a struct with fields

Inputs

  • 1
    std::vector<FunctionObj<T> > f, g
    correspond to the functions \( f \) and \( g \) in the objective. The dimension of 
    1
    f
    must be \( m \) and the dimension of 
    1
    g
    must be \( n \). See section below for an explanation of the 
    1
    FunctionObj<T>
    struct.
  • 1
    const M A
    corresponds to the data matrix \( A \). If \( A \) is a dense matrix, then 
    1
    M A
    is a pointer to a row major matrix of dimension \( m n \).
  • 1
    size_t m, n
    are the dimensions of \( y \), resp. \( x \).

Outputs

  • 1
    T *x, *y
    point to where the primal optimal variables \( x^\star_\text{pogs} \) and \( y^\star_\text{pogs} \) should be saved. The memory must be pre-allocated and have dimension \( m \) (resp. \( n \)). If either 
    1
    x=NULL
    or 
    1
    y=NULL
    , then the respective variable will be discarded upon exit. Note, \( y^\star_\text{pogs} = A x^\star_\text{pogs} \) is only satisfied to a given tolerance (see Usage).
  • 1
    T *l
    points to where the dual optimal variable \( \lambda^\star_\text{pogs} \) should be stored. The memory must be pre-allocated and have dimension \( m \). If 
    1
    l=NULL
    , then the dual variable will be discarded upon exit.
  • 1
    T optval
    is the primal optimum \( p^\star_\text{pogs} = f(y^\star_\text{pogs}) + g(x^\star_\text{pogs}) \). Note, since \( y^\star_\text{pogs} = A x^\star_\text{pogs} \) is only satisfied to a specified tolerance, 
    1
    optval
    may be a slightly lower than \( p^\star \) (the actual optimum).

Parameters (for a detailed description see Usage and ADMM)

  • 1
    T rho
    is the penalty term.
  • 1
    T rel_tol, abs_tol
    are the absolute and relative stopping tolerances.
  • 1
    unsigned int max_iter
    is the maximum number of iterations before the solver terminates.
  • 1
    bool quiet
    determines whether the solver should display progress information.
  • 1
    bool adaptive_rho
    determines whether \( \rho \) should be chosen adaptively.

Factors (allocate space for these variables to use factorization caching – see Usage)

  • 1
    M factors
    used for factorization caching. Allocate space using 
    1
    AllocDenseFactors
    and free space using 
    1
    FreeDenseFactors
    .

FunctionObj

The 

1
FunctionObj
struct is a parameterization of the generic function \[ c \, h(a \, x - b) + d \, x + e \, x ^ 2, \]

and is defined as

1
2
3
4
5
6
7
8
9
template <typename T>
struct FunctionObj {
  // Parameters
  Function h;
  T a, b, c, d, e;

  // Constructor with defaults
  FunctionObj(Function h) : h(h), a(1), b(0), c(1), d(0), e(0) { }
};

where 

1
Function
is an enum, taking on the values

1
2
kAbs,      kExp,     kHuber,   kIdentity, kIndBox01, kIndEq0,  kIndGe0,  kIndLe0,
kLogistic, kMaxNeg0, kMaxPos0, kNegEntr,  kNegLog,   kRecipr,  kSquare,  kZero.

Definitions of both 

1
FunctionObj
and 
1
Function
are located in 
1
<pogs>/src/prox_lib.h
.

The 

1
FunctionObj
is necessary when specifying the objective terms \( f_i(y_i) \) and \( g_j(x_j) \). For example, to specify that \(g_j(x_j) = |x_j|\) for \(j = 1\ldots 4\) and \(g_5(x_5) = I(x_5 = 0)\), use the syntax

1
2
3
4
pogs_data.g.reserve(5);
for (unsigned int i = 0; i < 4; ++i)
  pogs_data.g.push_back(FunctionObj(kAbs));
pogs_data.g.push_back(FunctionObj(kIndGe0));

Linking to CPU implementation

Open Terminal and navigate to the directory 

1
<pogs>/src
, then execute the command

1
make pogs.o

This creates an object file 

1
pogs.o
, to which your code must be linked. An example can be found in 
1
<pogs>/examples/cpp/Makefile
. Look for the section marked 
1
#CPU
. When compiling your code it is important to also link to a BLAS library. On an Apple computer this can be done using the flag 
1
-framework Accelerate
.

Linking to GPU implementation

Open terminal and navigate to the directory 

1
<pogs>/src
, then execute the command

1
make pogs_cu_link.o

This creates two object files – 

1
pogs_cu.o
and 
1
pogs_cu_link.o
– to which your code must be linked. An example can be found in 
1
<pogs>/examples/cpp/Makefile
. Look for the section marked 
1
#GPU
. You will need to link the the CUDA runtime and CuBLAS libraries. To do so, use the 
1
-lcudart -lcublas
flags.