CPG Code Documentation

Auto-generated by CVXPYgen $DATE.

# Generated Code for Solving Your CVXPY Problem

### Problem Summary

Your optimization problem has the following parameters, primal and dual variables. Dual variable `di` corresponds to the i-th constraint in your problem formulation. The dimensions after flattening (and considering sparsity) are given in parentheses.

Parameter | Dimension
--- | ---
$PARAMS

Primal Variable | Dimension
--- | ---
$PRIMALS

Dual Variable | Dimension
--- | ---
$DUALS

### File Tree

Your generated code is structured as follows inside your chosen `$CODEDIR` directory:

    $CODEDIR
        c
          solver_code
            ...
          include
            cpg_workspace.h
            cpg_solve.h
          src
            cpg_workspace.c
            cpg_solve.c
            cpg_example.c
          build
          CMakeLists.txt
        cpp
          include
            cpg_module.hpp
          src
            cpg_module.cpp
        setup.py
        cpg_solver.py
        problem.pickle
        LICENSE
        README.html

The `c/solver_code` subdirectory contains all code from the chosen numerical solver ($CPGSOLVERNAME). For documentation on this part, please have a look here.

To make this solver usable, your problem needs to be converted to the standard form accepted by $CPGSOLVERNAME. This is done by all the other source files inside the `$CODEDIR` directory.

### File Contents

`c/include/cpg_workspace.h` contains type definitions and variable declarations. The following types are part of the C interface:

      $CPGPRIMTYPEDEF
      $CPGDUALTYPEDEF
      $CPGINFOTYPEDEF
      $CPGRESULTTYPEDEF

`c/include/cpg_solve.h` contains function prototypes. Relevant for the C interface are:

      $CPGUPDATEDECLARATIONS
      $CPGSOLVEDECLARATIONS
      $CPGSETTINGSDECLARATIONS

  where `<setting_name>` and `<setting_type>` are the name and type of the solver setting to be updated, respectively.
`c/src/cpg_workspace.c` contains the static allocation of the C variables declared in `include/cpg_workspace.h`.
`c/src/cpg_solve.c` contains the definition of functions declared in `include/cpg_solve.h`.
`c/src/cpg_example.c` contains example code that initializes the problem data and solves a problem instance.
`c/CMakeLists.txt` contains instructions for build file generation inside the `c/build` directory with CMake.
`cpp/` contains binding code for the python wrapper generated with pybind11 and `setup.py`.
`cpg_solver.py` contains a custom CVXPY solve method that uses the python wrapper to solve your problem.
Finally, `problem.pickle` is the serialized version of your CVXPY problem object.

### Using Generated Code

#### CVXPY

To use the CVXPY interface, run exemplarily,

    import pickle
    from $CDPYTHON.cpg_solver import cpg_solve

    with open('$CODEDIR/problem.pickle', 'rb') as f:
        prob = pickle.load(f)

    prob.param_dict['<p_name>'].value = <p_value>
    prob.register_solve('CPG', cpg_solve)

    obj = prob.solve(method='CPG')
    print(prob.var_dict['<v_name>'].value)

where `<p_name>` and `<p_value>` are parameter name and value, respectively. After registering `<cpg_solve>` as custom solve method, the problem can be solved and the objective value `obj` and solution in terms of variable `<v_name>` can be inspected.

#### Example Executable

Before compiling the example executable, remember to activate the `cpg_env` environment.

    conda activate cpg_env

On Unix platforms, run the following commands in your terminal to compile and run the program:

    cd $CODEDIR/c/build
    cmake ..
    cmake --build . --target cpg_example
    ./cpg_example

On Windows, type:

    cd $CODEDIR\c\build
    cmake ..
    cmake --build . --target cpg_example --config release
    Release\cpg_example

#### Existing C/C++ Project

To use the generated code in an existing `CMake` project, copy the following to a subdirectory `<subdir>` of your project:

    $CODEDIR/c/CMakeLists.txt
    $CODEDIR/c/src/
    $CODEDIR/c/include/
    $CODEDIR/c/solver_code/

In your top-level `CMakeLists.txt`, add the subdirectory via

    add_subdirectory(<subdir>)
    include_directories(<existing_dirs> ${$CPGCMAKELISTS_include})

where `<existing_dirs>` is your existing include directories and `${$CPGCMAKELISTS_include}` lists the include directories used by the generated code. Add `${$CPGCMAKELISTS_head}` and `${$CPGCMAKELISTS_src}` to all targets that use the generated code. If not needed, you can remove the `cpg_example` and `cpg` targets from `$CODEDIR/c/CMakeLists.txt`.