# Contributing¶

We welcome all contributors to CVXPY. You don’t need to be an expert in convex optimization to help out. Here are simple ways to start contributing immediately:

Read the CVXPY source code and improve the documentation, or address TODOs

Fix typos or otherwise enhance the website documentation

Browse the issue tracker, and work on unassigned bugs or feature requests

Polish the example library

If you’d like to add a new example to our library, or implement a new feature, please get in touch with us first by opening a GitHub issue to make sure that your priorities align with ours.

The remainder of this page goes into more detail on how to contribute to CVXPY.

## General principles¶

### Development environment¶

Start by forking the CVXPY repository and installing CVXPY from source. You should configure git on your local machine before changing any code. Here’s one way CVXPY contributors might configure git:

Tell git about the existence of the official CVXPY repo:

git remote add upstream https://github.com/cvxgrp/cvxpy.git

Fetch a copy of the official master branch:

git fetch upstream masterCreate a local branch which will track the official master branch:

git branch --track official_master upstream/masterThe

onlycommand you should use on the`official_master`

branch is`git pull`

. The purpose of this tracking branch is to allow you to easily sync with the main CVXPY repository. Such an ability can be a huge help in resolving any merge conflicts encountered in a pull request. For simple contributions, you might never use this branch.

Switch back to your forked master branch:

git checkout masterResume work as usual!

### Contribution checklist¶

Contributions are made through pull requests. Before sending a pull request, make sure you do the following:

Add our license to new files

Check that your code adheres to our coding style.

Write unittests.

Run the unittests and check that they’re passing.

Run the benchmarks to make sure your change doesn’t introduce a regression

Once you’ve made your pull request, a member of the CVXPY development team will assign themselves to review it. You might have a few back-and-forths with your reviewer before it is accepted, which is completely normal. Your pull request will trigger continuous integration tests for many different Python versions and different platforms. If these tests start failing, please fix your code and send another commit, which will re-trigger the tests.

### License¶

Please add the following license to new files:

""" Copyright, the CVXPY authors Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. """

### Code style¶

We use flake8 to enforce our Python coding style. Before sending us a pull request, navigate to the project root and run

flake8 cvxpy/

to make sure that your changes abide by our style conventions. Please fix any errors that flake8 reports before sending the pull request.

### Writing unit tests¶

Most code changes will require new unit tests. (Even bug fixes require unit tests, since the presence of bugs usually indicates insufficient tests.) CVXPY tests live in the directory cvxpy/tests, which contains many files, each of which contains many unit tests. When adding tests, try to find a file in which your tests should belong; if you’re testing a new feature, you might want to create a new test file.

We use the standard Python unittest
framework for our tests. Tests are organized into classes, which inherit from
`BaseTest`

(see `cvxpy/tests/base_test.py`

). Every method beginning with `test_`

is a unit
test.

### Running unit tests¶

We use `pytest`

to run our unit tests, which you can install with `pip install pytest`

.
To run all unit tests, `cd`

into `cvxpy/tests`

and run the following command:

`pytest`

To run tests in a specific file (e.g., `test_dgp.py`

), use

pytest test_dgp.py

To run a specific test method (e.g., `TestDgp.test_product`

), use

pytest test_dgp.py::TestDgp::test_product

Please make sure that your change doesn’t cause any of the unit tests to fail.

`pytest`

suppresses stdout by default. To see stdout, pass the `-s`

flag
to `pytest`

.

### Benchmarks¶

CVXPY has a few benchmarks in `cvxpy/tests/test_benchmarks.py`

, which test
the time to canonicalize problems. Please run

pytest -s test_benchmarks.py

with and without your change, to make sure no performance regressions are introduced. If you are making a code contribution, please include the output of the above command (with and without your change) in your pull request.

## Solver interfaces¶

Third-party numerical optimization solvers are the lifeblood of CVXPY. We are very grateful to anyone who would be willing to volunteer their time to improve our existing solver interfaces, or create interfaces to new solvers. Improving an existing interface can usually be handled like fixing a bug. Creating a new interface requires much more work, and warrants coordination with CVXPY principal developers before writing any code.

This section of the contributing guide outlines considerations when adding new solver interfaces. For the time being, we only have documentation for conic solver interfaces. Additional documentation for QP solver interfaces is forthcoming.

Warning

This documentation is far from complete! It only tries to cover the absolutely essential parts of writing a solver interface. It also might not do that in a spectacular way – we welcome all feedback on this part of the documentation.

Warning

The developers try to keep this documentation up to date, however at any given time it might contain inaccurate information! It’s very important that you contact the CVXPY developers before writing a solver interface, if for no other reason than to prompt us to double-check the accuracy of this guide.

### Conic solvers¶

Conic solvers require that the objective is a linear function of the
optimization variable; constraints must be expressed using convex cones and
affine functions of the optimization variable.
The codepath for conic solvers begins with
reductions/solvers/conic_solvers
and in particular with the class `ConicSolver`

in
conic_solver.py.

Let’s say you’re writing a CVXPY interface for the “*Awesome*” conic solver,
and that there’s an existing package `AwesomePy`

for calling *Awesome* from python.
In this case you need to create a file called `awesome_conif.py`

in the same folder as `conic_solver.py`

.
Within `awesome_conif.py`

you will define a class `Awesome(ConicSolver)`

.
The `Awesome(ConicSolver)`

class will manage all interaction between CVXPY and the
existing `AwesomePy`

python package. It will need to implement six functions:

import_solver,

name,

accepts,

apply,

solve_via_data, and

invert.

The first three functions are very easy (often trivial) to write.
The remaining functions are called in order: `apply`

stages data for `solve_via_data`

,
`solve_via_data`

calls the *Awesome* solver by way of the existing third-party
`AwesomePy`

package, and `invert`

transforms the output from `AwesomePy`

into
the format that CVXPY expects.

Key goals in this process are that the output of `apply`

should be as close as possible
to the *Awesome*’s standard form, and that `solve_via_data`

should be kept short.
The complexity of `Awesome(ConicSolver).solve_via_data`

will depend on `AwesomePy`

.
If `AwesomePy`

allows very low level input– passed by one or two matrices,
and a handful of numeric vectors –then you’ll be in a situation like ECOS or GLPK.
If the `AwesomePy`

package requires that you build an object-oriented model,
then you’re looking at something closer to the MOSEK, GUROBI, or NAG interfaces.
Writing the `invert`

function may require nontrivial effort to properly recover dual variables.

### CVXPY’s conic form¶

CVXPY converts an optimization problem to an explicit form at the last possible moment. When CVXPY presents a problem in a concrete form, it’s over a single vectorized optimization variable, and a flattened representation of the feasible set. The abstraction for the standard form is

where \(K\) is a product of elementary convex cones. The design of CVXPY allows for any cone supported by a target solver, but the current elementary convex cones are

The zero cone \(y = 0 \in \mathbb{R}^m\).

The nonnegative cone \(y \geq 0 \in \mathbb{R}^m\).

The second order cone

\[(u,v) \in K_{\mathrm{soc}}^n \doteq \{ (t,x) \,:\, t \geq \|x\|_2 \} \subset \mathbb{R} \times \mathbb{R}^n.\]One of several vectorized versions of the positive semidefinite cone.

The exponential cone

\[(u,v,w) \in K_e \doteq \mathrm{cl}\{(x,y,z) | z \geq y \exp(x/y), y>0\}.\]

The 3-dimensional power cone, parameterized by a number \(\alpha\in (0, 1)\):

\[(u,v) \in K_{\mathrm{pow}}^{\alpha} \doteq \{ (x,y,z) \,:\, x^{\alpha}y^{1-\alpha} \geq |z|, (x,y) \geq 0 \}.\]

We address the vectorization options for the semidefinite cones later.
For now it’s useful to say that the `Awesome(ConicSolver)`

class will access an
explicit representation for problem \((P)\) in in `apply`

, with a code snippet like

```
# from cvxpy.constraints import Zero, NonNeg, SOC, PSD, ExpCone, PowCone3D
# ...
if not problem.formatted:
problem = self.format_constraints(problem, self.EXP_CONE_ORDER)
constr_map = problem.constr_map
cone_dims = problem.cone_dims
c, d, A, b = problem.apply_parameters()
```

The variable `constr_map`

is is a dict of lists of CVXPY Constraint objects.
The dict is keyed by the references to CVXPY’s Zero, NonNeg, SOC, PSD, ExpCone,
and PowCone3D classes. You will need to interact with these constraint classes during
dual variable recovery.
For the other variables in that code snippet …

`c, d`

define the objective function`c @ x + d`

, and

`A, b, cone_dims`

define the abstractions \(A\), \(b\), \(K\) in problem \((P)\).

The first step in writing a solver interface is to understand the exact
meanings of `A, b, cone_dims`

, so that you can correctly build a primal
problem using the third-party `AwesomePy`

interface to the *Awesome* solver.
The `cone_dims`

object is an instance of the ConeDims class, as defined in
cone_matrix_stuffing.py;
`A`

is a SciPy sparse matrix, and `b`

is a numpy ndarray with `b.ndim == 1`

.
The rows of `A`

and entries of `b`

are given in a very specific order, as described below.

Equality constraints are found in the first

`cone_dims.zero`

rows of`A`

and entries of`b`

. Letting`eq = cone_dims.zero`

, the constraint isA[:eq, :] @ x + b[:eq] == 0.Inequality constraints occur immediately after the equations. If for example

`ineq = cone_dims.nonneg`

then the feasible set has the constraintA[eq:eq + ineq, :] @ x + b[eq:eq + ineq] >= 0.Second order cone (SOC) constraints are handled after inequalities. Here,

`cone_dims.soc`

is alist of integersrather than a single integer. Supposing`cone_dims.soc[0] == 10`

, the first second order cone constraint appearing in this optimization problem would involve 10 rows of`A`

and 10 entries of`b`

. The SOC vectorization we use is given by \(K_{\mathrm{soc}}^n\) as defined above.PSD constraints follow SOC constraints. For most solver interfaces it is a good idea to make a deliberate decision about how to handle the vectorization, which amounts to implementing

`Awesome(ConicSolver).psd_format_mat`

. If you do nothing, then the vectorization will behave as in`ConicSolver.psd_format_mat`

, which takes a PSD constraint of order \(n\) and maps it to \(n^2\) rows of \(A\) and entries of \(b\). You can also borrow from`SCS.psd_format_mat`

which maps an order \(n\) PSD constraint to \(n(n+1)/2\) suitably scaled rows of \(A\) and entries of \(b\), or`MOSEK.psd_format_mat`

which behaves identically to SCS except for the scaling.The next block of

`3 * cone_dims.exp`

rows in`A, b`

correspond to consecutive three-dimensional exponential cones, as defined by \(K_e\) above.The final block of

`3 * len(cone_dims.p3d)`

rows in`A, b`

correspond to three-dimensional power cones defined by \(K_{\mathrm{pow}}^{\alpha}\), where the i-th triple of rows has`alpha = cone_dims.p3d[i]`

.

If *Awesome* supports nonlinear constraints like SOC, ExpCone, PSD, or PowCone3D, then
it’s possible that you will need to transform data `A, b`

in order to write these constraints in
the form expected by `AwesomePy`

.
The most common situations are when `AwesomePy`

parametrizes the second-order cone
as \(K = \{ (x,t) \,:\, \|x\|\leq t \} \subset \mathbb{R}^n \times \mathbb{R}\),
or when it parametrizes \(K_e \subset \mathbb{R}^3\) as some permutation of
what we defined earlier.

### An alternative conic form¶

Some conic solvers do not natively support problem formats like (P) described in the previous section. Instead, the solver requires problem statements like

Problem (Dir) uses so-called “direct” conic constraints \(z \in K\). If you are
writing an interface for a solver which works this way, you should use the
`Dualize`

reduction on the standard CVXPY problem data given in (P).
Using the Dualize reduction will avoid introduction unnecessary slack variables
for continuous problems, but it is not applicable for problems with integer constraints.
Therefore if your solver supports integer constraints, make sure to also use the
`Slacks`

reduction for that code path.

The MOSEK interface uses both of the reductions mentioned above.

### Dual variables¶

Dual variable extraction should be handled in `Awesome(ConicSolver).invert`

.
To perform this step correctly, it’s necessary to consider how CVXPY forms
a Lagrangian for the primal problem \((P)\).
Let’s say that the affine map \(Ax + b\) in the feasible set
\(Ax + b \in K \subset \mathbb{R}^m\) is broken up into six blocks of sizes
\(m_1,\ldots,m_6\) where the blocks correspond (in order) to zero-cone, nonnegative cone,
second-order cone, vectorized PSD cone, exponential cone, and 3D power cone constraints.
Then CVXPY defines the dual to \((P)\) by forming a Lagrangian

in dual variables \(\mu_1 \in \mathbb{R}^{m_1}\), \(\mu_2 \in \mathbb{R}^{m_2}_+\), and \(\mu_i \in K_i^* \subset \mathbb{R}^{m_i}\) for \(i \in \{3,4,5,6\}\). Here, \(K_i^*\) denotes the dual cone to \(K_i\) under the standard inner product.

More remarks on dual variables (particularly SOC dual variables) can be found in this comment on a GitHub thread.

Most concrete implementations of the ConicSolver class use a common set of helper functions for dual variable recovery, found in reductions/solvers/utilities.py.

### Registering a solver¶

Correctly implementing `Awesome(ConicSolver)`

isn’t enough to call *Awesome* from CVXPY.
You need to make edits in a handful of other places, namely

The existing content of those files should make it clear what’s needed
to add *Awesome* to CVXPY.

### Writing tests¶

Tests for `Awesome(ConicSolver)`

should be placed in cvxpy/tests/test_conic_solvers.py.
The overwhelming majority of tests in that file only take a single line, because
we make consistent use of a general testing framework defined in
solver_test_helpers.py.
Here are examples of helper functions we invoke in `test_conic_solvers.py`

,

```
class StandardTestSDPs(object):
@staticmethod
def test_sdp_1min(solver, places=4, **kwargs):
sth = sdp_1('min')
sth.solve(solver, **kwargs)
sth.verify_objective(places=2) # only 2 digits recorded.
sth.check_primal_feasibility(places)
sth.check_complementarity(places)
sth.check_dual_domains(places) # check dual variables are PSD.
...
class StandardTestSOCPs(object):
@staticmethod
def test_socp_0(solver, places=4, **kwargs):
sth = socp_0()
sth.solve(solver, **kwargs)
sth.verify_objective(places)
sth.verify_primal_values(places)
sth.check_complementarity(places)
...
@staticmethod
def test_mi_socp_1(solver, places=4, **kwargs):
sth = mi_socp_1()
sth.solve(solver, **kwargs)
# mixed integer problems don't have dual variables,
# so we only check the optimal objective and primal variables.
sth.verify_objective(places)
sth.verify_primal_values(places)
```

Notice the comments in the predefined functions.
In `test_sdp_1min`

, we override a user-supplied value for `places`

with
`places=2`

when checking the optimal objective function value.
We also go through extra effort to check that the dual variables are PSD
matrices.
In `test_mi_socp_1`

we’re working with a mixed-integer problem, so
there are no dual variables at all.
You should use these predefined functions partly because they automatically check
what’s most appropriate for the problem at hand.

Each of these predefined functions first constructs a SolverTestHelper object `sth`

which contains appropriate test data. The `.solve`

function for the
SolverTestHelper class is a simple wrapper around `prob.solve`

where
`prob`

is a CVXPY Problem. In particular, any keyword arguments
passed to `sth.solve`

will be passed to `prob.solve`

. This allows you to
call modified versions of a test with different solver parameters, for example

```
def test_mosek_lp_1(self):
# default settings
StandardTestLPs.test_lp_1(solver='MOSEK') # 4 places
# require a basic feasible solution
StandardTestLPs.test_lp_1(solver='MOSEK', places=6, bfs=True)
```

## Development roadmap¶

This roadmap highlights the development goals for the next minor and major release of CVXPY. New contributors are encouraged to focus on the development goals marked [Small]. If you are interested in working on a [Large] development goal, please contact a project maintainer.

### CVXPY 1.2¶

Move CI from Travis-CI to Github actions. [Large]

Add CI for Gurobi, CPLEX, GLPK, Cbc, and SCIP. [Small]

Post-solver feasibility checks. [Small]

State required cone types for atoms. [Small]

### CVXPY 2.0¶

Pretty print method for summarizing a solution and its dual variables. [Large]

Code generation for quadratic programs and cone programs. [Large]

Support for n-dimensional expressions, variables, parameters, etc. [Large]

10x improvement in the speed and memory usage of cvxcore, especially for DPP problems. [Large]

Sophisticated affine transformations: [457, 563, 808]. [Small]

Full compatibility with NumPy broadcasting rules. [Large]