Migration Guide: v0.3 to v0.4

This guide helps you migrate your POGS code from version 0.3 to version 0.4.

---

Overview

POGS v0.4 represents a major modernization with several breaking changes:

• Build System: Makefiles → CMake
• C++ Standard: C++11 → C++20
• MATLAB Interface: Removed (use Python/CVXPY instead)
• Type System: Raw enums → Enum classes (foundation laid)
• Documentation: Jekyll → MkDocs Material

Breaking Changes

Version 0.4 introduces breaking changes. Please review this guide carefully before upgrading.

---

Build System Migration

Old (v0.3): Makefiles

# Build CPU version
cd src
make cpu

# Build GPU version
make gpu

# Build examples
cd ../examples/cpp
make

New (v0.4): CMake

# Configure (CPU-only)
cmake -B build -DCMAKE_BUILD_TYPE=Release -DPOGS_BUILD_GPU=OFF

# Build everything
cmake --build build

# Build specific targets
cmake --build build --target pogs_cpu
cmake --build build --target pogs_tests

# Install
sudo cmake --install build

Integration into Your Project

Old (v0.3):

# Manual include paths and library linking
CXXFLAGS = -I/path/to/pogs/src/include
LDFLAGS = -L/path/to/pogs/src/build -lpogs_cpu

New (v0.4):

# CMake find_package
find_package(POGS REQUIRED)

add_executable(myapp main.cpp)
target_link_libraries(myapp PRIVATE pogs::cpu)

---

Compiler Requirements

Old (v0.3)

• C++11 compatible compiler
• GCC 4.8+, Clang 3.3+

New (v0.4)

• C++20 compatible compiler
• GCC 10+, Clang 13+, MSVC 19.29+, AppleClang 13+

Check your compiler:

g++ --version    # Need GCC 10+
clang++ --version # Need Clang 13+

Update if needed:

# Ubuntu/Debian
sudo apt-get install g++-11

# macOS
brew install gcc@11

# Specify compiler
cmake -B build -DCMAKE_CXX_COMPILER=g++-11

---

MATLAB Interface Removal

Old (v0.3): MATLAB Interface

% MATLAB code (NO LONGER SUPPORTED)
A = randn(100, 50);
b = randn(100, 1);
lambda = 0.1;

x = pogs_lasso(A, b, lambda);

New (v0.4): Python/CVXPY

import cvxpy as cp
import numpy as np

A = np.random.randn(100, 50)
b = np.random.randn(100)
lambda_val = 0.1

x = cp.Variable(50)
objective = cp.Minimize(
    0.5 * cp.sum_squares(A @ x - b) + lambda_val * cp.norm(x, 1)
)
prob = cp.Problem(objective)
prob.solve(solver='POGS', verbose=True)

print(f"Solution: {x.value}")

Why Python/CVXPY? - More active development - Better ecosystem (NumPy, SciPy, Pandas) - Easier installation (pip install cvxpy) - More expressive modeling language

---

C++ API (Current - Legacy)

The C++ API remains largely unchanged in v0.4. Full modernization will come in future releases.

Graph Form (Unchanged)

#include "pogs.h"
#include "matrix/matrix_dense.h"

// Problem data
pogs::MatrixDense<double> A('r', m, n, A_data);

std::vector<FunctionObj<double>> f(m);
std::vector<FunctionObj<double>> g(n);

// Define f and g...
for (size_t i = 0; i < m; ++i) {
    f[i].h = kSquare;
    f[i].c = 0.5;
}

for (size_t j = 0; j < n; ++j) {
    g[j].h = kAbs;
    g[j].c = lambda;
}

// Solve
pogs::PogsDirect<double, pogs::MatrixDense<double>> solver(A);
solver.SetAbsTol(1e-4);
solver.SetRelTol(1e-3);
solver.SetMaxIter(1000);
solver.Solve(f, g);

double optval = solver.GetOptval();
const double* x = solver.GetX();

Status: This API still works in v0.4 and will continue to be supported.

Cone Form (Unchanged)

#include "pogs.h"

// Cone form: min c'x s.t. Ax = b, x in K
std::vector<ConeConstraint> Kx = {{kConeNonNeg, {0, 1, 2}}};
std::vector<ConeConstraint> Ky = {{kConeZero, {0, 1}}};

pogs::PogsDirectCone<double, pogs::MatrixDense<double>> solver(A, Kx, Ky);
solver.Solve(b, c);

Status: This API still works in v0.4.

---

Future Modern API (Preview)

Not Yet Available

The following modern API is planned for a future release. This is shown for reference only.

Future: Modern C++20 API

#include <pogs/pogs.hpp>
#include <pogs/types.hpp>
#include <pogs/config.hpp>

// Modern type system
auto config = pogs::SolverConfig{
    .rho = 1.0,
    .abs_tol = 1e-4,
    .rel_tol = 1e-3,
    .max_iter = 1000,
    .verbose = true
};

// Smart pointers
auto A = std::make_unique<pogs::MatrixDense<double>>(m, n);
auto solver = pogs::make_solver<double>(std::move(A));
solver.configure(config);

// Modern function objects
std::vector<pogs::FunctionObj<double>> f(m);
for (auto& fi : f) {
    fi.type = pogs::FunctionType::Square;  // Enum class
    fi.c = 0.5;
}

auto result = solver.solve(f, g);

if (result.status == pogs::Status::Success) {
    std::cout << "Optimal: " << result.primal_obj.value() << "\n";
}

---

Common Migration Scenarios

Scenario 1: Simple Lasso Regression

Old (v0.3 - MATLAB):

A = randn(100, 50);
b = randn(100, 1);
x = pogs_lasso(A, b, 0.1);

New (v0.4 - Python):

import cvxpy as cp
import numpy as np

A = np.random.randn(100, 50)
b = np.random.randn(100)

x = cp.Variable(50)
objective = cp.Minimize(
    0.5 * cp.sum_squares(A @ x - b) + 0.1 * cp.norm(x, 1)
)
prob = cp.Problem(objective)
prob.solve(solver='POGS')

print(f"Solution: {x.value}")

New (v0.4 - C++, if needed):

// C++ API unchanged from v0.3
#include "pogs.h"

pogs::MatrixDense<double> A('r', m, n, A_data);
pogs::PogsDirect<double, pogs::MatrixDense<double>> solver(A);

std::vector<FunctionObj<double>> f(m), g(n);
// ... configure f and g as before ...

solver.Solve(f, g);

Scenario 2: Custom Problem in C++

Old (v0.3):

// Build with Makefile
// Uses C++11

#include "pogs.h"

pogs::MatrixDense<double> A('r', m, n, data);
pogs::PogsDirect<double, pogs::MatrixDense<double>> solver(A);
solver.Solve(f, g);

New (v0.4):

// Build with CMake
// Uses C++20 (but legacy API still works)

#include "pogs.h"  // Same header

pogs::MatrixDense<double> A('r', m, n, data);
pogs::PogsDirect<double, pogs::MatrixDense<double>> solver(A);
solver.Solve(f, g);  // Same API

CMakeLists.txt:

cmake_minimum_required(VERSION 3.20)
project(MyProject CXX)

set(CMAKE_CXX_STANDARD 20)

find_package(POGS REQUIRED)

add_executable(myapp main.cpp)
target_link_libraries(myapp PRIVATE pogs::cpu)

Scenario 3: Logistic Regression

Old (v0.3 - MATLAB):

X = randn(200, 50);
y = sign(randn(200, 1));
w = pogs_logistic(X, y, 0.1);

New (v0.4 - Python):

import cvxpy as cp
import numpy as np

X = np.random.randn(200, 50)
y = np.sign(np.random.randn(200))

w = cp.Variable(50)
b = cp.Variable()

losses = cp.sum(cp.logistic(-cp.multiply(y, X @ w + b)))
regularization = 0.1 * cp.sum_squares(w)
objective = cp.Minimize(losses + regularization)

prob = cp.Problem(objective)
prob.solve(solver='POGS')

print(f"Weights: {w.value}")
print(f"Intercept: {b.value}")

---

Installation Changes

Old (v0.3)

git clone https://github.com/foges/pogs.git
cd pogs/src
make cpu
# Library at: src/build/pogs.a

New (v0.4)

git clone https://github.com/foges/pogs.git
cd pogs

# Configure
cmake -B build -DCMAKE_BUILD_TYPE=Release

# Build
cmake --build build

# Install (optional)
sudo cmake --install build
# Installs to: /usr/local/lib/libpogs_cpu.a
#              /usr/local/include/pogs/

Custom Installation Location

# Install to $HOME/local
cmake -B build -DCMAKE_INSTALL_PREFIX=$HOME/local
cmake --build build
cmake --install build

# Set environment
export CMAKE_PREFIX_PATH=$HOME/local:$CMAKE_PREFIX_PATH
export LD_LIBRARY_PATH=$HOME/local/lib:$LD_LIBRARY_PATH

---

Documentation Changes

Old (v0.3)

• Jekyll-based GitHub Pages
• Outdated content from 2014
• Limited navigation
• No search

New (v0.4)

• MkDocs Material
• Modern, comprehensive documentation
• Full-text search
• Mobile-friendly
• Dark mode support

Access: - Online: https://foges.github.io/pogs/ - Local: mkdocs serve (requires pip install mkdocs-material)

---

Platform-Specific Notes

macOS

Old (v0.3):

make cpu  # Uses Accelerate

New (v0.4):

# CMake automatically finds Accelerate
cmake -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build

Linux

Old (v0.3):

# Manually specify BLAS/LAPACK in Makefile
make cpu BLAS_LIBS=-lopenblas

New (v0.4):

# Install dependencies
sudo apt-get install libopenblas-dev liblapack-dev

# CMake finds them automatically
cmake -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build

Windows

Old (v0.3): - Limited support - Manual configuration

New (v0.4):

# Visual Studio
cmake -B build -G "Visual Studio 17 2022" -A x64
cmake --build build --config Release
cmake --install build

---

Troubleshooting

"No such file: pogs.h"

Problem: Old include path

Solution:

// Old (v0.3)
#include "pogs.h"

// New (v0.4) - Same!
#include "pogs.h"  // Works if installed correctly

// Or use full path
#include "pogs/pogs.h"  // Future modern API

"Undefined reference to POGS functions"

Problem: Not linking against library

Solution:

# CMakeLists.txt
find_package(POGS REQUIRED)
target_link_libraries(myapp PRIVATE pogs::cpu)

"MATLAB interface not found"

Problem: MATLAB interface removed

Solution: Migrate to Python/CVXPY (see examples above)

"Compiler doesn't support C++20"

Problem: Old compiler

Solution:

# Check version
g++ --version

# Update compiler
sudo apt-get install g++-11  # Linux
brew install gcc@11          # macOS

# Specify compiler
cmake -B build -DCMAKE_CXX_COMPILER=g++-11

"CMake can't find POGS"

Problem: POGS not installed or not in CMake search path

Solution:

# Option 1: Install POGS
sudo cmake --install build

# Option 2: Set CMAKE_PREFIX_PATH
cmake -B build -DCMAKE_PREFIX_PATH=/path/to/pogs/install

# Option 3: Use environment variable
export CMAKE_PREFIX_PATH=/path/to/pogs/install

---

Performance Notes

No Performance Regression

Version 0.4 uses the same core ADMM algorithm as v0.3. Performance should be identical for the same problems.

Compiler Optimizations

C++20 compilers may provide better optimizations:

# Enable LTO (Link Time Optimization)
cmake -B build \
    -DCMAKE_BUILD_TYPE=Release \
    -DCMAKE_INTERPROCEDURAL_OPTIMIZATION=ON

---

Deprecation Timeline

Feature	v0.3	v0.4	Future
MATLAB Interface	✅ Supported	❌ Removed	❌ Not returning
R Interface	✅ Supported	❌ Removed	❌ Not returning
Makefile Build	✅ Primary	❌ Removed	❌ Not returning
CMake Build	❌ Not available	✅ Primary	✅ Continued
C++11 API	✅ Primary	✅ Compatible	🟡 Legacy
C++20 API	❌ Not available	🟡 Foundation	✅ Primary
Python/CVXPY	🟡 Experimental	✅ Supported	✅ Primary

---

Getting Help

• Documentation: https://foges.github.io/pogs/
• Examples: https://foges.github.io/pogs/examples/
• Issues: https://github.com/foges/pogs/issues
• Discussions: GitHub Discussions (coming soon)

---

Summary Checklist

Migration checklist for v0.3 → v0.4:

• Update build system from Makefile to CMake
• Ensure compiler supports C++20 (GCC 10+, Clang 13+)
• Migrate MATLAB code to Python/CVXPY
• Update include paths if needed
• Update link flags to use find_package(POGS)
• Test your code with v0.4
• Review new documentation
• Update CI/CD pipelines if applicable

---

Next Steps

After migration:

1. Explore new documentation: Modern guides and examples
2. Try Python/CVXPY: Easier problem formulation
3. Contribute: Help improve POGS
4. Stay updated: Watch for v0.5 with full modern API

---

Questions?

If you encounter issues during migration:

1. Check this guide
2. Review examples
3. Search existing issues
4. Open a new issue with:
5. Version: v0.3 → v0.4
6. Platform: OS and compiler
7. Error message
8. Minimal reproducible example